Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🩹 refactor: Move Resumable Response Patching Into the Chat Core (#17127)

Marco Beretta2a701417b74f
diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.ts
index de0479ac22..4d6b76a750 100644
--- a/client/src/hooks/SSE/useResumableSSE.ts
+++ b/client/src/hooks/SSE/useResumableSSE.ts
@@ -9,11 +9,8 @@ import {
Constants,
QueryKeys,
StepEvents,
- StepTypes,
SteerEvents,
dataService,
- ContentTypes,
- ToolCallTypes,
ActivityLabelEvents,
ReasoningLabelEvents,
UsageEvents,
@@ -26,7 +23,6 @@ import {
toStartGenerationError,
isOAuthStepEvent,
waitForRetryDelay,
- applyPendingAction,
getRecoverySteerId,
getRetryAfterDelay,
mergeResumeMessages,
@@ -38,7 +34,6 @@ import {
isRetryableNetworkError,
isReplacedStartResponse,
getResumeMessageIndexes,
- countTaggedApprovalParts,
isInitialNewConversation,
getStreamStartFailureText,
keepLocalCodeApprovalMode,
@@ -52,7 +47,6 @@ import {
getStartGenerationCreatedAt,
isUnnegotiatedV2StartControl,
supportsGenerationProtocolV2,
- findPendingActionMessageIndex,
START_GENERATION_NETWORK_RETRIES,
getStartGenerationConversationId,
getPredecessorMismatchStartResponse,
@@ -63,6 +57,7 @@ import {
authorizeTerminalTeardown,
reconcileGenerationLifecycle,
handleTransportFailure,
+ ResponsePatcher,
clearPendingApprovalForTerminal,
clearAttachedGenerationCreatedAt,
} from '@librechat/chat';
@@ -511,6 +506,9 @@ export default function useResumableSSE(
},
},
steers: {
+ resolve: resolveSteerChip,
+ markLiveApplied: (steerId) =>
+ setLiveAppliedSteerIds((prev) => appendAppliedSteerIds(prev, [steerId])),
seed: seedSteerChips,
appliedIds: collectAppliedSteerIds,
settleApplied: settleAppliedSteerParts,
@@ -518,6 +516,8 @@ export default function useResumableSSE(
convertLocalToQueued: convertLocalSteersToQueued,
},
events: {
+ stepHandler,
+ syncStepMessage,
clearStepMaps,
flushPendingDeltas,
resetLive,
@@ -528,6 +528,15 @@ export default function useResumableSSE(
}),
},
messages: { get: getMessages, set: setMessages },
+ parts: {
+ applySteer: applySteerPart,
+ findSteerTarget: findSteerMessageIndex,
+ applyActivityLabel: applyActivityLabelPart,
+ findActivityLabelTarget: findActivityLabelMessageIndex,
+ offsetActivityPhaseBoundary,
+ applyReasoningLabel,
+ findReasoningLabelTarget: findReasoningLabelMessageIndex,
+ },
};
const sub = new ResumableSubscription(run, host, target);
const {
@@ -591,412 +600,11 @@ export default function useResumableSSE(
currentStreamId;
run.bindPrefixState(generationId);
bindResponse(sub.submission);
- const replayPreCreatedStepEvents = () => {
- if (!sub.isCurrent() || sub.preCreatedStepEvents.length === 0) {
- return;
- }
-
- const submission = sub.liveSubmission() as EventSubmission;
- for (const event of sub.preCreatedStepEvents.splice(0)) {
- stepHandler(event, submission);
- }
- };
- const applyPendingOAuthPrompt = (
- prompt: Agents.PendingMCPOAuthPrompt,
- submission: EventSubmission,
- ) => {
- const toolCall: Agents.ToolCall = {
- id: prompt.toolCallId,
- name: prompt.toolName,
- args: '',
- type: ToolCallTypes.TOOL_CALL,
- };
- const toolCallDelta: Agents.ToolCallChunk = {
- id: prompt.toolCallId,
- name: prompt.toolName,
- args: '',
- };
- stepHandler(
- {
- event: StepEvents.ON_RUN_STEP,
- data: {
- id: prompt.stepId,
- runId: prompt.runId,
- index: prompt.index,
- type: StepTypes.TOOL_CALLS,
- stepDetails: {
- type: StepTypes.TOOL_CALLS,
- tool_calls: [toolCall],
- },
- },
- },
- submission,
- );
- stepHandler(
- {
- event: StepEvents.ON_RUN_STEP_DELTA,
- data: {
- id: prompt.stepId,
- delta: {
- type: StepTypes.TOOL_CALLS,
- tool_calls: [toolCallDelta],
- auth: prompt.authURL,
- expires_at: prompt.expiresAt,
- },
- },
- },
- submission,
- );
- };
-
- /**
- * Maps a pending action onto the in-flight response message so the
- * approval / ask-user UI renders. Syncs the result back into the step
- * handler's map so subsequent deltas build on the approval-tagged content
- * rather than clobbering it.
- *
- * If the mapping is a no-op (the paused tool-call content part hasn't
- * rendered yet, a pause-before-render race), retry on subsequent frames
- * so the approval still attaches. `ask_user_question` always applies (it
- * appends a synthetic part), so only `tool_approval` ever retries.
- */
- // Keep retrying across frames (not just once): Recoil/React message updates from
- // the preceding created/step events are async and can take several frames under
- // load, so a single retry would drop a valid pause and leave the run with no
- // approval controls. Bounded so a genuinely-absent target can't spin forever.
- const PENDING_ACTION_MAX_RETRY_FRAMES = 120;
- const applyPendingActionToMessages = (pendingAction: Agents.PendingAction, attempt = 0) => {
- if (!sub.isCurrent()) {
- return;
- }
- const pendingConversationId =
- pendingAction.conversationId ??
- sub.submission.conversation?.conversationId ??
- currentStreamId;
- jotaiStore.set(pendingApprovalActionFamily(pendingConversationId), pendingAction);
- const retryNextFrame = () => {
- if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- run.pendingActionRetry = run.scheduler.requestFrame(() => {
- if (sub.isCurrent()) {
- applyPendingActionToMessages(pendingAction, attempt + 1);
- }
- });
- }
- };
- /** The pause card must attach to the same message state the stream
- * produced: apply any queued delta before reading the cache, or the
- * later flush would clobber the card (and `syncStepMessage` below
- * would sync a pre-delta copy). */
- flushPendingDeltas();
- const messages = getMessages() ?? [];
- const index = findPendingActionMessageIndex(messages, pendingAction);
- if (index < 0) {
- retryNextFrame();
- return;
- }
- const updated = applyPendingAction(messages[index], pendingAction);
- const changed = updated !== messages[index];
- if (changed) {
- const nextMessages = [...messages];
- nextMessages[index] = updated;
- setMessages(nextMessages);
- syncStepMessage(updated);
- }
- // A `tool_approval` pause can carry several `action_requests` whose tool-call
- // parts render on different frames; tagging only the first to arrive would leave
- // late siblings with no approval card, and the resume route then 400s the partial
- // batch ("every paused tool call must be decided"). Keep retrying (bounded) until
- // EVERY paused call is tagged. `ask_user_question` applies its single synthetic
- // part in one shot, so it only needs the original "did anything change" retry.
- if (pendingAction.payload.type === 'tool_approval') {
- const expected = pendingAction.payload.action_requests.length;
- if (countTaggedApprovalParts(updated, pendingAction.actionId) < expected) {
- retryNextFrame();
- }
- } else if (!changed) {
- retryNextFrame();
- }
- };
-
+ const patcher = new ResponsePatcher(sub, host);
const terminal: TerminalContext = {
sub,
host,
- applyPendingAction: (action) => applyPendingActionToMessages(action),
- };
-
- /**
- * The identities this pane may be rendering the in-flight response under
- * before the first run step renames it to the server's pre-allocated id:
- * the submission's placeholder (updated on `created`) and the padded form
- * of the live user message. Read at call time — `created` reassigns both.
- */
- const livePlaceholderIds = () => [
- sub.submission.initialResponse?.messageId,
- sub.userMessage?.messageId ? `${sub.userMessage.messageId}_` : undefined,
- ];
-
- /**
- * A regenerate seeds the renamed response from `submission.initialResponse`
- * rather than the store tail (an edited resubmission seeds from its
- * content), so a part committed to the placeholder only in the store would
- * be dropped by the first run step's rename. Keep the submission the step
- * handler receives in step with the placeholder this pane mutated.
- */
- const syncSubmissionPlaceholder = (updated: TMessage) => {
- if (updated.messageId !== sub.submission.initialResponse?.messageId) {
- return;
- }
- sub.replaceSubmission({ ...sub.submission, initialResponse: updated });
- };
-
- /**
- * Edit-and-resubmit keeps the retained prefix on the client while the
- * server indexes only the NEW content, so every server-claimed index —
- * run steps (`useStepHandler`), labels and steers — shifts past it or
- * lands inside the prefix and overwrites kept content. The captured
- * length is used over the live array because a resume sync replaces
- * `initialResponse.content` with the server's completion-local snapshot.
- */
- const editPrefixLength = () =>
- sub.submission.editedContent != null && !run.editPrefixCleared
- ? (sub.submission.editPrefixLength ??
- sub.submission.initialResponse?.content?.length ??
- 0)
- : 0;
-
- /**
- * Places an injected steer part on the in-flight response message and
- * resolves its pending chip. Same bounded next-frame retry as pending
- * actions for the inject-before-render race (the assistant placeholder
- * can land a few frames after the created event under load).
- */
- const applySteerToMessages = (
- event: TSteerAppliedEvent,
- attempt = 0,
- liveSteerIds: string[] = [],
- ) => {
- if (!sub.isCurrent()) {
- return;
- }
- const chipConvoId =
- event.conversationId ?? sub.submission.conversation?.conversationId ?? currentStreamId;
- /** The server's applied event settles ownership immediately. Rendering
- * the inline part can wait for React to mount the target, but leaving
- * the chip pending during that wait lets an intervening error/final
- * convert already-applied words into a duplicate queued message. */
- const firstApplicationIds =
- attempt === 0
- ? (resolveSteerChip(
- chipConvoId,
- event.steerId,
- event.clientSteerId,
- event.part?.quotes,
- ) ?? [])
- : liveSteerIds;
- const retryNextFrame = () => {
- if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- const frameId = run.scheduler.requestFrame(() => {
- run.steerRetryFrames.delete(frameId);
- if (sub.isCurrent()) {
- applySteerToMessages(event, attempt + 1, firstApplicationIds);
- }
- });
- run.steerRetryFrames.add(frameId);
- }
- };
- /** Same boundary as pending actions: land queued deltas before the
- * steer part is placed and synced. */
- flushPendingDeltas();
- const messages = getMessages() ?? [];
- const index = findSteerMessageIndex(messages, event, livePlaceholderIds());
- if (index < 0) {
- retryNextFrame();
- return;
- }
- const prefixLength = editPrefixLength();
- const updated = applySteerPart(
- messages[index],
- typeof event.index === 'number' && prefixLength > 0
- ? { ...event, index: event.index + prefixLength }
- : event,
- );
- if (updated !== messages[index]) {
- /** Stamped only when the inline part is actually committed, in the
- * same batch, so its first render sees the flag and plays the
- * one-shot draw-in (`SteerPart` consumes the id on mount). A
- * replayed event is referentially stable here and an abandoned
- * placement never reaches this branch, so neither can strand a
- * stale id that would animate a historical part on a later visit.
- * Only the id the part RENDERS with (`part.steerId`) is stamped:
- * the part consumes exactly that id, so a client alias would sit
- * in the set forever as dead weight. */
- const renderedSteerId = event.part?.steerId ?? event.steerId;
- if (firstApplicationIds.includes(renderedSteerId)) {
- setLiveAppliedSteerIds((prev) => appendAppliedSteerIds(prev, [renderedSteerId]));
- }
- const nextMessages = [...messages];
- nextMessages[index] = updated;
- setMessages(nextMessages);
- syncStepMessage(updated);
- syncSubmissionPlaceholder(updated);
- }
- };
-
- /**
- * Places an activity-label part at its claimed content index on the
- * in-flight response message. Fires twice per block (the empty
- * reservation at batch end, the generated label on resolve);
- * `applyActivityLabelPart` is referentially stable on duplicate replays
- * and refuses to overwrite filled text with a stale placeholder. Same
- * bounded next-frame retry as steers for the inject-before-render race.
- */
- const applyActivityLabelToMessages = (event: TActivityLabelEvent, attempt = 0) => {
- if (!sub.isCurrent()) {
- return;
- }
- const retryNextFrame = () => {
- if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- const frameId = run.scheduler.requestFrame(() => {
- run.activityLabelRetryFrames.delete(frameId);
- if (sub.isCurrent()) {
- applyActivityLabelToMessages(event, attempt + 1);
- }
- });
- run.activityLabelRetryFrames.add(frameId);
- }
- };
- /** Same boundary as pending actions and steers: land queued deltas
- * before the label part is placed and synced, or the later flush
- * would clobber it (and `syncStepMessage` would sync a pre-delta
- * copy back into the step handler's authoritative map). */
- flushPendingDeltas();
- const messages = getMessages() ?? [];
- const index = findActivityLabelMessageIndex(messages, event, livePlaceholderIds());
- if (index < 0) {
- retryNextFrame();
- return;
- }
- /** Edit-and-resubmit replays the kept prefix into the response before
- * the run starts, and the server indexes only the NEW content, so
- * run steps offset by that prefix (`useStepHandler`). The label index
- * is claimed in the same server-side space and needs the identical
- * shift, or it lands inside the prefix and overwrites kept content.
- *
- * Uses `editPrefixLength`, captured when the submission was built,
- * for the same reason `useStepHandler` does: a resume sync replaces
- * `initialResponse.content` with the server's completion-local
- * snapshot, so its length no longer describes the retained prefix.
- * Tool cards and the label heading them must land in one index
- * space: a label shifting differently from its tools would overwrite
- * another part, and a gap fill would miss its own reservation and
- * leave the placeholder pending forever. */
- const prefixLength = editPrefixLength();
- const phasePart = event.part as TActivityLabelEvent['part'] & {
- activity_label_type?: 'phase';
- activity_start_index?: number;
- activity_end_index?: number;
- };
- let offsetEvent = event;
- if (prefixLength > 0) {
- let offsetPart: TActivityLabelEvent['part'] & {
- activity_label_type?: 'phase';
- activity_start_index?: number;
- activity_end_index?: number;
- } = phasePart;
- if (
- phasePart.activity_label_type === 'phase' &&
- typeof phasePart.activity_start_index === 'number'
- ) {
- let activityStartIndex = phasePart.activity_start_index + prefixLength;
- const foldedFirstPart = run.editPrefixFirstPartFolded;
- const targetContent = messages[index]?.content;
- /** The step handler records an actual server-index-zero text/think
- * merge. An empty +prefix slot is insufficient evidence because
- * a delayed tool may not have materialized there yet. */
- if (
- phasePart.activity_start_index === 0 &&
- activityStartIndex > 0 &&
- foldedFirstPart &&
- targetContent?.[activityStartIndex - 1] != null
- ) {
- activityStartIndex -= 1;
- }
- offsetPart = {
- ...phasePart,
- activity_start_index: activityStartIndex,
- ...(typeof phasePart.activity_end_index === 'number' && {
- activity_end_index: offsetActivityPhaseBoundary(
- phasePart.activity_end_index,
- prefixLength,
- foldedFirstPart,
- ),
- }),
- };
- }
- offsetEvent = {
- ...event,
- index: event.index + prefixLength,
- part: offsetPart,
- };
- }
- const updated = applyActivityLabelPart(messages[index], offsetEvent);
- if (updated !== messages[index]) {
- const nextMessages = [...messages];
- nextMessages[index] = updated;
- setMessages(nextMessages);
- syncStepMessage(updated);
- syncSubmissionPlaceholder(updated);
- }
- };
-
- /** Patches a generated title onto its existing reasoning part. */
- const applyReasoningLabelToMessages = (event: TReasoningLabelEvent, attempt = 0) => {
- if (!sub.isCurrent()) {
- return;
- }
- const retryNextFrame = () => {
- if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- const frameId = run.scheduler.requestFrame(() => {
- run.activityLabelRetryFrames.delete(frameId);
- if (sub.isCurrent()) {
- applyReasoningLabelToMessages(event, attempt + 1);
- }
- });
- run.activityLabelRetryFrames.add(frameId);
- }
- };
- flushPendingDeltas();
- const messages = getMessages() ?? [];
- const messageIndex = findReasoningLabelMessageIndex(messages, event);
- if (messageIndex < 0) {
- retryNextFrame();
- return;
- }
- const prefixLength = editPrefixLength();
- let contentIndex = event.index + prefixLength;
- if (
- prefixLength > 0 &&
- event.index === 0 &&
- run.editPrefixFirstPartFolded &&
- messages[messageIndex]?.content?.[contentIndex - 1]?.type === ContentTypes.THINK
- ) {
- contentIndex -= 1;
- }
- const updated = applyReasoningLabel(messages[messageIndex], {
- ...event,
- index: contentIndex,
- });
- if (updated === messages[messageIndex]) {
- const part = messages[messageIndex]?.content?.[contentIndex];
- if (part?.type !== ContentTypes.THINK && attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
- retryNextFrame();
- }
- return;
- }
- const nextMessages = [...messages];
- nextMessages[messageIndex] = updated;
- setMessages(nextMessages);
- syncStepMessage(updated);
+ applyPendingAction: (action) => patcher.applyPendingAction(action),
};
logger.log('ResumableSSE', 'Subscribing to stream:', sub.url(), { isResume });
@@ -1186,7 +794,7 @@ export default function useResumableSSE(
run.identityConfirmed = true;
bindResponse(sub.submission);
createdHandler(data, sub.submission as EventSubmission);
- replayPreCreatedStepEvents();
+ patcher.replayPreCreatedStepEvents();
return;
}
@@ -1214,13 +822,13 @@ export default function useResumableSSE(
}
if (event.type === 'pending_action') {
- applyPendingActionToMessages(event.data);
+ patcher.applyPendingAction(event.data);
setIsSubmitting(true);
return;
}
if (event.type === 'steer_applied') {
- applySteerToMessages(event.data);
+ patcher.applySteer(event.data);
return;
}
@@ -1230,12 +838,12 @@ export default function useResumableSSE(
}
if (event.type === 'activity_label') {
- applyActivityLabelToMessages(event.data);
+ patcher.applyActivityLabel(event.data);
return;
}
if (event.type === 'reasoning_label') {
- applyReasoningLabelToMessages(event.data);
+ patcher.applyReasoningLabel(event.data);
return;
}
@@ -1438,7 +1046,7 @@ export default function useResumableSSE(
}
for (const prompt of pendingOAuthPrompts) {
- applyPendingOAuthPrompt(prompt, resumeSubmission);
+ patcher.applyPendingOAuthPrompt(prompt, resumeSubmission);
}
/**
@@ -1447,7 +1055,7 @@ export default function useResumableSSE(
* controls render after a reload or dropped connection.
*/
if (data.resumeState?.pendingAction) {
- applyPendingActionToMessages(data.resumeState.pendingAction as Agents.PendingAction);
+ patcher.applyPendingAction(data.resumeState.pendingAction as Agents.PendingAction);
}
/**
@@ -1505,15 +1113,15 @@ export default function useResumableSSE(
} else if (replayEvent.event === ApprovalEvents.ON_PENDING_ACTION) {
// A pause that landed after the resume snapshot must still render its
// controls (mirror the live handler), not fall through to stepHandler.
- applyPendingActionToMessages(replayEvent.data as Agents.PendingAction);
+ patcher.applyPendingAction(replayEvent.data as Agents.PendingAction);
} else if (replayEvent.event === SteerEvents.ON_STEER_APPLIED) {
- applySteerToMessages(replayEvent.data as TSteerAppliedEvent);
+ patcher.applySteer(replayEvent.data as TSteerAppliedEvent);
} else if (replayEvent.event === SteerEvents.ON_STEER_UPDATED) {
updateSteerChips(replayEvent.data as TSteerUpdatedEvent);
} else if (replayEvent.event === ActivityLabelEvents.ON_ACTIVITY_LABEL) {
- applyActivityLabelToMessages(replayEvent.data as TActivityLabelEvent);
+ patcher.applyActivityLabel(replayEvent.data as TActivityLabelEvent);
} else if (replayEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL) {
- applyReasoningLabelToMessages(replayEvent.data as TReasoningLabelEvent);
+ patcher.applyReasoningLabel(replayEvent.data as TReasoningLabelEvent);
} else if (replayEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL_ATTEMPT) {
// Durable provider-call budget reservations never render.
} else if (replayEvent.event != null) {
@@ -1555,15 +1163,15 @@ export default function useResumableSSE(
// and the subscription here; route it to the same handler as a live event
// so the approval / ask-user controls render (else the stream sits paused
// with no UI until a full status reload).
- applyPendingActionToMessages(pendingEvent.data as Agents.PendingAction);
+ patcher.applyPendingAction(pendingEvent.data as Agents.PendingAction);
} else if (pendingEvent.event === SteerEvents.ON_STEER_APPLIED) {
- applySteerToMessages(pendingEvent.data as TSteerAppliedEvent);
+ patcher.applySteer(pendingEvent.data as TSteerAppliedEvent);
} else if (pendingEvent.event === SteerEvents.ON_STEER_UPDATED) {
updateSteerChips(pendingEvent.data as TSteerUpdatedEvent);
} else if (pendingEvent.event === ActivityLabelEvents.ON_ACTIVITY_LABEL) {
- applyActivityLabelToMessages(pendingEvent.data as TActivityLabelEvent);
+ patcher.applyActivityLabel(pendingEvent.data as TActivityLabelEvent);
} else if (pendingEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL) {
- applyReasoningLabelToMessages(pendingEvent.data as TReasoningLabelEvent);
+ patcher.applyReasoningLabel(pendingEvent.data as TReasoningLabelEvent);
} else if (pendingEvent.event === ReasoningLabelEvents.ON_REASONING_LABEL_ATTEMPT) {
// Durable provider-call budget reservations never render.
} else if (pendingEvent.event != null) {
diff --git a/packages/chat/src/core/__fixtures__/resumable.ts b/packages/chat/src/core/__fixtures__/resumable.ts
new file mode 100644
index 0000000000..a9d1371ddb
--- /dev/null
+++ b/packages/chat/src/core/__fixtures__/resumable.ts
@@ -0,0 +1,137 @@
+import type { TMessage } from 'librechat-data-provider';
+import type { ResumableHost, ResumableScheduler, StreamStatusResponse } from '../resumable';
+
+/** A scheduler the test drives by hand. */
+export type ManualScheduler = {
+ scheduler: ResumableScheduler;
+ advance: (ms: number) => void;
+ flushFrames: () => void;
+ pending: () => number;
+ frames: () => number;
+};
+
+/** Timers and frames that run only when the test advances the clock or flushes frames. */
+export const createScheduler = (): ManualScheduler => {
+ let now = 0;
+ let nextId = 1;
+ const timers = new Map<number, { at: number; callback: () => void }>();
+ const frames = new Map<number, () => void>();
+ const scheduler: ResumableScheduler = {
+ setTimeout: (callback, delay) => {
+ const id = nextId++;
+ timers.set(id, { at: now + delay, callback });
+ return id as unknown as ReturnType<typeof setTimeout>;
+ },
+ clearTimeout: (handle) => {
+ timers.delete(handle as unknown as number);
+ },
+ requestFrame: (callback) => {
+ const id = nextId++;
+ frames.set(id, callback);
+ return id;
+ },
+ cancelFrame: (handle) => {
+ frames.delete(handle);
+ },
+ now: () => now,
+ };
+ const advance = (ms: number): void => {
+ now += ms;
+ for (const [id, timer] of [...timers]) {
+ if (timer.at <= now) {
+ timers.delete(id);
+ timer.callback();
+ }
+ }
+ };
+ /** Runs the frames requested so far; frames they request wait for the next flush. */
+ const flushFrames = (): void => {
+ for (const [id, callback] of [...frames]) {
+ frames.delete(id);
+ callback();
+ }
+ };
+ return {
+ scheduler,
+ advance,
+ flushFrames,
+ pending: (): number => timers.size,
+ frames: (): number => frames.size,
+ };
+};
+
+/** A host whose every member is a mock, with a message list it keeps for real. */
+export const createHost = (
+ fetchStatus: jest.Mock<Promise<StreamStatusResponse>, [string]> = jest.fn(),
+): ResumableHost => {
+ let messages: TMessage[] = [];
+ const host: ResumableHost = {
+ logger: { log: jest.fn(), warn: jest.fn(), error: jest.fn() },
+ visibility: { isVisible: () => true, subscribe: () => () => undefined },
+ fetchStatus,
+ subscribe: jest.fn(),
+ cache: {
+ invalidateMessages: jest.fn(async () => undefined),
+ fetchMessages: jest.fn(async () => [] as TMessage[]),
+ refreshConversation: jest.fn(async () => undefined),
+ refreshConversationLists: jest.fn(async () => undefined),
+ refreshPinnedConversations: jest.fn(async () => undefined),
+ setStreamStatus: jest.fn(),
+ removeStreamStatus: jest.fn(),
+ invalidateStreamStatus: jest.fn(),
+ addActiveJob: jest.fn(),
+ removeActiveJob: jest.fn(),
+ fetchConversation: jest.fn(async () => undefined),
+ setConversation: jest.fn(),
+ upsertConversation: jest.fn(),
+ removeConversation: jest.fn(),
+ },
+ pane: {
+ setIsSubmitting: jest.fn(),
+ setShowStopButton: jest.fn(),
+ setSubmission: jest.fn(),
+ setStreamId: jest.fn(),
+ setGenerationEpoch: jest.fn(() => true),
+ setPendingAction: jest.fn(),
+ clearComposerDrafts: jest.fn(),
+ publishRunEnd: jest.fn(),
+ clearDrainAfterAbort: jest.fn(),
+ refreshBalance: jest.fn(),
+ updateConversation: jest.fn(),
+ resolveDetachedEnd: jest.fn(() => ({ resolvable: false, end: null })),
+ },
+ steers: {
+ resolve: jest.fn(() => []),
+ markLiveApplied: jest.fn(),
+ seed: jest.fn(),
+ appliedIds: jest.fn(() => []),
+ settleApplied: jest.fn(),
+ convertToQueued: jest.fn(),
+ convertLocalToQueued: jest.fn(),
+ },
+ events: {
+ stepHandler: jest.fn(),
+ syncStepMessage: jest.fn(),
+ clearStepMaps: jest.fn(),
+ flushPendingDeltas: jest.fn(),
+ resetLive: jest.fn(),
+ showError: jest.fn(),
+ },
+ messages: {
+ get: jest.fn(() => messages),
+ set: jest.fn((next: TMessage[]) => {
+ messages = next;
+ }),
+ },
+ parts: {
+ applySteer: jest.fn((message) => message),
+ findSteerTarget: jest.fn(() => -1),
+ applyActivityLabel: jest.fn((message) => message),
+ findActivityLabelTarget: jest.fn(() => -1),
+ offsetActivityPhaseBoundary: jest.fn((index, prefix) => index + prefix),
+ applyReasoningLabel: jest.fn((message) => message),
+ findReasoningLabelTarget: jest.fn(() => -1),
+ },
+ };
+ return host;
+};
diff --git a/packages/chat/src/core/__tests__/failure.spec.ts b/packages/chat/src/core/__tests__/failure.spec.ts
index ee6d2a342c..ed26ed80c3 100644
--- a/packages/chat/src/core/__tests__/failure.spec.ts
+++ b/packages/chat/src/core/__tests__/failure.spec.ts
@@ -1,95 +1,7 @@
import type { TMessage, TSubmission } from 'librechat-data-provider';
-import type {
- ResumableHost,
- TerminalContext,
- ResumableScheduler,
- StreamStatusResponse,
-} from '../resumable';
+import type { TerminalContext, StreamStatusResponse } from '../resumable';
import { ResumableRun, ResumableSubscription, handleTransportFailure } from '../resumable';
-
-/** Timers that run only when the test advances the clock. */
-const createScheduler = () => {
- let now = 0;
- const timers = new Map<number, { at: number; callback: () => void }>();
- let nextId = 1;
- const scheduler: ResumableScheduler = {
- setTimeout: (callback, delay) => {
- const id = nextId++;
- timers.set(id, { at: now + delay, callback });
- return id as unknown as ReturnType<typeof setTimeout>;
- },
- clearTimeout: (handle) => {
- timers.delete(handle as unknown as number);
- },
- requestFrame: () => nextId++,
- cancelFrame: () => undefined,
- now: () => now,
- };
- const advance = (ms: number) => {
- now += ms;
- for (const [id, timer] of [...timers]) {
- if (timer.at <= now) {
- timers.delete(id);
- timer.callback();
- }
- }
- };
- return { scheduler, advance };
-};
-
-const createHost = (fetchStatus: jest.Mock<Promise<StreamStatusResponse>, [string]>) => {
- const host: ResumableHost = {
- logger: { log: jest.fn(), warn: jest.fn(), error: jest.fn() },
- visibility: { isVisible: () => true, subscribe: () => () => undefined },
- fetchStatus,
- subscribe: jest.fn(),
- cache: {
- invalidateMessages: jest.fn(async () => undefined),
- fetchMessages: jest.fn(async () => [] as TMessage[]),
- refreshConversation: jest.fn(async () => undefined),
- refreshConversationLists: jest.fn(async () => undefined),
- refreshPinnedConversations: jest.fn(async () => undefined),
- setStreamStatus: jest.fn(),
- removeStreamStatus: jest.fn(),
- invalidateStreamStatus: jest.fn(),
- addActiveJob: jest.fn(),
- removeActiveJob: jest.fn(),
- fetchConversation: jest.fn(async () => undefined),
- setConversation: jest.fn(),
- upsertConversation: jest.fn(),
- removeConversation: jest.fn(),
- },
- pane: {
- setIsSubmitting: jest.fn(),
- setShowStopButton: jest.fn(),
- setSubmission: jest.fn(),
- setStreamId: jest.fn(),
- setGenerationEpoch: jest.fn(() => true),
- setPendingAction: jest.fn(),
- clearComposerDrafts: jest.fn(),
- publishRunEnd: jest.fn(),
- clearDrainAfterAbort: jest.fn(),
- refreshBalance: jest.fn(),
- updateConversation: jest.fn(),
- resolveDetachedEnd: jest.fn(() => ({ resolvable: false, end: null })),
- },
- steers: {
- seed: jest.fn(),
- appliedIds: jest.fn(() => []),
- settleApplied: jest.fn(),
- convertToQueued: jest.fn(),
- convertLocalToQueued: jest.fn(),
- },
- events: {
- clearStepMaps: jest.fn(),
- flushPendingDeltas: jest.fn(),
- resetLive: jest.fn(),
- showError: jest.fn(),
- },
- messages: { get: jest.fn(() => []), set: jest.fn() },
- };
- return host;
-};
+import { createHost, createScheduler } from '../__fixtures__/resumable';
const submission = {
userMessage: { messageId: 'u-1', conversationId: 'c-1', isCreatedByUser: true } as TMessage,
diff --git a/packages/chat/src/core/__tests__/patches.spec.ts b/packages/chat/src/core/__tests__/patches.spec.ts
new file mode 100644
index 0000000000..aaa559ff70
--- /dev/null
+++ b/packages/chat/src/core/__tests__/patches.spec.ts
@@ -0,0 +1,138 @@
+import { ContentTypes } from 'librechat-data-provider';
+import type {
+ Agents,
+ TMessage,
+ TSubmission,
+ TSteerAppliedEvent,
+ TActivityLabelEvent,
+ TReasoningLabelEvent,
+} from 'librechat-data-provider';
+import { ResumableRun, ResponsePatcher, ResumableSubscription } from '../resumable';
+import { createHost, createScheduler } from '../__fixtures__/resumable';
+
+const response = {
+ messageId: 'u-1_',
+ parentMessageId: 'u-1',
+ conversationId: 'c-1',
+ isCreatedByUser: false,
+ content: [
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id: 'call-1', name: 'search', args: '{}', type: 'tool_call' },
+ },
+ ],
+} as unknown as TMessage;
+
+const submission = {
+ userMessage: { messageId: 'u-1', conversationId: 'c-1', isCreatedByUser: true } as TMessage,
+ initialResponse: response,
+ conversation: { conversationId: 'c-1' },
+} as TSubmission;
+
+const setup = (overrides: Partial<TSubmission> = {}) => {
+ const clock = createScheduler();
+ const host = createHost();
+ const run = new ResumableRun(clock.scheduler);
+ const target = { ...submission, ...overrides } as TSubmission;
+ run.submission = target;
+ const sub = new ResumableSubscription(run, host, {
+ streamId: 'c-1',
+ submission: target,
+ isResume: false,
+ generationProtocolVersion: 2,
+ });
+ sub.claim();
+ return { clock, host, run, sub, patcher: new ResponsePatcher(sub, host) };
+};
+
+const approval = {
+ actionId: 'action-1',
+ conversationId: 'c-1',
+ responseMessageId: 'u-1_',
+ payload: {
+ type: 'tool_approval',
+ action_requests: [{ tool_call_id: 'call-1', name: 'search', arguments: '{}' }],
+ review_configs: [{ tool_call_id: 'call-1', allowed_decisions: ['approve', 'reject'] }],
+ },
+} as unknown as Agents.PendingAction;
+
+describe('ResponsePatcher', () => {
+ it('tags the paused tool call with its approval once the response renders', () => {
+ const { clock, host, patcher } = setup();
+ patcher.applyPendingAction(approval);
+ expect(host.pane.setPendingAction).toHaveBeenCalledWith('c-1', approval);
+ expect(host.messages.set).not.toHaveBeenCalled();
+
+ host.messages.set([submission.userMessage, response]);
+ clock.flushFrames();
+ const tagged = host.messages.get()?.[1];
+ expect(tagged?.content?.[0]).toMatchObject({
+ tool_call: { approval: { actionId: 'action-1' } },
+ });
+ expect(host.events.syncStepMessage).toHaveBeenCalledWith(tagged);
+ expect(clock.frames()).toBe(0);
+ });
+
+ it('stops retrying once the subscription is superseded', () => {
+ const { clock, run, patcher } = setup();
+ patcher.applyPendingAction(approval);
+ run.stream = new AbortController();
+ clock.flushFrames();
+ expect(clock.frames()).toBe(0);
+ });
+
+ it('places a steer, settles its chip and marks the draw-in once', () => {
+ const { host, patcher, run } = setup();
+ host.messages.set([submission.userMessage, response]);
+ const placed = { ...response, content: [] } as TMessage;
+ (host.steers.resolve as jest.Mock).mockReturnValue(['steer-1']);
+ (host.parts.findSteerTarget as jest.Mock).mockReturnValue(1);
+ (host.parts.applySteer as jest.Mock).mockReturnValue(placed);
+ const event = {
+ conversationId: 'c-1',
+ steerId: 'steer-1',
+ index: 1,
+ part: { steerId: 'steer-1' },
+ } as unknown as TSteerAppliedEvent;
+ patcher.applySteer(event);
+ expect(host.steers.resolve).toHaveBeenCalledWith('c-1', 'steer-1', undefined, undefined);
+ expect(host.steers.markLiveApplied).toHaveBeenCalledWith('steer-1');
+ expect(host.messages.get()?.[1]).toBe(placed);
+ expect(run.submission?.initialResponse).toBe(placed);
+ });
+
+ it('shifts an activity label past an edited response prefix', () => {
+ const { host, patcher } = setup({ editedContent: {}, editPrefixLength: 2 } as TSubmission);
+ host.messages.set([submission.userMessage, response]);
+ (host.parts.findActivityLabelTarget as jest.Mock).mockReturnValue(1);
+ const event = {
+ index: 3,
+ part: { type: 'activity_label', activity_label_type: 'phase', activity_start_index: 1 },
+ } as unknown as TActivityLabelEvent;
+ patcher.applyActivityLabel(event);
+ expect(host.parts.applyActivityLabel).toHaveBeenCalledWith(
+ response,
+ expect.objectContaining({
+ index: 5,
+ part: expect.objectContaining({ activity_start_index: 3 }),
+ }),
+ );
+ });
+
+ it('retries a reasoning label until its think part exists', () => {
+ const { clock, host, patcher } = setup();
+ host.messages.set([submission.userMessage, response]);
+ (host.parts.findReasoningLabelTarget as jest.Mock).mockReturnValue(1);
+ patcher.applyReasoningLabel({ index: 0 } as TReasoningLabelEvent);
+ expect(clock.frames()).toBe(1);
+ });
+
+ it('replays the step events that arrived before created', () => {
+ const { host, sub, patcher } = setup();
+ const event = { event: 'on_run_step', data: { id: 'step-1' } } as never;
+ sub.preCreatedStepEvents.push(event);
+ patcher.replayPreCreatedStepEvents();
+ expect(host.events.stepHandler).toHaveBeenCalledWith(event, sub.liveSubmission());
+ expect(sub.preCreatedStepEvents).toHaveLength(0);
+ });
+});
diff --git a/packages/chat/src/core/__tests__/subscription.spec.ts b/packages/chat/src/core/__tests__/subscription.spec.ts
index 23ca110a63..578e0045e2 100644
--- a/packages/chat/src/core/__tests__/subscription.spec.ts
+++ b/packages/chat/src/core/__tests__/subscription.spec.ts
@@ -5,43 +5,9 @@ import type {
ChatTransport,
ChatTransportOptions,
} from 'librechat-data-provider';
-import type {
- PageVisibility,
- ResumableScheduler,
- SubscriptionTarget,
- StreamStatusResponse,
-} from '../resumable';
+import type { PageVisibility, SubscriptionTarget, StreamStatusResponse } from '../resumable';
import { ResumableRun, ResumableSubscription } from '../resumable';
-
-/** Timers and frames that run only when the test says so. */
-const createScheduler = () => {
- let now = 0;
- const timers = new Map<number, { at: number; callback: () => void }>();
- let nextId = 1;
- const scheduler: ResumableScheduler = {
- setTimeout: (callback, delay) => {
- const id = nextId++;
- timers.set(id, { at: now + delay, callback });
- return id as unknown as ReturnType<typeof setTimeout>;
- },
- clearTimeout: (handle) => {
- timers.delete(handle as unknown as number);
- },
- requestFrame: () => nextId++,
- cancelFrame: () => undefined,
- now: () => now,
- };
- const advance = (ms: number) => {
- now += ms;
- for (const [id, timer] of [...timers]) {
- if (timer.at <= now) {
- timers.delete(id);
- timer.callback();
- }
- }
- };
- return { scheduler, advance, pending: () => timers.size };
-};
+import { createScheduler } from '../__fixtures__/resumable';
const createVisibility = () => {
let visible = true;
diff --git a/packages/chat/src/core/__tests__/terminal.spec.ts b/packages/chat/src/core/__tests__/terminal.spec.ts
index 3b9b7d1b00..6f71332f50 100644
--- a/packages/chat/src/core/__tests__/terminal.spec.ts
+++ b/packages/chat/src/core/__tests__/terminal.spec.ts
@@ -1,10 +1,5 @@
import type { TMessage, TSubmission } from 'librechat-data-provider';
-import type {
- ResumableHost,
- TerminalContext,
- ResumableScheduler,
- StreamStatusResponse,
-} from '../resumable';
+import type { TerminalContext, StreamStatusResponse } from '../resumable';
import {
ResumableRun,
handoffToReplacement,
@@ -12,90 +7,7 @@ import {
authorizeTerminalTeardown,
reconcileGenerationLifecycle,
} from '../resumable';
-
-/** Timers that run only when the test advances the clock. */
-const createScheduler = () => {
- let now = 0;
- const timers = new Map<number, { at: number; callback: () => void }>();
- let nextId = 1;
- const scheduler: ResumableScheduler = {
- setTimeout: (callback, delay) => {
- const id = nextId++;
- timers.set(id, { at: now + delay, callback });
- return id as unknown as ReturnType<typeof setTimeout>;
- },
- clearTimeout: (handle) => {
- timers.delete(handle as unknown as number);
- },
- requestFrame: () => nextId++,
- cancelFrame: () => undefined,
- now: () => now,
- };
- const advance = (ms: number) => {
- now += ms;
- for (const [id, timer] of [...timers]) {
- if (timer.at <= now) {
- timers.delete(id);
- timer.callback();
- }
- }
- };
- return { scheduler, advance };
-};
-
-const createHost = (fetchStatus: jest.Mock<Promise<StreamStatusResponse>, [string]>) => {
- const host: ResumableHost = {
- logger: { log: jest.fn(), warn: jest.fn(), error: jest.fn() },
- visibility: { isVisible: () => true, subscribe: () => () => undefined },
- fetchStatus,
- subscribe: jest.fn(),
- cache: {
- invalidateMessages: jest.fn(async () => undefined),
- fetchMessages: jest.fn(async () => [] as TMessage[]),
- refreshConversation: jest.fn(async () => undefined),
- refreshConversationLists: jest.fn(async () => undefined),
- refreshPinnedConversations: jest.fn(async () => undefined),
- setStreamStatus: jest.fn(),
- removeStreamStatus: jest.fn(),
- invalidateStreamStatus: jest.fn(),
- addActiveJob: jest.fn(),
- removeActiveJob: jest.fn(),
- fetchConversation: jest.fn(async () => undefined),
- setConversation: jest.fn(),
- upsertConversation: jest.fn(),
- removeConversation: jest.fn(),
- },
- pane: {
- setIsSubmitting: jest.fn(),
- setShowStopButton: jest.fn(),
- setSubmission: jest.fn(),
- setStreamId: jest.fn(),
- setGenerationEpoch: jest.fn(() => true),
- setPendingAction: jest.fn(),
- clearComposerDrafts: jest.fn(),
- publishRunEnd: jest.fn(),
- clearDrainAfterAbort: jest.fn(),
- refreshBalance: jest.fn(),
- updateConversation: jest.fn(),
- resolveDetachedEnd: jest.fn(() => ({ resolvable: false, end: null })),
- },
- steers: {
- seed: jest.fn(),
- appliedIds: jest.fn(() => []),
- settleApplied: jest.fn(),
- convertToQueued: jest.fn(),
- convertLocalToQueued: jest.fn(),
- },
- events: {
- clearStepMaps: jest.fn(),
- flushPendingDeltas: jest.fn(),
- resetLive: jest.fn(),
- showError: jest.fn(),
- },
- messages: { get: jest.fn(() => []), set: jest.fn() },
- };
- return host;
-};
+import { createHost, createScheduler } from '../__fixtures__/resumable';
const submission = {
userMessage: { messageId: 'u-1', conversationId: 'c-1', isCreatedByUser: true } as TMessage,
diff --git a/packages/chat/src/core/resumable/host.ts b/packages/chat/src/core/resumable/host.ts
index 6594ec4fcf..d7b886b730 100644
--- a/packages/chat/src/core/resumable/host.ts
+++ b/packages/chat/src/core/resumable/host.ts
@@ -4,9 +4,14 @@ import type {
TSubmission,
TConversation,
TPendingSteer,
+ EventSubmission,
+ TSteerAppliedEvent,
+ TActivityLabelEvent,
+ TReasoningLabelEvent,
} from 'librechat-data-provider';
import type { GenerationProtocolVersion } from '../protocol';
import type { RunEnd } from '../steer/types';
+import type { StepEvent } from '../reducer';
/** Where a resumable run reports what it is doing. The app passes its own logger. */
export interface ResumableLogger {
@@ -99,6 +104,18 @@ export interface SteerQueueOptions {
/** The pane's steer chips: what the composer shows for steers sent into the running turn. */
export interface ResumableSteers {
+ /**
+ * Removes the pending chip once its steer is injected, records the ids as applied, and
+ * returns the ids applied for the first time.
+ */
+ resolve: (
+ conversationId: string,
+ steerId: string,
+ clientSteerId?: string,
+ appliedPartQuotes?: string[],
+ ) => string[];
+ /** Marks the steer whose inline part just mounted, so it plays its draw-in once. */
+ markLiveApplied: (steerId: string) => void;
/** Re-seeds the chips from the server's still-queued steers. */
seed: (
conversationId: string,
@@ -193,6 +210,9 @@ export interface ResumablePane {
/** What the event handlers that render the stream expose to the run. */
export interface ResumableEvents {
+ stepHandler: (event: StepEvent, submission: EventSubmission) => void;
+ /** Replaces the step handler's copy of a message the run patched outside it. */
+ syncStepMessage: (message: TMessage) => void;
clearStepMaps: () => void;
flushPendingDeltas: () => void;
/** Discards the live usage estimate for a run that stopped streaming. */
@@ -207,6 +227,33 @@ export interface ResumableMessages {
set: (messages: TMessage[]) => void;
}
+/**
+ * How the app places the parts a run reports beside its deltas onto a response message, and
+ * finds the response each one targets among the pane's messages.
+ */
+export interface ResumableParts {
+ applySteer: (message: TMessage, event: TSteerAppliedEvent) => TMessage;
+ findSteerTarget: (
+ messages: TMessage[],
+ event: TSteerAppliedEvent,
+ fallbackMessageIds?: readonly (string | null | undefined)[],
+ ) => number;
+ applyActivityLabel: (message: TMessage, event: TActivityLabelEvent) => TMessage;
+ findActivityLabelTarget: (
+ messages: TMessage[],
+ event: TActivityLabelEvent,
+ fallbackMessageIds?: readonly (string | null | undefined)[],
+ ) => number;
+ /** Shifts a phase label's end boundary past an edit's retained prefix. */
+ offsetActivityPhaseBoundary: (
+ endIndex: number,
+ prefixLength: number,
+ foldedFirstPart: boolean,
+ ) => number;
+ applyReasoningLabel: (message: TMessage, event: TReasoningLabelEvent) => TMessage;
+ findReasoningLabelTarget: (messages: TMessage[], event: TReasoningLabelEvent) => number;
+}
+
/** Everything a resumable run needs from the app it runs in. */
export interface ResumableHost extends SubscriptionHost {
cache: ResumableCache;
@@ -214,4 +261,5 @@ export interface ResumableHost extends SubscriptionHost {
steers: ResumableSteers;
events: ResumableEvents;
messages: ResumableMessages;
+ parts: ResumableParts;
}
diff --git a/packages/chat/src/core/resumable/index.ts b/packages/chat/src/core/resumable/index.ts
index d94f8f3c90..028a9c2508 100644
--- a/packages/chat/src/core/resumable/index.ts
+++ b/packages/chat/src/core/resumable/index.ts
@@ -11,3 +11,4 @@ export * from './reconcile';
export * from './failure';
export * from './missing';
export * from './ceiling';
+export * from './patches';
diff --git a/packages/chat/src/core/resumable/patches.ts b/packages/chat/src/core/resumable/patches.ts
new file mode 100644
index 0000000000..4581008457
--- /dev/null
+++ b/packages/chat/src/core/resumable/patches.ts
@@ -0,0 +1,431 @@
+import { StepTypes, StepEvents, ContentTypes, ToolCallTypes } from 'librechat-data-provider';
+import type {
+ Agents,
+ TMessage,
+ EventSubmission,
+ TSteerAppliedEvent,
+ TActivityLabelEvent,
+ TReasoningLabelEvent,
+} from 'librechat-data-provider';
+import type { ResumableSubscription } from './subscription';
+import type { ResumableHost } from './host';
+import {
+ applyPendingAction,
+ countTaggedApprovalParts,
+ findPendingActionMessageIndex,
+} from '../pending';
+
+/**
+ * Keep retrying across frames (not just once): message updates from the preceding created/step
+ * events are async and can take several frames under load, so a single retry would drop a
+ * valid pause and leave the run with no approval controls. Bounded so a genuinely-absent target
+ * can't spin forever.
+ */
+const PENDING_ACTION_MAX_RETRY_FRAMES = 120;
+
+type PhaseLabelPart = TActivityLabelEvent['part'] & {
+ activity_label_type?: 'phase';
+ activity_start_index?: number;
+ activity_end_index?: number;
+};
+
+/**
+ * Places what the stream reports beside its deltas (pending actions, injected steers, activity
+ * and reasoning labels, OAuth prompts) onto the in-flight response, retrying on later frames
+ * while the response placeholder has not rendered yet.
+ */
+export class ResponsePatcher {
+ constructor(
+ private readonly sub: ResumableSubscription,
+ private readonly host: ResumableHost,
+ ) {}
+
+ /** Replays the step events that arrived before `created` named the turn. */
+ replayPreCreatedStepEvents(): void {
+ const { sub } = this;
+ if (!sub.isCurrent() || sub.preCreatedStepEvents.length === 0) {
+ return;
+ }
+
+ const submission = sub.liveSubmission() as EventSubmission;
+ for (const event of sub.preCreatedStepEvents.splice(0)) {
+ this.host.events.stepHandler(event, submission);
+ }
+ }
+
+ /** Renders a pending MCP OAuth prompt as the tool call it pauses. */
+ applyPendingOAuthPrompt(prompt: Agents.PendingMCPOAuthPrompt, submission: EventSubmission): void {
+ const { stepHandler } = this.host.events;
+ const toolCall: Agents.ToolCall = {
+ id: prompt.toolCallId,
+ name: prompt.toolName,
+ args: '',
+ type: ToolCallTypes.TOOL_CALL,
+ };
+ const toolCallDelta: Agents.ToolCallChunk = {
+ id: prompt.toolCallId,
+ name: prompt.toolName,
+ args: '',
+ };
+ stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP,
+ data: {
+ id: prompt.stepId,
+ runId: prompt.runId,
+ index: prompt.index,
+ type: StepTypes.TOOL_CALLS,
+ stepDetails: {
+ type: StepTypes.TOOL_CALLS,
+ tool_calls: [toolCall],
+ },
+ },
+ },
+ submission,
+ );
+ stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_DELTA,
+ data: {
+ id: prompt.stepId,
+ delta: {
+ type: StepTypes.TOOL_CALLS,
+ tool_calls: [toolCallDelta],
+ auth: prompt.authURL,
+ expires_at: prompt.expiresAt,
+ },
+ },
+ },
+ submission,
+ );
+ }
+
+ /**
+ * Maps a pending action onto the in-flight response message so the approval / ask-user UI
+ * renders. Syncs the result back into the step handler's map so subsequent deltas build on
+ * the approval-tagged content rather than clobbering it.
+ *
+ * If the mapping is a no-op (the paused tool-call content part hasn't rendered yet, a
+ * pause-before-render race), retry on subsequent frames so the approval still attaches.
+ * `ask_user_question` always applies (it appends a synthetic part), so only `tool_approval`
+ * ever retries.
+ */
+ applyPendingAction(pendingAction: Agents.PendingAction, attempt = 0): void {
+ const { sub, host } = this;
+ const { run } = sub;
+ if (!sub.isCurrent()) {
+ return;
+ }
+ const pendingConversationId = pendingAction.conversationId ?? sub.conversationId();
+ host.pane.setPendingAction(pendingConversationId, pendingAction);
+ const retryNextFrame = () => {
+ if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
+ run.pendingActionRetry = run.scheduler.requestFrame(() => {
+ if (sub.isCurrent()) {
+ this.applyPendingAction(pendingAction, attempt + 1);
+ }
+ });
+ }
+ };
+ /** The pause card must attach to the same message state the stream
+ * produced: apply any queued delta before reading the cache, or the
+ * later flush would clobber the card (and `syncStepMessage` below
+ * would sync a pre-delta copy). */
+ host.events.flushPendingDeltas();
+ const messages = host.messages.get() ?? [];
+ const index = findPendingActionMessageIndex(messages, pendingAction);
+ if (index < 0) {
+ retryNextFrame();
+ return;
+ }
+ const updated = applyPendingAction(messages[index], pendingAction);
+ const changed = updated !== messages[index];
+ if (changed) {
+ const nextMessages = [...messages];
+ nextMessages[index] = updated;
+ host.messages.set(nextMessages);
+ host.events.syncStepMessage(updated);
+ }
+ // A `tool_approval` pause can carry several `action_requests` whose tool-call
+ // parts render on different frames; tagging only the first to arrive would leave
+ // late siblings with no approval card, and the resume route then 400s the partial
+ // batch ("every paused tool call must be decided"). Keep retrying (bounded) until
+ // EVERY paused call is tagged. `ask_user_question` applies its single synthetic
+ // part in one shot, so it only needs the original "did anything change" retry.
+ if (pendingAction.payload.type === 'tool_approval') {
+ const expected = pendingAction.payload.action_requests.length;
+ if (countTaggedApprovalParts(updated, pendingAction.actionId) < expected) {
+ retryNextFrame();
+ }
+ } else if (!changed) {
+ retryNextFrame();
+ }
+ }
+
+ /**
+ * The identities this pane may be rendering the in-flight response under before the first
+ * run step renames it to the server's pre-allocated id: the submission's placeholder (updated
+ * on `created`) and the padded form of the live user message. Read at call time, since
+ * `created` reassigns both.
+ */
+ private livePlaceholderIds(): (string | undefined)[] {
+ const { sub } = this;
+ return [
+ sub.submission.initialResponse?.messageId,
+ sub.userMessage?.messageId ? `${sub.userMessage.messageId}_` : undefined,
+ ];
+ }
+
+ /**
+ * A regenerate seeds the renamed response from `submission.initialResponse` rather than the
+ * store tail (an edited resubmission seeds from its content), so a part committed to the
+ * placeholder only in the store would be dropped by the first run step's rename. Keep the
+ * submission the step handler receives in step with the placeholder this pane mutated.
+ */
+ private syncSubmissionPlaceholder(updated: TMessage): void {
+ const { sub } = this;
+ if (updated.messageId !== sub.submission.initialResponse?.messageId) {
+ return;
+ }
+ sub.replaceSubmission({ ...sub.submission, initialResponse: updated });
+ }
+
+ /**
+ * Edit-and-resubmit keeps the retained prefix on the client while the server indexes only
+ * the NEW content, so every server-claimed index (run steps, labels and steers) shifts past
+ * it or lands inside the prefix and overwrites kept content. The captured length is used
+ * over the live array because a resume sync replaces `initialResponse.content` with the
+ * server's completion-local snapshot.
+ */
+ private editPrefixLength(): number {
+ const { sub } = this;
+ return sub.submission.editedContent != null && !sub.run.editPrefixCleared
+ ? (sub.submission.editPrefixLength ?? sub.submission.initialResponse?.content?.length ?? 0)
+ : 0;
+ }
+
+ /** Writes `updated` over the message at `index`, in the cache and the step handler's map. */
+ private commit(messages: TMessage[], index: number, updated: TMessage): void {
+ const nextMessages = [...messages];
+ nextMessages[index] = updated;
+ this.host.messages.set(nextMessages);
+ this.host.events.syncStepMessage(updated);
+ }
+
+ /**
+ * Places an injected steer part on the in-flight response message and resolves its pending
+ * chip. Same bounded next-frame retry as pending actions for the inject-before-render race
+ * (the assistant placeholder can land a few frames after the created event under load).
+ */
+ applySteer(event: TSteerAppliedEvent, attempt = 0, liveSteerIds: string[] = []): void {
+ const { sub, host } = this;
+ const { run } = sub;
+ if (!sub.isCurrent()) {
+ return;
+ }
+ const chipConvoId = event.conversationId ?? sub.conversationId();
+ /** The server's applied event settles ownership immediately. Rendering
+ * the inline part can wait for the target to mount, but leaving
+ * the chip pending during that wait lets an intervening error/final
+ * convert already-applied words into a duplicate queued message. */
+ const firstApplicationIds =
+ attempt === 0
+ ? (host.steers.resolve(
+ chipConvoId,
+ event.steerId,
+ event.clientSteerId,
+ event.part?.quotes,
+ ) ?? [])
+ : liveSteerIds;
+ const retryNextFrame = () => {
+ if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
+ const frameId = run.scheduler.requestFrame(() => {
+ run.steerRetryFrames.delete(frameId);
+ if (sub.isCurrent()) {
+ this.applySteer(event, attempt + 1, firstApplicationIds);
+ }
+ });
+ run.steerRetryFrames.add(frameId);
+ }
+ };
+ /** Same boundary as pending actions: land queued deltas before the
+ * steer part is placed and synced. */
+ host.events.flushPendingDeltas();
+ const messages = host.messages.get() ?? [];
+ const index = host.parts.findSteerTarget(messages, event, this.livePlaceholderIds());
+ if (index < 0) {
+ retryNextFrame();
+ return;
+ }
+ const prefixLength = this.editPrefixLength();
+ const updated = host.parts.applySteer(
+ messages[index],
+ typeof event.index === 'number' && prefixLength > 0
+ ? { ...event, index: event.index + prefixLength }
+ : event,
+ );
+ if (updated !== messages[index]) {
+ /** Stamped only when the inline part is actually committed, in the
+ * same batch, so its first render sees the flag and plays the
+ * one-shot draw-in (`SteerPart` consumes the id on mount). A
+ * replayed event is referentially stable here and an abandoned
+ * placement never reaches this branch, so neither can strand a
+ * stale id that would animate a historical part on a later visit.
+ * Only the id the part RENDERS with (`part.steerId`) is stamped:
+ * the part consumes exactly that id, so a client alias would sit
+ * in the set forever as dead weight. */
+ const renderedSteerId = event.part?.steerId ?? event.steerId;
+ if (firstApplicationIds.includes(renderedSteerId)) {
+ host.steers.markLiveApplied(renderedSteerId);
+ }
+ this.commit(messages, index, updated);
+ this.syncSubmissionPlaceholder(updated);
+ }
+ }
+
+ /**
+ * Places an activity-label part at its claimed content index on the in-flight response
+ * message. Fires twice per block (the empty reservation at batch end, the generated label on
+ * resolve); the applier is referentially stable on duplicate replays and refuses to
+ * overwrite filled text with a stale placeholder. Same bounded next-frame retry as steers
+ * for the inject-before-render race.
+ */
+ applyActivityLabel(event: TActivityLabelEvent, attempt = 0): void {
+ const { sub, host } = this;
+ const { run } = sub;
+ if (!sub.isCurrent()) {
+ return;
+ }
+ const retryNextFrame = () => {
+ if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
+ const frameId = run.scheduler.requestFrame(() => {
+ run.activityLabelRetryFrames.delete(frameId);
+ if (sub.isCurrent()) {
+ this.applyActivityLabel(event, attempt + 1);
+ }
+ });
+ run.activityLabelRetryFrames.add(frameId);
+ }
+ };
+ /** Same boundary as pending actions and steers: land queued deltas
+ * before the label part is placed and synced, or the later flush
+ * would clobber it (and `syncStepMessage` would sync a pre-delta
+ * copy back into the step handler's authoritative map). */
+ host.events.flushPendingDeltas();
+ const messages = host.messages.get() ?? [];
+ const index = host.parts.findActivityLabelTarget(messages, event, this.livePlaceholderIds());
+ if (index < 0) {
+ retryNextFrame();
+ return;
+ }
+ /** Edit-and-resubmit replays the kept prefix into the response before
+ * the run starts, and the server indexes only the NEW content, so
+ * run steps offset by that prefix (`useStepHandler`). The label index
+ * is claimed in the same server-side space and needs the identical
+ * shift, or it lands inside the prefix and overwrites kept content.
+ *
+ * Uses `editPrefixLength`, captured when the submission was built,
+ * for the same reason `useStepHandler` does: a resume sync replaces
+ * `initialResponse.content` with the server's completion-local
+ * snapshot, so its length no longer describes the retained prefix.
+ * Tool cards and the label heading them must land in one index
+ * space: a label shifting differently from its tools would overwrite
+ * another part, and a gap fill would miss its own reservation and
+ * leave the placeholder pending forever. */
+ const prefixLength = this.editPrefixLength();
+ const phasePart = event.part as PhaseLabelPart;
+ let offsetEvent = event;
+ if (prefixLength > 0) {
+ let offsetPart: PhaseLabelPart = phasePart;
+ if (
+ phasePart.activity_label_type === 'phase' &&
+ typeof phasePart.activity_start_index === 'number'
+ ) {
+ let activityStartIndex = phasePart.activity_start_index + prefixLength;
+ const foldedFirstPart = run.editPrefixFirstPartFolded;
+ const targetContent = messages[index]?.content;
+ /** The step handler records an actual server-index-zero text/think
+ * merge. An empty +prefix slot is insufficient evidence because
+ * a delayed tool may not have materialized there yet. */
+ if (
+ phasePart.activity_start_index === 0 &&
+ activityStartIndex > 0 &&
+ foldedFirstPart &&
+ targetContent?.[activityStartIndex - 1] != null
+ ) {
+ activityStartIndex -= 1;
+ }
+ offsetPart = {
+ ...phasePart,
+ activity_start_index: activityStartIndex,
+ ...(typeof phasePart.activity_end_index === 'number' && {
+ activity_end_index: host.parts.offsetActivityPhaseBoundary(
+ phasePart.activity_end_index,
+ prefixLength,
+ foldedFirstPart,
+ ),
+ }),
+ };
+ }
+ offsetEvent = {
+ ...event,
+ index: event.index + prefixLength,
+ part: offsetPart,
+ };
+ }
+ const updated = host.parts.applyActivityLabel(messages[index], offsetEvent);
+ if (updated !== messages[index]) {
+ this.commit(messages, index, updated);
+ this.syncSubmissionPlaceholder(updated);
+ }
+ }
+
+ /** Patches a generated title onto its existing reasoning part. */
+ applyReasoningLabel(event: TReasoningLabelEvent, attempt = 0): void {
+ const { sub, host } = this;
+ const { run } = sub;
+ if (!sub.isCurrent()) {
+ return;
+ }
+ const retryNextFrame = () => {
+ if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
+ const frameId = run.scheduler.requestFrame(() => {
+ run.activityLabelRetryFrames.delete(frameId);
+ if (sub.isCurrent()) {
+ this.applyReasoningLabel(event, attempt + 1);
+ }
+ });
+ run.activityLabelRetryFrames.add(frameId);
+ }
+ };
+ host.events.flushPendingDeltas();
+ const messages = host.messages.get() ?? [];
+ const messageIndex = host.parts.findReasoningLabelTarget(messages, event);
+ if (messageIndex < 0) {
+ retryNextFrame();
+ return;
+ }
+ const prefixLength = this.editPrefixLength();
+ let contentIndex = event.index + prefixLength;
+ if (
+ prefixLength > 0 &&
+ event.index === 0 &&
+ run.editPrefixFirstPartFolded &&
+ messages[messageIndex]?.content?.[contentIndex - 1]?.type === ContentTypes.THINK
+ ) {
+ contentIndex -= 1;
+ }
+ const updated = host.parts.applyReasoningLabel(messages[messageIndex], {
+ ...event,
+ index: contentIndex,
+ });
+ if (updated === messages[messageIndex]) {
+ const part = messages[messageIndex]?.content?.[contentIndex];
+ if (part?.type !== ContentTypes.THINK && attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {
+ retryNextFrame();
+ }
+ return;
+ }
+ this.commit(messages, messageIndex, updated);
+ }
+}