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
import { useCallback, useRef } from 'react';
import { useStore } from 'jotai';
import type {
TMessage,
EventSubmission,
SubagentUpdateEvent,
PtcToolCallEvent,
} from 'librechat-data-provider';
import type { StepEvent, StepEffect, StepContext, StreamState, AnnounceOptions } from '../../core';
import {
activeSubagentPanel,
closeParentSubagentProgress,
listRegisteredSubagentProgressKeys,
reduceSubagentProgress,
registerSubagentProgressKey,
removeSubagentProgressAtoms,
subagentParentStreamOpenByToolCallId,
subagentProgressByToolCallId,
takeRegisteredSubagentProgressKeys,
} 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';
type TUseStepHandler = {
announcePolite: (options: AnnounceOptions) => void;
setMessages: (messages: TMessage[]) => void;
getMessages: () => TMessage[] | undefined;
lastAnnouncementTimeRef: React.MutableRefObject<number>;
/**
* Fired when a completed `create_file`/`edit_file` call targeted a
* `skills/...` path. The caller owns the side effect (skill query cache
* invalidation) so this hook stays free of query-client coupling.
*/
onSkillAuthoringComplete?: () => void;
onSubagentIndexChange?: (conversationId: string) => void;
};
/** 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): StepHandlers {
const subagentStore = useStore();
const stream = useRef<StreamState>(createStreamState());
/** Coalesces rapid-fire summarize delta renders into a single rAF frame */
const summarizeDeltaRaf = useRef<number | null>(null);
/** Coalesces per-token message/reasoning delta cache writes into one rAF frame.
* `deltaFlushScheduled` (not the handle) gates scheduling: the handle is
* assigned after `requestAnimationFrame` returns, which would race a
* synchronously-invoked callback. */
const messageDeltaRaf = useRef<number | null>(null);
const deltaFlushScheduled = useRef(false);
const pendingDeltaFlushIds = useRef(new Set<string>());
const pendingDeltaFlushRef = useRef<(() => void) | null>(null);
/** Both content parts and ticker lines are aggregated incrementally
* into the atom as each `ON_SUBAGENT_UPDATE` arrives; we never
* retain the raw event array, so no rolling window is needed. A
* talkative subagent can emit thousands of deltas without growing
* memory past what the structural output requires. */
const applySubagentProgress = useCallback(
(invocationKey: string, events: SubagentUpdateEvent[]): void => {
registerSubagentProgressKey(invocationKey);
subagentStore.set(subagentParentStreamOpenByToolCallId(invocationKey), true);
subagentStore.set(subagentProgressByToolCallId(invocationKey), (prev) =>
reduceSubagentProgress(prev, events, 'parent', true),
);
},
[subagentStore],
);
/** Navigation retains the selected durable task; host teardown drains every invocation. */
const resetSubagentAtoms = useCallback(
({ preserveSelectedTask = false }: { preserveSelectedTask?: boolean } = {}): void => {
const selected = preserveSelectedTask ? subagentStore.get(activeSubagentPanel) : null;
const retainedKey =
selected?.host === 'conversation' && selected.durable != null
? subagentProgressKey(
selected.parentMessageId,
selected.event?.progressKey ?? selected.toolCallId,
selected.partIndex,
)
: null;
for (const invocationKey of takeRegisteredSubagentProgressKeys()) {
subagentStore.set(subagentParentStreamOpenByToolCallId(invocationKey), false);
if (invocationKey === retainedKey) {
registerSubagentProgressKey(invocationKey);
subagentStore.set(
subagentProgressByToolCallId(invocationKey),
closeParentSubagentProgress,
);
continue;
}
subagentStore.set(subagentProgressByToolCallId(invocationKey), null);
removeSubagentProgressAtoms(invocationKey);
}
},
[subagentStore],
);
const closeParentSubagentStreams = useCallback((): void => {
for (const invocationKey of listRegisteredSubagentProgressKeys()) {
subagentStore.set(subagentParentStreamOpenByToolCallId(invocationKey), false);
subagentStore.set(subagentProgressByToolCallId(invocationKey), closeParentSubagentProgress);
}
}, [subagentStore]);
/** Tool-call ids whose sandbox-starting atom is set, so completion can clear them. */
const knownSandboxAtomKeys = useRef(new Set<string>());
const sandboxStore = useStore();
const setSandboxStarting = useCallback(
(toolCallId: string): void => {
knownSandboxAtomKeys.current.add(toolCallId);
sandboxStore.set(sandboxStartingByToolCallId(toolCallId), true);
},
[sandboxStore],
);
const clearSandboxStarting = useCallback(
(toolCallId?: string | null): void => {
if (!toolCallId || !knownSandboxAtomKeys.current.has(toolCallId)) {
return;
}
knownSandboxAtomKeys.current.delete(toolCallId);
sandboxStore.set(sandboxStartingByToolCallId(toolCallId), false);
},
[sandboxStore],
);
const resetSandboxAtoms = useCallback((): void => {
for (const toolCallId of knownSandboxAtomKeys.current) {
sandboxStore.set(sandboxStartingByToolCallId(toolCallId), false);
}
knownSandboxAtomKeys.current.clear();
}, [sandboxStore]);
/** PTC tool call ids with a live trace, so the atoms can be released. */
const knownPtcAtomKeys = useRef(new Set<string>());
const ptcStore = useStore();
/**
* Folds one `on_ptc_tool_call` envelope into its program's trace: the
* `running` event appends a row, the settling event updates that row in
* place by `call_id`. Order follows the sandbox's dispatch order, which is
* what the code reads like; a round trip can settle out of order.
*/
const applyPtcToolCall = useCallback(
(event: PtcToolCallEvent, parentMessageId: string): void => {
const { tool_call_id: toolCallId, call_id: callId, name, status } = event;
/** No parent message means no occurrence to scope this to; a raw
* `tool_call_id` would leak the rows into whichever card reused it. */
if (!toolCallId || !callId || !parentMessageId) {
return;
}
const atomKey = ptcTraceKey(parentMessageId, toolCallId);
knownPtcAtomKeys.current.add(atomKey);
ptcStore.set(ptcTraceByToolCallId(atomKey), (previous) => {
const index = previous.entries.findIndex((entry) => entry.callId === callId);
const entry = {
callId,
name,
status,
...(event.args ? { args: event.args } : {}),
...(event.error ? { error: event.error } : {}),
...(event.durationMs != null ? { durationMs: event.durationMs } : {}),
};
if (index !== -1) {
const next = [...previous.entries];
next[index] = { ...previous.entries[index], ...entry };
return { entries: next, dropped: previous.dropped };
}
/** A settle whose row is gone, evicted by the cap, or pruned across
* a resume gap, must not reappear at the tail out of order. */
if (status !== 'running') {
return previous;
}
const appended = [...previous.entries, entry];
const overflow = appended.length - PTC_TRACE_MAX_ENTRIES;
if (overflow <= 0) {
return { entries: appended, dropped: previous.dropped };
}
return {
entries: appended.slice(overflow),
dropped: previous.dropped + overflow,
};
});
},
[ptcStore],
);
const resetPtcAtoms = useCallback((): void => {
for (const atomKey of knownPtcAtomKeys.current) {
ptcStore.set(ptcTraceByToolCallId(atomKey), EMPTY_PTC_TRACE);
ptcTraceByToolCallId.remove(atomKey);
}
knownPtcAtomKeys.current.clear();
}, [ptcStore]);
/**
* Settles rows still marked `running` after a stream gap as `interrupted`.
* Inner calls carry no durable state: they are not content parts, so the
* resume snapshot cannot rebuild them and a settling event lost in the gap
* is never replayed, and that means such a row would otherwise spin forever.
*
* Marked, not removed: a call can also still be executing across the
* reconnect, and its settling event then arrives normally on the restored
* live stream. That event updates this row in place, so the call reports its
* real outcome. Deleting the row would strand it: a settle whose row is
* gone is dropped rather than re-appended out of order, and the call would
* vanish from the trace despite having run. Settled rows are untouched.
*/
const prunePtcTraces = useCallback((): void => {
for (const atomKey of knownPtcAtomKeys.current) {
ptcStore.set(ptcTraceByToolCallId(atomKey), (previous) =>
previous.entries.some((entry) => entry.status === 'running')
? {
...previous,
entries: previous.entries.map((entry) =>
entry.status === 'running' ? { ...entry, status: 'interrupted' as const } : entry,
),
}
: previous,
);
}
}, [ptcStore]);
/**
* Per-token deltas fold into the stream state immediately (authoritative), but
* the cache write, and the buildTree + message-tree walk it triggers,
* flushes at most once per frame. Non-delta events keep writing
* synchronously from the stream state, so a trailing flush after them merges
* the same authoritative state; `clearStepMaps` cancels the flush at run
* boundaries (same lifecycle as the summarize coalescing).
*/
const scheduleCoalescedMessagesFlush = useCallback(
(responseMessageId: string, messages: TMessage[], ctx: StepContext) => {
pendingDeltaFlushIds.current.add(responseMessageId);
const flush = () => {
deltaFlushScheduled.current = false;
messageDeltaRaf.current = null;
pendingDeltaFlushRef.current = null;
const ids = pendingDeltaFlushIds.current;
pendingDeltaFlushIds.current = new Set();
flushResponses(stream.current, ctx, ids, messages);
};
/** Exposed so terminal/read boundaries (abort, error, pending-action)
* can apply the queued tokens synchronously via `flushPendingDeltas`. */
pendingDeltaFlushRef.current = flush;
if (deltaFlushScheduled.current) {
return;
}
deltaFlushScheduled.current = true;
messageDeltaRaf.current = requestAnimationFrame(flush);
},
[],
);
const applyEffects = useCallback(
(effects: StepEffect[], ctx: StepContext): void => {
for (const effect of effects) {
switch (effect.type) {
case 'flush':
scheduleCoalescedMessagesFlush(effect.messageId, effect.messages, ctx);
break;
case 'summary':
if (summarizeDeltaRaf.current == null) {
summarizeDeltaRaf.current = requestAnimationFrame(() => {
summarizeDeltaRaf.current = null;
flushSummary(stream.current, ctx, effect.messageId, effect.messages);
});
}
break;
case 'announce':
announcePolite({ message: effect.message, isStatus: true });
break;
case 'sandbox-starting':
setSandboxStarting(effect.toolCallId);
break;
case 'sandbox-settled':
clearSandboxStarting(effect.toolCallId);
break;
case 'skill-authored':
onSkillAuthoringComplete?.();
break;
case 'ptc':
applyPtcToolCall(effect.event, effect.parentMessageId);
break;
case 'subagent':
applySubagentProgress(effect.invocationKey, effect.events);
break;
case 'subagent-index':
onSubagentIndexChange?.(effect.conversationId);
break;
}
}
},
[
announcePolite,
setSandboxStarting,
clearSandboxStarting,
onSkillAuthoringComplete,
applyPtcToolCall,
applySubagentProgress,
onSubagentIndexChange,
scheduleCoalescedMessagesFlush,
],
);
const stepHandler = useCallback(
(stepEvent: StepEvent, submission: EventSubmission) => {
const currentTime = Date.now();
if (currentTime - lastAnnouncementTimeRef.current > MESSAGE_UPDATE_INTERVAL) {
announcePolite({ message: 'composing', isStatus: true });
lastAnnouncementTimeRef.current = currentTime;
}
const ctx: StepContext = { submission, getMessages, setMessages };
applyEffects(reduceStep(stream.current, stepEvent, ctx), ctx);
},
[getMessages, setMessages, announcePolite, applyEffects, lastAnnouncementTimeRef],
);
/** Cancels a queued delta flush so it can't overwrite a terminal write:
* once a final handler has written the server's authoritative message, a
* trailing frame reading the older streaming copy from the stream state must
* never land on top of it. */
const cancelPendingDeltaFlush = useCallback(() => {
if (messageDeltaRaf.current != null) {
cancelAnimationFrame(messageDeltaRaf.current);
messageDeltaRaf.current = null;
}
deltaFlushScheduled.current = false;
pendingDeltaFlushRef.current = null;
pendingDeltaFlushIds.current.clear();
}, []);
/** Applies a queued delta flush synchronously (then cancels the frame).
* For boundaries that READ the cache or synthesize from it (abort's
* partial-response capture, error cards, pending-action application), the
* queued tokens must land first or the stopped/errored message loses them. */
const flushPendingDeltas = useCallback(() => {
if (messageDeltaRaf.current != null) {
cancelAnimationFrame(messageDeltaRaf.current);
messageDeltaRaf.current = null;
}
const flush = pendingDeltaFlushRef.current;
pendingDeltaFlushRef.current = null;
deltaFlushScheduled.current = false;
if (flush) {
flush();
}
}, []);
const clearStepMaps = useCallback(() => {
if (summarizeDeltaRaf.current != null) {
cancelAnimationFrame(summarizeDeltaRaf.current);
summarizeDeltaRaf.current = null;
}
cancelPendingDeltaFlush();
resetStreamState(stream.current);
closeParentSubagentStreams();
/** Unlike subagent atoms below, sandbox-starting flags are transient
* status with no audit value; reset them at this boundary so an
* interrupted cold boot can't leak a stale "starting" label onto a
* later tool call that reuses the same id (e.g. `call_0`). */
resetSandboxAtoms();
/** Intentionally NOT calling `resetSubagentAtoms()` here: users need
* to be able to reopen the SubagentCall dialog after completion to
* audit what the child did. `resetSubagentAtoms` is returned below
* so callers can wipe atoms on conversation-switch (see
* `useEventHandlers`); that's the correct cleanup boundary:
* persisted `subagent_content` takes over for historical messages
* once the conversation is saved, and we prevent unbounded
* atomFamily growth across multi-conversation sessions. */
}, [cancelPendingDeltaFlush, closeParentSubagentStreams, resetSandboxAtoms]);
/**
* Sync a message into the step handler's streaming copy.
* Call this after receiving sync event to ensure subsequent deltas
* build on the synced content, not stale content.
*/
const syncStepMessage = useCallback(
(message: TMessage) => {
for (const effect of syncStreamMessage(stream.current, message)) {
if (effect.type === 'subagent') {
applySubagentProgress(effect.invocationKey, effect.events);
}
}
},
[applySubagentProgress],
);
return {
stepHandler,
clearStepMaps,
resetSubagentAtoms,
resetPtcAtoms,
prunePtcTraces,
syncStepMessage,
cancelPendingDeltaFlush,
flushPendingDeltas,
};
}