Skip to content

The agent that grows with you

24.0 KB
Raw Blame
/**
 * ON-DEMAND OLDER-PAGE BACKFILL for the transcript window.
 *
 * Tail hydration (`getLatestSessionMessages`) loads only the newest page of a
 * session. "Show earlier" first pages the DOM budget, then the in-memory store
 * window — and when the whole in-memory transcript is materialized but the
 * REST hydration was truncated (`transcript-tail` bookkeeping), this module
 * fetches the next older page and merges it into the session store.
 *
 * Offsets follow the backend's `order: 'latest'` semantics: measured back
 * from the NEWEST persisted row. Rows persisted after hydration shift that
 * origin, so a fetched page can overlap rows we already hold and even extend
 * past the cached tail. Shared durable rows anchor the merge on either side;
 * the offset still advances by the fetched count, which self-corrects the
 * drift on the next page.
 */

import {
  dropPageFoldsCutByTheBoundary,
  dropPageRowsOfStoppedTurns,
  dropReceiptTurnsThePageHolds
} from '@/app/chat/transcript-receipt-turns'
import { transcriptRowIds } from '@/app/session/hooks/use-session-actions/pending-turn-identity'
import { getOlderSessionMessages, getSessionMessages, type ProfileScope } from '@/hermes'
import { type ChatMessage, chatMessageText, toChatMessages } from '@/lib/chat-messages'
import {
  recordTranscriptBackfillPage,
  tailStateFromPage,
  type TranscriptProfileScope,
  transcriptTailState
} from '@/store/transcript-tail'
import type { SessionMessage, SessionMessagesResponse } from '@/types/hermes'

/**
 * Compaction projection can stamp the session's opening USER row
 * `display_kind: hidden` (#96875): the durable store holds the greeting but
 * hydration drops the row, so paging to the very top of a compacted session
 * renders only the first assistant reply. When an older page carries the
 * opening user turn, clear the hidden stamp (keeping the content as the
 * display projection) so `toChatMessages` keeps it on screen. Only the
 * FIRST user row with content is unhidden — later hidden rows stay hidden
 * (model scaffolding, muted turns), and an opening row with no content
 * was never a greeting.
 */
export function unhideOpeningUserRows(messages: SessionMessage[]): SessionMessage[] {
  const openingIndex = messages.findIndex(message => message.role === 'user')

  if (openingIndex < 0) {
    return messages
  }

  const opening = messages[openingIndex]

  if (opening.display_kind !== 'hidden') {
    return messages
  }

  const content = opening.display_content ?? opening.content

  if (content == null || content === '') {
    return messages
  }

  return messages.map((message, index) => {
    if (index !== openingIndex) {
      return message
    }

    const { display_kind: _hidden, ...rest } = message

    return {
      ...rest,
      display_content: typeof content === 'string' ? content : String(content)
    }
  })
}

/** Older rows likely exist beyond what the in-memory store holds. */
export function transcriptBackfillAvailable(
  storedSessionId: null | string | undefined,
  profile?: TranscriptProfileScope
): boolean {
  return Boolean(transcriptTailState(storedSessionId, profile)?.possiblyTruncated)
}

/**
 * Merge a fetched page into the in-memory transcript, deduplicating rows
 * the store already holds (offset drift makes overlap normal — see module doc).
 * A page with no shared row is presumed older; overlapping pages use their
 * shared rows to place fresh messages before, within, or after the cached tail.
 * Preserves reference identity when nothing changes: handing React a fresh
 * array of the same messages re-renders the runtime for nothing.
 */
