From 3709e1fcec2edada9a06afdf841d3cff61be3d98 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Thu, 15 Oct 2026 17:19:36 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=B0=20refactor:=20Move=20Resumable=20S?= =?UTF-8?q?tart=20Helpers=20Into=20the=20Chat=20Core=20(#17109)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- client/src/hooks/SSE/useResumableSSE.ts | 405 ++---------------- .../chat/src/core/__tests__/start.spec.ts | 129 ++++++ packages/chat/src/core/index.ts | 1 + packages/chat/src/core/resumable/errors.ts | 60 +++ packages/chat/src/core/resumable/events.ts | 76 ++++ packages/chat/src/core/resumable/index.ts | 3 + packages/chat/src/core/resumable/start.ts | 223 ++++++++++ 7 files changed, 528 insertions(+), 369 deletions(-) create mode 100644 packages/chat/src/core/__tests__/start.spec.ts create mode 100644 packages/chat/src/core/resumable/errors.ts create mode 100644 packages/chat/src/core/resumable/events.ts create mode 100644 packages/chat/src/core/resumable/index.ts create mode 100644 packages/chat/src/core/resumable/start.ts 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; - }; -}; - -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; - 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 => - 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 = {}) => + 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) => 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; + 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; + }; +}; + +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 => + 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 }); + });