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: Give the Resumable Stream a Core Run and Subscription (#17117)

Marco Beretta5364225d0cd2
diff --git a/client/src/data-provider/SSE/protocol.ts b/client/src/data-provider/SSE/protocol.ts
index f9082deff2..e4adadbb52 100644
--- a/client/src/data-provider/SSE/protocol.ts
+++ b/client/src/data-provider/SSE/protocol.ts
@@ -1,17 +1,14 @@
import { request } from 'librechat-data-provider';
-import { GENERATION_PROTOCOL_VERSION } from '@librechat/chat';
+import { GENERATION_PROTOCOL_VERSION, generationProtocolHeaders } from '@librechat/chat';
export {
+ GENERATION_PROTOCOL_HEADER,
GENERATION_PROTOCOL_VERSION,
+ generationProtocolHeaders,
getGenerationProtocolVersion,
supportsGenerationProtocolV2,
} from '@librechat/chat';
export type { GenerationProtocolVersion } from '@librechat/chat';
-export const GENERATION_PROTOCOL_HEADER = 'X-LibreChat-Generation-Protocol';
-
-export const generationProtocolHeaders = (): Record<string, string> => ({
- [GENERATION_PROTOCOL_HEADER]: String(GENERATION_PROTOCOL_VERSION),
-});
export const withGenerationProtocolQuery = (url: string): string =>
`${url}${url.includes('?') ? '&' : '?'}generationProtocolVersion=${GENERATION_PROTOCOL_VERSION}`;
diff --git a/client/src/data-provider/SSE/queries.ts b/client/src/data-provider/SSE/queries.ts
index e3048181ed..87d860f1b8 100644
--- a/client/src/data-provider/SSE/queries.ts
+++ b/client/src/data-provider/SSE/queries.ts
@@ -1,7 +1,8 @@
import { useEffect, useMemo, useState } from 'react';
import { useQuery, useQueries, useQueryClient } from '@tanstack/react-query';
import { apiBaseUrl, QueryKeys, request, dataService } from 'librechat-data-provider';
-import type { Agents, TConversation, TPendingSteer } from 'librechat-data-provider';
+import type { TConversation } from 'librechat-data-provider';
+import type { StreamStatusResponse } from '@librechat/chat';
import {
isNotFoundError,
updateConvoInAllQueries,
@@ -11,32 +12,7 @@ import {
import { generationProtocolHeaders, withGenerationProtocolQuery } from './protocol';
import { useGetStartupConfig } from '../Endpoints';
-export interface StreamStatusResponse {
- /** Exact protocol selected by the job. Missing/1 is always legacy. */
- generationProtocolVersion?: number;
- active: boolean;
- /** Client-local cache marker used to force useResumeOnLoad to replace a
- * stale generation attachment with the newer epoch occupying this stream. */
- generationHandoff?: boolean;
- streamId?: string;
- status?: 'running' | 'complete' | 'error' | 'aborted' | 'requires_action';
- aggregatedContent?: Array<{ type: string; text?: string }>;
- createdAt?: number;
- /** Generation age computed on the server's clock, so a reattaching client
- * can rebuild a clock-local elapsed baseline free of cross-machine skew. */
- elapsedMs?: number;
- resumeState?: Agents.ResumeState;
- /** The run's temporary state as the server recorded it at admission, so a rebuilt
- * submission keeps a hidden chat out of history and titling after a reload. */
- isTemporary?: boolean;
- /** Live pending approval when `status === 'requires_action'`; mirrors
- * `resumeState.pendingAction`, surfaced top-level for the resume-on-load path. */
- pendingAction?: Agents.PendingAction;
- /** Acknowledged steers a terminal drain parked because no subscriber was
- * live for the final/abort event. Reads are replayable until an exact
- * recovery turn persists or the user discards the item. */
- unrecoveredSteers?: TPendingSteer[];
-}
+export type { StreamStatusResponse } from '@librechat/chat';
export const streamStatusQueryKey = (conversationId: string) => ['streamStatus', conversationId];
diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.ts
index 43a9589526..cbcf05a2b1 100644
--- a/client/src/hooks/SSE/useResumableSSE.ts
+++ b/client/src/hooks/SSE/useResumableSSE.ts
@@ -11,7 +11,6 @@ import {
ErrorTypes,
StepEvents,
StepTypes,
- apiBaseUrl,
SteerEvents,
dataService,
ContentTypes,
@@ -63,6 +62,9 @@ import {
getStartGenerationConversationId,
getPredecessorMismatchStartResponse,
START_GENERATION_READINESS_TIMEOUT_MS,
+ ResumableRun,
+ documentVisibility,
+ ResumableSubscription,
} from '@librechat/chat';
import type {
Agents,
@@ -81,9 +83,12 @@ import type {
TAttachment,
TTokenUsageEvent,
TContextUsageEvent,
- ChatStreamConnection,
} from 'librechat-data-provider';
-import type { GenerationProtocolVersion, StartGenerationResult } from '@librechat/chat';
+import type {
+ 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';
@@ -124,7 +129,6 @@ import {
useGetStartupConfig,
queueTitleGeneration,
streamStatusQueryKey,
- generationProtocolHeaders,
fetchConversationMessages,
} from '~/data-provider';
import {
@@ -206,6 +210,7 @@ export default function useResumableSSE(
isAddedRequest = false,
runIndex = 0,
) {
+ const [run] = useState(() => new ResumableRun());
const jotaiStore = useStore();
const localize = useLocalize();
const queryClient = useQueryClient();
@@ -283,47 +288,6 @@ export default function useResumableSSE(
const setShowStopButton = useSetAtom(showStopButtonByIndex(runIndex));
const setLiveAppliedSteerIds = useSetAtom(liveAppliedSteerIdsAtom);
- const streamRef = useRef<AbortController | null>(null);
- /** Removes the foreground re-attach listener owned by the newest
- * subscription; exactly one is registered at a time. */
- const stopForegroundReattachRef = useRef<(() => void) | null>(null);
- const reconnectAttemptRef = useRef(0);
- const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
- const submissionRef = useRef<TSubmission | null>(null);
- /** Suppresses the normal close/cleanup idle transition while a stale
- * generation is being atomically handed off to its live replacement. */
- const replacementHandoffRef = useRef(false);
- const optimisticStreamIdsRef = useRef(new Set<string>());
- const createdStreamIdsRef = useRef(new Set<string>());
- /** Pending action whose tool-call content part hasn't rendered yet, retried
- * on the next frame so a fast pause-before-render race still attaches. */
- const pendingActionRetryRef = useRef<number | null>(null);
- /** EVERY steer retry frame, not only the newest one. Several steers can be
- * applied before their shared response placeholder renders; retaining one
- * handle let the older chains outlive navigation/terminal cleanup and
- * mutate a later generation that reused the same response id. */
- const steerRetryFramesRef = useRef<Set<number>>(new Set());
- /** EVERY outstanding label-retry frame, not a single handle: labels fire
- * two events per slot (reservation, then fill), so concurrent retry
- * chains are the norm: a single ref would let cleanup cancel only the
- * newest chain while the others kept running for up to 120 frames and
- * could apply a stale label to a replacement generation that reuses the
- * same response id (edits do). */
- const activityLabelRetryFramesRef = useRef<Set<number>>(new Set());
- /**
- * Set once a SYNC has replaced the response with the server's
- * completion-local snapshot, which discards the prefix an edited
- * resubmission retained. From that point incoming indices are absolute and
- * `editPrefixLength` must no longer be applied, by run steps or labels.
- */
- const editPrefixClearedRef = useRef(false);
- const editPrefixFirstPartFoldedRef = useRef(false);
- /** Generation the cleared-prefix state above belongs to, so it is dropped
- * when a new generation starts rather than when a subscribe happens to be
- * live. Keyed by response message id: the stream id is the conversation
- * id and is therefore shared by every generation within it. */
- const prefixStateGenerationIdRef = useRef<string | null>(null);
-
const restoreQueuedSubmission = useCallback(
(failedSubmission: TSubmission, expectedPredecessorCreatedAt?: number) => {
const conversationId = failedSubmission.conversation?.conversationId;
@@ -350,19 +314,10 @@ export default function useResumableSSE(
updateActiveGenerationCreatedAt,
} = useSteerState();
- /** The generation epoch the pane's stream is attached to, kept so a run left mid-stream can
- * carry it. A server that reports no epoch leaves it unset. */
- const subscribedEpochRef = useRef<number | null>(null);
const publishRunEnd = useSetAtom(runEndByIndex(runIndex));
- /** Whether the current submission's run end already reached the queue drain. A run that
- * ended attached must not also be resolved as detached when the user later leaves. */
- const runEndPublishedRef = useRef(false);
- /** Whether the server named the current submission's user message (`created`, or a resume's
- * sync). Only a run whose identity it confirmed is remembered when the user leaves. */
- const identityConfirmedRef = useRef(false);
const setRunEnd = useCallback(
(end: RunEnd, options?: { retainDetached?: boolean }) => {
- runEndPublishedRef.current = true;
+ run.runEndPublished = true;
/** The run's end reached the drain here, so a marker this pane left for the same run is
* settled and must not be resolved a second time on a later visit. A provisional end that
* cannot drain the queue keeps the marker, so a later read of history can still settle it. */
@@ -379,7 +334,7 @@ export default function useResumableSSE(
}
publishRunEnd(end);
},
- [jotaiStore, publishRunEnd],
+ [jotaiStore, publishRunEnd, run],
);
const setDrainAfterAbort = useSetAtom(drainAfterAbortByIndex(runIndex));
const clearDrainAfterAbort = useCallback(
@@ -434,15 +389,15 @@ export default function useResumableSSE(
*/
const stepHandler = useCallback(
(...[event, submission]: Parameters<typeof rawStepHandler>) => {
- const eventSubmission = editPrefixClearedRef.current
+ const eventSubmission = run.editPrefixCleared
? ({ ...submission, editPrefixCleared: true } as EventSubmission)
: submission;
rawStepHandler(event, eventSubmission);
if (eventSubmission.editPrefixFirstPartFolded === true) {
- editPrefixFirstPartFoldedRef.current = true;
+ run.editPrefixFirstPartFolded = true;
}
},
- [rawStepHandler],
+ [rawStepHandler, run],
);
const { data: startupConfig } = useGetStartupConfig();
@@ -467,25 +422,29 @@ export default function useResumableSSE(
* @param isResume - If true, adds ?resume=true to trigger sync event from server
*/
const subscribeToStream = useCallback(
- (
- currentStreamId: string,
- currentSubmission: TSubmission,
- isResume = false,
- generationCreatedAt?: number,
- generationProtocolVersion: GenerationProtocolVersion = 1,
- lifecycleSignal?: AbortSignal,
- ) => {
- /** Every effect owns one AbortSignal, while every reconnect owns one SSE
- * instance. Both identities matter: cleanup can close an attachment after
- * its async listener has already crossed an `await`, and a reconnect can
- * supersede an older attachment without changing the submission object.
- * The captured submission check is the final fence against a later
- * conversation installing its own submission in this pane. */
- if (lifecycleSignal?.aborted || submissionRef.current !== currentSubmission) {
+ (target: SubscriptionTarget) => {
+ /** See `ResumableSubscription.isCurrent` for the fences every callback below checks. */
+ if (target.signal?.aborted || run.submission !== target.submission) {
return;
}
- subscribedEpochRef.current = generationCreatedAt ?? null;
- const startedAsNewConversation = optimisticStreamIdsRef.current.has(currentStreamId);
+ const sub = new ResumableSubscription(
+ run,
+ {
+ logger,
+ visibility: documentVisibility,
+ fetchStatus: fetchStreamStatus,
+ subscribe: (next) => subscribeToStream(next),
+ },
+ target,
+ );
+ const {
+ streamId: currentStreamId,
+ isResume,
+ generationCreatedAt,
+ generationProtocolVersion,
+ startedAsNewConversation,
+ } = sub;
+ run.subscribedEpoch = generationCreatedAt ?? null;
/** Terminal handlers below 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 another tab cannot leave a stale
@@ -494,8 +453,8 @@ export default function useResumableSSE(
const conversationIds = new Set<string>([
currentStreamId,
...(conversationId ? [conversationId] : []),
- ...(currentSubmission.conversation?.conversationId
- ? [currentSubmission.conversation.conversationId]
+ ...(sub.submission.conversation?.conversationId
+ ? [sub.submission.conversation.conversationId]
: []),
...(startedAsNewConversation ? [String(Constants.NEW_CONVO)] : []),
]);
@@ -557,32 +516,18 @@ export default function useResumableSSE(
* reconnects".
*/
const generationId =
- currentSubmission.clientRequestId ??
- (currentSubmission.initialResponse as TMessage | undefined)?.messageId ??
+ sub.submission.clientRequestId ??
+ (sub.submission.initialResponse as TMessage | undefined)?.messageId ??
currentStreamId;
- if (prefixStateGenerationIdRef.current !== generationId) {
- prefixStateGenerationIdRef.current = generationId;
- editPrefixClearedRef.current = false;
- editPrefixFirstPartFoldedRef.current = false;
- }
- bindResponse(currentSubmission);
- let { userMessage } = currentSubmission;
- let textIndex: number | null = null;
- let finalReceived = false;
- /** This subscription must never be revived. Set by the terminal
- * recoveries that do not ride a FINAL or served-error frame — the 404
- * and retry-ceiling reconciles both leave the attachment pointing at a
- * stream the server no longer has — and by the dev-only navigation
- * simulator below. `finalReceived` covers the frame-carried terminals. */
- let subscriptionRetired = false;
- const preCreatedStepEvents: StepEvent[] = [];
+ run.bindPrefixState(generationId);
+ bindResponse(sub.submission);
const replayPreCreatedStepEvents = () => {
- if (!isCurrentSubscription() || preCreatedStepEvents.length === 0) {
+ if (!sub.isCurrent() || sub.preCreatedStepEvents.length === 0) {
return;
}
- const submission = { ...currentSubmission, userMessage } as EventSubmission;
- for (const event of preCreatedStepEvents.splice(0)) {
+ const submission = sub.liveSubmission() as EventSubmission;
+ for (const event of sub.preCreatedStepEvents.splice(0)) {
stepHandler(event, submission);
}
};
@@ -650,25 +595,19 @@ export default function useResumableSSE(
// load, so a single retry would drop a valid pause and leave the run with no
// approval controls. Bounded so a genuinely-absent target can't spin forever.
const PENDING_ACTION_MAX_RETRY_FRAMES = 120;
- const cancelSteerRetryFrames = () => {
- for (const frameId of steerRetryFramesRef.current) {
- cancelAnimationFrame(frameId);
- }
- steerRetryFramesRef.current.clear();
- };
const applyPendingActionToMessages = (pendingAction: Agents.PendingAction, attempt = 0) => {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const pendingConversationId =
pendingAction.conversationId ??
- currentSubmission.conversation?.conversationId ??
+ sub.submission.conversation?.conversationId ??
currentStreamId;
jotaiStore.set(pendingApprovalActionFamily(pendingConversationId), pendingAction);
const retryNextFrame = () => {
if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- pendingActionRetryRef.current = requestAnimationFrame(() => {
- if (isCurrentSubscription()) {
+ run.pendingActionRetry = run.scheduler.requestFrame(() => {
+ if (sub.isCurrent()) {
applyPendingActionToMessages(pendingAction, attempt + 1);
}
});
@@ -716,8 +655,8 @@ export default function useResumableSSE(
* of the live user message. Read at call time — `created` reassigns both.
*/
const livePlaceholderIds = () => [
- currentSubmission.initialResponse?.messageId,
- userMessage?.messageId ? `${userMessage.messageId}_` : undefined,
+ sub.submission.initialResponse?.messageId,
+ sub.userMessage?.messageId ? `${sub.userMessage.messageId}_` : undefined,
];
/**
@@ -728,11 +667,10 @@ export default function useResumableSSE(
* handler receives in step with the placeholder this pane mutated.
*/
const syncSubmissionPlaceholder = (updated: TMessage) => {
- if (updated.messageId !== currentSubmission.initialResponse?.messageId) {
+ if (updated.messageId !== sub.submission.initialResponse?.messageId) {
return;
}
- currentSubmission = { ...currentSubmission, initialResponse: updated };
- submissionRef.current = currentSubmission;
+ sub.replaceSubmission({ ...sub.submission, initialResponse: updated });
};
/**
@@ -744,9 +682,9 @@ export default function useResumableSSE(
* `initialResponse.content` with the server's completion-local snapshot.
*/
const editPrefixLength = () =>
- currentSubmission.editedContent != null && !editPrefixClearedRef.current
- ? (currentSubmission.editPrefixLength ??
- currentSubmission.initialResponse?.content?.length ??
+ sub.submission.editedContent != null && !run.editPrefixCleared
+ ? (sub.submission.editPrefixLength ??
+ sub.submission.initialResponse?.content?.length ??
0)
: 0;
@@ -761,11 +699,11 @@ export default function useResumableSSE(
attempt = 0,
liveSteerIds: string[] = [],
) => {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const chipConvoId =
- event.conversationId ?? currentSubmission.conversation?.conversationId ?? currentStreamId;
+ event.conversationId ?? sub.submission.conversation?.conversationId ?? currentStreamId;
/** The server's applied event settles ownership immediately. Rendering
* the inline part can wait for React to mount the target, but leaving
* the chip pending during that wait lets an intervening error/final
@@ -781,13 +719,13 @@ export default function useResumableSSE(
: liveSteerIds;
const retryNextFrame = () => {
if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- const frameId = requestAnimationFrame(() => {
- steerRetryFramesRef.current.delete(frameId);
- if (isCurrentSubscription()) {
+ const frameId = run.scheduler.requestFrame(() => {
+ run.steerRetryFrames.delete(frameId);
+ if (sub.isCurrent()) {
applySteerToMessages(event, attempt + 1, firstApplicationIds);
}
});
- steerRetryFramesRef.current.add(frameId);
+ run.steerRetryFrames.add(frameId);
}
};
/** Same boundary as pending actions: land queued deltas before the
@@ -837,18 +775,18 @@ export default function useResumableSSE(
* bounded next-frame retry as steers for the inject-before-render race.
*/
const applyActivityLabelToMessages = (event: TActivityLabelEvent, attempt = 0) => {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const retryNextFrame = () => {
if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- const frameId = requestAnimationFrame(() => {
- activityLabelRetryFramesRef.current.delete(frameId);
- if (isCurrentSubscription()) {
+ const frameId = run.scheduler.requestFrame(() => {
+ run.activityLabelRetryFrames.delete(frameId);
+ if (sub.isCurrent()) {
applyActivityLabelToMessages(event, attempt + 1);
}
});
- activityLabelRetryFramesRef.current.add(frameId);
+ run.activityLabelRetryFrames.add(frameId);
}
};
/** Same boundary as pending actions and steers: land queued deltas
@@ -894,7 +832,7 @@ export default function useResumableSSE(
typeof phasePart.activity_start_index === 'number'
) {
let activityStartIndex = phasePart.activity_start_index + prefixLength;
- const foldedFirstPart = editPrefixFirstPartFoldedRef.current;
+ const foldedFirstPart = run.editPrefixFirstPartFolded;
const targetContent = messages[index]?.content;
/** The step handler records an actual server-index-zero text/think
* merge. An empty +prefix slot is insufficient evidence because
@@ -937,18 +875,18 @@ export default function useResumableSSE(
/** Patches a generated title onto its existing reasoning part. */
const applyReasoningLabelToMessages = (event: TReasoningLabelEvent, attempt = 0) => {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const retryNextFrame = () => {
if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- const frameId = requestAnimationFrame(() => {
- activityLabelRetryFramesRef.current.delete(frameId);
- if (isCurrentSubscription()) {
+ const frameId = run.scheduler.requestFrame(() => {
+ run.activityLabelRetryFrames.delete(frameId);
+ if (sub.isCurrent()) {
applyReasoningLabelToMessages(event, attempt + 1);
}
});
- activityLabelRetryFramesRef.current.add(frameId);
+ run.activityLabelRetryFrames.add(frameId);
}
};
flushPendingDeltas();
@@ -963,7 +901,7 @@ export default function useResumableSSE(
if (
prefixLength > 0 &&
event.index === 0 &&
- editPrefixFirstPartFoldedRef.current &&
+ run.editPrefixFirstPartFolded &&
messages[messageIndex]?.content?.[contentIndex - 1]?.type === ContentTypes.THINK
) {
contentIndex -= 1;
@@ -985,134 +923,12 @@ export default function useResumableSSE(
syncStepMessage(updated);
};
- const baseUrl = `${apiBaseUrl()}/api/agents/chat/stream/${encodeURIComponent(currentStreamId)}`;
- const query = new URLSearchParams();
- if (isResume) {
- query.set('resume', 'true');
- }
- if (generationCreatedAt != null) {
- query.set('generationCreatedAt', String(generationCreatedAt));
- }
- query.set('generationProtocolVersion', String(GENERATION_PROTOCOL_VERSION));
- const queryString = query.toString();
- const url = queryString ? `${baseUrl}?${queryString}` : baseUrl;
- logger.log('ResumableSSE', 'Subscribing to stream:', url, { isResume });
-
- /** Closing is per connection: the transport tells this hook's own close
- * (`abort`) apart from a cancel by the user agent (`error` with status 0). */
- const streamController = new AbortController();
- streamRef.current = streamController;
- let connection: ChatStreamConnection | null = null;
- const isCurrentSubscription = () =>
- lifecycleSignal?.aborted !== true &&
- streamRef.current === streamController &&
- submissionRef.current === currentSubmission;
-
- const closeStream = () => streamController.abort();
-
- let foregroundStatusCheckInFlight = false;
- const reattachOnForeground = () => {
- logger.log('ResumableSSE', 'Re-attaching stream on foreground');
- /** Any backoff still pending targets this same attachment, so returning
- * to the app supersedes it rather than waiting the delay out; its
- * callback finds a superseded subscription and does nothing. */
- if (reconnectTimeoutRef.current) {
- clearTimeout(reconnectTimeoutRef.current);
- reconnectTimeoutRef.current = null;
- }
- reconnectAttemptRef.current = Math.max(reconnectAttemptRef.current, 1);
- closeStream();
- subscribeToStream(
- currentStreamId,
- currentSubmission,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- };
-
- /**
- * A suspended page can lose its stream without the transport ever
- * reporting it. When a mobile browser freezes the tab, an intermediary
- * closes the response body underneath it, and XHR surfaces that as an
- * ordinary load — sse.js dispatches nothing for a body that simply ends,
- * so neither the error nor the abort recovery above ever runs. Nothing
- * else re-reads the conversation while the pane stays mounted, which is
- * why the response the run finished writing only appears after a reload.
- *
- * Some mobile WebViews leave the XHR marked OPEN even after the suspended
- * request stopped delivering events. In that case the durable run status
- * is the only authority that distinguishes a healthy live attachment from
- * a terminal one holding stale partial content. A terminal status forces
- * the same resume path as a closed transport; it returns the synthesized
- * terminal frame or 404 that reconciles persisted messages.
- */
- const handleForegroundReattach = () => {
- if (
- document.visibilityState !== 'visible' ||
- finalReceived ||
- subscriptionRetired ||
- replacementHandoffRef.current ||
- !isCurrentSubscription() ||
- !submissionRef.current
- ) {
- return;
- }
-
- if (connection?.closed === true) {
- reattachOnForeground();
- return;
- }
-
- if (foregroundStatusCheckInFlight) {
- return;
- }
- foregroundStatusCheckInFlight = true;
- const foregroundConvoId = currentSubmission.conversation?.conversationId ?? currentStreamId;
- void fetchStreamStatus(foregroundConvoId)
- .then((status) => {
- if (
- status.active !== false ||
- (status.createdAt != null &&
- generationCreatedAt != null &&
- status.createdAt !== generationCreatedAt) ||
- !isCurrentSubscription() ||
- finalReceived ||
- subscriptionRetired ||
- replacementHandoffRef.current ||
- document.visibilityState !== 'visible'
- ) {
- return;
- }
- logger.log(
- 'ResumableSSE',
- 'Apparently open stream is terminal - reconciling on foreground',
- { conversationId: foregroundConvoId, generationCreatedAt },
- );
- reattachOnForeground();
- })
- .catch((error) => {
- if (!isCurrentSubscription()) {
- return;
- }
- logger.warn('ResumableSSE', 'Could not verify stream on foreground', {
- conversationId: foregroundConvoId,
- generationCreatedAt,
- error,
- });
- })
- .finally(() => {
- foregroundStatusCheckInFlight = false;
- });
- };
- stopForegroundReattachRef.current?.();
- document.addEventListener('visibilitychange', handleForegroundReattach);
- stopForegroundReattachRef.current = () =>
- document.removeEventListener('visibilitychange', handleForegroundReattach);
+ logger.log('ResumableSSE', 'Subscribing to stream:', sub.url(), { isResume });
+ sub.claim();
+ sub.watchForeground();
const handleOpen = () => {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.log('ResumableSSE', 'Stream connected');
@@ -1120,12 +936,12 @@ export default function useResumableSSE(
// Restore UI state on successful connection (including reconnection)
setIsSubmitting(true);
setShowStopButton(generationCreatedAt != null);
- reconnectAttemptRef.current = 0;
+ run.reconnectAttempt = 0;
};
const handleFrame = async (event: ChatEvent) => {
try {
- if (!isCurrentSubscription() || finalReceived) {
+ if (!sub.isCurrent() || sub.finalReceived) {
return;
}
@@ -1141,43 +957,37 @@ export default function useResumableSSE(
// 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.
- finalReceived = true;
- cancelSteerRetryFrames();
+ sub.finalReceived = true;
+ run.cancelSteerRetryFrames();
void reconcileGenerationLifecycle(data);
return;
}
if (event.type === 'final') {
const { data } = event;
- finalReceived = true;
+ sub.finalReceived = true;
const finalConvoId =
data.conversation?.conversationId ??
- currentSubmission.conversation?.conversationId ??
+ sub.submission.conversation?.conversationId ??
currentStreamId;
- if (
- !(await authorizeTerminalTeardown(finalConvoId, 'FINAL')) ||
- !isCurrentSubscription()
- ) {
+ if (!(await authorizeTerminalTeardown(finalConvoId, 'FINAL')) || !sub.isCurrent()) {
return;
}
- cancelSteerRetryFrames();
- if (reconnectTimeoutRef.current) {
- clearTimeout(reconnectTimeoutRef.current);
- reconnectTimeoutRef.current = null;
- }
- reconnectAttemptRef.current = 0;
+ run.cancelSteerRetryFrames();
+ run.clearReconnectTimeout();
+ run.reconnectAttempt = 0;
logger.log('ResumableSSE', 'Received FINAL event', {
aborted: data.aborted,
conversationId: data.conversation?.conversationId,
hasResponseMessage: !!data.responseMessage,
});
clearPendingApprovalForTerminal(finalConvoId);
- clearComposerDrafts(runIndex, currentSubmission.conversation?.conversationId, {
+ clearComposerDrafts(runIndex, sub.submission.conversation?.conversationId, {
includeNewChatDraft:
- !currentSubmission.conversation?.conversationId ||
- currentSubmission.conversation.conversationId === Constants.NEW_CONVO ||
- optimisticStreamIdsRef.current.has(currentStreamId) ||
- isInitialNewConversation(currentSubmission),
+ !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
@@ -1218,9 +1028,9 @@ export default function useResumableSSE(
convertLocalSteersToQueued(finalConvoId);
let finalHandled = false;
try {
- finalHandler(data as TFinalResData, currentSubmission as EventSubmission);
+ finalHandler(data as TFinalResData, sub.submission as EventSubmission);
finalHandled = true;
- finalizeUsage(data, { ...currentSubmission, userMessage });
+ finalizeUsage(data, sub.liveSubmission());
} catch (error) {
logger.error('ResumableSSE', 'Error in finalHandler:', error);
setIsSubmitting(false);
@@ -1234,7 +1044,7 @@ export default function useResumableSSE(
const runEndTarget = resolveRunEndTarget({
conversationId: finalConvoId,
earlyAbort: data.earlyAbort === true,
- startedAsNewConvo: optimisticStreamIdsRef.current.has(currentStreamId),
+ startedAsNewConvo: run.optimisticStreamIds.has(currentStreamId),
});
let finalOutcome: 'completed' | 'aborted' | 'error' = 'error';
if (data.aborted === true || data.responseMessage?.unfinished === true) {
@@ -1249,7 +1059,7 @@ export default function useResumableSSE(
// wasAbortedBeforeComplete branch); it must not auto-drain.
outcome: finalOutcome,
startedAsNewConvo: runEndTarget.startedAsNewConvo,
- endedAt: Date.now(),
+ endedAt: run.scheduler.now(),
generationCreatedAt,
...(data.responseMessage?.messageId != null && {
responseMessageId: data.responseMessage.messageId,
@@ -1261,10 +1071,9 @@ export default function useResumableSSE(
removeActiveJob(currentStreamId);
clearAttachedGenerationCreatedAt();
(startupConfig?.balance?.enabled ?? false) && balanceQuery.refetch();
- closeStream();
+ sub.close();
setStreamId(null);
- optimisticStreamIdsRef.current.delete(currentStreamId);
- createdStreamIdsRef.current.delete(currentStreamId);
+ run.releaseStream(currentStreamId);
return;
}
@@ -1274,31 +1083,30 @@ export default function useResumableSSE(
messageId: data.message?.messageId,
conversationId: data.message?.conversationId,
});
- createdStreamIdsRef.current.add(currentStreamId);
+ run.createdStreamIds.add(currentStreamId);
if (startedAsNewConversation) {
updateActiveGenerationCreatedAt(Constants.NEW_CONVO, null, generationCreatedAt);
}
const runId = v4();
setActiveRunId(runId);
- userMessage = {
- ...userMessage,
+ sub.userMessage = {
+ ...sub.userMessage,
...data.message,
- overrideParentMessageId: userMessage.overrideParentMessageId,
+ overrideParentMessageId: sub.userMessage.overrideParentMessageId,
};
const createdInitialResponse = buildCreatedInitialResponse({
- initialResponse: currentSubmission.initialResponse as TMessage,
- userMessage,
- isRegenerate: currentSubmission.isRegenerate,
+ initialResponse: sub.submission.initialResponse as TMessage,
+ userMessage: sub.userMessage,
+ isRegenerate: sub.submission.isRegenerate,
});
- currentSubmission = {
- ...currentSubmission,
- userMessage,
+ sub.replaceSubmission({
+ ...sub.submission,
+ userMessage: sub.userMessage,
initialResponse: createdInitialResponse,
- };
- submissionRef.current = currentSubmission;
- identityConfirmedRef.current = true;
- bindResponse(currentSubmission);
- createdHandler(data, currentSubmission as EventSubmission);
+ });
+ run.identityConfirmed = true;
+ bindResponse(sub.submission);
+ createdHandler(data, sub.submission as EventSubmission);
replayPreCreatedStepEvents();
return;
}
@@ -1306,7 +1114,7 @@ export default function useResumableSSE(
if (event.type === 'attachment' && event.data) {
attachmentHandler({
data: event.data as TAttachment,
- submission: currentSubmission as EventSubmission,
+ submission: sub.submission as EventSubmission,
});
return;
}
@@ -1317,12 +1125,12 @@ export default function useResumableSSE(
}
if (event.type === 'context_usage') {
- contextHandler(event.data, { ...currentSubmission, userMessage });
+ contextHandler(event.data, sub.liveSubmission());
return;
}
if (event.type === 'token_usage') {
- usageHandler(event.data, { ...currentSubmission, userMessage });
+ usageHandler(event.data, sub.liveSubmission());
return;
}
@@ -1358,18 +1166,18 @@ export default function useResumableSSE(
data.event === StepEvents.ON_MESSAGE_DELTA ||
data.event === StepEvents.ON_REASONING_DELTA
) {
- tapStream(data.data, { ...currentSubmission, userMessage });
+ tapStream(data.data, sub.liveSubmission());
}
- if (!isResume && !createdStreamIdsRef.current.has(currentStreamId)) {
+ if (!isResume && !run.createdStreamIds.has(currentStreamId)) {
if (isOAuthStepEvent(data)) {
- preCreatedStepEvents.push(data);
- stepHandler(data, { ...currentSubmission, userMessage } as EventSubmission);
+ sub.preCreatedStepEvents.push(data);
+ stepHandler(data, sub.liveSubmission() as EventSubmission);
return;
}
- preCreatedStepEvents.push(data);
+ sub.preCreatedStepEvents.push(data);
return;
}
- stepHandler(data, { ...currentSubmission, userMessage } as EventSubmission);
+ stepHandler(data, sub.liveSubmission() as EventSubmission);
return;
}
@@ -1384,24 +1192,23 @@ export default function useResumableSSE(
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 = currentSubmission.initialResponse?.messageId;
- const currentUserMessageId = currentSubmission.userMessage?.messageId;
+ const preliminaryResponseMessageId = sub.submission.initialResponse?.messageId;
+ const currentUserMessageId = sub.submission.userMessage?.messageId;
const preliminaryUserMessageId =
currentUserMessageId &&
- (currentSubmission.initialResponse?.parentMessageId === currentUserMessageId ||
+ (sub.submission.initialResponse?.parentMessageId === currentUserMessageId ||
preliminaryResponseMessageId === `${currentUserMessageId}_`)
? currentUserMessageId
: undefined;
const resumeSubmission = buildResumeEventSubmission(
- currentSubmission,
- userMessage,
+ sub.submission,
+ sub.userMessage,
data.resumeState,
);
- currentSubmission = resumeSubmission;
- submissionRef.current = resumeSubmission;
- userMessage = resumeSubmission.userMessage;
+ sub.replaceSubmission(resumeSubmission);
+ sub.userMessage = resumeSubmission.userMessage;
if (data.resumeState?.userMessage != null) {
- identityConfirmedRef.current = true;
+ run.identityConfirmed = true;
}
/**
* Totals rebuild from the persisted backfill at sync. Replayed or
@@ -1442,9 +1249,9 @@ export default function useResumableSSE(
}
}
- if (data.resumeState?.aggregatedContent && userMessage?.messageId) {
+ if (data.resumeState?.aggregatedContent && sub.userMessage?.messageId) {
const messages = getMessages() ?? [];
- const userMsgId = userMessage.messageId;
+ const userMsgId = sub.userMessage.messageId;
const hasResumedContent = data.resumeState.aggregatedContent.length > 0;
const responseId = resumeSubmission.initialResponse.messageId;
const messageIndexes = getResumeMessageIndexes(
@@ -1487,7 +1294,7 @@ export default function useResumableSSE(
* it the offset. Run steps and labels both read this.
*/
if (!preserveLoadedContent) {
- editPrefixClearedRef.current = true;
+ run.editPrefixCleared = true;
}
const responseMessage = {
...resumeSubmission.initialResponse,
@@ -1507,7 +1314,7 @@ export default function useResumableSSE(
} as TMessage;
const updated = mergeResumeMessages(
messages,
- userMessage,
+ sub.userMessage,
responseMessage,
messageIndexes,
resumeSubmission.compact === true,
@@ -1529,7 +1336,7 @@ export default function useResumableSSE(
* 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. */
- editPrefixClearedRef.current = true;
+ run.editPrefixCleared = true;
const newMessage = {
...resumeSubmission.initialResponse,
messageId: responseId,
@@ -1540,7 +1347,7 @@ export default function useResumableSSE(
setMessages(
mergeResumeMessages(
messages,
- userMessage,
+ sub.userMessage,
newMessage,
messageIndexes,
resumeSubmission.compact === true,
@@ -1573,7 +1380,7 @@ export default function useResumableSSE(
// 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 = currentSubmission.conversation?.conversationId ?? currentStreamId;
+ const steerConvoId = sub.submission.conversation?.conversationId ?? currentStreamId;
seedSteerChips(
steerConvoId,
(data.resumeState?.pendingSteers ?? []) as TPendingSteer[],
@@ -1701,11 +1508,11 @@ export default function useResumableSSE(
const { data } = event;
const { index } = data;
const text = 'text' in data ? data.text : undefined;
- if (text != null && index !== textIndex) {
- textIndex = index;
+ if (text != null && index !== sub.textIndex) {
+ sub.textIndex = index;
}
- tapContent(text, { ...currentSubmission, userMessage });
- contentHandler({ data, submission: currentSubmission as EventSubmission });
+ tapContent(text, sub.liveSubmission());
+ contentHandler({ data, submission: sub.submission as EventSubmission });
return;
}
@@ -1713,15 +1520,18 @@ export default function useResumableSSE(
const { data } = event;
const text = data.text ?? data.response;
const initialResponse = {
- ...(currentSubmission.initialResponse as TMessage),
+ ...(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 = { ...currentSubmission, userMessage, initialResponse };
- currentSubmission = textSubmission;
- submissionRef.current = textSubmission;
+ const textSubmission = {
+ ...sub.submission,
+ userMessage: sub.userMessage,
+ initialResponse,
+ };
+ sub.replaceSubmission(textSubmission);
tapContent(text, textSubmission);
messageHandler(text, textSubmission);
}
@@ -1734,7 +1544,7 @@ export default function useResumableSSE(
conversationId: string,
knownStatus?: Awaited<ReturnType<typeof fetchStreamStatus>>,
): Promise<boolean> {
- if (!isCurrentSubscription() || generationProtocolVersion !== GENERATION_PROTOCOL_VERSION) {
+ if (!sub.isCurrent() || generationProtocolVersion !== GENERATION_PROTOCOL_VERSION) {
return false;
}
let replacementStatus = knownStatus;
@@ -1743,11 +1553,11 @@ export default function useResumableSSE(
// Deliberately unfenced: this read discovers the newer generation
// after the epoch-fenced SSE endpoint rejects the stale attachment.
replacementStatus = await fetchStreamStatus(conversationId);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return false;
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return false;
}
logger.warn('ResumableSSE', 'Could not inspect replacement generation', {
@@ -1774,13 +1584,10 @@ export default function useResumableSSE(
staleCreatedAt: generationCreatedAt,
replacementCreatedAt: replacementStatus.createdAt,
});
- replacementHandoffRef.current = true;
- cancelSteerRetryFrames();
- closeStream();
- if (reconnectTimeoutRef.current) {
- clearTimeout(reconnectTimeoutRef.current);
- reconnectTimeoutRef.current = null;
- }
+ run.replacementHandoff = true;
+ run.cancelSteerRetryFrames();
+ sub.close();
+ run.clearReconnectTimeout();
queryClient.setQueryData(streamStatusQueryKey(conversationId), {
...replacementStatus,
generationHandoff: true,
@@ -1816,10 +1623,10 @@ export default function useResumableSSE(
replacementStatus.resumeState?.pendingAction) as Agents.PendingAction,
);
}
- resetLive({ ...currentSubmission, userMessage });
+ resetLive(sub.liveSubmission());
clearStepMaps();
- reconnectAttemptRef.current = 0;
- submissionRef.current = null;
+ run.reconnectAttempt = 0;
+ run.submission = null;
setIsSubmitting(true);
setShowStopButton(true);
setSubmission(null);
@@ -1833,38 +1640,27 @@ export default function useResumableSSE(
* epoch can still be active despite a racing FINAL/error frame.
*/
function retryFencedTerminalAttachment(reason: string): void {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Deferring terminal teardown and retrying fenced attachment', {
- conversationId: currentSubmission.conversation?.conversationId ?? currentStreamId,
+ conversationId: sub.submission.conversation?.conversationId ?? currentStreamId,
generationCreatedAt,
reason,
});
- reconnectAttemptRef.current = Math.max(reconnectAttemptRef.current, 1);
- closeStream();
- if (reconnectTimeoutRef.current) {
- clearTimeout(reconnectTimeoutRef.current);
- }
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 250);
+ run.reconnectAttempt = Math.max(run.reconnectAttempt, 1);
+ sub.close();
+ if (run.reconnectTimeout) {
+ run.scheduler.clearTimeout(run.reconnectTimeout);
+ }
+ sub.scheduleReattach(250);
}
async function authorizeTerminalTeardown(
conversationId: string,
terminalKind: 'FINAL' | 'error',
): Promise<boolean> {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return false;
}
if (generationProtocolVersion !== GENERATION_PROTOCOL_VERSION) {
@@ -1874,11 +1670,11 @@ export default function useResumableSSE(
let status: Awaited<ReturnType<typeof fetchStreamStatus>>;
try {
status = await fetchStreamStatus(conversationId);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return false;
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return false;
}
logger.warn('ResumableSSE', `Could not verify ${terminalKind} generation status`, {
@@ -1901,7 +1697,7 @@ export default function useResumableSSE(
generationCreatedAt != null &&
status.createdAt !== generationCreatedAt &&
(await handoffToReplacement(conversationId, status));
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return false;
}
if (handedOff) {
@@ -1929,12 +1725,12 @@ export default function useResumableSSE(
'reconcileReason' | 'terminalStatus' | 'generationCreatedAt' | 'conversation'
>,
): Promise<void> => {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const reconciliationConvoId =
event.conversation?.conversationId ??
- currentSubmission.conversation?.conversationId ??
+ sub.submission.conversation?.conversationId ??
currentStreamId;
if (
generationCreatedAt != null &&
@@ -1946,7 +1742,7 @@ export default function useResumableSSE(
if (event.reconcileReason === 'generation_replaced') {
const handedOff = await handoffToReplacement(reconciliationConvoId);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (handedOff) {
@@ -1955,25 +1751,14 @@ export default function useResumableSSE(
// Replacement visibility can lag its notification by a round trip.
// Retry the stale epoch; the fenced HTTP endpoint will return the
// dedicated replacement response as soon as the new job is visible.
- reconnectAttemptRef.current = Math.max(reconnectAttemptRef.current, 1);
- closeStream();
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 250);
+ run.reconnectAttempt = Math.max(run.reconnectAttempt, 1);
+ sub.close();
+ sub.scheduleReattach(250);
return;
}
- reconnectAttemptRef.current = Math.max(reconnectAttemptRef.current, 1);
- closeStream();
+ run.reconnectAttempt = Math.max(run.reconnectAttempt, 1);
+ sub.close();
clearStepMaps();
let persistedMessages: TMessage[] | undefined;
const messageQueryKey = [QueryKeys.messages, reconciliationConvoId] as const;
@@ -1987,20 +1772,20 @@ export default function useResumableSSE(
queryKey: messageQueryKey,
refetchType: 'none',
});
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const fetched = await queryClient.fetchQuery<TMessage[]>({
queryKey: messageQueryKey,
});
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (Array.isArray(fetched)) {
persistedMessages = fetched;
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Could not refetch synthesized terminal state', {
@@ -2013,19 +1798,19 @@ export default function useResumableSSE(
queryKey: [QueryKeys.conversation, reconciliationConvoId],
refetchType: 'all',
});
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
await invalidateConversationLists(queryClient);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
await queryClient.invalidateQueries({ queryKey: [QueryKeys.pinnedConversations] });
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Could not refresh synthesized conversation metadata', {
@@ -2037,11 +1822,11 @@ export default function useResumableSSE(
let status: Awaited<ReturnType<typeof fetchStreamStatus>> | undefined;
try {
status = await fetchStreamStatus(reconciliationConvoId);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Could not inspect synthesized terminal status', {
@@ -2053,18 +1838,7 @@ export default function useResumableSSE(
/** A v2 control frame cannot be reconciled with a legacy status
* snapshot (for example during a rolling deploy). Preserve the
* attachment and retry the exact fenced generation. */
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 250);
+ sub.scheduleReattach(250);
return;
}
if (
@@ -2073,7 +1847,7 @@ export default function useResumableSSE(
(generationCreatedAt == null || status.createdAt !== generationCreatedAt)
) {
const handedOff = await handoffToReplacement(reconciliationConvoId, status);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (handedOff) {
@@ -2086,18 +1860,7 @@ export default function useResumableSSE(
) {
// Durable state still calls this exact epoch active. Prefer another
// fenced resume over terminalizing on a racing synthesized frame.
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 250);
+ sub.scheduleReattach(250);
return;
}
@@ -2109,7 +1872,7 @@ export default function useResumableSSE(
settleAppliedSteerParts(reconciliationConvoId, authoritativeValues);
const unrecovered = status?.unrecoveredSteers ?? [];
if (unrecovered.length > 0) {
- const recoverySteerId = getRecoverySteerId(currentSubmission);
+ const recoverySteerId = getRecoverySteerId(sub.submission);
convertSteersToQueued(reconciliationConvoId, unrecovered, {
...(recoverySteerId != null && {
allowPreviouslyConvertedIds: [recoverySteerId],
@@ -2129,7 +1892,7 @@ export default function useResumableSSE(
});
}
- resetLive({ ...currentSubmission, userMessage });
+ resetLive(sub.liveSubmission());
removeActiveJob(currentStreamId);
clearAttachedGenerationCreatedAt();
clearPendingApprovalForTerminal(reconciliationConvoId);
@@ -2137,8 +1900,8 @@ export default function useResumableSSE(
includeNewChatDraft:
!reconciliationConvoId ||
reconciliationConvoId === Constants.NEW_CONVO ||
- optimisticStreamIdsRef.current.has(currentStreamId) ||
- isInitialNewConversation(currentSubmission),
+ run.optimisticStreamIds.has(currentStreamId) ||
+ isInitialNewConversation(sub.submission),
});
setIsSubmitting(false);
setShowStopButton(false);
@@ -2148,7 +1911,7 @@ export default function useResumableSSE(
* unknown, so consume that override before publishing runEnd; the
* queued words remain available for a deliberate retry. */
clearDrainAfterAbort(
- currentSubmission.conversation?.conversationId || String(Constants.NEW_CONVO),
+ sub.submission.conversation?.conversationId || String(Constants.NEW_CONVO),
generationCreatedAt,
);
}
@@ -2162,15 +1925,14 @@ export default function useResumableSSE(
reconciliationOutcome === 'completed'
? completedResponseMessageId(
persistedMessages,
- userMessage?.messageId,
- status?.resumeState?.responseMessageId ??
- currentSubmission.initialResponse?.messageId,
+ sub.userMessage?.messageId,
+ status?.resumeState?.responseMessageId ?? sub.submission.initialResponse?.messageId,
)
: undefined;
setRunEnd({
conversationId: reconciliationConvoId,
outcome: reconciliationOutcome,
- endedAt: Date.now(),
+ endedAt: run.scheduler.now(),
generationCreatedAt: status?.createdAt ?? generationCreatedAt,
...(reconciledResponseMessageId != null && {
responseMessageId: reconciledResponseMessageId,
@@ -2178,9 +1940,8 @@ export default function useResumableSSE(
});
setSubmission(null);
setStreamId(null);
- optimisticStreamIdsRef.current.delete(currentStreamId);
- createdStreamIdsRef.current.delete(currentStreamId);
- reconnectAttemptRef.current = 0;
+ run.releaseStream(currentStreamId);
+ run.reconnectAttempt = 0;
};
/**
@@ -2195,11 +1956,11 @@ export default function useResumableSSE(
status: responseCode,
data,
}: Pick<Extract<ChatEvent, { type: 'error' }>, 'status' | 'data'>) => {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
- if (finalReceived) {
+ if (sub.finalReceived) {
logger.log('ResumableSSE', 'Ignoring error after FINAL event', {
responseCode,
hasData: data != null,
@@ -2210,10 +1971,9 @@ export default function useResumableSSE(
(startupConfig?.balance?.enabled ?? false) && balanceQuery.refetch();
if (responseCode === 409) {
- const replacementConvoId =
- currentSubmission.conversation?.conversationId ?? currentStreamId;
+ const replacementConvoId = sub.submission.conversation?.conversationId ?? currentStreamId;
const handedOff = await handoffToReplacement(replacementConvoId);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (handedOff) {
@@ -2225,22 +1985,22 @@ export default function useResumableSSE(
// Refetch and reconcile them before recovering local steers: the final
// response may contain an applied steer whose live event was missed.
if (responseCode === 404) {
- const convoId = currentSubmission.conversation?.conversationId;
+ const convoId = sub.submission.conversation?.conversationId;
logger.log('ResumableSSE', 'Stream 404, invalidating messages for:', convoId);
// Keep the UI non-idle while the status read decides whether this is
// terminal cleanup or a handoff to a newer generation epoch.
- reconnectAttemptRef.current = Math.max(reconnectAttemptRef.current, 1);
- cancelSteerRetryFrames();
- closeStream();
+ run.reconnectAttempt = Math.max(run.reconnectAttempt, 1);
+ run.cancelSteerRetryFrames();
+ sub.close();
/** Terminal: drop any in-flight live estimate so the gauge doesn't
* keep counting stale streamed output after the stream ends */
- resetLive({ ...currentSubmission, userMessage });
+ resetLive(sub.liveSubmission());
clearComposerDrafts(runIndex, convoId, {
includeNewChatDraft:
!convoId ||
convoId === Constants.NEW_CONVO ||
- optimisticStreamIdsRef.current.has(currentStreamId) ||
- isInitialNewConversation(currentSubmission),
+ run.optimisticStreamIds.has(currentStreamId) ||
+ isInitialNewConversation(sub.submission),
});
clearStepMaps();
let persistedMessages: TMessage[] | undefined;
@@ -2251,7 +2011,7 @@ export default function useResumableSSE(
queryKey: messageQueryKey,
refetchType: 'none',
});
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const fetched = await queryClient.fetchQuery<TMessage[]>({
@@ -2259,14 +2019,14 @@ export default function useResumableSSE(
// The first stream can finish before CREATED mounts the saved-chat query.
queryFn: () => fetchConversationMessages(convoId),
});
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (Array.isArray(fetched)) {
persistedMessages = fetched;
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Could not reconcile persisted messages after 404', {
@@ -2290,25 +2050,14 @@ export default function useResumableSSE(
let confirmedV2Terminal = false;
try {
const status = await fetchStreamStatus(recoveryConvoId);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (
generationProtocolVersion === GENERATION_PROTOCOL_VERSION &&
!supportsGenerationProtocolV2(status)
) {
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 1_000);
+ sub.scheduleReattach(1_000);
return;
}
if (
@@ -2317,7 +2066,7 @@ export default function useResumableSSE(
(generationCreatedAt == null || status.createdAt !== generationCreatedAt)
) {
const handedOff = await handoffToReplacement(recoveryConvoId, status);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (handedOff) {
@@ -2325,18 +2074,7 @@ export default function useResumableSSE(
}
/** Legacy generations have no replacement-handoff contract.
* Never attach this submission to a different epoch. */
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 1_000);
+ sub.scheduleReattach(1_000);
return;
}
if (status.active === true) {
@@ -2374,19 +2112,8 @@ export default function useResumableSSE(
}
setIsSubmitting(true);
setShowStopButton(status.createdAt != null);
- reconnectAttemptRef.current = Math.max(reconnectAttemptRef.current, 1);
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- activeStreamId,
- submissionRef.current,
- true,
- status.createdAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 1_000);
+ run.reconnectAttempt = Math.max(run.reconnectAttempt, 1);
+ sub.scheduleReattach(1_000, activeStreamId, status.createdAt);
return;
}
confirmedV2Terminal =
@@ -2395,7 +2122,7 @@ export default function useResumableSSE(
const canRecoverTerminalSteers = generationProtocolVersion === 1 || confirmedV2Terminal;
const unrecovered = canRecoverTerminalSteers ? (status.unrecoveredSteers ?? []) : [];
if (unrecovered.length > 0) {
- const recoverySteerId = getRecoverySteerId(currentSubmission);
+ const recoverySteerId = getRecoverySteerId(sub.submission);
convertSteersToQueued(recoveryConvoId, unrecovered, {
generationProtocolVersion,
...(recoverySteerId != null && {
@@ -2410,7 +2137,7 @@ export default function useResumableSSE(
}
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Could not recover parked steers after 404', {
@@ -2423,8 +2150,8 @@ export default function useResumableSSE(
clearAttachedGenerationCreatedAt();
clearPendingApprovalForTerminal(recoveryConvoId);
if (
- !createdStreamIdsRef.current.has(currentStreamId) &&
- optimisticStreamIdsRef.current.has(currentStreamId)
+ !run.createdStreamIds.has(currentStreamId) &&
+ run.optimisticStreamIds.has(currentStreamId)
) {
// Both fresh and resumed subscriptions can miss every event of a fast turn.
// A missing job proves neither that the conversation was saved nor that it failed.
@@ -2432,7 +2159,7 @@ export default function useResumableSSE(
const persisted = await fetchConvoSnapshot(queryClient, recoveryConvoId, () =>
dataService.getConversationById(recoveryConvoId),
);
- if (!isCurrentSubscription()) return;
+ if (!sub.isCurrent()) return;
if (persisted?.conversationId === recoveryConvoId) {
queryClient.setQueryData([QueryKeys.conversation, recoveryConvoId], persisted);
upsertConvoInAllQueries(queryClient, persisted, true, 'snapshot');
@@ -2453,7 +2180,7 @@ export default function useResumableSSE(
}
}
} catch (error) {
- if (!isCurrentSubscription()) return;
+ if (!sub.isCurrent()) return;
if (toStartGenerationError(error)?.response?.status === 404) {
removeConvoFromAllQueries(queryClient, currentStreamId);
}
@@ -2465,7 +2192,7 @@ export default function useResumableSSE(
if (persistedMessages) {
setMessages(persistedMessages);
}
- subscriptionRetired = true;
+ sub.retired = true;
setIsSubmitting(false);
setShowStopButton(false);
@@ -2500,9 +2227,9 @@ export default function useResumableSSE(
{
conversationId: recoveryConvoId,
outcome: 'aborted',
- endedAt: Date.now(),
+ endedAt: run.scheduler.now(),
...detachedEnd,
- startedAsNewConvo: optimisticStreamIdsRef.current.has(currentStreamId),
+ startedAsNewConvo: run.optimisticStreamIds.has(currentStreamId),
},
{
retainDetached:
@@ -2510,9 +2237,8 @@ export default function useResumableSSE(
},
);
setStreamId(null);
- optimisticStreamIdsRef.current.delete(currentStreamId);
- createdStreamIdsRef.current.delete(currentStreamId);
- reconnectAttemptRef.current = 0;
+ run.releaseStream(currentStreamId);
+ run.reconnectAttempt = 0;
return;
}
@@ -2524,17 +2250,14 @@ export default function useResumableSSE(
* not a server-sent error payload. Use `== null` to only match undefined/null (no HTTP status).
*/
if (responseCode == null && data != null) {
- finalReceived = true;
- const recoveryConvoId = currentSubmission.conversation?.conversationId ?? currentStreamId;
- if (
- !(await authorizeTerminalTeardown(recoveryConvoId, 'error')) ||
- !isCurrentSubscription()
- ) {
+ sub.finalReceived = true;
+ const recoveryConvoId = sub.submission.conversation?.conversationId ?? currentStreamId;
+ if (!(await authorizeTerminalTeardown(recoveryConvoId, 'error')) || !sub.isCurrent()) {
return;
}
logger.log('ResumableSSE', 'Server-sent error event received:', data);
- cancelSteerRetryFrames();
- closeStream();
+ run.cancelSteerRetryFrames();
+ sub.close();
/** FLUSH (not cancel): the error card below is built from the cache
* tail, so queued tokens must land first, and a stale trailing
* frame must never overwrite the error write. */
@@ -2542,10 +2265,10 @@ export default function useResumableSSE(
removeActiveJob(currentStreamId);
clearAttachedGenerationCreatedAt();
clearPendingApprovalForTerminal(recoveryConvoId);
- resetLive({ ...currentSubmission, userMessage });
+ resetLive(sub.liveSubmission());
if (
- !createdStreamIdsRef.current.has(currentStreamId) &&
- optimisticStreamIdsRef.current.has(currentStreamId)
+ !run.createdStreamIds.has(currentStreamId) &&
+ run.optimisticStreamIds.has(currentStreamId)
) {
removeConvoFromAllQueries(queryClient, currentStreamId);
}
@@ -2574,12 +2297,12 @@ export default function useResumableSSE(
// Display the error to user via errorHandler
errorHandler({
data: { text: errorString } as unknown as Parameters<typeof errorHandler>[0]['data'],
- submission: currentSubmission as EventSubmission,
+ submission: sub.submission as EventSubmission,
});
setIsSubmitting(false);
setShowStopButton(false);
- const recoverySteerId = getRecoverySteerId(currentSubmission);
+ const recoverySteerId = getRecoverySteerId(sub.submission);
if (
recoverySteerId != null &&
generationProtocolVersion === GENERATION_PROTOCOL_VERSION &&
@@ -2591,7 +2314,7 @@ export default function useResumableSSE(
* started before this recovery could return a stale parked copy
* after a successful commit and must never authorize redelivery. */
const terminalStatus = await fetchStreamStatus(recoveryConvoId);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const releasedSource = terminalStatus.unrecoveredSteers?.find(
@@ -2608,7 +2331,7 @@ export default function useResumableSSE(
});
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Could not recover source after generation error', {
@@ -2628,13 +2351,12 @@ export default function useResumableSSE(
setRunEnd({
conversationId: recoveryConvoId,
outcome: 'error',
- endedAt: Date.now(),
+ endedAt: run.scheduler.now(),
generationCreatedAt,
});
setStreamId(null);
- optimisticStreamIdsRef.current.delete(currentStreamId);
- createdStreamIdsRef.current.delete(currentStreamId);
- reconnectAttemptRef.current = 0;
+ run.releaseStream(currentStreamId);
+ run.reconnectAttempt = 0;
return;
}
@@ -2644,31 +2366,19 @@ export default function useResumableSSE(
hasData: data != null,
});
- if (reconnectAttemptRef.current < MAX_RETRIES) {
+ if (run.reconnectAttempt < MAX_RETRIES) {
// Increment counter BEFORE close() so abort handler knows we're reconnecting
- reconnectAttemptRef.current++;
- const delay = getReconnectDelay(reconnectAttemptRef.current);
+ run.reconnectAttempt++;
+ const delay = getReconnectDelay(run.reconnectAttempt);
logger.log(
'ResumableSSE',
- `Reconnecting in ${delay}ms (attempt ${reconnectAttemptRef.current}/${MAX_RETRIES})`,
+ `Reconnecting in ${delay}ms (attempt ${run.reconnectAttempt}/${MAX_RETRIES})`,
);
- closeStream();
+ sub.close();
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- // Reconnect with isResume=true to get sync event with any missed content
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, delay);
+ sub.scheduleReattach(delay);
// Keep UI in "submitting" state during reconnection attempts
// so user knows we're still trying (abort handler may have reset these)
@@ -2676,17 +2386,17 @@ export default function useResumableSSE(
setShowStopButton(generationCreatedAt != null);
} else {
logger.error('ResumableSSE', 'Max reconnect attempts reached');
- closeStream();
+ sub.close();
flushPendingDeltas();
- const recoveryConvoId = currentSubmission.conversation?.conversationId ?? currentStreamId;
+ const recoveryConvoId = sub.submission.conversation?.conversationId ?? currentStreamId;
let status: Awaited<ReturnType<typeof fetchStreamStatus>> | undefined;
try {
status = await fetchStreamStatus(recoveryConvoId);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Could not determine job state after reconnect limit', {
@@ -2710,25 +2420,14 @@ export default function useResumableSSE(
(generationCreatedAt == null || status.createdAt !== generationCreatedAt)
) {
const handedOff = await handoffToReplacement(recoveryConvoId, status);
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (handedOff) {
return;
}
- reconnectAttemptRef.current = 0;
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 30_000);
+ run.reconnectAttempt = 0;
+ sub.scheduleReattach(30_000);
return;
}
@@ -2754,19 +2453,8 @@ export default function useResumableSSE(
}
setIsSubmitting(true);
setShowStopButton(generationCreatedAt != null);
- reconnectAttemptRef.current = 0;
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 30_000);
+ run.reconnectAttempt = 0;
+ sub.scheduleReattach(30_000);
return;
}
@@ -2777,25 +2465,14 @@ export default function useResumableSSE(
queryClient.invalidateQueries({ queryKey: streamStatusQueryKey(recoveryConvoId) });
setIsSubmitting(true);
setShowStopButton(generationCreatedAt != null);
- reconnectAttemptRef.current = 0;
- reconnectTimeoutRef.current = setTimeout(() => {
- if (isCurrentSubscription() && submissionRef.current) {
- subscribeToStream(
- currentStreamId,
- submissionRef.current,
- true,
- generationCreatedAt,
- generationProtocolVersion,
- lifecycleSignal,
- );
- }
- }, 30_000);
+ run.reconnectAttempt = 0;
+ sub.scheduleReattach(30_000);
return;
}
// The status endpoint proved the job terminal. Reconcile persisted
// content before recovering leftovers, just like the 404 path.
- cancelSteerRetryFrames();
+ run.cancelSteerRetryFrames();
let persistedMessages: TMessage[] | undefined;
try {
const messageQueryKey = [QueryKeys.messages, recoveryConvoId] as const;
@@ -2803,20 +2480,20 @@ export default function useResumableSSE(
queryKey: messageQueryKey,
refetchType: 'none',
});
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
const fetched = await queryClient.fetchQuery<TMessage[]>({
queryKey: messageQueryKey,
});
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
if (Array.isArray(fetched)) {
persistedMessages = fetched;
}
} catch (error) {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
logger.warn('ResumableSSE', 'Could not reconcile terminal messages after disconnect', {
@@ -2837,7 +2514,7 @@ export default function useResumableSSE(
const canRecoverTerminalSteers = generationProtocolVersion === 1 || confirmedV2Terminal;
const unrecovered = canRecoverTerminalSteers ? (status.unrecoveredSteers ?? []) : [];
if (unrecovered.length > 0) {
- const recoverySteerId = getRecoverySteerId(currentSubmission);
+ const recoverySteerId = getRecoverySteerId(sub.submission);
convertSteersToQueued(recoveryConvoId, unrecovered, {
generationProtocolVersion,
...(recoverySteerId != null && {
@@ -2858,17 +2535,17 @@ export default function useResumableSSE(
});
}
- resetLive({ ...currentSubmission, userMessage });
+ resetLive(sub.liveSubmission());
removeActiveJob(currentStreamId);
clearAttachedGenerationCreatedAt();
clearPendingApprovalForTerminal(recoveryConvoId);
if (
- !createdStreamIdsRef.current.has(currentStreamId) &&
- optimisticStreamIdsRef.current.has(currentStreamId)
+ !run.createdStreamIds.has(currentStreamId) &&
+ run.optimisticStreamIds.has(currentStreamId)
) {
removeConvoFromAllQueries(queryClient, currentStreamId);
}
- subscriptionRetired = true;
+ sub.retired = true;
setIsSubmitting(false);
setShowStopButton(false);
let recoveryOutcome: 'completed' | 'aborted' | 'error' = 'error';
@@ -2881,15 +2558,15 @@ export default function useResumableSSE(
recoveryOutcome === 'completed'
? completedResponseMessageId(
persistedMessages,
- userMessage?.messageId,
+ sub.userMessage?.messageId,
status?.resumeState?.responseMessageId ??
- currentSubmission.initialResponse?.messageId,
+ sub.submission.initialResponse?.messageId,
)
: undefined;
setRunEnd({
conversationId: recoveryConvoId,
outcome: recoveryOutcome,
- endedAt: Date.now(),
+ endedAt: run.scheduler.now(),
generationCreatedAt: status.createdAt ?? generationCreatedAt,
...(recoveredResponseMessageId != null && {
responseMessageId: recoveredResponseMessageId,
@@ -2897,9 +2574,8 @@ export default function useResumableSSE(
});
setSubmission(null);
setStreamId(null);
- optimisticStreamIdsRef.current.delete(currentStreamId);
- createdStreamIdsRef.current.delete(currentStreamId);
- reconnectAttemptRef.current = 0;
+ run.releaseStream(currentStreamId);
+ run.reconnectAttempt = 0;
}
};
@@ -2911,28 +2587,25 @@ export default function useResumableSSE(
* connection rather than stranding the pane on its partial content.
*/
const handleClose = () => {
- if (!isCurrentSubscription()) {
+ if (!sub.isCurrent()) {
return;
}
- if (replacementHandoffRef.current) {
+ 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 (reconnectAttemptRef.current > 0) {
+ if (run.reconnectAttempt > 0) {
logger.log('ResumableSSE', 'Stream closed for reconnect - preserving state');
return;
}
logger.log('ResumableSSE', 'Stream aborted (intentional close) - no reconnect');
- cancelSteerRetryFrames();
+ run.cancelSteerRetryFrames();
// Clear any pending reconnect attempts
- if (reconnectTimeoutRef.current) {
- clearTimeout(reconnectTimeoutRef.current);
- reconnectTimeoutRef.current = null;
- }
+ run.clearReconnectTimeout();
// Reset UI state - useResumeOnLoad will restore if user returns to this conversation
setIsSubmitting(false);
setShowStopButton(false);
@@ -2941,7 +2614,7 @@ export default function useResumableSSE(
* 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({ ...currentSubmission, userMessage });
+ 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`
@@ -2950,33 +2623,17 @@ export default function useResumableSSE(
// 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(
- currentSubmission.conversation?.conversationId ?? currentStreamId,
- { statuses: ABORT_SWEEP_STATUSES },
- );
+ convertLocalSteersToQueued(sub.submission.conversation?.conversationId ?? currentStreamId, {
+ statuses: ABORT_SWEEP_STATUSES,
+ });
};
- connection = transport.stream({ token }).reconnectToStream(
- { url, headers: generationProtocolHeaders() },
- {
- signal: streamController.signal,
- onEvent: (event) => {
- switch (event.type) {
- case 'open':
- handleOpen();
- return;
- case 'error':
- void handleTransportFailure(event);
- return;
- case 'abort':
- handleClose();
- return;
- default:
- void handleFrame(event);
- }
- },
- },
- );
+ sub.connect(transport.stream({ token }), {
+ onOpen: handleOpen,
+ onFrame: (event) => void handleFrame(event),
+ onFailure: (event) => void handleTransportFailure(event),
+ onClose: handleClose,
+ });
// Debug hooks for testing reconnection vs clean close behavior (dev only)
if (import.meta.env.DEV) {
@@ -2994,12 +2651,13 @@ export default function useResumableSSE(
/** Simulate clean close (navigation away) - triggers abort event → no reconnection */
debugWindow.__closeClean = () => {
logger.log('Debug', 'Simulating clean close (navigation away)...');
- subscriptionRetired = true;
- closeStream();
+ sub.retired = true;
+ sub.close();
};
}
},
[
+ run,
isAddedRequest,
setConversation,
runIndex,
@@ -3076,7 +2734,7 @@ export default function useResumableSSE(
let requestAttempts = 0;
let networkAttempts = 0;
let readinessAttempts = 0;
- const readinessDeadline = Date.now() + START_GENERATION_READINESS_TIMEOUT_MS;
+ const readinessDeadline = run.scheduler.now() + START_GENERATION_READINESS_TIMEOUT_MS;
while (!signal?.aborted) {
const recoverySteerId = getRecoverySteerId(currentSubmission);
@@ -3184,7 +2842,7 @@ export default function useResumableSSE(
lastError = error;
const isNetworkError = isRetryableNetworkError(error);
const isServerNotReady = isServerNotReadyError(error);
- const remainingReadinessMs = readinessDeadline - Date.now();
+ const remainingReadinessMs = readinessDeadline - run.scheduler.now();
const shouldRetryNetwork =
isNetworkError && networkAttempts < START_GENERATION_NETWORK_RETRIES - 1;
const shouldRetryServerNotReady = isServerNotReady && remainingReadinessMs > 0;
@@ -3294,6 +2952,7 @@ export default function useResumableSSE(
return null;
},
[
+ run,
clearStepMaps,
convertSteersToQueued,
errorHandler,
@@ -3312,18 +2971,15 @@ export default function useResumableSSE(
if (!submission || Object.keys(submission).length === 0) {
logger.log('ResumableSSE', 'No submission, cleaning up');
// Clear reconnect timeout if submission is cleared
- if (reconnectTimeoutRef.current) {
- clearTimeout(reconnectTimeoutRef.current);
- reconnectTimeoutRef.current = null;
- }
- stopForegroundReattachRef.current?.();
- stopForegroundReattachRef.current = null;
+ run.clearReconnectTimeout();
+ run.stopForegroundReattach?.();
+ run.stopForegroundReattach = null;
// Close SSE but do NOT dispatch cancel - navigation should not abort
- streamRef.current?.abort();
- streamRef.current = null;
+ run.stream?.abort();
+ run.stream = null;
setStreamId(null);
- reconnectAttemptRef.current = 0;
- submissionRef.current = null;
+ run.reconnectAttempt = 0;
+ run.submission = null;
return;
}
@@ -3343,10 +2999,10 @@ export default function useResumableSSE(
userMessageId: submission.userMessage?.messageId,
});
- submissionRef.current = submission;
- runEndPublishedRef.current = false;
- identityConfirmedRef.current = false;
- subscribedEpochRef.current = null;
+ run.submission = submission;
+ run.runEndPublished = false;
+ run.identityConfirmed = false;
+ run.subscribedEpoch = null;
if (submission.conversation?.conversationId != null) {
/** A different run starting here owns the conversation's end from now on: an earlier run
* this pane left is superseded, and a Stop belonged to that earlier run. Reattaching to
@@ -3369,7 +3025,7 @@ export default function useResumableSSE(
}
const startController = new AbortController();
const { signal } = startController;
- const isCurrentEffect = () => !signal.aborted && submissionRef.current === submission;
+ const isCurrentEffect = () => !signal.aborted && run.submission === submission;
const initStream = async () => {
if (!isCurrentEffect()) {
@@ -3399,14 +3055,14 @@ export default function useResumableSSE(
setStreamId(resumeStreamId);
// Optimistically add to active jobs (in case it's not already there)
addActiveJob(resumeStreamId);
- subscribeToStream(
- resumeStreamId,
+ subscribeToStream({
+ streamId: resumeStreamId,
submission,
- true,
- resumeGenerationCreatedAt,
- resumeGenerationProtocolVersion,
+ isResume: true,
+ generationCreatedAt: resumeGenerationCreatedAt,
+ generationProtocolVersion: resumeGenerationProtocolVersion,
signal,
- );
+ });
} else {
// New generation: start and then subscribe
logger.log('ResumableSSE', 'Starting NEW generation');
@@ -3533,7 +3189,7 @@ export default function useResumableSSE(
});
}
clearDrainAfterAbort(startResult.conversationId, expectedPredecessorCreatedAt);
- submissionRef.current = null;
+ run.submission = null;
setIsSubmitting(false);
setShowStopButton(false);
setSubmission(null);
@@ -3630,7 +3286,7 @@ export default function useResumableSSE(
);
addActiveJob(replacementStart.streamId);
if (startedAsNewConvo) {
- optimisticStreamIdsRef.current.add(replacementStart.streamId);
+ run.optimisticStreamIds.add(replacementStart.streamId);
updateActiveGenerationCreatedAt(
Constants.NEW_CONVO,
replacementStart.generationCreatedAt,
@@ -3650,8 +3306,8 @@ export default function useResumableSSE(
replacementStatus.resumeState?.aggregatedContent ??
replacementStatus.aggregatedContent,
);
- replacementHandoffRef.current = true;
- submissionRef.current = null;
+ run.replacementHandoff = true;
+ run.submission = null;
setIsSubmitting(true);
setShowStopButton(true);
setSubmission(null);
@@ -3677,7 +3333,7 @@ export default function useResumableSSE(
setRunEnd({
conversationId: replacementStart.conversationId,
outcome: 'error',
- endedAt: Date.now(),
+ endedAt: run.scheduler.now(),
generationCreatedAt: replacementStart.generationCreatedAt,
});
setSubmission(null);
@@ -3809,7 +3465,7 @@ export default function useResumableSSE(
conversationId: settledConversationId,
outcome: conversationLookup === 'inconclusive' ? 'error' : 'aborted',
startedAsNewConvo,
- endedAt: Date.now(),
+ endedAt: run.scheduler.now(),
});
setSubmission(null);
return;
@@ -3834,21 +3490,21 @@ export default function useResumableSSE(
queueTitleGeneration(newStreamId);
}
if (isInitialNewConversation(submission)) {
- optimisticStreamIdsRef.current.add(newStreamId);
+ run.optimisticStreamIds.add(newStreamId);
replaceNewConversationUrl(newStreamId);
}
const streamSubmission = addOptimisticConversation(newStreamId, submission);
- submissionRef.current = streamSubmission;
+ run.submission = streamSubmission;
// A deduped retry (status: 'resumed') attaches to an already-running stream, so
// subscribe with resume=true to replay its state instead of only live events.
- subscribeToStream(
- newStreamId,
- streamSubmission,
- resumed,
+ subscribeToStream({
+ streamId: newStreamId,
+ submission: streamSubmission,
+ isResume: resumed,
generationCreatedAt,
generationProtocolVersion,
signal,
- );
+ });
} else {
logger.error('ResumableSSE', 'Failed to get streamId from startGeneration');
}
@@ -3865,51 +3521,32 @@ export default function useResumableSSE(
setSubmission(null);
});
- /** The Set object itself is never reassigned, so this alias reads the
- * LIVE frame ids at cleanup time (satisfies react-hooks/exhaustive-deps
- * without changing behavior). */
- const activityLabelRetryFrames = activityLabelRetryFramesRef.current;
- const steerRetryFrames = steerRetryFramesRef.current;
return () => {
logger.log('ResumableSSE', 'Cleanup - closing SSE, resetting UI state');
startController.abort();
// Cleanup on unmount/navigation - close connection but DO NOT abort backend
// Reset UI state so it doesn't leak to other conversations
// If user returns to this conversation, useResumeOnLoad will restore the state
- if (reconnectTimeoutRef.current) {
- clearTimeout(reconnectTimeoutRef.current);
- reconnectTimeoutRef.current = null;
- }
- if (pendingActionRetryRef.current != null) {
- cancelAnimationFrame(pendingActionRetryRef.current);
- pendingActionRetryRef.current = null;
- }
- for (const frameId of activityLabelRetryFrames) {
- cancelAnimationFrame(frameId);
- }
- activityLabelRetryFrames.clear();
- for (const frameId of steerRetryFrames) {
- cancelAnimationFrame(frameId);
- }
- steerRetryFrames.clear();
- stopForegroundReattachRef.current?.();
- stopForegroundReattachRef.current = null;
+ run.clearReconnectTimeout();
+ run.cancelRetryFrames();
+ run.stopForegroundReattach?.();
+ run.stopForegroundReattach = null;
// Reset reconnect counter before closing (so abort handler doesn't think we're reconnecting)
- reconnectAttemptRef.current = 0;
+ run.reconnectAttempt = 0;
/** The pane is moving off a run that is still generating (another chat, a new chat, or
* an unmount): the server keeps going with no subscriber and deletes the job when done,
* so no terminal event will reach the queue drain. Remember the run; on return its end is
* read from history. Only a run whose identity the server confirmed (its epoch, and the
* user message `created` or a resume's sync named) is remembered, and not a regeneration,
* a run that already published its end, or one the user stopped. */
- const closing = submissionRef.current;
+ const closing = run.submission;
const closingConvoId = closing?.conversation?.conversationId;
const closingUserMessageId = closing?.userMessage?.messageId;
- const generationCreatedAt = subscribedEpochRef.current;
+ const generationCreatedAt = run.subscribedEpoch;
if (
- streamRef.current != null &&
- identityConfirmedRef.current &&
- !runEndPublishedRef.current &&
+ run.stream != null &&
+ run.identityConfirmed &&
+ !run.runEndPublished &&
closing?.isRegenerate !== true &&
closingConvoId != null &&
closingConvoId !== Constants.NEW_CONVO &&
@@ -3923,18 +3560,18 @@ export default function useResumableSSE(
generationCreatedAt,
});
}
- streamRef.current?.abort();
- streamRef.current = null;
+ run.stream?.abort();
+ run.stream = null;
// Clear handler maps to prevent memory leaks and stale state
clearStepMaps();
// Reset UI state on ordinary cleanup. A generation handoff already
// cached the replacement and must remain non-idle until resume-on-load
// installs its epoch-fenced submission.
- if (!replacementHandoffRef.current) {
+ if (!run.replacementHandoff) {
setIsSubmitting(false);
setShowStopButton(false);
}
- replacementHandoffRef.current = false;
+ run.replacementHandoff = false;
};
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [submission]);
diff --git a/packages/chat/src/core/__tests__/subscription.spec.ts b/packages/chat/src/core/__tests__/subscription.spec.ts
new file mode 100644
index 0000000000..23ca110a63
--- /dev/null
+++ b/packages/chat/src/core/__tests__/subscription.spec.ts
@@ -0,0 +1,235 @@
+import type {
+ TMessage,
+ ChatEvent,
+ TSubmission,
+ ChatTransport,
+ ChatTransportOptions,
+} from 'librechat-data-provider';
+import type {
+ PageVisibility,
+ ResumableScheduler,
+ SubscriptionTarget,
+ StreamStatusResponse,
+} from '../resumable';
+import { ResumableRun, ResumableSubscription } from '../resumable';
+
+/** Timers and frames that run only when the test says so. */
+const createScheduler = () => {
+ let now = 0;
+ const timers = new Map<number, { at: number; callback: () => void }>();
+ let nextId = 1;
+ const scheduler: ResumableScheduler = {
+ setTimeout: (callback, delay) => {
+ const id = nextId++;
+ timers.set(id, { at: now + delay, callback });
+ return id as unknown as ReturnType<typeof setTimeout>;
+ },
+ clearTimeout: (handle) => {
+ timers.delete(handle as unknown as number);
+ },
+ requestFrame: () => nextId++,
+ cancelFrame: () => undefined,
+ now: () => now,
+ };
+ const advance = (ms: number) => {
+ now += ms;
+ for (const [id, timer] of [...timers]) {
+ if (timer.at <= now) {
+ timers.delete(id);
+ timer.callback();
+ }
+ }
+ };
+ return { scheduler, advance, pending: () => timers.size };
+};
+
+const createVisibility = () => {
+ let visible = true;
+ const listeners = new Set<() => void>();
+ const visibility: PageVisibility = {
+ isVisible: () => visible,
+ subscribe: (listener) => {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+ },
+ };
+ const show = () => {
+ visible = true;
+ listeners.forEach((listener) => listener());
+ };
+ return { visibility, show, listeners };
+};
+
+const submission = {
+ userMessage: { messageId: 'u-1', conversationId: 'c-1' } as TMessage,
+ initialResponse: { messageId: 'u-1_', conversationId: 'c-1' } as TMessage,
+ conversation: { conversationId: 'c-1' },
+} as TSubmission;
+
+const setup = (overrides: Partial<SubscriptionTarget> = {}) => {
+ const clock = createScheduler();
+ const page = createVisibility();
+ const run = new ResumableRun(clock.scheduler);
+ const fetchStatus = jest.fn<Promise<StreamStatusResponse>, [string]>();
+ const subscribe = jest.fn<void, [SubscriptionTarget]>();
+ const logger = { log: jest.fn(), warn: jest.fn(), error: jest.fn() };
+ const target: SubscriptionTarget = {
+ streamId: 'c-1',
+ submission,
+ isResume: false,
+ generationCreatedAt: 2000,
+ generationProtocolVersion: 2,
+ ...overrides,
+ };
+ run.submission = target.submission;
+ const sub = new ResumableSubscription(
+ run,
+ { logger, visibility: page.visibility, fetchStatus, subscribe },
+ target,
+ );
+ return { run, sub, clock, page, fetchStatus, subscribe };
+};
+
+describe('ResumableSubscription', () => {
+ it('is current only while it holds the pane, its submission and its lifecycle', () => {
+ const controller = new AbortController();
+ const { run, sub } = setup({ signal: controller.signal });
+ expect(sub.isCurrent()).toBe(false);
+ sub.claim();
+ expect(sub.isCurrent()).toBe(true);
+
+ sub.replaceSubmission({ ...submission, isRegenerate: true });
+ expect(run.submission).toBe(sub.submission);
+ expect(sub.isCurrent()).toBe(true);
+
+ run.submission = submission;
+ expect(sub.isCurrent()).toBe(false);
+ run.submission = sub.submission;
+ controller.abort();
+ expect(sub.isCurrent()).toBe(false);
+ });
+
+ it('builds the stream route with the resume cursor and generation fence', () => {
+ const { sub } = setup({ streamId: 'c 1', isResume: true });
+ const url = new URL(sub.url(), 'http://localhost');
+ expect(url.pathname).toBe('/api/agents/chat/stream/c%201');
+ expect(Object.fromEntries(url.searchParams)).toEqual({
+ resume: 'true',
+ generationCreatedAt: '2000',
+ generationProtocolVersion: '2',
+ });
+ });
+
+ it('routes connection events to their handlers', () => {
+ const { sub } = setup();
+ let options: ChatTransportOptions | undefined;
+ const transport = {
+ send: jest.fn(),
+ reconnectToStream: jest.fn((_request, opts: ChatTransportOptions) => {
+ options = opts;
+ return { closed: false };
+ }),
+ } as ChatTransport;
+ const handlers = {
+ onOpen: jest.fn(),
+ onFrame: jest.fn(),
+ onFailure: jest.fn(),
+ onClose: jest.fn(),
+ };
+ sub.connect(transport, handlers);
+
+ const emit = (event: ChatEvent) => options?.onEvent(event);
+ emit({ type: 'open' } as ChatEvent);
+ emit({ type: 'error', status: 0 });
+ emit({ type: 'abort' });
+ emit({ type: 'title', data: { event: 'title', data: { title: 't' } } } as ChatEvent);
+ expect(handlers.onOpen).toHaveBeenCalledTimes(1);
+ expect(handlers.onFailure).toHaveBeenCalledWith({ type: 'error', status: 0 });
+ expect(handlers.onClose).toHaveBeenCalledTimes(1);
+ expect(handlers.onFrame).toHaveBeenCalledTimes(1);
+ expect(transport.reconnectToStream).toHaveBeenCalledWith(
+ expect.objectContaining({ headers: { 'X-LibreChat-Generation-Protocol': '2' } }),
+ expect.objectContaining({ signal: sub.controller.signal }),
+ );
+ });
+
+ it('re-attaches after a delay only while it is still current', () => {
+ const { run, sub, clock, subscribe } = setup();
+ sub.claim();
+ sub.scheduleReattach(1000);
+ clock.advance(999);
+ expect(subscribe).not.toHaveBeenCalled();
+ clock.advance(1);
+ expect(subscribe).toHaveBeenCalledWith(
+ expect.objectContaining({ streamId: 'c-1', isResume: true, generationCreatedAt: 2000 }),
+ );
+
+ sub.scheduleReattach(1000, 'c-2', 3000);
+ run.stream = new AbortController();
+ clock.advance(1000);
+ expect(subscribe).toHaveBeenCalledTimes(1);
+ });
+
+ it('re-attaches on foreground when the connection closed while hidden', () => {
+ const { run, sub, page, subscribe } = setup();
+ sub.claim();
+ sub.connection = { closed: true };
+ sub.watchForeground();
+ run.reconnectAttempt = 0;
+ page.show();
+ expect(sub.controller.signal.aborted).toBe(true);
+ expect(run.reconnectAttempt).toBe(1);
+ expect(subscribe).toHaveBeenCalledWith(expect.objectContaining({ isResume: true }));
+ });
+
+ it('re-attaches on foreground when the status proves an open connection terminal', async () => {
+ const { sub, page, fetchStatus, subscribe } = setup();
+ sub.claim();
+ sub.connection = { closed: false };
+ sub.watchForeground();
+ fetchStatus.mockResolvedValueOnce({ active: true, createdAt: 2000 });
+ page.show();
+ await new Promise((resolve) => setImmediate(resolve));
+ expect(subscribe).not.toHaveBeenCalled();
+
+ fetchStatus.mockResolvedValueOnce({ active: false, createdAt: 2000 });
+ page.show();
+ await new Promise((resolve) => setImmediate(resolve));
+ expect(fetchStatus).toHaveBeenLastCalledWith('c-1');
+ expect(subscribe).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps one foreground listener per pane', () => {
+ const { run, sub, page } = setup();
+ sub.watchForeground();
+ const second = new ResumableSubscription(run, sub.host, {
+ streamId: 'c-1',
+ submission,
+ isResume: true,
+ generationProtocolVersion: 2,
+ });
+ second.watchForeground();
+ expect(page.listeners.size).toBe(1);
+ });
+});
+
+describe('ResumableRun', () => {
+ it('drops the cleared edit prefix only when a new generation binds', () => {
+ const run = new ResumableRun(createScheduler().scheduler);
+ run.bindPrefixState('gen-1');
+ run.editPrefixCleared = true;
+ run.bindPrefixState('gen-1');
+ expect(run.editPrefixCleared).toBe(true);
+ run.bindPrefixState('gen-2');
+ expect(run.editPrefixCleared).toBe(false);
+ });
+
+ it('clears a pending reattach', () => {
+ const clock = createScheduler();
+ const run = new ResumableRun(clock.scheduler);
+ run.reconnectTimeout = clock.scheduler.setTimeout(() => undefined, 1000);
+ run.clearReconnectTimeout();
+ expect(run.reconnectTimeout).toBeNull();
+ expect(clock.pending()).toBe(0);
+ });
+});
diff --git a/packages/chat/src/core/protocol.ts b/packages/chat/src/core/protocol.ts
index bee0e5e4f7..88e1ea2fd9 100644
--- a/packages/chat/src/core/protocol.ts
+++ b/packages/chat/src/core/protocol.ts
@@ -1,4 +1,5 @@
export const GENERATION_PROTOCOL_VERSION = 2 as const;
+export const GENERATION_PROTOCOL_HEADER = 'X-LibreChat-Generation-Protocol';
export type GenerationProtocolVersion = 1 | typeof GENERATION_PROTOCOL_VERSION;
@@ -22,3 +23,7 @@ export const getGenerationProtocolVersion = (value: unknown): GenerationProtocol
export const supportsGenerationProtocolV2 = (value: unknown): boolean =>
getGenerationProtocolVersion(value) === GENERATION_PROTOCOL_VERSION;
+
+export const generationProtocolHeaders = (): Record<string, string> => ({
+ [GENERATION_PROTOCOL_HEADER]: String(GENERATION_PROTOCOL_VERSION),
+});
diff --git a/packages/chat/src/core/resumable/host.ts b/packages/chat/src/core/resumable/host.ts
new file mode 100644
index 0000000000..6527420307
--- /dev/null
+++ b/packages/chat/src/core/resumable/host.ts
@@ -0,0 +1,55 @@
+import type { Agents, TPendingSteer } from 'librechat-data-provider';
+
+/** Where a resumable run reports what it is doing. The app passes its own logger. */
+export interface ResumableLogger {
+ log: (...args: unknown[]) => void;
+ warn: (...args: unknown[]) => void;
+ error: (...args: unknown[]) => void;
+}
+
+/** Whether the page is in the foreground, and a way to hear when that changes. */
+export interface PageVisibility {
+ isVisible: () => boolean;
+ /** Calls `listener` on every visibility change; returns the unsubscribe. */
+ subscribe: (listener: () => void) => () => void;
+}
+
+/** The document's own visibility. */
+export const documentVisibility: PageVisibility = {
+ isVisible: () => document.visibilityState === 'visible',
+ subscribe: (listener) => {
+ document.addEventListener('visibilitychange', listener);
+ return () => document.removeEventListener('visibilitychange', listener);
+ },
+};
+
+/** The status route's answer for a conversation's generation. */
+export interface StreamStatusResponse {
+ /** Exact protocol selected by the job. Missing/1 is always legacy. */
+ generationProtocolVersion?: number;
+ active: boolean;
+ /** Client-local cache marker used to force useResumeOnLoad to replace a
+ * stale generation attachment with the newer epoch occupying this stream. */
+ generationHandoff?: boolean;
+ streamId?: string;
+ status?: 'running' | 'complete' | 'error' | 'aborted' | 'requires_action';
+ aggregatedContent?: Array<{ type: string; text?: string }>;
+ createdAt?: number;
+ /** Generation age computed on the server's clock, so a reattaching client
+ * can rebuild a clock-local elapsed baseline free of cross-machine skew. */
+ elapsedMs?: number;
+ resumeState?: Agents.ResumeState;
+ /** The run's temporary state as the server recorded it at admission, so a rebuilt
+ * submission keeps a hidden chat out of history and titling after a reload. */
+ isTemporary?: boolean;
+ /** Live pending approval when `status === 'requires_action'`; mirrors
+ * `resumeState.pendingAction`, surfaced top-level for the resume-on-load path. */
+ pendingAction?: Agents.PendingAction;
+ /** Acknowledged steers a terminal drain parked because no subscriber was
+ * live for the final/abort event. Reads are replayable until an exact
+ * recovery turn persists or the user discards the item. */
+ unrecoveredSteers?: TPendingSteer[];
+}
+
+/** Reads a conversation's generation status. */
+export type FetchStreamStatus = (conversationId: string) => Promise<StreamStatusResponse>;
diff --git a/packages/chat/src/core/resumable/index.ts b/packages/chat/src/core/resumable/index.ts
index d519a3e604..db6cbf6b09 100644
--- a/packages/chat/src/core/resumable/index.ts
+++ b/packages/chat/src/core/resumable/index.ts
@@ -3,3 +3,6 @@ export * from './errors';
export * from './events';
export * from './resume';
export * from './messages';
+export * from './run';
+export * from './host';
+export * from './subscription';
diff --git a/packages/chat/src/core/resumable/run.ts b/packages/chat/src/core/resumable/run.ts
new file mode 100644
index 0000000000..cca3327408
--- /dev/null
+++ b/packages/chat/src/core/resumable/run.ts
@@ -0,0 +1,132 @@
+import type { TSubmission } from 'librechat-data-provider';
+
+/** A pending timer, as the scheduler that set it returns it. */
+export type TimerHandle = ReturnType<typeof setTimeout>;
+
+/**
+ * The clock and frame source a resumable run waits on. The browser supplies its globals; a test
+ * or another runtime supplies its own.
+ */
+export interface ResumableScheduler {
+ setTimeout: (callback: () => void, delay: number) => TimerHandle;
+ clearTimeout: (handle: TimerHandle) => void;
+ requestFrame: (callback: () => void) => number;
+ cancelFrame: (handle: number) => void;
+ now: () => number;
+}
+
+/** The browser's timers and animation frames. */
+export const browserScheduler: ResumableScheduler = {
+ setTimeout: (callback, delay) => setTimeout(callback, delay),
+ clearTimeout: (handle) => clearTimeout(handle),
+ requestFrame: (callback) => requestAnimationFrame(callback),
+ cancelFrame: (handle) => cancelAnimationFrame(handle),
+ now: () => Date.now(),
+};
+
+/**
+ * What one chat pane knows about the generation it is attached to, across every submission and
+ * reconnect: the live connection and its retry ladder, the submission it serves, the stream ids
+ * it created optimistically, and the frame retries still waiting on a response placeholder.
+ * The pane owns one for its lifetime; every subscription reads and fences against it.
+ */
+export class ResumableRun {
+ /** Closes the live connection; replaced by every subscription. */
+ stream: AbortController | null = null;
+ /** Removes the foreground re-attach listener owned by the newest subscription; exactly one
+ * is registered at a time. */
+ stopForegroundReattach: (() => void) | null = null;
+ reconnectAttempt = 0;
+ reconnectTimeout: TimerHandle | null = null;
+ /** The submission this pane serves; a subscription whose submission is no longer this one is
+ * stale. */
+ submission: TSubmission | null = null;
+ /** Suppresses the normal close/cleanup idle transition while a stale generation is being
+ * atomically handed off to its live replacement. */
+ replacementHandoff = false;
+ readonly optimisticStreamIds: Set<string> = new Set();
+ readonly createdStreamIds: Set<string> = new Set();
+ /** Pending action whose tool-call content part hasn't rendered yet, retried on the next frame
+ * so a fast pause-before-render race still attaches. */
+ pendingActionRetry: number | null = null;
+ /** EVERY steer retry frame, not only the newest one. Several steers can be applied before
+ * their shared response placeholder renders; retaining one handle let the older chains
+ * outlive navigation/terminal cleanup and mutate a later generation that reused the same
+ * response id. */
+ readonly steerRetryFrames: Set<number> = new Set();
+ /** EVERY outstanding label-retry frame, not a single handle: labels fire two events per slot
+ * (reservation, then fill), so concurrent retry chains are the norm: a single handle would
+ * let cleanup cancel only the newest chain while the others kept running for up to 120
+ * frames and could apply a stale label to a replacement generation that reuses the same
+ * response id (edits do). */
+ readonly activityLabelRetryFrames: Set<number> = new Set();
+ /**
+ * Set once a SYNC has replaced the response with the server's completion-local snapshot,
+ * which discards the prefix an edited resubmission retained. From that point incoming indices
+ * are absolute and `editPrefixLength` must no longer be applied, by run steps or labels.
+ */
+ editPrefixCleared = false;
+ editPrefixFirstPartFolded = false;
+ /** Generation the cleared-prefix state above belongs to, so it is dropped when a new
+ * generation starts rather than when a subscribe happens to be live. */
+ prefixStateGenerationId: string | null = null;
+ /** The generation epoch the pane's stream is attached to, kept so a run left mid-stream can
+ * carry it. A server that reports no epoch leaves it unset. */
+ subscribedEpoch: number | null = null;
+ /** Whether the current submission's run end already reached the queue drain. A run that
+ * ended attached must not also be resolved as detached when the user later leaves. */
+ runEndPublished = false;
+ /** Whether the server named the current submission's user message (`created`, or a resume's
+ * sync). Only a run whose identity it confirmed is remembered when the user leaves. */
+ identityConfirmed = false;
+
+ constructor(readonly scheduler: ResumableScheduler = browserScheduler) {}
+
+ /** Drops the backoff still waiting to re-attach, if any. */
+ clearReconnectTimeout(): void {
+ if (this.reconnectTimeout) {
+ this.scheduler.clearTimeout(this.reconnectTimeout);
+ this.reconnectTimeout = null;
+ }
+ }
+
+ cancelSteerRetryFrames(): void {
+ for (const frameId of this.steerRetryFrames) {
+ this.scheduler.cancelFrame(frameId);
+ }
+ this.steerRetryFrames.clear();
+ }
+
+ /** Cancels every frame retry still waiting on a response placeholder. */
+ cancelRetryFrames(): void {
+ if (this.pendingActionRetry != null) {
+ this.scheduler.cancelFrame(this.pendingActionRetry);
+ this.pendingActionRetry = null;
+ }
+ for (const frameId of this.activityLabelRetryFrames) {
+ this.scheduler.cancelFrame(frameId);
+ }
+ this.activityLabelRetryFrames.clear();
+ this.cancelSteerRetryFrames();
+ }
+
+ /**
+ * A NEW generation starts with its retained prefix intact, so the cleared-prefix state from a
+ * previous one must not carry over. Keyed on the submission's `clientRequestId`, which is new
+ * per edit attempt and stable across reconnects.
+ */
+ bindPrefixState(generationId: string): void {
+ if (this.prefixStateGenerationId === generationId) {
+ return;
+ }
+ this.prefixStateGenerationId = generationId;
+ this.editPrefixCleared = false;
+ this.editPrefixFirstPartFolded = false;
+ }
+
+ /** Forgets a stream once its run has ended. */
+ releaseStream(streamId: string): void {
+ this.optimisticStreamIds.delete(streamId);
+ this.createdStreamIds.delete(streamId);
+ }
+}
diff --git a/packages/chat/src/core/resumable/subscription.ts b/packages/chat/src/core/resumable/subscription.ts
new file mode 100644
index 0000000000..039f493bdf
--- /dev/null
+++ b/packages/chat/src/core/resumable/subscription.ts
@@ -0,0 +1,296 @@
+import { apiBaseUrl } from 'librechat-data-provider';
+import type {
+ TMessage,
+ ChatEvent,
+ TSubmission,
+ ChatTransport,
+ ChatStreamConnection,
+} from 'librechat-data-provider';
+import type { ResumableLogger, PageVisibility, FetchStreamStatus } from './host';
+import type { GenerationProtocolVersion } from '../protocol';
+import type { StepEvent } from '../reducer';
+import type { ResumableRun } from './run';
+import { GENERATION_PROTOCOL_VERSION, generationProtocolHeaders } from '../protocol';
+
+/** The generation one subscription attaches to, and how. */
+export interface SubscriptionTarget {
+ streamId: string;
+ submission: TSubmission;
+ /** Asks the server to replay the run's state (`sync`) before live events. */
+ isResume: boolean;
+ generationCreatedAt?: number;
+ generationProtocolVersion: GenerationProtocolVersion;
+ /** The pane's lifecycle: once aborted, nothing this subscription does lands. */
+ signal?: AbortSignal;
+}
+
+/** How a subscription reaches the stream and decides when to re-attach. */
+export interface SubscriptionHost {
+ logger: ResumableLogger;
+ visibility: PageVisibility;
+ fetchStatus: FetchStreamStatus;
+ /** Attaches a fresh subscription to `target`; how a subscription re-attaches itself. */
+ subscribe: (target: SubscriptionTarget) => void;
+}
+
+/** What a subscription does with the events its connection reports. */
+export interface SubscriptionHandlers {
+ onOpen: () => void;
+ onFrame: (event: ChatEvent) => void;
+ onFailure: (event: Extract<ChatEvent, { type: 'error' }>) => void;
+ onClose: () => void;
+}
+
+/**
+ * One attachment of a pane to a running generation: the connection, the submission as the
+ * stream has revised it so far, and the fences that make every late callback a no-op once a
+ * newer attachment, submission or pane lifecycle has taken over.
+ */
+export class ResumableSubscription {
+ readonly streamId: string;
+ readonly isResume: boolean;
+ readonly generationCreatedAt?: number;
+ readonly generationProtocolVersion: GenerationProtocolVersion;
+ readonly signal?: AbortSignal;
+ /** Whether the pane created this stream's conversation optimistically, from `/c/new`. */
+ readonly startedAsNewConversation: boolean;
+ /** Closing is per connection: the transport tells this subscription's own close (`abort`)
+ * apart from a cancel by the user agent (`error` with status 0). */
+ readonly controller: AbortController = new AbortController();
+ submission: TSubmission;
+ userMessage: TMessage;
+ textIndex: number | null = null;
+ finalReceived = false;
+ /**
+ * This subscription must never be revived. Set by the terminal recoveries that do not ride a
+ * FINAL or served-error frame (the 404 and retry-ceiling reconciles both leave the attachment
+ * pointing at a stream the server no longer has) and by the dev-only navigation simulator.
+ * `finalReceived` covers the frame-carried terminals.
+ */
+ retired = false;
+ /** Step events that arrived before `created` named the turn, replayed once it does. */
+ readonly preCreatedStepEvents: StepEvent[] = [];
+ connection: ChatStreamConnection | null = null;
+ private foregroundStatusCheckInFlight = false;
+
+ constructor(
+ readonly run: ResumableRun,
+ readonly host: SubscriptionHost,
+ target: SubscriptionTarget,
+ ) {
+ this.streamId = target.streamId;
+ this.isResume = target.isResume;
+ this.generationCreatedAt = target.generationCreatedAt;
+ this.generationProtocolVersion = target.generationProtocolVersion;
+ this.signal = target.signal;
+ this.submission = target.submission;
+ this.userMessage = target.submission.userMessage;
+ this.startedAsNewConversation = run.optimisticStreamIds.has(target.streamId);
+ }
+
+ /**
+ * Every pane lifecycle owns one AbortSignal, while every reconnect owns one connection. Both
+ * identities matter: cleanup can close an attachment after its async listener has already
+ * crossed an `await`, and a reconnect can supersede an older attachment without changing the
+ * submission object. The submission check is the final fence against a later conversation
+ * installing its own submission in this pane.
+ */
+ isCurrent(): boolean {
+ return (
+ this.signal?.aborted !== true &&
+ this.run.stream === this.controller &&
+ this.run.submission === this.submission
+ );
+ }
+
+ /** The submission with the user message as the stream has named it so far. */
+ liveSubmission(): TSubmission {
+ return { ...this.submission, userMessage: this.userMessage };
+ }
+
+ /** Adopts a revised submission as the one this subscription and its pane serve. */
+ replaceSubmission(next: TSubmission): void {
+ this.submission = next;
+ this.run.submission = next;
+ }
+
+ close(): void {
+ this.controller.abort();
+ }
+
+ /** The conversation this subscription's run belongs to, as far as it is known. */
+ conversationId(): string {
+ return this.submission.conversation?.conversationId ?? this.streamId;
+ }
+
+ /** Re-attaches now, with the run's state replayed. */
+ reattach(): void {
+ this.host.subscribe(this.resumeTarget(this.submission));
+ }
+
+ /**
+ * Re-attaches after `delay` with the run's state replayed, unless a newer attachment or
+ * submission takes over first. A different stream or epoch is passed when the status read
+ * that scheduled it named one.
+ */
+ scheduleReattach(
+ delay: number,
+ streamId: string = this.streamId,
+ generationCreatedAt: number | undefined = this.generationCreatedAt,
+ ): void {
+ this.run.reconnectTimeout = this.run.scheduler.setTimeout(() => {
+ if (this.isCurrent() && this.run.submission) {
+ this.host.subscribe({
+ ...this.resumeTarget(this.run.submission),
+ streamId,
+ generationCreatedAt,
+ });
+ }
+ }, delay);
+ }
+
+ private resumeTarget(submission: TSubmission): SubscriptionTarget {
+ return {
+ streamId: this.streamId,
+ submission,
+ isResume: true,
+ generationCreatedAt: this.generationCreatedAt,
+ generationProtocolVersion: this.generationProtocolVersion,
+ signal: this.signal,
+ };
+ }
+
+ /** The stream route, with the resume cursor and generation fence in its query. */
+ url(): string {
+ const baseUrl = `${apiBaseUrl()}/api/agents/chat/stream/${encodeURIComponent(this.streamId)}`;
+ const query = new URLSearchParams();
+ if (this.isResume) {
+ query.set('resume', 'true');
+ }
+ if (this.generationCreatedAt != null) {
+ query.set('generationCreatedAt', String(this.generationCreatedAt));
+ }
+ query.set('generationProtocolVersion', String(GENERATION_PROTOCOL_VERSION));
+ const queryString = query.toString();
+ return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+ }
+
+ /** Makes this the pane's live attachment, superseding any earlier one. */
+ claim(): void {
+ this.run.stream = this.controller;
+ }
+
+ /** Opens the connection and routes its events to `handlers`. */
+ connect(transport: ChatTransport, handlers: SubscriptionHandlers): void {
+ this.connection = transport.reconnectToStream(
+ { url: this.url(), headers: generationProtocolHeaders() },
+ {
+ signal: this.controller.signal,
+ onEvent: (event) => {
+ switch (event.type) {
+ case 'open':
+ handlers.onOpen();
+ return;
+ case 'error':
+ handlers.onFailure(event);
+ return;
+ case 'abort':
+ handlers.onClose();
+ return;
+ default:
+ handlers.onFrame(event);
+ }
+ },
+ },
+ );
+ }
+
+ private reattachOnForeground(): void {
+ this.host.logger.log('ResumableSSE', 'Re-attaching stream on foreground');
+ /** Any backoff still pending targets this same attachment, so returning to the app
+ * supersedes it rather than waiting the delay out; its callback finds a superseded
+ * subscription and does nothing. */
+ this.run.clearReconnectTimeout();
+ this.run.reconnectAttempt = Math.max(this.run.reconnectAttempt, 1);
+ this.close();
+ this.reattach();
+ }
+
+ private isSettled(): boolean {
+ return this.finalReceived || this.retired || this.run.replacementHandoff;
+ }
+
+ /**
+ * A suspended page can lose its stream without the transport ever reporting it. When a
+ * mobile browser freezes the tab, an intermediary closes the response body underneath it,
+ * and XHR surfaces that as an ordinary load: sse.js dispatches nothing for a body that simply
+ * ends, so neither the error nor the abort recovery ever runs. Nothing else re-reads the
+ * conversation while the pane stays mounted, which is why the response the run finished
+ * writing only appears after a reload.
+ *
+ * Some mobile WebViews leave the XHR marked OPEN even after the suspended request stopped
+ * delivering events. In that case the durable run status is the only authority that
+ * distinguishes a healthy live attachment from a terminal one holding stale partial content.
+ * A terminal status forces the same resume path as a closed transport; it returns the
+ * synthesized terminal frame or 404 that reconciles persisted messages.
+ */
+ private handleForegroundReattach(): void {
+ const { visibility, fetchStatus, logger } = this.host;
+ if (!visibility.isVisible() || this.isSettled() || !this.isCurrent() || !this.run.submission) {
+ return;
+ }
+
+ if (this.connection?.closed === true) {
+ this.reattachOnForeground();
+ return;
+ }
+
+ if (this.foregroundStatusCheckInFlight) {
+ return;
+ }
+ this.foregroundStatusCheckInFlight = true;
+ const foregroundConvoId = this.conversationId();
+ const { generationCreatedAt } = this;
+ void fetchStatus(foregroundConvoId)
+ .then((status) => {
+ if (
+ status.active !== false ||
+ (status.createdAt != null &&
+ generationCreatedAt != null &&
+ status.createdAt !== generationCreatedAt) ||
+ !this.isCurrent() ||
+ this.isSettled() ||
+ !visibility.isVisible()
+ ) {
+ return;
+ }
+ logger.log(
+ 'ResumableSSE',
+ 'Apparently open stream is terminal - reconciling on foreground',
+ { conversationId: foregroundConvoId, generationCreatedAt },
+ );
+ this.reattachOnForeground();
+ })
+ .catch((error) => {
+ if (!this.isCurrent()) {
+ return;
+ }
+ logger.warn('ResumableSSE', 'Could not verify stream on foreground', {
+ conversationId: foregroundConvoId,
+ generationCreatedAt,
+ error,
+ });
+ })
+ .finally(() => {
+ this.foregroundStatusCheckInFlight = false;
+ });
+ }
+
+ /** Replaces the pane's foreground listener with this subscription's. */
+ watchForeground(): void {
+ this.run.stopForegroundReattach?.();
+ this.run.stopForegroundReattach = this.host.visibility.subscribe(() =>
+ this.handleForegroundReattach(),
+ );
+ }
+}