Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🧰 refactor: Move Resumable Start Helpers Into the Chat Core (#17109)

Marco Beretta3709e1fcec2e
diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.ts
index 5042cbb391..2f20fe0fe2 100644
--- a/client/src/hooks/SSE/useResumableSSE.ts
+++ b/client/src/hooks/SSE/useResumableSSE.ts
@@ -24,6 +24,32 @@ import {
ViolationTypes,
removeNullishValues,
} from 'librechat-data-provider';
+import {
+ MAX_RETRIES,
+ getReconnectDelay,
+ START_GENERATION_NETWORK_RETRIES,
+ START_GENERATION_READINESS_TIMEOUT_MS,
+ getRecoverySteerId,
+ getPredecessorMismatchStartResponse,
+ isUnnegotiatedV2StartControl,
+ getStartGenerationCreatedAt,
+ getStartGenerationConversationId,
+ getStartGenerationStreamId,
+ isResumedStartResponse,
+ isSettledStartResponse,
+ isReplacedStartResponse,
+ isRetryableNetworkError,
+ isServerNotReadyError,
+ getRetryAfterDelay,
+ waitForRetryDelay,
+ getStreamStartFailureText,
+ isOAuthStepEvent,
+ getStepEventId,
+ toStartGenerationError,
+ GENERATION_PROTOCOL_VERSION,
+ getGenerationProtocolVersion,
+ supportsGenerationProtocolV2,
+} from '@librechat/chat';
import type {
Agents,
TMessage,
@@ -43,9 +69,9 @@ import type {
TContextUsageEvent,
ChatStreamConnection,
} from 'librechat-data-provider';
+import type { GenerationProtocolVersion, StartGenerationResult } from '@librechat/chat';
import type { QueuedMessageOrigin, DrainAfterAbort, RunEnd } from '~/hooks/Chat/queue';
import type { ActiveJobsResponse, StreamStatusResponse } from '~/data-provider';
-import type { GenerationProtocolVersion } from '~/data-provider';
import type { EventHandlerParams } from './useEventHandlers';
import type { TResData, TFinalResData } from '~/common';
import {
@@ -72,18 +98,6 @@ import {
insertQueuedOrigin,
isCompactionAnchorProjection,
} from '~/utils';
-import {
- useGetUserBalance,
- fetchStreamStatus,
- useGetStartupConfig,
- queueTitleGeneration,
- streamStatusQueryKey,
- generationProtocolHeaders,
- getGenerationProtocolVersion,
- supportsGenerationProtocolV2,
- fetchConversationMessages,
- GENERATION_PROTOCOL_VERSION,
-} from '~/data-provider';
import {
resolveDetachedRunEnd,
isDetachedRunManual,
@@ -94,6 +108,15 @@ import {
queuedMessagesByConvoId,
runEndByIndex,
} from '~/hooks/Chat/queue';
+import {
+ useGetUserBalance,
+ fetchStreamStatus,
+ useGetStartupConfig,
+ queueTitleGeneration,
+ streamStatusQueryKey,
+ generationProtocolHeaders,
+ fetchConversationMessages,
+} from '~/data-provider';
import {
recoveryDispositionsFamily,
canRestoreRecovery,
@@ -141,293 +164,12 @@ const clearMatchingDrainAfterAbort = (
? false
: armed;
-const MAX_RETRIES = 5;
-const RECONNECT_BASE_DELAY_MS = 1000;
-const RECONNECT_MAX_DELAY_MS = 30000;
-const getReconnectDelay = (attempt: number) =>
- Math.min(RECONNECT_BASE_DELAY_MS * Math.pow(2, attempt - 1), RECONNECT_MAX_DELAY_MS);
-const START_GENERATION_NETWORK_RETRIES = 3;
-const START_GENERATION_READINESS_TIMEOUT_MS = 120000;
-const SERVER_NOT_READY_CODE = 'SERVER_NOT_READY';
-const PREDECESSOR_MISMATCH_CODE = 'GENERATION_PREDECESSOR_MISMATCH';
-const STEER_RECOVERY_REQUEST_PREFIX = 'steer-recovery:';
-
-type StartGenerationError = {
- code?: string;
- response?: {
- status?: number;
- data?: unknown;
- headers?: Record<string, string | number | string[] | undefined>;
- };
-};
-
-const toStartGenerationError = (error: unknown): StartGenerationError | undefined =>
- error != null && typeof error === 'object' ? (error as StartGenerationError) : undefined;
-
-const getStartGenerationStreamId = (data: unknown): string | null => {
- if (data == null || typeof data !== 'object' || !('streamId' in data)) {
- return null;
- }
-
- const streamId = (data as { streamId?: unknown }).streamId;
- return typeof streamId === 'string' && streamId.length > 0 ? streamId : null;
-};
-
-/** The server returns `status: 'resumed'` when a duplicate start request was deduped to an
- * already-running stream: the client must subscribe with resume=true to replay its state
- * (prior content and any pending-action) rather than only receiving live events. */
-const isResumedStartResponse = (data: unknown): boolean =>
- data != null && typeof data === 'object' && (data as { status?: unknown }).status === 'resumed';
-
-const isSettledStartResponse = (data: unknown): boolean =>
- supportsGenerationProtocolV2(data) &&
- data != null &&
- typeof data === 'object' &&
- (data as { status?: unknown }).status === 'settled';
-
-const isReplacedStartResponse = (data: unknown): boolean =>
- supportsGenerationProtocolV2(data) &&
- data != null &&
- typeof data === 'object' &&
- (data as { status?: unknown }).status === 'replaced';
-
-const isUnnegotiatedV2StartControl = (data: unknown): boolean => {
- if (supportsGenerationProtocolV2(data) || data == null || typeof data !== 'object') {
- return false;
- }
- const status = (data as { status?: unknown }).status;
- return status === 'settled' || status === 'replaced';
-};
-
-const getStartGenerationConversationId = (data: unknown): string | null => {
- if (data == null || typeof data !== 'object' || !('conversationId' in data)) {
- return null;
- }
- const conversationId = (data as { conversationId?: unknown }).conversationId;
- return typeof conversationId === 'string' && conversationId.length > 0 ? conversationId : null;
-};
-
-const getStartGenerationCreatedAt = (data: unknown): number | null => {
- if (data == null || typeof data !== 'object' || !('generationCreatedAt' in data)) {
- return null;
- }
- const createdAt = (data as { generationCreatedAt?: unknown }).generationCreatedAt;
- return typeof createdAt === 'number' && Number.isSafeInteger(createdAt) && createdAt >= 0
- ? createdAt
- : null;
-};
-
-type PredecessorMismatchStartResponse = {
- streamId: string;
- conversationId: string;
- generationCreatedAt: number;
- active: boolean;
-};
-
-const getPredecessorMismatchStartResponse = (
- error: unknown,
-): PredecessorMismatchStartResponse | null => {
- const startError = toStartGenerationError(error);
- const data = startError?.response?.data;
- if (
- startError?.response?.status !== 409 ||
- data == null ||
- typeof data !== 'object' ||
- (data as { status?: unknown }).status !== 'predecessor_mismatch' ||
- (data as { code?: unknown }).code !== PREDECESSOR_MISMATCH_CODE
- ) {
- return null;
- }
-
- const streamId = getStartGenerationStreamId(data);
- const conversationId = getStartGenerationConversationId(data);
- if (!streamId || !conversationId) {
- return null;
- }
-
- const generationCreatedAt = getStartGenerationCreatedAt(data);
- const active = (data as { active?: unknown }).active;
- if (generationCreatedAt == null || typeof active !== 'boolean') {
- return null;
- }
- return {
- streamId,
- conversationId,
- generationCreatedAt,
- active,
- };
-};
-
-/** Recovery submissions use a deterministic request id tied to the parked
- * source. A status read performed only after this exact submission is proven
- * terminal may authorize that source past the client-side live-event
- * tombstone; unrelated status snapshots must remain deduped. */
-const getRecoverySteerId = (submission: TSubmission): string | null => {
- if (typeof submission.recoverySteerId === 'string' && submission.recoverySteerId.length > 0) {
- return submission.recoverySteerId;
- }
- const clientRequestId = submission.clientRequestId;
- if (
- typeof clientRequestId !== 'string' ||
- !clientRequestId.startsWith(STEER_RECOVERY_REQUEST_PREFIX)
- ) {
- return null;
- }
- const steerId = clientRequestId.slice(STEER_RECOVERY_REQUEST_PREFIX.length);
- return steerId.length > 0 ? steerId : null;
-};
-
-type StartGenerationResult =
- | {
- status: 'stream';
- streamId: string;
- resumed: boolean;
- generationCreatedAt?: number;
- generationProtocolVersion: GenerationProtocolVersion;
- }
- | {
- status: 'settled';
- conversationId: string;
- generationProtocolVersion: typeof GENERATION_PROTOCOL_VERSION;
- }
- | {
- status: 'replaced';
- streamId: string;
- conversationId: string;
- generationCreatedAt: number;
- generationProtocolVersion: typeof GENERATION_PROTOCOL_VERSION;
- }
- | {
- status: 'predecessor_mismatch';
- streamId: string;
- conversationId: string;
- generationCreatedAt: number;
- active: boolean;
- generationProtocolVersion: typeof GENERATION_PROTOCOL_VERSION;
- };
-
-const parseSSEErrorData = (body: string): unknown | null => {
- const blocks = body.split(/\r?\n\r?\n/);
- for (const block of blocks) {
- const lines = block.split(/\r?\n/);
- const event = lines
- .find((line) => line.startsWith('event:'))
- ?.slice('event:'.length)
- .trim();
- if (event !== 'error') {
- continue;
- }
-
- const data = lines
- .filter((line) => line.startsWith('data:'))
- .map((line) => line.slice('data:'.length).trimStart())
- .join('\n')
- .trim();
-
- if (!data) {
- return null;
- }
-
- try {
- return JSON.parse(data);
- } catch {
- return data;
- }
- }
-
- return null;
-};
-
-const getSSEErrorText = (payload: unknown): string | null => {
- if (typeof payload === 'string') {
- return payload;
- }
-
- if (payload == null || typeof payload !== 'object') {
- return null;
- }
-
- const record = payload as Record<string, unknown>;
- const text = record.text ?? record.message ?? record.error;
- return typeof text === 'string' && text.length > 0 ? text : null;
-};
-
-const getStreamStartFailureText = (errorData?: unknown): string => {
- if (typeof errorData === 'string') {
- const sseErrorData = parseSSEErrorData(errorData);
- if (sseErrorData != null) {
- return getSSEErrorText(sseErrorData) ?? JSON.stringify(sseErrorData);
- }
-
- return errorData || 'Error connecting to server, try refreshing the page.';
- }
-
- return errorData
- ? JSON.stringify(errorData)
- : 'Error connecting to server, try refreshing the page.';
-};
-
const getStreamStartFailureData = (errorData?: unknown, termsRefusalText?: string): TResData =>
({
text: termsRefusalText ?? getStreamStartFailureText(errorData),
metadata: markStreamStartFailedMetadata(),
}) as unknown as TResData;
-const isRetryableNetworkError = (error: unknown) => {
- if (!(error instanceof Error)) {
- return false;
- }
-
- const { code } = toStartGenerationError(error) ?? {};
- return code === 'ERR_NETWORK' || code === 'ERR_INTERNET_DISCONNECTED';
-};
-
-const isServerNotReadyError = (error: unknown) => {
- const candidate = toStartGenerationError(error);
- const data = candidate?.response?.data;
- const code =
- data != null && typeof data === 'object' && 'code' in data
- ? (data as { code?: unknown }).code
- : undefined;
- return candidate?.response?.status === 503 && code === SERVER_NOT_READY_CODE;
-};
-
-const getRetryAfterDelay = (error: unknown, fallbackDelay: number) => {
- const headers = toStartGenerationError(error)?.response?.headers;
- const rawValue = headers?.['retry-after'] ?? headers?.['Retry-After'];
- const retryAfter = Array.isArray(rawValue) ? rawValue[0] : rawValue;
- const seconds = typeof retryAfter === 'number' ? retryAfter : Number(retryAfter);
-
- if (!Number.isFinite(seconds) || seconds < 0) {
- return fallbackDelay;
- }
-
- return Math.min(seconds * 1000, 30000);
-};
-
-const waitForRetryDelay = (delay: number, signal?: AbortSignal): Promise<boolean> =>
- new Promise((resolve) => {
- if (signal?.aborted) {
- resolve(false);
- return;
- }
-
- function cleanup() {
- signal?.removeEventListener('abort', onAbort);
- }
- function onAbort() {
- clearTimeout(timeout);
- cleanup();
- resolve(false);
- }
- const timeout = setTimeout(() => {
- cleanup();
- resolve(true);
- }, delay);
-
- signal?.addEventListener('abort', onAbort, { once: true });
- });
-
const hasConcreteConversationId = (conversationId?: string | null) =>
!!conversationId &&
conversationId !== Constants.NEW_CONVO &&
@@ -438,81 +180,6 @@ const isInitialNewConversation = (submission: TSubmission) => {
return !hasConcreteConversationId(conversationId);
};
-const getToolCallName = (toolCall: unknown) =>
- toolCall != null && typeof toolCall === 'object' && 'name' in toolCall
- ? (toolCall.name as unknown)
- : undefined;
-
-const isOAuthToolCallName = (name: unknown) =>
- typeof name === 'string' && name.startsWith(`oauth${Constants.mcp_delimiter}`);
-
-const hasOAuthToolCall = (toolCalls: unknown) =>
- Array.isArray(toolCalls) &&
- toolCalls.some((toolCall) => isOAuthToolCallName(getToolCallName(toolCall)));
-
-const isOAuthStepEvent = (data: unknown) => {
- if (data == null || typeof data !== 'object' || !('event' in data)) {
- return false;
- }
-
- const event = data.event;
- const payload = 'data' in data ? data.data : undefined;
- if (payload == null || typeof payload !== 'object') {
- return false;
- }
-
- if (event === StepEvents.ON_RUN_STEP) {
- const stepDetails = 'stepDetails' in payload ? payload.stepDetails : undefined;
- return (
- stepDetails != null &&
- typeof stepDetails === 'object' &&
- 'tool_calls' in stepDetails &&
- hasOAuthToolCall(stepDetails.tool_calls)
- );
- }
-
- if (event === StepEvents.ON_RUN_STEP_DELTA) {
- const delta = 'delta' in payload ? payload.delta : undefined;
- if (delta == null || typeof delta !== 'object') {
- return false;
- }
- return (
- ('auth' in delta && delta.auth != null) ||
- ('tool_calls' in delta && hasOAuthToolCall(delta.tool_calls))
- );
- }
-
- if (event === StepEvents.ON_RUN_STEP_COMPLETED) {
- const result = 'result' in payload ? payload.result : undefined;
- if (result == null || typeof result !== 'object' || !('tool_call' in result)) {
- return false;
- }
- return isOAuthToolCallName(getToolCallName(result.tool_call));
- }
-
- return false;
-};
-
-const getStepEventId = (event: unknown): string | undefined => {
- if (event == null || typeof event !== 'object' || !('data' in event)) {
- return undefined;
- }
- const data = event.data;
- if (data == null || typeof data !== 'object') {
- return undefined;
- }
- if ('id' in data && typeof data.id === 'string') {
- return data.id;
- }
- const result = 'result' in data ? data.result : undefined;
- return result != null &&
- typeof result === 'object' &&
- 'id' in result &&
- typeof result.id === 'string'
- ? result.id
- : undefined;
-};
-
const replaceNewConversationUrl = (conversationId: string) => {
if (window.location.pathname !== `/c/${Constants.NEW_CONVO}`) {
return;
diff --git a/packages/chat/src/core/__tests__/start.spec.ts b/packages/chat/src/core/__tests__/start.spec.ts
new file mode 100644
index 0000000000..4769fe2cff
--- /dev/null
+++ b/packages/chat/src/core/__tests__/start.spec.ts
@@ -0,0 +1,129 @@
+import type { TSubmission } from 'librechat-data-provider';
+import {
+ getReconnectDelay,
+ waitForRetryDelay,
+ getRecoverySteerId,
+ getRetryAfterDelay,
+ isServerNotReadyError,
+ isSettledStartResponse,
+ isResumedStartResponse,
+ isRetryableNetworkError,
+ isReplacedStartResponse,
+ getStreamStartFailureText,
+ getStartGenerationStreamId,
+ getStartGenerationCreatedAt,
+ isUnnegotiatedV2StartControl,
+ getPredecessorMismatchStartResponse,
+} from '../resumable';
+import { supportsGenerationProtocolV2, getGenerationProtocolVersion } from '../protocol';
+
+/** An HTTP failure as the generation POST rejects with it. */
+const httpError = (status: number, data: unknown, headers: Record<string, string> = {}) =>
+ Object.assign(new Error('request failed'), { response: { status, data, headers } });
+
+describe('generation protocol negotiation', () => {
+ it.each([
+ [{ generationProtocolVersion: 2 }, 2],
+ [{ generationProtocolVersion: 1 }, 1],
+ [{ generationProtocolVersion: '2' }, 1],
+ [{}, 1],
+ [undefined, 1],
+ ] as const)('fails closed for protocol echo %#', (value, expected) => {
+ expect(getGenerationProtocolVersion(value)).toBe(expected);
+ expect(supportsGenerationProtocolV2(value)).toBe(expected === 2);
+ });
+});
+
+describe('start responses', () => {
+ it('reads the stream id and the generation epoch only when well formed', () => {
+ expect(getStartGenerationStreamId({ streamId: 's-1' })).toBe('s-1');
+ expect(getStartGenerationStreamId({ streamId: '' })).toBeNull();
+ expect(getStartGenerationStreamId(null)).toBeNull();
+ expect(getStartGenerationCreatedAt({ generationCreatedAt: 1000 })).toBe(1000);
+ expect(getStartGenerationCreatedAt({ generationCreatedAt: -1 })).toBeNull();
+ expect(getStartGenerationCreatedAt({ generationCreatedAt: 1.5 })).toBeNull();
+ });
+
+ it('honors settled and replaced only on a negotiated v2 response', () => {
+ const v2 = { generationProtocolVersion: 2 };
+ expect(isSettledStartResponse({ ...v2, status: 'settled' })).toBe(true);
+ expect(isReplacedStartResponse({ ...v2, status: 'replaced' })).toBe(true);
+ expect(isSettledStartResponse({ status: 'settled' })).toBe(false);
+ expect(isUnnegotiatedV2StartControl({ status: 'replaced' })).toBe(true);
+ expect(isUnnegotiatedV2StartControl({ ...v2, status: 'replaced' })).toBe(false);
+ expect(isResumedStartResponse({ status: 'resumed' })).toBe(true);
+ });
+
+ it('reads a predecessor mismatch only from its complete 409 body', () => {
+ const body = {
+ status: 'predecessor_mismatch',
+ code: 'GENERATION_PREDECESSOR_MISMATCH',
+ streamId: 's-1',
+ conversationId: 'c-1',
+ generationCreatedAt: 5,
+ active: true,
+ };
+ expect(getPredecessorMismatchStartResponse(httpError(409, body))).toEqual({
+ streamId: 's-1',
+ conversationId: 'c-1',
+ generationCreatedAt: 5,
+ active: true,
+ });
+ expect(getPredecessorMismatchStartResponse(httpError(400, body))).toBeNull();
+ expect(
+ getPredecessorMismatchStartResponse(httpError(409, { ...body, active: 'yes' })),
+ ).toBeNull();
+ });
+
+ it('names the parked steer a recovery submission replays', () => {
+ const submission = (fields: Partial<TSubmission>) => fields as TSubmission;
+ expect(getRecoverySteerId(submission({ recoverySteerId: 'steer-1' }))).toBe('steer-1');
+ expect(getRecoverySteerId(submission({ clientRequestId: 'steer-recovery:steer-2' }))).toBe(
+ 'steer-2',
+ );
+ expect(getRecoverySteerId(submission({ clientRequestId: 'steer-recovery:' }))).toBeNull();
+ expect(getRecoverySteerId(submission({ clientRequestId: 'other' }))).toBeNull();
+ });
+});
+
+describe('start retries', () => {
+ it('backs off exponentially up to the cap', () => {
+ expect([1, 2, 3, 6, 10].map(getReconnectDelay)).toEqual([1000, 2000, 4000, 30000, 30000]);
+ });
+
+ it('retries network failures and a server that is not ready yet', () => {
+ expect(isRetryableNetworkError(Object.assign(new Error(), { code: 'ERR_NETWORK' }))).toBe(true);
+ expect(isRetryableNetworkError({ code: 'ERR_NETWORK' })).toBe(false);
+ expect(isServerNotReadyError(httpError(503, { code: 'SERVER_NOT_READY' }))).toBe(true);
+ expect(isServerNotReadyError(httpError(503, {}))).toBe(false);
+ });
+
+ it('waits as long as Retry-After asks, within bounds', () => {
+ expect(getRetryAfterDelay(httpError(503, {}, { 'retry-after': '3' }), 500)).toBe(3000);
+ expect(getRetryAfterDelay(httpError(503, {}, { 'Retry-After': '90' }), 500)).toBe(30000);
+ expect(getRetryAfterDelay(httpError(503, {}, { 'retry-after': 'soon' }), 500)).toBe(500);
+ });
+
+ it('resolves false when the wait is aborted', async () => {
+ const controller = new AbortController();
+ const waiting = waitForRetryDelay(60000, controller.signal);
+ controller.abort();
+ await expect(waiting).resolves.toBe(false);
+ await expect(waitForRetryDelay(0)).resolves.toBe(true);
+ });
+});
+
+describe('getStreamStartFailureText', () => {
+ it('reads the error event out of an SSE body', () => {
+ const body = 'event: message\ndata: {}\n\nevent: error\ndata: {"message":"quota"}\n\n';
+ expect(getStreamStartFailureText(body)).toBe('quota');
+ });
+
+ it('falls back to the raw body, the JSON payload, or the connection message', () => {
+ expect(getStreamStartFailureText('plain failure')).toBe('plain failure');
+ expect(getStreamStartFailureText({ code: 1 })).toBe('{"code":1}');
+ expect(getStreamStartFailureText()).toBe(
+ 'Error connecting to server, try refreshing the page.',
+ );
+ });
+});
diff --git a/packages/chat/src/core/index.ts b/packages/chat/src/core/index.ts
index 2c531f4964..542d3ab76a 100644
--- a/packages/chat/src/core/index.ts
+++ b/packages/chat/src/core/index.ts
@@ -1,4 +1,5 @@
export * from './ask';
+export * from './resumable';
export * from './steps';
export * from './steer';
export * from './types';
diff --git a/packages/chat/src/core/resumable/errors.ts b/packages/chat/src/core/resumable/errors.ts
new file mode 100644
index 0000000000..7a9161de98
--- /dev/null
+++ b/packages/chat/src/core/resumable/errors.ts
@@ -0,0 +1,60 @@
+const parseSSEErrorData = (body: string): unknown | null => {
+ const blocks = body.split(/\r?\n\r?\n/);
+ for (const block of blocks) {
+ const lines = block.split(/\r?\n/);
+ const event = lines
+ .find((line) => line.startsWith('event:'))
+ ?.slice('event:'.length)
+ .trim();
+ if (event !== 'error') {
+ continue;
+ }
+
+ const data = lines
+ .filter((line) => line.startsWith('data:'))
+ .map((line) => line.slice('data:'.length).trimStart())
+ .join('\n')
+ .trim();
+
+ if (!data) {
+ return null;
+ }
+
+ try {
+ return JSON.parse(data);
+ } catch {
+ return data;
+ }
+ }
+
+ return null;
+};
+
+const getSSEErrorText = (payload: unknown): string | null => {
+ if (typeof payload === 'string') {
+ return payload;
+ }
+
+ if (payload == null || typeof payload !== 'object') {
+ return null;
+ }
+
+ const record = payload as Record<string, unknown>;
+ const text = record.text ?? record.message ?? record.error;
+ return typeof text === 'string' && text.length > 0 ? text : null;
+};
+
+export const getStreamStartFailureText = (errorData?: unknown): string => {
+ if (typeof errorData === 'string') {
+ const sseErrorData = parseSSEErrorData(errorData);
+ if (sseErrorData != null) {
+ return getSSEErrorText(sseErrorData) ?? JSON.stringify(sseErrorData);
+ }
+
+ return errorData || 'Error connecting to server, try refreshing the page.';
+ }
+
+ return errorData
+ ? JSON.stringify(errorData)
+ : 'Error connecting to server, try refreshing the page.';
+};
diff --git a/packages/chat/src/core/resumable/events.ts b/packages/chat/src/core/resumable/events.ts
new file mode 100644
index 0000000000..e02c765dbe
--- /dev/null
+++ b/packages/chat/src/core/resumable/events.ts
@@ -0,0 +1,76 @@
+import { Constants, StepEvents } from 'librechat-data-provider';
+
+const getToolCallName = (toolCall: unknown): unknown =>
+ toolCall != null && typeof toolCall === 'object' && 'name' in toolCall
+ ? (toolCall.name as unknown)
+ : undefined;
+
+const isOAuthToolCallName = (name: unknown): boolean =>
+ typeof name === 'string' && name.startsWith(`oauth${Constants.mcp_delimiter}`);
+
+const hasOAuthToolCall = (toolCalls: unknown): boolean =>
+ Array.isArray(toolCalls) &&
+ toolCalls.some((toolCall) => isOAuthToolCallName(getToolCallName(toolCall)));
+
+export const isOAuthStepEvent = (data: unknown): boolean => {
+ if (data == null || typeof data !== 'object' || !('event' in data)) {
+ return false;
+ }
+
+ const event = data.event;
+ const payload = 'data' in data ? data.data : undefined;
+ if (payload == null || typeof payload !== 'object') {
+ return false;
+ }
+
+ if (event === StepEvents.ON_RUN_STEP) {
+ const stepDetails = 'stepDetails' in payload ? payload.stepDetails : undefined;
+ return (
+ stepDetails != null &&
+ typeof stepDetails === 'object' &&
+ 'tool_calls' in stepDetails &&
+ hasOAuthToolCall(stepDetails.tool_calls)
+ );
+ }
+
+ if (event === StepEvents.ON_RUN_STEP_DELTA) {
+ const delta = 'delta' in payload ? payload.delta : undefined;
+ if (delta == null || typeof delta !== 'object') {
+ return false;
+ }
+ return (
+ ('auth' in delta && delta.auth != null) ||
+ ('tool_calls' in delta && hasOAuthToolCall(delta.tool_calls))
+ );
+ }
+
+ if (event === StepEvents.ON_RUN_STEP_COMPLETED) {
+ const result = 'result' in payload ? payload.result : undefined;
+ if (result == null || typeof result !== 'object' || !('tool_call' in result)) {
+ return false;
+ }
+ return isOAuthToolCallName(getToolCallName(result.tool_call));
+ }
+
+ return false;
+};
+
+export const getStepEventId = (event: unknown): string | undefined => {
+ if (event == null || typeof event !== 'object' || !('data' in event)) {
+ return undefined;
+ }
+ const data = event.data;
+ if (data == null || typeof data !== 'object') {
+ return undefined;
+ }
+ if ('id' in data && typeof data.id === 'string') {
+ return data.id;
+ }
+ const result = 'result' in data ? data.result : undefined;
+ return result != null &&
+ typeof result === 'object' &&
+ 'id' in result &&
+ typeof result.id === 'string'
+ ? result.id
+ : undefined;
+};
diff --git a/packages/chat/src/core/resumable/index.ts b/packages/chat/src/core/resumable/index.ts
new file mode 100644
index 0000000000..94f7190768
--- /dev/null
+++ b/packages/chat/src/core/resumable/index.ts
@@ -0,0 +1,3 @@
+export * from './start';
+export * from './errors';
+export * from './events';
diff --git a/packages/chat/src/core/resumable/start.ts b/packages/chat/src/core/resumable/start.ts
new file mode 100644
index 0000000000..7f4da00495
--- /dev/null
+++ b/packages/chat/src/core/resumable/start.ts
@@ -0,0 +1,223 @@
+import type { TSubmission } from 'librechat-data-provider';
+import type { GenerationProtocolVersion } from '../protocol';
+import { GENERATION_PROTOCOL_VERSION, supportsGenerationProtocolV2 } from '../protocol';
+
+export const MAX_RETRIES = 5;
+const RECONNECT_BASE_DELAY_MS = 1000;
+const RECONNECT_MAX_DELAY_MS = 30000;
+export const getReconnectDelay = (attempt: number): number =>
+ Math.min(RECONNECT_BASE_DELAY_MS * Math.pow(2, attempt - 1), RECONNECT_MAX_DELAY_MS);
+export const START_GENERATION_NETWORK_RETRIES = 3;
+export const START_GENERATION_READINESS_TIMEOUT_MS = 120000;
+const SERVER_NOT_READY_CODE = 'SERVER_NOT_READY';
+const PREDECESSOR_MISMATCH_CODE = 'GENERATION_PREDECESSOR_MISMATCH';
+const STEER_RECOVERY_REQUEST_PREFIX = 'steer-recovery:';
+
+export type StartGenerationError = {
+ code?: string;
+ response?: {
+ status?: number;
+ data?: unknown;
+ headers?: Record<string, string | number | string[] | undefined>;
+ };
+};
+
+export const toStartGenerationError = (error: unknown): StartGenerationError | undefined =>
+ error != null && typeof error === 'object' ? (error as StartGenerationError) : undefined;
+
+export const getStartGenerationStreamId = (data: unknown): string | null => {
+ if (data == null || typeof data !== 'object' || !('streamId' in data)) {
+ return null;
+ }
+
+ const streamId = (data as { streamId?: unknown }).streamId;
+ return typeof streamId === 'string' && streamId.length > 0 ? streamId : null;
+};
+
+/** The server returns `status: 'resumed'` when a duplicate start request was deduped to an
+ * already-running stream: the client must subscribe with resume=true to replay its state
+ * (prior content and any pending-action) rather than only receiving live events. */
+export const isResumedStartResponse = (data: unknown): boolean =>
+ data != null && typeof data === 'object' && (data as { status?: unknown }).status === 'resumed';
+
+export const isSettledStartResponse = (data: unknown): boolean =>
+ supportsGenerationProtocolV2(data) &&
+ data != null &&
+ typeof data === 'object' &&
+ (data as { status?: unknown }).status === 'settled';
+
+export const isReplacedStartResponse = (data: unknown): boolean =>
+ supportsGenerationProtocolV2(data) &&
+ data != null &&
+ typeof data === 'object' &&
+ (data as { status?: unknown }).status === 'replaced';
+
+export const isUnnegotiatedV2StartControl = (data: unknown): boolean => {
+ if (supportsGenerationProtocolV2(data) || data == null || typeof data !== 'object') {
+ return false;
+ }
+ const status = (data as { status?: unknown }).status;
+ return status === 'settled' || status === 'replaced';
+};
+
+export const getStartGenerationConversationId = (data: unknown): string | null => {
+ if (data == null || typeof data !== 'object' || !('conversationId' in data)) {
+ return null;
+ }
+ const conversationId = (data as { conversationId?: unknown }).conversationId;
+ return typeof conversationId === 'string' && conversationId.length > 0 ? conversationId : null;
+};
+
+export const getStartGenerationCreatedAt = (data: unknown): number | null => {
+ if (data == null || typeof data !== 'object' || !('generationCreatedAt' in data)) {
+ return null;
+ }
+ const createdAt = (data as { generationCreatedAt?: unknown }).generationCreatedAt;
+ return typeof createdAt === 'number' && Number.isSafeInteger(createdAt) && createdAt >= 0
+ ? createdAt
+ : null;
+};
+
+export type PredecessorMismatchStartResponse = {
+ streamId: string;
+ conversationId: string;
+ generationCreatedAt: number;
+ active: boolean;
+};
+
+export const getPredecessorMismatchStartResponse = (
+ error: unknown,
+): PredecessorMismatchStartResponse | null => {
+ const startError = toStartGenerationError(error);
+ const data = startError?.response?.data;
+ if (
+ startError?.response?.status !== 409 ||
+ data == null ||
+ typeof data !== 'object' ||
+ (data as { status?: unknown }).status !== 'predecessor_mismatch' ||
+ (data as { code?: unknown }).code !== PREDECESSOR_MISMATCH_CODE
+ ) {
+ return null;
+ }
+
+ const streamId = getStartGenerationStreamId(data);
+ const conversationId = getStartGenerationConversationId(data);
+ if (!streamId || !conversationId) {
+ return null;
+ }
+
+ const generationCreatedAt = getStartGenerationCreatedAt(data);
+ const active = (data as { active?: unknown }).active;
+ if (generationCreatedAt == null || typeof active !== 'boolean') {
+ return null;
+ }
+ return {
+ streamId,
+ conversationId,
+ generationCreatedAt,
+ active,
+ };
+};
+
+/** Recovery submissions use a deterministic request id tied to the parked
+ * source. A status read performed only after this exact submission is proven
+ * terminal may authorize that source past the client-side live-event
+ * tombstone; unrelated status snapshots must remain deduped. */
+export const getRecoverySteerId = (submission: TSubmission): string | null => {
+ if (typeof submission.recoverySteerId === 'string' && submission.recoverySteerId.length > 0) {
+ return submission.recoverySteerId;
+ }
+ const clientRequestId = submission.clientRequestId;
+ if (
+ typeof clientRequestId !== 'string' ||
+ !clientRequestId.startsWith(STEER_RECOVERY_REQUEST_PREFIX)
+ ) {
+ return null;
+ }
+ const steerId = clientRequestId.slice(STEER_RECOVERY_REQUEST_PREFIX.length);
+ return steerId.length > 0 ? steerId : null;
+};
+
+export type StartGenerationResult =
+ | {
+ status: 'stream';
+ streamId: string;
+ resumed: boolean;
+ generationCreatedAt?: number;
+ generationProtocolVersion: GenerationProtocolVersion;
+ }
+ | {
+ status: 'settled';
+ conversationId: string;
+ generationProtocolVersion: typeof GENERATION_PROTOCOL_VERSION;
+ }
+ | {
+ status: 'replaced';
+ streamId: string;
+ conversationId: string;
+ generationCreatedAt: number;
+ generationProtocolVersion: typeof GENERATION_PROTOCOL_VERSION;
+ }
+ | {
+ status: 'predecessor_mismatch';
+ streamId: string;
+ conversationId: string;
+ generationCreatedAt: number;
+ active: boolean;
+ generationProtocolVersion: typeof GENERATION_PROTOCOL_VERSION;
+ };
+
+export const isRetryableNetworkError = (error: unknown): boolean => {
+ if (!(error instanceof Error)) {
+ return false;
+ }
+
+ const { code } = toStartGenerationError(error) ?? {};
+ return code === 'ERR_NETWORK' || code === 'ERR_INTERNET_DISCONNECTED';
+};
+
+export const isServerNotReadyError = (error: unknown): boolean => {
+ const candidate = toStartGenerationError(error);
+ const data = candidate?.response?.data;
+ const code =
+ data != null && typeof data === 'object' && 'code' in data
+ ? (data as { code?: unknown }).code
+ : undefined;
+ return candidate?.response?.status === 503 && code === SERVER_NOT_READY_CODE;
+};
+
+export const getRetryAfterDelay = (error: unknown, fallbackDelay: number): number => {
+ const headers = toStartGenerationError(error)?.response?.headers;
+ const rawValue = headers?.['retry-after'] ?? headers?.['Retry-After'];
+ const retryAfter = Array.isArray(rawValue) ? rawValue[0] : rawValue;
+ const seconds = typeof retryAfter === 'number' ? retryAfter : Number(retryAfter);
+
+ if (!Number.isFinite(seconds) || seconds < 0) {
+ return fallbackDelay;
+ }
+
+ return Math.min(seconds * 1000, 30000);
+};
+
+export const waitForRetryDelay = (delay: number, signal?: AbortSignal): Promise<boolean> =>
+ new Promise((resolve) => {
+ if (signal?.aborted) {
+ resolve(false);
+ return;
+ }
+
+ function cleanup() {
+ signal?.removeEventListener('abort', onAbort);
+ }
+ function onAbort() {
+ clearTimeout(timeout);
+ cleanup();
+ resolve(false);
+ }
+ const timeout = setTimeout(() => {
+ cleanup();
+ resolve(true);
+ }, delay);
+
+ signal?.addEventListener('abort', onAbort, { once: true });
+ });