@flamingo-stack/openframe-frontend-core 0.0.243 → 0.0.244

package/src/components/chat/utils/__tests__/history-merge.test.ts

@@ -0,0 +1,339 @@
+import { describe, expect, it } from 'vitest'
+import type { MessageSegment } from '../../types'
+import {
+  computeHistoryPrepend,
+  flattenMessagePagesChronological,
+  maxPersistedStreamSeq,
+  type MergeableChatMessage,
+  mergeHistoryWithRealtime,
+} from '../history-merge'
+
+interface TestMessage extends MergeableChatMessage {
+  role: 'user' | 'assistant'
+}
+
+const txt = (s: string): MessageSegment[] => [{ type: 'text', text: s }]
+const t = (ms: number) => new Date(ms)
+const ids = (msgs: TestMessage[]) => msgs.map((m) => m.id)
+const batchSeg = {
+  type: 'approval_batch',
+  data: { approvalRequestId: 'req-9', toolCalls: [] },
+} as unknown as MessageSegment
+
+// Persisted history (Mongo ids), first fetched at t=1000
+const U0: TestMessage = { id: 'aaaa0001', role: 'user', content: 'first question', timestamp: t(500) }
+const A0: TestMessage = { id: 'aaaa0002', role: 'assistant', content: txt('first answer'), timestamp: t(600) }
+
+// A later turn that happened via realtime (optimistic user + streamed reply)
+const OPT1: TestMessage = { id: 'optimistic-2000-x', role: 'user', content: 'second question', timestamp: t(2000) }
+const SYN1: TestMessage = { id: 'assistant-2100-x', role: 'assistant', content: txt('second answer'), timestamp: t(2100) }
+
+// Persisted counterparts of that turn (what a FRESH fetch returns)
+const U1: TestMessage = { id: 'aaaa0003', role: 'user', content: 'second question', timestamp: t(2000) }
+const A1: TestMessage = { id: 'aaaa0004', role: 'assistant', content: txt('second answer'), timestamp: t(2100) }
+
+describe('mergeHistoryWithRealtime', () => {
+  it('keeps realtime messages newer than a STALE history snapshot (no data loss)', () => {
+    // Reopen a dialog: first merge runs against the cached snapshot fetched
+    // BEFORE the second turn existed. The completed reply must survive — the
+    // realtime transport will not redeliver chunks this client already consumed.
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [U0, A0, OPT1, SYN1],
+      streamingMessageId: null,
+      historyFetchedAt: 1000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, OPT1.id, SYN1.id])
+  })
+
+  it('replaces optimistic + synthetic messages with their persisted twins on a FRESH snapshot', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, A1],
+      existingMessages: [U0, A0, OPT1, SYN1],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, A1.id])
+  })
+
+  it('never drops the in-flight streaming synthetic', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1], // assistant turn not persisted yet
+      existingMessages: [U0, A0, OPT1, SYN1],
+      streamingMessageId: SYN1.id,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(SYN1.id)
+  })
+
+  it('dedupes mid-list synthetics against fresh history (no duplicated turns)', () => {
+    const OPT2: TestMessage = { id: 'optimistic-3000-x', role: 'user', content: 'third question', timestamp: t(3000) }
+    const SYN2: TestMessage = { id: 'assistant-3100-x', role: 'assistant', content: txt('third answer'), timestamp: t(3100) }
+    const U2: TestMessage = { id: 'aaaa0006', role: 'user', content: 'third question', timestamp: t(3000) }
+    const A2: TestMessage = { id: 'aaaa0007', role: 'assistant', content: txt('third answer'), timestamp: t(3100) }
+
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, A1, U2, A2],
+      existingMessages: [U0, A0, OPT1, SYN1, OPT2, SYN2],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, A1.id, U2.id, A2.id])
+  })
+
+  it('pins the more-complete synthetic over a partial history assistant (approval persistence race)', () => {
+    const partialHistA: TestMessage = { id: 'aaaa0005', role: 'assistant', content: [batchSeg], timestamp: t(2100) }
+    const fullSyn: TestMessage = {
+      id: 'assistant-2100-y',
+      role: 'assistant',
+      content: [...txt('second answer'), batchSeg],
+      timestamp: t(2100), // OLDER than the snapshot — pin must beat the freshness rule
+    }
+
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, partialHistA],
+      existingMessages: [U0, A0, OPT1, fullSyn],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(fullSyn.id)
+    expect(ids(merged)).not.toContain(partialHistA.id)
+  })
+
+  it('drops the synthetic when history is at least as complete for the same approval batch', () => {
+    const fullHistA: TestMessage = {
+      id: 'aaaa0005',
+      role: 'assistant',
+      content: [...txt('second answer'), batchSeg],
+      timestamp: t(2100),
+    }
+    const lesserSyn: TestMessage = {
+      id: 'assistant-2100-y',
+      role: 'assistant',
+      content: [batchSeg],
+      timestamp: t(9000), // even NEWER than the snapshot — explicit drop wins
+    }
+
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, fullHistA],
+      existingMessages: [U0, A0, OPT1, lesserSyn],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(fullHistA.id)
+    expect(ids(merged)).not.toContain(lesserSyn.id)
+  })
+
+  it('drops a replay-minted synthetic with a FRESH timestamp when seq coverage proves history contains it', () => {
+    // Chunk replay re-materializes an old turn into a synthetic stamped with
+    // the CURRENT time — newer than the snapshot, so the wall-clock rule
+    // would wrongly keep it next to its persisted twin (the "duplicated
+    // assistant message after navigating back" bug). Seq coverage is exact:
+    // history persisted through seq 80 >= client consumed through seq 80.
+    const replayedSyn: TestMessage = {
+      id: 'assistant-9999-r',
+      role: 'assistant',
+      content: txt('second answer'),
+      timestamp: t(9999), // newer than historyFetchedAt
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, A1],
+      existingMessages: [U0, A0, replayedSyn],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 80,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, A1.id])
+  })
+
+  it('keeps an old-looking synthetic when seq coverage proves history is BEHIND (persistence lag)', () => {
+    // Client consumed through seq 90 but history only persisted through 80 —
+    // dropping the synthetic would lose content, no matter how old its
+    // wall-clock timestamp looks.
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [U0, A0, OPT1, SYN1], // SYN1 timestamp 2100 <= fetchedAt
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 90,
+    })
+    expect(ids(merged)).toContain(SYN1.id)
+  })
+
+  it('falls back to the wall-clock rule when seq signals are unavailable', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, A1],
+      existingMessages: [U0, A0, OPT1, SYN1],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+      historyMaxStreamSeq: 0,
+      realtimeSeenStreamSeq: 0,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, A1.id])
+  })
+
+  it('keeps a just-sent optimistic message whose text repeats an older turn (stale snapshot)', () => {
+    // The user re-sends "first question" and the merge runs against a STALE
+    // snapshot (e.g. triggered by stream start). Content-dedup must not match
+    // it against the OLD persisted turn with the same text.
+    const repeat: TestMessage = { id: 'optimistic-9000-x', role: 'user', content: 'first question', timestamp: t(9000) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [U0, A0, repeat],
+      streamingMessageId: null,
+      historyFetchedAt: 1000,
+    })
+    expect(ids(merged)).toContain(repeat.id)
+  })
+
+  it('drops an optimistic repeat once the snapshot is fresh enough to contain its twin', () => {
+    const repeatPersisted: TestMessage = { id: 'bbbb0001', role: 'user', content: 'first question', timestamp: t(9000) }
+    const repeat: TestMessage = { id: 'optimistic-9000-x', role: 'user', content: 'first question', timestamp: t(9000) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, repeatPersisted],
+      existingMessages: [U0, A0, repeat],
+      streamingMessageId: null,
+      historyFetchedAt: 10_000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, repeatPersisted.id])
+  })
+
+  it('returns existing messages untouched when the history snapshot is empty', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [],
+      existingMessages: [OPT1, SYN1],
+      streamingMessageId: null,
+      historyFetchedAt: 10_000,
+    })
+    expect(merged).toEqual([OPT1, SYN1])
+  })
+
+  it('keeps a just-sent optimistic repeat even when seq coverage reports covered', () => {
+    // Optimistic messages are minted on send, not by chunks — seq coverage
+    // says nothing about them. Sent AFTER the snapshot → must survive even
+    // though its text matches an old persisted turn.
+    const repeat: TestMessage = { id: 'optimistic-9000-x', role: 'user', content: 'first question', timestamp: t(9000) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [U0, A0, repeat],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 80,
+    })
+    expect(ids(merged)).toContain(repeat.id)
+  })
+
+  it('pins the streaming twin even when it carries a persisted history id (adoption path)', () => {
+    // Chunk processors ADOPT an in-progress trailing assistant after a prior
+    // merge, so the streaming twin can have the SAME Mongo id as history's
+    // trailing message. The pin must beat the processed/raw id dedup or the
+    // turn vanishes from both lists.
+    const adopted: TestMessage = { id: 'aaaa0005', role: 'assistant', content: [batchSeg], timestamp: t(2100) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, adopted],
+      rawHistoryIds: new Set([U0.id, A0.id, U1.id, adopted.id]),
+      existingMessages: [U0, A0, adopted],
+      streamingMessageId: adopted.id,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, adopted.id])
+  })
+
+  it('never drops the streaming twin in the approval-batch resolution (pins it instead)', () => {
+    // History's trailing assistant fully persisted the approval turn, but the
+    // same batch id belongs to the LIVE streaming bubble (continuation after
+    // approve). Dropping it would orphan the host's streaming pointer and
+    // make continuation chunks invisible.
+    const fullHistA: TestMessage = {
+      id: 'aaaa0005',
+      role: 'assistant',
+      content: [...txt('second answer'), batchSeg],
+      timestamp: t(2100),
+    }
+    const liveTwin: TestMessage = { id: 'assistant-2100-y', role: 'assistant', content: [batchSeg], timestamp: t(2100) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, fullHistA],
+      existingMessages: [U0, A0, OPT1, liveTwin],
+      streamingMessageId: liveTwin.id,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(liveTwin.id)
+    expect(ids(merged)).not.toContain(fullHistA.id)
+  })
+
+  it('resolves the approval batch against the most recent twin when several share the batch id', () => {
+    const partialHistA: TestMessage = { id: 'aaaa0005', role: 'assistant', content: [batchSeg], timestamp: t(2100) }
+    const staleTwin: TestMessage = { id: 'assistant-1000-old', role: 'assistant', content: [batchSeg], timestamp: t(1000) }
+    const fullTwin: TestMessage = {
+      id: 'assistant-2100-y',
+      role: 'assistant',
+      content: [...txt('second answer'), batchSeg],
+      timestamp: t(2100),
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, partialHistA],
+      existingMessages: [U0, A0, staleTwin, fullTwin],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(fullTwin.id)
+    expect(ids(merged)).not.toContain(partialHistA.id)
+    expect(ids(merged)).not.toContain(staleTwin.id)
+  })
+
+  it('keeps welcome bubbles (never persisted server-side)', () => {
+    const welcome: TestMessage = { id: 'welcome-d1', role: 'assistant', content: 'Hi!', timestamp: t(100) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [welcome],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(welcome.id)
+  })
+})
+
+describe('computeHistoryPrepend', () => {
+  it('collects only messages above the first known id', () => {
+    const older: TestMessage = { id: 'aaaa0000', role: 'user', content: 'zeroth', timestamp: t(100) }
+    const result = computeHistoryPrepend([older, U0, A0], [U0, A0, SYN1])
+    expect(result).not.toBeNull()
+    expect(ids(result!.newMessages)).toEqual([older.id])
+    expect(result!.boundaryUpdates).toBeUndefined()
+  })
+
+  it('reports a boundary content refresh when the known boundary message changed', () => {
+    const updatedU0: TestMessage = { ...U0, content: 'first question (edited)' }
+    const result = computeHistoryPrepend([updatedU0, A0], [U0, A0])
+    expect(result).not.toBeNull()
+    expect(result!.newMessages).toEqual([])
+    expect(result!.boundaryMessageId).toBe(U0.id)
+    expect(result!.boundaryUpdates).toEqual({ content: 'first question (edited)' })
+  })
+
+  it('returns null when there is nothing to apply', () => {
+    expect(computeHistoryPrepend([U0, A0], [U0, A0])).toBeNull()
+  })
+})
+
+describe('page helpers', () => {
+  // Pages arrive DESC (newest page first, newest message first within a page).
+  const pages: { messages: { id: string; lastChunkStreamSeq?: number | null }[] }[] = [
+    { messages: [{ id: 'd', lastChunkStreamSeq: 40 }, { id: 'c', lastChunkStreamSeq: null }] },
+    { messages: [{ id: 'b', lastChunkStreamSeq: 20 }, { id: 'a' }] },
+  ]
+
+  it('flattenMessagePagesChronological reverses pages and messages into chronological order', () => {
+    expect(flattenMessagePagesChronological(pages).map((m) => m.id)).toEqual(['a', 'b', 'c', 'd'])
+    expect(flattenMessagePagesChronological(undefined)).toEqual([])
+  })
+
+  it('maxPersistedStreamSeq returns the highest stamped seq, 0 when absent', () => {
+    expect(maxPersistedStreamSeq(pages)).toBe(40)
+    expect(maxPersistedStreamSeq([{ messages: [{}] }])).toBe(0)
+    expect(maxPersistedStreamSeq(undefined)).toBe(0)
+  })
+})

