Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🌊 refactor: Move the Stream Step Handler Into the Chat Package (#17555)
Marco Berettabf0b529e1652
diff --git a/client/src/common/a11y.ts b/client/src/common/a11y.tsindex 0a0e56eab2..01673cf542 100644--- a/client/src/common/a11y.ts+++ b/client/src/common/a11y.ts@@ -1,6 +1,2 @@-export interface AnnounceOptions {- message: string;- isStatus?: boolean;-}--export const MESSAGE_UPDATE_INTERVAL = 7000;+export { MESSAGE_UPDATE_INTERVAL } from '@librechat/chat';+export type { AnnounceOptions } from '@librechat/chat';diff --git a/client/src/common/ptc.ts b/client/src/common/ptc.tsindex bf3047d23d..5fa86b1cf2 100644--- a/client/src/common/ptc.ts+++ b/client/src/common/ptc.ts@@ -1,29 +1 @@-import type { PtcToolCallStatus } from 'librechat-data-provider';--/**- * A row's outcome. Widens the wire status with `interrupted`, which the- * backend never sends: it is what the client concludes locally about a call- * that was still running when a stream gap swallowed its settling event.- */-export type PtcTraceStatus = PtcToolCallStatus | 'interrupted';--/** One tool call a programmatic (PTC) program made from inside the sandbox. */-export interface PtcTraceEntry {- /** Stable id from the backend; the settle event updates this row in place. */- callId: string;- /** Inner tool id, e.g. `search_code_mcp_github`. */- name: string;- status: PtcTraceStatus;- /** `key=value` preview of the call's input. */- args?: string;- /** Truncated failure message on a failed call. */- error?: string;- durationMs?: number;-}--/** One PTC program's trace: the retained tail plus what the cap discarded. */-export interface PtcTrace {- entries: PtcTraceEntry[];- /** Rows evicted by the trace cap (`PTC_TRACE_MAX_ENTRIES`), so the cap is never silent. */- dropped: number;-}+export type { PtcTrace, PtcTraceEntry, PtcTraceStatus } from '@librechat/chat';diff --git a/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts b/client/src/hooks/SSE/__tests__/stepEquivalence.spec.tsindex 451968d3b0..d59f60b0e4 100644--- a/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts+++ b/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts@@ -2,6 +2,7 @@ import React from 'react';import { createHash } from 'crypto';import { RecoilRoot } from 'recoil';import { createStore, Provider } from 'jotai';+import { useStepHandler } from '@librechat/chat/react';import { renderHook, act } from '@testing-library/react';import {Constants,@@ -27,7 +28,6 @@ import type {import type { StepEvent } from '@librechat/chat';import { ptcTraceByToolCallId, ptcTraceKey } from '~/hooks/SSE/ptc';import { sandboxStartingByToolCallId } from '~/hooks/SSE/sandbox';-import useStepHandler from '~/hooks/SSE/useStepHandler';/*** Equivalence table for the step reducer. Each row is an event sequence shaped like a recordeddiff --git a/client/src/hooks/SSE/__tests__/titles.spec.tsx b/client/src/hooks/SSE/__tests__/titles.spec.tsxindex 4602270c25..0d9cecaa7a 100644--- a/client/src/hooks/SSE/__tests__/titles.spec.tsx+++ b/client/src/hooks/SSE/__tests__/titles.spec.tsx@@ -14,9 +14,12 @@ jest.mock('~/hooks/AuthContext', () => ({ useAuthContext: () => ({ token: 'test'jest.mock('~/Providers', () => ({ useLiveAnnouncer: () => ({ announcePolite: jest.fn() }) }));jest.mock('../useContentHandler', () => () => ({}));jest.mock('../useAttachmentHandler', () => () => jest.fn());-jest.mock('../useStepHandler', () => () => ({- resetSubagentAtoms: jest.fn(),- resetPtcAtoms: jest.fn(),+jest.mock('@librechat/chat/react', () => ({+ ...jest.requireActual('@librechat/chat/react'),+ useStepHandler: () => ({+ resetSubagentAtoms: jest.fn(),+ resetPtcAtoms: jest.fn(),+ }),}));const initialConversation = {diff --git a/client/src/hooks/SSE/__tests__/useEventHandlers.cancel.spec.tsx b/client/src/hooks/SSE/__tests__/useEventHandlers.cancel.spec.tsxindex 6c9099f4df..e7dccbc739 100644--- a/client/src/hooks/SSE/__tests__/useEventHandlers.cancel.spec.tsx+++ b/client/src/hooks/SSE/__tests__/useEventHandlers.cancel.spec.tsx@@ -38,15 +38,18 @@ jest.mock('../useContentHandler', () => () => ({resetContentHandler: jest.fn(),}));jest.mock('../useAttachmentHandler', () => () => jest.fn());-jest.mock('../useStepHandler', () => () => ({- stepHandler: jest.fn(),- clearStepMaps: jest.fn(),- resetSubagentAtoms: mockResetSubagentAtoms,- resetPtcAtoms: mockResetPtcAtoms,- prunePtcTraces: jest.fn(),- syncStepMessage: jest.fn(),- cancelPendingDeltaFlush: jest.fn(),- flushPendingDeltas: jest.fn(),+jest.mock('@librechat/chat/react', () => ({+ ...jest.requireActual('@librechat/chat/react'),+ useStepHandler: () => ({+ stepHandler: jest.fn(),+ clearStepMaps: jest.fn(),+ resetSubagentAtoms: mockResetSubagentAtoms,+ resetPtcAtoms: mockResetPtcAtoms,+ prunePtcTraces: jest.fn(),+ syncStepMessage: jest.fn(),+ cancelPendingDeltaFlush: jest.fn(),+ flushPendingDeltas: jest.fn(),+ }),}));jest.mock('~/data-provider', () => ({...jest.requireActual('~/data-provider/CodeEnvironments'),diff --git a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts b/client/src/hooks/SSE/__tests__/useStepHandler.spec.tsindex 89fbe9699a..2772f43797 100644--- a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts+++ b/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts@@ -1,5 +1,6 @@import React from 'react';import { RecoilRoot } from 'recoil';+import { useStepHandler } from '@librechat/chat/react';import { renderHook, act } from '@testing-library/react';import { useStore, useAtomValue, createStore, Provider as JotaiProvider } from 'jotai';import {@@ -34,7 +35,6 @@ import type { PtcTrace, PtcTraceEntry } from '~/common';import { ptcTraceByToolCallId, ptcTraceKey, PTC_TRACE_MAX_ENTRIES } from '~/hooks/SSE/ptc';import { sandboxStartingByToolCallId } from '~/hooks/SSE/sandbox';import { resolveAskUserQuestionPart } from '~/utils/approval';-import useStepHandler from '~/hooks/SSE/useStepHandler';import { IsolatedAtomStore } from 'test/harness';/** `Constants` is a heterogeneous enum (`string | number`); annotate asdiff --git a/client/src/hooks/SSE/__tests__/workspace.spec.tsx b/client/src/hooks/SSE/__tests__/workspace.spec.tsxindex 51fd3dfca1..b0e70bfac9 100644--- a/client/src/hooks/SSE/__tests__/workspace.spec.tsx+++ b/client/src/hooks/SSE/__tests__/workspace.spec.tsx@@ -38,9 +38,12 @@ jest.mock('~/Providers', () => ({}));jest.mock('~/hooks/SSE/useContentHandler', () => () => ({}));jest.mock('~/hooks/SSE/useAttachmentHandler', () => () => jest.fn());-jest.mock('~/hooks/SSE/useStepHandler', () => () => ({- resetSubagentAtoms: mockReset,- resetPtcAtoms: mockReset,+jest.mock('@librechat/chat/react', () => ({+ ...jest.requireActual('@librechat/chat/react'),+ useStepHandler: () => ({+ resetSubagentAtoms: mockReset,+ resetPtcAtoms: mockReset,+ }),}));jest.mock('~/hooks/Agents/workspacePreferences', () => ({useWorkspacePreferences: () => ({ get: () => undefined }),diff --git a/client/src/hooks/SSE/index.ts b/client/src/hooks/SSE/index.tsindex f2438e42ba..a2d68c10e4 100644--- a/client/src/hooks/SSE/index.ts+++ b/client/src/hooks/SSE/index.ts@@ -1,7 +1,7 @@export { default as useSSE } from './useSSE';export { useResumableSSE, useAdaptiveSSE } from '@librechat/chat/react';export { default as useResumeOnLoad } from './useResumeOnLoad';-export { default as useStepHandler } from './useStepHandler';+export { useStepHandler } from '@librechat/chat/react';export { default as useUsageHandler } from './useUsageHandler';export { default as useContentHandler } from './useContentHandler';export { default as useAttachmentHandler } from './useAttachmentHandler';diff --git a/client/src/hooks/SSE/ptc.ts b/client/src/hooks/SSE/ptc.tsindex b1b9dba668..6a6ffc68b6 100644--- a/client/src/hooks/SSE/ptc.ts+++ b/client/src/hooks/SSE/ptc.ts@@ -1,34 +1,6 @@-import { atom } from 'jotai';-import { atomFamily } from 'jotai/utils';-import type { PtcTrace } from '~/common';--/**- * Stable identity for one PTC invocation in its parent message. Providers- * reuse `tool_call_id` across turns and agents, so the raw id is not- * sufficient identity for live progress — the same rule `subagentProgressKey`- * exists for. Without the message scope, a later program's rows would land in- * an earlier card that happened to share `call_0`.- */-export const ptcTraceKey = (parentMessageId: string, toolCallId: string) =>- `${parentMessageId}\u0000${toolCallId}`;--/**- * Rolling cap on retained rows. A program looping over a large collection can- * make thousands of inner calls; without a bound, every event would copy an- * ever-growing array and the card would render a row per call.- */-export const PTC_TRACE_MAX_ENTRIES = 100;--/** Shared empty value — one reference, so untouched atoms compare equal. */-export const EMPTY_PTC_TRACE: PtcTrace = { entries: [], dropped: 0 };--/**- * Live trace of the inner tool calls made by one PTC run step, in the order- * the sandbox started them (`on_ptc_tool_call` SSE events). Keyed by- * {@link ptcTraceKey} — one concrete invocation in one message.- *- * Session-scoped like the subagent ticker: inner calls open no run step, so- * nothing persists them on the message. Cleared on conversation switch rather- * than at run boundaries, so a finished program's trace stays readable.- */-export const ptcTraceByToolCallId = atomFamily((_key: string) => atom<PtcTrace>(EMPTY_PTC_TRACE));+export {+ ptcTraceKey,+ EMPTY_PTC_TRACE,+ ptcTraceByToolCallId,+ PTC_TRACE_MAX_ENTRIES,+} from '@librechat/chat/react';diff --git a/client/src/hooks/SSE/sandbox.ts b/client/src/hooks/SSE/sandbox.tsindex 30e7d8ad2a..96b79cdef3 100644--- a/client/src/hooks/SSE/sandbox.ts+++ b/client/src/hooks/SSE/sandbox.ts@@ -1,11 +1 @@-import { atom } from 'jotai';-import { atomFamily } from 'jotai/utils';--/**- * True while the backend reported the stateful code sandbox is cold-booting- * for this tool call (`on_sandbox_starting` SSE event). Keyed by- * `tool_call_id`; `ExecuteCode`/`BashCall` swap their in-progress label to a- * "starting sandbox" message while set. Cleared when the tool call's run- * step completes.- */-export const sandboxStartingByToolCallId = atomFamily((_toolCallId: string) => atom(false));+export { sandboxStartingByToolCallId } from '@librechat/chat/react';diff --git a/client/src/hooks/SSE/useEventHandlers.ts b/client/src/hooks/SSE/useEventHandlers.tsindex b1ff0898e3..22206a9388 100644--- a/client/src/hooks/SSE/useEventHandlers.ts+++ b/client/src/hooks/SSE/useEventHandlers.ts@@ -5,6 +5,7 @@ import { buildRecoveryPreset } from '@librechat/chat';import { useQueryClient } from '@tanstack/react-query';import { useParams, useNavigate, useLocation } from 'react-router-dom';import {+ useStepHandler,submissionStartFamily,getReasoningStateKey,pendingQuotesByConvoId,@@ -19,7 +20,6 @@ import { getFailedCodeDecisionRequest } from '~/hooks/Agents/codeDecision';import { shouldResetSubagentAtomsOnConversationChange } from './cleanup';import useAttachmentHandler from '~/hooks/SSE/useAttachmentHandler';import useContentHandler from '~/hooks/SSE/useContentHandler';-import useStepHandler from '~/hooks/SSE/useStepHandler';import { useApplyAgentTemplate } from '~/hooks/Agents';import { useLiveAnnouncer } from '~/Providers';import useTurnHandlers from './opening';diff --git a/packages/chat/src/core/a11y.ts b/packages/chat/src/core/a11y.tsnew file mode 100644index 0000000000..0a0e56eab2--- /dev/null+++ b/packages/chat/src/core/a11y.ts@@ -0,0 +1,6 @@+export interface AnnounceOptions {+ message: string;+ isStatus?: boolean;+}++export const MESSAGE_UPDATE_INTERVAL = 7000;diff --git a/packages/chat/src/core/index.ts b/packages/chat/src/core/index.tsindex d3c29f4d63..35a90defa0 100644--- a/packages/chat/src/core/index.ts+++ b/packages/chat/src/core/index.ts@@ -17,5 +17,7 @@ export * from './regenerate';export * from './content';export * from './turns';export * from './parts';+export * from './a11y';+export * from './ptc';export * from './subagents';export { strongDirection } from './direction';diff --git a/packages/chat/src/core/ptc.ts b/packages/chat/src/core/ptc.tsnew file mode 100644index 0000000000..bf3047d23d--- /dev/null+++ b/packages/chat/src/core/ptc.ts@@ -0,0 +1,29 @@+import type { PtcToolCallStatus } from 'librechat-data-provider';++/**+ * A row's outcome. Widens the wire status with `interrupted`, which the+ * backend never sends: it is what the client concludes locally about a call+ * that was still running when a stream gap swallowed its settling event.+ */+export type PtcTraceStatus = PtcToolCallStatus | 'interrupted';++/** One tool call a programmatic (PTC) program made from inside the sandbox. */+export interface PtcTraceEntry {+ /** Stable id from the backend; the settle event updates this row in place. */+ callId: string;+ /** Inner tool id, e.g. `search_code_mcp_github`. */+ name: string;+ status: PtcTraceStatus;+ /** `key=value` preview of the call's input. */+ args?: string;+ /** Truncated failure message on a failed call. */+ error?: string;+ durationMs?: number;+}++/** One PTC program's trace: the retained tail plus what the cap discarded. */+export interface PtcTrace {+ entries: PtcTraceEntry[];+ /** Rows evicted by the trace cap (`PTC_TRACE_MAX_ENTRIES`), so the cap is never silent. */+ dropped: number;+}diff --git a/packages/chat/src/react/stream/index.ts b/packages/chat/src/react/stream/index.tsindex 350dabbfa4..5ac49fe7d8 100644--- a/packages/chat/src/react/stream/index.ts+++ b/packages/chat/src/react/stream/index.ts@@ -1,4 +1,8 @@export { default as useAdaptiveSSE } from './adaptive';export { default as useResumableSSE } from './resumable';export { StreamHostProvider, useStreamHost } from './host';+export { useStepHandler } from './step';+export type { StepHandlers } from './step';+export { sandboxStartingByToolCallId } from './sandbox';+export { ptcTraceKey, ptcTraceByToolCallId, EMPTY_PTC_TRACE, PTC_TRACE_MAX_ENTRIES } from './ptc';export type { StreamHost, StreamChat, ResumableServices, ResumableStreamParams } from './host';diff --git a/packages/chat/src/react/stream/ptc.ts b/packages/chat/src/react/stream/ptc.tsnew file mode 100644index 0000000000..20bffeac38--- /dev/null+++ b/packages/chat/src/react/stream/ptc.ts@@ -0,0 +1,37 @@+import { atom } from 'jotai';+import { atomFamily } from 'jotai/utils';+import type { Family } from '../steer/family';+import type { PtcTrace } from '../../core';++/**+ * Stable identity for one PTC invocation in its parent message. Providers+ * reuse `tool_call_id` across turns and agents, so the raw id is not+ * sufficient identity for live progress, the same rule `subagentProgressKey`+ * exists for. Without the message scope, a later program's rows would land in+ * an earlier card that happened to share `call_0`.+ */+export const ptcTraceKey = (parentMessageId: string, toolCallId: string): string =>+ `${parentMessageId}\u0000${toolCallId}`;++/**+ * Rolling cap on retained rows. A program looping over a large collection can+ * make thousands of inner calls; without a bound, every event would copy an+ * ever-growing array and the card would render a row per call.+ */+export const PTC_TRACE_MAX_ENTRIES = 100;++/** Shared empty value: one reference, so untouched atoms compare equal. */+export const EMPTY_PTC_TRACE: PtcTrace = { entries: [], dropped: 0 };++/**+ * Live trace of the inner tool calls made by one PTC run step, in the order+ * the sandbox started them (`on_ptc_tool_call` SSE events). Keyed by+ * {@link ptcTraceKey}, one concrete invocation in one message.+ *+ * Session-scoped like the subagent ticker: inner calls open no run step, so+ * nothing persists them on the message. Cleared on conversation switch rather+ * than at run boundaries, so a finished program's trace stays readable.+ */+export const ptcTraceByToolCallId: Family<PtcTrace> = atomFamily((_key: string) =>+ atom<PtcTrace>(EMPTY_PTC_TRACE),+);diff --git a/packages/chat/src/react/stream/sandbox.ts b/packages/chat/src/react/stream/sandbox.tsnew file mode 100644index 0000000000..4ccfff7da6--- /dev/null+++ b/packages/chat/src/react/stream/sandbox.ts@@ -0,0 +1,14 @@+import { atom } from 'jotai';+import { atomFamily } from 'jotai/utils';+import type { Family } from '../steer/family';++/**+ * True while the backend reported the stateful code sandbox is cold-booting+ * for this tool call (`on_sandbox_starting` SSE event). Keyed by+ * `tool_call_id`; `ExecuteCode`/`BashCall` swap their in-progress label to a+ * "starting sandbox" message while set. Cleared when the tool call's run+ * step completes.+ */+export const sandboxStartingByToolCallId: Family<boolean> = atomFamily((_toolCallId: string) =>+ atom(false),+);diff --git a/client/src/hooks/SSE/useStepHandler.ts b/packages/chat/src/react/stream/step.tssimilarity index 95%rename from client/src/hooks/SSE/useStepHandler.tsrename to packages/chat/src/react/stream/step.tsindex 53e9b437a6..af6b3e4bbf 100644--- a/client/src/hooks/SSE/useStepHandler.ts+++ b/packages/chat/src/react/stream/step.ts@@ -1,14 +1,12 @@import { useCallback, useRef } from 'react';import { useStore } from 'jotai';-import {- reduceStep,- flushSummary,- flushResponses,- resetStreamState,- syncStreamMessage,- createStreamState,- subagentProgressKey,-} from '@librechat/chat';+import type {+ TMessage,+ EventSubmission,+ SubagentUpdateEvent,+ PtcToolCallEvent,+} from 'librechat-data-provider';+import type { StepEvent, StepEffect, StepContext, StreamState, AnnounceOptions } from '../../core';import {activeSubagentPanel,closeParentSubagentProgress,@@ -19,18 +17,19 @@ import {subagentParentStreamOpenByToolCallId,subagentProgressByToolCallId,takeRegisteredSubagentProgressKeys,-} from '@librechat/chat/react';-import type {- TMessage,- EventSubmission,- SubagentUpdateEvent,- PtcToolCallEvent,-} from 'librechat-data-provider';-import type { StepEvent, StepEffect, StepContext, StreamState } from '@librechat/chat';-import type { AnnounceOptions } from '~/common';+} from '../subagents/state';+import {+ reduceStep,+ flushSummary,+ flushResponses,+ resetStreamState,+ syncStreamMessage,+ createStreamState,+ subagentProgressKey,+ MESSAGE_UPDATE_INTERVAL,+} from '../../core';import { ptcTraceByToolCallId, EMPTY_PTC_TRACE, PTC_TRACE_MAX_ENTRIES, ptcTraceKey } from './ptc';import { sandboxStartingByToolCallId } from './sandbox';-import { MESSAGE_UPDATE_INTERVAL } from '~/common';type TUseStepHandler = {announcePolite: (options: AnnounceOptions) => void;@@ -46,14 +45,26 @@ type TUseStepHandler = {onSubagentIndexChange?: (conversationId: string) => void;};-export default function useStepHandler({+/** The handlers a pane's stream feeds run steps through, and the resets around a run. */+export type StepHandlers = {+ stepHandler: (stepEvent: StepEvent, submission: EventSubmission) => void;+ clearStepMaps: () => void;+ resetSubagentAtoms: (options?: { preserveSelectedTask?: boolean }) => void;+ resetPtcAtoms: () => void;+ prunePtcTraces: () => void;+ syncStepMessage: (message: TMessage) => void;+ cancelPendingDeltaFlush: () => void;+ flushPendingDeltas: () => void;+};++export function useStepHandler({setMessages,getMessages,announcePolite,lastAnnouncementTimeRef,onSkillAuthoringComplete,onSubagentIndexChange,-}: TUseStepHandler) {+}: TUseStepHandler): StepHandlers {const subagentStore = useStore();const stream = useRef<StreamState>(createStreamState());/** Coalesces rapid-fire summarize delta renders into a single rAF frame */