From 98c35b648bea36ebec15f7457e10d25aaeec917b Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Mon, 12 Oct 2026 16:02:17 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=81=20refactor:=20Lift=20the=20Step=20?= =?UTF-8?q?Handler=20Into=20a=20Core=20reduceStep=20With=20an=20Effects=20?= =?UTF-8?q?Channel=20(#17000)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor: Lift the step handler branches into a core reduceStep The stepHandler branches move to @librechat/chat as reduceStep(state, event, ctx), with the per-run maps in a StreamState and every write outside the message list returned as a StepEffect. useStepHandler keeps the frame coalescing and applies the effects to the Jotai and Recoil stores. The equivalence spec runs a frozen copy of the previous hook against the new binding on each recorded sequence and compares every channel they write. * test: Pin the step reducer equivalence digests and drop the frozen handler * test: Load the step reducer from the built chat core * test: Type the equivalence fixtures to the event unions --- client/src/components/Chat/Subagents/state.ts | 6 +- .../SSE/__tests__/stepEquivalence.spec.ts | 548 ++++++++++ client/src/hooks/SSE/useStepHandler.ts | 994 ++---------------- e2e/specs/mock/scenarios/chat-package.spec.ts | 4 +- .../chat/src/core/__tests__/reducer.spec.ts | 236 +++++ packages/chat/src/core/index.ts | 1 + packages/chat/src/core/reducer.ts | 867 +++++++++++++++ 7 files changed, 1755 insertions(+), 901 deletions(-) create mode 100644 client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts create mode 100644 packages/chat/src/core/__tests__/reducer.spec.ts create mode 100644 packages/chat/src/core/reducer.ts diff --git a/client/src/components/Chat/Subagents/state.ts b/client/src/components/Chat/Subagents/state.ts index 3f396ec1bf..7f648e067b 100644 --- a/client/src/components/Chat/Subagents/state.ts +++ b/client/src/components/Chat/Subagents/state.ts @@ -473,11 +473,7 @@ export const subagentControlStateByTask = atomFamily< }); /** Stable identity for one subagent invocation in the parent conversation. */ -export const subagentProgressKey = ( - parentMessageId: string, - toolCallId: string, - partIndex: number, -) => `${parentMessageId}\u0000${toolCallId}\u0000${partIndex}`; +export { subagentProgressKey } from '@librechat/chat'; /** Progress state keyed by one concrete tool-call content-part occurrence. */ export const subagentProgressByToolCallId = atomFamily((_key: string) => diff --git a/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts b/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts new file mode 100644 index 0000000000..e8d636a005 --- /dev/null +++ b/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts @@ -0,0 +1,548 @@ +import React from 'react'; +import { createHash } from 'crypto'; +import { createStore, Provider } from 'jotai'; +import { RecoilRoot, useRecoilCallback } from 'recoil'; +import { renderHook, act } from '@testing-library/react'; +import { + Constants, + StepTypes, + StepEvents, + ContentTypes, + ToolCallTypes, +} from 'librechat-data-provider'; +import type { + Agents, + TMessage, + EventSubmission, + PtcToolCallEvent, + SubagentUpdateEvent, + TMessageContentParts, +} from 'librechat-data-provider'; +import type { StepEvent } from '@librechat/chat'; +import { + subagentProgressKey, + subagentProgressByToolCallId, + takeRegisteredSubagentProgressKeys, + subagentParentStreamOpenByToolCallId, +} from '~/components/Chat/Subagents/state'; +import { ptcTraceByToolCallId, ptcTraceKey } from '~/store/ptc'; +import { sandboxStartingByToolCallId } from '~/store/sandbox'; +import useStepHandler from '~/hooks/SSE/useStepHandler'; + +/** + * Equivalence table for the step reducer. Each row is an event sequence shaped like a recorded + * agent stream, with the frame boundaries and run-boundary calls the SSE hooks make. The digest + * pins what the pre-reducer `stepHandler` produced for the row on every channel it writes: each + * message-list write, each announcement, each host callback, and the live-status atoms. The + * digests were recorded by running that handler side by side with this binding and requiring + * equal logs, so a row whose digest moves changed observable behavior. + */ + +const PRELIM: string = Constants.USE_PRELIM_RESPONSE_MESSAGE_ID; +const SUBAGENT: string = Constants.SUBAGENT; + +type Step = + | StepEvent + | { frame: true } + | { sync: TMessage } + | { call: 'clearStepMaps' | 'flushPendingDeltas' | 'cancelPendingDeltaFlush' | 'prunePtcTraces' }; + +type Row = { + name: string; + submission?: Partial; + cache?: TMessage[]; + steps: Step[]; + sandbox?: string[]; + ptc?: Array<[string, string]>; + subagents?: string[]; + digest: string; +}; + +const user = (overrides: Partial = {}): 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 => ({ + 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 = {}, +): 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): 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): 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; + 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, + 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(); + 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, + }; + 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) => + createHash('sha256').update(JSON.stringify(log)).digest('hex').slice(0, 16); + +describe('step reducer equivalence', () => { + beforeEach(() => { + jest.spyOn(Date, 'now').mockReturnValue(1_000_000); + }); + + it.each(rows.map((row) => [row.name, row] as const))('%s', (_name, row) => { + const log = run(useStepHandler, row); + expect( + log.writes.length + log.callbacks.length + Object.keys(log.atoms).length, + ).toBeGreaterThan(0); + expect(digest(log)).toBe(row.digest); + }); +}); diff --git a/client/src/hooks/SSE/useStepHandler.ts b/client/src/hooks/SSE/useStepHandler.ts index a9668a4799..300e5b81be 100644 --- a/client/src/hooks/SSE/useStepHandler.ts +++ b/client/src/hooks/SSE/useStepHandler.ts @@ -2,35 +2,20 @@ import { useCallback, useRef } from 'react'; import { useStore } from 'jotai'; import { useRecoilCallback } from 'recoil'; import { - Constants, - StepTypes, - StepEvents, - ContentTypes, - getToolTimingDurations, -} from 'librechat-data-provider'; -import { - applyReasoningDelta, - applyToolCallCompleted, - isSkillAuthoringToolCall, - applyToolCallDelta, - applySummarizeDelta, - applyRunStepClosed, - applyToolCallsStep, - applyMessageDelta, - finalizeSummaries, - applyAgentUpdate, - applySummaryStep, - getEditPrefix, + reduceStep, + flushSummary, + flushResponses, + resetStreamState, + syncStreamMessage, + createStreamState, } from '@librechat/chat'; import type { - Agents, TMessage, EventSubmission, - TMessageContentParts, SubagentUpdateEvent, - SandboxStartingEvent, PtcToolCallEvent, } from 'librechat-data-provider'; +import type { StepEvent, StepEffect, StepContext, StreamState } from '@librechat/chat'; import type { SetterOrUpdater } from 'recoil'; import type { AnnounceOptions } from '~/common'; import { @@ -42,7 +27,6 @@ import { subagentParentStreamOpenByToolCallId, subagentProgressByToolCallId, takeRegisteredSubagentProgressKeys, - subagentProgressKey, } from '~/components/Chat/Subagents/state'; import { sandboxStartingByToolCallId, @@ -68,25 +52,6 @@ type TUseStepHandler = { onSubagentIndexChange?: (conversationId: string) => void; }; -const toolTimingKey = (stepId: string, callId: string) => `${stepId}\u0000${callId}`; - -type TStepEvent = - | { event: StepEvents.ON_RUN_STEP; data: Agents.RunStep } - | { event: StepEvents.ON_AGENT_UPDATE; data: Agents.AgentUpdate } - | { event: StepEvents.ON_MESSAGE_DELTA; data: Agents.MessageDeltaEvent } - | { event: StepEvents.ON_REASONING_DELTA; data: Agents.ReasoningDeltaEvent } - | { event: StepEvents.ON_RUN_STEP_DELTA; data: Agents.RunStepDeltaEvent } - | { event: StepEvents.ON_TOOL_CALLS_DISPATCHED; data: Agents.ToolCallsDispatchedEvent } - | { event: StepEvents.ON_TOOL_PREPARATION; data: Agents.ToolPreparationMarker } - | { event: StepEvents.ON_RUN_STEP_COMPLETED; data: { result: Agents.ToolEndEvent } } - | { event: StepEvents.ON_RUN_STEP_CLOSED; data: Agents.RunStepClosedEvent } - | { event: StepEvents.ON_SUMMARIZE_START; data: Agents.SummarizeStartEvent } - | { event: StepEvents.ON_SUMMARIZE_DELTA; data: Agents.SummarizeDeltaEvent } - | { event: StepEvents.ON_SUMMARIZE_COMPLETE; data: Agents.SummarizeCompleteEvent } - | { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent } - | { event: StepEvents.ON_SANDBOX_STARTING; data: SandboxStartingEvent } - | { event: StepEvents.ON_PTC_TOOL_CALL; data: PtcToolCallEvent }; - export default function useStepHandler({ setMessages, getMessages, @@ -96,15 +61,7 @@ export default function useStepHandler({ onSubagentIndexChange, }: TUseStepHandler) { const subagentStore = useStore(); - const toolCallIdMap = useRef(new Map()); - const firstFragmentByCall = useRef(new Map()); - const firstFragmentByStep = useRef(new Map()); - const dispatchedByCall = useRef(new Map()); - const completedByCall = useRef(new Map()); - const messageMap = useRef(new Map()); - const stepMap = useRef(new Map()); - /** Buffer for deltas that arrive before their corresponding run step */ - const pendingDeltaBuffer = useRef(new Map()); + const stream = useRef(createStreamState()); /** Coalesces rapid-fire summarize delta renders into a single rAF frame */ const summarizeDeltaRaf = useRef(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()); 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()); - const claimedSubagentInvocationKeys = useRef(new Set()); - /** - * 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(), - ); - 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(); - 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; + /** + * 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); }; - 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; - } + /** 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); + }, + [], + ); - /** 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; + 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; - } - } - 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; + case 'summary': + if (summarizeDeltaRaf.current == null) { + summarizeDeltaRaf.current = requestAnimationFrame(() => { + summarizeDeltaRaf.current = null; + flushSummary(stream.current, ctx, effect.messageId, effect.messages); + }); } - 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; + 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; } - deltaFlushScheduled.current = true; - messageDeltaRaf.current = requestAnimationFrame(flush); - }; - let parentMessageId = - submission.isRegenerate && submission.initialResponse?.parentMessageId - ? submission.initialResponse.parentMessageId - : userMessage.messageId; + } + }, + [ + announcePolite, + setSandboxStarting, + clearSandboxStarting, + onSkillAuthoringComplete, + applyPtcToolCall, + applySubagentProgress, + onSubagentIndexChange, + scheduleCoalescedMessagesFlush, + ], + ); + const stepHandler = useCallback( + (stepEvent: StepEvent, submission: EventSubmission) => { const currentTime = Date.now(); if (currentTime - lastAnnouncementTimeRef.current > MESSAGE_UPDATE_INTERVAL) { announcePolite({ message: 'composing', isStatus: true }); lastAnnouncementTimeRef.current = currentTime; } - - /** 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 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)); - } - } else { - const _exhaustive: never = stepEvent; - console.warn('Unhandled step event', (_exhaustive as TStepEvent).event); - } + const ctx: StepContext = { submission, getMessages, setMessages }; + applyEffects(reduceStep(stream.current, stepEvent, ctx), ctx); }, - [ - getMessages, - lastAnnouncementTimeRef, - announcePolite, - setMessages, - getCurrentMessages, - applySubagentUpdate, - onSubagentIndexChange, - setSandboxStarting, - clearSandboxStarting, - applyPtcToolCall, - onSkillAuthoringComplete, - ], + [getMessages, setMessages, announcePolite, applyEffects, lastAnnouncementTimeRef], ); /** Cancels a queued delta flush so it can't overwrite a terminal write: * once a final handler has written the server's authoritative message, a - * trailing frame reading the older streaming copy from `messageMap` must + * trailing frame reading the older streaming copy from the stream state must * never land on top of it. */ const cancelPendingDeltaFlush = useCallback(() => { if (messageDeltaRaf.current != null) { @@ -1160,17 +382,7 @@ export default function useStepHandler({ summarizeDeltaRaf.current = null; } cancelPendingDeltaFlush(); - toolCallIdMap.current.clear(); - firstFragmentByCall.current.clear(); - firstFragmentByStep.current.clear(); - dispatchedByCall.current.clear(); - completedByCall.current.clear(); - messageMap.current.clear(); - stepMap.current.clear(); - pendingDeltaBuffer.current.clear(); - subagentRunToInvocationKey.current.clear(); - claimedSubagentInvocationKeys.current.clear(); - pendingSubagentBuffer.current.clear(); + resetStreamState(stream.current); closeParentSubagentStreams(); /** Unlike subagent atoms below, sandbox-starting flags are transient * status with no audit value; reset them at this boundary so an @@ -1188,25 +400,19 @@ export default function useStepHandler({ }, [cancelPendingDeltaFlush, closeParentSubagentStreams, resetSandboxAtoms]); /** - * Sync a message into the step handler's messageMap. + * Sync a message into the step handler's streaming copy. * Call this after receiving sync event to ensure subsequent deltas * build on the synced content, not stale content. */ const syncStepMessage = useCallback( (message: TMessage) => { - if (!message?.messageId) return; - messageMap.current.set(message.messageId, { ...message }); - const ready = [...pendingSubagentBuffer.current.entries()].filter( - ([, pending]) => pending.parentMessageId === message.messageId, - ); - for (const [subagentRunId, pending] of ready) { - pendingSubagentBuffer.current.delete(subagentRunId); - for (const event of pending.events) { - applySubagentUpdate(event, message.messageId); + for (const effect of syncStreamMessage(stream.current, message)) { + if (effect.type === 'subagent') { + applySubagentProgress(effect.invocationKey, effect.events); } } }, - [applySubagentUpdate], + [applySubagentProgress], ); return { diff --git a/e2e/specs/mock/scenarios/chat-package.spec.ts b/e2e/specs/mock/scenarios/chat-package.spec.ts index ff2d8162a6..4d9217c137 100644 --- a/e2e/specs/mock/scenarios/chat-package.spec.ts +++ b/e2e/specs/mock/scenarios/chat-package.spec.ts @@ -247,7 +247,7 @@ test.describe('the built @librechat/chat package', () => { return resolveFilename.call(this, request, ...rest); }; const core = require('@librechat/chat'); - const names = ['createSSETransport', 'normalizeFrame', 'applyMessageDelta', 'applyToolCallDelta', 'isAnsweredAskUserQuestionPart']; + const names = ['createSSETransport', 'normalizeFrame', 'applyMessageDelta', 'applyToolCallDelta', 'isAnsweredAskUserQuestionPart', 'reduceStep', 'createStreamState']; const answer = { entry: require.resolve('@librechat/chat'), cjs: {}, esm: {} }; for (const name of names) answer.cjs[name] = typeof core[name]; import('@librechat/chat').then((esm) => { @@ -264,7 +264,7 @@ test.describe('the built @librechat/chat package', () => { }; expect(answer.entry).toBe(resolve(dist, 'index.cjs')); for (const exports of [answer.cjs, answer.esm]) { - expect(Object.values(exports)).toEqual(Array(5).fill('function')); + expect(Object.values(exports)).toEqual(Array(7).fill('function')); } }); }); diff --git a/packages/chat/src/core/__tests__/reducer.spec.ts b/packages/chat/src/core/__tests__/reducer.spec.ts new file mode 100644 index 0000000000..65ffaa8075 --- /dev/null +++ b/packages/chat/src/core/__tests__/reducer.spec.ts @@ -0,0 +1,236 @@ +import { + Constants, + StepTypes, + StepEvents, + ContentTypes, + ToolCallTypes, +} from 'librechat-data-provider'; +import type { Agents, TMessage, EventSubmission } from 'librechat-data-provider'; +import type { StepEvent, StepContext } from '../reducer'; +import { + reduceStep, + flushResponses, + resetStreamState, + syncStreamMessage, + createStreamState, + subagentProgressKey, +} from '../reducer'; + +const user: TMessage = { + messageId: 'user-1', + conversationId: 'conv-1', + parentMessageId: Constants.NO_PARENT as string, + isCreatedByUser: true, + text: 'Hello', + sender: 'User', +}; + +const createContext = () => { + let messages: TMessage[] = [user]; + const writes: TMessage[][] = []; + const submission = { + userMessage: user, + isRegenerate: false, + messages: [], + conversation: { conversationId: 'conv-1' }, + initialResponse: { ...user, messageId: 'resp-1', isCreatedByUser: false, content: [] }, + } as unknown as EventSubmission; + const ctx: StepContext = { + submission, + getMessages: () => messages, + setMessages: (next) => { + messages = next; + writes.push(next); + }, + }; + return { ctx, writes, read: () => messages }; +}; + +const textStep = (id: string, index: number): StepEvent => ({ + event: StepEvents.ON_RUN_STEP, + data: { + id, + runId: 'resp-1', + index, + type: StepTypes.MESSAGE_CREATION, + stepDetails: { type: StepTypes.MESSAGE_CREATION, message_creation: { message_id: id } }, + usage: null, + }, +}); + +const toolStep = (id: string, index: number, callId: string, name: string): StepEvent => ({ + event: StepEvents.ON_RUN_STEP, + data: { + id, + runId: 'resp-1', + index, + type: StepTypes.TOOL_CALLS, + stepDetails: { + type: StepTypes.TOOL_CALLS, + tool_calls: [{ id: callId, name, args: '', type: ToolCallTypes.TOOL_CALL }], + }, + usage: null, + }, +}); + +const text = (id: string, value: string): StepEvent => ({ + event: StepEvents.ON_MESSAGE_DELTA, + data: { id, delta: { content: [{ type: ContentTypes.TEXT, text: value }] } }, +}); + +const responseContent = (messages: TMessage[]) => + messages.find((message) => message.messageId === 'resp-1')?.content; + +describe('reduceStep', () => { + it('places each part at its step index, leaving holes rather than shifting', () => { + const state = createStreamState(); + const { ctx, read } = createContext(); + + reduceStep(state, textStep('s2', 2), ctx); + const effects = reduceStep(state, text('s2', 'later'), ctx); + reduceStep(state, textStep('s0', 0), ctx); + reduceStep(state, text('s0', 'first'), ctx); + flushResponses(state, ctx, ['resp-1'], read()); + + expect(effects).toEqual([{ type: 'flush', messageId: 'resp-1', messages: expect.any(Array) }]); + const content = responseContent(read()); + expect(content).toHaveLength(3); + expect(content?.[0]).toEqual({ type: ContentTypes.TEXT, text: 'first' }); + expect(content?.[1]).toBeUndefined(); + expect(content?.[2]).toEqual({ type: ContentTypes.TEXT, text: 'later' }); + }); + + it('holds deltas for an unseen step and replays them, in order, when it opens', () => { + const state = createStreamState(); + const { ctx, writes, read } = createContext(); + + expect(reduceStep(state, text('s0', 'a'), ctx)).toEqual([]); + expect(reduceStep(state, text('s0', 'b'), ctx)).toEqual([]); + expect(writes).toHaveLength(0); + + const effects = reduceStep(state, textStep('s0', 0), ctx); + expect(effects.map((effect) => effect.type)).toEqual(['flush', 'flush']); + flushResponses(state, ctx, ['resp-1'], read()); + expect(responseContent(read())?.[0]).toEqual({ type: ContentTypes.TEXT, text: 'ab' }); + expect(state.pendingDeltas.size).toBe(0); + }); + + it('reports side channels as effects without touching the message list', () => { + const state = createStreamState(); + const { ctx, writes } = createContext(); + + expect( + reduceStep( + state, + { event: StepEvents.ON_SANDBOX_STARTING, data: { tool_call_id: 'call-1' } }, + ctx, + ), + ).toEqual([{ type: 'sandbox-starting', toolCallId: 'call-1' }]); + expect( + reduceStep( + state, + { + event: StepEvents.ON_SUMMARIZE_START, + data: { agentId: 'a' } as Agents.SummarizeStartEvent, + }, + ctx, + ), + ).toEqual([{ type: 'announce', message: 'summarize_started' }]); + const ptc = { + tool_call_id: 'call-1', + call_id: 'call-1:0', + name: 'read_file', + status: 'running' as const, + runId: Constants.USE_PRELIM_RESPONSE_MESSAGE_ID as string, + }; + expect(reduceStep(state, { event: StepEvents.ON_PTC_TOOL_CALL, data: ptc }, ctx)).toEqual([ + { type: 'ptc', event: ptc, parentMessageId: 'resp-1' }, + ]); + expect(writes).toHaveLength(0); + }); + + it('settles the sandbox signal and reports a skill authored by a completed call', () => { + const state = createStreamState(); + const { ctx } = createContext(); + reduceStep(state, toolStep('t1', 0, 'call-1', 'create_file'), ctx); + + const effects = reduceStep( + state, + { + event: StepEvents.ON_RUN_STEP_COMPLETED, + data: { + result: { + id: 't1', + index: 0, + tool_call: { + id: 'call-1', + name: 'create_file', + args: '{"file_path":"skills/demo/SKILL.md"}', + output: 'ok', + }, + } as never, + }, + }, + ctx, + ); + + expect(effects).toEqual([ + { type: 'sandbox-settled', toolCallId: 'call-1' }, + { type: 'skill-authored' }, + ]); + }); + + it('buffers a subagent envelope until a sync shows its parent call', () => { + const state = createStreamState(); + const { ctx } = createContext(); + const update = { + runId: 'resp-1', + subagentRunId: 'child-1', + subagentType: 'self', + subagentAgentId: 'child', + parentAgentId: 'parent', + phase: 'start' as const, + label: 'started', + timestamp: '2026-10-11T00:00:00.000Z', + }; + + expect(reduceStep(state, { event: StepEvents.ON_SUBAGENT_UPDATE, data: update }, ctx)).toEqual([ + { type: 'subagent-index', conversationId: 'conv-1' }, + ]); + + const effects = syncStreamMessage(state, { + ...user, + messageId: 'resp-1', + isCreatedByUser: false, + content: [ + { type: ContentTypes.TEXT, text: 'x' }, + { + type: ContentTypes.TOOL_CALL, + tool_call: { id: 'call-sub', name: Constants.SUBAGENT, args: '{}', type: 'tool_call' }, + }, + ] as TMessage['content'], + }); + + expect(effects).toEqual([ + { + type: 'subagent', + invocationKey: subagentProgressKey('resp-1', 'call-sub', 1), + events: [update], + }, + ]); + expect(state.pendingSubagents.size).toBe(0); + }); + + it('forgets every step, response and buffer on reset', () => { + const state = createStreamState(); + const { ctx } = createContext(); + reduceStep(state, text('s9', 'held'), ctx); + reduceStep(state, textStep('s0', 0), ctx); + + resetStreamState(state); + + expect(state.steps.size + state.messages.size + state.pendingDeltas.size).toBe(0); + expect(reduceStep(state, text('s0', 'late'), ctx)).toEqual([]); + expect(state.pendingDeltas.get('s0')).toHaveLength(1); + }); +}); diff --git a/packages/chat/src/core/index.ts b/packages/chat/src/core/index.ts index e1a4841011..a76551ae67 100644 --- a/packages/chat/src/core/index.ts +++ b/packages/chat/src/core/index.ts @@ -1,4 +1,5 @@ export * from './ask'; export * from './steps'; export * from './types'; +export * from './reducer'; export * from './transport'; diff --git a/packages/chat/src/core/reducer.ts b/packages/chat/src/core/reducer.ts new file mode 100644 index 0000000000..89bdafba33 --- /dev/null +++ b/packages/chat/src/core/reducer.ts @@ -0,0 +1,867 @@ +import { + Constants, + StepTypes, + StepEvents, + ContentTypes, + getToolTimingDurations, +} from 'librechat-data-provider'; +import type { + Agents, + TMessage, + EventSubmission, + PtcToolCallEvent, + SubagentUpdateEvent, + SandboxStartingEvent, + TMessageContentParts, +} from 'librechat-data-provider'; +import { + getEditPrefix, + applyAgentUpdate, + applySummaryStep, + applyMessageDelta, + finalizeSummaries, + applyRunStepClosed, + applyToolCallsStep, + applyToolCallDelta, + applyReasoningDelta, + applySummarizeDelta, + applyToolCallCompleted, + isSkillAuthoringToolCall, +} from './steps'; + +/** + * The step reducer behind `useStepHandler`: folds one agent step event into the response message + * it targets and reports every write outside the message list as an effect. + * + * Message writes go through `StepContext.setMessages` as they happen, because later writes in the + * same event read the list back through `getMessages`. Everything else (live-status stores, + * announcements, cache invalidation, coalesced flushes) is returned in order for the binding. + * + * Invariant: a part's position in `message.content` is its step index plus the retained edit + * prefix. Nothing here splices content mid-stream. + */ + +export type StepEvent = + | { event: StepEvents.ON_RUN_STEP; data: Agents.RunStep } + | { event: StepEvents.ON_AGENT_UPDATE; data: Agents.AgentUpdate } + | { event: StepEvents.ON_MESSAGE_DELTA; data: Agents.MessageDeltaEvent } + | { event: StepEvents.ON_REASONING_DELTA; data: Agents.ReasoningDeltaEvent } + | { event: StepEvents.ON_RUN_STEP_DELTA; data: Agents.RunStepDeltaEvent } + | { event: StepEvents.ON_TOOL_CALLS_DISPATCHED; data: Agents.ToolCallsDispatchedEvent } + | { event: StepEvents.ON_TOOL_PREPARATION; data: Agents.ToolPreparationMarker } + | { event: StepEvents.ON_RUN_STEP_COMPLETED; data: { result: Agents.ToolEndEvent } } + | { event: StepEvents.ON_RUN_STEP_CLOSED; data: Agents.RunStepClosedEvent } + | { event: StepEvents.ON_SUMMARIZE_START; data: Agents.SummarizeStartEvent } + | { event: StepEvents.ON_SUMMARIZE_DELTA; data: Agents.SummarizeDeltaEvent } + | { event: StepEvents.ON_SUMMARIZE_COMPLETE; data: Agents.SummarizeCompleteEvent } + | { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent } + | { event: StepEvents.ON_SANDBOX_STARTING; data: SandboxStartingEvent } + | { event: StepEvents.ON_PTC_TOOL_CALL; data: PtcToolCallEvent }; + +/** + * Side channels of one step event, in the order the event produced them. + * + * `flush` and `summary` ask the binding to merge the response into the list later (deltas are + * coalesced per frame); `messages` is the list the event read, which the flush merges onto. + */ +export type StepEffect = + | { type: 'flush'; messageId: string; messages: TMessage[] } + | { type: 'summary'; messageId: string; messages: TMessage[] } + | { type: 'announce'; message: 'summarize_started' | 'summarize_completed' | 'summarize_failed' } + | { type: 'sandbox-starting'; toolCallId: string } + | { type: 'sandbox-settled'; toolCallId?: string } + | { type: 'skill-authored' } + | { type: 'ptc'; event: PtcToolCallEvent; parentMessageId: string } + | { type: 'subagent'; invocationKey: string; events: SubagentUpdateEvent[] } + | { type: 'subagent-index'; conversationId: string }; + +/** The message list the reducer reads and writes; the React Query cache in the app. */ +export type StepContext = { + submission: EventSubmission; + getMessages: () => TMessage[] | undefined; + setMessages: (messages: TMessage[]) => void; +}; + +type PendingSubagent = { parentMessageId: string; events: SubagentUpdateEvent[] }; + +/** Per-run bookkeeping. Mutable by design: deltas arrive per token. */ +export type StreamState = { + /** Authoritative streaming copy of each response, ahead of the cache while a flush is queued. */ + messages: Map; + steps: Map; + toolCallIds: Map; + firstFragmentByCall: Map; + firstFragmentByStep: Map; + dispatchedByCall: Map; + completedByCall: Map; + /** Deltas that arrived before their run step, replayed when it lands. */ + pendingDeltas: Map; + /** + * `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; + claimedInvocations: Set; + /** Subagent envelopes that arrived before their parent tool call was in `messages`. */ + pendingSubagents: Map; +}; + +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(); + 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, + 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; +}