Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🔁 refactor: 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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;+}