export function mergeOlderTranscriptPage(existing: ChatMessage[], olderPage: ChatMessage[]): ChatMessage[] {
  // Backfill only makes sense under an already-hydrated tail. An empty store
  // here means the session was swapped or wiped mid-fetch; prepending would
  // paint the older page as the whole conversation.
  if (existing.length === 0 || olderPage.length === 0) {
    return existing
  }

  const existingRowIndices = new Map<number, number>()
  const existingIdIndices = new Map<string, number>()
  // Part-level durable identity. Hydration folds a turn's tool rows and its
  // final reply into one bubble addressed by its FIRST source row
  // (message.rowId), while the final reply rides inside as a text part with
  // its own sourceRowId. Message-level matching alone misses that shared
  // final row and appends the fold next to the settled live bubble, so the
  // same reply renders twice (#123801).
  const existingPartRowIndices = new Map<number, number>()

  existing.forEach((message, index) => {
    if (message.rowId !== undefined) {
      existingRowIndices.set(message.rowId, index)
    }

    for (const part of message.parts) {
      if (part.sourceRowId !== undefined) {
        existingPartRowIndices.set(part.sourceRowId, index)
      }
    }

    existingIdIndices.set(message.id, index)
  })

  // The offset counts backwards from the newest durable row. While a long
  // turn persists, an "older" page can overlap the cached tail AND extend
  // beyond its end. Position fresh rows by the shared anchors, not by the
  // page's requested direction.
  const insertions = new Map<number, ChatMessage[]>()
  let pending: ChatMessage[] = []
  let lastAnchor = -1

  const heldRowAnchor = (row: number) => existingRowIndices.get(row) ?? existingPartRowIndices.get(row)

  // A fetched fold is only a duplicate when EVERY row it carries is already
  // held; one unheld row (narration beside a tool call) means dropping it
  // would lose that content, so it is appended as before.
  const partRowAnchor = (message: ChatMessage): number | undefined => {
    const anchors = transcriptRowIds(message).map(heldRowAnchor)

    if (!anchors.length || anchors.includes(undefined)) {
      return undefined
    }

    // With a rowId the fold is addressed by its FIRST source row, the same key
    // hydration uses. Without one its part rows are the only identity, and the
    // last of them is the turn's final reply — the row the settled live bubble
    // holds (#123801) — so preceding pending rows land before that bubble.
    return message.rowId !== undefined ? anchors[0] : anchors[anchors.length - 1]
  }

  for (const message of olderPage) {
    const anchor =
      (message.rowId !== undefined ? existingRowIndices.get(message.rowId) : undefined) ??
      existingIdIndices.get(message.id) ??
      partRowAnchor(message)

    if (anchor === undefined) {
      pending.push(message)

      continue
    }

    if (pending.length) {
      insertions.set(anchor, [...(insertions.get(anchor) ?? []), ...pending])
      pending = []
    }

    lastAnchor = anchor
  }

  if (pending.length) {
    const position = lastAnchor < 0 ? 0 : lastAnchor + 1
    insertions.set(position, [...(insertions.get(position) ?? []), ...pending])
  }

  if (insertions.size === 0) {
    return existing
  }

  const merged: ChatMessage[] = []

  for (let index = 0; index <= existing.length; index++) {
    const additions = insertions.get(index)

    if (additions) {
      merged.push(...additions)
    }

    if (index < existing.length) {
      merged.push(existing[index])
    }
  }

  return merged
}

/**
 * Re-anchor a refreshed TAIL onto a transcript that has backfilled older
 * pages. Background refreshes and post-turn rehydrates re-read only the
 * newest page; replacing the store with that page outright would silently
 * drop everything "Show earlier" already loaded. Find where the refreshed
 * tail begins inside the previous transcript and keep the older prefix when
 * that prefix is actually earlier. An anchor on the first on-screen row is a
 * real match: the page replaces the window from there. A page that already
 * contains every on-screen row replaces the window. When the page overlaps
 * the screen but that splice would put an older stored id after a newer one,
 * merge by stored id. The fresh page wins where both sides share an id, and
 * a row with no stored id stays at the end. A page that shares no stored id
 * is the transcript now on screen — a compaction rewrite or a different
 * session — and replaces the window.
 */
function pageCoversWindow(previous: ChatMessage[], refreshedIds: Set<string>, refreshedRowIds: Set<number>): boolean {
  return previous.every(
    message => (message.rowId !== undefined && refreshedRowIds.has(message.rowId)) || refreshedIds.has(message.id)
  )
}

