Skip to content

The agent that grows with you

20.6 KB
Raw Blame
import { useStore } from '@nanostores/react'
import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'

import { PRIMARY_SESSION_VIEW } from '@/app/chat/session-view'
import type { ChatMessage } from '@/lib/chat-messages'
import { preserveLocalAssistantErrors } from '@/lib/chat-messages'
import { createClientSessionState } from '@/lib/chat-runtime'
import { migrateInFlightTurnJournal, persistInFlightTurnState } from '@/lib/inflight-turn-journal'
import { setMutableRef } from '@/lib/mutable-ref'
import { adoptPendingRuntimeTabs, rekeyPreviewTabsSession } from '@/store/preview'
import {
  $activeSessionId,
  $messages,
  setActiveSessionStoredIdRotation,
  setCurrentFastMode,
  setCurrentModelTransient,
  setCurrentPersonality,
  setCurrentProviderTransient,
  setCurrentReasoningEffort,
  setCurrentReasoningEffortWire,
  setCurrentServiceTier,
  setSessionStartedAt,
  setTurnStartedAt,
  setYoloActive
} from '@/store/session'
import {
  $parkedTileStoredIds,
  $sessionStates,
  $sessionTiles,
  isSessionInForeground,
  publishSessionState,
  rekeySessionTile,
  releaseSessionTranscript
} from '@/store/session-states'

import type { ClientSessionState } from '../../types'
import { SessionStateCache } from '../session-state-cache'

import {
  invalidatePersistedDisplayTranscriptAuthority,
  suppressTranscriptForView,
  transcriptRowContentKey
} from './use-session-actions/transcript-provenance'
import { chatMessageArraysEquivalent } from './use-session-actions/utils'

// A held transcript gate hides only the unproven CACHED prefix (the ids
// captured when the hold was armed) — rows that arrive live during the hold
// still paint, which is the point of the fix (#117867).
interface TranscriptViewGate {
  cutoffIds: ReadonlySet<string>
  cutoffKeys: ReadonlySet<string>
  token: symbol
}

interface SessionStateCacheOptions {
  activeSessionId: string | null
  busyRef: MutableRefObject<boolean>
  selectedStoredSessionId: string | null
  setAwaitingResponse: (awaiting: boolean) => void
  setBusy: (busy: boolean) => void
  setMessages: (messages: ChatMessage[]) => void
}

function syncRuntimeMetadataToView(state: ClientSessionState) {
  // Transient: this runs on every session-state sync, including the periodic
  // session.info heartbeat, whose reported model/provider is the runtime's
  // resolved identity (e.g. the generic `custom` billing class), not a user
  // pick. The persisting setters would silently overwrite the composer's
  // sticky localStorage selection with that runtime value (#102793).
  setCurrentModelTransient(state.model ?? '')
  setCurrentProviderTransient(state.provider ?? '')
  setCurrentReasoningEffort(state.reasoningEffort ?? '')
  setCurrentReasoningEffortWire(state.reasoningEffortWire ?? '')
  setCurrentServiceTier(state.serviceTier ?? '')
  setCurrentFastMode(state.fast ?? false)
  setYoloActive(state.yolo ?? false)
  setCurrentPersonality(state.personality ?? '')
}

