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 the Stream Step Handler Into the Chat Package (#17555)

Marco Berettabf0b529e1652
diff --git a/client/src/common/a11y.ts b/client/src/common/a11y.ts
index 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.ts
index 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.ts
index 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 recorded
diff --git a/client/src/hooks/SSE/__tests__/titles.spec.tsx b/client/src/hooks/SSE/__tests__/titles.spec.tsx
index 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.tsx
index 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.ts
index 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 as
diff --git a/client/src/hooks/SSE/__tests__/workspace.spec.tsx b/client/src/hooks/SSE/__tests__/workspace.spec.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
similarity index 95%
rename from client/src/hooks/SSE/useStepHandler.ts
rename to packages/chat/src/react/stream/step.ts
index 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 */