function durableRowIds(messages: ChatMessage[]): Set<number> {
  return new Set(messages.flatMap(message => (message.rowId === undefined ? [] : [message.rowId])))
}

/** A text-only refresh can omit the live tool bubble after the turn settles. */
function retainCompletedTurnTools(messages: ChatMessage[], previous: ChatMessage[]): ChatMessage[] {
  const previousFinalIndex = previous.findLastIndex(
    message => message.role === 'assistant' && message.rowId !== undefined && Boolean(chatMessageText(message).trim())
  )

  if (previousFinalIndex < 0) {
    return messages
  }

  const previousFinal = previous[previousFinalIndex]

  const finalIndex = messages.findIndex(
    message => message.role === 'assistant' && message.rowId === previousFinal.rowId
  )

  if (finalIndex < 0 || chatMessageText(messages[finalIndex]).trim() !== chatMessageText(previousFinal).trim()) {
    return messages
  }

  const previousUserIndex = previous.findLastIndex(
    (message, index) => index < previousFinalIndex && message.role === 'user'
  )

  const userIndex = messages.findLastIndex((message, index) => index < finalIndex && message.role === 'user')

  if (
    previousUserIndex < 0 ||
    userIndex < 0 ||
    previous[previousUserIndex].rowId === undefined ||
    previous[previousUserIndex].rowId !== messages[userIndex].rowId
  ) {
    return messages
  }

  const existingIds = new Set(
    messages
      .slice(userIndex + 1, finalIndex + 1)
      .flatMap(message => message.parts.flatMap(part => (part.type === 'tool-call' ? [part.toolCallId] : [])))
  )

  const missing = previous.slice(previousUserIndex + 1, previousFinalIndex + 1).flatMap(message =>
    message.parts.filter(part => {
      if (part.type !== 'tool-call' || (part.result === undefined && part.completedAt === undefined)) {
        return false
      }

      if (existingIds.has(part.toolCallId)) {
        return false
      }

      existingIds.add(part.toolCallId)

      return true
    })
  )

  if (!missing.length) {
    return messages
  }

  return messages.map((message, index) =>
    index === finalIndex ? { ...message, parts: [...missing, ...message.parts] } : message
  )
}

function sharesDurableRow(first: ChatMessage[], second: ChatMessage[]): boolean {
  const rowIds = durableRowIds(first)

  return second.some(message => message.rowId !== undefined && rowIds.has(message.rowId))
}

interface StoredRowSlot {
  message: ChatMessage
  /** Rows without a stored id (e.g. a page-local tool fold) that precede this row. */
  leading: ChatMessage[]
}

/**
 * Stored-id merge for a page that overlaps the window but does not anchor in
 * front of it. A row with no stored id travels with the next stored row after
 * it, so a page-local fold stays in front of the row it preceded. Rows with no
 * stored id after the last stored row stay at the end (page first, then live).
 */
