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'; +}