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
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧭 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.tsindex 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.tsindex 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.tsindex 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 errorHandlererrorHandler({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 conversationsetIsSubmitting(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 subscribelogger.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 stateclearStepMaps();// 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.tsnew file mode 100644index 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.tsindex 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): GenerationProtocolexport 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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(),+ );+ }+}