package/src/components/chat/utils/history-merge.ts

@@ -0,0 +1,255 @@
+import type { ApprovalBatchSegment, MessageContent } from '../types'
+
+/**
+ * Reconciliation between persisted dialog history (processed GraphQL pages)
+ * and the realtime messages a chat client accumulated from streaming chunks.
+ *
+ * This is the missing middle piece of the chat pipeline this lib already
+ * owns: `processHistoricalMessages*` produces one stream, the realtime chunk
+ * processor / segment accumulator produces the other, and every host (Mingo,
+ * tickets, openframe-chat) needs to merge them whenever history is (re)fetched.
+ * Hand-rolled versions of this merge have produced both duplicated turns
+ * (synthetic kept alongside its persisted twin) and lost turns (synthetic
+ * trimmed against a stale snapshot that didn't contain its persisted twin
+ * yet) — the freshness rule below is the invariant that prevents both.
+ *
+ * Pure on purpose: the host owns WHEN to merge (react-query wiring, store
+ * writes), this module owns HOW.
+ */
+
+/** Minimal structural shape the merge needs — hosts pass their own message
+ *  type and get it back. */
+export interface MergeableChatMessage {
+  id: string
+  role: string
+  content: MessageContent
+  timestamp?: Date
+}
+
+/** Ids minted client-side by realtime chunk processors
+ *  (`assistant-<ts>-…` placeholder bubbles, `user-<ts>-…` peer messages,
+ *  `error-<ts>` stream errors). They never match the Mongo ObjectIds history
+ *  returns for the same turns. This is the cross-host contract every minting
+ *  site (lib `use-chat`, Mingo / tickets chunk processors, openframe-chat)
+ *  must keep matching — exported so it lives in exactly one place.
+ *  `welcome-` and `optimistic-` ids are intentionally NOT listed: welcome
+ *  bubbles are never persisted server-side, and optimistic user messages are
+ *  deduped by content below. */
+export const SYNTHETIC_REALTIME_ID_PREFIXES = ['assistant-', 'user-', 'error-'] as const
+
+function isSyntheticRealtimeId(id: string): boolean {
+  return SYNTHETIC_REALTIME_ID_PREFIXES.some((prefix) => id.startsWith(prefix))
+}
+
+/** Flattens DESC-sorted message pages (newest page first, newest message
+ *  first within a page) into one chronological list. */
+export function flattenMessagePagesChronological<T>(pages: readonly { messages: readonly T[] }[] | undefined): T[] {
+  if (!pages) return []
+  return [...pages].reverse().flatMap((page) => [...page.messages].reverse())
+}
+
+/** Max `lastChunkStreamSeq` across history pages — the history half of the
+ *  merge's seq-coverage signal (`HistoryMergeInput.historyMaxStreamSeq`),
+ *  also used by hosts as the JetStream replay start offset. 0 = unstamped. */
+export function maxPersistedStreamSeq(
+  pages: readonly { messages: readonly { lastChunkStreamSeq?: number | null }[] }[] | undefined,
+): number {
+  let max = 0
+  if (!pages) return max
+  for (const page of pages) {
+    for (const msg of page.messages) {
+      const seq = msg.lastChunkStreamSeq
+      if (typeof seq === 'number' && seq > max) max = seq
+    }
+  }
+  return max
+}
+
+export interface HistoryMergeInput<M extends MergeableChatMessage> {
+  /** Processed history in chronological order (all fetched pages). */
+  processedHistory: M[]
+  /** Raw history message ids across all fetched pages, when they can differ
+   *  from processed ids (processing may merge/rename). Optional — pass when
+   *  available so raw-id duplicates are filtered too. */
+  rawHistoryIds?: ReadonlySet<string>
+  /** Messages currently in the host store for this dialog (realtime + prior merges). */
+  existingMessages: M[]
+  /** Id of the in-flight streaming synthetic, if any. Never dropped.
+   *  IMPORTANT: hosts must not pass a STALE id here (e.g. a streaming entry
+   *  left behind by unmounting mid-stream) — gate it on the server-side
+   *  stream state when available, or the synthetic will be exempted forever. */
+  streamingMessageId: string | null
+  /** Epoch ms when the history pages were fetched (react-query `dataUpdatedAt`).
+   *  Wall-clock freshness fallback used when seq coverage (below) is unknown:
+   *  a synthetic created AFTER this instant cannot be represented in the
+   *  snapshot, so it must be kept. NOTE this heuristic is blind to chunk
+   *  REPLAY, which re-mints synthetics for old turns with fresh timestamps —
+   *  pass the seq fields whenever the host tracks them. */
+  historyFetchedAt: number
+  /** Max `lastChunkStreamSeq` across the raw history pages, when the backend
+   *  stamps it (see `maxPersistedStreamSeq`). Together with
+   *  `realtimeSeenStreamSeq` this gives an exact coverage signal that
+   *  replaces the wall-clock heuristic. */
+  historyMaxStreamSeq?: number
+  /** Highest stream seq this client has consumed for the dialog (live or
+   *  replayed chunks). */
+  realtimeSeenStreamSeq?: number
+}
+
+export function mergeHistoryWithRealtime<M extends MergeableChatMessage>(input: HistoryMergeInput<M>): M[] {
+  const {
+    processedHistory,
+    rawHistoryIds,
+    existingMessages,
+    streamingMessageId,
+    historyFetchedAt,
+    historyMaxStreamSeq = 0,
+    realtimeSeenStreamSeq = 0,
+  } = input
+
+  // An empty snapshot can't dedupe anything — merging would only let the
+  // freshness rules below wipe completed realtime messages (e.g. persistence
+  // lag on a fresh dialog). The realtime side stays the source of truth.
+  if (processedHistory.length === 0) return existingMessages
+
+  const processedIds = new Set(processedHistory.map((m) => m.id))
+
+  // Seq-based coverage: every synthetic is derived from consumed chunks, so
+  // when history's max persisted seq reaches the highest seq this client has
+  // consumed, ALL synthetics are represented in history (drop them); when it
+  // hasn't, history is provably behind (keep them ALL — even ones that look
+  // old by wall-clock, e.g. re-minted by a chunk replay). `null` = signal
+  // unavailable (legacy transport / backend without seq stamps) → fall back
+  // to the per-message wall-clock rule.
+  const seqCoverageKnown = realtimeSeenStreamSeq > 0 && historyMaxStreamSeq > 0
+  const historyCoversRealtime = seqCoverageKnown ? historyMaxStreamSeq >= realtimeSeenStreamSeq : null
+
+  // Persistence is asynchronous per-chunk: an assistant turn ending in an
+  // approval can have its APPROVAL_REQUEST document persisted before the
+  // leading THINKING/TEXT documents, so history can return a partial trailing
+  // assistant (just `[approval_batch]`) while the realtime store already has
+  // the full `[thinking, text, approval_batch]` synthetic. Resolve by
+  // `approval_batch.approvalRequestId`:
+  //   - if the existing twin is the LIVE streaming message, or has more
+  //     segments — drop the history assistant and pin the twin (realtime is
+  //     the more complete / still-growing copy).
+  //   - else (history is at least as complete) — drop the twin.
+  const trailing = processedHistory[processedHistory.length - 1]
+  const historyTrailingAssistant = trailing?.role === 'assistant' ? trailing : null
+  const historyBatchId =
+    historyTrailingAssistant && Array.isArray(historyTrailingAssistant.content)
+      ? ((historyTrailingAssistant.content.find((s) => s.type === 'approval_batch') as ApprovalBatchSegment | undefined)
+          ?.data?.approvalRequestId ?? null)
+      : null
+
+  let processedToUse = processedHistory
+  const pinnedSyntheticIds = new Set<string>()
+  const droppedSyntheticIds = new Set<string>()
+
+  if (historyBatchId) {
+    const batchTwins = existingMessages.filter(
+      (m) =>
+        m.role === 'assistant' &&
+        Array.isArray(m.content) &&
+        m.content.some(
+          (s) => s.type === 'approval_batch' && (s as ApprovalBatchSegment).data?.approvalRequestId === historyBatchId,
+        ),
+    )
+    // Prefer the live streaming twin; otherwise the most recent one (a stale
+    // replay-minted duplicate may precede it).
+    const existingWithSameBatch = batchTwins.find((m) => m.id === streamingMessageId) ?? batchTwins[batchTwins.length - 1]
+    if (existingWithSameBatch && Array.isArray(existingWithSameBatch.content)) {
+      const histSize = Array.isArray(historyTrailingAssistant?.content) ? historyTrailingAssistant.content.length : 0
+      const realtimeSize = existingWithSameBatch.content.length
+      if (existingWithSameBatch.id === streamingMessageId || realtimeSize > histSize) {
+        processedToUse = processedHistory.slice(0, -1)
+        pinnedSyntheticIds.add(existingWithSameBatch.id)
+      } else {
+        droppedSyntheticIds.add(existingWithSameBatch.id)
+      }
+    }
+  }
+
+  const realtimeMessages = existingMessages.filter((m) => {
+    // Pin wins over everything: the twin may carry a persisted Mongo id (the
+    // chunk processors ADOPT an in-progress trailing assistant after a prior
+    // merge), in which case `processedIds`/`rawHistoryIds` would drop it even
+    // though the pin branch above already removed history's copy — vanishing
+    // the whole turn.
+    if (pinnedSyntheticIds.has(m.id)) return true
+    if (droppedSyntheticIds.has(m.id)) return false
+    if (processedIds.has(m.id)) return false
+    if (rawHistoryIds?.has(m.id)) return false
+    if (m.role === 'user' && m.id.startsWith('optimistic-') && typeof m.content === 'string') {
+      // Content-dedup only when the message predates the snapshot — a
+      // just-sent message whose text repeats an earlier turn ("yes", "ok")
+      // must not vanish against stale history. Wall-clock, not seq coverage:
+      // optimistic messages are minted on send, never by chunk replay, so
+      // their timestamps are trustworthy.
+      const canBeInSnapshot = (m.timestamp?.getTime() ?? 0) <= historyFetchedAt
+      return !(canBeInSnapshot && processedToUse.some((pm) => pm.role === 'user' && pm.content === m.content))
+    }
+    // Freshness rule: a synthetic whose turn is represented in the snapshot
+    // (under its persisted Mongo id) must be dropped or the turn renders
+    // twice; one the snapshot cannot contain yet must be kept or a message
+    // the user already saw is lost, with no realtime replay to restore it
+    // (JetStream resumes after the highest seq this client has consumed).
+    // Decided by seq coverage when known, wall-clock otherwise.
+    if (isSyntheticRealtimeId(m.id) && m.id !== streamingMessageId) {
+      const covered =
+        historyCoversRealtime !== null ? historyCoversRealtime : (m.timestamp?.getTime() ?? 0) <= historyFetchedAt
+      if (covered) return false
+    }
+    return true
+  })
+
+  return [...processedToUse, ...realtimeMessages]
+}
+
+export interface HistoryPrependResult<M extends MergeableChatMessage> {
+  newMessages: M[]
+  boundaryMessageId?: string
+  boundaryUpdates?: { content: MessageContent }
+}
+
+/** Pagination path (an older page arrived via fetchNextPage): everything on
+ *  screen stays; collect only the messages above the first already-known id,
+ *  plus a content refresh for that boundary message if it changed. Returns
+ *  null when there is nothing to apply. */
+export function computeHistoryPrepend<M extends MergeableChatMessage>(
+  processedHistory: M[],
+  existingMessages: M[],
+): HistoryPrependResult<M> | null {
+  const existingIds = new Set(existingMessages.map((m) => m.id))
+  const newMessages: M[] = []
+  let boundaryMessageIndex = -1
+
+  for (let i = 0; i < processedHistory.length; i++) {
+    if (existingIds.has(processedHistory[i].id)) {
+      boundaryMessageIndex = i
+      break
+    }
+    newMessages.push(processedHistory[i])
+  }
+
+  let boundaryMessageId: string | undefined
+  let boundaryUpdates: { content: MessageContent } | undefined
+
+  if (boundaryMessageIndex >= 0) {
+    const boundaryMessage = processedHistory[boundaryMessageIndex]
+    const existingBoundary = existingMessages.find((m) => m.id === boundaryMessage.id)
+
+    if (existingBoundary) {
+      const existingContent = JSON.stringify(existingBoundary.content)
+      const newContent = JSON.stringify(boundaryMessage.content)
+
+      if (existingContent !== newContent) {
+        boundaryMessageId = boundaryMessage.id
+        boundaryUpdates = { content: boundaryMessage.content }
+      }
+    }
+  }
+
+  if (newMessages.length === 0 && !boundaryUpdates) return null
+  return { newMessages, boundaryMessageId, boundaryUpdates }
+}

package/src/components/chat/utils/index.ts

@@ -31,6 +31,18 @@ export {
   extractIncompleteMessageState,
 } from './extract-incomplete-message-state'
 
+// History <-> realtime reconciliation
+export {
+  mergeHistoryWithRealtime,
+  computeHistoryPrepend,
+  flattenMessagePagesChronological,
+  maxPersistedStreamSeq,
+  SYNTHETIC_REALTIME_ID_PREFIXES,
+  type MergeableChatMessage,
+  type HistoryMergeInput,
+  type HistoryPrependResult,
+} from './history-merge'
+
 // Tool call helpers
 export { getCommandText } from './tool-call-helpers'