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 Resumable Frame Dispatch and Attach Into the Chat Core (#17129)

Marco Beretta07a72afbc2a4
diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.ts
index 8d9855edcf..383860af88 100644
--- a/client/src/hooks/SSE/useResumableSSE.ts
+++ b/client/src/hooks/SSE/useResumableSSE.ts
@@ -13,40 +13,27 @@ import {
import {
Constants,
QueryKeys,
- StepEvents,
- SteerEvents,
dataService,
- ActivityLabelEvents,
- ReasoningLabelEvents,
- UsageEvents,
createPayload,
- ApprovalEvents,
removeNullishValues,
} from 'librechat-data-provider';
import {
- getStepEventId,
toStartGenerationError,
- isOAuthStepEvent,
waitForRetryDelay,
getRecoverySteerId,
getRetryAfterDelay,
- mergeResumeMessages,
- preferDefinedString,
isServerNotReadyError,
getOptimisticMessages,
isResumedStartResponse,
isSettledStartResponse,
isRetryableNetworkError,
isReplacedStartResponse,
- getResumeMessageIndexes,
isInitialNewConversation,
getStreamStartFailureText,
keepLocalCodeApprovalMode,
hydrateSubmissionMessages,
- buildResumeEventSubmission,
getStartGenerationStreamId,
buildOptimisticConversation,
- buildCreatedInitialResponse,
getGenerationProtocolVersion,
GENERATION_PROTOCOL_VERSION,
getStartGenerationCreatedAt,
@@ -58,39 +45,23 @@ import {
START_GENERATION_READINESS_TIMEOUT_MS,
ResumableRun,
documentVisibility,
- ResumableSubscription,
- authorizeTerminalTeardown,
- reconcileGenerationLifecycle,
- handleTransportFailure,
- ResponsePatcher,
- clearPendingApprovalForTerminal,
- clearAttachedGenerationCreatedAt,
+ attachResumableStream,
+} from '@librechat/chat';
+import type {
+ ResumableHost,
+ ResumableCache,
+ SubscriptionTarget,
+ StartGenerationResult,
+ GenerationProtocolVersion,
} from '@librechat/chat';
import type {
- Agents,
TMessage,
- ChatEvent,
TPayload,
TSubmission,
TConversation,
TPendingSteer,
EventSubmission,
- TSteerAppliedEvent,
- TSteerUpdatedEvent,
- TActivityLabelEvent,
- TReasoningLabelEvent,
- TAttachment,
- TTokenUsageEvent,
- TContextUsageEvent,
} from 'librechat-data-provider';
-import type {
- ResumableHost,
- ResumableCache,
- TerminalContext,
- SubscriptionTarget,
- StartGenerationResult,
- GenerationProtocolVersion,
-} from '@librechat/chat';
import type { QueuedMessageOrigin, DrainAfterAbort, RunEnd } from '~/hooks/Chat/queue';
import type { ActiveJobsResponse, StreamStatusResponse } from '~/data-provider';
import type { EventHandlerParams } from './useEventHandlers';
@@ -150,9 +121,6 @@ import useLocalize from '~/hooks/useLocalize';
import useSteerState from './steer';
import store from '~/store';
-/** The step handler predates the wire types and accepts a narrower payload. */
-type StepEvent = Parameters<ReturnType<typeof useEventHandlers>['stepHandler']>[0];
-
type ChatHelpers = Pick<
EventHandlerParams,
'setMessages' | 'getMessages' | 'setConversation' | 'setIsSubmitting' | 'newConversation'
@@ -469,10 +437,6 @@ export default function useResumableSSE(
*/
const subscribeToStream = useCallback(
(target: SubscriptionTarget) => {
- /** See `ResumableSubscription.isCurrent` for the fences every callback below checks. */
- if (target.signal?.aborted || run.submission !== target.submission) {
- return;
- }
const host: ResumableHost = {
logger,
visibility: documentVisibility,
@@ -490,6 +454,9 @@ export default function useResumableSSE(
clearComposerDrafts: (conversationId, options) =>
clearComposerDrafts(runIndex, conversationId, options),
publishRunEnd: setRunEnd,
+ setAbortScroll,
+ renewActiveRun: () => setActiveRunId(v4()),
+ runEndTarget: resolveRunEndTarget,
clearDrainAfterAbort,
refreshBalance: () => {
(startupConfig?.balance?.enabled ?? false) && balanceQuery.refetch();
@@ -511,6 +478,7 @@ export default function useResumableSSE(
},
steers: {
resolve: resolveSteerChip,
+ update: updateSteerChips,
markLiveApplied: (steerId) =>
setLiveAppliedSteerIds((prev) => appendAppliedSteerIds(prev, [steerId])),
seed: seedSteerChips,
@@ -521,6 +489,15 @@ export default function useResumableSSE(
},
events: {
stepHandler,
+ finalHandler: (data, finalSubmission) =>
+ finalHandler(data as TFinalResData, finalSubmission),
+ createdHandler,
+ attachmentHandler,
+ titleHandler,
+ contentHandler,
+ messageHandler,
+ prunePtcTraces,
+ resetContentHandler,
syncStepMessage,
clearStepMaps,
flushPendingDeltas,
@@ -532,6 +509,29 @@ export default function useResumableSSE(
}),
},
messages: { get: getMessages, set: setMessages },
+ usage: {
+ bindResponse,
+ contextHandler,
+ usageHandler,
+ tapStream,
+ tapContent,
+ finalizeUsage,
+ backfillUsage,
+ seedLiveFromContent: (content, usageSubmission) =>
+ seedLive(countTrailingOutputChars(content), usageSubmission),
+ },
+ stream: transport.stream({ token }),
+ exposeDebugControls: import.meta.env.DEV
+ ? ({ killNetwork, closeClean }) => {
+ // Debug hooks for testing reconnection vs clean close behavior (dev only)
+ const debugWindow = window as Window & {
+ __killNetwork?: () => void;
+ __closeClean?: () => void;
+ };
+ debugWindow.__killNetwork = killNetwork;
+ debugWindow.__closeClean = closeClean;
+ }
+ : undefined,
parts: {
applySteer: applySteerPart,
findSteerTarget: findSteerMessageIndex,
@@ -542,771 +542,7 @@ export default function useResumableSSE(
findReasoningLabelTarget: findReasoningLabelMessageIndex,
},
};
- const sub = new ResumableSubscription(run, host, target);
- const {
- streamId: currentStreamId,
- isResume,
- generationCreatedAt,
- generationProtocolVersion,
- startedAsNewConversation,
- } = sub;
- run.subscribedEpoch = generationCreatedAt ?? null;
- if (generationCreatedAt != null) {
- updateActiveGenerationCreatedAt(
- currentStreamId,
- generationCreatedAt,
- undefined,
- generationProtocolVersion,
- );
- /** Until CREATED moves the conversation context off `/c/new`, Stop and
- * approval controls still read the placeholder key. Mirror the exact
- * epoch there briefly; the server's user-wide fallback plus this fence
- * can safely resolve the just-started job. */
- if (startedAsNewConversation) {
- updateActiveGenerationCreatedAt(
- Constants.NEW_CONVO,
- generationCreatedAt,
- undefined,
- generationProtocolVersion,
- );
- }
- setShowStopButton(true);
- } else {
- /** Generation-scoped mutations are unsafe until the server supplies
- * the epoch they must fence against. Keep Stop hidden if an old or
- * malformed response omitted it. */
- setShowStopButton(false);
- }
- /**
- * A NEW generation starts with its retained prefix intact, so the
- * cleared-prefix state from a previous one must not carry over: the
- * hook outlives any single submission, and a later edited resubmission
- * would otherwise dispatch with no offset and overwrite the content it
- * kept.
- *
- * Keyed on `clientRequestId`, the per-submission uuid. Each of the
- * narrower keys tried before it crossed a real boundary:
- * - `isResume`: a submission whose POST succeeded but lost its
- * response retries and returns `resumed: true`, so a NEW generation
- * arrives in resume mode and skipped the reset.
- * - the stream id: `request.js` sets `streamId = conversationId`, so
- * every generation in a conversation shares it.
- * - the response message id: editing an assistant response reuses
- * that same id (`editedMessageId`), so re-editing one response
- * produced the same key twice.
- * `clientRequestId` is minted per submission and forwarded unchanged on
- * retries, which is exactly "new per edit attempt, stable across
- * reconnects".
- */
- const generationId =
- sub.submission.clientRequestId ??
- (sub.submission.initialResponse as TMessage | undefined)?.messageId ??
- currentStreamId;
- run.bindPrefixState(generationId);
- bindResponse(sub.submission);
- const patcher = new ResponsePatcher(sub, host);
- const terminal: TerminalContext = {
- sub,
- host,
- applyPendingAction: (action) => patcher.applyPendingAction(action),
- };
-
- logger.log('ResumableSSE', 'Subscribing to stream:', sub.url(), { isResume });
- sub.claim();
- sub.watchForeground();
-
- const handleOpen = () => {
- if (!sub.isCurrent()) {
- return;
- }
- logger.log('ResumableSSE', 'Stream connected');
- setAbortScroll(false);
- // Restore UI state on successful connection (including reconnection)
- setIsSubmitting(true);
- setShowStopButton(generationCreatedAt != null);
- run.reconnectAttempt = 0;
- };
-
- const handleFrame = async (event: ChatEvent) => {
- try {
- if (!sub.isCurrent() || sub.finalReceived) {
- return;
- }
-
- if (event.type === 'final' && event.data.reconcile === true) {
- const { data } = event;
- if (
- generationProtocolVersion !== GENERATION_PROTOCOL_VERSION ||
- !supportsGenerationProtocolV2(data)
- ) {
- logger.warn('ResumableSSE', 'Ignoring unnegotiated lifecycle reconciliation frame');
- return;
- }
- // Synthesized lifecycle frames deliberately carry no ordinary
- // response payload. Reconcile durable history (or hand off to a
- // replacement epoch) instead of passing them to finalHandler.
- sub.finalReceived = true;
- run.cancelSteerRetryFrames();
- void reconcileGenerationLifecycle(terminal, data);
- return;
- }
-
- if (event.type === 'final') {
- const { data } = event;
- sub.finalReceived = true;
- const finalConvoId =
- data.conversation?.conversationId ??
- sub.submission.conversation?.conversationId ??
- currentStreamId;
- if (
- !(await authorizeTerminalTeardown(terminal, finalConvoId, 'FINAL')) ||
- !sub.isCurrent()
- ) {
- return;
- }
- run.cancelSteerRetryFrames();
- run.clearReconnectTimeout();
- run.reconnectAttempt = 0;
- logger.log('ResumableSSE', 'Received FINAL event', {
- aborted: data.aborted,
- conversationId: data.conversation?.conversationId,
- hasResponseMessage: !!data.responseMessage,
- });
- clearPendingApprovalForTerminal(terminal, finalConvoId);
- clearComposerDrafts(runIndex, sub.submission.conversation?.conversationId, {
- includeNewChatDraft:
- !sub.submission.conversation?.conversationId ||
- sub.submission.conversation.conversationId === Constants.NEW_CONVO ||
- run.optimisticStreamIds.has(currentStreamId) ||
- isInitialNewConversation(sub.submission),
- });
- // A steer-applied event may still be waiting for its next-frame
- // message target when FINAL arrives. Reconcile directly from the
- // authoritative final message before converting leftovers so a
- // late 202 ACK cannot resurrect (or queue) an already-applied steer.
- const finalAppliedSteerIds = new Set(
- collectAppliedSteerIds(data.responseMessage ? [data.responseMessage] : []),
- );
- settleAppliedSteerParts(
- finalConvoId,
- data.responseMessage ? [data.responseMessage] : undefined,
- );
- // Steers the run never injected ride the final event; convert them
- // to queued follow-ups before the run-end signal fires the drain
- // (also resets the applied-id set for the finished run).
- // `claimParked` reconciles the replayable parked copy of the same
- // steers; explicit dismissal or a persisted recovery removes it.
- convertSteersToQueued(
- finalConvoId,
- (generationProtocolVersion === 1 || supportsGenerationProtocolV2(data)) &&
- Array.isArray(data.pendingSteers)
- ? (data.pendingSteers as TPendingSteer[]).filter(
- (steer) =>
- !finalAppliedSteerIds.has(steer.steerId) &&
- (steer.clientSteerId == null ||
- !finalAppliedSteerIds.has(steer.clientSteerId)),
- )
- : [],
- {
- claimParked: true,
- generationProtocolVersion,
- },
- );
- // A `failed` chip never reached the server, so it never rides
- // `data.pendingSteers` above; without this it survives a NORMAL
- // completion and renders (with a live Retry) under the NEXT run's
- // reply. Idempotent alongside the call above: both dedupe by id.
- convertLocalSteersToQueued(finalConvoId);
- let finalHandled = false;
- try {
- finalHandler(data as TFinalResData, sub.submission as EventSubmission);
- finalHandled = true;
- finalizeUsage(data, sub.liveSubmission());
- } catch (error) {
- logger.error('ResumableSSE', 'Error in finalHandler:', error);
- setIsSubmitting(false);
- setShowStopButton(false);
- }
- // One-shot run-end signal for the queue drain. Written AFTER
- // finalHandler so `isSubmitting` has flipped false by the time the
- // drain effect observes it (both land in the same Recoil batch).
- // An early-aborted FIRST turn keys under NEW_CONVO: finalHandler
- // restored /c/new, so the optimistic id would strand the queue.
- const runEndTarget = resolveRunEndTarget({
- conversationId: finalConvoId,
- earlyAbort: data.earlyAbort === true,
- startedAsNewConvo: run.optimisticStreamIds.has(currentStreamId),
- });
- let finalOutcome: 'completed' | 'aborted' | 'error' = 'error';
- if (data.aborted === true || data.responseMessage?.unfinished === true) {
- finalOutcome = 'aborted';
- } else if (finalHandled) {
- finalOutcome = 'completed';
- }
- setRunEnd({
- conversationId: runEndTarget.conversationId,
- // A Stop that lands before completion can arrive as a final with
- // `unfinished: true` and no `aborted` flag (request.js's
- // wasAbortedBeforeComplete branch); it must not auto-drain.
- outcome: finalOutcome,
- startedAsNewConvo: runEndTarget.startedAsNewConvo,
- endedAt: run.scheduler.now(),
- generationCreatedAt,
- ...(data.responseMessage?.messageId != null && {
- responseMessageId: data.responseMessage.messageId,
- }),
- });
- // Clear handler maps on stream completion to prevent memory leaks
- clearStepMaps();
- // Optimistically remove from active jobs
- removeActiveJob(currentStreamId);
- clearAttachedGenerationCreatedAt(terminal);
- (startupConfig?.balance?.enabled ?? false) && balanceQuery.refetch();
- sub.close();
- setStreamId(null);
- run.releaseStream(currentStreamId);
- return;
- }
-
- if (event.type === 'created') {
- const { data } = event;
- logger.log('ResumableSSE', 'Received CREATED event', {
- messageId: data.message?.messageId,
- conversationId: data.message?.conversationId,
- });
- run.createdStreamIds.add(currentStreamId);
- if (startedAsNewConversation) {
- updateActiveGenerationCreatedAt(Constants.NEW_CONVO, null, generationCreatedAt);
- }
- const runId = v4();
- setActiveRunId(runId);
- sub.userMessage = {
- ...sub.userMessage,
- ...data.message,
- overrideParentMessageId: sub.userMessage.overrideParentMessageId,
- };
- const createdInitialResponse = buildCreatedInitialResponse({
- initialResponse: sub.submission.initialResponse as TMessage,
- userMessage: sub.userMessage,
- isRegenerate: sub.submission.isRegenerate,
- });
- sub.replaceSubmission({
- ...sub.submission,
- userMessage: sub.userMessage,
- initialResponse: createdInitialResponse,
- });
- run.identityConfirmed = true;
- bindResponse(sub.submission);
- createdHandler(data, sub.submission as EventSubmission);
- patcher.replayPreCreatedStepEvents();
- return;
- }
-
- if (event.type === 'attachment' && event.data) {
- attachmentHandler({
- data: event.data as TAttachment,
- submission: sub.submission as EventSubmission,
- });
- return;
- }
-
- if (event.type === 'title') {
- titleHandler(event.data);
- return;
- }
-
- if (event.type === 'context_usage') {
- contextHandler(event.data, sub.liveSubmission());
- return;
- }
-
- if (event.type === 'token_usage') {
- usageHandler(event.data, sub.liveSubmission());
- return;
- }
-
- if (event.type === 'pending_action') {
- patcher.applyPendingAction(event.data);
- setIsSubmitting(true);
- return;
- }
-
- if (event.type === 'steer_applied') {
- patcher.applySteer(event.data);
- return;
- }
-
- if (event.type === 'steer_updated') {
- updateSteerChips(event.data);
- return;
- }
-
- if (event.type === 'activity_label') {
- patcher.applyActivityLabel(event.data);
- return;
- }
-
- if (event.type === 'reasoning_label') {
- patcher.applyReasoningLabel(event.data);
- return;
- }
-
- if (event.type === 'step') {
- const data = event.data as StepEvent;
- if (
- data.event === StepEvents.ON_MESSAGE_DELTA ||
- data.event === StepEvents.ON_REASONING_DELTA
- ) {
- tapStream(data.data, sub.liveSubmission());
- }
- if (!isResume && !run.createdStreamIds.has(currentStreamId)) {
- if (isOAuthStepEvent(data)) {
- sub.preCreatedStepEvents.push(data);
- stepHandler(data, sub.liveSubmission() as EventSubmission);
- return;
- }
- sub.preCreatedStepEvents.push(data);
- return;
- }
- stepHandler(data, sub.liveSubmission() as EventSubmission);
- return;
- }
-
- if (event.type === 'sync') {
- const { data } = event;
- logger.log('ResumableSSE', 'SYNC received', {
- runSteps: data.resumeState?.runSteps?.length ?? 0,
- pendingEvents: data.pendingEvents?.length ?? 0,
- });
-
- const runId = v4();
- setActiveRunId(runId);
- /** Keep the current run's preliminary id long enough to replace that optimistic
- * row in place if this snapshot assigns its durable response id. */
- const preliminaryResponseMessageId = sub.submission.initialResponse?.messageId;
- const currentUserMessageId = sub.submission.userMessage?.messageId;
- const preliminaryUserMessageId =
- currentUserMessageId &&
- (sub.submission.initialResponse?.parentMessageId === currentUserMessageId ||
- preliminaryResponseMessageId === `${currentUserMessageId}_`)
- ? currentUserMessageId
- : undefined;
- const resumeSubmission = buildResumeEventSubmission(
- sub.submission,
- sub.userMessage,
- data.resumeState,
- );
- sub.replaceSubmission(resumeSubmission);
- sub.userMessage = resumeSubmission.userMessage;
- if (data.resumeState?.userMessage != null) {
- run.identityConfirmed = true;
- }
- /**
- * Totals rebuild from the persisted backfill at sync. Replayed or
- * gap usage events already represented in the snapshot are skipped
- * via multiset matching; events that raced past the snapshot read
- * still fold so multi-call runs don't undercount.
- */
- /** Fold the run's persisted usage; events also replayed below are
- * deduped by (runId, seq) inside the handler, so prior prompts in
- * this conversation keep their usage and gap events still count */
- backfillUsage(data.resumeState?.collectedUsage ?? [], resumeSubmission);
- if (data.resumeState?.contextUsage) {
- /** Already reconciled to the call's real prompt tokens server-side
- * (GenerationJobManager.persistTokenUsage) when the snapshot's call
- * completed, so install it as-is: no client backfill reconcile. */
- contextHandler(data.resumeState.contextUsage, resumeSubmission);
- }
- /** Output streamed before this resume is not re-delivered as deltas;
- * estimate it from the trailing aggregated content. This is
- * needed even with a snapshot: the snapshot is pre-invoke, so the
- * in-flight output it precedes rides on the live estimate.
- * countTrailingOutputChars only counts output at the very end (0
- * when paused at a tool call), so a snapshot's budget is never
- * double-counted. */
- seedLive(
- countTrailingOutputChars(data.resumeState?.aggregatedContent),
- resumeSubmission,
- );
-
- const pendingOAuthPrompts = data.resumeState?.pendingOAuthPrompts ?? [];
- const pendingOAuthStepIds = new Set(pendingOAuthPrompts.map((prompt) => prompt.stepId));
- if (data.resumeState?.runSteps) {
- for (const runStep of data.resumeState.runSteps) {
- if (pendingOAuthStepIds.has(runStep.id)) {
- continue;
- }
- stepHandler({ event: StepEvents.ON_RUN_STEP, data: runStep }, resumeSubmission);
- }
- }
-
- if (data.resumeState?.aggregatedContent && sub.userMessage?.messageId) {
- const messages = getMessages() ?? [];
- const userMsgId = sub.userMessage.messageId;
- const hasResumedContent = data.resumeState.aggregatedContent.length > 0;
- const responseId = resumeSubmission.initialResponse.messageId;
- const messageIndexes = getResumeMessageIndexes(
- messages,
- userMsgId,
- responseId,
- preliminaryUserMessageId,
- preliminaryResponseMessageId,
- );
- const responseIdx =
- messageIndexes.responseIndex >= 0
- ? messageIndexes.responseIndex
- : messageIndexes.preliminaryResponseIndex;
-
- logger.log('ResumableSSE', 'SYNC update', {
- userMsgId,
- responseId,
- responseIdx,
- foundMessageId: responseIdx >= 0 ? messages[responseIdx]?.messageId : null,
- messagesCount: messages.length,
- aggregatedContentLength: data.resumeState.aggregatedContent?.length,
- });
-
- if (responseIdx >= 0) {
- const oldContent = messages[responseIdx]?.content;
- /** An EMPTY resume snapshot is not authoritative over content we already loaded
- * for the SAME generation-owned response: assigning it would erase that content
- * and leave a bare cursor. Require an existing content array so it is never
- * swapped for `undefined`. */
- const preserveLoadedContent =
- !hasResumedContent && Array.isArray(oldContent) && oldContent.length > 0;
- /**
- * Replacing the response with `aggregatedContent` drops the
- * prefix an edited resubmission had retained: the snapshot is
- * completion-local, indexed from zero. Every later event must
- * therefore stop offsetting, or it writes past the end of the
- * shorter array: for an activity label that means the fill
- * misses its own reservation and the placeholder never
- * resolves. Preserving `oldContent` keeps the prefix, and with
- * it the offset. Run steps and labels both read this.
- */
- if (!preserveLoadedContent) {
- run.editPrefixCleared = true;
- }
- const responseMessage = {
- ...resumeSubmission.initialResponse,
- ...messages[responseIdx],
- messageId: responseId,
- parentMessageId: userMsgId,
- content: preserveLoadedContent ? oldContent : data.resumeState.aggregatedContent,
- sender: messages[responseIdx]?.sender ?? resumeSubmission.initialResponse.sender,
- iconURL: preferDefinedString(
- messages[responseIdx]?.iconURL,
- resumeSubmission.initialResponse.iconURL ?? data.resumeState.iconURL,
- ),
- model: preferDefinedString(
- messages[responseIdx]?.model,
- resumeSubmission.initialResponse.model ?? data.resumeState.model,
- ),
- } as TMessage;
- const updated = mergeResumeMessages(
- messages,
- sub.userMessage,
- responseMessage,
- messageIndexes,
- resumeSubmission.compact === true,
- );
- logger.log('ResumableSSE', 'SYNC updating message', {
- messageId: responseMessage.messageId,
- oldContentLength: Array.isArray(oldContent) ? oldContent.length : 0,
- newContentLength: data.resumeState.aggregatedContent?.length,
- preservedExistingContent: preserveLoadedContent,
- });
- setMessages(updated);
- resetContentHandler();
- syncStepMessage(responseMessage);
- logger.log('ResumableSSE', 'SYNC complete, handlers synced');
- } else {
- /** Same reasoning as the matched branch above: this row is
- * built straight from the server's completion-local
- * `aggregatedContent`, so it holds no retained prefix and
- * later steps and labels must stop offsetting. Setting it
- * only in the matched branch left this path adding an offset
- * to indices that were already absolute. */
- run.editPrefixCleared = true;
- const newMessage = {
- ...resumeSubmission.initialResponse,
- messageId: responseId,
- parentMessageId: userMsgId,
- content: data.resumeState.aggregatedContent,
- isCreatedByUser: false,
- } as TMessage;
- setMessages(
- mergeResumeMessages(
- messages,
- sub.userMessage,
- newMessage,
- messageIndexes,
- resumeSubmission.compact === true,
- ),
- );
- resetContentHandler();
- syncStepMessage(newMessage);
- }
- }
-
- for (const prompt of pendingOAuthPrompts) {
- patcher.applyPendingOAuthPrompt(prompt, resumeSubmission);
- }
-
- /**
- * Re-pause on reconnect: the run is parked on a human-review
- * interrupt. Re-apply the pending action so the approval / ask-user
- * controls render after a reload or dropped connection.
- */
- if (data.resumeState?.pendingAction) {
- patcher.applyPendingAction(data.resumeState.pendingAction as Agents.PendingAction);
- }
-
- /**
- * Re-seed steer chips from the server's still-queued steers.
- * Injected steers are already inside `aggregatedContent`, so this
- * covers exactly the remainder a reloading client can't know about.
- */
- // Always reconcile against the server's still-queued list: a steer
- // applied while this client was disconnected is absent here (its
- // inline part rides aggregatedContent instead), so an EMPTY list
- // must clear stale local pending chips, not leave them stranded.
- const steerConvoId = sub.submission.conversation?.conversationId ?? currentStreamId;
- seedSteerChips(
- steerConvoId,
- (data.resumeState?.pendingSteers ?? []) as TPendingSteer[],
- generationCreatedAt,
- generationProtocolVersion,
- );
- // Seed first, then remove anything already represented in the
- // authoritative content. Reversing this order can re-mint a stale
- // server snapshot entry after it was just settled.
- settleAppliedSteerParts(
- steerConvoId,
- data.resumeState?.aggregatedContent as unknown[] | undefined,
- );
-
- if (data.resumeState?.titleEvent) {
- titleHandler(data.resumeState.titleEvent);
- }
-
- /** PTC inner calls are not content parts, so the resume snapshot
- * can't rebuild them and a settling event lost in this gap is
- * never replayed. Mark rows still `running` as interrupted rather
- * than leave a spinner that never resolves — and rather than drop
- * them, since a call still executing across the reconnect settles
- * normally on the restored stream and updates its row in place. */
- prunePtcTraces();
-
- const replayEvents = data.resumeState?.replayEvents ?? [];
- if (replayEvents.length > 0) {
- logger.log('ResumableSSE', `Replaying ${replayEvents.length} resume events`);
- for (const replayEvent of replayEvents) {
- const replayStepId = getStepEventId(replayEvent);
- if (
- replayStepId != null &&
- pendingOAuthStepIds.has(replayStepId) &&
- isOAuthStepEvent(replayEvent)
- ) {
- continue;
- }
- if (replayEvent.event === UsageEvents.ON_CONTEXT_USAGE) {
- contextHandler(replayEvent.data as TContextUsageEvent, resumeSubmission);
- } else if (replayEvent.event === UsageEvents.ON_TOKEN_USAGE) {
- usageHandler(replayEvent.data as TTokenUsageEvent, resumeSubmission);
- } else if (replayEvent.event === ApprovalEvents.ON_PENDING_ACTION) {
- // A pause that landed after the resume snapshot must still render its
- // controls (mirror the live handler), not fall through to stepHandler.
- patcher.applyPendingAction(replayEvent.data as Agents.PendingAction);
- } else if (replayEvent.event === SteerEvents.ON_STEER_APPLIED) {
- patcher.applySteer(replayEvent.data as TSteerAppliedEvent);
- } else if (replayEvent.event === SteerEvents.ON_STEER_UPDATED) {
- updateSteerChips(replayEvent.data as TSteerUpdatedEvent);
- } else if (replayEvent.event === ActivityLabelEvents.ON_ACTIVITY_LABEL) {
- patcher.applyActivityLabel(replayEvent.data as TActivityLabelEvent);
- } else if (replayEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL) {
- patcher.applyReasoningLabel(replayEvent.data as TReasoningLabelEvent);
- } else if (replayEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL_ATTEMPT) {
- // Durable provider-call budget reservations never render.
- } else if (replayEvent.event != null) {
- if (
- replayEvent.event === StepEvents.ON_MESSAGE_DELTA ||
- replayEvent.event === StepEvents.ON_REASONING_DELTA
- ) {
- tapStream(replayEvent.data as Agents.MessageDeltaEvent, resumeSubmission);
- }
- stepHandler(replayEvent as StepEvent, resumeSubmission);
- }
- }
- }
-
- const pendingEvents = data.pendingEvents ?? [];
- if (pendingEvents.length > 0) {
- logger.log('ResumableSSE', `Replaying ${pendingEvents.length} pending events`);
- for (const pendingEvent of pendingEvents) {
- if (!('event' in pendingEvent)) {
- if ('type' in pendingEvent) {
- /** Gap output streamed past the resume snapshot must reach the
- * live estimate too, not just the message UI */
- tapContent(
- 'text' in pendingEvent ? pendingEvent.text : undefined,
- resumeSubmission,
- );
- contentHandler({ data: pendingEvent, submission: resumeSubmission });
- }
- continue;
- }
- if (pendingEvent.event === 'title') {
- titleHandler(pendingEvent);
- } else if (pendingEvent.event === UsageEvents.ON_CONTEXT_USAGE) {
- contextHandler(pendingEvent.data, resumeSubmission);
- } else if (pendingEvent.event === UsageEvents.ON_TOKEN_USAGE) {
- usageHandler(pendingEvent.data, resumeSubmission);
- } else if (pendingEvent.event === ApprovalEvents.ON_PENDING_ACTION) {
- // In-memory mode can surface a pause that landed between getResumeState()
- // and the subscription here; route it to the same handler as a live event
- // so the approval / ask-user controls render (else the stream sits paused
- // with no UI until a full status reload).
- patcher.applyPendingAction(pendingEvent.data as Agents.PendingAction);
- } else if (pendingEvent.event === SteerEvents.ON_STEER_APPLIED) {
- patcher.applySteer(pendingEvent.data as TSteerAppliedEvent);
- } else if (pendingEvent.event === SteerEvents.ON_STEER_UPDATED) {
- updateSteerChips(pendingEvent.data as TSteerUpdatedEvent);
- } else if (pendingEvent.event === ActivityLabelEvents.ON_ACTIVITY_LABEL) {
- patcher.applyActivityLabel(pendingEvent.data as TActivityLabelEvent);
- } else if (pendingEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL) {
- patcher.applyReasoningLabel(pendingEvent.data as TReasoningLabelEvent);
- } else if (pendingEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL_ATTEMPT) {
- // Durable provider-call budget reservations never render.
- } else if (pendingEvent.event != null) {
- if (
- pendingEvent.event === StepEvents.ON_MESSAGE_DELTA ||
- pendingEvent.event === StepEvents.ON_REASONING_DELTA
- ) {
- tapStream(pendingEvent.data, resumeSubmission);
- }
- stepHandler(pendingEvent as StepEvent, resumeSubmission);
- }
- }
- }
-
- setIsSubmitting(true);
- setShowStopButton(generationCreatedAt != null);
- return;
- }
-
- if (event.type === 'content') {
- const { data } = event;
- const { index } = data;
- const text = 'text' in data ? data.text : undefined;
- if (text != null && index !== sub.textIndex) {
- sub.textIndex = index;
- }
- tapContent(text, sub.liveSubmission());
- contentHandler({ data, submission: sub.submission as EventSubmission });
- return;
- }
-
- if (event.type === 'text') {
- const { data } = event;
- const text = data.text ?? data.response;
- const initialResponse = {
- ...(sub.submission.initialResponse as TMessage),
- parentMessageId: data.parentMessageId,
- messageId: data.messageId,
- } as TMessage;
- /** Legacy non-agent streams send cumulative text here; feed the
- * live estimate like the content path above */
- const textSubmission = {
- ...sub.submission,
- userMessage: sub.userMessage,
- initialResponse,
- };
- sub.replaceSubmission(textSubmission);
- tapContent(text, textSubmission);
- messageHandler(text, textSubmission);
- }
- } catch (error) {
- logger.error('ResumableSSE', 'Error processing message:', error);
- }
- };
-
- /**
- * The transport emits `abort` only for this hook's own closes. A cancel
- * the user agent issued (a backgrounded or frozen mobile tab, while the
- * generation keeps running server-side) arrives as an `error` with status
- * 0 instead, so it climbs the same reconnect ladder as any dropped
- * connection rather than stranding the pane on its partial content.
- */
- const handleClose = () => {
- if (!sub.isCurrent()) {
- return;
- }
-
- if (run.replacementHandoff) {
- logger.log('ResumableSSE', 'Stream closed for generation handoff - preserving state');
- return;
- }
- // If we're in a reconnection cycle, don't reset state
- // (error handler will set up the reconnect timeout)
- if (run.reconnectAttempt > 0) {
- logger.log('ResumableSSE', 'Stream closed for reconnect - preserving state');
- return;
- }
-
- logger.log('ResumableSSE', 'Stream aborted (intentional close) - no reconnect');
- run.cancelSteerRetryFrames();
- // Clear any pending reconnect attempts
- run.clearReconnectTimeout();
- // Reset UI state - useResumeOnLoad will restore if user returns to this conversation
- setIsSubmitting(false);
- setShowStopButton(false);
- setStreamId(null);
- /** Intentional close without a final event (explicit stop, or navigation
- * while generating): discard the in-flight pending usage so it can't
- * merge into the next response in this conversation. On a resume the
- * collected usage is re-folded via backfillUsage, so nothing is lost. */
- resetLive(sub.liveSubmission());
- // No final/error event fires on this path, so it's the only place left
- // to sweep a local `failed` chip; otherwise it survives this close and
- // renders (with a live Retry) under whatever run starts next. `pending`
- // chips are deliberately left alone here: this listener also fires on
- // navigation away while the run CONTINUES server-side, so a
- // server-ACK'd `pending` steer is not stranded: the server injects it
- // regardless, and sweeping it into the queue too would resend the same
- // words as a duplicate turn once `useQueueDrain` fires at run end.
- convertLocalSteersToQueued(sub.submission.conversation?.conversationId ?? currentStreamId, {
- statuses: ABORT_SWEEP_STATUSES,
- });
- };
-
- sub.connect(transport.stream({ token }), {
- onOpen: handleOpen,
- onFrame: (event) => void handleFrame(event),
- onFailure: (event) => void handleTransportFailure(terminal, event),
- onClose: handleClose,
- });
-
- // Debug hooks for testing reconnection vs clean close behavior (dev only)
- if (import.meta.env.DEV) {
- const debugWindow = window as Window & {
- __killNetwork?: () => void;
- __closeClean?: () => void;
- };
-
- /** Simulate network drop - triggers error event → reconnection */
- debugWindow.__killNetwork = () => {
- logger.log('Debug', 'Simulating network drop...');
- void handleTransportFailure(terminal, {});
- };
-
- /** Simulate clean close (navigation away) - triggers abort event → no reconnection */
- debugWindow.__closeClean = () => {
- logger.log('Debug', 'Simulating clean close (navigation away)...');
- sub.retired = true;
- sub.close();
- };
- }
+ attachResumableStream(run, host, target);
},
[
run,
@@ -1337,7 +573,6 @@ export default function useResumableSSE(
setMessages,
startupConfig?.balance?.enabled,
balanceQuery,
- removeActiveJob,
bindResponse,
contextHandler,
usageHandler,
diff --git a/packages/chat/src/core/__fixtures__/resumable.ts b/packages/chat/src/core/__fixtures__/resumable.ts
index a9d1371ddb..c87f7051e1 100644
--- a/packages/chat/src/core/__fixtures__/resumable.ts
+++ b/packages/chat/src/core/__fixtures__/resumable.ts
@@ -99,10 +99,17 @@ export const createHost = (
refreshBalance: jest.fn(),
updateConversation: jest.fn(),
resolveDetachedEnd: jest.fn(() => ({ resolvable: false, end: null })),
+ setAbortScroll: jest.fn(),
+ renewActiveRun: jest.fn(),
+ runEndTarget: jest.fn((params) => ({
+ conversationId: params.conversationId,
+ startedAsNewConvo: params.startedAsNewConvo,
+ })),
},
steers: {
resolve: jest.fn(() => []),
markLiveApplied: jest.fn(),
+ update: jest.fn(),
seed: jest.fn(),
appliedIds: jest.fn(() => []),
settleApplied: jest.fn(),
@@ -111,6 +118,14 @@ export const createHost = (
},
events: {
stepHandler: jest.fn(),
+ finalHandler: jest.fn(),
+ createdHandler: jest.fn(),
+ attachmentHandler: jest.fn(),
+ titleHandler: jest.fn(),
+ contentHandler: jest.fn(),
+ messageHandler: jest.fn(),
+ prunePtcTraces: jest.fn(),
+ resetContentHandler: jest.fn(),
syncStepMessage: jest.fn(),
clearStepMaps: jest.fn(),
flushPendingDeltas: jest.fn(),
@@ -132,6 +147,17 @@ export const createHost = (
applyReasoningLabel: jest.fn((message) => message),
findReasoningLabelTarget: jest.fn(() => -1),
},
+ usage: {
+ bindResponse: jest.fn(),
+ contextHandler: jest.fn(),
+ usageHandler: jest.fn(),
+ tapStream: jest.fn(),
+ tapContent: jest.fn(),
+ finalizeUsage: jest.fn(),
+ backfillUsage: jest.fn(),
+ seedLiveFromContent: jest.fn(),
+ },
+ stream: { send: jest.fn(), reconnectToStream: jest.fn(() => ({ closed: false })) },
};
return host;
};
diff --git a/packages/chat/src/core/__tests__/dispatch.spec.ts b/packages/chat/src/core/__tests__/dispatch.spec.ts
new file mode 100644
index 0000000000..50ba94af9f
--- /dev/null
+++ b/packages/chat/src/core/__tests__/dispatch.spec.ts
@@ -0,0 +1,193 @@
+import { StepEvents } from 'librechat-data-provider';
+import type {
+ ChatEvent,
+ TMessage,
+ TSubmission,
+ ChatTransportOptions,
+} from 'librechat-data-provider';
+import type { ResumableHost, StreamStatusResponse } from '../resumable';
+import { createHost, createScheduler } from '../__fixtures__/resumable';
+import { ResumableRun, attachResumableStream } from '../resumable';
+
+const userMessage = {
+ messageId: 'u-1',
+ conversationId: 'c-1',
+ isCreatedByUser: true,
+ text: 'Hello',
+} as TMessage;
+
+const submission = {
+ userMessage,
+ initialResponse: { messageId: 'u-1_', conversationId: 'c-1', isCreatedByUser: false },
+ conversation: { conversationId: 'c-1' },
+ clientRequestId: 'req-1',
+} as TSubmission;
+
+/** Attaches a pane and returns a way to emit events on its connection. */
+const attach = (overrides: { isResume?: boolean; generationProtocolVersion?: 1 | 2 } = {}) => {
+ const clock = createScheduler();
+ const fetchStatus = jest.fn<Promise<StreamStatusResponse>, [string]>();
+ const host: ResumableHost = createHost(fetchStatus);
+ let options: ChatTransportOptions | undefined;
+ (host.stream.reconnectToStream as jest.Mock).mockImplementation((_request, opts) => {
+ options = opts;
+ return { closed: false };
+ });
+ const run = new ResumableRun(clock.scheduler);
+ run.submission = submission;
+ attachResumableStream(run, host, {
+ streamId: 'c-1',
+ submission,
+ isResume: overrides.isResume ?? false,
+ generationCreatedAt: 2000,
+ generationProtocolVersion: overrides.generationProtocolVersion ?? 1,
+ });
+ const emit = async (event: ChatEvent) => {
+ options?.onEvent(event);
+ await new Promise((resolve) => setImmediate(resolve));
+ };
+ return { clock, fetchStatus, host, run, emit };
+};
+
+describe('attachResumableStream', () => {
+ it('installs the epoch, binds the response and connects', () => {
+ const { host, run } = attach();
+ expect(host.pane.setGenerationEpoch).toHaveBeenCalledWith('c-1', 2000, undefined, 1);
+ expect(host.pane.setShowStopButton).toHaveBeenCalledWith(true);
+ expect(host.usage.bindResponse).toHaveBeenCalledWith(submission);
+ expect(run.prefixStateGenerationId).toBe('req-1');
+ expect(run.subscribedEpoch).toBe(2000);
+ expect(host.stream.reconnectToStream).toHaveBeenCalledTimes(1);
+ });
+
+ it('attaches nothing for a submission the pane no longer serves', () => {
+ const host = createHost();
+ const run = new ResumableRun(createScheduler().scheduler);
+ attachResumableStream(run, host, {
+ streamId: 'c-1',
+ submission,
+ isResume: false,
+ generationProtocolVersion: 1,
+ });
+ expect(host.stream.reconnectToStream).not.toHaveBeenCalled();
+ });
+
+ it('restores the controls when the connection opens', async () => {
+ const { host, run, emit } = attach();
+ run.reconnectAttempt = 2;
+ await emit({ type: 'open' });
+ expect(host.pane.setAbortScroll).toHaveBeenCalledWith(false);
+ expect(host.pane.setIsSubmitting).toHaveBeenCalledWith(true);
+ expect(run.reconnectAttempt).toBe(0);
+ });
+});
+
+describe('handleFrame', () => {
+ it('holds step events until created names the turn, then replays them', async () => {
+ const { host, run, emit } = attach();
+ const step = { event: StepEvents.ON_RUN_STEP, data: { id: 'step-1' } };
+ await emit({ type: 'step', data: step } as ChatEvent);
+ expect(host.events.stepHandler).not.toHaveBeenCalled();
+
+ await emit({
+ type: 'created',
+ data: { created: true, message: { ...userMessage, messageId: 'u-2' } },
+ } as ChatEvent);
+ expect(host.pane.renewActiveRun).toHaveBeenCalled();
+ expect(run.identityConfirmed).toBe(true);
+ expect(run.submission?.userMessage.messageId).toBe('u-2');
+ expect(run.submission?.initialResponse?.messageId).toBe('u-2_');
+ expect(host.events.createdHandler).toHaveBeenCalled();
+ expect(host.events.stepHandler).toHaveBeenCalledWith(
+ step,
+ expect.objectContaining({ userMessage: expect.objectContaining({ messageId: 'u-2' }) }),
+ );
+ });
+
+ it('settles a final frame and publishes the run end', async () => {
+ const { host, run, emit } = attach();
+ const responseMessage = { messageId: 'r-1', conversationId: 'c-1' } as TMessage;
+ await emit({
+ type: 'final',
+ data: { final: true, conversation: { conversationId: 'c-1' }, responseMessage },
+ } as ChatEvent);
+ expect(host.events.finalHandler).toHaveBeenCalled();
+ expect(host.usage.finalizeUsage).toHaveBeenCalled();
+ expect(host.steers.convertLocalToQueued).toHaveBeenCalledWith('c-1');
+ expect(host.pane.publishRunEnd).toHaveBeenCalledWith(
+ expect.objectContaining({
+ conversationId: 'c-1',
+ outcome: 'completed',
+ generationCreatedAt: 2000,
+ responseMessageId: 'r-1',
+ }),
+ );
+ expect(host.cache.removeActiveJob).toHaveBeenCalledWith('c-1');
+ expect(run.stream?.signal.aborted).toBe(true);
+ });
+
+ it('ignores an unnegotiated lifecycle reconciliation frame', async () => {
+ const { host, emit } = attach();
+ await emit({ type: 'final', data: { final: true, reconcile: true } } as ChatEvent);
+ expect(host.cache.invalidateMessages).not.toHaveBeenCalled();
+ expect(host.events.finalHandler).not.toHaveBeenCalled();
+ });
+
+ it('routes side events to the patcher, usage and steer chips', async () => {
+ const { host, emit } = attach();
+ await emit({ type: 'title', data: { event: 'title' } } as ChatEvent);
+ await emit({ type: 'steer_updated', data: { conversationId: 'c-1', steers: [] } } as ChatEvent);
+ await emit({ type: 'token_usage', data: {} } as ChatEvent);
+ expect(host.events.titleHandler).toHaveBeenCalled();
+ expect(host.steers.update).toHaveBeenCalled();
+ expect(host.usage.usageHandler).toHaveBeenCalled();
+ });
+});
+
+describe('handleSync', () => {
+ it('rebuilds the response from the resume snapshot', async () => {
+ const { host, emit, run } = attach({ isResume: true });
+ host.messages.set([userMessage, submission.initialResponse as TMessage]);
+ await emit({
+ type: 'sync',
+ data: {
+ sync: true,
+ resumeState: {
+ runSteps: [],
+ aggregatedContent: [{ type: 'text', text: 'partial' }],
+ userMessage: { messageId: 'u-1', parentMessageId: null, text: 'Hello' },
+ responseMessageId: 'r-1',
+ conversationId: 'c-1',
+ pendingSteers: [],
+ },
+ pendingEvents: [],
+ },
+ } as unknown as ChatEvent);
+ const response = host.messages.get()?.find((message) => message.messageId === 'r-1');
+ expect(response?.content).toEqual([{ type: 'text', text: 'partial' }]);
+ expect(run.editPrefixCleared).toBe(true);
+ expect(host.events.resetContentHandler).toHaveBeenCalled();
+ expect(host.steers.seed).toHaveBeenCalledWith('c-1', [], 2000, 1);
+ expect(host.usage.seedLiveFromContent).toHaveBeenCalled();
+ expect(host.pane.setIsSubmitting).toHaveBeenLastCalledWith(true);
+ });
+});
+
+describe('handleClose', () => {
+ it('idles the pane and sweeps failed chips on an intentional close', async () => {
+ const { host, emit } = attach();
+ await emit({ type: 'abort' });
+ expect(host.pane.setIsSubmitting).toHaveBeenLastCalledWith(false);
+ expect(host.pane.setStreamId).toHaveBeenCalledWith(null);
+ expect(host.steers.convertLocalToQueued).toHaveBeenCalledWith('c-1', {
+ statuses: ['failed'],
+ });
+ });
+
+ it('keeps the pane busy while a reconnect is pending', async () => {
+ const { host, run, emit } = attach();
+ run.reconnectAttempt = 1;
+ await emit({ type: 'abort' });
+ expect(host.pane.setStreamId).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/chat/src/core/resumable/attach.ts b/packages/chat/src/core/resumable/attach.ts
new file mode 100644
index 0000000000..622b19c817
--- /dev/null
+++ b/packages/chat/src/core/resumable/attach.ts
@@ -0,0 +1,114 @@
+import { Constants } from 'librechat-data-provider';
+import type { TMessage } from 'librechat-data-provider';
+import type { ResumableHost, SubscriptionTarget } from './host';
+import type { StreamContext } from './terminal';
+import type { ResumableRun } from './run';
+import { handleOpen, handleClose, handleFrame } from './frames';
+import { ResumableSubscription } from './subscription';
+import { handleTransportFailure } from './failure';
+import { ResponsePatcher } from './patches';
+
+/**
+ * Attaches the pane to a generation: installs its epoch on the controls, binds the response
+ * the stream writes to, and opens the connection with every frame, failure and close routed
+ * through core. A target whose pane lifecycle ended or whose submission the pane no longer
+ * serves attaches nothing.
+ */
+export function attachResumableStream(
+ run: ResumableRun,
+ host: ResumableHost,
+ target: SubscriptionTarget,
+): void {
+ /** See `ResumableSubscription.isCurrent` for the fences every callback below checks. */
+ if (target.signal?.aborted || run.submission !== target.submission) {
+ return;
+ }
+ const sub = new ResumableSubscription(run, host, target);
+ const { streamId, isResume, generationCreatedAt, generationProtocolVersion } = sub;
+ run.subscribedEpoch = generationCreatedAt ?? null;
+ if (generationCreatedAt != null) {
+ host.pane.setGenerationEpoch(
+ streamId,
+ generationCreatedAt,
+ undefined,
+ generationProtocolVersion,
+ );
+ /** Until CREATED moves the conversation context off `/c/new`, Stop and
+ * approval controls still read the placeholder key. Mirror the exact
+ * epoch there briefly; the server's user-wide fallback plus this fence
+ * can safely resolve the just-started job. */
+ if (sub.startedAsNewConversation) {
+ host.pane.setGenerationEpoch(
+ Constants.NEW_CONVO,
+ generationCreatedAt,
+ undefined,
+ generationProtocolVersion,
+ );
+ }
+ host.pane.setShowStopButton(true);
+ } else {
+ /** Generation-scoped mutations are unsafe until the server supplies
+ * the epoch they must fence against. Keep Stop hidden if an old or
+ * malformed response omitted it. */
+ host.pane.setShowStopButton(false);
+ }
+ /**
+ * A NEW generation starts with its retained prefix intact, so the
+ * cleared-prefix state from a previous one must not carry over: the
+ * run outlives any single submission, and a later edited resubmission
+ * would otherwise dispatch with no offset and overwrite the content it
+ * kept.
+ *
+ * Keyed on `clientRequestId`, the per-submission uuid. Each of the
+ * narrower keys tried before it crossed a real boundary:
+ * - `isResume`: a submission whose POST succeeded but lost its
+ * response retries and returns `resumed: true`, so a NEW generation
+ * arrives in resume mode and skipped the reset.
+ * - the stream id: `request.js` sets `streamId = conversationId`, so
+ * every generation in a conversation shares it.
+ * - the response message id: editing an assistant response reuses
+ * that same id (`editedMessageId`), so re-editing one response
+ * produced the same key twice.
+ * `clientRequestId` is minted per submission and forwarded unchanged on
+ * retries, which is exactly "new per edit attempt, stable across
+ * reconnects".
+ */
+ const generationId =
+ sub.submission.clientRequestId ??
+ (sub.submission.initialResponse as TMessage | undefined)?.messageId ??
+ streamId;
+ run.bindPrefixState(generationId);
+ host.usage.bindResponse(sub.submission);
+ const patcher = new ResponsePatcher(sub, host);
+ const ctx: StreamContext = {
+ sub,
+ host,
+ patcher,
+ applyPendingAction: (action) => patcher.applyPendingAction(action),
+ };
+
+ host.logger.log('ResumableSSE', 'Subscribing to stream:', sub.url(), { isResume });
+ sub.claim();
+ sub.watchForeground();
+
+ sub.connect(host.stream, {
+ onOpen: () => handleOpen(ctx),
+ onFrame: (event) => void handleFrame(ctx, event),
+ onFailure: (event) => void handleTransportFailure(ctx, event),
+ onClose: () => handleClose(ctx),
+ });
+
+ host.exposeDebugControls?.({
+ /** Simulate network drop - triggers error event → reconnection */
+ killNetwork: () => {
+ host.logger.log('Debug', 'Simulating network drop...');
+ void handleTransportFailure(ctx, {});
+ },
+ /** Simulate clean close (navigation away) - triggers abort event → no reconnection */
+ closeClean: () => {
+ host.logger.log('Debug', 'Simulating clean close (navigation away)...');
+ sub.retired = true;
+ sub.close();
+ },
+ });
+}
diff --git a/packages/chat/src/core/resumable/frames.ts b/packages/chat/src/core/resumable/frames.ts
new file mode 100644
index 0000000000..d6796e224e
--- /dev/null
+++ b/packages/chat/src/core/resumable/frames.ts
@@ -0,0 +1,386 @@
+import { Constants, StepEvents } from 'librechat-data-provider';
+import type {
+ TMessage,
+ ChatEvent,
+ TAttachment,
+ TPendingSteer,
+ ChatFinalFrame,
+ EventSubmission,
+ ChatCreatedFrame,
+} from 'librechat-data-provider';
+import type { StreamContext } from './terminal';
+import type { StepEvent } from '../reducer';
+import {
+ authorizeTerminalTeardown,
+ clearPendingApprovalForTerminal,
+ clearAttachedGenerationCreatedAt,
+} from './terminal';
+import { GENERATION_PROTOCOL_VERSION, supportsGenerationProtocolV2 } from '../protocol';
+import { isInitialNewConversation, buildCreatedInitialResponse } from './messages';
+import { reconcileGenerationLifecycle } from './reconcile';
+import { ABORT_SWEEP_STATUSES } from '../steer/chips';
+import { isOAuthStepEvent } from './events';
+import { handleSync } from './sync';
+
+export function handleOpen({ sub, host }: StreamContext): void {
+ const { run, generationCreatedAt } = sub;
+ if (!sub.isCurrent()) {
+ return;
+ }
+ host.logger.log('ResumableSSE', 'Stream connected');
+ host.pane.setAbortScroll(false);
+ // Restore UI state on successful connection (including reconnection)
+ host.pane.setIsSubmitting(true);
+ host.pane.setShowStopButton(generationCreatedAt != null);
+ run.reconnectAttempt = 0;
+}
+
+/** The run's ordinary final: settles steers, writes the final response and publishes the end. */
+async function handleFinal(ctx: StreamContext, data: ChatFinalFrame): Promise<void> {
+ const { sub, host } = ctx;
+ const { run, generationCreatedAt, generationProtocolVersion } = sub;
+ const currentStreamId = sub.streamId;
+ sub.finalReceived = true;
+ const finalConvoId =
+ data.conversation?.conversationId ??
+ sub.submission.conversation?.conversationId ??
+ currentStreamId;
+ if (!(await authorizeTerminalTeardown(ctx, finalConvoId, 'FINAL')) || !sub.isCurrent()) {
+ return;
+ }
+ run.cancelSteerRetryFrames();
+ run.clearReconnectTimeout();
+ run.reconnectAttempt = 0;
+ host.logger.log('ResumableSSE', 'Received FINAL event', {
+ aborted: data.aborted,
+ conversationId: data.conversation?.conversationId,
+ hasResponseMessage: !!data.responseMessage,
+ });
+ clearPendingApprovalForTerminal(ctx, finalConvoId);
+ host.pane.clearComposerDrafts(sub.submission.conversation?.conversationId, {
+ includeNewChatDraft:
+ !sub.submission.conversation?.conversationId ||
+ sub.submission.conversation.conversationId === Constants.NEW_CONVO ||
+ run.optimisticStreamIds.has(currentStreamId) ||
+ isInitialNewConversation(sub.submission),
+ });
+ // A steer-applied event may still be waiting for its next-frame
+ // message target when FINAL arrives. Reconcile directly from the
+ // authoritative final message before converting leftovers so a
+ // late 202 ACK cannot resurrect (or queue) an already-applied steer.
+ const finalAppliedSteerIds = new Set(
+ host.steers.appliedIds(data.responseMessage ? [data.responseMessage] : []),
+ );
+ host.steers.settleApplied(
+ finalConvoId,
+ data.responseMessage ? [data.responseMessage] : undefined,
+ );
+ // Steers the run never injected ride the final event; convert them
+ // to queued follow-ups before the run-end signal fires the drain
+ // (also resets the applied-id set for the finished run).
+ // `claimParked` reconciles the replayable parked copy of the same
+ // steers; explicit dismissal or a persisted recovery removes it.
+ host.steers.convertToQueued(
+ finalConvoId,
+ (generationProtocolVersion === 1 || supportsGenerationProtocolV2(data)) &&
+ Array.isArray(data.pendingSteers)
+ ? (data.pendingSteers as TPendingSteer[]).filter(
+ (steer) =>
+ !finalAppliedSteerIds.has(steer.steerId) &&
+ (steer.clientSteerId == null || !finalAppliedSteerIds.has(steer.clientSteerId)),
+ )
+ : [],
+ {
+ claimParked: true,
+ generationProtocolVersion,
+ },
+ );
+ // A `failed` chip never reached the server, so it never rides
+ // `data.pendingSteers` above; without this it survives a NORMAL
+ // completion and renders (with a live Retry) under the NEXT run's
+ // reply. Idempotent alongside the call above: both dedupe by id.
+ host.steers.convertLocalToQueued(finalConvoId);
+ let finalHandled = false;
+ try {
+ host.events.finalHandler(data, sub.submission as EventSubmission);
+ finalHandled = true;
+ host.usage.finalizeUsage(data, sub.liveSubmission());
+ } catch (error) {
+ host.logger.error('ResumableSSE', 'Error in finalHandler:', error);
+ host.pane.setIsSubmitting(false);
+ host.pane.setShowStopButton(false);
+ }
+ // One-shot run-end signal for the queue drain. Written AFTER
+ // finalHandler so `isSubmitting` has flipped false by the time the
+ // drain effect observes it (both land in the same Recoil batch).
+ // An early-aborted FIRST turn keys under NEW_CONVO: finalHandler
+ // restored /c/new, so the optimistic id would strand the queue.
+ const runEndTarget = host.pane.runEndTarget({
+ conversationId: finalConvoId,
+ earlyAbort: data.earlyAbort === true,
+ startedAsNewConvo: run.optimisticStreamIds.has(currentStreamId),
+ });
+ let finalOutcome: 'completed' | 'aborted' | 'error' = 'error';
+ if (data.aborted === true || data.responseMessage?.unfinished === true) {
+ finalOutcome = 'aborted';
+ } else if (finalHandled) {
+ finalOutcome = 'completed';
+ }
+ host.pane.publishRunEnd({
+ conversationId: runEndTarget.conversationId,
+ // A Stop that lands before completion can arrive as a final with
+ // `unfinished: true` and no `aborted` flag (request.js's
+ // wasAbortedBeforeComplete branch); it must not auto-drain.
+ outcome: finalOutcome,
+ startedAsNewConvo: runEndTarget.startedAsNewConvo,
+ endedAt: run.scheduler.now(),
+ generationCreatedAt,
+ ...(data.responseMessage?.messageId != null && {
+ responseMessageId: data.responseMessage.messageId,
+ }),
+ });
+ // Clear handler maps on stream completion to prevent memory leaks
+ host.events.clearStepMaps();
+ // Optimistically remove from active jobs
+ host.cache.removeActiveJob(currentStreamId);
+ clearAttachedGenerationCreatedAt(ctx);
+ host.pane.refreshBalance();
+ sub.close();
+ host.pane.setStreamId(null);
+ run.releaseStream(currentStreamId);
+}
+
+/** The server named the turn: adopt its user message and the response placeholder under it. */
+function handleCreated(ctx: StreamContext, data: ChatCreatedFrame): void {
+ const { sub, host, patcher } = ctx;
+ const { run, generationCreatedAt, startedAsNewConversation } = sub;
+ const currentStreamId = sub.streamId;
+ host.logger.log('ResumableSSE', 'Received CREATED event', {
+ messageId: data.message?.messageId,
+ conversationId: data.message?.conversationId,
+ });
+ run.createdStreamIds.add(currentStreamId);
+ if (startedAsNewConversation) {
+ host.pane.setGenerationEpoch(Constants.NEW_CONVO, null, generationCreatedAt);
+ }
+ host.pane.renewActiveRun();
+ sub.userMessage = {
+ ...sub.userMessage,
+ ...data.message,
+ overrideParentMessageId: sub.userMessage.overrideParentMessageId,
+ };
+ const createdInitialResponse = buildCreatedInitialResponse({
+ initialResponse: sub.submission.initialResponse as TMessage,
+ userMessage: sub.userMessage,
+ isRegenerate: sub.submission.isRegenerate,
+ });
+ sub.replaceSubmission({
+ ...sub.submission,
+ userMessage: sub.userMessage,
+ initialResponse: createdInitialResponse,
+ });
+ run.identityConfirmed = true;
+ host.usage.bindResponse(sub.submission);
+ host.events.createdHandler(data, sub.submission as EventSubmission);
+ patcher.replayPreCreatedStepEvents();
+}
+
+/** Routes one stream frame to its handler, fenced by the subscription. */
+export async function handleFrame(ctx: StreamContext, event: ChatEvent): Promise<void> {
+ const { sub, host, patcher } = ctx;
+ const { run, isResume, generationProtocolVersion } = sub;
+ const currentStreamId = sub.streamId;
+ try {
+ if (!sub.isCurrent() || sub.finalReceived) {
+ return;
+ }
+
+ if (event.type === 'final' && event.data.reconcile === true) {
+ const { data } = event;
+ if (
+ generationProtocolVersion !== GENERATION_PROTOCOL_VERSION ||
+ !supportsGenerationProtocolV2(data)
+ ) {
+ host.logger.warn('ResumableSSE', 'Ignoring unnegotiated lifecycle reconciliation frame');
+ return;
+ }
+ // Synthesized lifecycle frames deliberately carry no ordinary
+ // response payload. Reconcile durable history (or hand off to a
+ // replacement epoch) instead of passing them to finalHandler.
+ sub.finalReceived = true;
+ run.cancelSteerRetryFrames();
+ void reconcileGenerationLifecycle(ctx, data);
+ return;
+ }
+
+ if (event.type === 'final') {
+ await handleFinal(ctx, event.data);
+ return;
+ }
+
+ if (event.type === 'created') {
+ handleCreated(ctx, event.data);
+ return;
+ }
+
+ if (event.type === 'attachment' && event.data) {
+ host.events.attachmentHandler({
+ data: event.data as TAttachment,
+ submission: sub.submission as EventSubmission,
+ });
+ return;
+ }
+
+ if (event.type === 'title') {
+ host.events.titleHandler(event.data);
+ return;
+ }
+
+ if (event.type === 'context_usage') {
+ host.usage.contextHandler(event.data, sub.liveSubmission());
+ return;
+ }
+
+ if (event.type === 'token_usage') {
+ host.usage.usageHandler(event.data, sub.liveSubmission());
+ return;
+ }
+
+ if (event.type === 'pending_action') {
+ patcher.applyPendingAction(event.data);
+ host.pane.setIsSubmitting(true);
+ return;
+ }
+
+ if (event.type === 'steer_applied') {
+ patcher.applySteer(event.data);
+ return;
+ }
+
+ if (event.type === 'steer_updated') {
+ host.steers.update(event.data);
+ return;
+ }
+
+ if (event.type === 'activity_label') {
+ patcher.applyActivityLabel(event.data);
+ return;
+ }
+
+ if (event.type === 'reasoning_label') {
+ patcher.applyReasoningLabel(event.data);
+ return;
+ }
+
+ if (event.type === 'step') {
+ const data = event.data as StepEvent;
+ if (
+ data.event === StepEvents.ON_MESSAGE_DELTA ||
+ data.event === StepEvents.ON_REASONING_DELTA
+ ) {
+ host.usage.tapStream(data.data, sub.liveSubmission());
+ }
+ if (!isResume && !run.createdStreamIds.has(currentStreamId)) {
+ if (isOAuthStepEvent(data)) {
+ sub.preCreatedStepEvents.push(data);
+ host.events.stepHandler(data, sub.liveSubmission() as EventSubmission);
+ return;
+ }
+ sub.preCreatedStepEvents.push(data);
+ return;
+ }
+ host.events.stepHandler(data, sub.liveSubmission() as EventSubmission);
+ return;
+ }
+
+ if (event.type === 'sync') {
+ handleSync(ctx, event.data);
+ return;
+ }
+
+ if (event.type === 'content') {
+ const { data } = event;
+ const { index } = data;
+ const text = 'text' in data ? data.text : undefined;
+ if (text != null && index !== sub.textIndex) {
+ sub.textIndex = index;
+ }
+ host.usage.tapContent(text, sub.liveSubmission());
+ host.events.contentHandler({ data, submission: sub.submission as EventSubmission });
+ return;
+ }
+
+ if (event.type === 'text') {
+ const { data } = event;
+ const text = data.text ?? data.response;
+ const initialResponse = {
+ ...(sub.submission.initialResponse as TMessage),
+ parentMessageId: data.parentMessageId,
+ messageId: data.messageId,
+ } as TMessage;
+ /** Legacy non-agent streams send cumulative text here; feed the
+ * live estimate like the content path above */
+ const textSubmission = {
+ ...sub.submission,
+ userMessage: sub.userMessage,
+ initialResponse,
+ };
+ sub.replaceSubmission(textSubmission);
+ host.usage.tapContent(text, textSubmission);
+ host.events.messageHandler(text, textSubmission);
+ }
+ } catch (error) {
+ host.logger.error('ResumableSSE', 'Error processing message:', error);
+ }
+}
+
+/**
+ * The transport emits `abort` only for this hook's own closes. A cancel
+ * the user agent issued (a backgrounded or frozen mobile tab, while the
+ * generation keeps running server-side) arrives as an `error` with status
+ * 0 instead, so it climbs the same reconnect ladder as any dropped
+ * connection rather than stranding the pane on its partial content.
+ */
+export function handleClose({ sub, host }: StreamContext): void {
+ const { run } = sub;
+ const currentStreamId = sub.streamId;
+ if (!sub.isCurrent()) {
+ return;
+ }
+
+ if (run.replacementHandoff) {
+ host.logger.log('ResumableSSE', 'Stream closed for generation handoff - preserving state');
+ return;
+ }
+ // If we're in a reconnection cycle, don't reset state
+ // (error handler will set up the reconnect timeout)
+ if (run.reconnectAttempt > 0) {
+ host.logger.log('ResumableSSE', 'Stream closed for reconnect - preserving state');
+ return;
+ }
+
+ host.logger.log('ResumableSSE', 'Stream aborted (intentional close) - no reconnect');
+ run.cancelSteerRetryFrames();
+ // Clear any pending reconnect attempts
+ run.clearReconnectTimeout();
+ // Reset UI state - useResumeOnLoad will restore if user returns to this conversation
+ host.pane.setIsSubmitting(false);
+ host.pane.setShowStopButton(false);
+ host.pane.setStreamId(null);
+ /** Intentional close without a final event (explicit stop, or navigation
+ * while generating): discard the in-flight pending usage so it can't
+ * merge into the next response in this conversation. On a resume the
+ * collected usage is re-folded via backfillUsage, so nothing is lost. */
+ host.events.resetLive(sub.liveSubmission());
+ // No final/error event fires on this path, so it's the only place left
+ // to sweep a local `failed` chip; otherwise it survives this close and
+ // renders (with a live Retry) under whatever run starts next. `pending`
+ // chips are deliberately left alone here: this listener also fires on
+ // navigation away while the run CONTINUES server-side, so a
+ // server-ACK'd `pending` steer is not stranded: the server injects it
+ // regardless, and sweeping it into the queue too would resend the same
+ // words as a duplicate turn once `useQueueDrain` fires at run end.
+ host.steers.convertLocalToQueued(sub.submission.conversation?.conversationId ?? currentStreamId, {
+ statuses: ABORT_SWEEP_STATUSES,
+ });
+}
diff --git a/packages/chat/src/core/resumable/host.ts b/packages/chat/src/core/resumable/host.ts
index d7b886b730..c1fa5df2bc 100644
--- a/packages/chat/src/core/resumable/host.ts
+++ b/packages/chat/src/core/resumable/host.ts
@@ -4,7 +4,16 @@ import type {
TSubmission,
TConversation,
TPendingSteer,
+ TAttachment,
+ ChatTransport,
+ ChatTitleFrame,
+ ChatFinalFrame,
EventSubmission,
+ ChatCreatedFrame,
+ ChatContentFrame,
+ TTokenUsageEvent,
+ TContextUsageEvent,
+ TSteerUpdatedEvent,
TSteerAppliedEvent,
TActivityLabelEvent,
TReasoningLabelEvent,
@@ -116,6 +125,8 @@ export interface ResumableSteers {
) => string[];
/** Marks the steer whose inline part just mounted, so it plays its draw-in once. */
markLiveApplied: (steerId: string) => void;
+ /** Patches the chips the server re-labelled (preempt capability); never removes one. */
+ update: (event: TSteerUpdatedEvent) => void;
/** Re-seeds the chips from the server's still-queued steers. */
seed: (
conversationId: string,
@@ -196,6 +207,15 @@ export interface ResumablePane {
clearDrainAfterAbort: (conversationId: string, generationCreatedAt?: number) => void;
/** Refreshes the token balance, when the deployment tracks one. */
refreshBalance: () => void;
+ setAbortScroll: (abort: boolean) => void;
+ /** Starts a new identity for the run the pane displays (a `created` or resume `sync`). */
+ renewActiveRun: () => void;
+ /** Where a run's end lands: an early-aborted first turn keys under the new-chat id. */
+ runEndTarget: (params: {
+ conversationId: string;
+ earlyAbort: boolean;
+ startedAsNewConvo: boolean;
+ }) => { conversationId: string; startedAsNewConvo: boolean };
/** Updates the pane's conversation; absent for a pane that only adds a comparison response. */
updateConversation?: (update: (current: TConversation | null) => TConversation | null) => void;
/**
@@ -211,6 +231,16 @@ export interface ResumablePane {
/** What the event handlers that render the stream expose to the run. */
export interface ResumableEvents {
stepHandler: (event: StepEvent, submission: EventSubmission) => void;
+ finalHandler: (data: ChatFinalFrame, submission: EventSubmission) => void;
+ createdHandler: (data: ChatCreatedFrame, submission: EventSubmission) => void;
+ attachmentHandler: (params: { data: TAttachment; submission: EventSubmission }) => void;
+ titleHandler: (data: ChatTitleFrame) => void;
+ contentHandler: (params: { data: ChatContentFrame; submission: EventSubmission }) => void;
+ /** Legacy streams' cumulative text. */
+ messageHandler: (text: string | undefined, submission: EventSubmission) => void;
+ /** Marks programmatic tool calls a resume cannot rebuild as interrupted. */
+ prunePtcTraces: () => void;
+ resetContentHandler: () => void;
/** Replaces the step handler's copy of a message the run patched outside it. */
syncStepMessage: (message: TMessage) => void;
clearStepMaps: () => void;
@@ -221,6 +251,19 @@ export interface ResumableEvents {
showError: (text: string | boolean | { message?: string }, submission: TSubmission) => void;
}
+/** The run's token usage: the live estimate while it streams and the totals it settles to. */
+export interface ResumableUsage {
+ bindResponse: (submission: TSubmission) => void;
+ contextHandler: (data: TContextUsageEvent, submission: TSubmission) => void;
+ usageHandler: (data: TTokenUsageEvent, submission: TSubmission) => void;
+ tapStream: (data: { delta?: { content?: unknown } }, submission: TSubmission) => void;
+ tapContent: (text: unknown, submission: TSubmission) => void;
+ finalizeUsage: (data: ChatFinalFrame, submission: TSubmission) => void;
+ backfillUsage: (entries: TTokenUsageEvent[], submission: TSubmission) => void;
+ /** Seeds the live estimate with the output a resume snapshot already holds. */
+ seedLiveFromContent: (content: unknown[] | undefined, submission: TSubmission) => void;
+}
+
/** The pane's message list. */
export interface ResumableMessages {
get: () => TMessage[] | undefined;
@@ -262,4 +305,9 @@ export interface ResumableHost extends SubscriptionHost {
events: ResumableEvents;
messages: ResumableMessages;
parts: ResumableParts;
+ usage: ResumableUsage;
+ /** The stream side of the app's transport, bound to the signed-in user. */
+ stream: ChatTransport;
+ /** Receives the dev-only controls that simulate a dropped or a clean close. */
+ exposeDebugControls?: (controls: { killNetwork: () => void; closeClean: () => void }) => void;
}
diff --git a/packages/chat/src/core/resumable/index.ts b/packages/chat/src/core/resumable/index.ts
index 028a9c2508..7c1b1a400c 100644
--- a/packages/chat/src/core/resumable/index.ts
+++ b/packages/chat/src/core/resumable/index.ts
@@ -12,3 +12,6 @@ export * from './failure';
export * from './missing';
export * from './ceiling';
export * from './patches';
+export * from './frames';
+export * from './sync';
+export * from './attach';
diff --git a/packages/chat/src/core/resumable/sync.ts b/packages/chat/src/core/resumable/sync.ts
new file mode 100644
index 0000000000..2cfa28913e
--- /dev/null
+++ b/packages/chat/src/core/resumable/sync.ts
@@ -0,0 +1,350 @@
+import {
+ StepEvents,
+ UsageEvents,
+ SteerEvents,
+ ApprovalEvents,
+ ActivityLabelEvents,
+ ReasoningLabelEvents,
+} from 'librechat-data-provider';
+import type {
+ Agents,
+ TMessage,
+ ChatSyncFrame,
+ TPendingSteer,
+ TTokenUsageEvent,
+ TContextUsageEvent,
+ TSteerAppliedEvent,
+ TSteerUpdatedEvent,
+ TActivityLabelEvent,
+ TReasoningLabelEvent,
+} from 'librechat-data-provider';
+import type { StreamContext } from './terminal';
+import type { StepEvent } from '../reducer';
+import { getResumeMessageIndexes, buildResumeEventSubmission, mergeResumeMessages } from './resume';
+import { getStepEventId, isOAuthStepEvent } from './events';
+import { preferDefinedString } from './messages';
+
+/**
+ * A resume's snapshot of the run: adopts the server's identity for the turn, rebuilds the
+ * response from the aggregated content, re-applies pending prompts, steers and labels, and
+ * replays the events the snapshot did not cover.
+ */
+export function handleSync(ctx: StreamContext, data: ChatSyncFrame): void {
+ const { sub, host, patcher } = ctx;
+ const { run, generationCreatedAt, generationProtocolVersion } = sub;
+ const currentStreamId = sub.streamId;
+ host.logger.log('ResumableSSE', 'SYNC received', {
+ runSteps: data.resumeState?.runSteps?.length ?? 0,
+ pendingEvents: data.pendingEvents?.length ?? 0,
+ });
+
+ host.pane.renewActiveRun();
+ /** Keep the current run's preliminary id long enough to replace that optimistic
+ * row in place if this snapshot assigns its durable response id. */
+ const preliminaryResponseMessageId = sub.submission.initialResponse?.messageId;
+ const currentUserMessageId = sub.submission.userMessage?.messageId;
+ const preliminaryUserMessageId =
+ currentUserMessageId &&
+ (sub.submission.initialResponse?.parentMessageId === currentUserMessageId ||
+ preliminaryResponseMessageId === `${currentUserMessageId}_`)
+ ? currentUserMessageId
+ : undefined;
+ const resumeSubmission = buildResumeEventSubmission(
+ sub.submission,
+ sub.userMessage,
+ data.resumeState,
+ );
+ sub.replaceSubmission(resumeSubmission);
+ sub.userMessage = resumeSubmission.userMessage;
+ if (data.resumeState?.userMessage != null) {
+ run.identityConfirmed = true;
+ }
+ /**
+ * Totals rebuild from the persisted backfill at sync. Replayed or
+ * gap usage events already represented in the snapshot are skipped
+ * via multiset matching; events that raced past the snapshot read
+ * still fold so multi-call runs don't undercount.
+ */
+ /** Fold the run's persisted usage; events also replayed below are
+ * deduped by (runId, seq) inside the handler, so prior prompts in
+ * this conversation keep their usage and gap events still count */
+ host.usage.backfillUsage(data.resumeState?.collectedUsage ?? [], resumeSubmission);
+ if (data.resumeState?.contextUsage) {
+ /** Already reconciled to the call's real prompt tokens server-side
+ * (GenerationJobManager.persistTokenUsage) when the snapshot's call
+ * completed, so install it as-is: no client backfill reconcile. */
+ host.usage.contextHandler(data.resumeState.contextUsage, resumeSubmission);
+ }
+ /** Output streamed before this resume is not re-delivered as deltas;
+ * estimate it from the trailing aggregated content. This is
+ * needed even with a snapshot: the snapshot is pre-invoke, so the
+ * in-flight output it precedes rides on the live estimate.
+ * Only output at the very end counts (0
+ * when paused at a tool call), so a snapshot's budget is never
+ * double-counted. */
+ host.usage.seedLiveFromContent(data.resumeState?.aggregatedContent, resumeSubmission);
+
+ const pendingOAuthPrompts = data.resumeState?.pendingOAuthPrompts ?? [];
+ const pendingOAuthStepIds = new Set(pendingOAuthPrompts.map((prompt) => prompt.stepId));
+ if (data.resumeState?.runSteps) {
+ for (const runStep of data.resumeState.runSteps) {
+ if (pendingOAuthStepIds.has(runStep.id)) {
+ continue;
+ }
+ host.events.stepHandler({ event: StepEvents.ON_RUN_STEP, data: runStep }, resumeSubmission);
+ }
+ }
+
+ if (data.resumeState?.aggregatedContent && sub.userMessage?.messageId) {
+ const messages = host.messages.get() ?? [];
+ const userMsgId = sub.userMessage.messageId;
+ const hasResumedContent = data.resumeState.aggregatedContent.length > 0;
+ const responseId = resumeSubmission.initialResponse.messageId;
+ const messageIndexes = getResumeMessageIndexes(
+ messages,
+ userMsgId,
+ responseId,
+ preliminaryUserMessageId,
+ preliminaryResponseMessageId,
+ );
+ const responseIdx =
+ messageIndexes.responseIndex >= 0
+ ? messageIndexes.responseIndex
+ : messageIndexes.preliminaryResponseIndex;
+
+ host.logger.log('ResumableSSE', 'SYNC update', {
+ userMsgId,
+ responseId,
+ responseIdx,
+ foundMessageId: responseIdx >= 0 ? messages[responseIdx]?.messageId : null,
+ messagesCount: messages.length,
+ aggregatedContentLength: data.resumeState.aggregatedContent?.length,
+ });
+
+ if (responseIdx >= 0) {
+ const oldContent = messages[responseIdx]?.content;
+ /** An EMPTY resume snapshot is not authoritative over content we already loaded
+ * for the SAME generation-owned response: assigning it would erase that content
+ * and leave a bare cursor. Require an existing content array so it is never
+ * swapped for `undefined`. */
+ const preserveLoadedContent =
+ !hasResumedContent && Array.isArray(oldContent) && oldContent.length > 0;
+ /**
+ * Replacing the response with `aggregatedContent` drops the
+ * prefix an edited resubmission had retained: the snapshot is
+ * completion-local, indexed from zero. Every later event must
+ * therefore stop offsetting, or it writes past the end of the
+ * shorter array: for an activity label that means the fill
+ * misses its own reservation and the placeholder never
+ * resolves. Preserving `oldContent` keeps the prefix, and with
+ * it the offset. Run steps and labels both read this.
+ */
+ if (!preserveLoadedContent) {
+ run.editPrefixCleared = true;
+ }
+ const responseMessage = {
+ ...resumeSubmission.initialResponse,
+ ...messages[responseIdx],
+ messageId: responseId,
+ parentMessageId: userMsgId,
+ content: preserveLoadedContent ? oldContent : data.resumeState.aggregatedContent,
+ sender: messages[responseIdx]?.sender ?? resumeSubmission.initialResponse.sender,
+ iconURL: preferDefinedString(
+ messages[responseIdx]?.iconURL,
+ resumeSubmission.initialResponse.iconURL ?? data.resumeState.iconURL,
+ ),
+ model: preferDefinedString(
+ messages[responseIdx]?.model,
+ resumeSubmission.initialResponse.model ?? data.resumeState.model,
+ ),
+ } as TMessage;
+ const updated = mergeResumeMessages(
+ messages,
+ sub.userMessage,
+ responseMessage,
+ messageIndexes,
+ resumeSubmission.compact === true,
+ );
+ host.logger.log('ResumableSSE', 'SYNC updating message', {
+ messageId: responseMessage.messageId,
+ oldContentLength: Array.isArray(oldContent) ? oldContent.length : 0,
+ newContentLength: data.resumeState.aggregatedContent?.length,
+ preservedExistingContent: preserveLoadedContent,
+ });
+ host.messages.set(updated);
+ host.events.resetContentHandler();
+ host.events.syncStepMessage(responseMessage);
+ host.logger.log('ResumableSSE', 'SYNC complete, handlers synced');
+ } else {
+ /** Same reasoning as the matched branch above: this row is
+ * built straight from the server's completion-local
+ * `aggregatedContent`, so it holds no retained prefix and
+ * later steps and labels must stop offsetting. Setting it
+ * only in the matched branch left this path adding an offset
+ * to indices that were already absolute. */
+ run.editPrefixCleared = true;
+ const newMessage = {
+ ...resumeSubmission.initialResponse,
+ messageId: responseId,
+ parentMessageId: userMsgId,
+ content: data.resumeState.aggregatedContent,
+ isCreatedByUser: false,
+ } as TMessage;
+ host.messages.set(
+ mergeResumeMessages(
+ messages,
+ sub.userMessage,
+ newMessage,
+ messageIndexes,
+ resumeSubmission.compact === true,
+ ),
+ );
+ host.events.resetContentHandler();
+ host.events.syncStepMessage(newMessage);
+ }
+ }
+
+ for (const prompt of pendingOAuthPrompts) {
+ patcher.applyPendingOAuthPrompt(prompt, resumeSubmission);
+ }
+
+ /**
+ * Re-pause on reconnect: the run is parked on a human-review
+ * interrupt. Re-apply the pending action so the approval / ask-user
+ * controls render after a reload or dropped connection.
+ */
+ if (data.resumeState?.pendingAction) {
+ patcher.applyPendingAction(data.resumeState.pendingAction as Agents.PendingAction);
+ }
+
+ /**
+ * Re-seed steer chips from the server's still-queued steers.
+ * Injected steers are already inside `aggregatedContent`, so this
+ * covers exactly the remainder a reloading client can't know about.
+ */
+ // Always reconcile against the server's still-queued list: a steer
+ // applied while this client was disconnected is absent here (its
+ // inline part rides aggregatedContent instead), so an EMPTY list
+ // must clear stale local pending chips, not leave them stranded.
+ const steerConvoId = sub.submission.conversation?.conversationId ?? currentStreamId;
+ host.steers.seed(
+ steerConvoId,
+ (data.resumeState?.pendingSteers ?? []) as TPendingSteer[],
+ generationCreatedAt,
+ generationProtocolVersion,
+ );
+ // Seed first, then remove anything already represented in the
+ // authoritative content. Reversing this order can re-mint a stale
+ // server snapshot entry after it was just settled.
+ host.steers.settleApplied(
+ steerConvoId,
+ data.resumeState?.aggregatedContent as unknown[] | undefined,
+ );
+
+ if (data.resumeState?.titleEvent) {
+ host.events.titleHandler(data.resumeState.titleEvent);
+ }
+
+ /** PTC inner calls are not content parts, so the resume snapshot
+ * can't rebuild them and a settling event lost in this gap is
+ * never replayed. Mark rows still `running` as interrupted rather
+ * than leave a spinner that never resolves, and rather than drop
+ * them, since a call still executing across the reconnect settles
+ * normally on the restored stream and updates its row in place. */
+ host.events.prunePtcTraces();
+
+ const replayEvents = data.resumeState?.replayEvents ?? [];
+ if (replayEvents.length > 0) {
+ host.logger.log('ResumableSSE', `Replaying ${replayEvents.length} resume events`);
+ for (const replayEvent of replayEvents) {
+ const replayStepId = getStepEventId(replayEvent);
+ if (
+ replayStepId != null &&
+ pendingOAuthStepIds.has(replayStepId) &&
+ isOAuthStepEvent(replayEvent)
+ ) {
+ continue;
+ }
+ if (replayEvent.event === UsageEvents.ON_CONTEXT_USAGE) {
+ host.usage.contextHandler(replayEvent.data as TContextUsageEvent, resumeSubmission);
+ } else if (replayEvent.event === UsageEvents.ON_TOKEN_USAGE) {
+ host.usage.usageHandler(replayEvent.data as TTokenUsageEvent, resumeSubmission);
+ } else if (replayEvent.event === ApprovalEvents.ON_PENDING_ACTION) {
+ // A pause that landed after the resume snapshot must still render its
+ // controls (mirror the live handler), not fall through to stepHandler.
+ patcher.applyPendingAction(replayEvent.data as Agents.PendingAction);
+ } else if (replayEvent.event === SteerEvents.ON_STEER_APPLIED) {
+ patcher.applySteer(replayEvent.data as TSteerAppliedEvent);
+ } else if (replayEvent.event === SteerEvents.ON_STEER_UPDATED) {
+ host.steers.update(replayEvent.data as TSteerUpdatedEvent);
+ } else if (replayEvent.event === ActivityLabelEvents.ON_ACTIVITY_LABEL) {
+ patcher.applyActivityLabel(replayEvent.data as TActivityLabelEvent);
+ } else if (replayEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL) {
+ patcher.applyReasoningLabel(replayEvent.data as TReasoningLabelEvent);
+ } else if (replayEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL_ATTEMPT) {
+ // Durable provider-call budget reservations never render.
+ } else if (replayEvent.event != null) {
+ if (
+ replayEvent.event === StepEvents.ON_MESSAGE_DELTA ||
+ replayEvent.event === StepEvents.ON_REASONING_DELTA
+ ) {
+ host.usage.tapStream(replayEvent.data as Agents.MessageDeltaEvent, resumeSubmission);
+ }
+ host.events.stepHandler(replayEvent as StepEvent, resumeSubmission);
+ }
+ }
+ }
+
+ const pendingEvents = data.pendingEvents ?? [];
+ if (pendingEvents.length > 0) {
+ host.logger.log('ResumableSSE', `Replaying ${pendingEvents.length} pending events`);
+ for (const pendingEvent of pendingEvents) {
+ if (!('event' in pendingEvent)) {
+ if ('type' in pendingEvent) {
+ /** Gap output streamed past the resume snapshot must reach the
+ * live estimate too, not just the message UI */
+ host.usage.tapContent(
+ 'text' in pendingEvent ? pendingEvent.text : undefined,
+ resumeSubmission,
+ );
+ host.events.contentHandler({ data: pendingEvent, submission: resumeSubmission });
+ }
+ continue;
+ }
+ if (pendingEvent.event === 'title') {
+ host.events.titleHandler(pendingEvent);
+ } else if (pendingEvent.event === UsageEvents.ON_CONTEXT_USAGE) {
+ host.usage.contextHandler(pendingEvent.data, resumeSubmission);
+ } else if (pendingEvent.event === UsageEvents.ON_TOKEN_USAGE) {
+ host.usage.usageHandler(pendingEvent.data, resumeSubmission);
+ } else if (pendingEvent.event === ApprovalEvents.ON_PENDING_ACTION) {
+ // In-memory mode can surface a pause that landed between getResumeState()
+ // and the subscription here; route it to the same handler as a live event
+ // so the approval / ask-user controls render (else the stream sits paused
+ // with no UI until a full status reload).
+ patcher.applyPendingAction(pendingEvent.data as Agents.PendingAction);
+ } else if (pendingEvent.event === SteerEvents.ON_STEER_APPLIED) {
+ patcher.applySteer(pendingEvent.data as TSteerAppliedEvent);
+ } else if (pendingEvent.event === SteerEvents.ON_STEER_UPDATED) {
+ host.steers.update(pendingEvent.data as TSteerUpdatedEvent);
+ } else if (pendingEvent.event === ActivityLabelEvents.ON_ACTIVITY_LABEL) {
+ patcher.applyActivityLabel(pendingEvent.data as TActivityLabelEvent);
+ } else if (pendingEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL) {
+ patcher.applyReasoningLabel(pendingEvent.data as TReasoningLabelEvent);
+ } else if (pendingEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL_ATTEMPT) {
+ // Durable provider-call budget reservations never render.
+ } else if (pendingEvent.event != null) {
+ if (
+ pendingEvent.event === StepEvents.ON_MESSAGE_DELTA ||
+ pendingEvent.event === StepEvents.ON_REASONING_DELTA
+ ) {
+ host.usage.tapStream(pendingEvent.data, resumeSubmission);
+ }
+ host.events.stepHandler(pendingEvent as StepEvent, resumeSubmission);
+ }
+ }
+ }
+
+ host.pane.setIsSubmitting(true);
+ host.pane.setShowStopButton(generationCreatedAt != null);
+}
diff --git a/packages/chat/src/core/resumable/terminal.ts b/packages/chat/src/core/resumable/terminal.ts
index 9f56b0f52b..78a706ce3d 100644
--- a/packages/chat/src/core/resumable/terminal.ts
+++ b/packages/chat/src/core/resumable/terminal.ts
@@ -3,6 +3,7 @@ import type { Agents, TPendingSteer } from 'librechat-data-provider';
import type { ResumableHost, StreamStatusResponse } from './host';
import type { GenerationProtocolVersion } from '../protocol';
import type { ResumableSubscription } from './subscription';
+import type { ResponsePatcher } from './patches';
import { GENERATION_PROTOCOL_VERSION, supportsGenerationProtocolV2 } from '../protocol';
/** One subscription's terminal handling: the attachment, the app around it, and how a pending
@@ -13,6 +14,11 @@ export interface TerminalContext {
applyPendingAction: (action: Agents.PendingAction) => void;
}
+/** A subscription's terminal handling, plus the patcher that lands its side events. */
+export interface StreamContext extends TerminalContext {
+ patcher: ResponsePatcher;
+}
+
/**
* Terminal handlers are fenced by this subscription and its generation. Clear every key the
* same run may have occupied, including the temporary new-chat key, so aborts and resumes from