diff --git a/client/src/data-provider/SSE/protocol.ts b/client/src/data-provider/SSE/protocol.ts index f9082deff2..e4adadbb52 100644 --- a/client/src/data-provider/SSE/protocol.ts +++ b/client/src/data-provider/SSE/protocol.ts @@ -1,17 +1,14 @@ import { request } from 'librechat-data-provider'; -import { GENERATION_PROTOCOL_VERSION } from '@librechat/chat'; +import { GENERATION_PROTOCOL_VERSION, generationProtocolHeaders } from '@librechat/chat'; export { + GENERATION_PROTOCOL_HEADER, GENERATION_PROTOCOL_VERSION, + generationProtocolHeaders, getGenerationProtocolVersion, supportsGenerationProtocolV2, } from '@librechat/chat'; export type { GenerationProtocolVersion } from '@librechat/chat'; -export const GENERATION_PROTOCOL_HEADER = 'X-LibreChat-Generation-Protocol'; - -export const generationProtocolHeaders = (): Record => ({ - [GENERATION_PROTOCOL_HEADER]: String(GENERATION_PROTOCOL_VERSION), -}); export const withGenerationProtocolQuery = (url: string): string => `${url}${url.includes('?') ? '&' : '?'}generationProtocolVersion=${GENERATION_PROTOCOL_VERSION}`; diff --git a/client/src/data-provider/SSE/queries.ts b/client/src/data-provider/SSE/queries.ts index e3048181ed..87d860f1b8 100644 --- a/client/src/data-provider/SSE/queries.ts +++ b/client/src/data-provider/SSE/queries.ts @@ -1,7 +1,8 @@ import { useEffect, useMemo, useState } from 'react'; import { useQuery, useQueries, useQueryClient } from '@tanstack/react-query'; import { apiBaseUrl, QueryKeys, request, dataService } from 'librechat-data-provider'; -import type { Agents, TConversation, TPendingSteer } from 'librechat-data-provider'; +import type { TConversation } from 'librechat-data-provider'; +import type { StreamStatusResponse } from '@librechat/chat'; import { isNotFoundError, updateConvoInAllQueries, @@ -11,32 +12,7 @@ import { import { generationProtocolHeaders, withGenerationProtocolQuery } from './protocol'; import { useGetStartupConfig } from '../Endpoints'; -export interface StreamStatusResponse { - /** Exact protocol selected by the job. Missing/1 is always legacy. */ - generationProtocolVersion?: number; - active: boolean; - /** Client-local cache marker used to force useResumeOnLoad to replace a - * stale generation attachment with the newer epoch occupying this stream. */ - generationHandoff?: boolean; - streamId?: string; - status?: 'running' | 'complete' | 'error' | 'aborted' | 'requires_action'; - aggregatedContent?: Array<{ type: string; text?: string }>; - createdAt?: number; - /** Generation age computed on the server's clock, so a reattaching client - * can rebuild a clock-local elapsed baseline free of cross-machine skew. */ - elapsedMs?: number; - resumeState?: Agents.ResumeState; - /** The run's temporary state as the server recorded it at admission, so a rebuilt - * submission keeps a hidden chat out of history and titling after a reload. */ - isTemporary?: boolean; - /** Live pending approval when `status === 'requires_action'`; mirrors - * `resumeState.pendingAction`, surfaced top-level for the resume-on-load path. */ - pendingAction?: Agents.PendingAction; - /** Acknowledged steers a terminal drain parked because no subscriber was - * live for the final/abort event. Reads are replayable until an exact - * recovery turn persists or the user discards the item. */ - unrecoveredSteers?: TPendingSteer[]; -} +export type { StreamStatusResponse } from '@librechat/chat'; export const streamStatusQueryKey = (conversationId: string) => ['streamStatus', conversationId]; diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.ts index 43a9589526..cbcf05a2b1 100644 --- a/client/src/hooks/SSE/useResumableSSE.ts +++ b/client/src/hooks/SSE/useResumableSSE.ts @@ -11,7 +11,6 @@ import { ErrorTypes, StepEvents, StepTypes, - apiBaseUrl, SteerEvents, dataService, ContentTypes, @@ -63,6 +62,9 @@ import { getStartGenerationConversationId, getPredecessorMismatchStartResponse, START_GENERATION_READINESS_TIMEOUT_MS, + ResumableRun, + documentVisibility, + ResumableSubscription, } from '@librechat/chat'; import type { Agents, @@ -81,9 +83,12 @@ import type { TAttachment, TTokenUsageEvent, TContextUsageEvent, - ChatStreamConnection, } from 'librechat-data-provider'; -import type { GenerationProtocolVersion, StartGenerationResult } from '@librechat/chat'; +import type { + SubscriptionTarget, + StartGenerationResult, + GenerationProtocolVersion, +} from '@librechat/chat'; import type { QueuedMessageOrigin, DrainAfterAbort, RunEnd } from '~/hooks/Chat/queue'; import type { ActiveJobsResponse, StreamStatusResponse } from '~/data-provider'; import type { EventHandlerParams } from './useEventHandlers'; @@ -124,7 +129,6 @@ import { useGetStartupConfig, queueTitleGeneration, streamStatusQueryKey, - generationProtocolHeaders, fetchConversationMessages, } from '~/data-provider'; import { @@ -206,6 +210,7 @@ export default function useResumableSSE( isAddedRequest = false, runIndex = 0, ) { + const [run] = useState(() => new ResumableRun()); const jotaiStore = useStore(); const localize = useLocalize(); const queryClient = useQueryClient(); @@ -283,47 +288,6 @@ export default function useResumableSSE( const setShowStopButton = useSetAtom(showStopButtonByIndex(runIndex)); const setLiveAppliedSteerIds = useSetAtom(liveAppliedSteerIdsAtom); - const streamRef = useRef(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(null); - const submissionRef = useRef(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()); - const createdStreamIdsRef = useRef(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. */ - const pendingActionRetryRef = useRef(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>(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>(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(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(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) => { - 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([ 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>, ): Promise { - 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); + run.reconnectAttempt = Math.max(run.reconnectAttempt, 1); + sub.close(); + if (run.reconnectTimeout) { + run.scheduler.clearTimeout(run.reconnectTimeout); } - reconnectTimeoutRef.current = setTimeout(() => { - if (isCurrentSubscription() && submissionRef.current) { - subscribeToStream( - currentStreamId, - submissionRef.current, - true, - generationCreatedAt, - generationProtocolVersion, - lifecycleSignal, - ); - } - }, 250); + sub.scheduleReattach(250); } async function authorizeTerminalTeardown( conversationId: string, terminalKind: 'FINAL' | 'error', ): Promise { - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return false; } if (generationProtocolVersion !== GENERATION_PROTOCOL_VERSION) { @@ -1874,11 +1670,11 @@ export default function useResumableSSE( let status: Awaited>; 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 => { - 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({ 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> | 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, '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({ @@ -2259,14 +2019,14 @@ export default function useResumableSSE( // The first stream can finish before CREATED mounts the saved-chat query. queryFn: () => fetchConversationMessages(convoId), }); - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return; } if (Array.isArray(fetched)) { persistedMessages = fetched; } } catch (error) { - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return; } logger.warn('ResumableSSE', 'Could not reconcile persisted messages after 404', { @@ -2290,25 +2050,14 @@ export default function useResumableSSE( let confirmedV2Terminal = false; try { const status = await fetchStreamStatus(recoveryConvoId); - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return; } if ( generationProtocolVersion === GENERATION_PROTOCOL_VERSION && !supportsGenerationProtocolV2(status) ) { - reconnectTimeoutRef.current = setTimeout(() => { - if (isCurrentSubscription() && submissionRef.current) { - subscribeToStream( - currentStreamId, - submissionRef.current, - true, - generationCreatedAt, - generationProtocolVersion, - lifecycleSignal, - ); - } - }, 1_000); + sub.scheduleReattach(1_000); return; } if ( @@ -2317,7 +2066,7 @@ export default function useResumableSSE( (generationCreatedAt == null || status.createdAt !== generationCreatedAt) ) { const handedOff = await handoffToReplacement(recoveryConvoId, status); - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return; } if (handedOff) { @@ -2325,18 +2074,7 @@ export default function useResumableSSE( } /** Legacy generations have no replacement-handoff contract. * Never attach this submission to a different epoch. */ - reconnectTimeoutRef.current = setTimeout(() => { - if (isCurrentSubscription() && submissionRef.current) { - subscribeToStream( - currentStreamId, - submissionRef.current, - true, - generationCreatedAt, - generationProtocolVersion, - lifecycleSignal, - ); - } - }, 1_000); + sub.scheduleReattach(1_000); return; } if (status.active === true) { @@ -2374,19 +2112,8 @@ export default function useResumableSSE( } setIsSubmitting(true); setShowStopButton(status.createdAt != null); - reconnectAttemptRef.current = Math.max(reconnectAttemptRef.current, 1); - reconnectTimeoutRef.current = setTimeout(() => { - if (isCurrentSubscription() && submissionRef.current) { - subscribeToStream( - activeStreamId, - submissionRef.current, - true, - status.createdAt, - generationProtocolVersion, - lifecycleSignal, - ); - } - }, 1_000); + run.reconnectAttempt = Math.max(run.reconnectAttempt, 1); + sub.scheduleReattach(1_000, activeStreamId, status.createdAt); return; } confirmedV2Terminal = @@ -2395,7 +2122,7 @@ export default function useResumableSSE( const canRecoverTerminalSteers = generationProtocolVersion === 1 || confirmedV2Terminal; const unrecovered = canRecoverTerminalSteers ? (status.unrecoveredSteers ?? []) : []; if (unrecovered.length > 0) { - const recoverySteerId = getRecoverySteerId(currentSubmission); + const recoverySteerId = getRecoverySteerId(sub.submission); convertSteersToQueued(recoveryConvoId, unrecovered, { generationProtocolVersion, ...(recoverySteerId != null && { @@ -2410,7 +2137,7 @@ export default function useResumableSSE( } } } catch (error) { - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return; } logger.warn('ResumableSSE', 'Could not recover parked steers after 404', { @@ -2423,8 +2150,8 @@ export default function useResumableSSE( clearAttachedGenerationCreatedAt(); clearPendingApprovalForTerminal(recoveryConvoId); if ( - !createdStreamIdsRef.current.has(currentStreamId) && - optimisticStreamIdsRef.current.has(currentStreamId) + !run.createdStreamIds.has(currentStreamId) && + run.optimisticStreamIds.has(currentStreamId) ) { // Both fresh and resumed subscriptions can miss every event of a fast turn. // A missing job proves neither that the conversation was saved nor that it failed. @@ -2432,7 +2159,7 @@ export default function useResumableSSE( const persisted = await fetchConvoSnapshot(queryClient, recoveryConvoId, () => dataService.getConversationById(recoveryConvoId), ); - if (!isCurrentSubscription()) return; + if (!sub.isCurrent()) return; if (persisted?.conversationId === recoveryConvoId) { queryClient.setQueryData([QueryKeys.conversation, recoveryConvoId], persisted); upsertConvoInAllQueries(queryClient, persisted, true, 'snapshot'); @@ -2453,7 +2180,7 @@ export default function useResumableSSE( } } } catch (error) { - if (!isCurrentSubscription()) return; + if (!sub.isCurrent()) return; if (toStartGenerationError(error)?.response?.status === 404) { removeConvoFromAllQueries(queryClient, currentStreamId); } @@ -2465,7 +2192,7 @@ export default function useResumableSSE( if (persistedMessages) { setMessages(persistedMessages); } - subscriptionRetired = true; + sub.retired = true; setIsSubmitting(false); setShowStopButton(false); @@ -2500,9 +2227,9 @@ export default function useResumableSSE( { conversationId: recoveryConvoId, outcome: 'aborted', - endedAt: Date.now(), + endedAt: run.scheduler.now(), ...detachedEnd, - startedAsNewConvo: optimisticStreamIdsRef.current.has(currentStreamId), + startedAsNewConvo: run.optimisticStreamIds.has(currentStreamId), }, { retainDetached: @@ -2510,9 +2237,8 @@ export default function useResumableSSE( }, ); setStreamId(null); - optimisticStreamIdsRef.current.delete(currentStreamId); - createdStreamIdsRef.current.delete(currentStreamId); - reconnectAttemptRef.current = 0; + run.releaseStream(currentStreamId); + run.reconnectAttempt = 0; return; } @@ -2524,17 +2250,14 @@ export default function useResumableSSE( * not a server-sent error payload. Use `== null` to only match undefined/null (no HTTP status). */ if (responseCode == null && data != null) { - finalReceived = true; - const recoveryConvoId = currentSubmission.conversation?.conversationId ?? currentStreamId; - if ( - !(await authorizeTerminalTeardown(recoveryConvoId, 'error')) || - !isCurrentSubscription() - ) { + sub.finalReceived = true; + const recoveryConvoId = sub.submission.conversation?.conversationId ?? currentStreamId; + if (!(await authorizeTerminalTeardown(recoveryConvoId, 'error')) || !sub.isCurrent()) { return; } logger.log('ResumableSSE', 'Server-sent error event received:', data); - cancelSteerRetryFrames(); - closeStream(); + run.cancelSteerRetryFrames(); + sub.close(); /** FLUSH (not cancel): the error card below is built from the cache * tail, so queued tokens must land first, and a stale trailing * frame must never overwrite the error write. */ @@ -2542,10 +2265,10 @@ export default function useResumableSSE( removeActiveJob(currentStreamId); clearAttachedGenerationCreatedAt(); clearPendingApprovalForTerminal(recoveryConvoId); - resetLive({ ...currentSubmission, userMessage }); + resetLive(sub.liveSubmission()); if ( - !createdStreamIdsRef.current.has(currentStreamId) && - optimisticStreamIdsRef.current.has(currentStreamId) + !run.createdStreamIds.has(currentStreamId) && + run.optimisticStreamIds.has(currentStreamId) ) { removeConvoFromAllQueries(queryClient, currentStreamId); } @@ -2574,12 +2297,12 @@ export default function useResumableSSE( // Display the error to user via errorHandler errorHandler({ data: { text: errorString } as unknown as Parameters[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> | 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({ queryKey: messageQueryKey, }); - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return; } if (Array.isArray(fetched)) { persistedMessages = fetched; } } catch (error) { - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return; } logger.warn('ResumableSSE', 'Could not reconcile terminal messages after disconnect', { @@ -2837,7 +2514,7 @@ export default function useResumableSSE( const canRecoverTerminalSteers = generationProtocolVersion === 1 || confirmedV2Terminal; const unrecovered = canRecoverTerminalSteers ? (status.unrecoveredSteers ?? []) : []; if (unrecovered.length > 0) { - const recoverySteerId = getRecoverySteerId(currentSubmission); + const recoverySteerId = getRecoverySteerId(sub.submission); convertSteersToQueued(recoveryConvoId, unrecovered, { generationProtocolVersion, ...(recoverySteerId != null && { @@ -2858,17 +2535,17 @@ export default function useResumableSSE( }); } - resetLive({ ...currentSubmission, userMessage }); + resetLive(sub.liveSubmission()); removeActiveJob(currentStreamId); clearAttachedGenerationCreatedAt(); clearPendingApprovalForTerminal(recoveryConvoId); if ( - !createdStreamIdsRef.current.has(currentStreamId) && - optimisticStreamIdsRef.current.has(currentStreamId) + !run.createdStreamIds.has(currentStreamId) && + run.optimisticStreamIds.has(currentStreamId) ) { removeConvoFromAllQueries(queryClient, currentStreamId); } - subscriptionRetired = true; + sub.retired = true; setIsSubmitting(false); setShowStopButton(false); let recoveryOutcome: 'completed' | 'aborted' | 'error' = 'error'; @@ -2881,15 +2558,15 @@ export default function useResumableSSE( recoveryOutcome === 'completed' ? completedResponseMessageId( persistedMessages, - userMessage?.messageId, + sub.userMessage?.messageId, status?.resumeState?.responseMessageId ?? - currentSubmission.initialResponse?.messageId, + sub.submission.initialResponse?.messageId, ) : undefined; setRunEnd({ conversationId: recoveryConvoId, outcome: recoveryOutcome, - endedAt: Date.now(), + endedAt: run.scheduler.now(), generationCreatedAt: status.createdAt ?? generationCreatedAt, ...(recoveredResponseMessageId != null && { responseMessageId: recoveredResponseMessageId, @@ -2897,9 +2574,8 @@ export default function useResumableSSE( }); setSubmission(null); setStreamId(null); - optimisticStreamIdsRef.current.delete(currentStreamId); - createdStreamIdsRef.current.delete(currentStreamId); - reconnectAttemptRef.current = 0; + run.releaseStream(currentStreamId); + run.reconnectAttempt = 0; } }; @@ -2911,28 +2587,25 @@ export default function useResumableSSE( * connection rather than stranding the pane on its partial content. */ const handleClose = () => { - if (!isCurrentSubscription()) { + if (!sub.isCurrent()) { return; } - if (replacementHandoffRef.current) { + if (run.replacementHandoff) { logger.log('ResumableSSE', 'Stream closed for generation handoff - preserving state'); return; } // If we're in a reconnection cycle, don't reset state // (error handler will set up the reconnect timeout) - if (reconnectAttemptRef.current > 0) { + if (run.reconnectAttempt > 0) { logger.log('ResumableSSE', 'Stream closed for reconnect - preserving state'); return; } logger.log('ResumableSSE', 'Stream aborted (intentional close) - no reconnect'); - cancelSteerRetryFrames(); + run.cancelSteerRetryFrames(); // Clear any pending reconnect attempts - if (reconnectTimeoutRef.current) { - clearTimeout(reconnectTimeoutRef.current); - reconnectTimeoutRef.current = null; - } + run.clearReconnectTimeout(); // Reset UI state - useResumeOnLoad will restore if user returns to this conversation setIsSubmitting(false); setShowStopButton(false); @@ -2941,7 +2614,7 @@ export default function useResumableSSE( * while generating): discard the in-flight pending usage so it can't * merge into the next response in this conversation. On a resume the * collected usage is re-folded via backfillUsage, so nothing is lost. */ - resetLive({ ...currentSubmission, userMessage }); + resetLive(sub.liveSubmission()); // No final/error event fires on this path, so it's the only place left // to sweep a local `failed` chip; otherwise it survives this close and // renders (with a live Retry) under whatever run starts next. `pending` @@ -2950,33 +2623,17 @@ export default function useResumableSSE( // server-ACK'd `pending` steer is not stranded: the server injects it // regardless, and sweeping it into the queue too would resend the same // words as a duplicate turn once `useQueueDrain` fires at run end. - convertLocalSteersToQueued( - currentSubmission.conversation?.conversationId ?? currentStreamId, - { statuses: ABORT_SWEEP_STATUSES }, - ); + convertLocalSteersToQueued(sub.submission.conversation?.conversationId ?? currentStreamId, { + statuses: ABORT_SWEEP_STATUSES, + }); }; - connection = transport.stream({ token }).reconnectToStream( - { url, headers: generationProtocolHeaders() }, - { - signal: streamController.signal, - onEvent: (event) => { - switch (event.type) { - case 'open': - handleOpen(); - return; - case 'error': - void handleTransportFailure(event); - return; - case 'abort': - handleClose(); - return; - default: - void handleFrame(event); - } - }, - }, - ); + sub.connect(transport.stream({ token }), { + onOpen: handleOpen, + onFrame: (event) => void handleFrame(event), + onFailure: (event) => void handleTransportFailure(event), + onClose: handleClose, + }); // Debug hooks for testing reconnection vs clean close behavior (dev only) if (import.meta.env.DEV) { @@ -2994,12 +2651,13 @@ export default function useResumableSSE( /** Simulate clean close (navigation away) - triggers abort event → no reconnection */ debugWindow.__closeClean = () => { logger.log('Debug', 'Simulating clean close (navigation away)...'); - subscriptionRetired = true; - closeStream(); + sub.retired = true; + sub.close(); }; } }, [ + run, isAddedRequest, setConversation, runIndex, @@ -3076,7 +2734,7 @@ export default function useResumableSSE( let requestAttempts = 0; let networkAttempts = 0; let readinessAttempts = 0; - const readinessDeadline = Date.now() + START_GENERATION_READINESS_TIMEOUT_MS; + const readinessDeadline = run.scheduler.now() + START_GENERATION_READINESS_TIMEOUT_MS; while (!signal?.aborted) { const recoverySteerId = getRecoverySteerId(currentSubmission); @@ -3184,7 +2842,7 @@ export default function useResumableSSE( lastError = error; const isNetworkError = isRetryableNetworkError(error); const isServerNotReady = isServerNotReadyError(error); - const remainingReadinessMs = readinessDeadline - Date.now(); + const remainingReadinessMs = readinessDeadline - run.scheduler.now(); const shouldRetryNetwork = isNetworkError && networkAttempts < START_GENERATION_NETWORK_RETRIES - 1; const shouldRetryServerNotReady = isServerNotReady && remainingReadinessMs > 0; @@ -3294,6 +2952,7 @@ export default function useResumableSSE( return null; }, [ + run, clearStepMaps, convertSteersToQueued, errorHandler, @@ -3312,18 +2971,15 @@ export default function useResumableSSE( if (!submission || Object.keys(submission).length === 0) { logger.log('ResumableSSE', 'No submission, cleaning up'); // Clear reconnect timeout if submission is cleared - if (reconnectTimeoutRef.current) { - clearTimeout(reconnectTimeoutRef.current); - reconnectTimeoutRef.current = null; - } - stopForegroundReattachRef.current?.(); - stopForegroundReattachRef.current = null; + run.clearReconnectTimeout(); + run.stopForegroundReattach?.(); + run.stopForegroundReattach = null; // Close SSE but do NOT dispatch cancel - navigation should not abort - streamRef.current?.abort(); - streamRef.current = null; + run.stream?.abort(); + run.stream = null; setStreamId(null); - reconnectAttemptRef.current = 0; - submissionRef.current = null; + run.reconnectAttempt = 0; + run.submission = null; return; } @@ -3343,10 +2999,10 @@ export default function useResumableSSE( userMessageId: submission.userMessage?.messageId, }); - submissionRef.current = submission; - runEndPublishedRef.current = false; - identityConfirmedRef.current = false; - subscribedEpochRef.current = null; + run.submission = submission; + run.runEndPublished = false; + run.identityConfirmed = false; + run.subscribedEpoch = null; if (submission.conversation?.conversationId != null) { /** A different run starting here owns the conversation's end from now on: an earlier run * this pane left is superseded, and a Stop belonged to that earlier run. Reattaching to @@ -3369,7 +3025,7 @@ export default function useResumableSSE( } const startController = new AbortController(); const { signal } = startController; - const isCurrentEffect = () => !signal.aborted && submissionRef.current === submission; + const isCurrentEffect = () => !signal.aborted && run.submission === submission; const initStream = async () => { if (!isCurrentEffect()) { @@ -3399,14 +3055,14 @@ export default function useResumableSSE( setStreamId(resumeStreamId); // Optimistically add to active jobs (in case it's not already there) addActiveJob(resumeStreamId); - subscribeToStream( - resumeStreamId, + subscribeToStream({ + streamId: resumeStreamId, submission, - true, - resumeGenerationCreatedAt, - resumeGenerationProtocolVersion, + isResume: true, + generationCreatedAt: resumeGenerationCreatedAt, + generationProtocolVersion: resumeGenerationProtocolVersion, signal, - ); + }); } else { // New generation: start and then subscribe logger.log('ResumableSSE', 'Starting NEW generation'); @@ -3533,7 +3189,7 @@ export default function useResumableSSE( }); } clearDrainAfterAbort(startResult.conversationId, expectedPredecessorCreatedAt); - submissionRef.current = null; + run.submission = null; setIsSubmitting(false); setShowStopButton(false); setSubmission(null); @@ -3630,7 +3286,7 @@ export default function useResumableSSE( ); addActiveJob(replacementStart.streamId); if (startedAsNewConvo) { - optimisticStreamIdsRef.current.add(replacementStart.streamId); + run.optimisticStreamIds.add(replacementStart.streamId); updateActiveGenerationCreatedAt( Constants.NEW_CONVO, replacementStart.generationCreatedAt, @@ -3650,8 +3306,8 @@ export default function useResumableSSE( replacementStatus.resumeState?.aggregatedContent ?? replacementStatus.aggregatedContent, ); - replacementHandoffRef.current = true; - submissionRef.current = null; + run.replacementHandoff = true; + run.submission = null; setIsSubmitting(true); setShowStopButton(true); setSubmission(null); @@ -3677,7 +3333,7 @@ export default function useResumableSSE( setRunEnd({ conversationId: replacementStart.conversationId, outcome: 'error', - endedAt: Date.now(), + endedAt: run.scheduler.now(), generationCreatedAt: replacementStart.generationCreatedAt, }); setSubmission(null); @@ -3809,7 +3465,7 @@ export default function useResumableSSE( conversationId: settledConversationId, outcome: conversationLookup === 'inconclusive' ? 'error' : 'aborted', startedAsNewConvo, - endedAt: Date.now(), + endedAt: run.scheduler.now(), }); setSubmission(null); return; @@ -3834,21 +3490,21 @@ export default function useResumableSSE( queueTitleGeneration(newStreamId); } if (isInitialNewConversation(submission)) { - optimisticStreamIdsRef.current.add(newStreamId); + run.optimisticStreamIds.add(newStreamId); replaceNewConversationUrl(newStreamId); } const streamSubmission = addOptimisticConversation(newStreamId, submission); - submissionRef.current = streamSubmission; + run.submission = streamSubmission; // A deduped retry (status: 'resumed') attaches to an already-running stream, so // subscribe with resume=true to replay its state instead of only live events. - subscribeToStream( - newStreamId, - streamSubmission, - resumed, + subscribeToStream({ + streamId: newStreamId, + submission: streamSubmission, + isResume: resumed, generationCreatedAt, generationProtocolVersion, signal, - ); + }); } else { logger.error('ResumableSSE', 'Failed to get streamId from startGeneration'); } @@ -3865,51 +3521,32 @@ export default function useResumableSSE( setSubmission(null); }); - /** The Set object itself is never reassigned, so this alias reads the - * LIVE frame ids at cleanup time (satisfies react-hooks/exhaustive-deps - * without changing behavior). */ - const activityLabelRetryFrames = activityLabelRetryFramesRef.current; - const steerRetryFrames = steerRetryFramesRef.current; return () => { logger.log('ResumableSSE', 'Cleanup - closing SSE, resetting UI state'); startController.abort(); // Cleanup on unmount/navigation - close connection but DO NOT abort backend // Reset UI state so it doesn't leak to other conversations // If user returns to this conversation, useResumeOnLoad will restore the state - if (reconnectTimeoutRef.current) { - clearTimeout(reconnectTimeoutRef.current); - reconnectTimeoutRef.current = null; - } - if (pendingActionRetryRef.current != null) { - cancelAnimationFrame(pendingActionRetryRef.current); - pendingActionRetryRef.current = null; - } - for (const frameId of activityLabelRetryFrames) { - cancelAnimationFrame(frameId); - } - activityLabelRetryFrames.clear(); - for (const frameId of steerRetryFrames) { - cancelAnimationFrame(frameId); - } - steerRetryFrames.clear(); - stopForegroundReattachRef.current?.(); - stopForegroundReattachRef.current = null; + run.clearReconnectTimeout(); + run.cancelRetryFrames(); + run.stopForegroundReattach?.(); + run.stopForegroundReattach = null; // Reset reconnect counter before closing (so abort handler doesn't think we're reconnecting) - reconnectAttemptRef.current = 0; + run.reconnectAttempt = 0; /** The pane is moving off a run that is still generating (another chat, a new chat, or * an unmount): the server keeps going with no subscriber and deletes the job when done, * so no terminal event will reach the queue drain. Remember the run; on return its end is * read from history. Only a run whose identity the server confirmed (its epoch, and the * user message `created` or a resume's sync named) is remembered, and not a regeneration, * a run that already published its end, or one the user stopped. */ - const closing = submissionRef.current; + const closing = run.submission; const closingConvoId = closing?.conversation?.conversationId; const closingUserMessageId = closing?.userMessage?.messageId; - const generationCreatedAt = subscribedEpochRef.current; + const generationCreatedAt = run.subscribedEpoch; if ( - streamRef.current != null && - identityConfirmedRef.current && - !runEndPublishedRef.current && + run.stream != null && + run.identityConfirmed && + !run.runEndPublished && closing?.isRegenerate !== true && closingConvoId != null && closingConvoId !== Constants.NEW_CONVO && @@ -3923,18 +3560,18 @@ export default function useResumableSSE( generationCreatedAt, }); } - streamRef.current?.abort(); - streamRef.current = null; + run.stream?.abort(); + run.stream = null; // Clear handler maps to prevent memory leaks and stale state clearStepMaps(); // Reset UI state on ordinary cleanup. A generation handoff already // cached the replacement and must remain non-idle until resume-on-load // installs its epoch-fenced submission. - if (!replacementHandoffRef.current) { + if (!run.replacementHandoff) { setIsSubmitting(false); setShowStopButton(false); } - replacementHandoffRef.current = false; + run.replacementHandoff = false; }; // eslint-disable-next-line react-hooks/exhaustive-deps }, [submission]); diff --git a/packages/chat/src/core/__tests__/subscription.spec.ts b/packages/chat/src/core/__tests__/subscription.spec.ts new file mode 100644 index 0000000000..23ca110a63 --- /dev/null +++ b/packages/chat/src/core/__tests__/subscription.spec.ts @@ -0,0 +1,235 @@ +import type { + TMessage, + ChatEvent, + TSubmission, + ChatTransport, + ChatTransportOptions, +} from 'librechat-data-provider'; +import type { + PageVisibility, + ResumableScheduler, + SubscriptionTarget, + StreamStatusResponse, +} from '../resumable'; +import { ResumableRun, ResumableSubscription } from '../resumable'; + +/** Timers and frames that run only when the test says so. */ +const createScheduler = () => { + let now = 0; + const timers = new Map 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; + }, + 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 = {}) => { + const clock = createScheduler(); + const page = createVisibility(); + const run = new ResumableRun(clock.scheduler); + const fetchStatus = jest.fn, [string]>(); + const subscribe = jest.fn(); + const logger = { log: jest.fn(), warn: jest.fn(), error: jest.fn() }; + const target: SubscriptionTarget = { + streamId: 'c-1', + submission, + isResume: false, + generationCreatedAt: 2000, + generationProtocolVersion: 2, + ...overrides, + }; + run.submission = target.submission; + const sub = new ResumableSubscription( + run, + { logger, visibility: page.visibility, fetchStatus, subscribe }, + target, + ); + return { run, sub, clock, page, fetchStatus, subscribe }; +}; + +describe('ResumableSubscription', () => { + it('is current only while it holds the pane, its submission and its lifecycle', () => { + const controller = new AbortController(); + const { run, sub } = setup({ signal: controller.signal }); + expect(sub.isCurrent()).toBe(false); + sub.claim(); + expect(sub.isCurrent()).toBe(true); + + sub.replaceSubmission({ ...submission, isRegenerate: true }); + expect(run.submission).toBe(sub.submission); + expect(sub.isCurrent()).toBe(true); + + run.submission = submission; + expect(sub.isCurrent()).toBe(false); + run.submission = sub.submission; + controller.abort(); + expect(sub.isCurrent()).toBe(false); + }); + + it('builds the stream route with the resume cursor and generation fence', () => { + const { sub } = setup({ streamId: 'c 1', isResume: true }); + const url = new URL(sub.url(), 'http://localhost'); + expect(url.pathname).toBe('/api/agents/chat/stream/c%201'); + expect(Object.fromEntries(url.searchParams)).toEqual({ + resume: 'true', + generationCreatedAt: '2000', + generationProtocolVersion: '2', + }); + }); + + it('routes connection events to their handlers', () => { + const { sub } = setup(); + let options: ChatTransportOptions | undefined; + const transport = { + send: jest.fn(), + reconnectToStream: jest.fn((_request, opts: ChatTransportOptions) => { + options = opts; + return { closed: false }; + }), + } as ChatTransport; + const handlers = { + onOpen: jest.fn(), + onFrame: jest.fn(), + onFailure: jest.fn(), + onClose: jest.fn(), + }; + sub.connect(transport, handlers); + + const emit = (event: ChatEvent) => options?.onEvent(event); + emit({ type: 'open' } as ChatEvent); + emit({ type: 'error', status: 0 }); + emit({ type: 'abort' }); + emit({ type: 'title', data: { event: 'title', data: { title: 't' } } } as ChatEvent); + expect(handlers.onOpen).toHaveBeenCalledTimes(1); + expect(handlers.onFailure).toHaveBeenCalledWith({ type: 'error', status: 0 }); + expect(handlers.onClose).toHaveBeenCalledTimes(1); + expect(handlers.onFrame).toHaveBeenCalledTimes(1); + expect(transport.reconnectToStream).toHaveBeenCalledWith( + expect.objectContaining({ headers: { 'X-LibreChat-Generation-Protocol': '2' } }), + expect.objectContaining({ signal: sub.controller.signal }), + ); + }); + + it('re-attaches after a delay only while it is still current', () => { + const { run, sub, clock, subscribe } = setup(); + sub.claim(); + sub.scheduleReattach(1000); + clock.advance(999); + expect(subscribe).not.toHaveBeenCalled(); + clock.advance(1); + expect(subscribe).toHaveBeenCalledWith( + expect.objectContaining({ streamId: 'c-1', isResume: true, generationCreatedAt: 2000 }), + ); + + sub.scheduleReattach(1000, 'c-2', 3000); + run.stream = new AbortController(); + clock.advance(1000); + expect(subscribe).toHaveBeenCalledTimes(1); + }); + + it('re-attaches on foreground when the connection closed while hidden', () => { + const { run, sub, page, subscribe } = setup(); + sub.claim(); + sub.connection = { closed: true }; + sub.watchForeground(); + run.reconnectAttempt = 0; + page.show(); + expect(sub.controller.signal.aborted).toBe(true); + expect(run.reconnectAttempt).toBe(1); + expect(subscribe).toHaveBeenCalledWith(expect.objectContaining({ isResume: true })); + }); + + it('re-attaches on foreground when the status proves an open connection terminal', async () => { + const { sub, page, fetchStatus, subscribe } = setup(); + sub.claim(); + sub.connection = { closed: false }; + sub.watchForeground(); + fetchStatus.mockResolvedValueOnce({ active: true, createdAt: 2000 }); + page.show(); + await new Promise((resolve) => setImmediate(resolve)); + expect(subscribe).not.toHaveBeenCalled(); + + fetchStatus.mockResolvedValueOnce({ active: false, createdAt: 2000 }); + page.show(); + await new Promise((resolve) => setImmediate(resolve)); + expect(fetchStatus).toHaveBeenLastCalledWith('c-1'); + expect(subscribe).toHaveBeenCalledTimes(1); + }); + + it('keeps one foreground listener per pane', () => { + const { run, sub, page } = setup(); + sub.watchForeground(); + const second = new ResumableSubscription(run, sub.host, { + streamId: 'c-1', + submission, + isResume: true, + generationProtocolVersion: 2, + }); + second.watchForeground(); + expect(page.listeners.size).toBe(1); + }); +}); + +describe('ResumableRun', () => { + it('drops the cleared edit prefix only when a new generation binds', () => { + const run = new ResumableRun(createScheduler().scheduler); + run.bindPrefixState('gen-1'); + run.editPrefixCleared = true; + run.bindPrefixState('gen-1'); + expect(run.editPrefixCleared).toBe(true); + run.bindPrefixState('gen-2'); + expect(run.editPrefixCleared).toBe(false); + }); + + it('clears a pending reattach', () => { + const clock = createScheduler(); + const run = new ResumableRun(clock.scheduler); + run.reconnectTimeout = clock.scheduler.setTimeout(() => undefined, 1000); + run.clearReconnectTimeout(); + expect(run.reconnectTimeout).toBeNull(); + expect(clock.pending()).toBe(0); + }); +}); diff --git a/packages/chat/src/core/protocol.ts b/packages/chat/src/core/protocol.ts index bee0e5e4f7..88e1ea2fd9 100644 --- a/packages/chat/src/core/protocol.ts +++ b/packages/chat/src/core/protocol.ts @@ -1,4 +1,5 @@ export const GENERATION_PROTOCOL_VERSION = 2 as const; +export const GENERATION_PROTOCOL_HEADER = 'X-LibreChat-Generation-Protocol'; export type GenerationProtocolVersion = 1 | typeof GENERATION_PROTOCOL_VERSION; @@ -22,3 +23,7 @@ export const getGenerationProtocolVersion = (value: unknown): GenerationProtocol export const supportsGenerationProtocolV2 = (value: unknown): boolean => getGenerationProtocolVersion(value) === GENERATION_PROTOCOL_VERSION; + +export const generationProtocolHeaders = (): Record => ({ + [GENERATION_PROTOCOL_HEADER]: String(GENERATION_PROTOCOL_VERSION), +}); diff --git a/packages/chat/src/core/resumable/host.ts b/packages/chat/src/core/resumable/host.ts new file mode 100644 index 0000000000..6527420307 --- /dev/null +++ b/packages/chat/src/core/resumable/host.ts @@ -0,0 +1,55 @@ +import type { Agents, TPendingSteer } from 'librechat-data-provider'; + +/** Where a resumable run reports what it is doing. The app passes its own logger. */ +export interface ResumableLogger { + log: (...args: unknown[]) => void; + warn: (...args: unknown[]) => void; + error: (...args: unknown[]) => void; +} + +/** Whether the page is in the foreground, and a way to hear when that changes. */ +export interface PageVisibility { + isVisible: () => boolean; + /** Calls `listener` on every visibility change; returns the unsubscribe. */ + subscribe: (listener: () => void) => () => void; +} + +/** The document's own visibility. */ +export const documentVisibility: PageVisibility = { + isVisible: () => document.visibilityState === 'visible', + subscribe: (listener) => { + document.addEventListener('visibilitychange', listener); + return () => document.removeEventListener('visibilitychange', listener); + }, +}; + +/** The status route's answer for a conversation's generation. */ +export interface StreamStatusResponse { + /** Exact protocol selected by the job. Missing/1 is always legacy. */ + generationProtocolVersion?: number; + active: boolean; + /** Client-local cache marker used to force useResumeOnLoad to replace a + * stale generation attachment with the newer epoch occupying this stream. */ + generationHandoff?: boolean; + streamId?: string; + status?: 'running' | 'complete' | 'error' | 'aborted' | 'requires_action'; + aggregatedContent?: Array<{ type: string; text?: string }>; + createdAt?: number; + /** Generation age computed on the server's clock, so a reattaching client + * can rebuild a clock-local elapsed baseline free of cross-machine skew. */ + elapsedMs?: number; + resumeState?: Agents.ResumeState; + /** The run's temporary state as the server recorded it at admission, so a rebuilt + * submission keeps a hidden chat out of history and titling after a reload. */ + isTemporary?: boolean; + /** Live pending approval when `status === 'requires_action'`; mirrors + * `resumeState.pendingAction`, surfaced top-level for the resume-on-load path. */ + pendingAction?: Agents.PendingAction; + /** Acknowledged steers a terminal drain parked because no subscriber was + * live for the final/abort event. Reads are replayable until an exact + * recovery turn persists or the user discards the item. */ + unrecoveredSteers?: TPendingSteer[]; +} + +/** Reads a conversation's generation status. */ +export type FetchStreamStatus = (conversationId: string) => Promise; diff --git a/packages/chat/src/core/resumable/index.ts b/packages/chat/src/core/resumable/index.ts index d519a3e604..db6cbf6b09 100644 --- a/packages/chat/src/core/resumable/index.ts +++ b/packages/chat/src/core/resumable/index.ts @@ -3,3 +3,6 @@ export * from './errors'; export * from './events'; export * from './resume'; export * from './messages'; +export * from './run'; +export * from './host'; +export * from './subscription'; diff --git a/packages/chat/src/core/resumable/run.ts b/packages/chat/src/core/resumable/run.ts new file mode 100644 index 0000000000..cca3327408 --- /dev/null +++ b/packages/chat/src/core/resumable/run.ts @@ -0,0 +1,132 @@ +import type { TSubmission } from 'librechat-data-provider'; + +/** A pending timer, as the scheduler that set it returns it. */ +export type TimerHandle = ReturnType; + +/** + * 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 = new Set(); + readonly createdStreamIds: Set = 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 = 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 = new Set(); + /** + * Set once a SYNC has replaced the response with the server's completion-local snapshot, + * which discards the prefix an edited resubmission retained. From that point incoming indices + * are absolute and `editPrefixLength` must no longer be applied, by run steps or labels. + */ + editPrefixCleared = false; + editPrefixFirstPartFolded = false; + /** Generation the cleared-prefix state above belongs to, so it is dropped when a new + * generation starts rather than when a subscribe happens to be live. */ + prefixStateGenerationId: string | null = null; + /** The generation epoch the pane's stream is attached to, kept so a run left mid-stream can + * carry it. A server that reports no epoch leaves it unset. */ + subscribedEpoch: number | null = null; + /** Whether the current submission's run end already reached the queue drain. A run that + * ended attached must not also be resolved as detached when the user later leaves. */ + runEndPublished = false; + /** Whether the server named the current submission's user message (`created`, or a resume's + * sync). Only a run whose identity it confirmed is remembered when the user leaves. */ + identityConfirmed = false; + + constructor(readonly scheduler: ResumableScheduler = browserScheduler) {} + + /** Drops the backoff still waiting to re-attach, if any. */ + clearReconnectTimeout(): void { + if (this.reconnectTimeout) { + this.scheduler.clearTimeout(this.reconnectTimeout); + this.reconnectTimeout = null; + } + } + + cancelSteerRetryFrames(): void { + for (const frameId of this.steerRetryFrames) { + this.scheduler.cancelFrame(frameId); + } + this.steerRetryFrames.clear(); + } + + /** Cancels every frame retry still waiting on a response placeholder. */ + cancelRetryFrames(): void { + if (this.pendingActionRetry != null) { + this.scheduler.cancelFrame(this.pendingActionRetry); + this.pendingActionRetry = null; + } + for (const frameId of this.activityLabelRetryFrames) { + this.scheduler.cancelFrame(frameId); + } + this.activityLabelRetryFrames.clear(); + this.cancelSteerRetryFrames(); + } + + /** + * A NEW generation starts with its retained prefix intact, so the cleared-prefix state from a + * previous one must not carry over. Keyed on the submission's `clientRequestId`, which is new + * per edit attempt and stable across reconnects. + */ + bindPrefixState(generationId: string): void { + if (this.prefixStateGenerationId === generationId) { + return; + } + this.prefixStateGenerationId = generationId; + this.editPrefixCleared = false; + this.editPrefixFirstPartFolded = false; + } + + /** Forgets a stream once its run has ended. */ + releaseStream(streamId: string): void { + this.optimisticStreamIds.delete(streamId); + this.createdStreamIds.delete(streamId); + } +} diff --git a/packages/chat/src/core/resumable/subscription.ts b/packages/chat/src/core/resumable/subscription.ts new file mode 100644 index 0000000000..039f493bdf --- /dev/null +++ b/packages/chat/src/core/resumable/subscription.ts @@ -0,0 +1,296 @@ +import { apiBaseUrl } from 'librechat-data-provider'; +import type { + TMessage, + ChatEvent, + TSubmission, + ChatTransport, + ChatStreamConnection, +} from 'librechat-data-provider'; +import type { ResumableLogger, PageVisibility, FetchStreamStatus } from './host'; +import type { GenerationProtocolVersion } from '../protocol'; +import type { StepEvent } from '../reducer'; +import type { ResumableRun } from './run'; +import { GENERATION_PROTOCOL_VERSION, generationProtocolHeaders } from '../protocol'; + +/** The generation one subscription attaches to, and how. */ +export interface SubscriptionTarget { + streamId: string; + submission: TSubmission; + /** Asks the server to replay the run's state (`sync`) before live events. */ + isResume: boolean; + generationCreatedAt?: number; + generationProtocolVersion: GenerationProtocolVersion; + /** The pane's lifecycle: once aborted, nothing this subscription does lands. */ + signal?: AbortSignal; +} + +/** How a subscription reaches the stream and decides when to re-attach. */ +export interface SubscriptionHost { + logger: ResumableLogger; + visibility: PageVisibility; + fetchStatus: FetchStreamStatus; + /** Attaches a fresh subscription to `target`; how a subscription re-attaches itself. */ + subscribe: (target: SubscriptionTarget) => void; +} + +/** What a subscription does with the events its connection reports. */ +export interface SubscriptionHandlers { + onOpen: () => void; + onFrame: (event: ChatEvent) => void; + onFailure: (event: Extract) => 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(), + ); + } +}