🌊 refactor: Move the Stream Step Handler Into the Chat Package (#17555)

This commit is contained in:
Marco Beretta 2026-10-29 20:40:26 +01:00 • committed by GitHub
parent 528820d81c
commit bf0b529e16
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 162 additions and 120 deletions

View file

@ -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';

View file

@ -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';

View file

@ -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

View file

@ -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 = {

View file

@ -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'),

View file

@ -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

View file

@ -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 }),

View file

@ -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';

View file

@ -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';

View file

@ -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';

View file

@ -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';

View file

@ -0,0 +1,6 @@
export interface AnnounceOptions {
message: string;
isStatus?: boolean;
}
export const MESSAGE_UPDATE_INTERVAL = 7000;

View file

@ -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';

View file

@ -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;
}

View file

@ -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';

View file

@ -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),
);

View file

@ -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),
);

View file

@ -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 */