function mergeOverlappingTail(previous: ChatMessage[], refreshedTail: ChatMessage[]): ChatMessage[] {
  // Compaction, rewind, or a different session arrives as new stored ids.
  // This function is the path that puts that page on screen.
  if (!sharesDurableRow(previous, refreshedTail)) {
    return refreshedTail
  }

  const refreshedIds = new Set(refreshedTail.map(message => message.id))
  const refreshedBySource = new Map<number, ChatMessage>()

  for (const message of refreshedTail) {
    for (const rowId of transcriptRowIds(message)) {
      refreshedBySource.set(rowId, message)
    }
  }

  const byRowId = new Map<number, StoredRowSlot>()
  // A turn the page holds whole is the page's to draw, whatever stored ids
  // its live rows managed to bind (see transcript-receipt-turns).
  const receiptDrop = dropReceiptTurnsThePageHolds(previous, refreshedTail)
  // Local notices of a dropped turn, keyed by the page row they precede.
  const anchored = new Map<number, ChatMessage[]>()

  const anchorNotice = (message: ChatMessage): boolean => {
    const anchor = receiptDrop.noticeAnchors.get(message.id)
    const slot = anchor === undefined ? undefined : refreshedBySource.get(anchor)?.rowId

    if (slot === undefined) {
      return false
    }

    anchored.set(slot, [...(anchored.get(slot) ?? []), message])

    return true
  }

  const place = (messages: ChatMessage[], fresh: boolean): ChatMessage[] => {
    let pending: ChatMessage[] = []

    for (const message of messages) {
      const sourceIds = transcriptRowIds(message)
      const folded = sourceIds.length ? refreshedBySource.get(sourceIds[0]) : undefined

      // A completed live reply is addressed by its final row; hydration can
      // fold that row into an earlier tool bubble. Give both the fold's slot,
      // so the fresh copy replaces the live one without losing its leading rows.
      // Partial/live bubbles may still hold an uncommitted suffix.
      const covered =
        !fresh &&
        !message.pending &&
        !message.interim &&
        !message.error &&
        message.durableComplete !== false &&
        message.persistedTurn?.complete !== false &&
        folded?.role === message.role &&
        sourceIds.every(id => refreshedBySource.get(id) === folded)

      const rowId = covered ? (folded?.rowId ?? message.rowId) : message.rowId

      if (rowId === undefined) {
        // The fresh page's copy of an unstored row wins over the window's.
        if (fresh || !refreshedIds.has(message.id)) {
          pending.push(message)
        }

        continue
      }

      const existing = byRowId.get(rowId)

      if (!fresh && existing) {
        pending = []

        continue
      }

      // The fresh page replaces the row; keep the window's leading rows when
      // the page brought none of its own for it.
      const leading = fresh && existing && pending.length === 0 ? existing.leading : pending
      byRowId.set(rowId, { message, leading })
      pending = []
    }

    return pending
  }

  const previousTrailing = place(
    receiptDrop.window.filter(message => !anchorNotice(message)),
    false
  )

  const freshRows = dropPageRowsOfStoppedTurns(previous, dropPageFoldsCutByTheBoundary(previous, refreshedTail))
  const refreshedTrailing = place(freshRows, true)

  const stored = [...byRowId.entries()]
    .sort((left, right) => left[0] - right[0])
    .flatMap(([rowId, { leading, message }]) => [...leading, ...(anchored.get(rowId) ?? []), message])

  // A notice whose anchor row the page dropped after all still stays on screen.
  const unplaced = [...anchored.entries()].filter(([rowId]) => !byRowId.has(rowId)).flatMap(([, notices]) => notices)

  return [...stored, ...refreshedTrailing, ...previousTrailing, ...unplaced]
}