export function useSessionStateCache({
  activeSessionId,
  busyRef,
  selectedStoredSessionId,
  setAwaitingResponse,
  setBusy,
  setMessages
}: SessionStateCacheOptions) {
  const busy = useStore(PRIMARY_SESSION_VIEW.$busy)
  const sessionTiles = useStore($sessionTiles)
  // Parking is driven by pane-lifecycle when focus moves off a tile (onto a
  // terminal pane, say). That changes neither the active/selected ids nor the
  // tile list, so without subscribing here an idle window would keep the parked
  // transcript pinned until some unrelated publish happened to re-run prune.
  const parkedTileStoredIds = useStore($parkedTileStoredIds)
  const activeSessionIdRef = useRef<string | null>(activeSessionId)
  const selectedStoredSessionIdRef = useRef<string | null>(selectedStoredSessionId)

  // Mirror the latest prop into its ref synchronously during render — not via
  // a passive useEffect, which only fires a frame after paint and left the
  // ref pointing at the outgoing session for one commit (#59305). Guarded to
  // fire only when the PROP itself changed since the last render (the same
  // condition a `useEffect(..., [activeSessionId])` dependency array already
  // enforced) rather than unconditionally: submit.ts and use-session-actions
  // pin these refs imperatively mid-flight (e.g. to a just-resumed runtime id)
  // without updating the source atom in lockstep, and wiring.tsx re-renders
  // constantly during an active turn — an unconditional resync would silently
  // clobber that pin on the next incidental render (#54527-class regression).
  const activeSessionIdPropRef = useRef(activeSessionId)

  if (activeSessionIdPropRef.current !== activeSessionId) {
    activeSessionIdPropRef.current = activeSessionId
    activeSessionIdRef.current = activeSessionId
  }

  const selectedStoredSessionIdPropRef = useRef(selectedStoredSessionId)

  if (selectedStoredSessionIdPropRef.current !== selectedStoredSessionId) {
    selectedStoredSessionIdPropRef.current = selectedStoredSessionId
    selectedStoredSessionIdRef.current = selectedStoredSessionId
  }

  const runtimeIdByStoredSessionIdRef = useRef(new Map<string, string>())
  const sessionStateByRuntimeIdRef = useRef<SessionStateCache>(null!)

  if (sessionStateByRuntimeIdRef.current === null) {
    sessionStateByRuntimeIdRef.current = new SessionStateCache({
      isReferenced: (runtimeId, state) =>
        runtimeId === activeSessionIdRef.current ||
        state.storedSessionId === selectedStoredSessionIdRef.current ||
        $sessionTiles
          .get()
          .some(
            tile =>
              !$parkedTileStoredIds.get().has(tile.storedSessionId) &&
              (tile.runtimeId === runtimeId ||
                (state.storedSessionId !== null && tile.storedSessionId === state.storedSessionId))
          ),
      // A connection death mid-turn leaves snapshots whose frozen busy flags
      // will never settle (the respawned backend re-mints runtime ids), which
      // pinned megabytes of warm transcript per reconnect cycle behind
      // #isWarmSettled (#95189). Trust the cached in-flight flags only while
      // the authoritative store still claims work for the same runtime id.
      isAuthoritativelyActive: runtimeId => {
        const live = $sessionStates.get()[runtimeId]

        return Boolean(live && (live.busy || live.awaitingResponse))
      },
      onEvict: (runtimeId, state) => {
        // Ownership is removed with the transcript, but only if both sides still
        // describe this exact binding. A recycled runtime must not erase its
        // new owner's reverse entry.
        if (state.storedSessionId && runtimeIdByStoredSessionIdRef.current.get(state.storedSessionId) === runtimeId) {
          runtimeIdByStoredSessionIdRef.current.delete(state.storedSessionId)
        }

        releaseSessionTranscript(runtimeId)
      }
    })
  }

  const sessionStateCache = sessionStateByRuntimeIdRef.current
  const pendingViewStateRef = useRef<{ sessionId: string; state: ClientSessionState } | null>(null)
  const viewSyncRafRef = useRef<number | null>(null)
  const transcriptViewGateByRuntimeIdRef = useRef(new Map<string, TranscriptViewGate>())
  // Runtime id whose transcript currently occupies `$messages` — lets the
  // flush below tell a same-session refresh from a thread switch.
  const viewSessionIdRef = useRef<string | null>(null)

  // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment)
  useEffect(() => {
    setMutableRef(busyRef, busy)
  }, [busy, busyRef])

  const ensureSessionState = useCallback(
    (sessionId: string, storedSessionId?: string | null) => {
      const existing = sessionStateCache.get(sessionId)

      if (existing) {
        if (storedSessionId !== undefined && storedSessionId !== existing.storedSessionId) {
          // Stored id changed (e.g. auto-compression rotated it). Create a NEW
          // state object rather than mutating in place — updateSessionState needs
          // the PREVIOUS state to detect transitions (busy→idle, id rotation).
          const updated = invalidatePersistedDisplayTranscriptAuthority({ ...existing, storedSessionId })

          // Drop the obsolete stored→runtime reverse mapping as soon as the id
          // rotates (e.g. auto-compression forks a continuation). Leaving the
          // stale key lets getRuntimeIdForStoredSession resolve the old stored id
          // to this runtime, which the compression route-follow logic relies on
          // being absent. The rotation signal was previously emitted centrally
          // from handleTransition (session-states.ts), but updateSessionState
          // now skips publishSessionState (and thus handleTransition) when the
          // updater is a no-op — fire it here so the route-follow effect still
          // tracks compression without needing a dummy state write.
          if (existing.storedSessionId && existing.storedSessionId !== storedSessionId) {
            runtimeIdByStoredSessionIdRef.current.delete(existing.storedSessionId)

            // The journal under the pre-rotation id is keyed by a stored id
            // nothing will name again (the reverse mapping above is gone and
            // lineage resolution follows the tip), so a later permanent delete
            // could not reach it. Re-key it to the new id — copy first, then
            // delete — so recovery survives the rotation AND the delete
            // gesture still reaches every copy (#77486).
            migrateInFlightTurnJournal(existing.storedSessionId, storedSessionId)

            // Re-home any open tile keyed on the pre-rotation id (#98622).
            // Ungated on the active runtime: a background tile's conversation
            // rotates here too, and its pane would otherwise keep the stale id
            // (duplicate/differently-titled tabs). Mirrors handleTransition's
            // rekey, which this path can skip when the state updater is a no-op.
            if (storedSessionId) {
              rekeySessionTile(existing.storedSessionId, storedSessionId, sessionId)
              rekeyPreviewTabsSession(existing.storedSessionId, storedSessionId)
            }

            // A rotation event needs a real next id — a null/cleared stored id
            // is a detach, not a rotation the route-follow effect should chase.
            if (
              storedSessionId &&
              sessionId === $activeSessionId.get() &&
              isSessionInForeground(existing.storedSessionId)
            ) {
              setActiveSessionStoredIdRotation({
                nextStoredSessionId: storedSessionId,
                previousStoredSessionId: existing.storedSessionId,
                runtimeSessionId: sessionId
              })
            }
          }

          if (storedSessionId) {
            runtimeIdByStoredSessionIdRef.current.set(storedSessionId, sessionId)

            // The runtime's stored id binding (null → id). Mirrors
            // handleTransition's hand-over, which a no-op updater skips.
            if (!existing.storedSessionId) {
              adoptPendingRuntimeTabs(sessionId, storedSessionId)
            }
          }

          sessionStateCache.set(sessionId, updated)
        }

        return sessionStateCache.get(sessionId)!
      }

      const created = createClientSessionState(storedSessionId ?? null)

      if (storedSessionId) {
        runtimeIdByStoredSessionIdRef.current.set(storedSessionId, sessionId)
      }

      sessionStateCache.set(sessionId, created)

      return created
    },
    [sessionStateCache]
  )

  const resetViewSync = useCallback(() => {
    // Drop any RAF-pending transcript stage so a backgrounded turn cannot
    // repaint over the chat the user just switched to (#47709 / #47743).
    pendingViewStateRef.current = null
    viewSessionIdRef.current = null

    if (viewSyncRafRef.current !== null && typeof window !== 'undefined') {
      window.cancelAnimationFrame(viewSyncRafRef.current)
      viewSyncRafRef.current = null
    }
  }, [])

  const holdSessionTranscriptView = useCallback(
    (runtimeId: string): (() => void) => {
      const token = Symbol(runtimeId)
      const cached = sessionStateCache.get(runtimeId)

      transcriptViewGateByRuntimeIdRef.current.set(runtimeId, {
        cutoffIds: new Set((cached?.messages ?? []).map(message => message.id)),
        cutoffKeys: new Set((cached?.messages ?? []).map(transcriptRowContentKey)),
        token
      })

      return () => {
        if (transcriptViewGateByRuntimeIdRef.current.get(runtimeId)?.token === token) {
          transcriptViewGateByRuntimeIdRef.current.delete(runtimeId)
        }
      }
    },
    [sessionStateCache]
  )

  const flushPendingViewState = useCallback(() => {
    const pending = pendingViewStateRef.current
    pendingViewStateRef.current = null

    if (!pending || pending.sessionId !== activeSessionIdRef.current) {
      return
    }

    // `preserveLocalAssistantErrors` always returns a fresh array, so publishing
    // it unconditionally puts a new `$messages` reference on the store every
    // flush — including the periodic `session.info` heartbeats that don't touch
    // the transcript. That churns ChatView → runtimeMessageRepository → the
    // assistant-ui runtime → the virtualizer, which re-measures and visibly
    // jerks the scroll position while the user is reading. Skip the publish when
    // the merged result is content-equivalent to what's already on screen.
    // Deep comparison (not just reference equality) is needed because the warm
    // resume path's `reconcileAuthoritativeMessages` creates new message objects
    // via `toChatMessages` even when the content hasn't changed — reference
    // equality would fail and cause a redundant second paint (the "warm resume
    // jitter" bug).
    const currentMessages = $messages.get()

    // On a thread switch `$messages` still holds the *previous* thread, so
    // preserving its local errors would graft that thread's failed turn (e.g.
    // an out-of-funds error) onto this one — then cascade it everywhere as the
    // polluted view becomes the next switch's baseline. Only carry errors
    // across a same-session refresh; our cached state already keeps its own.
    const nextMessages =
      viewSessionIdRef.current === pending.sessionId
        ? preserveLocalAssistantErrors(pending.state.messages, currentMessages)
        : pending.state.messages

    if (!chatMessageArraysEquivalent(nextMessages, currentMessages)) {
      setMessages(nextMessages)
    }

    viewSessionIdRef.current = pending.sessionId

    syncRuntimeMetadataToView(pending.state)
    setBusy(pending.state.busy)
    setMutableRef(busyRef, pending.state.busy)
    setAwaitingResponse(pending.state.awaitingResponse)
    // Keep the foreground duration anchored to the runtime's first renderer
    // attachment. Background state remains cached without stealing this view.
    setSessionStartedAt(pending.state.runtimeStartedAt)
    // Mirror the focused session's per-session turn clock into the global
    // atom the statusbar timer reads. Keeps a backgrounded turn's elapsed
    // time intact on focus instead of zeroing it (the "timer restarts" bug).
    setTurnStartedAt(pending.state.turnStartedAt)
  }, [busyRef, setAwaitingResponse, setBusy, setMessages])

  const syncSessionStateToView = useCallback(
    (sessionId: string, state: ClientSessionState) => {
      // Only the currently-viewed session may stage into the shared `$messages`
      // view. A background session (e.g. one still busy and emitting stream /
      // error updates after the user toggled away) must update its own cache
      // entry but never the view — otherwise its messages clobber the
      // foreground transcript and appear to "bleed" into every other session.
      // The flush below also re-checks the active id, but staging here is what
      // prevents a background write from overwriting an already-pending
      // foreground write within the same animation frame (only one RAF is
      // scheduled, so the last `pendingViewStateRef` writer would otherwise win).
      if (sessionId !== activeSessionIdRef.current) {
        return
      }

      const gate = transcriptViewGateByRuntimeIdRef.current.get(sessionId)
      const viewState = suppressTranscriptForView(state, gate ?? null)

      syncRuntimeMetadataToView(viewState)
      pendingViewStateRef.current = { sessionId, state: viewState }

      // Terminal / attention transitions (turn finished, error, or the agent is
      // now waiting on the user) MUST reach the view immediately. Electron
      // throttles `requestAnimationFrame` to ~0 while the window is
      // backgrounded, occluded, or unfocused, so an RAF-deferred flush can be
      // stranded in `pendingViewStateRef` indefinitely — that's the "new chat
      // stuck on Thinking until I refocus / F5" bug. Flush these synchronously
      // (cancelling any in-flight RAF, since we're about to publish the latest
      // state anyway). The plain busy heartbeat stays RAF-batched: that
      // coalescing exists only to keep periodic `session.info` updates from
      // churning `$messages` and jerking the scroll position while reading.
      const isCriticalTransition = !viewState.busy || viewState.needsInput

      if (isCriticalTransition) {
        if (viewSyncRafRef.current !== null && typeof window !== 'undefined') {
          window.cancelAnimationFrame(viewSyncRafRef.current)
          viewSyncRafRef.current = null
        }

        flushPendingViewState()

        return
      }

      if (viewSyncRafRef.current !== null) {
        return
      }

      if (typeof window === 'undefined') {
        flushPendingViewState()

        return
      }

      viewSyncRafRef.current = window.requestAnimationFrame(() => {
        viewSyncRafRef.current = null
        flushPendingViewState()
      })
    },
    [flushPendingViewState]
  )

  useEffect(
    () => () => {
      if (viewSyncRafRef.current !== null && typeof window !== 'undefined') {
        window.cancelAnimationFrame(viewSyncRafRef.current)
        viewSyncRafRef.current = null
      }
    },
    []
  )

  const updateSessionState = useCallback(
    (
      sessionId: string,
      updater: (state: ClientSessionState) => ClientSessionState,
      storedSessionId?: string | null
    ) => {
      const previous = ensureSessionState(sessionId, storedSessionId)
      // Give the updater the raw previous state so it can return the same
      // reference when nothing changed (the caller sees a no-op). Previously
      // the param was always a fresh spread, so every call looked like a
      // change — including periodic ~1/s session.info heartbeats that churn
      // $sessionStates and its computed atoms on every tick.
      const next = updater(previous)

      // If the updater returned the same reference, nothing changed for this
      // session — skip the store write, publishSessionState, and view sync.
      // The cache entry was already updated by ensureSessionState (if
      // storedSessionId rotated); the caller gets its return value from the
      // cache, so stale reads don't regress.
      if (next === previous) {
        return previous
      }

      sessionStateCache.set(sessionId, next)
      // Crash-survivable turn progress: journal the running turn's visible
      // tail (throttled localStorage write; cleared the moment the turn
      // settles) so a renderer/app death mid-turn can be recovered on resume.
      persistInFlightTurnState(next)
      // Publishing to $sessionStates automatically fires transition side-effects
      // (watchdog, settle grace, unread marker, compression id rotation) inside
      // publishSessionState — no manual transition call needed.
      publishSessionState(sessionId, next)
      sessionStateCache.prune()
      syncSessionStateToView(sessionId, next)

      return next
    },
    [ensureSessionState, sessionStateCache, syncSessionStateToView]
  )

  useEffect(() => {
    sessionStateCache.prune()
  }, [activeSessionId, parkedTileStoredIds, selectedStoredSessionId, sessionStateCache, sessionTiles])

  const getRuntimeIdForStoredSession = useCallback(
    (storedSessionId: string): string | null => {
      const runtimeId = runtimeIdByStoredSessionIdRef.current.get(storedSessionId)

      if (!runtimeId) {
        return null
      }

      const runtimeState = sessionStateCache.get(runtimeId)

      return runtimeState?.storedSessionId === storedSessionId ? runtimeId : null
    },
    [sessionStateCache]
  )

  return {
    activeSessionIdRef,
    ensureSessionState,
    getRuntimeIdForStoredSession,
    holdSessionTranscriptView,
    resetViewSync,
    runtimeIdByStoredSessionIdRef,
    selectedStoredSessionIdRef,
    sessionStateByRuntimeIdRef: sessionStateByRuntimeIdRef as MutableRefObject<Map<string, ClientSessionState>>,
    syncSessionStateToView,
    updateSessionState
  }
}