🧮 refactor: Pure Step Reducer Behind useStepHandler (#16289)

* refactor: lift text and reasoning step transitions into pure reducers

Move the content-part primitives (updateContent, content index and edit
prefix resolution, step metadata, reasoning label reset) out of
useStepHandler into hooks/SSE/steps, and add pure reducers for message,
reasoning, agent update and summary events. The hook keeps its refs,
message lookup, buffering and cache writes and calls the reducers; its
public signature is unchanged. Tool call events follow in the next change.

* test: cover reasoning order and live compaction with e2e scenarios

* fix: tolerate a message step without message_creation details

The inline handler read the phase through optional chaining; keep that in
applyMessageDelta so a bare MESSAGE_CREATION step still streams.

* test: assert the reset reasoning part without an untyped cast
This commit is contained in:
Marco Beretta 2026-09-24 17:36:34 +02:00 • committed by GitHub
parent 0d4627b387
commit 1c5e8ee7bf
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 1159 additions and 532 deletions

View file

@ -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> = {},
): 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<EventSubmission> = {}) =>
({
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 });
});
});
});

View file

@ -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-<name>`,
* `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<TMessageContentParts>) => {
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<TMessageContentParts> | 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<TMessageContentParts>;
}
return { ...message, content: updatedContent as TMessageContentParts[] };
}

View file

@ -0,0 +1,2 @@
export * from './content';
export * from './text';

View file

@ -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;
}

View file

@ -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<TMessageContentParts>) => {
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<TMessageContentParts> | 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. */

View file

@ -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<boolean> {
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);
});
});