export function graftRefreshedTailOntoBackfill(refreshedTail: ChatMessage[], previous: ChatMessage[]): ChatMessage[] {
  if (refreshedTail.length === 0 || previous.length === 0) {
    return refreshedTail
  }

  // The first rendered message can be a page-local tool fold whose id is not
  // durable. Anchor on the first shared persisted row anywhere in the page.
  const refreshedRowIds = durableRowIds(refreshedTail)

  const firstDurable = refreshedTail.find(message => message.rowId !== undefined)

  const anchor = firstDurable === undefined ? -1 : previous.findIndex(message => message.rowId === firstDurable.rowId)

  const anchorRowId = firstDurable?.rowId

  // A hit on the first row, or a hit after a prefix whose stored ids are all
  // earlier, is the backfill anchor. A hit further down on a row that was
  // glued on late is not: the prefix is newer than the match.
  const prefixIsEarlier =
    anchor > 0 &&
    anchorRowId !== undefined &&
    previous.slice(0, anchor).every(message => message.rowId === undefined || message.rowId < anchorRowId)

  if (anchor === 0) {
    return retainCompletedTurnTools(refreshedTail, previous)
  }

  if (prefixIsEarlier) {
    // A page-local tool fold can sit in front of the anchor on BOTH sides: the
    // window's copy was hydrated from the same page, and the refreshed page
    // re-emits that row with the same id. Keeping both copies makes the graft
    // non-idempotent — the refreshed window comes back one row longer than the
    // local window on every read, and a duplicate fold accumulates per refresh.
    // Drop only the prefix copies the page already carries. Every durable
    // prefix row keeps travelling in front of the refreshed tail, and so does
    // an unstored row the page has no copy of (it can only have come from an
    // older page).
    const refreshedIds = new Set(refreshedTail.map(message => message.id))

    const prefix = previous
      .slice(0, anchor)
      .filter(message => message.rowId !== undefined || !refreshedIds.has(message.id))

    return retainCompletedTurnTools(prefix.length ? [...prefix, ...refreshedTail] : refreshedTail, previous)
  }

  const refreshedIds = new Set(refreshedTail.map(message => message.id))

  // The page already contains everything on screen, including a live row the
  // tail really did cover. Take the page. This is what keeps a finished reply
  // through a long tool turn.
  if (pageCoversWindow(previous, refreshedIds, refreshedRowIds)) {
    return retainCompletedTurnTools(refreshedTail, previous)
  }

  return retainCompletedTurnTools(mergeOverlappingTail(previous, refreshedTail), previous)
}

const REFRESH_OVERLAP_PAGE_LIMIT = 4

/**
 * Reader for the pages older than a refreshed newest page. Paging follows the
 * transcript-tail rules: it starts at the page's own offset and stops once a
 * page comes back short, or without pagination metadata (a legacy backend
 * already returned everything).
 */
export function olderPageReader(
  storedSessionId: string,
  scope: ProfileScope,
  page: null | Pick<SessionMessagesResponse, 'messages' | 'pagination'> | undefined
): () => Promise<ChatMessage[]> {
  let state = page ? tailStateFromPage(page) : undefined

  return async () => {
    if (!state?.possiblyTruncated) {
      return []
    }

    const older = await getOlderSessionMessages(storedSessionId, scope, state.nextOffset)
    state = tailStateFromPage(older)

    return toChatMessages(older.messages)
  }
}

/**
 * A refresh begins at the newest persisted row. A tool-heavy turn can fill
 * that page entirely, putting its first durable row after the rendered
 * transcript. Read a small, bounded number of older pages until one shares a
 * durable row, so graftRefreshedTailOntoBackfill can retain the live prefix.
 * Stored ids only grow, so once a page reaches below the oldest rendered id
 * no older page can overlap.
 */
export async function extendRefreshPageToOverlap(
  refreshedTail: ChatMessage[],
  previous: ChatMessage[],
  readOlderPage: () => Promise<ChatMessage[]>
): Promise<ChatMessage[]> {
  if (!refreshedTail.length || !previous.length) {
    return refreshedTail
  }

  const previousRowIds = durableRowIds(previous)

  // Streamed or optimistic rows carry no stored id: nothing can overlap.
  if (previousRowIds.size === 0) {
    return refreshedTail
  }

  const sharesPrevious = (messages: ChatMessage[]) =>
    messages.some(message => message.rowId !== undefined && previousRowIds.has(message.rowId))

  if (sharesPrevious(refreshedTail)) {
    return refreshedTail
  }

  const oldestPrevious = Math.min(...previousRowIds)
  let extended = refreshedTail

  for (let page = 0; page < REFRESH_OVERLAP_PAGE_LIMIT; page += 1) {
    let older: ChatMessage[]

    try {
      older = await readOlderPage()
    } catch {
      // A refresh failure must retain today's newest-page behavior.
      return refreshedTail
    }

    if (!older.length) {
      return refreshedTail
    }

    extended = [...older, ...extended]

    if (sharesPrevious(older)) {
      return extended
    }

    if (older.some(message => message.rowId !== undefined && message.rowId < oldestPrevious)) {
      return refreshedTail
    }
  }

  return refreshedTail
}

