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: Lift the Step Handler Into a Core reduceStep With an Effects Channel (#17000)

Marco Beretta98c35b648bea
diff --git a/client/src/components/Chat/Subagents/state.ts b/client/src/components/Chat/Subagents/state.ts
index 3f396ec1bf..7f648e067b 100644
--- a/client/src/components/Chat/Subagents/state.ts
+++ b/client/src/components/Chat/Subagents/state.ts
@@ -473,11 +473,7 @@ export const subagentControlStateByTask = atomFamily<
});
/** Stable identity for one subagent invocation in the parent conversation. */
-export const subagentProgressKey = (
- parentMessageId: string,
- toolCallId: string,
- partIndex: number,
-) => `${parentMessageId}\u0000${toolCallId}\u0000${partIndex}`;
+export { subagentProgressKey } from '@librechat/chat';
/** Progress state keyed by one concrete tool-call content-part occurrence. */
export const subagentProgressByToolCallId = atomFamily((_key: string) =>
diff --git a/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts b/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts
new file mode 100644
index 0000000000..e8d636a005
--- /dev/null
+++ b/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts
@@ -0,0 +1,548 @@
+import React from 'react';
+import { createHash } from 'crypto';
+import { createStore, Provider } from 'jotai';
+import { RecoilRoot, useRecoilCallback } from 'recoil';
+import { renderHook, act } from '@testing-library/react';
+import {
+ Constants,
+ StepTypes,
+ StepEvents,
+ ContentTypes,
+ ToolCallTypes,
+} from 'librechat-data-provider';
+import type {
+ Agents,
+ TMessage,
+ EventSubmission,
+ PtcToolCallEvent,
+ SubagentUpdateEvent,
+ TMessageContentParts,
+} from 'librechat-data-provider';
+import type { StepEvent } from '@librechat/chat';
+import {
+ subagentProgressKey,
+ subagentProgressByToolCallId,
+ takeRegisteredSubagentProgressKeys,
+ subagentParentStreamOpenByToolCallId,
+} from '~/components/Chat/Subagents/state';
+import { ptcTraceByToolCallId, ptcTraceKey } from '~/store/ptc';
+import { sandboxStartingByToolCallId } from '~/store/sandbox';
+import useStepHandler from '~/hooks/SSE/useStepHandler';
+
+/**
+ * Equivalence table for the step reducer. Each row is an event sequence shaped like a recorded
+ * agent stream, with the frame boundaries and run-boundary calls the SSE hooks make. The digest
+ * pins what the pre-reducer `stepHandler` produced for the row on every channel it writes: each
+ * message-list write, each announcement, each host callback, and the live-status atoms. The
+ * digests were recorded by running that handler side by side with this binding and requiring
+ * equal logs, so a row whose digest moves changed observable behavior.
+ */
+
+const PRELIM: string = Constants.USE_PRELIM_RESPONSE_MESSAGE_ID;
+const SUBAGENT: string = Constants.SUBAGENT;
+
+type Step =
+ | StepEvent
+ | { frame: true }
+ | { sync: TMessage }
+ | { call: 'clearStepMaps' | 'flushPendingDeltas' | 'cancelPendingDeltaFlush' | 'prunePtcTraces' };
+
+type Row = {
+ name: string;
+ submission?: Partial<EventSubmission>;
+ cache?: TMessage[];
+ steps: Step[];
+ sandbox?: string[];
+ ptc?: Array<[string, string]>;
+ subagents?: string[];
+ digest: string;
+};
+
+const user = (overrides: Partial<TMessage> = {}): TMessage => ({
+ messageId: 'user-1',
+ conversationId: 'conv-1',
+ parentMessageId: Constants.NO_PARENT as string,
+ isCreatedByUser: true,
+ text: 'Hello',
+ sender: 'User',
+ ...overrides,
+});
+
+const response = (overrides: Partial<TMessage> = {}): TMessage => ({
+ messageId: 'resp-1',
+ conversationId: 'conv-1',
+ parentMessageId: 'user-1',
+ isCreatedByUser: false,
+ text: '',
+ sender: 'Assistant',
+ content: [],
+ ...overrides,
+});
+
+const textStep = (id: string, index: number, runId = 'resp-1'): StepEvent => ({
+ event: StepEvents.ON_RUN_STEP,
+ data: {
+ id,
+ runId,
+ index,
+ type: StepTypes.MESSAGE_CREATION,
+ stepDetails: { type: StepTypes.MESSAGE_CREATION, message_creation: { message_id: id } },
+ usage: null,
+ },
+});
+
+const toolStep = (
+ id: string,
+ index: number,
+ calls: Array<{ id: string; name: string; args?: string }>,
+ overrides: Partial<Agents.RunStep> = {},
+): StepEvent => ({
+ event: StepEvents.ON_RUN_STEP,
+ data: {
+ id,
+ runId: 'resp-1',
+ index,
+ type: StepTypes.TOOL_CALLS,
+ stepDetails: {
+ type: StepTypes.TOOL_CALLS,
+ tool_calls: calls.map((call) => ({
+ args: '',
+ ...call,
+ type: ToolCallTypes.TOOL_CALL,
+ })),
+ },
+ usage: null,
+ ...overrides,
+ },
+});
+
+const text = (id: string, value: string): StepEvent => ({
+ event: StepEvents.ON_MESSAGE_DELTA,
+ data: { id, delta: { content: [{ type: ContentTypes.TEXT, text: value }] } },
+});
+
+const think = (id: string, value: string): StepEvent => ({
+ event: StepEvents.ON_REASONING_DELTA,
+ data: { id, delta: { content: [{ type: ContentTypes.THINK, think: value }] } },
+});
+
+const args = (id: string, callId: string | undefined, value: string, at?: number): StepEvent => ({
+ event: StepEvents.ON_RUN_STEP_DELTA,
+ data: {
+ id,
+ ...(at != null ? { observed_at: at } : {}),
+ delta: {
+ type: StepTypes.TOOL_CALLS,
+ tool_calls: [{ ...(callId ? { id: callId } : {}), index: 0, args: value }],
+ },
+ },
+});
+
+const completed = (
+ id: string,
+ call: { id: string; name: string; args: string; output: string },
+ at?: number,
+): StepEvent => ({
+ event: StepEvents.ON_RUN_STEP_COMPLETED,
+ data: {
+ result: { id, index: 0, ...(at != null ? { completed_at: at } : {}), tool_call: call },
+ } as { result: Agents.ToolEndEvent },
+});
+
+const closed = (id: string, index: number): StepEvent => ({
+ event: StepEvents.ON_RUN_STEP_CLOSED,
+ data: { id, index, status: 'completed' } as Agents.RunStepClosedEvent,
+});
+
+const subagent = (overrides: Partial<SubagentUpdateEvent>): StepEvent => ({
+ event: StepEvents.ON_SUBAGENT_UPDATE,
+ data: {
+ runId: 'resp-1',
+ subagentRunId: 'child-1',
+ subagentType: 'self',
+ subagentAgentId: 'child-agent',
+ parentAgentId: 'parent-agent',
+ phase: 'start',
+ label: 'started',
+ timestamp: '2026-10-11T00:00:00.000Z',
+ ...overrides,
+ } as SubagentUpdateEvent,
+});
+
+const ptc = (overrides: Partial<PtcToolCallEvent>): StepEvent => ({
+ event: StepEvents.ON_PTC_TOOL_CALL,
+ data: {
+ tool_call_id: 'call_ptc',
+ call_id: 'call_ptc:0',
+ name: 'read_file',
+ status: 'running',
+ runId: 'resp-1',
+ ...overrides,
+ },
+});
+
+const subagentPart = (id: string): TMessageContentParts =>
+ ({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id, name: SUBAGENT, args: '{}', type: ToolCallTypes.TOOL_CALL },
+ }) as TMessageContentParts;
+
+const summaryStep = (id: string, index: number): StepEvent => {
+ const step = textStep(id, index) as Extract<StepEvent, { event: StepEvents.ON_RUN_STEP }>;
+ return {
+ event: StepEvents.ON_RUN_STEP,
+ data: {
+ ...step.data,
+ summary: { type: ContentTypes.SUMMARY, model: 'm', provider: 'p' },
+ } as Agents.RunStep,
+ };
+};
+
+const summaryDelta = (id: string, value: string): StepEvent => ({
+ event: StepEvents.ON_SUMMARIZE_DELTA,
+ data: {
+ id,
+ delta: { summary: { type: ContentTypes.SUMMARY, content: [{ type: 'text', text: value }] } },
+ } as unknown as Agents.SummarizeDeltaEvent,
+});
+
+const rows: Row[] = [
+ {
+ name: 'streams reasoning then text, coalesced per frame',
+ cache: [user()],
+ steps: [
+ textStep('s1', 0),
+ think('s1', 'Let me'),
+ think('s1', ' think'),
+ { frame: true },
+ textStep('s2', 1),
+ text('s2', 'Hel'),
+ text('s2', 'lo'),
+ { frame: true },
+ text('s2', '!'),
+ { call: 'flushPendingDeltas' },
+ { frame: true },
+ ],
+ digest: '078e3ccb88c2a351',
+ },
+ {
+ name: 'replays deltas that arrive before their run step',
+ cache: [user()],
+ steps: [
+ text('s1', 'early'),
+ args('t1', 'call-1', '{"q":', 50),
+ completed('t1', { id: 'call-1', name: 'search', args: '{"q":1}', output: 'ok' }, 90),
+ textStep('s1', 0),
+ toolStep('t1', 1, [{ id: 'call-1', name: 'search' }]),
+ { frame: true },
+ ],
+ digest: 'b11e5d4a36c3f25d',
+ },
+ {
+ name: 'times a tool call from preparation to close',
+ cache: [user()],
+ steps: [
+ {
+ event: StepEvents.ON_TOOL_PREPARATION,
+ data: { id: 't1', index: 0, observed_at: 100 },
+ },
+ toolStep('t1', 0, [{ id: 'call-1', name: 'execute_code' }]),
+ args('t1', undefined, '{"code":', 120),
+ args('t1', 'call-1', '"1+1"}', 130),
+ {
+ event: StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ data: {
+ dispatched_at: 150,
+ toolCalls: [{ id: 'call-1', name: 'execute_code', stepId: 't1' }],
+ },
+ },
+ { event: StepEvents.ON_SANDBOX_STARTING, data: { tool_call_id: 'call-1' } },
+ { event: StepEvents.ON_SANDBOX_STARTING, data: { tool_call_id: 'call-2' } },
+ completed('t1', { id: 'call-1', name: 'execute_code', args: '{}', output: '2' }, 400),
+ closed('t1', 0),
+ ],
+ sandbox: ['call-1', 'call-2'],
+ digest: '43800a3620d7f481',
+ },
+ {
+ name: 'reports a skill file authored by a tool call',
+ cache: [user()],
+ steps: [
+ toolStep('t1', 0, [{ id: 'call-1', name: 'create_file' }]),
+ completed('t1', {
+ id: 'call-1',
+ name: 'create_file',
+ args: '{"file_path":"skills/demo/SKILL.md"}',
+ output: 'written',
+ }),
+ ],
+ digest: '3655708ced395a6c',
+ },
+ {
+ name: 'regenerates an earlier branch through the preliminary id',
+ submission: {
+ isRegenerate: true,
+ userMessage: user({ responseMessageId: 'resp-old' }),
+ initialResponse: response({ messageId: 'resp-old_', parentMessageId: 'user-1' }),
+ messages: [
+ user(),
+ response({ messageId: 'resp-old', text: 'old' }),
+ user({ messageId: 'user-2', parentMessageId: 'resp-old' }),
+ response({ messageId: 'resp-2', parentMessageId: 'user-2' }),
+ ],
+ },
+ steps: [textStep('s1', 0, PRELIM), text('s1', 'again'), { frame: true }],
+ digest: '55ebe9bf5b9df0ea',
+ },
+ {
+ name: 'continues an edit after its retained prefix',
+ cache: [user()],
+ submission: {
+ editedContent: { index: 0, type: ContentTypes.TEXT, text: 'kept' },
+ editPrefixLength: 1,
+ initialResponse: response({ content: [{ type: ContentTypes.TEXT, text: 'kept' }] }),
+ } as Partial<EventSubmission>,
+ steps: [
+ textStep('s1', 0),
+ text('s1', ' and more'),
+ { frame: true },
+ toolStep('t1', 1, [{ id: 'call-1', name: 'search' }]),
+ textStep('s2', 2),
+ text('s2', 'tail'),
+ { frame: true },
+ ],
+ digest: 'bcf040ec24e470fc',
+ },
+ {
+ name: 'streams and settles a summary',
+ cache: [user()],
+ steps: [
+ { event: StepEvents.ON_SUMMARIZE_START, data: { agentId: 'a1' } } as StepEvent,
+ summaryStep('sum1', 0),
+ summaryDelta('sum1', 'Earlier, '),
+ summaryDelta('sum1', 'we talked.'),
+ { frame: true },
+ {
+ event: StepEvents.ON_SUMMARIZE_COMPLETE,
+ data: {
+ id: 'sum1',
+ agentId: 'a1',
+ summary: {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: 'text', text: 'Earlier, we talked.' }],
+ },
+ },
+ } as StepEvent,
+ ],
+ digest: '141779fddd2f4add',
+ },
+ {
+ name: 'announces a failed summary',
+ cache: [user()],
+ steps: [
+ summaryStep('sum1', 0),
+ {
+ event: StepEvents.ON_SUMMARIZE_COMPLETE,
+ data: { id: 'sum1', agentId: 'a1', error: 'boom' },
+ } as StepEvent,
+ ],
+ digest: 'f63470a3394dbd94',
+ },
+ {
+ name: 'records an agent handoff',
+ cache: [user()],
+ steps: [
+ textStep('s1', 0),
+ {
+ event: StepEvents.ON_AGENT_UPDATE,
+ data: {
+ type: ContentTypes.AGENT_UPDATE,
+ agent_update: { runId: 'resp-1', index: 1, agentId: 'agent-2' },
+ },
+ },
+ ],
+ digest: '48f03bdf6613a5f0',
+ },
+ {
+ name: 'routes subagent envelopes to their parent occurrence',
+ cache: [user()],
+ steps: [
+ subagent({ phase: 'start', label: 'a' }),
+ toolStep('t1', 0, [{ id: 'call-sub', name: SUBAGENT }]),
+ subagent({ phase: 'run_step_delta' as SubagentUpdateEvent['phase'], label: 'b' }),
+ subagent({ phase: 'stop', label: 'c' }),
+ subagent({ subagentRunId: 'child-2', runId: 'resp-2', phase: 'start', label: 'd' }),
+ { sync: response({ messageId: 'resp-2', content: [subagentPart('call-sub-2')] }) },
+ { call: 'clearStepMaps' },
+ ],
+ subagents: [
+ subagentProgressKey('resp-1', 'call-sub', 0),
+ subagentProgressKey('resp-2', 'call-sub-2', 0),
+ ],
+ digest: '4e5902ea8131cf80',
+ },
+ {
+ name: 'folds a programmatic tool-call trace and settles it across a gap',
+ steps: [
+ ptc({ call_id: 'c:0', args: 'a' }),
+ ptc({ call_id: 'c:1' }),
+ ptc({ call_id: 'c:0', status: 'success', durationMs: 5 }),
+ ptc({ call_id: 'c:9', status: 'error', error: 'late' }),
+ ptc({ call_id: 'c:2', runId: PRELIM }),
+ { call: 'prunePtcTraces' },
+ ],
+ submission: { initialResponse: response({ messageId: 'resp-prelim' }) },
+ ptc: [
+ ['resp-1', 'call_ptc'],
+ ['resp-prelim', 'call_ptc'],
+ ],
+ digest: '9d1bb17142716632',
+ },
+ {
+ name: 'restores a user turn missing from another tab',
+ submission: { initialResponse: response({ messageId: 'resp-placeholder' }) },
+ cache: [
+ user({ messageId: 'user-0' }),
+ response({ messageId: 'resp-abandoned', parentMessageId: 'user-1' }),
+ response({ messageId: 'resp-placeholder', parentMessageId: 'user-1' }),
+ ],
+ steps: [textStep('s1', 0), text('s1', 'hi'), { frame: true }],
+ digest: '2196daeec40a5ec4',
+ },
+ {
+ name: 'keeps the compaction anchor of a compact regenerate',
+ submission: {
+ isRegenerate: true,
+ compact: true,
+ userMessage: user({ messageId: 'anchor', isCreatedByUser: false }),
+ initialResponse: response({ messageId: 'anchor_', parentMessageId: 'anchor' }),
+ messages: [user(), response({ messageId: 'anchor', parentMessageId: 'user-1' })],
+ },
+ steps: [summaryStep('sum1', 0), summaryDelta('sum1', 'short'), { frame: true }],
+ digest: 'bec603f100020017',
+ },
+ {
+ name: 'drops a queued flush at an abort boundary',
+ cache: [user()],
+ steps: [
+ textStep('s1', 0),
+ text('s1', 'partial'),
+ { call: 'cancelPendingDeltaFlush' },
+ { frame: true },
+ { call: 'clearStepMaps' },
+ text('s1', 'orphan'),
+ textStep('s1', 0),
+ { frame: true },
+ ],
+ digest: '3e9b683cabfffbcc',
+ },
+];
+
+function run(hook: typeof useStepHandler, row: Row) {
+ takeRegisteredSubagentProgressKeys();
+ const store = createStore();
+ let cache: TMessage[] = row.cache ?? [];
+ const frames = new Map<number, FrameRequestCallback>();
+ let nextFrame = 1;
+ jest.spyOn(window, 'requestAnimationFrame').mockImplementation((cb) => {
+ frames.set(nextFrame, cb);
+ return nextFrame++;
+ });
+ jest.spyOn(window, 'cancelAnimationFrame').mockImplementation((id) => {
+ frames.delete(id);
+ });
+ const runFrames = () => {
+ const queued = [...frames.values()];
+ frames.clear();
+ queued.forEach((cb) => cb(0));
+ };
+
+ const log = {
+ writes: [] as string[],
+ announcements: [] as string[],
+ callbacks: [] as string[],
+ atoms: {} as Record<string, unknown>,
+ };
+ const wrapper = ({ children }: { children: React.ReactNode }) =>
+ React.createElement(RecoilRoot, null, React.createElement(Provider, { store }, children));
+ const { result } = renderHook(
+ () => ({
+ handler: hook({
+ setMessages: (messages) => {
+ cache = messages;
+ log.writes.push(JSON.stringify(messages));
+ },
+ getMessages: () => cache,
+ announcePolite: (options) => log.announcements.push(JSON.stringify(options)),
+ lastAnnouncementTimeRef: { current: 0 },
+ onSkillAuthoringComplete: () => log.callbacks.push('skill'),
+ onSubagentIndexChange: (id) => log.callbacks.push(`subagent-index:${id}`),
+ }),
+ readPtc: useRecoilCallback(
+ ({ snapshot }) =>
+ (key: string) =>
+ snapshot.getLoadable(ptcTraceByToolCallId(key)).getValue(),
+ [],
+ ),
+ }),
+ { wrapper },
+ );
+
+ const submission = {
+ userMessage: user(),
+ isRegenerate: false,
+ isTemporary: false,
+ messages: [],
+ conversation: { conversationId: 'conv-1' },
+ endpointOption: {},
+ initialResponse: response(),
+ ...row.submission,
+ } as unknown as EventSubmission;
+
+ act(() => {
+ for (const step of row.steps) {
+ if ('frame' in step) {
+ runFrames();
+ } else if ('sync' in step) {
+ result.current.handler.syncStepMessage(step.sync);
+ } else if ('call' in step) {
+ result.current.handler[step.call]();
+ } else {
+ result.current.handler.stepHandler(step, submission);
+ }
+ }
+ runFrames();
+ });
+
+ for (const id of row.sandbox ?? []) {
+ log.atoms[`sandbox:${id}`] = store.get(sandboxStartingByToolCallId(id));
+ }
+ for (const [messageId, toolCallId] of row.ptc ?? []) {
+ log.atoms[`ptc:${messageId}`] = result.current.readPtc(ptcTraceKey(messageId, toolCallId));
+ }
+ for (const key of row.subagents ?? []) {
+ log.atoms[`subagent:${key}`] = [
+ store.get(subagentParentStreamOpenByToolCallId(key)),
+ store.get(subagentProgressByToolCallId(key)),
+ ];
+ }
+ jest.restoreAllMocks();
+ return log;
+}
+
+const digest = (log: ReturnType<typeof run>) =>
+ createHash('sha256').update(JSON.stringify(log)).digest('hex').slice(0, 16);
+
+describe('step reducer equivalence', () => {
+ beforeEach(() => {
+ jest.spyOn(Date, 'now').mockReturnValue(1_000_000);
+ });
+
+ it.each(rows.map((row) => [row.name, row] as const))('%s', (_name, row) => {
+ const log = run(useStepHandler, row);
+ expect(
+ log.writes.length + log.callbacks.length + Object.keys(log.atoms).length,
+ ).toBeGreaterThan(0);
+ expect(digest(log)).toBe(row.digest);
+ });
+});
diff --git a/client/src/hooks/SSE/useStepHandler.ts b/client/src/hooks/SSE/useStepHandler.ts
index a9668a4799..300e5b81be 100644
--- a/client/src/hooks/SSE/useStepHandler.ts
+++ b/client/src/hooks/SSE/useStepHandler.ts
@@ -2,35 +2,20 @@ import { useCallback, useRef } from 'react';
import { useStore } from 'jotai';
import { useRecoilCallback } from 'recoil';
import {
- Constants,
- StepTypes,
- StepEvents,
- ContentTypes,
- getToolTimingDurations,
-} from 'librechat-data-provider';
-import {
- applyReasoningDelta,
- applyToolCallCompleted,
- isSkillAuthoringToolCall,
- applyToolCallDelta,
- applySummarizeDelta,
- applyRunStepClosed,
- applyToolCallsStep,
- applyMessageDelta,
- finalizeSummaries,
- applyAgentUpdate,
- applySummaryStep,
- getEditPrefix,
+ reduceStep,
+ flushSummary,
+ flushResponses,
+ resetStreamState,
+ syncStreamMessage,
+ createStreamState,
} from '@librechat/chat';
import type {
- Agents,
TMessage,
EventSubmission,
- TMessageContentParts,
SubagentUpdateEvent,
- SandboxStartingEvent,
PtcToolCallEvent,
} from 'librechat-data-provider';
+import type { StepEvent, StepEffect, StepContext, StreamState } from '@librechat/chat';
import type { SetterOrUpdater } from 'recoil';
import type { AnnounceOptions } from '~/common';
import {
@@ -42,7 +27,6 @@ import {
subagentParentStreamOpenByToolCallId,
subagentProgressByToolCallId,
takeRegisteredSubagentProgressKeys,
- subagentProgressKey,
} from '~/components/Chat/Subagents/state';
import {
sandboxStartingByToolCallId,
@@ -68,25 +52,6 @@ type TUseStepHandler = {
onSubagentIndexChange?: (conversationId: string) => void;
};
-const toolTimingKey = (stepId: string, callId: string) => `${stepId}\u0000${callId}`;
-
-type TStepEvent =
- | { event: StepEvents.ON_RUN_STEP; data: Agents.RunStep }
- | { event: StepEvents.ON_AGENT_UPDATE; data: Agents.AgentUpdate }
- | { event: StepEvents.ON_MESSAGE_DELTA; data: Agents.MessageDeltaEvent }
- | { event: StepEvents.ON_REASONING_DELTA; data: Agents.ReasoningDeltaEvent }
- | { event: StepEvents.ON_RUN_STEP_DELTA; data: Agents.RunStepDeltaEvent }
- | { event: StepEvents.ON_TOOL_CALLS_DISPATCHED; data: Agents.ToolCallsDispatchedEvent }
- | { event: StepEvents.ON_TOOL_PREPARATION; data: Agents.ToolPreparationMarker }
- | { event: StepEvents.ON_RUN_STEP_COMPLETED; data: { result: Agents.ToolEndEvent } }
- | { event: StepEvents.ON_RUN_STEP_CLOSED; data: Agents.RunStepClosedEvent }
- | { event: StepEvents.ON_SUMMARIZE_START; data: Agents.SummarizeStartEvent }
- | { event: StepEvents.ON_SUMMARIZE_DELTA; data: Agents.SummarizeDeltaEvent }
- | { event: StepEvents.ON_SUMMARIZE_COMPLETE; data: Agents.SummarizeCompleteEvent }
- | { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent }
- | { event: StepEvents.ON_SANDBOX_STARTING; data: SandboxStartingEvent }
- | { event: StepEvents.ON_PTC_TOOL_CALL; data: PtcToolCallEvent };
-
export default function useStepHandler({
setMessages,
getMessages,
@@ -96,15 +61,7 @@ export default function useStepHandler({
onSubagentIndexChange,
}: TUseStepHandler) {
const subagentStore = useStore();
- const toolCallIdMap = useRef(new Map<string, string | undefined>());
- const firstFragmentByCall = useRef(new Map<string, number>());
- const firstFragmentByStep = useRef(new Map<string, number>());
- const dispatchedByCall = useRef(new Map<string, number>());
- const completedByCall = useRef(new Map<string, number>());
- const messageMap = useRef(new Map<string, TMessage>());
- const stepMap = useRef(new Map<string, Agents.RunStep>());
- /** Buffer for deltas that arrive before their corresponding run step */
- const pendingDeltaBuffer = useRef(new Map<string, TStepEvent[]>());
+ 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.
@@ -115,114 +72,21 @@ export default function useStepHandler({
const deltaFlushScheduled = useRef(false);
const pendingDeltaFlushIds = useRef(new Set<string>());
const pendingDeltaFlushRef = useRef<(() => void) | null>(null);
- /**
- * Maps `SubagentUpdateEvent.subagentRunId` → one concrete parent content-part
- * occurrence. `payload.parentToolCallId` narrows the candidates when present,
- * but provider IDs are not unique enough to be the atom identity: they may be
- * reused across messages or even within one message. Forward (oldest-first)
- * claiming preserves creation order for both modern and legacy envelopes.
- */
- const subagentRunToInvocationKey = useRef(new Map<string, string>());
- const claimedSubagentInvocationKeys = useRef(new Set<string>());
- /**
- * Buffers for envelopes that arrive before their `subagent` tool call is
- * reflected in `messageMap`. Keyed by `subagentRunId`. Once a tool call is
- * claimed we drain the buffer into the Recoil atom in arrival order.
- */
- const pendingSubagentBuffer = useRef(
- new Map<string, { parentMessageId: string; events: SubagentUpdateEvent[] }>(),
- );
- const getCurrentMessages = useCallback(
- (messages: TMessage[]) => {
- const freshMessages = getMessages();
- return freshMessages && freshMessages.length >= messages.length ? freshMessages : messages;
- },
- [getMessages],
- );
/** 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. */
-
- /**
- * Resolves a subagent run to an occurrence-scoped parent invocation key.
- */
- const resolveSubagentInvocationKey = useCallback(
- (payload: SubagentUpdateEvent, parentMessageId: string): string | undefined => {
- const cached = subagentRunToInvocationKey.current.get(payload.subagentRunId);
- if (cached != null) return cached;
- if (parentMessageId === '') return undefined;
-
- // Claim one concrete content-part occurrence. Providers can repeat a
- // tool_call ID even within one assistant message, so raw IDs alone are
- // not sufficient identity for either the card or its live progress.
- const preferred = messageMap.current.get(parentMessageId);
- // `runId` gives us the expected parent message. If that message has not
- // arrived yet, buffer instead of claiming a same-ID call from another
- // parallel response; the mapping is permanent once claimed.
- if (preferred == null) return undefined;
- for (const [messageId, message] of [[parentMessageId, preferred] as const]) {
- const content = message.content;
- if (!Array.isArray(content)) continue;
- for (let i = 0; i < content.length; i++) {
- const part = content[i];
- if (part?.type !== ContentTypes.TOOL_CALL) continue;
- const tc = (part as { [ContentTypes.TOOL_CALL]?: { id?: string; name?: string } })[
- ContentTypes.TOOL_CALL
- ];
- if (
- tc?.name === Constants.SUBAGENT &&
- tc.id &&
- (payload.parentToolCallId == null || tc.id === payload.parentToolCallId) &&
- !claimedSubagentInvocationKeys.current.has(subagentProgressKey(messageId, tc.id, i))
- ) {
- const invocationKey = subagentProgressKey(messageId, tc.id, i);
- subagentRunToInvocationKey.current.set(payload.subagentRunId, invocationKey);
- claimedSubagentInvocationKeys.current.add(invocationKey);
- return invocationKey;
- }
- }
- }
-
- return undefined;
- },
- [],
- );
-
- /**
- * Merges an incoming {@link SubagentUpdateEvent} into the atom bucket keyed
- * by the parent `tool_call_id`. Buffers early-arriving events whose tool call
- * is not yet mapped, and replays the buffer once correlation completes.
- */
- const applySubagentUpdate = useCallback(
- (payload: SubagentUpdateEvent, parentMessageId: string): void => {
- const invocationKey = resolveSubagentInvocationKey(payload, parentMessageId);
-
- if (!invocationKey) {
- const pending = pendingSubagentBuffer.current.get(payload.subagentRunId) ?? {
- parentMessageId,
- events: [],
- };
- pending.events.push(payload);
- pendingSubagentBuffer.current.set(payload.subagentRunId, pending);
- return;
- }
-
- const pending = pendingSubagentBuffer.current.get(payload.subagentRunId);
- if (pending && pending.events.length > 0) {
- pendingSubagentBuffer.current.delete(payload.subagentRunId);
- }
- const toApply = pending ? [...pending.events, payload] : [payload];
-
+ const applySubagentProgress = useCallback(
+ (invocationKey: string, events: SubagentUpdateEvent[]): void => {
registerSubagentProgressKey(invocationKey);
subagentStore.set(subagentParentStreamOpenByToolCallId(invocationKey), true);
subagentStore.set(subagentProgressByToolCallId(invocationKey), (prev) =>
- reduceSubagentProgress(prev, toApply, 'parent', true),
+ reduceSubagentProgress(prev, events, 'parent', true),
);
},
- [resolveSubagentInvocationKey, subagentStore],
+ [subagentStore],
);
/**
@@ -386,746 +250,104 @@ export default function useStepHandler({
[],
);
- const stepHandler = useCallback(
- (stepEvent: TStepEvent, submission: EventSubmission) => {
- const submissionMessages = submission.messages ?? [];
- const getEventMessages = (candidateMessages: TMessage[]) =>
- submission.isRegenerate ? candidateMessages : getCurrentMessages(candidateMessages);
- const messages = getEventMessages(submissionMessages);
- const { userMessage } = submission;
- const getRegenerateResponseIds = (responseMessageId: string) => {
- const ids = new Set<string>();
- const addId = (id?: string | null) => {
- if (!id) {
- return;
- }
- ids.add(id);
- ids.add(id.replace(/_+$/, ''));
- };
- addId(responseMessageId);
- addId(submission.initialResponse?.messageId);
- addId(submission.userMessage?.responseMessageId);
- return ids;
- };
- const shouldRemoveRegenerateResponse = (message: TMessage, responseMessageId: string) =>
- submission.isRegenerate &&
- !message.isCreatedByUser &&
- /** A compaction's preliminary response is `${anchorId}_`. The ordinary
- * regenerate alias set strips that suffix, but here the base ID is the
- * assistant ANCHOR, not a response being replaced. Keep it so the
- * summary remains its child instead of becoming an orphan root. */
- (submission.compact !== true || message.messageId !== userMessage.messageId) &&
- getRegenerateResponseIds(responseMessageId).has(message.messageId);
- const shouldRemoveInitialResponse = (message: TMessage, responseMessageId: string) => {
- const initialResponseId = submission.initialResponse?.messageId;
- return (
- !submission.isRegenerate &&
- !message.isCreatedByUser &&
- initialResponseId != null &&
- initialResponseId !== responseMessageId &&
- message.messageId === initialResponseId &&
- message.parentMessageId === userMessage.messageId
- );
- };
- const ensureUserMessagePresent = (
- candidateMessages: TMessage[],
- responseMessageId: string,
- ) => {
- if (
- submission.isRegenerate ||
- !userMessage?.messageId ||
- candidateMessages.some((message) => message.messageId === userMessage.messageId)
- ) {
- return candidateMessages;
- }
-
- /** Insert before the row's first CHILD as well as before the response
- * row: abandoned responses from preempted attempts are children of
- * this user message and may already sit in the list. Landing the
- * parent after them orders children before their parent, which the
- * message tree renders as phantom root branches (a folded thread). */
- let insertIndex = candidateMessages.length;
- for (let i = 0; i < candidateMessages.length; i++) {
- const message = candidateMessages[i];
- if (
- message.messageId === responseMessageId ||
- message.parentMessageId === userMessage.messageId
- ) {
- insertIndex = i;
- break;
- }
- }
- if (insertIndex >= candidateMessages.length) {
- return [...candidateMessages, userMessage as TMessage];
- }
-
- const nextMessages = [...candidateMessages];
- nextMessages.splice(insertIndex, 0, userMessage as TMessage);
- return nextMessages;
- };
- const getResponseBaseMessages = (
- candidateMessages: TMessage[],
- responseMessageId: string,
- ensureUserMessage = false,
- ) => {
- const currentMessages = getEventMessages(candidateMessages);
- if (!submission.isRegenerate) {
- const nextMessages = currentMessages.filter(
- (message) => !shouldRemoveInitialResponse(message, responseMessageId),
- );
- return ensureUserMessage
- ? ensureUserMessagePresent(nextMessages, responseMessageId)
- : nextMessages;
- }
- return currentMessages.filter(
- (message) => !shouldRemoveRegenerateResponse(message, responseMessageId),
- );
- };
- const mergeResponseMessage = (
- candidateMessages: TMessage[],
- updatedResponse: TMessage,
- responseMessageId: string,
- options?: { ensureUserMessage?: boolean },
- ) => {
- const currentMessages = getResponseBaseMessages(
- candidateMessages,
- responseMessageId,
- options?.ensureUserMessage === true,
- );
- const hasResponseMessage = currentMessages.some(
- (msg) => msg.messageId === responseMessageId,
- );
- return hasResponseMessage
- ? currentMessages.map((msg) =>
- msg.messageId === responseMessageId ? updatedResponse : msg,
- )
- : [...currentMessages, updatedResponse];
- };
- /**
- * Per-token deltas fold into `messageMap` 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 `messageMap`, so a trailing flush after them merges
- * the same authoritative state; `clearStepMaps` cancels the flush at run
- * boundaries (same lifecycle as the summarize coalescing above).
- */
- const scheduleCoalescedMessagesFlush = (responseMessageId: string) => {
- pendingDeltaFlushIds.current.add(responseMessageId);
- const flush = () => {
- deltaFlushScheduled.current = false;
- messageDeltaRaf.current = null;
- pendingDeltaFlushRef.current = null;
- const ids = pendingDeltaFlushIds.current;
- pendingDeltaFlushIds.current = new Set();
- let candidate = messages;
- for (const id of ids) {
- const latest = messageMap.current.get(id);
- if (!latest) {
- continue;
- }
- candidate = mergeResponseMessage(candidate, latest, id, { ensureUserMessage: true });
- setMessages(candidate);
- }
- };
- /** 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);
+ /**
+ * 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);
};
- let parentMessageId =
- submission.isRegenerate && submission.initialResponse?.parentMessageId
- ? submission.initialResponse.parentMessageId
- : userMessage.messageId;
-
- const currentTime = Date.now();
- if (currentTime - lastAnnouncementTimeRef.current > MESSAGE_UPDATE_INTERVAL) {
- announcePolite({ message: 'composing', isStatus: true });
- lastAnnouncementTimeRef.current = currentTime;
+ /** 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);
+ },
+ [],
+ );
- /** Activity labels honor the same `editPrefixCleared` flag `getEditPrefix` reads, so a
- * batch's tool cards and its header land in one index space. */
- const { initialContent, editPrefixOffset } = getEditPrefix(submission);
-
- if (stepEvent.event === StepEvents.ON_RUN_STEP) {
- const runStep = stepEvent.data;
- let responseMessageId = runStep.runId ?? '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
- }
- if (!responseMessageId) {
- console.warn('No message id found in run step event');
- return;
- }
-
- stepMap.current.set(runStep.id, runStep);
-
- let response = messageMap.current.get(responseMessageId);
-
- if (!response) {
- // Find the actual response message. Regenerate submissions can target
- // an earlier branch while the visible history still ends at a later
- // assistant message, so never seed a regenerated response from the
- // conversation tail.
- const lastMessage = messages[messages.length - 1] as TMessage;
- const responseMessage =
- !submission.isRegenerate && lastMessage && !lastMessage.isCreatedByUser
- ? lastMessage
- : (submission?.initialResponse as TMessage);
-
- // For edit scenarios, initialContent IS the complete starting content (not to be merged)
- // For resume scenarios (no editedContent), initialContent is empty and we use existingContent
- const existingContent = responseMessage?.content ?? [];
- const mergedContent: TMessageContentParts[] =
- initialContent.length > 0 ? initialContent : existingContent;
-
- response = {
- ...responseMessage,
- parentMessageId,
- conversationId: userMessage.conversationId,
- messageId: responseMessageId,
- content: mergedContent,
- };
-
- messageMap.current.set(responseMessageId, response);
-
- // Get fresh messages to handle multi-tab scenarios where messages may have loaded
- // after this handler started (Tab 2 may have more complete history now)
- const currentMessages = getResponseBaseMessages(messages, responseMessageId, true);
-
- // Remove any existing response placeholder
- let updatedMessages = currentMessages.filter(
- (message) =>
- message.messageId !== responseMessageId &&
- !shouldRemoveRegenerateResponse(message, responseMessageId) &&
- !shouldRemoveInitialResponse(message, responseMessageId),
- );
-
- // Ensure userMessage is present (multi-tab: Tab 2 may not have it yet).
- // Regenerate reuses an existing user turn; its submission userMessage is only
- // a transport placeholder and must not become a new visible branch.
- // (`ensureUserMessagePresent` no-ops for regenerate and inserts in
- // parent-before-children order otherwise.)
- updatedMessages = ensureUserMessagePresent(updatedMessages, responseMessageId);
-
- setMessages([...updatedMessages, response]);
- }
-
- if (runStep.stepDetails.type === StepTypes.TOOL_CALLS) {
- const { message: updatedResponse, toolCallId } = applyToolCallsStep(
- response,
- runStep,
- editPrefixOffset,
- (callId) => ({
- toolPreparationStartedAt:
- firstFragmentByCall.current.get(toolTimingKey(runStep.id, callId)) ??
- (runStep.stepDetails.type === StepTypes.TOOL_CALLS &&
- (runStep.stepDetails.tool_calls?.length ?? 0) <= 1
- ? firstFragmentByStep.current.get(runStep.id)
- : undefined),
- toolDispatchedAt: dispatchedByCall.current.get(toolTimingKey(runStep.id, callId)),
- }),
- );
- if (toolCallId) {
- toolCallIdMap.current.set(runStep.id, toolCallId);
- }
- messageMap.current.set(responseMessageId, updatedResponse);
- setMessages(
- mergeResponseMessage(messages, updatedResponse, responseMessageId, {
- ensureUserMessage: true,
- }),
- );
- }
-
- if (runStep.summary != null) {
- const updatedResponse = applySummaryStep(
- messageMap.current.get(responseMessageId) ?? response,
- runStep,
- editPrefixOffset,
- );
- messageMap.current.set(responseMessageId, updatedResponse);
- setMessages(
- mergeResponseMessage(messages, updatedResponse, responseMessageId, {
- ensureUserMessage: true,
- }),
- );
- }
-
- const bufferedDeltas = pendingDeltaBuffer.current.get(runStep.id);
- if (bufferedDeltas && bufferedDeltas.length > 0) {
- pendingDeltaBuffer.current.delete(runStep.id);
- for (const bufferedDelta of bufferedDeltas) {
- stepHandler(bufferedDelta, submission);
- }
- }
- } else if (stepEvent.event === StepEvents.ON_AGENT_UPDATE) {
- const { agent_update } = stepEvent.data;
- let responseMessageId = agent_update.runId || '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
- }
- if (!responseMessageId) {
- console.warn('No message id found in agent update event');
- return;
- }
-
- const response = messageMap.current.get(responseMessageId);
- if (response) {
- const updatedResponse = applyAgentUpdate(response, stepEvent.data, editPrefixOffset);
- messageMap.current.set(responseMessageId, updatedResponse);
- setMessages(
- mergeResponseMessage(messages, updatedResponse, responseMessageId, {
- ensureUserMessage: true,
- }),
- );
- }
- } else if (stepEvent.event === StepEvents.ON_MESSAGE_DELTA) {
- const messageDelta = stepEvent.data;
- const runStep = stepMap.current.get(messageDelta.id);
- let responseMessageId = runStep?.runId ?? '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
- }
-
- if (!runStep || !responseMessageId) {
- const buffer = pendingDeltaBuffer.current.get(messageDelta.id) ?? [];
- buffer.push({ event: StepEvents.ON_MESSAGE_DELTA, data: messageDelta });
- pendingDeltaBuffer.current.set(messageDelta.id, buffer);
- return;
- }
-
- const response = messageMap.current.get(responseMessageId);
- if (response) {
- const result = applyMessageDelta(response, runStep, messageDelta, editPrefixOffset);
- if (result.foldedEditPrefix && submission != null) {
- submission.editPrefixFirstPartFolded = true;
- }
- if (result.updated) {
- messageMap.current.set(responseMessageId, result.message);
- scheduleCoalescedMessagesFlush(responseMessageId);
- }
- }
- } else if (stepEvent.event === StepEvents.ON_REASONING_DELTA) {
- const reasoningDelta = stepEvent.data;
- const runStep = stepMap.current.get(reasoningDelta.id);
- let responseMessageId = runStep?.runId ?? '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
- }
-
- if (!runStep || !responseMessageId) {
- const buffer = pendingDeltaBuffer.current.get(reasoningDelta.id) ?? [];
- buffer.push({ event: StepEvents.ON_REASONING_DELTA, data: reasoningDelta });
- pendingDeltaBuffer.current.set(reasoningDelta.id, buffer);
- return;
- }
-
- const response = messageMap.current.get(responseMessageId);
- if (response) {
- const result = applyReasoningDelta(response, runStep, reasoningDelta, editPrefixOffset);
- if (result.foldedEditPrefix && submission != null) {
- submission.editPrefixFirstPartFolded = true;
- }
- if (result.updated) {
- messageMap.current.set(responseMessageId, result.message);
- scheduleCoalescedMessagesFlush(responseMessageId);
- }
- }
- } else if (stepEvent.event === StepEvents.ON_TOOL_PREPARATION) {
- const { id, index, toolCallId, observed_at: at } = stepEvent.data;
- if (!id || typeof at !== 'number' || !Number.isFinite(at) || at < 0) return;
- const runStep = stepMap.current.get(id);
- const declaredCalls =
- runStep?.stepDetails.type === StepTypes.TOOL_CALLS
- ? runStep.stepDetails.tool_calls
- : undefined;
- const resolvedId =
- toolCallId ??
- (index === 0 && declaredCalls?.length === 1 ? declaredCalls[0]?.id : undefined);
- if (resolvedId) {
- const key = toolTimingKey(id, resolvedId);
- firstFragmentByCall.current.set(
- key,
- Math.min(firstFragmentByCall.current.get(key) ?? at, at),
- );
- } else if (index === 0) {
- firstFragmentByStep.current.set(
- id,
- Math.min(firstFragmentByStep.current.get(id) ?? at, at),
- );
- }
- if (!runStep?.runId || (runStep.status && runStep.status !== 'in_progress')) return;
- const responseId =
- runStep.runId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID
- ? (submission.initialResponse?.messageId ?? '')
- : runStep.runId;
- const response = messageMap.current.get(responseId);
- const contentIndex = runStep.index + editPrefixOffset;
- const part = response?.content?.[contentIndex];
- if (
- !response ||
- part?.type !== ContentTypes.TOOL_CALL ||
- part.tool_call.runStepStatus != null ||
- (resolvedId && part.tool_call.id !== resolvedId)
- )
- return;
- const content = [...(response.content ?? [])];
- content[contentIndex] = {
- ...part,
- tool_call: {
- ...part.tool_call,
- toolPreparationStartedAt: Math.min(part.tool_call.toolPreparationStartedAt ?? at, at),
- },
- };
- const updated = { ...response, content };
- messageMap.current.set(responseId, updated);
- setMessages(
- mergeResponseMessage(messages, updated, responseId, { ensureUserMessage: true }),
- );
- } else if (stepEvent.event === StepEvents.ON_RUN_STEP_DELTA) {
- const runStepDelta = stepEvent.data;
- const at = runStepDelta.observed_at;
- if (typeof at === 'number' && Number.isFinite(at) && at >= 0) {
- for (const chunk of runStepDelta.delta.tool_calls ?? []) {
- if (chunk.id) {
- const first =
- chunk.index === 0 ? firstFragmentByStep.current.get(runStepDelta.id) : undefined;
- const key = toolTimingKey(runStepDelta.id, chunk.id);
- firstFragmentByCall.current.set(
- key,
- Math.min(firstFragmentByCall.current.get(key) ?? at, first ?? at, at),
- );
- if (first != null) firstFragmentByStep.current.delete(runStepDelta.id);
- } else if (chunk.index === 0 && runStepDelta.delta.tool_calls?.length === 1) {
- const declared = stepMap.current.get(runStepDelta.id)?.stepDetails;
- const firstCallId =
- declared?.type === StepTypes.TOOL_CALLS && declared.tool_calls?.length === 1
- ? declared.tool_calls[0]?.id
- : undefined;
- if (firstCallId) {
- const key = toolTimingKey(runStepDelta.id, firstCallId);
- firstFragmentByCall.current.set(
- key,
- Math.min(firstFragmentByCall.current.get(key) ?? at, at),
- );
- } else {
- firstFragmentByStep.current.set(
- runStepDelta.id,
- Math.min(firstFragmentByStep.current.get(runStepDelta.id) ?? at, at),
- );
- }
+ 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);
+ });
}
- }
- }
- const runStep = stepMap.current.get(runStepDelta.id);
- let responseMessageId = runStep?.runId ?? '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
- }
-
- if (!runStep || !responseMessageId) {
- const buffer = pendingDeltaBuffer.current.get(runStepDelta.id) ?? [];
- buffer.push({ event: StepEvents.ON_RUN_STEP_DELTA, data: runStepDelta });
- pendingDeltaBuffer.current.set(runStepDelta.id, buffer);
- return;
- }
-
- const response = messageMap.current.get(responseMessageId);
- const updatedResponse =
- response &&
- applyToolCallDelta(
- response,
- runStep,
- runStepDelta,
- toolCallIdMap.current.get(runStepDelta.id) ?? '',
- editPrefixOffset,
- (callId, index) => ({
- toolPreparationStartedAt:
- firstFragmentByCall.current.get(toolTimingKey(runStepDelta.id, callId)) ??
- (index === 0 ? firstFragmentByStep.current.get(runStepDelta.id) : undefined),
- toolDispatchedAt: dispatchedByCall.current.get(
- toolTimingKey(runStepDelta.id, callId),
- ),
- }),
- );
- if (updatedResponse) {
- messageMap.current.set(responseMessageId, updatedResponse);
- setMessages(
- mergeResponseMessage(messages, updatedResponse, responseMessageId, {
- ensureUserMessage: true,
- }),
- );
- }
- } else if (stepEvent.event === StepEvents.ON_TOOL_CALLS_DISPATCHED) {
- const { dispatched_at: at, toolCalls } = stepEvent.data;
- if (typeof at !== 'number' || !Number.isFinite(at) || at < 0) return;
- for (const call of toolCalls ?? []) {
- if (!call.id) continue;
- if (!call.stepId) continue;
- const key = toolTimingKey(call.stepId, call.id);
- const dispatchedAt = Math.min(dispatchedByCall.current.get(key) ?? at, at);
- dispatchedByCall.current.set(key, dispatchedAt);
- const runStep = stepMap.current.get(call.stepId ?? '');
- if (!runStep?.runId) continue;
- const responseId =
- runStep.runId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID
- ? (submission.initialResponse?.messageId ?? '')
- : runStep.runId;
- const response = messageMap.current.get(responseId);
- const index = runStep.index + editPrefixOffset;
- const part = response?.content?.[index];
- if (
- !response ||
- part?.type !== ContentTypes.TOOL_CALL ||
- part.tool_call.id !== call.id ||
- part.tool_call.runStepStatus != null
- )
- continue;
- const content = [...(response.content ?? [])];
- content[index] = {
- ...part,
- tool_call: { ...part.tool_call, toolDispatchedAt: dispatchedAt },
- };
- const updated = { ...response, content };
- messageMap.current.set(responseId, updated);
- setMessages(
- mergeResponseMessage(messages, updated, responseId, { ensureUserMessage: true }),
- );
- }
- } else if (stepEvent.event === StepEvents.ON_RUN_STEP_COMPLETED) {
- const { result } = stepEvent.data;
-
- const { id: stepId } = result;
- const completedCallId = result.tool_call?.id;
- if (
- completedCallId &&
- typeof result.completed_at === 'number' &&
- Number.isFinite(result.completed_at)
- ) {
- completedByCall.current.set(toolTimingKey(stepId, completedCallId), result.completed_at);
- }
- clearSandboxStarting(completedCallId);
-
- const runStep = stepMap.current.get(stepId);
- let responseMessageId = runStep?.runId ?? '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
- }
-
- if (!runStep || !responseMessageId) {
- const buffer = pendingDeltaBuffer.current.get(stepId) ?? [];
- buffer.push({ event: StepEvents.ON_RUN_STEP_COMPLETED, data: stepEvent.data });
- pendingDeltaBuffer.current.set(stepId, buffer);
- return;
- }
-
- if (isSkillAuthoringToolCall(result.tool_call)) {
- onSkillAuthoringComplete?.();
- }
-
- const response = messageMap.current.get(responseMessageId);
- if (response) {
- const updatedResponse = applyToolCallCompleted(
- response,
- runStep,
- result,
- editPrefixOffset,
- );
- messageMap.current.set(responseMessageId, updatedResponse);
- setMessages(
- mergeResponseMessage(messages, updatedResponse, responseMessageId, {
- ensureUserMessage: true,
- }),
- );
- }
- } else if (stepEvent.event === StepEvents.ON_RUN_STEP_CLOSED) {
- const closed = stepEvent.data;
- const runStep = stepMap.current.get(closed.id);
- let responseMessageId = runStep?.runId ?? '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
- }
-
- /**
- * A closure for a step this client never saw opened is not an error
- * worth surfacing; it happens on reconnect, where the replay may
- * start after the step was created.
- */
- if (!runStep || !responseMessageId) {
- return;
- }
-
- const response = messageMap.current.get(responseMessageId);
- if (!response) {
- return;
- }
-
- const existing = response.content?.[runStep.index + editPrefixOffset];
- if (existing?.type !== ContentTypes.TOOL_CALL || !existing.tool_call) {
- return;
- }
- const existingToolCall = existing.tool_call;
- const callId = existingToolCall.id ?? '';
- const key = toolTimingKey(closed.id, callId);
- const singleCallStep =
- runStep.stepDetails.type === StepTypes.TOOL_CALLS &&
- (runStep.stepDetails.tool_calls?.length ?? 0) <= 1;
- const observedAt = Math.min(
- firstFragmentByCall.current.get(key) ?? Infinity,
- existingToolCall.toolPreparationStartedAt ?? Infinity,
- singleCallStep ? (firstFragmentByStep.current.get(closed.id) ?? Infinity) : Infinity,
- );
- const timing = getToolTimingDurations({
- observedAt: Number.isFinite(observedAt) ? observedAt : undefined,
- dispatchedAt: existingToolCall.toolDispatchedAt ?? dispatchedByCall.current.get(key),
- completedAt: completedByCall.current.get(key),
- });
- firstFragmentByCall.current.delete(key);
- firstFragmentByStep.current.delete(closed.id);
- dispatchedByCall.current.delete(key);
- completedByCall.current.delete(key);
- const updatedResponse = applyRunStepClosed(
- response,
- runStep,
- closed,
- editPrefixOffset,
- timing,
- );
- if (!updatedResponse) {
- return;
- }
- messageMap.current.set(responseMessageId, updatedResponse);
- setMessages(
- mergeResponseMessage(messages, updatedResponse, responseMessageId, {
- ensureUserMessage: true,
- }),
- );
- } else if (stepEvent.event === StepEvents.ON_SANDBOX_STARTING) {
- setSandboxStarting(stepEvent.data.tool_call_id);
- } else if (stepEvent.event === StepEvents.ON_PTC_TOOL_CALL) {
- /** `runId` is the response message id (the run configurable's
- * `run_id`), the same correlation the subagent path uses. */
- let responseMessageId = stepEvent.data.runId ?? '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- }
- applyPtcToolCall(stepEvent.data, responseMessageId);
- } else if (stepEvent.event === StepEvents.ON_SUBAGENT_UPDATE) {
- let responseMessageId = stepEvent.data.runId;
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- }
- applySubagentUpdate(stepEvent.data, responseMessageId);
- if (
- stepEvent.data.phase === 'start' ||
- stepEvent.data.phase === 'stop' ||
- stepEvent.data.phase === 'error'
- ) {
- const conversationId = [
- submission?.userMessage?.conversationId,
- submission?.initialResponse?.conversationId,
- submission?.conversation?.conversationId,
- ].find((id) => id && id !== Constants.NEW_CONVO && id !== Constants.PENDING_CONVO);
- if (conversationId) onSubagentIndexChange?.(conversationId);
- }
- } else if (stepEvent.event === StepEvents.ON_SUMMARIZE_START) {
- announcePolite({ message: 'summarize_started', isStatus: true });
- } else if (stepEvent.event === StepEvents.ON_SUMMARIZE_DELTA) {
- const deltaData = stepEvent.data;
- const runStep = stepMap.current.get(deltaData.id);
- let responseMessageId = runStep?.runId ?? '';
- if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- responseMessageId = submission?.initialResponse?.messageId ?? '';
- parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
- }
-
- if (!runStep || !responseMessageId) {
- const buffer = pendingDeltaBuffer.current.get(deltaData.id) ?? [];
- buffer.push({ event: StepEvents.ON_SUMMARIZE_DELTA, data: deltaData });
- pendingDeltaBuffer.current.set(deltaData.id, buffer);
- return;
- }
-
- const response = messageMap.current.get(responseMessageId);
- if (response) {
- const updatedResponse = applySummarizeDelta(
- response,
- runStep,
- deltaData,
- editPrefixOffset,
- );
- messageMap.current.set(responseMessageId, updatedResponse);
- if (summarizeDeltaRaf.current == null) {
- summarizeDeltaRaf.current = requestAnimationFrame(() => {
- summarizeDeltaRaf.current = null;
- const latest = messageMap.current.get(responseMessageId);
- if (latest) {
- const currentMessages = submission.isRegenerate ? messages : getMessages() || [];
- setMessages(mergeResponseMessage(currentMessages, latest, responseMessageId));
- }
- });
- }
- }
- } else if (stepEvent.event === StepEvents.ON_SUMMARIZE_COMPLETE) {
- const completeData = stepEvent.data;
- const completeRunStep = stepMap.current.get(completeData.id);
- let completeMessageId = completeRunStep?.runId ?? '';
- if (completeMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
- completeMessageId = submission?.initialResponse?.messageId ?? '';
- }
-
- const targetMessage = messageMap.current.get(completeMessageId);
- if (!targetMessage) {
- return;
- }
-
- /** Scoped to the owning step's slot when the step is known; see `finalizeSummaries`. */
- const completeIndex =
- completeRunStep != null ? completeRunStep.index + editPrefixOffset : -1;
- const finalized = finalizeSummaries(targetMessage, completeData, completeIndex);
- if (finalized) {
- announcePolite({
- message: completeData.error ? 'summarize_failed' : 'summarize_completed',
- isStatus: true,
- });
- const currentMessages = submission.isRegenerate ? messages : getMessages() || [];
- messageMap.current.set(completeMessageId, finalized);
- setMessages(mergeResponseMessage(currentMessages, finalized, completeMessageId));
+ 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;
}
- } else {
- const _exhaustive: never = stepEvent;
- console.warn('Unhandled step event', (_exhaustive as TStepEvent).event);
}
},
[
- getMessages,
- lastAnnouncementTimeRef,
announcePolite,
- setMessages,
- getCurrentMessages,
- applySubagentUpdate,
- onSubagentIndexChange,
setSandboxStarting,
clearSandboxStarting,
- applyPtcToolCall,
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 `messageMap` must
+ * 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) {
@@ -1160,17 +382,7 @@ export default function useStepHandler({
summarizeDeltaRaf.current = null;
}
cancelPendingDeltaFlush();
- toolCallIdMap.current.clear();
- firstFragmentByCall.current.clear();
- firstFragmentByStep.current.clear();
- dispatchedByCall.current.clear();
- completedByCall.current.clear();
- messageMap.current.clear();
- stepMap.current.clear();
- pendingDeltaBuffer.current.clear();
- subagentRunToInvocationKey.current.clear();
- claimedSubagentInvocationKeys.current.clear();
- pendingSubagentBuffer.current.clear();
+ 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
@@ -1188,25 +400,19 @@ export default function useStepHandler({
}, [cancelPendingDeltaFlush, closeParentSubagentStreams, resetSandboxAtoms]);
/**
- * Sync a message into the step handler's messageMap.
+ * 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) => {
- if (!message?.messageId) return;
- messageMap.current.set(message.messageId, { ...message });
- const ready = [...pendingSubagentBuffer.current.entries()].filter(
- ([, pending]) => pending.parentMessageId === message.messageId,
- );
- for (const [subagentRunId, pending] of ready) {
- pendingSubagentBuffer.current.delete(subagentRunId);
- for (const event of pending.events) {
- applySubagentUpdate(event, message.messageId);
+ for (const effect of syncStreamMessage(stream.current, message)) {
+ if (effect.type === 'subagent') {
+ applySubagentProgress(effect.invocationKey, effect.events);
}
}
},
- [applySubagentUpdate],
+ [applySubagentProgress],
);
return {
diff --git a/e2e/specs/mock/scenarios/chat-package.spec.ts b/e2e/specs/mock/scenarios/chat-package.spec.ts
index ff2d8162a6..4d9217c137 100644
--- a/e2e/specs/mock/scenarios/chat-package.spec.ts
+++ b/e2e/specs/mock/scenarios/chat-package.spec.ts
@@ -247,7 +247,7 @@ test.describe('the built @librechat/chat package', () => {
return resolveFilename.call(this, request, ...rest);
};
const core = require('@librechat/chat');
- const names = ['createSSETransport', 'normalizeFrame', 'applyMessageDelta', 'applyToolCallDelta', 'isAnsweredAskUserQuestionPart'];
+ const names = ['createSSETransport', 'normalizeFrame', 'applyMessageDelta', 'applyToolCallDelta', 'isAnsweredAskUserQuestionPart', 'reduceStep', 'createStreamState'];
const answer = { entry: require.resolve('@librechat/chat'), cjs: {}, esm: {} };
for (const name of names) answer.cjs[name] = typeof core[name];
import('@librechat/chat').then((esm) => {
@@ -264,7 +264,7 @@ test.describe('the built @librechat/chat package', () => {
};
expect(answer.entry).toBe(resolve(dist, 'index.cjs'));
for (const exports of [answer.cjs, answer.esm]) {
- expect(Object.values(exports)).toEqual(Array(5).fill('function'));
+ expect(Object.values(exports)).toEqual(Array(7).fill('function'));
}
});
});
diff --git a/packages/chat/src/core/__tests__/reducer.spec.ts b/packages/chat/src/core/__tests__/reducer.spec.ts
new file mode 100644
index 0000000000..65ffaa8075
--- /dev/null
+++ b/packages/chat/src/core/__tests__/reducer.spec.ts
@@ -0,0 +1,236 @@
+import {
+ Constants,
+ StepTypes,
+ StepEvents,
+ ContentTypes,
+ ToolCallTypes,
+} from 'librechat-data-provider';
+import type { Agents, TMessage, EventSubmission } from 'librechat-data-provider';
+import type { StepEvent, StepContext } from '../reducer';
+import {
+ reduceStep,
+ flushResponses,
+ resetStreamState,
+ syncStreamMessage,
+ createStreamState,
+ subagentProgressKey,
+} from '../reducer';
+
+const user: TMessage = {
+ messageId: 'user-1',
+ conversationId: 'conv-1',
+ parentMessageId: Constants.NO_PARENT as string,
+ isCreatedByUser: true,
+ text: 'Hello',
+ sender: 'User',
+};
+
+const createContext = () => {
+ let messages: TMessage[] = [user];
+ const writes: TMessage[][] = [];
+ const submission = {
+ userMessage: user,
+ isRegenerate: false,
+ messages: [],
+ conversation: { conversationId: 'conv-1' },
+ initialResponse: { ...user, messageId: 'resp-1', isCreatedByUser: false, content: [] },
+ } as unknown as EventSubmission;
+ const ctx: StepContext = {
+ submission,
+ getMessages: () => messages,
+ setMessages: (next) => {
+ messages = next;
+ writes.push(next);
+ },
+ };
+ return { ctx, writes, read: () => messages };
+};
+
+const textStep = (id: string, index: number): StepEvent => ({
+ event: StepEvents.ON_RUN_STEP,
+ data: {
+ id,
+ runId: 'resp-1',
+ index,
+ type: StepTypes.MESSAGE_CREATION,
+ stepDetails: { type: StepTypes.MESSAGE_CREATION, message_creation: { message_id: id } },
+ usage: null,
+ },
+});
+
+const toolStep = (id: string, index: number, callId: string, name: string): StepEvent => ({
+ event: StepEvents.ON_RUN_STEP,
+ data: {
+ id,
+ runId: 'resp-1',
+ index,
+ type: StepTypes.TOOL_CALLS,
+ stepDetails: {
+ type: StepTypes.TOOL_CALLS,
+ tool_calls: [{ id: callId, name, args: '', type: ToolCallTypes.TOOL_CALL }],
+ },
+ usage: null,
+ },
+});
+
+const text = (id: string, value: string): StepEvent => ({
+ event: StepEvents.ON_MESSAGE_DELTA,
+ data: { id, delta: { content: [{ type: ContentTypes.TEXT, text: value }] } },
+});
+
+const responseContent = (messages: TMessage[]) =>
+ messages.find((message) => message.messageId === 'resp-1')?.content;
+
+describe('reduceStep', () => {
+ it('places each part at its step index, leaving holes rather than shifting', () => {
+ const state = createStreamState();
+ const { ctx, read } = createContext();
+
+ reduceStep(state, textStep('s2', 2), ctx);
+ const effects = reduceStep(state, text('s2', 'later'), ctx);
+ reduceStep(state, textStep('s0', 0), ctx);
+ reduceStep(state, text('s0', 'first'), ctx);
+ flushResponses(state, ctx, ['resp-1'], read());
+
+ expect(effects).toEqual([{ type: 'flush', messageId: 'resp-1', messages: expect.any(Array) }]);
+ const content = responseContent(read());
+ expect(content).toHaveLength(3);
+ expect(content?.[0]).toEqual({ type: ContentTypes.TEXT, text: 'first' });
+ expect(content?.[1]).toBeUndefined();
+ expect(content?.[2]).toEqual({ type: ContentTypes.TEXT, text: 'later' });
+ });
+
+ it('holds deltas for an unseen step and replays them, in order, when it opens', () => {
+ const state = createStreamState();
+ const { ctx, writes, read } = createContext();
+
+ expect(reduceStep(state, text('s0', 'a'), ctx)).toEqual([]);
+ expect(reduceStep(state, text('s0', 'b'), ctx)).toEqual([]);
+ expect(writes).toHaveLength(0);
+
+ const effects = reduceStep(state, textStep('s0', 0), ctx);
+ expect(effects.map((effect) => effect.type)).toEqual(['flush', 'flush']);
+ flushResponses(state, ctx, ['resp-1'], read());
+ expect(responseContent(read())?.[0]).toEqual({ type: ContentTypes.TEXT, text: 'ab' });
+ expect(state.pendingDeltas.size).toBe(0);
+ });
+
+ it('reports side channels as effects without touching the message list', () => {
+ const state = createStreamState();
+ const { ctx, writes } = createContext();
+
+ expect(
+ reduceStep(
+ state,
+ { event: StepEvents.ON_SANDBOX_STARTING, data: { tool_call_id: 'call-1' } },
+ ctx,
+ ),
+ ).toEqual([{ type: 'sandbox-starting', toolCallId: 'call-1' }]);
+ expect(
+ reduceStep(
+ state,
+ {
+ event: StepEvents.ON_SUMMARIZE_START,
+ data: { agentId: 'a' } as Agents.SummarizeStartEvent,
+ },
+ ctx,
+ ),
+ ).toEqual([{ type: 'announce', message: 'summarize_started' }]);
+ const ptc = {
+ tool_call_id: 'call-1',
+ call_id: 'call-1:0',
+ name: 'read_file',
+ status: 'running' as const,
+ runId: Constants.USE_PRELIM_RESPONSE_MESSAGE_ID as string,
+ };
+ expect(reduceStep(state, { event: StepEvents.ON_PTC_TOOL_CALL, data: ptc }, ctx)).toEqual([
+ { type: 'ptc', event: ptc, parentMessageId: 'resp-1' },
+ ]);
+ expect(writes).toHaveLength(0);
+ });
+
+ it('settles the sandbox signal and reports a skill authored by a completed call', () => {
+ const state = createStreamState();
+ const { ctx } = createContext();
+ reduceStep(state, toolStep('t1', 0, 'call-1', 'create_file'), ctx);
+
+ const effects = reduceStep(
+ state,
+ {
+ event: StepEvents.ON_RUN_STEP_COMPLETED,
+ data: {
+ result: {
+ id: 't1',
+ index: 0,
+ tool_call: {
+ id: 'call-1',
+ name: 'create_file',
+ args: '{"file_path":"skills/demo/SKILL.md"}',
+ output: 'ok',
+ },
+ } as never,
+ },
+ },
+ ctx,
+ );
+
+ expect(effects).toEqual([
+ { type: 'sandbox-settled', toolCallId: 'call-1' },
+ { type: 'skill-authored' },
+ ]);
+ });
+
+ it('buffers a subagent envelope until a sync shows its parent call', () => {
+ const state = createStreamState();
+ const { ctx } = createContext();
+ const update = {
+ runId: 'resp-1',
+ subagentRunId: 'child-1',
+ subagentType: 'self',
+ subagentAgentId: 'child',
+ parentAgentId: 'parent',
+ phase: 'start' as const,
+ label: 'started',
+ timestamp: '2026-10-11T00:00:00.000Z',
+ };
+
+ expect(reduceStep(state, { event: StepEvents.ON_SUBAGENT_UPDATE, data: update }, ctx)).toEqual([
+ { type: 'subagent-index', conversationId: 'conv-1' },
+ ]);
+
+ const effects = syncStreamMessage(state, {
+ ...user,
+ messageId: 'resp-1',
+ isCreatedByUser: false,
+ content: [
+ { type: ContentTypes.TEXT, text: 'x' },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id: 'call-sub', name: Constants.SUBAGENT, args: '{}', type: 'tool_call' },
+ },
+ ] as TMessage['content'],
+ });
+
+ expect(effects).toEqual([
+ {
+ type: 'subagent',
+ invocationKey: subagentProgressKey('resp-1', 'call-sub', 1),
+ events: [update],
+ },
+ ]);
+ expect(state.pendingSubagents.size).toBe(0);
+ });
+
+ it('forgets every step, response and buffer on reset', () => {
+ const state = createStreamState();
+ const { ctx } = createContext();
+ reduceStep(state, text('s9', 'held'), ctx);
+ reduceStep(state, textStep('s0', 0), ctx);
+
+ resetStreamState(state);
+
+ expect(state.steps.size + state.messages.size + state.pendingDeltas.size).toBe(0);
+ expect(reduceStep(state, text('s0', 'late'), ctx)).toEqual([]);
+ expect(state.pendingDeltas.get('s0')).toHaveLength(1);
+ });
+});
diff --git a/packages/chat/src/core/index.ts b/packages/chat/src/core/index.ts
index e1a4841011..a76551ae67 100644
--- a/packages/chat/src/core/index.ts
+++ b/packages/chat/src/core/index.ts
@@ -1,4 +1,5 @@
export * from './ask';
export * from './steps';
export * from './types';
+export * from './reducer';
export * from './transport';
diff --git a/packages/chat/src/core/reducer.ts b/packages/chat/src/core/reducer.ts
new file mode 100644
index 0000000000..89bdafba33
--- /dev/null
+++ b/packages/chat/src/core/reducer.ts
@@ -0,0 +1,867 @@
+import {
+ Constants,
+ StepTypes,
+ StepEvents,
+ ContentTypes,
+ getToolTimingDurations,
+} from 'librechat-data-provider';
+import type {
+ Agents,
+ TMessage,
+ EventSubmission,
+ PtcToolCallEvent,
+ SubagentUpdateEvent,
+ SandboxStartingEvent,
+ TMessageContentParts,
+} from 'librechat-data-provider';
+import {
+ getEditPrefix,
+ applyAgentUpdate,
+ applySummaryStep,
+ applyMessageDelta,
+ finalizeSummaries,
+ applyRunStepClosed,
+ applyToolCallsStep,
+ applyToolCallDelta,
+ applyReasoningDelta,
+ applySummarizeDelta,
+ applyToolCallCompleted,
+ isSkillAuthoringToolCall,
+} from './steps';
+
+/**
+ * The step reducer behind `useStepHandler`: folds one agent step event into the response message
+ * it targets and reports every write outside the message list as an effect.
+ *
+ * Message writes go through `StepContext.setMessages` as they happen, because later writes in the
+ * same event read the list back through `getMessages`. Everything else (live-status stores,
+ * announcements, cache invalidation, coalesced flushes) is returned in order for the binding.
+ *
+ * Invariant: a part's position in `message.content` is its step index plus the retained edit
+ * prefix. Nothing here splices content mid-stream.
+ */
+
+export type StepEvent =
+ | { event: StepEvents.ON_RUN_STEP; data: Agents.RunStep }
+ | { event: StepEvents.ON_AGENT_UPDATE; data: Agents.AgentUpdate }
+ | { event: StepEvents.ON_MESSAGE_DELTA; data: Agents.MessageDeltaEvent }
+ | { event: StepEvents.ON_REASONING_DELTA; data: Agents.ReasoningDeltaEvent }
+ | { event: StepEvents.ON_RUN_STEP_DELTA; data: Agents.RunStepDeltaEvent }
+ | { event: StepEvents.ON_TOOL_CALLS_DISPATCHED; data: Agents.ToolCallsDispatchedEvent }
+ | { event: StepEvents.ON_TOOL_PREPARATION; data: Agents.ToolPreparationMarker }
+ | { event: StepEvents.ON_RUN_STEP_COMPLETED; data: { result: Agents.ToolEndEvent } }
+ | { event: StepEvents.ON_RUN_STEP_CLOSED; data: Agents.RunStepClosedEvent }
+ | { event: StepEvents.ON_SUMMARIZE_START; data: Agents.SummarizeStartEvent }
+ | { event: StepEvents.ON_SUMMARIZE_DELTA; data: Agents.SummarizeDeltaEvent }
+ | { event: StepEvents.ON_SUMMARIZE_COMPLETE; data: Agents.SummarizeCompleteEvent }
+ | { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent }
+ | { event: StepEvents.ON_SANDBOX_STARTING; data: SandboxStartingEvent }
+ | { event: StepEvents.ON_PTC_TOOL_CALL; data: PtcToolCallEvent };
+
+/**
+ * Side channels of one step event, in the order the event produced them.
+ *
+ * `flush` and `summary` ask the binding to merge the response into the list later (deltas are
+ * coalesced per frame); `messages` is the list the event read, which the flush merges onto.
+ */
+export type StepEffect =
+ | { type: 'flush'; messageId: string; messages: TMessage[] }
+ | { type: 'summary'; messageId: string; messages: TMessage[] }
+ | { type: 'announce'; message: 'summarize_started' | 'summarize_completed' | 'summarize_failed' }
+ | { type: 'sandbox-starting'; toolCallId: string }
+ | { type: 'sandbox-settled'; toolCallId?: string }
+ | { type: 'skill-authored' }
+ | { type: 'ptc'; event: PtcToolCallEvent; parentMessageId: string }
+ | { type: 'subagent'; invocationKey: string; events: SubagentUpdateEvent[] }
+ | { type: 'subagent-index'; conversationId: string };
+
+/** The message list the reducer reads and writes; the React Query cache in the app. */
+export type StepContext = {
+ submission: EventSubmission;
+ getMessages: () => TMessage[] | undefined;
+ setMessages: (messages: TMessage[]) => void;
+};
+
+type PendingSubagent = { parentMessageId: string; events: SubagentUpdateEvent[] };
+
+/** Per-run bookkeeping. Mutable by design: deltas arrive per token. */
+export type StreamState = {
+ /** Authoritative streaming copy of each response, ahead of the cache while a flush is queued. */
+ messages: Map<string, TMessage>;
+ steps: Map<string, Agents.RunStep>;
+ toolCallIds: Map<string, string | undefined>;
+ firstFragmentByCall: Map<string, number>;
+ firstFragmentByStep: Map<string, number>;
+ dispatchedByCall: Map<string, number>;
+ completedByCall: Map<string, number>;
+ /** Deltas that arrived before their run step, replayed when it lands. */
+ pendingDeltas: Map<string, StepEvent[]>;
+ /**
+ * `subagentRunId` to one concrete parent content-part occurrence. Provider ids repeat across
+ * and within messages, so the claim is by occurrence, oldest first.
+ */
+ subagentInvocations: Map<string, string>;
+ claimedInvocations: Set<string>;
+ /** Subagent envelopes that arrived before their parent tool call was in `messages`. */
+ pendingSubagents: Map<string, PendingSubagent>;
+};
+
+export function createStreamState(): StreamState {
+ return {
+ messages: new Map(),
+ steps: new Map(),
+ toolCallIds: new Map(),
+ firstFragmentByCall: new Map(),
+ firstFragmentByStep: new Map(),
+ dispatchedByCall: new Map(),
+ completedByCall: new Map(),
+ pendingDeltas: new Map(),
+ subagentInvocations: new Map(),
+ claimedInvocations: new Set(),
+ pendingSubagents: new Map(),
+ };
+}
+
+export function resetStreamState(state: StreamState): void {
+ state.messages.clear();
+ state.steps.clear();
+ state.toolCallIds.clear();
+ state.firstFragmentByCall.clear();
+ state.firstFragmentByStep.clear();
+ state.dispatchedByCall.clear();
+ state.completedByCall.clear();
+ state.pendingDeltas.clear();
+ state.subagentInvocations.clear();
+ state.claimedInvocations.clear();
+ state.pendingSubagents.clear();
+}
+
+/** Atom identity of one subagent tool-call content-part occurrence. */
+export const subagentProgressKey = (
+ parentMessageId: string,
+ toolCallId: string,
+ partIndex: number,
+): string => `${parentMessageId}\u0000${toolCallId}\u0000${partIndex}`;
+
+const toolTimingKey = (stepId: string, callId: string) => `${stepId}\u0000${callId}`;
+
+const isValidTime = (at: unknown): at is number =>
+ typeof at === 'number' && Number.isFinite(at) && at >= 0;
+
+const getCurrentMessages = (ctx: StepContext, messages: TMessage[]): TMessage[] => {
+ const freshMessages = ctx.getMessages();
+ return freshMessages && freshMessages.length >= messages.length ? freshMessages : messages;
+};
+
+const getEventMessages = (ctx: StepContext, messages: TMessage[]): TMessage[] =>
+ ctx.submission.isRegenerate ? messages : getCurrentMessages(ctx, messages);
+
+const getRegenerateResponseIds = (submission: EventSubmission, responseMessageId: string) => {
+ const ids = new Set<string>();
+ const addId = (id?: string | null) => {
+ if (!id) {
+ return;
+ }
+ ids.add(id);
+ ids.add(id.replace(/_+$/, ''));
+ };
+ addId(responseMessageId);
+ addId(submission.initialResponse?.messageId);
+ addId(submission.userMessage?.responseMessageId);
+ return ids;
+};
+
+const shouldRemoveRegenerateResponse = (
+ submission: EventSubmission,
+ message: TMessage,
+ responseMessageId: string,
+) =>
+ submission.isRegenerate &&
+ !message.isCreatedByUser &&
+ /** A compaction's preliminary response is `${anchorId}_`. The ordinary regenerate alias set
+ * strips that suffix, but here the base ID is the assistant ANCHOR, not a response being
+ * replaced. Keep it so the summary remains its child instead of becoming an orphan root. */
+ (submission.compact !== true || message.messageId !== submission.userMessage.messageId) &&
+ getRegenerateResponseIds(submission, responseMessageId).has(message.messageId);
+
+const shouldRemoveInitialResponse = (
+ submission: EventSubmission,
+ message: TMessage,
+ responseMessageId: string,
+) => {
+ const initialResponseId = submission.initialResponse?.messageId;
+ return (
+ !submission.isRegenerate &&
+ !message.isCreatedByUser &&
+ initialResponseId != null &&
+ initialResponseId !== responseMessageId &&
+ message.messageId === initialResponseId &&
+ message.parentMessageId === submission.userMessage.messageId
+ );
+};
+
+const ensureUserMessagePresent = (
+ submission: EventSubmission,
+ candidateMessages: TMessage[],
+ responseMessageId: string,
+): TMessage[] => {
+ const { userMessage } = submission;
+ if (
+ submission.isRegenerate ||
+ !userMessage?.messageId ||
+ candidateMessages.some((message) => message.messageId === userMessage.messageId)
+ ) {
+ return candidateMessages;
+ }
+
+ /** Insert before the row's first CHILD as well as before the response row: abandoned responses
+ * from preempted attempts are children of this user message and may already sit in the list.
+ * Landing the parent after them orders children before their parent, which the message tree
+ * renders as phantom root branches (a folded thread). */
+ let insertIndex = candidateMessages.length;
+ for (let i = 0; i < candidateMessages.length; i++) {
+ const message = candidateMessages[i];
+ if (
+ message.messageId === responseMessageId ||
+ message.parentMessageId === userMessage.messageId
+ ) {
+ insertIndex = i;
+ break;
+ }
+ }
+ if (insertIndex >= candidateMessages.length) {
+ return [...candidateMessages, userMessage as TMessage];
+ }
+
+ const nextMessages = [...candidateMessages];
+ nextMessages.splice(insertIndex, 0, userMessage as TMessage);
+ return nextMessages;
+};
+
+const getResponseBaseMessages = (
+ ctx: StepContext,
+ candidateMessages: TMessage[],
+ responseMessageId: string,
+ ensureUserMessage = false,
+): TMessage[] => {
+ const { submission } = ctx;
+ const currentMessages = getEventMessages(ctx, candidateMessages);
+ if (!submission.isRegenerate) {
+ const nextMessages = currentMessages.filter(
+ (message) => !shouldRemoveInitialResponse(submission, message, responseMessageId),
+ );
+ return ensureUserMessage
+ ? ensureUserMessagePresent(submission, nextMessages, responseMessageId)
+ : nextMessages;
+ }
+ return currentMessages.filter(
+ (message) => !shouldRemoveRegenerateResponse(submission, message, responseMessageId),
+ );
+};
+
+/** Replaces (or appends) the response in the list, dropping the placeholder it supersedes. */
+export function mergeResponseMessage(
+ ctx: StepContext,
+ candidateMessages: TMessage[],
+ updatedResponse: TMessage,
+ responseMessageId: string,
+ options?: { ensureUserMessage?: boolean },
+): TMessage[] {
+ const currentMessages = getResponseBaseMessages(
+ ctx,
+ candidateMessages,
+ responseMessageId,
+ options?.ensureUserMessage === true,
+ );
+ const hasResponseMessage = currentMessages.some((msg) => msg.messageId === responseMessageId);
+ return hasResponseMessage
+ ? currentMessages.map((msg) => (msg.messageId === responseMessageId ? updatedResponse : msg))
+ : [...currentMessages, updatedResponse];
+}
+
+/** Writes the coalesced delta state of each response, merging onto the list the event read. */
+export function flushResponses(
+ state: StreamState,
+ ctx: StepContext,
+ messageIds: Iterable<string>,
+ messages: TMessage[],
+): void {
+ let candidate = messages;
+ for (const id of messageIds) {
+ const latest = state.messages.get(id);
+ if (!latest) {
+ continue;
+ }
+ candidate = mergeResponseMessage(ctx, candidate, latest, id, { ensureUserMessage: true });
+ ctx.setMessages(candidate);
+ }
+}
+
+/** Writes the coalesced summarize-delta state of one response. */
+export function flushSummary(
+ state: StreamState,
+ ctx: StepContext,
+ messageId: string,
+ messages: TMessage[],
+): void {
+ const latest = state.messages.get(messageId);
+ if (!latest) {
+ return;
+ }
+ const currentMessages = ctx.submission.isRegenerate ? messages : ctx.getMessages() || [];
+ ctx.setMessages(mergeResponseMessage(ctx, currentMessages, latest, messageId));
+}
+
+const resolveSubagentInvocationKey = (
+ state: StreamState,
+ payload: SubagentUpdateEvent,
+ parentMessageId: string,
+): string | undefined => {
+ const cached = state.subagentInvocations.get(payload.subagentRunId);
+ if (cached != null) return cached;
+ if (parentMessageId === '') return undefined;
+
+ /** `runId` names the expected parent message. Until it arrives, buffer instead of claiming a
+ * same-ID call from another parallel response; the claim is permanent once made. */
+ const content = state.messages.get(parentMessageId)?.content;
+ if (!Array.isArray(content)) return undefined;
+ for (let i = 0; i < content.length; i++) {
+ const part = content[i];
+ if (part?.type !== ContentTypes.TOOL_CALL) continue;
+ const tc = (part as { [ContentTypes.TOOL_CALL]?: { id?: string; name?: string } })[
+ ContentTypes.TOOL_CALL
+ ];
+ if (
+ tc?.name === Constants.SUBAGENT &&
+ tc.id &&
+ (payload.parentToolCallId == null || tc.id === payload.parentToolCallId) &&
+ !state.claimedInvocations.has(subagentProgressKey(parentMessageId, tc.id, i))
+ ) {
+ const invocationKey = subagentProgressKey(parentMessageId, tc.id, i);
+ state.subagentInvocations.set(payload.subagentRunId, invocationKey);
+ state.claimedInvocations.add(invocationKey);
+ return invocationKey;
+ }
+ }
+ return undefined;
+};
+
+/**
+ * Routes a subagent envelope to its parent invocation, buffering it until the parent tool call
+ * is known and releasing the buffer, in arrival order, once it is.
+ */
+function claimSubagentUpdate(
+ state: StreamState,
+ payload: SubagentUpdateEvent,
+ parentMessageId: string,
+): StepEffect[] {
+ const invocationKey = resolveSubagentInvocationKey(state, payload, parentMessageId);
+ const pending = state.pendingSubagents.get(payload.subagentRunId);
+
+ if (!invocationKey) {
+ const buffer = pending ?? { parentMessageId, events: [] };
+ buffer.events.push(payload);
+ state.pendingSubagents.set(payload.subagentRunId, buffer);
+ return [];
+ }
+
+ if (pending && pending.events.length > 0) {
+ state.pendingSubagents.delete(payload.subagentRunId);
+ }
+ const events = pending ? [...pending.events, payload] : [payload];
+ return [{ type: 'subagent', invocationKey, events }];
+}
+
+/**
+ * Seeds the streaming copy of a message from a sync snapshot, so later deltas build on it, and
+ * releases subagent envelopes that were waiting for it.
+ */
+export function syncStreamMessage(state: StreamState, message: TMessage): StepEffect[] {
+ if (!message?.messageId) return [];
+ state.messages.set(message.messageId, { ...message });
+ const effects: StepEffect[] = [];
+ const ready = [...state.pendingSubagents.entries()].filter(
+ ([, pending]) => pending.parentMessageId === message.messageId,
+ );
+ for (const [subagentRunId, pending] of ready) {
+ state.pendingSubagents.delete(subagentRunId);
+ for (const event of pending.events) {
+ effects.push(...claimSubagentUpdate(state, event, message.messageId));
+ }
+ }
+ return effects;
+}
+
+/** The response a step writes to; a preliminary id resolves to the submission's response. */
+const resolveResponseId = (submission: EventSubmission, runId: string | undefined): string =>
+ runId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID
+ ? (submission.initialResponse?.messageId ?? '')
+ : (runId ?? '');
+
+const bufferDelta = (state: StreamState, stepId: string, event: StepEvent) => {
+ const buffer = state.pendingDeltas.get(stepId) ?? [];
+ buffer.push(event);
+ state.pendingDeltas.set(stepId, buffer);
+};
+
+/** Folds one step event into `state` and the message list; returns its side channels in order. */
+export function reduceStep(state: StreamState, event: StepEvent, ctx: StepContext): StepEffect[] {
+ const { submission } = ctx;
+ const messages = getEventMessages(ctx, submission.messages ?? []);
+ const { userMessage } = submission;
+ const effects: StepEffect[] = [];
+ const merge = (updated: TMessage, responseMessageId: string) =>
+ ctx.setMessages(
+ mergeResponseMessage(ctx, messages, updated, responseMessageId, { ensureUserMessage: true }),
+ );
+
+ /** Activity labels honor the same `editPrefixCleared` flag `getEditPrefix` reads, so a batch's
+ * tool cards and its header land in one index space. */
+ const { initialContent, editPrefixOffset } = getEditPrefix(submission);
+
+ if (event.event === StepEvents.ON_RUN_STEP) {
+ const runStep = event.data;
+ let parentMessageId =
+ submission.isRegenerate && submission.initialResponse?.parentMessageId
+ ? submission.initialResponse.parentMessageId
+ : userMessage.messageId;
+ let responseMessageId = runStep.runId ?? '';
+ if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
+ responseMessageId = submission?.initialResponse?.messageId ?? '';
+ parentMessageId = submission?.initialResponse?.parentMessageId ?? '';
+ }
+ if (!responseMessageId) {
+ console.warn('No message id found in run step event');
+ return effects;
+ }
+
+ state.steps.set(runStep.id, runStep);
+
+ let response = state.messages.get(responseMessageId);
+
+ if (!response) {
+ /** Regenerate can target an earlier branch while the visible history still ends at a later
+ * assistant message, so a regenerated response is never seeded from the tail. */
+ const lastMessage = messages[messages.length - 1] as TMessage;
+ const responseMessage =
+ !submission.isRegenerate && lastMessage && !lastMessage.isCreatedByUser
+ ? lastMessage
+ : (submission?.initialResponse as TMessage);
+
+ /** An edit's `initialContent` IS the starting content; a resume starts from what exists. */
+ const existingContent = responseMessage?.content ?? [];
+ const mergedContent: TMessageContentParts[] =
+ initialContent.length > 0 ? initialContent : existingContent;
+
+ response = {
+ ...responseMessage,
+ parentMessageId,
+ conversationId: userMessage.conversationId,
+ messageId: responseMessageId,
+ content: mergedContent,
+ };
+
+ state.messages.set(responseMessageId, response);
+
+ /** Fresh read: another tab may have loaded more history since the handler started. */
+ const currentMessages = getResponseBaseMessages(ctx, messages, responseMessageId, true);
+
+ let updatedMessages = currentMessages.filter(
+ (message) =>
+ message.messageId !== responseMessageId &&
+ !shouldRemoveRegenerateResponse(submission, message, responseMessageId) &&
+ !shouldRemoveInitialResponse(submission, message, responseMessageId),
+ );
+
+ /** Regenerate reuses an existing user turn; its submission userMessage is only a transport
+ * placeholder and must not become a new visible branch. */
+ updatedMessages = ensureUserMessagePresent(submission, updatedMessages, responseMessageId);
+
+ ctx.setMessages([...updatedMessages, response]);
+ }
+
+ if (runStep.stepDetails.type === StepTypes.TOOL_CALLS) {
+ const { message: updatedResponse, toolCallId } = applyToolCallsStep(
+ response,
+ runStep,
+ editPrefixOffset,
+ (callId) => ({
+ toolPreparationStartedAt:
+ state.firstFragmentByCall.get(toolTimingKey(runStep.id, callId)) ??
+ (runStep.stepDetails.type === StepTypes.TOOL_CALLS &&
+ (runStep.stepDetails.tool_calls?.length ?? 0) <= 1
+ ? state.firstFragmentByStep.get(runStep.id)
+ : undefined),
+ toolDispatchedAt: state.dispatchedByCall.get(toolTimingKey(runStep.id, callId)),
+ }),
+ );
+ if (toolCallId) {
+ state.toolCallIds.set(runStep.id, toolCallId);
+ }
+ state.messages.set(responseMessageId, updatedResponse);
+ merge(updatedResponse, responseMessageId);
+ }
+
+ if (runStep.summary != null) {
+ const updatedResponse = applySummaryStep(
+ state.messages.get(responseMessageId) ?? response,
+ runStep,
+ editPrefixOffset,
+ );
+ state.messages.set(responseMessageId, updatedResponse);
+ merge(updatedResponse, responseMessageId);
+ }
+
+ const bufferedDeltas = state.pendingDeltas.get(runStep.id);
+ if (bufferedDeltas && bufferedDeltas.length > 0) {
+ state.pendingDeltas.delete(runStep.id);
+ for (const bufferedDelta of bufferedDeltas) {
+ effects.push(...reduceStep(state, bufferedDelta, ctx));
+ }
+ }
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_AGENT_UPDATE) {
+ const responseMessageId = resolveResponseId(submission, event.data.agent_update.runId || '');
+ if (!responseMessageId) {
+ console.warn('No message id found in agent update event');
+ return effects;
+ }
+ const response = state.messages.get(responseMessageId);
+ if (response) {
+ const updatedResponse = applyAgentUpdate(response, event.data, editPrefixOffset);
+ state.messages.set(responseMessageId, updatedResponse);
+ merge(updatedResponse, responseMessageId);
+ }
+ return effects;
+ }
+
+ if (
+ event.event === StepEvents.ON_MESSAGE_DELTA ||
+ event.event === StepEvents.ON_REASONING_DELTA
+ ) {
+ const delta = event.data;
+ const runStep = state.steps.get(delta.id);
+ const responseMessageId = resolveResponseId(submission, runStep?.runId);
+ if (!runStep || !responseMessageId) {
+ bufferDelta(state, delta.id, event);
+ return effects;
+ }
+ const response = state.messages.get(responseMessageId);
+ if (!response) {
+ return effects;
+ }
+ const result =
+ event.event === StepEvents.ON_MESSAGE_DELTA
+ ? applyMessageDelta(response, runStep, event.data, editPrefixOffset)
+ : applyReasoningDelta(response, runStep, event.data, editPrefixOffset);
+ if (result.foldedEditPrefix && submission != null) {
+ submission.editPrefixFirstPartFolded = true;
+ }
+ if (result.updated) {
+ state.messages.set(responseMessageId, result.message);
+ effects.push({ type: 'flush', messageId: responseMessageId, messages });
+ }
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_TOOL_PREPARATION) {
+ const { id, index, toolCallId, observed_at: at } = event.data;
+ if (!id || !isValidTime(at)) return effects;
+ const runStep = state.steps.get(id);
+ const declaredCalls =
+ runStep?.stepDetails.type === StepTypes.TOOL_CALLS
+ ? runStep.stepDetails.tool_calls
+ : undefined;
+ const resolvedId =
+ toolCallId ?? (index === 0 && declaredCalls?.length === 1 ? declaredCalls[0]?.id : undefined);
+ if (resolvedId) {
+ const key = toolTimingKey(id, resolvedId);
+ state.firstFragmentByCall.set(key, Math.min(state.firstFragmentByCall.get(key) ?? at, at));
+ } else if (index === 0) {
+ state.firstFragmentByStep.set(id, Math.min(state.firstFragmentByStep.get(id) ?? at, at));
+ }
+ if (!runStep?.runId || (runStep.status && runStep.status !== 'in_progress')) return effects;
+ const responseId = resolveResponseId(submission, runStep.runId);
+ const response = state.messages.get(responseId);
+ const contentIndex = runStep.index + editPrefixOffset;
+ const part = response?.content?.[contentIndex];
+ if (
+ !response ||
+ part?.type !== ContentTypes.TOOL_CALL ||
+ part.tool_call.runStepStatus != null ||
+ (resolvedId && part.tool_call.id !== resolvedId)
+ ) {
+ return effects;
+ }
+ const content = [...(response.content ?? [])];
+ content[contentIndex] = {
+ ...part,
+ tool_call: {
+ ...part.tool_call,
+ toolPreparationStartedAt: Math.min(part.tool_call.toolPreparationStartedAt ?? at, at),
+ },
+ };
+ const updated = { ...response, content };
+ state.messages.set(responseId, updated);
+ merge(updated, responseId);
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_RUN_STEP_DELTA) {
+ const runStepDelta = event.data;
+ const at = runStepDelta.observed_at;
+ if (typeof at === 'number' && Number.isFinite(at) && at >= 0) {
+ for (const chunk of runStepDelta.delta.tool_calls ?? []) {
+ if (chunk.id) {
+ const first =
+ chunk.index === 0 ? state.firstFragmentByStep.get(runStepDelta.id) : undefined;
+ const key = toolTimingKey(runStepDelta.id, chunk.id);
+ state.firstFragmentByCall.set(
+ key,
+ Math.min(state.firstFragmentByCall.get(key) ?? at, first ?? at, at),
+ );
+ if (first != null) state.firstFragmentByStep.delete(runStepDelta.id);
+ } else if (chunk.index === 0 && runStepDelta.delta.tool_calls?.length === 1) {
+ const declared = state.steps.get(runStepDelta.id)?.stepDetails;
+ const firstCallId =
+ declared?.type === StepTypes.TOOL_CALLS && declared.tool_calls?.length === 1
+ ? declared.tool_calls[0]?.id
+ : undefined;
+ if (firstCallId) {
+ const key = toolTimingKey(runStepDelta.id, firstCallId);
+ state.firstFragmentByCall.set(
+ key,
+ Math.min(state.firstFragmentByCall.get(key) ?? at, at),
+ );
+ } else {
+ state.firstFragmentByStep.set(
+ runStepDelta.id,
+ Math.min(state.firstFragmentByStep.get(runStepDelta.id) ?? at, at),
+ );
+ }
+ }
+ }
+ }
+ const runStep = state.steps.get(runStepDelta.id);
+ const responseMessageId = resolveResponseId(submission, runStep?.runId);
+ if (!runStep || !responseMessageId) {
+ bufferDelta(state, runStepDelta.id, event);
+ return effects;
+ }
+
+ const response = state.messages.get(responseMessageId);
+ const updatedResponse =
+ response &&
+ applyToolCallDelta(
+ response,
+ runStep,
+ runStepDelta,
+ state.toolCallIds.get(runStepDelta.id) ?? '',
+ editPrefixOffset,
+ (callId, index) => ({
+ toolPreparationStartedAt:
+ state.firstFragmentByCall.get(toolTimingKey(runStepDelta.id, callId)) ??
+ (index === 0 ? state.firstFragmentByStep.get(runStepDelta.id) : undefined),
+ toolDispatchedAt: state.dispatchedByCall.get(toolTimingKey(runStepDelta.id, callId)),
+ }),
+ );
+ if (updatedResponse) {
+ state.messages.set(responseMessageId, updatedResponse);
+ merge(updatedResponse, responseMessageId);
+ }
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_TOOL_CALLS_DISPATCHED) {
+ const { dispatched_at: at, toolCalls } = event.data;
+ if (!isValidTime(at)) return effects;
+ for (const call of toolCalls ?? []) {
+ if (!call.id || !call.stepId) continue;
+ const key = toolTimingKey(call.stepId, call.id);
+ const dispatchedAt = Math.min(state.dispatchedByCall.get(key) ?? at, at);
+ state.dispatchedByCall.set(key, dispatchedAt);
+ const runStep = state.steps.get(call.stepId);
+ if (!runStep?.runId) continue;
+ const responseId = resolveResponseId(submission, runStep.runId);
+ const response = state.messages.get(responseId);
+ const index = runStep.index + editPrefixOffset;
+ const part = response?.content?.[index];
+ if (
+ !response ||
+ part?.type !== ContentTypes.TOOL_CALL ||
+ part.tool_call.id !== call.id ||
+ part.tool_call.runStepStatus != null
+ ) {
+ continue;
+ }
+ const content = [...(response.content ?? [])];
+ content[index] = {
+ ...part,
+ tool_call: { ...part.tool_call, toolDispatchedAt: dispatchedAt },
+ };
+ const updated = { ...response, content };
+ state.messages.set(responseId, updated);
+ merge(updated, responseId);
+ }
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_RUN_STEP_COMPLETED) {
+ const { result } = event.data;
+ const { id: stepId } = result;
+ const completedCallId = result.tool_call?.id;
+ if (
+ completedCallId &&
+ typeof result.completed_at === 'number' &&
+ Number.isFinite(result.completed_at)
+ ) {
+ state.completedByCall.set(toolTimingKey(stepId, completedCallId), result.completed_at);
+ }
+ effects.push({ type: 'sandbox-settled', toolCallId: completedCallId });
+
+ const runStep = state.steps.get(stepId);
+ const responseMessageId = resolveResponseId(submission, runStep?.runId);
+ if (!runStep || !responseMessageId) {
+ bufferDelta(state, stepId, event);
+ return effects;
+ }
+
+ if (isSkillAuthoringToolCall(result.tool_call)) {
+ effects.push({ type: 'skill-authored' });
+ }
+
+ const response = state.messages.get(responseMessageId);
+ if (response) {
+ const updatedResponse = applyToolCallCompleted(response, runStep, result, editPrefixOffset);
+ state.messages.set(responseMessageId, updatedResponse);
+ merge(updatedResponse, responseMessageId);
+ }
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_RUN_STEP_CLOSED) {
+ const closed = event.data;
+ const runStep = state.steps.get(closed.id);
+ const responseMessageId = resolveResponseId(submission, runStep?.runId);
+ /** A closure for a step this client never saw opened happens on reconnect, where the replay
+ * may start after the step was created; it is not an error worth surfacing. */
+ if (!runStep || !responseMessageId) {
+ return effects;
+ }
+ const response = state.messages.get(responseMessageId);
+ const existing = response?.content?.[runStep.index + editPrefixOffset];
+ if (!response || existing?.type !== ContentTypes.TOOL_CALL || !existing.tool_call) {
+ return effects;
+ }
+ const existingToolCall = existing.tool_call;
+ const key = toolTimingKey(closed.id, existingToolCall.id ?? '');
+ const singleCallStep =
+ runStep.stepDetails.type === StepTypes.TOOL_CALLS &&
+ (runStep.stepDetails.tool_calls?.length ?? 0) <= 1;
+ const observedAt = Math.min(
+ state.firstFragmentByCall.get(key) ?? Infinity,
+ existingToolCall.toolPreparationStartedAt ?? Infinity,
+ singleCallStep ? (state.firstFragmentByStep.get(closed.id) ?? Infinity) : Infinity,
+ );
+ const timing = getToolTimingDurations({
+ observedAt: Number.isFinite(observedAt) ? observedAt : undefined,
+ dispatchedAt: existingToolCall.toolDispatchedAt ?? state.dispatchedByCall.get(key),
+ completedAt: state.completedByCall.get(key),
+ });
+ state.firstFragmentByCall.delete(key);
+ state.firstFragmentByStep.delete(closed.id);
+ state.dispatchedByCall.delete(key);
+ state.completedByCall.delete(key);
+ const updatedResponse = applyRunStepClosed(response, runStep, closed, editPrefixOffset, timing);
+ if (updatedResponse) {
+ state.messages.set(responseMessageId, updatedResponse);
+ merge(updatedResponse, responseMessageId);
+ }
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_SANDBOX_STARTING) {
+ effects.push({ type: 'sandbox-starting', toolCallId: event.data.tool_call_id });
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_PTC_TOOL_CALL) {
+ /** `runId` is the response message id (the run configurable's `run_id`), the same
+ * correlation the subagent path uses. */
+ effects.push({
+ type: 'ptc',
+ event: event.data,
+ parentMessageId: resolveResponseId(submission, event.data.runId),
+ });
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_SUBAGENT_UPDATE) {
+ const { phase } = event.data;
+ effects.push(
+ ...claimSubagentUpdate(state, event.data, resolveResponseId(submission, event.data.runId)),
+ );
+ if (phase === 'start' || phase === 'stop' || phase === 'error') {
+ const conversationId = [
+ submission?.userMessage?.conversationId,
+ submission?.initialResponse?.conversationId,
+ submission?.conversation?.conversationId,
+ ].find((id) => id && id !== Constants.NEW_CONVO && id !== Constants.PENDING_CONVO);
+ if (conversationId) effects.push({ type: 'subagent-index', conversationId });
+ }
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_SUMMARIZE_START) {
+ effects.push({ type: 'announce', message: 'summarize_started' });
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_SUMMARIZE_DELTA) {
+ const deltaData = event.data;
+ const runStep = state.steps.get(deltaData.id);
+ const responseMessageId = resolveResponseId(submission, runStep?.runId);
+ if (!runStep || !responseMessageId) {
+ bufferDelta(state, deltaData.id, event);
+ return effects;
+ }
+ const response = state.messages.get(responseMessageId);
+ if (response) {
+ state.messages.set(
+ responseMessageId,
+ applySummarizeDelta(response, runStep, deltaData, editPrefixOffset),
+ );
+ effects.push({ type: 'summary', messageId: responseMessageId, messages });
+ }
+ return effects;
+ }
+
+ if (event.event === StepEvents.ON_SUMMARIZE_COMPLETE) {
+ const completeData = event.data;
+ const completeRunStep = state.steps.get(completeData.id);
+ const completeMessageId = resolveResponseId(submission, completeRunStep?.runId);
+ const targetMessage = state.messages.get(completeMessageId);
+ if (!targetMessage) {
+ return effects;
+ }
+ /** Scoped to the owning step's slot when the step is known; see `finalizeSummaries`. */
+ const completeIndex = completeRunStep != null ? completeRunStep.index + editPrefixOffset : -1;
+ const finalized = finalizeSummaries(targetMessage, completeData, completeIndex);
+ if (finalized) {
+ effects.push({
+ type: 'announce',
+ message: completeData.error ? 'summarize_failed' : 'summarize_completed',
+ });
+ const currentMessages = submission.isRegenerate ? messages : ctx.getMessages() || [];
+ state.messages.set(completeMessageId, finalized);
+ ctx.setMessages(mergeResponseMessage(ctx, currentMessages, finalized, completeMessageId));
+ }
+ return effects;
+ }
+
+ const _exhaustive: never = event;
+ console.warn('Unhandled step event', (_exhaustive as StepEvent).event);
+ return effects;
+}