From 012f75513f9d50d9c1cbe8eeb1970a89a0d01d36 Mon Sep 17 00:00:00 2001 From: Arga Fairuz Date: Wed, 18 Nov 2026 00:11:57 +0700 Subject: [PATCH] fix(chat): stop the last reply of a turn from showing twice The final reply of a turn often appeared twice while streaming and became one again after a refresh. Recorded from the Claude SDK, the saved assistant message arrives before content_block_stop and message_stop, and the server re-sends it once the stop reason is known. Since the delta stream (#579), a stream end created a placeholder when none was left, so the late stops left an empty one behind. The re-sent message then claimed that placeholder before it was matched to the copy already on screen by id. A catch-up snapshot answered after newer events could also recreate a placeholder for text that was already saved: the reply carried the turn's whole message history and went out in chunks that live events overtook. A saved message now updates its copy by id before it may claim a placeholder, and replacing a placeholder settles that block: no later end, update or snapshot about it touches the transcript again. An end never creates a placeholder. The snapshot drops the message history, carries the stream's sequence so an older one can only extend existing text, and the server stops treating text as live before saving its message rather than after. A reasoning stop no longer emits a text end, and an end is sent only for a block still being streamed. The placeholder rules move to stream-placeholders.ts, where the recorded event order is replayed in tests. --- backend/chat/stream-manager.ts | 40 ++- backend/ws/chat/stream.ts | 21 +- frontend/services/chat/chat.service.ts | 220 +++------------- .../utils/chat/stream-placeholders.test.ts | 158 ++++++++++++ frontend/utils/chat/stream-placeholders.ts | 244 ++++++++++++++++++ 5 files changed, 469 insertions(+), 214 deletions(-) create mode 100644 frontend/utils/chat/stream-placeholders.test.ts create mode 100644 frontend/utils/chat/stream-placeholders.ts diff --git a/backend/chat/stream-manager.ts b/backend/chat/stream-manager.ts index 736a879d..1093036e 100644 --- a/backend/chat/stream-manager.ts +++ b/backend/chat/stream-manager.ts @@ -1166,24 +1166,31 @@ class StreamManager extends EventEmitter { }); } } else if (streamEvt.event === 'stop') { + // `end` re-sends a block's full text once, as the reconciliation + // point. Only for a block still being streamed: once its saved + // message has gone out (which clears the text below), the block is + // settled and an `end` for it could only bring a stale copy back. + // A reasoning stop never ends the text block. const lifecycle = streamEvt as StreamLifecycleEvent; - if (lifecycle.reasoning && streamState.currentReasoningText) { - this.emitStreamEvent(streamState, 'partial', { - processId: streamState.processId, - eventType: 'end', - block: streamState.reasoningBlock ?? 0, - partialText: streamState.currentReasoningText, - deltaText: '', - reasoning: true, - timestamp: new Date().toISOString() - }); + if (lifecycle.reasoning) { + if (streamState.currentReasoningText) { + this.emitStreamEvent(streamState, 'partial', { + processId: streamState.processId, + eventType: 'end', + block: streamState.reasoningBlock ?? 0, + partialText: streamState.currentReasoningText, + deltaText: '', + reasoning: true, + timestamp: new Date().toISOString() + }); + } streamState.currentReasoningText = ''; - } else { + } else if (streamState.currentPartialText) { this.emitStreamEvent(streamState, 'partial', { processId: streamState.processId, eventType: 'end', block: streamState.partialBlock ?? 0, - partialText: streamState.currentPartialText || '', + partialText: streamState.currentPartialText, deltaText: '', timestamp: new Date().toISOString() }); @@ -1240,6 +1247,13 @@ class StreamManager extends EventEmitter { const usage = assistantMsg.usage; const messageTimestamp = assistantMsg.createdAt; + // The text this message settles stops being "live" before it is + // saved, so a catch-up snapshot can never carry text whose saved + // message a reloaded transcript already shows. Only a root message + // settles the root's live text — a sub-agent's (parent-tagged) one + // finishing must not wipe the main turn's partial. + if (!assistantMsg.parent.toolUseId) streamState.currentPartialText = undefined; + let savedMsgId: string | undefined; let savedParentId: string | null = null; if (chatSessionId) { @@ -1252,8 +1266,6 @@ class StreamManager extends EventEmitter { savedParentId = saved?.parent_message_id || null; } - if (!assistantMsg.parent.toolUseId) streamState.currentPartialText = undefined; - streamState.messages.push({ processId: streamState.processId, message: assistantMsg as any, diff --git a/backend/ws/chat/stream.ts b/backend/ws/chat/stream.ts index a7d418aa..0292c9c4 100644 --- a/backend/ws/chat/stream.ts +++ b/backend/ws/chat/stream.ts @@ -636,7 +636,11 @@ export const streamHandler = createRouter() t.Literal('cancelled') ]), processId: t.String(), - messages: t.Array(t.Any()), + /** + * The stream's event sequence when this snapshot was taken. A client + * that already applied a newer event treats the snapshot as stale. + */ + seq: t.Optional(t.Number()), currentPartialText: t.Optional(t.String()), currentReasoningText: t.Optional(t.String()), /** The blocks those two texts belong to (see `chat:partial`). */ @@ -664,7 +668,6 @@ export const streamHandler = createRouter() streamId: data.chatSessionId || '', status: 'completed' as const, processId: '', - messages: [], currentPartialText: undefined, currentReasoningText: undefined, error: undefined, @@ -677,14 +680,12 @@ export const streamHandler = createRouter() streamId: streamState.streamId, status: streamState.status, processId: streamState.processId, - // Trim sub-agent noise from the catch-up buffer too (see trimSubAgentForWire). - // Buffer entries wrap the UnifiedMessage under `.message`; leave the rest intact. - messages: streamState.messages.map(entry => { - const wrapped = entry as { message?: UnifiedMessage }; - return wrapped?.message - ? { ...wrapped, message: trimSubAgentForWire(wrapped.message) } - : entry; - }), + // No message history here: the transcript is loaded through + // messages:list-page, and a long turn's history (screenshots + // included) made this reply megabytes — sent in chunks that newer + // live events overtook, so the snapshot landed after the messages + // it predated. + seq: streamState.eventSeq, currentPartialText: streamState.currentPartialText, currentReasoningText: streamState.currentReasoningText, partialBlock: streamState.partialBlock, diff --git a/frontend/services/chat/chat.service.ts b/frontend/services/chat/chat.service.ts index f5ed5a44..a329e19c 100644 --- a/frontend/services/chat/chat.service.ts +++ b/frontend/services/chat/chat.service.ts @@ -23,7 +23,7 @@ import { setRateLimit } from '$frontend/stores/ui/rate-limit.svelte'; import type { UnifiedMessage, AssistantMessage, ReasoningMessage } from '$shared/types/unified'; import type { StreamingMessage, OptimisticUserMessage, FrontendMessage } from '$frontend/stores/core/sessions.svelte'; import { debug } from '$shared/utils/logger'; -import { placeDelta } from '$frontend/utils/stream-delta'; +import { applyPartial, applySnapshot, placeSavedMessage, type SettledMap, type StreamSnapshot } from '$frontend/utils/chat/stream-placeholders'; import { INTERACTIVE_TOOLS, isWaitingForInteractiveInput } from '$shared/utils/interactive-input'; /** Chat service configuration */ @@ -76,6 +76,8 @@ const START_CONFIRM_TIMEOUT_MS = 60_000; class ChatService { private streams = new Map(); private lastEventSeq = new Map(); // Sequence-based deduplication (processId → last seq) + /** Streamed blocks a saved message has already replaced, per process (see stream-placeholders.ts). */ + private settledBlocks: SettledMap = new Map(); static loadingTexts: string[] = [ 'thinking', 'processing', 'analyzing', 'calculating', 'computing', @@ -334,6 +336,7 @@ class ChatService { ctx.state.streamCompleted = true; ctx.state.processId = null; + if (data.processId) this.settledBlocks.delete(data.processId); this.clearCancelSafetyTimer(ctx.sessionId); this.setProcessState({ isLoading: false, isWaitingInput: false, isCancelling: false }, ctx.sessionId); @@ -366,6 +369,7 @@ class ChatService { } ctx.state.streamCompleted = true; ctx.state.processId = null; + if (data.processId) this.settledBlocks.delete(data.processId); this.clearCancelSafetyTimer(ctx.sessionId); // Don't clear isCancelling here — it causes a race with presence. // The chat:cancelled WS event arrives before broadcastPresence() updates, @@ -399,6 +403,7 @@ class ChatService { // (e.g. from multiple subscriptions or late-arriving events with different processId/seq) ctx.state.streamCompleted = true; ctx.state.processId = null; + if (data.processId) this.settledBlocks.delete(data.processId); this.clearCancelSafetyTimer(ctx.sessionId); this.setProcessState({ isLoading: false, isWaitingInput: false, isCancelling: false }, ctx.sessionId); @@ -933,60 +938,18 @@ class ChatService { } } - // If this is an assistant message, replace the matching non-reasoning - // stream_event placeholder (leave any reasoning placeholder alone — - // it will be replaced by its own ReasoningMessage). - // Only root assistant messages may claim the root text placeholder. - // Agent/Workflow child messages already carry parent.toolUseId and must be - // pushed intact so the grouper embeds them directly into subActivities. - // Replacing a root placeholder with a child briefly renders that child at - // the root before the next reactive grouping pass relocates it. - if (message.type === 'assistant' && !message.parent?.toolUseId) { - for (let i = sessionState.messages.length - 1; i >= 0; i--) { - const msg = sessionState.messages[i]; - if (msg.type === 'stream_event' && !(msg as StreamingMessage).reasoning) { - sessionState.messages[i] = message; - this.checkInteractiveTools(message, ctx.sessionId); - return; - } - } - // No matching stream_event found, fall through to push - } - - // If this is a reasoning message, replace the matching reasoning - // stream_event placeholder. Fall back to inserting before the first - // non-reasoning stream_event so the display order stays reasoning → text. - // Same rule as assistant: a sub-agent's reasoning never claims the root - // placeholder — it is pushed intact and folded into its parent tool. - if (message.type === 'reasoning' && !message.parent?.toolUseId) { - for (let i = sessionState.messages.length - 1; i >= 0; i--) { - const msg = sessionState.messages[i]; - if (msg.type === 'stream_event' && (msg as StreamingMessage).reasoning) { - sessionState.messages[i] = message; - return; - } - } - const textStreamIdx = (sessionState.messages as FrontendMessage[]).findIndex( - m => m.type === 'stream_event' && !(m as StreamingMessage).reasoning - ); - if (textStreamIdx !== -1) { - (sessionState.messages as FrontendMessage[]).splice(textStreamIdx, 0, message); - return; - } - // No stream_event yet — fall through to dedup + push - } - - // Deduplicate: if a message with the same messageId already exists, update it in place - // (e.g., stopReason backfill arrives after initial assistant message was emitted) - if (message.messageId) { - const existingIdx = (sessionState.messages as FrontendMessage[]).findIndex( - (m) => m.type !== 'stream_event' && 'messageId' in m && m.messageId === message.messageId && !('optimistic' in m && m.optimistic) - ); - if (existingIdx !== -1) { - (sessionState.messages as FrontendMessage[])[existingIdx] = message; - return; - } - } + // A message already in the transcript (the stop-reason re-send, a repeated + // delivery) is updated in place by id BEFORE it may claim a placeholder — + // otherwise the re-send takes the empty placeholder a late stream event + // left behind and the reply shows twice. A root assistant/reasoning message + // then replaces its streaming placeholder and settles that block, so no + // later event about it can bring a placeholder back. Sub-agent messages + // (parent.toolUseId) never claim a root placeholder: they are pushed intact + // and the grouper folds them into their parent tool. + // See frontend/utils/chat/stream-placeholders.ts. + const placed = placeSavedMessage(sessionState.messages as FrontendMessage[], this.settledBlocks, message); + if (placed === 'claimed' && message.type === 'assistant') this.checkInteractiveTools(message, ctx.sessionId); + if (placed !== 'none') return; // Detect interactive tool_use blocks (e.g., AskUserQuestion) and set waiting status if (message.type === 'assistant') { @@ -1018,111 +981,15 @@ class ChatService { } /** - * The streaming placeholder for one (process, reasoning) pair, if any. - */ - private findStreamPlaceholder(processId: string, reasoning: boolean): StreamingMessage | undefined { - for (let i = sessionState.messages.length - 1; i >= 0; i--) { - const msg = sessionState.messages[i]; - if ( - msg.type === 'stream_event' && - (msg as StreamingMessage).processId === processId && - !!(msg as StreamingMessage).reasoning === reasoning - ) { - return msg as StreamingMessage; - } - } - return undefined; - } - - /** - * Insert an empty streaming placeholder. - * - * A reasoning placeholder goes BEFORE any existing non-reasoning stream_event - * so the on-screen order stays reasoning → text within a turn. Without this, - * engines that emit a preliminary non-reasoning stream_start at turn - * boundaries (e.g. OpenCode) leave a stale empty text placeholder ahead of the - * reasoning block, which then gets claimed by the next tool message and - * visually swaps reasoning behind the tool. - */ - private insertStreamPlaceholder( - processId: string, - reasoning: boolean, - block: number | undefined, - text = '', - createdAt = new Date().toISOString() - ): StreamingMessage { - const placeholder: StreamingMessage = { type: 'stream_event', processId, text, createdAt, reasoning, block }; - const messages = sessionState.messages as FrontendMessage[]; - if (reasoning) { - const textIdx = messages.findIndex((m) => m.type === 'stream_event' && !(m as StreamingMessage).reasoning); - if (textIdx !== -1) { - messages.splice(textIdx, 0, placeholder); - return messages[textIdx] as StreamingMessage; - } - } - messages.push(placeholder); - return messages[messages.length - 1] as StreamingMessage; - } - - /** - * Handle partial message events (streaming). - * - * An `update` carries only its delta and where it starts (`offset`), so the - * text is rebuilt here: a delta already covered is ignored, one that - * overlaps adds only its new tail, and one that starts past the end of what - * we hold means frames were missed — the text is re-read from the server - * rather than shown with a hole in it. `end` carries the full text and - * settles any remaining doubt. + * Handle partial message events (streaming) — see applyPartial in + * frontend/utils/chat/stream-placeholders.ts. A gap (frames missed) is + * repaired by re-reading the live text from the server. */ private handlePartialEvent(data: any, stream: SessionStreamState): void { // Ignore partials from a completed/cancelled stream if (stream.streamCompleted) return; - - const isReasoning = data.reasoning === true; - const block: number | undefined = typeof data.block === 'number' ? data.block : undefined; - let placeholder = this.findStreamPlaceholder(data.processId, isReasoning); - - // A newer block replaces the text; a stale block's frames are dropped. - if (placeholder && block !== undefined && placeholder.block !== undefined && placeholder.block !== block) { - if (block < placeholder.block) return; - placeholder.text = ''; - placeholder.block = block; - } - - if (data.eventType === 'start') { - if (placeholder) { - placeholder.text = ''; - placeholder.block = block; - } else { - this.insertStreamPlaceholder(data.processId, isReasoning, block, '', data.timestamp); - } - return; - } - - if (data.eventType === 'end') { - if (typeof data.partialText !== 'string') return; - if (placeholder) { - placeholder.text = data.partialText; - placeholder.block = block; - } else { - this.insertStreamPlaceholder(data.processId, isReasoning, block, data.partialText, data.timestamp); - } - return; - } - - if (data.eventType !== 'update') return; - if (!placeholder) { - // Missed the start (or joined mid-block): begin empty and let the offset - // check below decide whether this delta can be placed. - placeholder = this.insertStreamPlaceholder(data.processId, isReasoning, block, '', data.timestamp); - } - if (placeholder.block === undefined) placeholder.block = block; - - const delta: string = data.deltaText || ''; - const offset: number = typeof data.offset === 'number' ? data.offset : placeholder.text.length; - const placed = placeDelta(placeholder.text, offset, delta); - if (placed.kind === 'extended') placeholder.text = placed.text; - else if (placed.kind === 'gap') this.resyncStreamText(data.chatSessionId); + const result = applyPartial(sessionState.messages as FrontendMessage[], this.settledBlocks, data); + if (result === 'gap') this.resyncStreamText(data.chatSessionId); } /** Sessions with a stream-state re-read in flight, so a burst of gaps asks once. */ @@ -1144,41 +1011,14 @@ class ChatService { /** * Bring the streaming placeholders up to a server snapshot * (`chat:stream-state`): used to catch up when joining a running stream and - * to repair a gap. A snapshot only ever moves text forward — it is ignored - * for a block it is older than, and never shortens text that live frames - * have already extended. + * to repair a gap. A snapshot taken before events this client has already + * applied (`seq` older than the last one seen) may only extend a placeholder + * that still exists — see applySnapshot. */ - applyStreamSnapshot(snapshot: { - processId: string; - currentPartialText?: string; - currentReasoningText?: string; - partialBlock?: number; - reasoningBlock?: number; - }): void { - const apply = (reasoning: boolean, text: string | undefined, block: number | undefined) => { - if (!text) return; - const placeholder = this.findStreamPlaceholder(snapshot.processId, reasoning); - if (!placeholder) { - this.insertStreamPlaceholder(snapshot.processId, reasoning, block, text); - return; - } - if (block !== undefined && placeholder.block !== undefined && block < placeholder.block) return; - if (block === placeholder.block && placeholder.text.length > text.length && placeholder.text.startsWith(text)) return; - placeholder.text = text; - placeholder.block = block; - }; - - // Reasoning before text, so the display order matches live emission. - apply(true, snapshot.currentReasoningText, snapshot.reasoningBlock); - apply(false, snapshot.currentPartialText, snapshot.partialBlock); - - // Nothing streamed yet: an empty text placeholder keeps the loading indicator visible. - if (!snapshot.currentPartialText && !snapshot.currentReasoningText) { - const hasAnyStream = sessionState.messages.some( - (m) => m.type === 'stream_event' && (m as StreamingMessage).processId === snapshot.processId - ); - if (!hasAnyStream) this.insertStreamPlaceholder(snapshot.processId, false, snapshot.partialBlock); - } + applyStreamSnapshot(snapshot: StreamSnapshot & { seq?: number }): void { + const lastSeen = this.lastEventSeq.get(snapshot.processId); + const stale = typeof snapshot.seq === 'number' && lastSeen !== undefined && snapshot.seq < lastSeen; + applySnapshot(sessionState.messages as FrontendMessage[], this.settledBlocks, snapshot, stale); } /** diff --git a/frontend/utils/chat/stream-placeholders.test.ts b/frontend/utils/chat/stream-placeholders.test.ts new file mode 100644 index 00000000..49503c06 --- /dev/null +++ b/frontend/utils/chat/stream-placeholders.test.ts @@ -0,0 +1,158 @@ +/** + * Replays of real event orders against the streaming placeholders. The Claude + * order below was recorded from the SDK: the saved assistant message arrives + * BEFORE `content_block_stop` / `message_stop`, and the server re-sends the + * last message once its stop reason is known. That combination used to leave + * the final reply on screen twice until a refresh. + */ + +import { describe, it, expect } from 'bun:test'; +import type { UnifiedMessage } from '$shared/types/unified'; +import type { FrontendMessage } from '$frontend/stores/core/sessions.svelte'; +import { applyPartial, applySnapshot, placeSavedMessage, type SettledMap } from './stream-placeholders'; + +const P = 'proc-1'; + +function assistant(messageId: string, text: string, extra: Record = {}): UnifiedMessage { + return { + type: 'assistant', + messageId, + createdAt: '', + sessionId: 's', + parent: { messageId: null, sessionId: null, toolUseId: null }, + engine: {}, + content: [{ type: 'text', text }], + stopReason: null, + usage: null, + ...extra + } as unknown as UnifiedMessage; +} + +function reasoning(messageId: string, text: string): UnifiedMessage { + return { + type: 'reasoning', + messageId, + createdAt: '', + sessionId: 's', + parent: { messageId: null, sessionId: null, toolUseId: null }, + engine: {}, + text + } as unknown as UnifiedMessage; +} + +const start = (block: number, reasoningBlock = false) => ({ processId: P, eventType: 'start' as const, block, offset: 0, deltaText: '', ...(reasoningBlock && { reasoning: true }) }); +const update = (block: number, offset: number, deltaText: string, reasoningBlock = false) => ({ processId: P, eventType: 'update' as const, block, offset, deltaText, ...(reasoningBlock && { reasoning: true }) }); +const end = (block: number, partialText: string, reasoningBlock = false) => ({ processId: P, eventType: 'end' as const, block, partialText, deltaText: '', ...(reasoningBlock && { reasoning: true }) }); + +/** Apply a saved message the way chat.service does: place it, else append. */ +function save(messages: FrontendMessage[], settled: SettledMap, message: UnifiedMessage) { + if (placeSavedMessage(messages, settled, message) === 'none') messages.push(message as FrontendMessage); +} + +const kinds = (messages: FrontendMessage[]) => messages.map((m) => (m.type === 'stream_event' ? `stream:${(m as { text: string }).text}` : `${m.type}:${(m as { messageId: string }).messageId}`)); + +describe('final reply of a Claude turn', () => { + it('shows once, whatever arrives after the saved message', () => { + const messages: FrontendMessage[] = []; + const settled: SettledMap = new Map(); + + applyPartial(messages, settled, start(1)); // message_start + applyPartial(messages, settled, start(1, true)); // thinking block + applyPartial(messages, settled, update(1, 0, 'Let me think', true)); + save(messages, settled, reasoning('r1', 'Let me think')); + applyPartial(messages, settled, end(1, '')); // old server: thinking stop sent as a TEXT end + applyPartial(messages, settled, start(2)); // text block + applyPartial(messages, settled, update(2, 0, 'Xcode is ')); + applyPartial(messages, settled, update(2, 9, 'open.')); + save(messages, settled, assistant('m1', 'Xcode is open.')); // arrives before the block stops + applyPartial(messages, settled, end(2, '')); // content_block_stop + applyPartial(messages, settled, end(2, '')); // message_stop + save(messages, settled, assistant('m1', 'Xcode is open.', { stopReason: 'end_turn' })); // stop-reason re-send + + expect(kinds(messages)).toEqual(['reasoning:r1', 'assistant:m1']); + expect((messages[1] as { stopReason: string }).stopReason).toBe('end_turn'); + }); + + it('does not bring the reply back from a late end carrying its full text', () => { + const messages: FrontendMessage[] = []; + const settled: SettledMap = new Map(); + applyPartial(messages, settled, start(1)); + applyPartial(messages, settled, update(1, 0, 'done')); + save(messages, settled, assistant('m1', 'done')); + applyPartial(messages, settled, end(1, 'done')); + expect(kinds(messages)).toEqual(['assistant:m1']); + }); + + it('keeps streaming the next block after a tool call settled the previous one', () => { + const messages: FrontendMessage[] = []; + const settled: SettledMap = new Map(); + applyPartial(messages, settled, start(1)); + save(messages, settled, assistant('tool-call', '')); // a tool_use message claims the empty placeholder + applyPartial(messages, settled, end(1, '')); + messages.push({ type: 'user', messageId: 'tool-result' } as unknown as FrontendMessage); + applyPartial(messages, settled, start(2)); + applyPartial(messages, settled, update(2, 0, 'Next answer')); + expect(kinds(messages)).toEqual(['assistant:tool-call', 'user:tool-result', 'stream:Next answer']); + save(messages, settled, assistant('m2', 'Next answer')); + expect(kinds(messages)).toEqual(['assistant:tool-call', 'user:tool-result', 'assistant:m2']); + }); +}); + +describe('catch-up snapshots', () => { + it('never recreate a placeholder for a block a saved message settled', () => { + const messages: FrontendMessage[] = []; + const settled: SettledMap = new Map(); + applyPartial(messages, settled, start(1)); + applyPartial(messages, settled, update(1, 0, 'answer')); + save(messages, settled, assistant('m1', 'answer')); + // A snapshot taken before the message went out, answered after it. + applySnapshot(messages, settled, { processId: P, currentPartialText: 'answer', partialBlock: 1 }); + expect(kinds(messages)).toEqual(['assistant:m1']); + }); + + it('a stale snapshot only extends a placeholder that still exists', () => { + const settled: SettledMap = new Map(); + const empty: FrontendMessage[] = []; + applySnapshot(empty, settled, { processId: P, currentPartialText: 'partial', partialBlock: 3 }, true); + expect(empty).toHaveLength(0); + + const live: FrontendMessage[] = []; + applyPartial(live, settled, start(3)); + applyPartial(live, settled, update(3, 0, 'par')); + applySnapshot(live, settled, { processId: P, currentPartialText: 'partial', partialBlock: 3 }, true); + expect(kinds(live)).toEqual(['stream:partial']); + }); + + it('a fresh snapshot lets a late joiner see the text being written', () => { + const messages: FrontendMessage[] = [{ type: 'assistant', messageId: 'older' } as unknown as FrontendMessage]; + applySnapshot(messages, new Map(), { processId: P, currentPartialText: 'writing…', partialBlock: 4 }); + expect(kinds(messages)).toEqual(['assistant:older', 'stream:writing…']); + }); +}); + +describe('placement rules', () => { + it('a sub-agent message never claims the root placeholder', () => { + const messages: FrontendMessage[] = []; + const settled: SettledMap = new Map(); + applyPartial(messages, settled, start(1)); + applyPartial(messages, settled, update(1, 0, 'root text')); + const child = assistant('child', 'from a sub-agent', { parent: { messageId: null, sessionId: null, toolUseId: 'toolu_1' } }); + save(messages, settled, child); + expect(kinds(messages)).toEqual(['stream:root text', 'assistant:child']); + }); + + it('a delta past the end of the held text is reported as a gap', () => { + const messages: FrontendMessage[] = []; + const settled: SettledMap = new Map(); + applyPartial(messages, settled, start(1)); + applyPartial(messages, settled, update(1, 0, 'abc')); + expect(applyPartial(messages, settled, update(1, 10, 'xyz'))).toBe('gap'); + expect(kinds(messages)).toEqual(['stream:abc']); + }); + + it('an end never creates a placeholder', () => { + const messages: FrontendMessage[] = []; + applyPartial(messages, new Map(), end(7, 'orphan text')); + expect(messages).toHaveLength(0); + }); +}); diff --git a/frontend/utils/chat/stream-placeholders.ts b/frontend/utils/chat/stream-placeholders.ts new file mode 100644 index 00000000..9510974f --- /dev/null +++ b/frontend/utils/chat/stream-placeholders.ts @@ -0,0 +1,244 @@ +/** + * The live streaming placeholders of a chat transcript, and how stream events + * and saved messages land on them. + * + * A streamed block (one run of text or reasoning) is shown as a `stream_event` + * placeholder until the saved message carrying the same content replaces it. + * Events about a block can arrive AFTER that replacement — Claude sends the + * assistant message before `content_block_stop` and `message_stop`, a catch-up + * snapshot can be answered after newer events, and the server re-sends a + * message once its stop reason is known. Anything that recreated or reclaimed a + * placeholder at that point showed the reply twice until a refresh. + * + * So a block is SETTLED once a saved message has replaced its placeholder, and + * nothing about a settled block (or an older one) may touch the transcript + * again. A saved message that is already in the transcript is updated in place + * by id before it may claim any placeholder. + * + * Kept free of stores so the exact event order of a real turn can be replayed + * in tests; `chat.service` owns the state and calls in. + */ + +import type { UnifiedMessage } from '$shared/types/unified'; +import type { FrontendMessage, StreamingMessage } from '$frontend/stores/core/sessions.svelte'; +import { placeDelta } from '$frontend/utils/stream-delta'; + +/** The newest settled block per kind, per stream process. */ +export interface SettledBlocks { + text?: number; + reasoning?: number; +} + +export type SettledMap = Map; + +/** Whether `block` of this kind is at or below the newest settled one. */ +export function isSettled(settled: SettledMap, processId: string, reasoning: boolean, block: number | undefined): boolean { + if (block === undefined) return false; + const newest = settled.get(processId)?.[reasoning ? 'reasoning' : 'text']; + return newest !== undefined && block <= newest; +} + +/** Record that a saved message replaced the placeholder of `block`. */ +export function settle(settled: SettledMap, processId: string, reasoning: boolean, block: number | undefined): void { + if (block === undefined) return; + const entry = settled.get(processId) ?? {}; + const key = reasoning ? 'reasoning' : 'text'; + if (entry[key] === undefined || block > entry[key]!) entry[key] = block; + settled.set(processId, entry); +} + +function isPlaceholder(message: FrontendMessage): message is StreamingMessage { + return message.type === 'stream_event'; +} + +/** The streaming placeholder for one (process, reasoning) pair, if any. */ +export function findStreamPlaceholder(messages: FrontendMessage[], processId: string, reasoning: boolean): StreamingMessage | undefined { + for (let i = messages.length - 1; i >= 0; i--) { + const msg = messages[i]; + if (isPlaceholder(msg) && msg.processId === processId && !!msg.reasoning === reasoning) return msg; + } + return undefined; +} + +/** + * Insert an empty streaming placeholder. + * + * A reasoning placeholder goes BEFORE any existing non-reasoning stream_event + * so the on-screen order stays reasoning → text within a turn. Without this, + * engines that emit a preliminary non-reasoning stream_start at turn + * boundaries (e.g. OpenCode) leave a stale empty text placeholder ahead of the + * reasoning block, which then gets claimed by the next tool message and + * visually swaps reasoning behind the tool. + */ +export function insertStreamPlaceholder( + messages: FrontendMessage[], + processId: string, + reasoning: boolean, + block: number | undefined, + text = '', + createdAt = new Date().toISOString() +): StreamingMessage { + const placeholder: StreamingMessage = { type: 'stream_event', processId, text, createdAt, reasoning, block }; + if (reasoning) { + const textIdx = messages.findIndex((m) => isPlaceholder(m) && !m.reasoning); + if (textIdx !== -1) { + messages.splice(textIdx, 0, placeholder); + return messages[textIdx] as StreamingMessage; + } + } + messages.push(placeholder); + return messages[messages.length - 1] as StreamingMessage; +} + +export interface PartialEvent { + processId: string; + eventType: 'start' | 'update' | 'end'; + block?: number; + offset?: number; + deltaText?: string; + partialText?: string; + reasoning?: boolean; + timestamp?: string; +} + +/** + * Apply one `chat:partial` event. An `update` carries only its delta and where + * it starts (`offset`): a delta already covered is ignored, one that overlaps + * adds only its new tail, and one that starts past the end of what we hold is + * a gap the caller must repair from the server (returns `'gap'`). `end` carries + * the full text and only ever corrects a placeholder that still exists. + */ +export function applyPartial(messages: FrontendMessage[], settled: SettledMap, data: PartialEvent): 'ok' | 'gap' { + const reasoning = data.reasoning === true; + const block = typeof data.block === 'number' ? data.block : undefined; + if (isSettled(settled, data.processId, reasoning, block)) return 'ok'; + + let placeholder = findStreamPlaceholder(messages, data.processId, reasoning); + + // A newer block replaces the text; a stale block's frames are dropped. + if (placeholder && block !== undefined && placeholder.block !== undefined && placeholder.block !== block) { + if (block < placeholder.block) return 'ok'; + placeholder.text = ''; + placeholder.block = block; + } + + if (data.eventType === 'start') { + if (placeholder) { + placeholder.text = ''; + placeholder.block = block; + } else { + insertStreamPlaceholder(messages, data.processId, reasoning, block, '', data.timestamp); + } + return 'ok'; + } + + if (data.eventType === 'end') { + if (placeholder && typeof data.partialText === 'string') { + placeholder.text = data.partialText; + placeholder.block = block; + } + return 'ok'; + } + + if (data.eventType !== 'update') return 'ok'; + if (!placeholder) { + // Missed the start (or joined mid-block): begin empty and let the offset + // check below decide whether this delta can be placed. + placeholder = insertStreamPlaceholder(messages, data.processId, reasoning, block, '', data.timestamp); + } + if (placeholder.block === undefined) placeholder.block = block; + + const delta = data.deltaText || ''; + const offset = typeof data.offset === 'number' ? data.offset : placeholder.text.length; + const placed = placeDelta(placeholder.text, offset, delta); + if (placed.kind === 'extended') placeholder.text = placed.text; + return placed.kind === 'gap' ? 'gap' : 'ok'; +} + +export interface StreamSnapshot { + processId: string; + currentPartialText?: string; + currentReasoningText?: string; + partialBlock?: number; + reasoningBlock?: number; +} + +/** + * Bring the placeholders up to a server snapshot (`chat:stream-state`): used to + * catch up when joining a running stream and to repair a gap. A snapshot only + * ever moves text forward, never touches a settled block, and never shortens + * text that live frames have already extended. A snapshot older than events + * already applied (`stale`) may only extend a placeholder that still exists. + */ +export function applySnapshot(messages: FrontendMessage[], settled: SettledMap, snapshot: StreamSnapshot, stale = false): void { + const apply = (reasoning: boolean, text: string | undefined, block: number | undefined) => { + if (!text) return; + if (isSettled(settled, snapshot.processId, reasoning, block)) return; + const placeholder = findStreamPlaceholder(messages, snapshot.processId, reasoning); + if (!placeholder) { + if (!stale) insertStreamPlaceholder(messages, snapshot.processId, reasoning, block, text); + return; + } + if (block !== undefined && placeholder.block !== undefined && block < placeholder.block) return; + if (block === placeholder.block && placeholder.text.length > text.length && placeholder.text.startsWith(text)) return; + if (stale && (block !== placeholder.block || !text.startsWith(placeholder.text))) return; + placeholder.text = text; + placeholder.block = block; + }; + + // Reasoning before text, so the display order matches live emission. + apply(true, snapshot.currentReasoningText, snapshot.reasoningBlock); + apply(false, snapshot.currentPartialText, snapshot.partialBlock); + + // Nothing streamed yet: an empty text placeholder keeps the loading indicator visible. + if (!stale && !snapshot.currentPartialText && !snapshot.currentReasoningText) { + const hasAnyStream = messages.some((m) => isPlaceholder(m) && m.processId === snapshot.processId); + if (!hasAnyStream) insertStreamPlaceholder(messages, snapshot.processId, false, snapshot.partialBlock); + } +} + +/** + * Put a saved root assistant or reasoning message into the transcript. + * + * Returns `'updated'` when a message with the same id was already there (it is + * replaced in place — the stop-reason re-send, a duplicate delivery), `'claimed'` + * when it replaced its streaming placeholder (whose block is then settled), and + * `'none'` when the caller should append it. Sub-agent messages (with + * `parent.toolUseId`) never claim a root placeholder; they only dedupe by id. + */ +export function placeSavedMessage(messages: FrontendMessage[], settled: SettledMap, message: UnifiedMessage): 'updated' | 'claimed' | 'inserted' | 'none' { + const id = (message as { messageId?: string }).messageId; + if (id) { + const existing = messages.findIndex( + (m) => !isPlaceholder(m) && (m as { messageId?: string }).messageId === id && !('optimistic' in m && m.optimistic) + ); + if (existing !== -1) { + messages[existing] = message; + return 'updated'; + } + } + + const isRoot = !message.parent?.toolUseId; + if (!isRoot || (message.type !== 'assistant' && message.type !== 'reasoning')) return 'none'; + + const reasoning = message.type === 'reasoning'; + for (let i = messages.length - 1; i >= 0; i--) { + const msg = messages[i]; + if (isPlaceholder(msg) && !!msg.reasoning === reasoning) { + settle(settled, msg.processId, reasoning, msg.block); + messages[i] = message; + return 'claimed'; + } + } + + // A reasoning message with no placeholder of its own still goes before the + // text being streamed, so the order stays reasoning → text. + if (reasoning) { + const textIdx = messages.findIndex((m) => isPlaceholder(m) && !m.reasoning); + if (textIdx !== -1) { + messages.splice(textIdx, 0, message); + return 'inserted'; + } + } + return 'none'; +}