export interface BackfillRequest {
  /** Durable stored session id — the tail bookkeeping key. */
  storedSessionId: string
  /** Owner scope captured when the tail was hydrated. */
  profile?: TranscriptProfileScope
  /** Stale-response guard: called after the fetch resolves; when it reports
   *  false (the user switched sessions mid-flight) the page is discarded and
   *  the bookkeeping is left untouched, mirroring the isCurrentResume()
   *  pattern in use-session-actions. */
  isCurrent: () => boolean
  /** Apply the converted older page to the session's message store. The
   *  callback owns WHERE the messages live (session-state cache vs the global
   *  draft atom) and must merge via `mergeOlderTranscriptPage`. */
  applyOlderPage: (olderPage: ChatMessage[]) => void
}

// One fetch per stored session at a time. Keyed by stored id (not runtime id)
// so a mid-fetch runtime rebind cannot double-fetch the same page.
const inflightByStoredSessionId = new Map<string, Promise<boolean>>()

/** Test-only: drop in-flight guards between cases. */
export function _resetTranscriptBackfillForTests(): void {
  inflightByStoredSessionId.clear()
}

/**
 * Fetch the next older page for a session and prepend it via
 * `applyOlderPage`. Resolves true when a page was applied. Concurrent calls
 * for the same session share one fetch.
 */
export function backfillOlderTranscriptPage(request: BackfillRequest): Promise<boolean> {
  const { profile, storedSessionId } = request
  const inflightKey = JSON.stringify([profile || null, storedSessionId])
  const inflight = inflightByStoredSessionId.get(inflightKey)

  if (inflight) {
    return inflight
  }

  const run = (async () => {
    const tail = transcriptTailState(storedSessionId, profile)

    if (!tail?.possiblyTruncated) {
      return false
    }

    let page

    try {
      page = await getOlderSessionMessages(storedSessionId, tail.profile, tail.nextOffset)
    } catch {
      // Non-fatal: the action stays available and the next click retries.
      return false
    }

    // A route can stay put while rewind or revalidation replaces its tail.
    // This page belongs to the exact tail generation we fetched against, not
    // merely the same stored id. Never graft it onto a newer display history.
    if (!request.isCurrent() || transcriptTailState(storedSessionId, profile) !== tail) {
      return false
    }

    // A response without pagination metadata is a legacy backend that ignored
    // the paging query and returned the FULL transcript one-shot. The merge
    // below prepends whatever prefix the store is missing, and the recorded
    // state marks the session fully loaded so the REST action retires.
    recordTranscriptBackfillPage(storedSessionId, page, profile)
    const olderRows = unhideOpeningUserRows(page.messages)
    request.applyOlderPage(toChatMessages(olderRows))

    // #96875: paging can reach the top while the opening USER turn is still
    // missing — the durable row is compaction-projected to display_kind=hidden
    // (dropped at hydration) or sits before the last reachable `latest` page.
    // Once the tail bookkeeping reports the session fully loaded and the page
    // that landed carries no user turn, fetch the oldest display rows once and
    // prepend the opening user turn. Best-effort: a failure keeps the older
    // page that already landed.
    const openingTurnLoaded = olderRows.some(message => message.role === 'user' && message.display_kind !== 'hidden')

    if (!openingTurnLoaded && !transcriptTailState(storedSessionId, profile)?.possiblyTruncated) {
      try {
        const origin = await getSessionMessages(storedSessionId, tail.profile, {
          includeCompacted: true,
          limit: 20,
          offset: 0,
          order: 'oldest'
        })

        if (request.isCurrent()) {
          request.applyOlderPage(toChatMessages(unhideOpeningUserRows(origin.messages)))
        }
      } catch {
        // Origin fetch is best-effort; the already-applied older page stays.
      }
    }

    return true
  })().finally(() => {
    inflightByStoredSessionId.delete(inflightKey)
  })

  inflightByStoredSessionId.set(inflightKey, run)

  return run
}