diff --git a/client/src/hooks/SSE/__tests__/steps.spec.ts b/client/src/hooks/SSE/__tests__/steps.spec.ts new file mode 100644 index 0000000000..fd89253e74 --- /dev/null +++ b/client/src/hooks/SSE/__tests__/steps.spec.ts @@ -0,0 +1,456 @@ +import { StepTypes, ContentTypes } from 'librechat-data-provider'; +import type { + Agents, + TMessage, + EventSubmission, + SummaryContentPart, + TMessageContentParts, +} from 'librechat-data-provider'; +import { + calculateContentIndex, + applyReasoningDelta, + applySummarizeDelta, + finalizeSummaries, + applyMessageDelta, + applySummaryStep, + applyAgentUpdate, + getEditPrefix, + updateContent, +} from '../steps'; + +const RUN_ID = 'response-1'; + +const createResponse = (content: TMessageContentParts[] = []): TMessage => + ({ + messageId: RUN_ID, + conversationId: 'convo-1', + parentMessageId: 'user-1', + isCreatedByUser: false, + text: '', + content, + }) as TMessage; + +const messageStep = ( + id: string, + index: number, + overrides: Partial = {}, +): Agents.RunStep => ({ + id, + index, + runId: RUN_ID, + type: StepTypes.MESSAGE_CREATION, + stepDetails: { type: StepTypes.MESSAGE_CREATION, message_creation: { message_id: id } }, + ...overrides, +}); + +const textDelta = (id: string, text: string): Agents.MessageDeltaEvent => ({ + id, + delta: { content: [{ type: ContentTypes.TEXT, text }] }, +}); + +const thinkDelta = (id: string, think: string): Agents.ReasoningDeltaEvent => ({ + id, + delta: { content: [{ type: ContentTypes.THINK, think }] }, +}); + +const typesOf = (message: TMessage) => (message.content ?? []).map((part) => part?.type); + +/** + * The invariant every reducer keeps: each step's part sits at `step.index + offset`, whatever + * order the events arrived in. + */ +const expectStepPositions = ( + message: TMessage, + steps: Array<[Agents.RunStep, ContentTypes]>, + offset = 0, +) => { + for (const [step, type] of steps) { + expect(message.content?.[step.index + offset]?.type).toBe(type); + } +}; + +const streamText = (message: TMessage, step: Agents.RunStep, chunks: string[], offset = 0) => + chunks.reduce( + (current, chunk) => applyMessageDelta(current, step, textDelta(step.id, chunk), offset).message, + message, + ); + +describe('steps', () => { + describe('text deltas', () => { + it('appends a recorded sequence of chunks into the step slot', () => { + const step = messageStep('step-text', 0); + const result = streamText(createResponse(), step, ['Hel', 'lo', ', world']); + + expect(result.content).toEqual([{ type: ContentTypes.TEXT, text: 'Hello, world' }]); + expectStepPositions(result, [[step, ContentTypes.TEXT]]); + }); + + it('applies every part of a multi-part delta in order', () => { + const step = messageStep('step-text', 0); + const result = applyMessageDelta( + createResponse(), + step, + { + id: step.id, + delta: { + content: [ + { type: ContentTypes.TEXT, text: 'a' }, + null as unknown as Agents.MessageContentComplex, + { type: ContentTypes.TEXT, text: 'b' }, + ], + }, + }, + 0, + ); + + expect(result.updated).toBe(true); + expect(result.message.content).toEqual([{ type: ContentTypes.TEXT, text: 'ab' }]); + }); + + it('reports no update and returns the same message for an empty delta', () => { + const response = createResponse(); + const result = applyMessageDelta( + response, + messageStep('step-text', 0), + { id: 'step-text', delta: {} }, + 0, + ); + + expect(result).toEqual({ message: response, updated: false, foldedEditPrefix: false }); + expect(result.message).toBe(response); + }); + + it('stamps the step phase on text parts', () => { + const step = messageStep('step-final', 0, { + stepDetails: { + type: StepTypes.MESSAGE_CREATION, + message_creation: { message_id: 'm', phase: 'final_answer' }, + }, + }); + const result = streamText(createResponse(), step, ['done']); + + expect(result.content?.[0]).toEqual({ + type: ContentTypes.TEXT, + text: 'done', + phase: 'final_answer', + }); + }); + + it('streams into a message step that carries no message_creation details', () => { + const step = messageStep('step-bare', 0, { + stepDetails: { type: StepTypes.MESSAGE_CREATION } as Agents.StepDetails, + }); + const result = streamText(createResponse(), step, ['still streams']); + + expect(result.content).toEqual([{ type: ContentTypes.TEXT, text: 'still streams' }]); + }); + + it('keeps slots in place when a later step streams before an earlier one', () => { + const first = messageStep('step-a', 0); + const second = messageStep('step-b', 2); + let result = streamText(createResponse(), second, ['second']); + expect(result.content?.[0]).toBeUndefined(); + expect(result.content?.[1]).toBeUndefined(); + + result = streamText(result, first, ['first']); + + expectStepPositions(result, [ + [first, ContentTypes.TEXT], + [second, ContentTypes.TEXT], + ]); + expect(result.content?.[1]).toBeUndefined(); + expect(result.content).toHaveLength(3); + }); + + it('does not dedupe a redelivered chunk; the transport owns delivery', () => { + const step = messageStep('step-text', 0); + const result = streamText(createResponse(), step, ['once', 'once']); + + expect(result.content).toEqual([{ type: ContentTypes.TEXT, text: 'onceonce' }]); + }); + + it('never overwrites a slot holding a different part type', () => { + const warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined); + const opened = createResponse([ + { + type: ContentTypes.TOOL_CALL, + tool_call: { id: 'call-1', name: 'search', args: '', type: 'tool_call' }, + } as TMessageContentParts, + ]); + + const result = streamText(opened, messageStep('step-text', 0), ['collide']); + + expect(result).toBe(opened); + expect(typesOf(result)).toEqual([ContentTypes.TOOL_CALL]); + expect(warn).toHaveBeenCalledWith('Content type mismatch', expect.any(Object)); + warn.mockRestore(); + }); + + it('propagates agent and group metadata without mutating the previous part', () => { + const step = messageStep('step-text', 0, { agentId: 'agent-a', groupId: 2 }); + const before = streamText(createResponse(), messageStep('step-text', 0), ['a']); + const previousPart = before.content?.[0]; + + const result = streamText(before, step, ['b']); + + expect(result.content?.[0]).toMatchObject({ text: 'ab', agentId: 'agent-a', groupId: 2 }); + expect(previousPart).toEqual({ type: ContentTypes.TEXT, text: 'a' }); + }); + }); + + describe('reasoning deltas', () => { + it('streams reasoning then text into consecutive slots', () => { + const think = messageStep('step-think', 0); + const text = messageStep('step-text', 1); + let result = createResponse(); + for (const chunk of ['Let me ', 'think']) { + result = applyReasoningDelta(result, think, thinkDelta(think.id, chunk), 0).message; + } + result = streamText(result, text, ['Answer']); + + expect(result.content?.[0]).toMatchObject({ + type: ContentTypes.THINK, + think: 'Let me think', + reasoning_label_step_id: think.id, + }); + expectStepPositions(result, [ + [think, ContentTypes.THINK], + [text, ContentTypes.TEXT], + ]); + }); + + it('resets the label domain when a different step reuses a THINK slot', () => { + const labelled = createResponse([ + { + type: ContentTypes.THINK, + think: 'old', + reasoning_label: 'Planning', + reasoning_label_revision: 3, + reasoning_label_step_id: 'step-old', + } as TMessageContentParts, + ]); + + const result = applyReasoningDelta( + labelled, + messageStep('step-new', 0), + thinkDelta('step-new', ' more'), + 0, + ).message; + + expect(result.content?.[0]).toStrictEqual({ + type: ContentTypes.THINK, + think: 'old more', + reasoning_label_step_id: 'step-new', + }); + }); + + it('stamps a THINK slot streamed on the message channel once it exists', () => { + const step = messageStep('step-think', 0); + const delta = (think: string): Agents.MessageDeltaEvent => ({ + id: step.id, + delta: { content: [{ type: ContentTypes.THINK, think }] }, + }); + const first = applyMessageDelta(createResponse(), step, delta('h'), 0).message; + const second = applyMessageDelta(first, step, delta('m'), 0).message; + + expect(first.content?.[0]).toEqual({ type: ContentTypes.THINK, think: 'h' }); + expect(second.content?.[0]).toEqual({ + type: ContentTypes.THINK, + think: 'hm', + reasoning_label_step_id: step.id, + }); + }); + }); + + describe('edit prefix', () => { + const prefix = [ + { type: ContentTypes.TEXT, text: 'kept' }, + { type: ContentTypes.TEXT, text: 'kept tail' }, + ] as TMessageContentParts[]; + const submission = (overrides: Partial = {}) => + ({ + editedContent: { index: 1, text: 'kept tail', type: ContentTypes.TEXT }, + editPrefixLength: 2, + initialResponse: createResponse(prefix), + ...overrides, + }) as EventSubmission; + + it('offsets by the captured prefix length, not the live content length', () => { + expect(getEditPrefix(submission()).editPrefixOffset).toBe(2); + expect( + getEditPrefix( + submission({ editPrefixLength: undefined, initialResponse: createResponse() }), + ).editPrefixOffset, + ).toBe(0); + }); + + it('drops the offset once a resume sync cleared the prefix', () => { + expect(getEditPrefix(submission({ editPrefixCleared: true }))).toEqual({ + initialContent: [], + editPrefixOffset: 0, + }); + expect(getEditPrefix({ initialResponse: createResponse() } as EventSubmission)).toEqual({ + initialContent: [], + editPrefixOffset: 0, + }); + }); + + it('folds the first continued text into the last prefix part and reports it', () => { + const step = messageStep('step-text', 0); + const result = applyMessageDelta(createResponse(prefix), step, textDelta(step.id, '!'), 2); + + expect(result.foldedEditPrefix).toBe(true); + expect(result.message.content).toEqual([ + { type: ContentTypes.TEXT, text: 'kept' }, + { type: ContentTypes.TEXT, text: 'kept tail!' }, + ]); + }); + + it('does not fold across a phase boundary', () => { + expect(calculateContentIndex(0, 2, ContentTypes.TEXT, prefix, 'final_answer')).toBe(2); + expect(calculateContentIndex(0, 2, ContentTypes.TEXT, prefix)).toBe(1); + expect(calculateContentIndex(0, 2, ContentTypes.TOOL_CALL, prefix)).toBe(2); + }); + + it('places later steps after the prefix', () => { + const think = messageStep('step-think', 1); + const result = applyReasoningDelta( + createResponse(prefix), + think, + thinkDelta(think.id, 'next'), + 2, + ).message; + + expect(typesOf(result)).toEqual([ + ContentTypes.TEXT, + ContentTypes.TEXT, + undefined, + ContentTypes.THINK, + ]); + expectStepPositions(result, [[think, ContentTypes.THINK]], 2); + }); + }); + + describe('image parts', () => { + it('holds an image slot without letting text overwrite it', () => { + const warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined); + const image = createResponse([ + { type: ContentTypes.IMAGE_URL, image_url: { url: 'https://x/y.png' } }, + ] as TMessageContentParts[]); + + const result = updateContent(image, 0, { + type: ContentTypes.IMAGE_URL, + image_url: 'https://x/y.png', + } as Agents.MessageContentComplex); + const collided = streamText(result, messageStep('step-text', 0), ['no']); + + expect(result.content?.[0]).toEqual(image.content?.[0]); + expect(collided).toBe(result); + warn.mockRestore(); + }); + }); + + describe('agent updates', () => { + it('writes the handoff marker at its index with default group metadata', () => { + const event: Agents.AgentUpdate = { + type: ContentTypes.AGENT_UPDATE, + agent_update: { index: 1, runId: RUN_ID, agentId: 'agent-b' }, + }; + + const result = applyAgentUpdate(createResponse(), event, 0); + + expect(result.content?.[1]).toEqual({ + type: ContentTypes.AGENT_UPDATE, + agent_update: event.agent_update, + agentId: 'agent-b', + groupId: 1, + }); + expect(applyAgentUpdate(result, event, 0).content).toEqual(result.content); + }); + }); + + describe('summaries', () => { + const summarize = messageStep('step-summary', 1, { + summary: { + type: ContentTypes.SUMMARY, + content: [], + model: 'model-a', + provider: 'provider-a', + } as SummaryContentPart, + }); + const summaryDelta = (text: string): Agents.SummarizeDeltaEvent => ({ + id: summarize.id, + delta: { + summary: { + type: ContentTypes.SUMMARY, + content: [{ type: ContentTypes.TEXT, text }], + } as SummaryContentPart, + }, + }); + + const streamSummary = () => { + let message = applySummaryStep(createResponse(), summarize, 0); + for (const chunk of ['Earlier, ', 'we talked.']) { + message = applySummarizeDelta(message, summarize, summaryDelta(chunk), 0); + } + return message; + }; + + it('opens, streams, and settles a summary in its step slot', () => { + const streamed = streamSummary(); + expect(streamed.content?.[1]).toMatchObject({ + type: ContentTypes.SUMMARY, + summarizing: true, + content: [ + { type: ContentTypes.TEXT, text: 'Earlier, ' }, + { type: ContentTypes.TEXT, text: 'we talked.' }, + ], + }); + + const settled = finalizeSummaries( + streamed, + { + id: summarize.id, + agentId: 'a', + summary: { type: ContentTypes.SUMMARY, content: [] } as SummaryContentPart, + }, + 1, + ); + + expect(settled?.content?.[1]).toMatchObject({ summarizing: false }); + expectStepPositions(settled as TMessage, [[summarize, ContentTypes.SUMMARY]]); + expect( + finalizeSummaries(settled as TMessage, { id: summarize.id, agentId: 'a' }, 1), + ).toBeUndefined(); + }); + + it('keeps a failed round in its slot instead of splicing it out', () => { + const text = messageStep('step-text', 2); + const streamed = streamText(streamSummary(), text, ['after']); + + const failed = finalizeSummaries( + streamed, + { id: summarize.id, agentId: 'a', error: 'boom' }, + 1, + ) as TMessage; + + expect(failed.content?.[1]).toMatchObject({ summarizing: false, failed: true }); + expectStepPositions(failed, [ + [summarize, ContentTypes.SUMMARY], + [text, ContentTypes.TEXT], + ]); + }); + + it('finalizes only the owning slot when the step is known', () => { + const newer = messageStep('step-summary-2', 3, { summary: summarize.summary }); + const both = applySummaryStep(streamSummary(), newer, 0); + + const scoped = finalizeSummaries(both, { id: summarize.id, agentId: 'a' }, 1) as TMessage; + const global = finalizeSummaries(both, { id: 'unknown', agentId: 'a' }, -1) as TMessage; + + expect(scoped.content?.[1]).toMatchObject({ summarizing: false }); + expect(scoped.content?.[3]).toMatchObject({ summarizing: true }); + expect(global.content?.[3]).toMatchObject({ summarizing: false }); + }); + }); +}); diff --git a/client/src/hooks/SSE/steps/content.ts b/client/src/hooks/SSE/steps/content.ts new file mode 100644 index 0000000000..25415d5ad3 --- /dev/null +++ b/client/src/hooks/SSE/steps/content.ts @@ -0,0 +1,354 @@ +import { Constants, ContentTypes, ToolCallTypes, getNonEmptyValue } from 'librechat-data-provider'; +import type { + Agents, + TMessage, + PartMetadata, + ContentMetadata, + EventSubmission, + SummaryContentPart, + TMessageContentParts, +} from 'librechat-data-provider'; +import { isAskUserQuestionPart, isAnsweredAskUserQuestionPart } from '~/utils/approval'; + +/** + * Pure content-part primitives behind `useStepHandler`. + * + * Invariant every function here keeps: a part's position in `message.content` is its step index + * (plus the retained edit prefix). Parts are written in place, never spliced, so a slot that + * arrives early leaves holes rather than shifting later parts. + * + * AI SDK mapping, for orientation only: `message.content` is `UIMessage.parts`, and the part + * types map as `text` to `text`, `think` to `reasoning`, `tool_call` to `tool-`, + * `image_file`/`image_url` to `file`, and `summary`/`agent_update` to `data-*` parts. + */ + +export type TextPhase = 'commentary' | 'final_answer'; + +type MessageDeltaUpdate = { + type: ContentTypes.TEXT; + text: string; + tool_call_ids?: string[]; + phase?: TextPhase; +}; + +type ReasoningDeltaUpdate = { type: ContentTypes.THINK; think: string }; + +type AllContentTypes = + | ContentTypes.TEXT + | ContentTypes.THINK + | ContentTypes.TOOL_CALL + | ContentTypes.IMAGE_FILE + | ContentTypes.IMAGE_URL + | ContentTypes.SUMMARY + | ContentTypes.ERROR; + +export const isOAuthToolCallName = (name?: string) => + typeof name === 'string' && name.startsWith(`oauth${Constants.mcp_delimiter}`); + +const isOAuthToolCallContent = (part?: Partial) => { + if (part?.type !== ContentTypes.TOOL_CALL || !('tool_call' in part)) { + return false; + } + const { tool_call: toolCall } = part; + const name = toolCall != null && 'name' in toolCall ? toolCall.name : undefined; + return isOAuthToolCallName(name); +}; + +/** + * Index offset for an edited resubmission: the server indexes only the NEW content, so incoming + * indices shift past the prefix the client kept. + * + * Reads the length CAPTURED when the submission was built rather than the live + * `initialResponse.content` array, because a resume sync REPLACES that array with the server's + * completion-local snapshot, whose length describes the new generation, not the retained prefix. + * + * `editPrefixCleared` means that sync also replaced the RENDERED content: the prefix is gone from + * the message and server indices are already absolute, so any offset would write past the end. + * + * `initialContent` stays the live array: it seeds a response that is not in the map yet, and + * post-sync the seeding path correctly falls back to the rendered content instead. + */ +export function getEditPrefix(submission: EventSubmission): { + initialContent: TMessageContentParts[]; + editPrefixOffset: number; +} { + if (submission?.editedContent == null || submission?.editPrefixCleared === true) { + return { initialContent: [], editPrefixOffset: 0 }; + } + const initialContent = submission?.initialResponse?.content ?? []; + return { + initialContent, + editPrefixOffset: submission?.editPrefixLength ?? initialContent.length, + }; +} + +/** + * Content index for a server step index. Takes the edit-prefix OFFSET rather than the prefix + * array: after a resume sync the live array no longer describes the retained prefix, so deriving + * the offset from its length would disagree with the offset every other event path applies. + */ +export function calculateContentIndex( + serverIndex: number, + editPrefixOffset: number, + incomingContentType: string, + existingContent?: TMessageContentParts[], + incomingPhase?: TextPhase, +): number { + /** Only apply -1 adjustment for TEXT or THINK types when they match existing content */ + if ( + editPrefixOffset > 0 && + (incomingContentType === ContentTypes.TEXT || incomingContentType === ContentTypes.THINK) + ) { + const targetIndex = serverIndex + editPrefixOffset - 1; + const existingPart = existingContent?.[targetIndex]; + const existingType = existingPart?.type; + const existingPhase = existingPart?.type === ContentTypes.TEXT ? existingPart.phase : undefined; + /** Match final assembly: phased and legacy/unphased text cannot share + * a content part because the phase controls client grouping. */ + const phaseCompatible = + incomingContentType !== ContentTypes.TEXT || + (incomingPhase ?? null) === (existingPhase ?? null); + if (existingType === incomingContentType && phaseCompatible) { + return targetIndex; + } + } + return serverIndex + editPrefixOffset; +} + +/** True when a delta at `contentIndex` folded into the last part of the retained edit prefix. */ +export function foldsEditPrefix( + serverIndex: number, + editPrefixOffset: number, + contentIndex: number, +): boolean { + return serverIndex === 0 && editPrefixOffset > 0 && contentIndex === editPrefixOffset - 1; +} + +/** Extract metadata from a run step for parallel content rendering. */ +export function getStepMetadata(runStep: Agents.RunStep | undefined): ContentMetadata | undefined { + if (!runStep?.agentId && runStep?.groupId == null) { + return undefined; + } + return { + agentId: runStep.agentId, + /** Only set when explicitly provided by the server: sequential handoffs have agentId but no + * groupId, parallel execution has both. */ + groupId: runStep.groupId, + }; +} + +/** Starts a fresh label-revision domain when a different reasoning step + * reuses or folds into an existing THINK slot. The step id is stamped before + * the first generated title so compacted resume snapshots can still correlate + * later label events by identity rather than relying only on a sparse index. */ +export function prepareReasoningPartForStep( + message: TMessage, + index: number, + stepId: string, +): TMessage { + const current = message.content?.[index]; + if (current?.type !== ContentTypes.THINK || current.reasoning_label_step_id === stepId) { + return message; + } + const nextPart = { ...current }; + delete nextPart.reasoning_label; + delete nextPart.reasoning_label_attempts; + delete nextPart.reasoning_label_submitted_chars; + delete nextPart.reasoning_label_revision; + delete nextPart.reasoning_label_status; + nextPart.reasoning_label_step_id = stepId; + const nextContent = [...(message.content ?? [])]; + nextContent[index] = nextPart; + return { ...message, content: nextContent }; +} + +/** + * Writes one incoming part into `message.content[index]` and returns the next message. Text and + * reasoning append, tool calls merge (args concatenate until they arrive as an object), summaries + * concatenate their content, and a part of a different type never overwrites an occupied slot. + * Returns the input message unchanged when the part is rejected. + */ +export function updateContent( + message: TMessage, + index: number, + contentPart: Agents.MessageContentComplex, + finalUpdate = false, + metadata?: ContentMetadata, +): TMessage { + const contentType = contentPart.type ?? ''; + if (!contentType) { + console.warn('No content type found in content part'); + return message; + } + + const incomingOAuthToolCall = + contentType === ContentTypes.TOOL_CALL && + 'tool_call' in contentPart && + isOAuthToolCallName(contentPart.tool_call?.name); + + let updatedContent = [...(message.content || [])] as Array< + Partial | undefined + >; + + const oauthPromptOccupiesSlot = isOAuthToolCallContent(updatedContent[index]); + if (!incomingOAuthToolCall && oauthPromptOccupiesSlot) { + updatedContent = updatedContent.filter((part) => !isOAuthToolCallContent(part)); + } + + /** + * The synthetic ask-user-question card is pause-scoped UI appended at the end + * of the content, exactly the ABSOLUTE index the resumed segment streams + * into. Once real content arrives for that slot the pause is over: displace + * the card (same displacement pattern as the OAuth prompt above) instead of + * dropping the incoming part as a type mismatch. Covers the streaming + * handler's own in-flight message copy, reconnecting tabs, and other devices: + * the store-level strip on answer submit can't reach those. + */ + if (isAskUserQuestionPart(updatedContent[index])) { + updatedContent[index] = undefined; + } else if (updatedContent.some(isAnsweredAskUserQuestionPart)) { + /** + * An ALREADY-ANSWERED card the resumed segment streams around rather than + * into: the first event after the resume re-renders the ask tool_call at + * ITS OWN index, so the slot test above never fires and this handler's + * cached copy, which still holds the card the answer-submit stripped from + * the store, gets written back, reopening the popover with its options + * locked. Only cards the user actually answered are dropped, so an event + * racing a still-live pause can't take its card down. Preserve sparse + * absolute indices: compacting holes can move an older tool call into a + * text slot until the terminal snapshot repairs the rendered order. + */ + updatedContent = updatedContent.map((part) => + isAnsweredAskUserQuestionPart(part) ? undefined : part, + ); + } + + if (!updatedContent[index] && contentType !== ContentTypes.TOOL_CALL) { + updatedContent[index] = { type: contentPart.type as AllContentTypes }; + } + + /** Prevent overwriting an existing content part with a different type */ + const existingType = (updatedContent[index]?.type as string | undefined) ?? ''; + if ( + existingType && + existingType !== contentType && + !contentType.startsWith(existingType) && + !existingType.startsWith(contentType) + ) { + console.warn('Content type mismatch', { existingType, contentType, index }); + return message; + } + + if ( + contentType.startsWith(ContentTypes.TEXT) && + ContentTypes.TEXT in contentPart && + typeof contentPart.text === 'string' + ) { + const currentContent = updatedContent[index] as MessageDeltaUpdate; + const incomingContent = contentPart as MessageDeltaUpdate; + const phase = incomingContent.phase ?? currentContent.phase; + const update: MessageDeltaUpdate = { + type: ContentTypes.TEXT, + text: (currentContent.text || '') + incomingContent.text, + ...(phase != null && { phase }), + }; + + if ('tool_call_ids' in contentPart && contentPart.tool_call_ids != null) { + update.tool_call_ids = contentPart.tool_call_ids; + } + updatedContent[index] = update; + } else if ( + contentType.startsWith(ContentTypes.AGENT_UPDATE) && + ContentTypes.AGENT_UPDATE in contentPart && + contentPart.agent_update + ) { + const update: Agents.AgentUpdate = { + type: ContentTypes.AGENT_UPDATE, + agent_update: contentPart.agent_update, + }; + + updatedContent[index] = update; + } else if ( + contentType.startsWith(ContentTypes.THINK) && + ContentTypes.THINK in contentPart && + typeof contentPart.think === 'string' + ) { + const currentContent = updatedContent[index] as ReasoningDeltaUpdate; + const update: ReasoningDeltaUpdate = { + ...currentContent, + type: ContentTypes.THINK, + think: (currentContent.think || '') + contentPart.think, + }; + + updatedContent[index] = update; + } else if (contentType === ContentTypes.IMAGE_URL && 'image_url' in contentPart) { + const currentContent = updatedContent[index] as { + type: ContentTypes.IMAGE_URL; + image_url: string; + }; + updatedContent[index] = { + ...currentContent, + }; + } else if (contentType === ContentTypes.SUMMARY) { + const currentSummary = updatedContent[index] as SummaryContentPart | undefined; + const incoming = contentPart as SummaryContentPart; + updatedContent[index] = { + ...incoming, + content: [...(currentSummary?.content ?? []), ...(incoming.content ?? [])], + }; + } else if (contentType === ContentTypes.TOOL_CALL && 'tool_call' in contentPart) { + const existingContent = updatedContent[index] as Agents.ToolCallContent | undefined; + const existingToolCall = existingContent?.tool_call; + const toolCallArgs = (contentPart.tool_call as Agents.ToolCall).args; + /** When args are a valid object, they are likely already invoked */ + let args = + finalUpdate || typeof existingToolCall?.args === 'object' || typeof toolCallArgs === 'object' + ? contentPart.tool_call.args + : (existingToolCall?.args ?? '') + (toolCallArgs ?? ''); + /** Preserve previously streamed args when final update omits them */ + if (finalUpdate && args == null && existingToolCall?.args != null) { + args = existingToolCall.args; + } + + const id = getNonEmptyValue([contentPart.tool_call.id, existingToolCall?.id]) ?? ''; + const name = getNonEmptyValue([contentPart.tool_call.name, existingToolCall?.name]) ?? ''; + + const newToolCall: Agents.ToolCall & PartMetadata = { + id, + name, + args, + stepId: getNonEmptyValue([contentPart.tool_call.stepId, existingToolCall?.stepId]), + type: ToolCallTypes.TOOL_CALL, + auth: contentPart.tool_call.auth, + expires_at: contentPart.tool_call.expires_at, + }; + + if (finalUpdate) { + newToolCall.progress = 1; + newToolCall.output = contentPart.tool_call.output; + if ( + 'inputValidationError' in contentPart.tool_call && + contentPart.tool_call.inputValidationError === true + ) { + Object.assign(newToolCall, { inputValidationError: true }); + } + } + + updatedContent[index] = { + type: ContentTypes.TOOL_CALL, + tool_call: newToolCall, + }; + } + + /** Metadata goes on last so no branch above overwrites it. The part is copied rather than + * mutated: an untouched slot still holds the caller's object. */ + if (metadata?.agentId != null || metadata?.groupId != null) { + updatedContent[index] = { + ...updatedContent[index], + ...(metadata.agentId != null && { agentId: metadata.agentId }), + ...(metadata.groupId != null && { groupId: metadata.groupId }), + } as Partial; + } + + return { ...message, content: updatedContent as TMessageContentParts[] }; +} diff --git a/client/src/hooks/SSE/steps/index.ts b/client/src/hooks/SSE/steps/index.ts new file mode 100644 index 0000000000..d2ae7b2e9b --- /dev/null +++ b/client/src/hooks/SSE/steps/index.ts @@ -0,0 +1,2 @@ +export * from './content'; +export * from './text'; diff --git a/client/src/hooks/SSE/steps/text.ts b/client/src/hooks/SSE/steps/text.ts new file mode 100644 index 0000000000..24bf5aedc5 --- /dev/null +++ b/client/src/hooks/SSE/steps/text.ts @@ -0,0 +1,207 @@ +import { StepTypes, ContentTypes } from 'librechat-data-provider'; +import type { + Agents, + TMessage, + ContentMetadata, + SummaryContentPart, +} from 'librechat-data-provider'; +import type { TextPhase } from './content'; +import { + prepareReasoningPartForStep, + calculateContentIndex, + getStepMetadata, + foldsEditPrefix, + updateContent, +} from './content'; + +/** Result of folding one message or reasoning delta into a response. */ +export type DeltaResult = { + message: TMessage; + /** False when the delta carried no parts, so nothing should be written. */ + updated: boolean; + /** True when a part folded into the last part of the retained edit prefix. */ + foldedEditPrefix: boolean; +}; + +const toParts = ( + content: Agents.MessageContentComplex | Agents.MessageContentComplex[], +): Agents.MessageContentComplex[] => (Array.isArray(content) ? content : [content]); + +/** + * Folds a message delta (text, or think parts on providers that stream reasoning through the + * message channel) into the response. A delta may carry several parts, such as Google server-side + * tool chunks, and every entry is applied in order or streamed text is silently dropped. + * AI SDK: `text-delta`. + */ +export function applyMessageDelta( + message: TMessage, + runStep: Agents.RunStep, + delta: Agents.MessageDeltaEvent, + editPrefixOffset: number, +): DeltaResult { + const result: DeltaResult = { message, updated: false, foldedEditPrefix: false }; + if (!delta.delta.content) { + return result; + } + const phase = + runStep.stepDetails.type === StepTypes.MESSAGE_CREATION + ? (runStep.stepDetails.message_creation as { phase?: TextPhase } | undefined)?.phase + : undefined; + const metadata = getStepMetadata(runStep); + for (const contentPart of toParts(delta.delta.content)) { + if (contentPart == null) { + continue; + } + const phasedContentPart = + contentPart.type === ContentTypes.TEXT && (phase === 'commentary' || phase === 'final_answer') + ? { ...contentPart, phase } + : contentPart; + const index = calculateContentIndex( + runStep.index, + editPrefixOffset, + phasedContentPart.type || '', + result.message.content, + phase, + ); + if (foldsEditPrefix(runStep.index, editPrefixOffset, index)) { + result.foldedEditPrefix = true; + } + if (phasedContentPart.type === ContentTypes.THINK) { + result.message = prepareReasoningPartForStep(result.message, index, delta.id); + } + result.message = updateContent(result.message, index, phasedContentPart, false, metadata); + result.updated = true; + } + return result; +} + +/** + * Folds a reasoning delta into the response. Same multi-part contract as + * {@link applyMessageDelta}. AI SDK: `reasoning-delta`. + */ +export function applyReasoningDelta( + message: TMessage, + runStep: Agents.RunStep, + delta: Agents.ReasoningDeltaEvent, + editPrefixOffset: number, +): DeltaResult { + const result: DeltaResult = { message, updated: false, foldedEditPrefix: false }; + if (delta.delta.content == null) { + return result; + } + const metadata = getStepMetadata(runStep); + for (const contentPart of toParts(delta.delta.content)) { + if (contentPart == null) { + continue; + } + const index = calculateContentIndex( + runStep.index, + editPrefixOffset, + contentPart.type || '', + result.message.content, + ); + if (foldsEditPrefix(runStep.index, editPrefixOffset, index)) { + result.foldedEditPrefix = true; + } + result.message = prepareReasoningPartForStep(result.message, index, delta.id); + result.message = updateContent(result.message, index, contentPart, false, metadata); + result.updated = true; + } + return result; +} + +/** + * Writes an agent handoff marker at its own index. Agent updates carry their own agent id and + * default to group 1 when they have one. + */ +export function applyAgentUpdate( + message: TMessage, + event: Agents.AgentUpdate, + editPrefixOffset: number, +): TMessage { + const { agent_update } = event; + const metadata: ContentMetadata | undefined = agent_update.agentId + ? { agentId: agent_update.agentId, groupId: 1 } + : undefined; + return updateContent(message, agent_update.index + editPrefixOffset, event, false, metadata); +} + +/** Opens an in-flight summary part at a summarize step's slot. */ +export function applySummaryStep( + message: TMessage, + runStep: Agents.RunStep, + editPrefixOffset: number, +): TMessage { + if (runStep.summary == null) { + return message; + } + const summaryPart: SummaryContentPart = { + type: ContentTypes.SUMMARY, + content: [], + summarizing: true, + model: runStep.summary.model, + provider: runStep.summary.provider, + }; + return updateContent( + { ...message }, + runStep.index + editPrefixOffset, + summaryPart, + false, + getStepMetadata(runStep), + ); +} + +/** Appends a summary delta to its step's in-flight summary part. */ +export function applySummarizeDelta( + message: TMessage, + runStep: Agents.RunStep, + delta: Agents.SummarizeDeltaEvent, + editPrefixOffset: number, +): TMessage { + const contentPart: SummaryContentPart = { ...delta.delta.summary, summarizing: true }; + return updateContent( + message, + runStep.index + editPrefixOffset, + contentPart, + false, + getStepMetadata(runStep), + ); +} + +/** + * Settles in-flight summary parts. Scoped to `completeIndex` when the owning step is known: a + * global scan would finalize a NEWER round's in-flight part when summarize cycles run + * back-to-back. A negative index finalizes every in-flight part. + * + * Failed rounds keep their slot, flagged `failed`, rather than being spliced out: removing a part + * shifts every later part under the index-keyed renderer and breaks the position invariant. + * + * Returns `undefined` when no part was in flight. + */ +export function finalizeSummaries( + message: TMessage, + event: Agents.SummarizeCompleteEvent, + completeIndex: number, +): TMessage | undefined { + if (!Array.isArray(message.content)) { + return undefined; + } + let didFinalize = false; + const content = message.content.map((part, index) => { + if (part?.type !== ContentTypes.SUMMARY || !(part as SummaryContentPart).summarizing) { + return part; + } + if (completeIndex >= 0 && index !== completeIndex) { + return part; + } + didFinalize = true; + if (!event.error && event.summary) { + return { ...event.summary, summarizing: false } as SummaryContentPart; + } + if (event.error) { + return { ...part, summarizing: false, failed: true } as SummaryContentPart; + } + return { ...part, summarizing: false } as SummaryContentPart; + }); + return didFinalize ? { ...message, content } : undefined; +} diff --git a/client/src/hooks/SSE/useStepHandler.ts b/client/src/hooks/SSE/useStepHandler.ts index 7e70de8572..985ec8c5b2 100644 --- a/client/src/hooks/SSE/useStepHandler.ts +++ b/client/src/hooks/SSE/useStepHandler.ts @@ -6,17 +6,12 @@ import { StepTypes, StepEvents, ContentTypes, - ToolCallTypes, - getNonEmptyValue, getRunStepDurationMs, } from 'librechat-data-provider'; import type { Agents, TMessage, - PartMetadata, - ContentMetadata, EventSubmission, - SummaryContentPart, TMessageContentParts, SubagentUpdateEvent, SandboxStartingEvent, @@ -35,13 +30,23 @@ import { takeRegisteredSubagentProgressKeys, subagentProgressKey, } from '~/components/Chat/Subagents/state'; +import { + applyReasoningDelta, + applySummarizeDelta, + applyMessageDelta, + finalizeSummaries, + applyAgentUpdate, + applySummaryStep, + getStepMetadata, + getEditPrefix, + updateContent, +} from './steps'; import { sandboxStartingByToolCallId, ptcTraceByToolCallId, PTC_TRACE_MAX_ENTRIES, ptcTraceKey, } from '~/store'; -import { isAskUserQuestionPart, isAnsweredAskUserQuestionPart } from '~/utils/approval'; import { MESSAGE_UPDATE_INTERVAL } from '~/common'; type TUseStepHandler = { @@ -74,45 +79,6 @@ type TStepEvent = | { event: StepEvents.ON_SANDBOX_STARTING; data: SandboxStartingEvent } | { event: StepEvents.ON_PTC_TOOL_CALL; data: PtcToolCallEvent }; -type MessageDeltaUpdate = { - type: ContentTypes.TEXT; - text: string; - tool_call_ids?: string[]; - phase?: 'commentary' | 'final_answer'; -}; - -type ReasoningDeltaUpdate = { type: ContentTypes.THINK; think: string }; - -/** Starts a fresh label-revision domain when a different reasoning step - * reuses or folds into an existing THINK slot. The step id is stamped before - * the first generated title so compacted resume snapshots can still correlate - * later label events by identity rather than relying only on a sparse index. */ -function prepareReasoningPartForStep(message: TMessage, index: number, stepId: string): TMessage { - const current = message.content?.[index]; - if (current?.type !== ContentTypes.THINK || current.reasoning_label_step_id === stepId) { - return message; - } - const nextPart = { ...current }; - delete nextPart.reasoning_label; - delete nextPart.reasoning_label_attempts; - delete nextPart.reasoning_label_submitted_chars; - delete nextPart.reasoning_label_revision; - delete nextPart.reasoning_label_status; - nextPart.reasoning_label_step_id = stepId; - const nextContent = [...(message.content ?? [])]; - nextContent[index] = nextPart; - return { ...message, content: nextContent }; -} - -type AllContentTypes = - | ContentTypes.TEXT - | ContentTypes.THINK - | ContentTypes.TOOL_CALL - | ContentTypes.IMAGE_FILE - | ContentTypes.IMAGE_URL - | ContentTypes.SUMMARY - | ContentTypes.ERROR; - /** Mirrors `SKILL_FILE_PREFIX` in `@librechat/api` file-authoring handlers. */ const SKILL_FILE_PREFIX = 'skills/'; const FILE_AUTHORING_TOOLS = new Set(['create_file', 'edit_file']); @@ -141,18 +107,6 @@ function isSkillAuthoringToolCall(toolCall?: Agents.ToolCall): boolean { return typeof filePath === 'string' && filePath.startsWith(SKILL_FILE_PREFIX); } -const isOAuthToolCallName = (name?: string) => - typeof name === 'string' && name.startsWith(`oauth${Constants.mcp_delimiter}`); - -const isOAuthToolCallContent = (part?: Partial) => { - if (part?.type !== ContentTypes.TOOL_CALL || !('tool_call' in part)) { - return false; - } - const { tool_call: toolCall } = part; - const name = toolCall != null && 'name' in toolCall ? toolCall.name : undefined; - return isOAuthToolCallName(name); -}; - export default function useStepHandler({ setMessages, getMessages, @@ -202,7 +156,7 @@ export default function useStepHandler({ ); /** Both content parts and ticker lines are aggregated incrementally - * into the atom as each `ON_SUBAGENT_UPDATE` arrives — we never + * 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. */ @@ -288,13 +242,13 @@ export default function useStepHandler({ /** * Resets all accumulated subagent state. Kept for conversation-switch - * cleanup (see top-level hook usage) but NOT called from `clearStepMaps` — + * cleanup (see top-level hook usage) but NOT called from `clearStepMaps`: * the collapsed SubagentCall ticker and its panel read from these atoms to * render the child's content parts, and we want that history to remain * visible after the stream ends so the user can reopen the panel for * auditability. The atoms are bounded by aggregated structure and * per-conversation (one atom per subagent spawn), so growth is proportional - * to messages — the same growth profile as the rest of the conversation + * to messages: the same growth profile as the rest of the conversation * state. */ const resetSubagentAtoms = useCallback((): void => { @@ -352,7 +306,7 @@ export default function useStepHandler({ * Folds one `on_ptc_tool_call` envelope into its program's trace: the * `running` event appends a row, the settling event updates that row in * place by `call_id`. Order follows the sandbox's dispatch order, which is - * what the code reads like — a round trip can settle out of order. + * what the code reads like; a round trip can settle out of order. */ const applyPtcToolCall = useRecoilCallback( ({ set }) => @@ -382,8 +336,8 @@ export default function useStepHandler({ return { entries: next, dropped: previous.dropped }; } - /** A settle whose row is gone — evicted by the cap, or pruned across - * a resume gap — must not reappear at the tail out of order. */ + /** A settle whose row is gone, evicted by the cap, or pruned across + * a resume gap, must not reappear at the tail out of order. */ if (status !== 'running') { return previous; } @@ -415,15 +369,15 @@ export default function useStepHandler({ /** * Settles rows still marked `running` after a stream gap as `interrupted`. - * Inner calls carry no durable state — they are not content parts, so the + * Inner calls carry no durable state: they are not content parts, so the * resume snapshot cannot rebuild them and a settling event lost in the gap - * is never replayed — which means such a row would otherwise spin forever. + * is never replayed, and that means such a row would otherwise spin forever. * * Marked, not removed: a call can also still be executing across the * reconnect, and its settling event then arrives normally on the restored * live stream. That event updates this row in place, so the call reports its - * real outcome. Deleting the row would strand it — a settle whose row is - * gone is dropped rather than re-appended out of order — and the call would + * real outcome. Deleting the row would strand it: a settle whose row is + * gone is dropped rather than re-appended out of order, and the call would * vanish from the trace despite having run. Settled rows are untouched. */ const prunePtcTraces = useRecoilCallback( @@ -447,252 +401,6 @@ export default function useStepHandler({ [], ); - /** - * Calculate content index for a run step. - * - * Takes the edit-prefix OFFSET rather than the prefix array: after a resume - * sync the live array no longer describes the retained prefix, so deriving - * the offset here from its length would disagree with the offset every - * other event path applies. - */ - const calculateContentIndex = useCallback( - ( - serverIndex: number, - editPrefixOffset: number, - incomingContentType: string, - existingContent?: TMessageContentParts[], - incomingPhase?: 'commentary' | 'final_answer', - ): number => { - /** Only apply -1 adjustment for TEXT or THINK types when they match existing content */ - if ( - editPrefixOffset > 0 && - (incomingContentType === ContentTypes.TEXT || incomingContentType === ContentTypes.THINK) - ) { - const targetIndex = serverIndex + editPrefixOffset - 1; - const existingPart = existingContent?.[targetIndex]; - const existingType = existingPart?.type; - const existingPhase = - existingPart?.type === ContentTypes.TEXT ? existingPart.phase : undefined; - /** Match final assembly: phased and legacy/unphased text cannot share - * a content part because the phase controls client grouping. */ - const phaseCompatible = - incomingContentType !== ContentTypes.TEXT || - (incomingPhase ?? null) === (existingPhase ?? null); - if (existingType === incomingContentType && phaseCompatible) { - return targetIndex; - } - } - return serverIndex + editPrefixOffset; - }, - [], - ); - - /** Metadata to propagate onto content parts for parallel rendering - uses ContentMetadata from data-provider */ - - const updateContent = ( - message: TMessage, - index: number, - contentPart: Agents.MessageContentComplex, - finalUpdate = false, - metadata?: ContentMetadata, - ) => { - const contentType = contentPart.type ?? ''; - if (!contentType) { - console.warn('No content type found in content part'); - return message; - } - - const incomingOAuthToolCall = - contentType === ContentTypes.TOOL_CALL && - 'tool_call' in contentPart && - isOAuthToolCallName(contentPart.tool_call?.name); - - let updatedContent = [...(message.content || [])] as Array< - Partial | undefined - >; - - const oauthPromptOccupiesSlot = isOAuthToolCallContent(updatedContent[index]); - if (!incomingOAuthToolCall && oauthPromptOccupiesSlot) { - updatedContent = updatedContent.filter((part) => !isOAuthToolCallContent(part)); - } - - /** - * The synthetic ask-user-question card is pause-scoped UI appended at the end - * of the content — exactly the ABSOLUTE index the resumed segment streams - * into. Once real content arrives for that slot the pause is over: displace - * the card (same displacement pattern as the OAuth prompt above) instead of - * dropping the incoming part as a type mismatch. Covers the streaming - * handler's own in-flight message copy, reconnecting tabs, and other devices - * — the store-level strip on answer submit can't reach those. - */ - if (isAskUserQuestionPart(updatedContent[index])) { - updatedContent[index] = undefined; - } else if (updatedContent.some(isAnsweredAskUserQuestionPart)) { - /** - * An ALREADY-ANSWERED card the resumed segment streams around rather than - * into: the first event after the resume re-renders the ask tool_call at - * ITS OWN index, so the slot test above never fires and this handler's - * cached copy — which still holds the card the answer-submit stripped from - * the store — gets written back, reopening the popover with its options - * locked. Only cards the user actually answered are dropped, so an event - * racing a still-live pause can't take its card down. Preserve sparse - * absolute indices: compacting holes can move an older tool call into a - * text slot until the terminal snapshot repairs the rendered order. - */ - updatedContent = updatedContent.map((part) => - isAnsweredAskUserQuestionPart(part) ? undefined : part, - ); - } - - if (!updatedContent[index] && contentType !== ContentTypes.TOOL_CALL) { - updatedContent[index] = { type: contentPart.type as AllContentTypes }; - } - - /** Prevent overwriting an existing content part with a different type */ - const existingType = (updatedContent[index]?.type as string | undefined) ?? ''; - if ( - existingType && - existingType !== contentType && - !contentType.startsWith(existingType) && - !existingType.startsWith(contentType) - ) { - console.warn('Content type mismatch', { existingType, contentType, index }); - return message; - } - - if ( - contentType.startsWith(ContentTypes.TEXT) && - ContentTypes.TEXT in contentPart && - typeof contentPart.text === 'string' - ) { - const currentContent = updatedContent[index] as MessageDeltaUpdate; - const incomingContent = contentPart as MessageDeltaUpdate; - const phase = incomingContent.phase ?? currentContent.phase; - const update: MessageDeltaUpdate = { - type: ContentTypes.TEXT, - text: (currentContent.text || '') + incomingContent.text, - ...(phase != null && { phase }), - }; - - if ('tool_call_ids' in contentPart && contentPart.tool_call_ids != null) { - update.tool_call_ids = contentPart.tool_call_ids; - } - updatedContent[index] = update; - } else if ( - contentType.startsWith(ContentTypes.AGENT_UPDATE) && - ContentTypes.AGENT_UPDATE in contentPart && - contentPart.agent_update - ) { - const update: Agents.AgentUpdate = { - type: ContentTypes.AGENT_UPDATE, - agent_update: contentPart.agent_update, - }; - - updatedContent[index] = update; - } else if ( - contentType.startsWith(ContentTypes.THINK) && - ContentTypes.THINK in contentPart && - typeof contentPart.think === 'string' - ) { - const currentContent = updatedContent[index] as ReasoningDeltaUpdate; - const update: ReasoningDeltaUpdate = { - ...currentContent, - type: ContentTypes.THINK, - think: (currentContent.think || '') + contentPart.think, - }; - - updatedContent[index] = update; - } else if (contentType === ContentTypes.IMAGE_URL && 'image_url' in contentPart) { - const currentContent = updatedContent[index] as { - type: ContentTypes.IMAGE_URL; - image_url: string; - }; - updatedContent[index] = { - ...currentContent, - }; - } else if (contentType === ContentTypes.SUMMARY) { - const currentSummary = updatedContent[index] as SummaryContentPart | undefined; - const incoming = contentPart as SummaryContentPart; - updatedContent[index] = { - ...incoming, - content: [...(currentSummary?.content ?? []), ...(incoming.content ?? [])], - }; - } else if (contentType === ContentTypes.TOOL_CALL && 'tool_call' in contentPart) { - const existingContent = updatedContent[index] as Agents.ToolCallContent | undefined; - const existingToolCall = existingContent?.tool_call; - const toolCallArgs = (contentPart.tool_call as Agents.ToolCall).args; - /** When args are a valid object, they are likely already invoked */ - let args = - finalUpdate || - typeof existingToolCall?.args === 'object' || - typeof toolCallArgs === 'object' - ? contentPart.tool_call.args - : (existingToolCall?.args ?? '') + (toolCallArgs ?? ''); - /** Preserve previously streamed args when final update omits them */ - if (finalUpdate && args == null && existingToolCall?.args != null) { - args = existingToolCall.args; - } - - const id = getNonEmptyValue([contentPart.tool_call.id, existingToolCall?.id]) ?? ''; - const name = getNonEmptyValue([contentPart.tool_call.name, existingToolCall?.name]) ?? ''; - - const newToolCall: Agents.ToolCall & PartMetadata = { - id, - name, - args, - stepId: getNonEmptyValue([contentPart.tool_call.stepId, existingToolCall?.stepId]), - type: ToolCallTypes.TOOL_CALL, - auth: contentPart.tool_call.auth, - expires_at: contentPart.tool_call.expires_at, - }; - - if (finalUpdate) { - newToolCall.progress = 1; - newToolCall.output = contentPart.tool_call.output; - if ( - 'inputValidationError' in contentPart.tool_call && - contentPart.tool_call.inputValidationError === true - ) { - Object.assign(newToolCall, { inputValidationError: true }); - } - } - - updatedContent[index] = { - type: ContentTypes.TOOL_CALL, - tool_call: newToolCall, - }; - } - - // Apply metadata to the content part for parallel rendering - // This must happen AFTER all content updates to avoid being overwritten - if (metadata?.agentId != null || metadata?.groupId != null) { - const part = updatedContent[index] as TMessageContentParts & ContentMetadata; - if (metadata.agentId != null) { - part.agentId = metadata.agentId; - } - if (metadata.groupId != null) { - part.groupId = metadata.groupId; - } - } - - return { ...message, content: updatedContent as TMessageContentParts[] }; - }; - - /** Extract metadata from runStep for parallel content rendering */ - const getStepMetadata = (runStep: Agents.RunStep | undefined): ContentMetadata | undefined => { - if (!runStep?.agentId && runStep?.groupId == null) { - return undefined; - } - const metadata = { - agentId: runStep.agentId, - // Only set groupId when explicitly provided by the server - // Sequential handoffs have agentId but no groupId - // Parallel execution has both agentId AND groupId - groupId: runStep.groupId, - }; - return metadata; - }; - const stepHandler = useCallback( (stepEvent: TStepEvent, submission: EventSubmission) => { const submissionMessages = submission.messages ?? []; @@ -805,7 +513,7 @@ export default function useStepHandler({ }; /** * Per-token deltas fold into `messageMap` immediately (authoritative), but - * the cache write — and the buildTree + message-tree walk it triggers — + * 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 @@ -849,34 +557,9 @@ export default function useStepHandler({ lastAnnouncementTimeRef.current = currentTime; } - /** - * Index offset for an edited resubmission: the server indexes only the - * NEW content, so incoming indices shift past the prefix the client - * kept. - * - * Reads the length CAPTURED when the submission was built rather than - * the live `initialResponse.content` array, because a resume sync - * REPLACES that array with the server's completion-local snapshot — - * whose length describes the new generation, not the retained prefix. - * They are equal until a reconnect, so the non-resumed path is - * unaffected. - * - * `editPrefixCleared` means that sync also replaced the RENDERED - * content: the prefix is gone from the message and server indices are - * already absolute, so any offset would write past the end. Activity - * labels honor the same flag — both must agree, or a batch's tool - * cards and its header land in different index spaces. - * - * `initialContent` stays the live array: it seeds a response that is - * not in the map yet, and post-sync the seeding path correctly falls - * back to the rendered content instead. - */ - let initialContent: TMessageContentParts[] = []; - let editPrefixOffset = 0; - if (submission?.editedContent != null && submission?.editPrefixCleared !== true) { - initialContent = submission?.initialResponse?.content ?? initialContent; - editPrefixOffset = submission?.editPrefixLength ?? initialContent.length; - } + /** 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; @@ -892,9 +575,6 @@ export default function useStepHandler({ stepMap.current.set(runStep.id, runStep); - // Calculate content index - use server index, offset by the retained edit prefix - const contentIndex = runStep.index + editPrefixOffset; - let response = messageMap.current.get(responseMessageId); if (!response) { @@ -946,9 +626,9 @@ export default function useStepHandler({ setMessages([...updatedMessages, response]); } - // Store tool call IDs if present if (runStep.stepDetails.type === StepTypes.TOOL_CALLS) { let updatedResponse = { ...response }; + const contentIndex = runStep.index + editPrefixOffset; ((runStep.stepDetails.tool_calls ?? []) as Agents.ToolCall[]).forEach((toolCall) => { const toolCallId = toolCall.id ?? ''; if ('id' in toolCall && toolCallId) { @@ -965,7 +645,6 @@ export default function useStepHandler({ }, }; - // Use the pre-calculated contentIndex which handles parallel agent indexing updatedResponse = updateContent( updatedResponse, contentIndex, @@ -984,23 +663,11 @@ export default function useStepHandler({ } if (runStep.summary != null) { - const summaryPart: SummaryContentPart = { - type: ContentTypes.SUMMARY, - content: [], - summarizing: true, - model: runStep.summary.model, - provider: runStep.summary.provider, - }; - - let updatedResponse = { ...(messageMap.current.get(responseMessageId) ?? response) }; - updatedResponse = updateContent( - updatedResponse, - contentIndex, - summaryPart, - false, - getStepMetadata(runStep), + const updatedResponse = applySummaryStep( + messageMap.current.get(responseMessageId) ?? response, + runStep, + editPrefixOffset, ); - messageMap.current.set(responseMessageId, updatedResponse); setMessages( mergeResponseMessage(messages, updatedResponse, responseMessageId, { @@ -1030,19 +697,7 @@ export default function useStepHandler({ const response = messageMap.current.get(responseMessageId); if (response) { - // Agent updates don't need index adjustment - const currentIndex = agent_update.index + editPrefixOffset; - // Agent updates carry their own agentId - use default groupId if agentId is present - const agentUpdateMeta: ContentMetadata | undefined = agent_update.agentId - ? { agentId: agent_update.agentId, groupId: 1 } - : undefined; - const updatedResponse = updateContent( - response, - currentIndex, - stepEvent.data, - false, - agentUpdateMeta, - ); + const updatedResponse = applyAgentUpdate(response, stepEvent.data, editPrefixOffset); messageMap.current.set(responseMessageId, updatedResponse); setMessages( mergeResponseMessage(messages, updatedResponse, responseMessageId, { @@ -1067,65 +722,13 @@ export default function useStepHandler({ } const response = messageMap.current.get(responseMessageId); - if (response && messageDelta.delta.content) { - /** A delta may carry several parts (e.g. Google server-side tool - * chunks) — every entry must be applied, in order, or streamed - * text is silently dropped. */ - const contentParts = Array.isArray(messageDelta.delta.content) - ? messageDelta.delta.content - : [messageDelta.delta.content]; - - let updatedResponse = response; - let hasUpdate = false; - for (const contentPart of contentParts) { - if (contentPart == null) { - continue; - } - const messageCreation = - runStep.stepDetails.type === StepTypes.MESSAGE_CREATION - ? (runStep.stepDetails.message_creation as { - phase?: 'commentary' | 'final_answer'; - }) - : undefined; - const phase = messageCreation?.phase; - const phasedContentPart = - contentPart.type === ContentTypes.TEXT && - (phase === 'commentary' || phase === 'final_answer') - ? { ...contentPart, phase } - : contentPart; - const currentIndex = calculateContentIndex( - runStep.index, - editPrefixOffset, - phasedContentPart.type || '', - updatedResponse.content, - phase, - ); - if ( - submission != null && - runStep.index === 0 && - editPrefixOffset > 0 && - currentIndex === editPrefixOffset - 1 - ) { - submission.editPrefixFirstPartFolded = true; - } - if (phasedContentPart.type === ContentTypes.THINK) { - updatedResponse = prepareReasoningPartForStep( - updatedResponse, - currentIndex, - messageDelta.id, - ); - } - updatedResponse = updateContent( - updatedResponse, - currentIndex, - phasedContentPart, - false, - getStepMetadata(runStep), - ); - hasUpdate = true; + if (response) { + const result = applyMessageDelta(response, runStep, messageDelta, editPrefixOffset); + if (result.foldedEditPrefix && submission != null) { + submission.editPrefixFirstPartFolded = true; } - if (hasUpdate) { - messageMap.current.set(responseMessageId, updatedResponse); + if (result.updated) { + messageMap.current.set(responseMessageId, result.message); scheduleCoalescedMessagesFlush(responseMessageId); } } @@ -1146,49 +749,13 @@ export default function useStepHandler({ } const response = messageMap.current.get(responseMessageId); - if (response && reasoningDelta.delta.content != null) { - /** Same multi-part contract as message deltas: Google server-side - * tool chunks emit several think entries in one delta. */ - const contentParts = Array.isArray(reasoningDelta.delta.content) - ? reasoningDelta.delta.content - : [reasoningDelta.delta.content]; - - let updatedResponse = response; - let hasUpdate = false; - for (const contentPart of contentParts) { - if (contentPart == null) { - continue; - } - const currentIndex = calculateContentIndex( - runStep.index, - editPrefixOffset, - contentPart.type || '', - updatedResponse.content, - ); - if ( - submission != null && - runStep.index === 0 && - editPrefixOffset > 0 && - currentIndex === editPrefixOffset - 1 - ) { - submission.editPrefixFirstPartFolded = true; - } - updatedResponse = prepareReasoningPartForStep( - updatedResponse, - currentIndex, - reasoningDelta.id, - ); - updatedResponse = updateContent( - updatedResponse, - currentIndex, - contentPart, - false, - getStepMetadata(runStep), - ); - hasUpdate = true; + if (response) { + const result = applyReasoningDelta(response, runStep, reasoningDelta, editPrefixOffset); + if (result.foldedEditPrefix && submission != null) { + submission.editPrefixFirstPartFolded = true; } - if (hasUpdate) { - messageMap.current.set(responseMessageId, updatedResponse); + if (result.updated) { + messageMap.current.set(responseMessageId, result.message); scheduleCoalescedMessagesFlush(responseMessageId); } } @@ -1311,7 +878,7 @@ export default function useStepHandler({ /** * A closure for a step this client never saw opened is not an error - * worth surfacing — it happens on reconnect, where the replay may + * worth surfacing; it happens on reconnect, where the replay may * start after the step was created. */ if (!runStep || !responseMessageId) { @@ -1396,18 +963,11 @@ export default function useStepHandler({ const response = messageMap.current.get(responseMessageId); if (response) { - const contentPart: SummaryContentPart = { - ...deltaData.delta.summary, - summarizing: true, - }; - - const contentIndex = runStep.index + editPrefixOffset; - const updatedResponse = updateContent( + const updatedResponse = applySummarizeDelta( response, - contentIndex, - contentPart, - false, - getStepMetadata(runStep), + runStep, + deltaData, + editPrefixOffset, ); messageMap.current.set(responseMessageId, updatedResponse); if (summarizeDeltaRaf.current == null) { @@ -1430,53 +990,19 @@ export default function useStepHandler({ } const targetMessage = messageMap.current.get(completeMessageId); - if (!targetMessage || !Array.isArray(targetMessage.content)) { + if (!targetMessage) { return; } - /** - * Scoped to the owning step's slot when the step is known: a global - * scan finalizes a NEWER round's in-flight part when summarize - * cycles run back-to-back (tiny context windows re-trigger - * summarization every graph step). Unknown step falls back to - * finalizing every in-flight part. - */ + /** Scoped to the owning step's slot when the step is known; see `finalizeSummaries`. */ const completeIndex = completeRunStep != null ? completeRunStep.index + editPrefixOffset : -1; - let didFinalize = false; - const updatedContent = targetMessage.content.map((part, index) => { - if (part?.type !== ContentTypes.SUMMARY || !(part as SummaryContentPart).summarizing) { - return part; - } - if (completeIndex >= 0 && index !== completeIndex) { - return part; - } - didFinalize = true; - if (!completeData.error && completeData.summary) { - return { ...completeData.summary, summarizing: false } as SummaryContentPart; - } - /** - * Failed rounds keep their slot. Splicing the part out shifts every - * later part under the index-keyed renderer (remounting rows and - * collapsing whatever the user expanded mid-stream) and breaks the - * content-position == step-index invariant that `updateContent` - * writes rely on. Flipping the flag alone hides an empty row - * (`Summary` renders null without text) and matches the persisted - * message, which retains the part server-side. An errored round - * carries `failed` so partial deltas that already streamed in are - * not presented as a completed summary. - */ - if (completeData.error) { - return { ...part, summarizing: false, failed: true } as SummaryContentPart; - } - return { ...part, summarizing: false } as SummaryContentPart; - }); - if (didFinalize) { + const finalized = finalizeSummaries(targetMessage, completeData, completeIndex); + if (finalized) { announcePolite({ message: completeData.error ? 'summarize_failed' : 'summarize_completed', isStatus: true, }); - const finalized = { ...targetMessage, content: updatedContent }; const currentMessages = submission.isRegenerate ? messages : getMessages() || []; messageMap.current.set(completeMessageId, finalized); setMessages(mergeResponseMessage(currentMessages, finalized, completeMessageId)); @@ -1491,7 +1017,6 @@ export default function useStepHandler({ lastAnnouncementTimeRef, announcePolite, setMessages, - calculateContentIndex, getCurrentMessages, applySubagentUpdate, setSandboxStarting, @@ -1516,8 +1041,8 @@ export default function useStepHandler({ }, []); /** Applies a queued delta flush synchronously (then cancels the frame). - * For boundaries that READ the cache or synthesize from it — abort's - * partial-response capture, error cards, pending-action application — the + * For boundaries that READ the cache or synthesize from it (abort's + * partial-response capture, error cards, pending-action application), the * queued tokens must land first or the stopped/errored message loses them. */ const flushPendingDeltas = useCallback(() => { if (messageDeltaRaf.current != null) { @@ -1547,15 +1072,15 @@ export default function useStepHandler({ pendingSubagentBuffer.current.clear(); closeParentSubagentStreams(); /** Unlike subagent atoms below, sandbox-starting flags are transient - * status with no audit value — reset them at this boundary so an + * status with no audit value; reset them at this boundary so an * interrupted cold boot can't leak a stale "starting" label onto a * later tool call that reuses the same id (e.g. `call_0`). */ resetSandboxAtoms(); - /** Intentionally NOT calling `resetSubagentAtoms()` here — users need + /** Intentionally NOT calling `resetSubagentAtoms()` here: users need * to be able to reopen the SubagentCall dialog after completion to * audit what the child did. `resetSubagentAtoms` is returned below * so callers can wipe atoms on conversation-switch (see - * `useEventHandlers`) — that's the correct cleanup boundary: + * `useEventHandlers`); that's the correct cleanup boundary: * persisted `subagent_content` takes over for historical messages * once the conversation is saved, and we prevent unbounded * atomFamily growth across multi-conversation sessions. */ diff --git a/e2e/specs/mock/scenarios/step-reducer.spec.ts b/e2e/specs/mock/scenarios/step-reducer.spec.ts new file mode 100644 index 0000000000..d0746792d9 --- /dev/null +++ b/e2e/specs/mock/scenarios/step-reducer.spec.ts @@ -0,0 +1,83 @@ +import { expect, test } from '@playwright/test'; +import type { Locator, Page } from '@playwright/test'; +import { + sendMessageAndWaitForCompletion, + selectMockEndpoint, + MOCK_ENDPOINTS, + NEW_CHAT_PATH, + messagesView, + thinkPrompt, + replyText, +} from '../helpers'; + +/** + * Streamed content parts are folded into the response by the step reducers in + * `client/src/hooks/SSE/steps`, each at its step's index. These scenarios pin + * what that looks like on screen, live and after the persisted copy reloads. + */ + +const uniqueLabel = (prefix: string) => + `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`; + +const lastAssistant = (page: Page) => messagesView(page).locator('.message-render').last(); + +/** True when `first` sits before `second` in document order. */ +async function precedes(first: Locator, second: Locator): Promise { + const handle = await second.elementHandle(); + return first.evaluate( + (node, other) => + other != null && (node.compareDocumentPosition(other) & Node.DOCUMENT_POSITION_FOLLOWING) > 0, + handle, + ); +} + +async function expectReasoningBeforeReply(page: Page, label: string) { + const assistant = lastAssistant(page); + const thoughts = assistant.getByText('Thoughts', { exact: true }).first(); + const reply = assistant.getByText(replyText(label), { exact: true }); + await expect(thoughts).toBeVisible({ timeout: 30_000 }); + await expect(reply).toBeVisible({ timeout: 30_000 }); + await expect(reply).toHaveCount(1); + expect(await precedes(thoughts, reply)).toBe(true); +} + +test.describe('step reducer', () => { + test('streamed reasoning renders ahead of its reply text, live and after reload @scenario:reasoning-renders-before-its-reply-text', async ({ + page, + }) => { + test.setTimeout(60_000); + const label = uniqueLabel('think'); + await page.goto(NEW_CHAT_PATH, { timeout: 10_000 }); + await selectMockEndpoint(page, MOCK_ENDPOINTS[0]); + + const response = await sendMessageAndWaitForCompletion(page, thinkPrompt(label)); + expect(response.ok()).toBeTruthy(); + await expectReasoningBeforeReply(page, label); + + await page.reload({ timeout: 10_000 }); + await expectReasoningBeforeReply(page, label); + }); + + test('a manual compaction streams its summary into the conversation and keeps it after reload @scenario:manual-compaction-summary-survives-reload', async ({ + page, + }) => { + test.setTimeout(120_000); + const label = uniqueLabel('compact'); + await page.goto(NEW_CHAT_PATH, { timeout: 10_000 }); + await sendMessageAndWaitForCompletion(page, `tell me about ${label}`); + + await page.getByTestId('token-usage').click(); + await page.getByRole('button', { name: 'Compact context' }).click(); + + const compacted = messagesView(page).getByText('You compacted the context', { exact: true }); + await expect(compacted).toBeVisible({ timeout: 60_000 }); + await expect(compacted).toHaveCount(1); + await expect(page.getByRole('button', { name: 'Stop generating' })).toBeHidden({ + timeout: 30_000, + }); + + await page.reload({ timeout: 10_000 }); + await expect(compacted).toBeVisible({ timeout: 30_000 }); + await expect(compacted).toHaveCount(1); + }); +});