@flamingo-stack/openframe-frontend-core 0.0.523-1675.4360.1 → 0.0.523

package/src/components/chat/hooks/use-jetstream-dialog-subscription.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import {
   acquireClient as acquireSharedClient,
   releaseClient as releaseSharedClient,
@@ -20,7 +20,24 @@ const DEFAULT_STREAM_NAME = 'CHAT_CHUNKS'
  * absence worth resyncing for. Alt-tabbing must not churn the consumer; a
  * window that sat in the tray must not come back showing a stale conversation.
  */
-const RESYNC_AFTER_HIDDEN_MS = 10_000
+export const RESYNC_AFTER_HIDDEN_MS = 10_000
+/**
+ * How long resync requests are gathered before one is acted on.
+ *
+ * A single reveal can be reported twice: the page sees `visibilitychange`, and
+ * a host that knows the window was away reports it too (`resyncSignal`),
+ * neither able to tell whether the other noticed. Both land within a frame or
+ * two of each other, being driven by the same OS event, and acting on both
+ * rebuilds the consumer and refetches history twice for one reveal.
+ *
+ * Gathered on the TRAILING edge, so a request is deferred and never dropped.
+ * Two reports of one reveal collapse into one rebuild; two genuinely different
+ * signals — a notification reply landing just before the user opens the window
+ * — also collapse into one, which is correct, because a single refetch after
+ * the last of them covers both. The cost is a second of latency on a path whose
+ * next step is a network round trip.
+ */
+const RESYNC_COALESCE_MS = 1_000
 /**
  * Floor between two reported recoveries. Every recovery costs the caller a
  * history refetch, and a consumer that cannot hold its sequence — gap, reset,
@@ -60,6 +77,7 @@ export function useJetStreamDialogSubscription({
   clientConfig = {},
   reconnectionBackoff,
   inactiveThresholdMs,
+  resyncSignal = 0,
 }: UseJetStreamDialogSubscriptionOptions): UseJetStreamDialogSubscriptionReturn {
   const [isConnected, setIsConnected] = useState(false)
   const [isSubscribed, setIsSubscribed] = useState(false)
@@ -73,6 +91,8 @@ export function useJetStreamDialogSubscription({
   const [currentStreamSeq, setCurrentStreamSeq] = useState<number | null>(null)
 
   const lastRecoveryReportRef = useRef(0)
+  const resyncTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const lastResyncSignalRef = useRef(resyncSignal)
   const clientRef = useRef<NatsClient | null>(null)
   const subscriptionRef = useRef<JetStreamSubscriptionHandle | null>(null)
   const highestStreamSeqRef = useRef<number | null>(null)
@@ -245,7 +265,26 @@ export function useJetStreamDialogSubscription({
   // ignoring optStartSeq).
   useEffect(() => {
     highestStreamSeqRef.current = null
+    // A host's signal counts per dialog (it can carry a per-conversation term),
+    // so the baseline has to move with the dialog or a switch to one with a
+    // LOWER count would swallow every later resync for it.
+    lastResyncSignalRef.current = resyncSignal
     setCurrentStreamSeq(null)
+    // A resync gathered for the previous dialog must not land on this one: the
+    // counter says nothing about which conversation it meant, so callers would
+    // refetch the wrong one. The dialog change supersedes it — the new dialog
+    // loads its own history regardless. As cleanup, so it covers unmount too,
+    // which is the same rule.
+    return () => {
+      if (resyncTimerRef.current !== null) {
+        clearTimeout(resyncTimerRef.current)
+        resyncTimerRef.current = null
+      }
+    }
+    // `resyncSignal` is read as the new baseline, not depended on: reacting to
+    // it here would reset the baseline on the very change meant to trigger a
+    // resync, and the effect below owns that.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [dialogId])
 
   // Coming back into view after a real absence is treated exactly like a
@@ -256,8 +295,20 @@ export function useJetStreamDialogSubscription({
   // report that: the tail simply stays quiet, and the conversation on screen
   // stays frozen at whatever was there when the window went away (the user's
   // manual fix is a page refresh, which is exactly the history refetch this
-  // triggers). Bumping the counter rebuilds the consumer from the last sequence
-  // seen AND tells callers to refetch history.
+  // triggers). Rebuilds the consumer from the last sequence seen AND tells
+  // callers to refetch history.
+  //
+  // Every source funnels through here (see `RESYNC_COALESCE_MS`). Restarting
+  // the timer rather than dropping is what makes that safe: a request is only
+  // ever folded into the one that follows it, never discarded.
+  const requestResync = useCallback(() => {
+    if (resyncTimerRef.current !== null) clearTimeout(resyncTimerRef.current)
+    resyncTimerRef.current = setTimeout(() => {
+      resyncTimerRef.current = null
+      setReconnectionCount((c) => c + 1)
+    }, RESYNC_COALESCE_MS)
+  }, [])
+
   useEffect(() => {
     if (!enabled) return
     let hiddenSince = document.visibilityState === 'hidden' ? Date.now() : 0
@@ -270,13 +321,27 @@ export function useJetStreamDialogSubscription({
       const awayMs = hiddenSince === 0 ? 0 : Date.now() - hiddenSince
       hiddenSince = 0
       if (awayMs >= RESYNC_AFTER_HIDDEN_MS) {
-        setReconnectionCount((c) => c + 1)
+        requestResync()
       }
     }
 
     document.addEventListener('visibilitychange', onVisibilityChange)
     return () => document.removeEventListener('visibilitychange', onVisibilityChange)
-  }, [enabled])
+  }, [enabled, requestResync])
+
+  useEffect(() => {
+    // Held, not consumed, while disabled: it fires once on enable instead.
+    // A host reports a signal against the conversation, not against this hook's
+    // readiness, so one arriving while the caller is still assembling the
+    // subscription describes a gap in the history the caller is fetching right
+    // now. Dropping it would leave that fetch's result stale with nothing left
+    // to say so.
+    if (!enabled) return
+    // The mount value is a baseline, not a signal.
+    if (resyncSignal <= lastResyncSignalRef.current) return
+    lastResyncSignalRef.current = resyncSignal
+    requestResync()
+  }, [enabled, resyncSignal, requestResync])
 
   // Subscription lifecycle: (re)create the ephemeral JetStream consumer whenever
   // we transition into a connected state for a dialog, and whenever the dialog

package/src/components/chat/index.ts

@@ -3,6 +3,8 @@
 // Chat components exports
 export * from './approval-request-message'
 export * from './approval-batch-message'
+export * from './escalation-offer-message'
+export * from './ticket-escalated-message'
 export * from './context-compaction-display'
 export * from './expand-chevron'
 export * from './thinking-display'

package/src/components/chat/stream/chat-stream-reducer.ts

@@ -197,6 +197,7 @@ export interface ChatReducerEffect {
     | 'onEscalatedApproval'
     | 'onEscalatedApprovalResult'
     | 'onApprovalResolved'
+    | 'onEscalationOfferResolved'
     | 'onToolExecuted'
     | 'onAgentBusy'
     | 'onDialogClosed'
@@ -1275,6 +1276,55 @@ export function createChatStreamReducer(
         break
       }
 
+      case 'escalation-offer': {
+        // MUST route through `applyAccumulated`. The block reaches a client
+        // in three shapes — inline in Fae's live turn (tool origin), or with
+        // NO preceding MESSAGE_START when the backend surfaces a deferred
+        // offer at turn end or honours the header button while idle. In the
+        // latter shapes a cumulative emit would replace the trailing bubble's
+        // segments with the lone card, wiping the reply the user is reading.
+        const status = (approvalStatuses[event.offerId] || 'pending') as ChatApprovalStatus
+        const before = accumulator.getSegments().length
+        const segments = accumulator.addEscalationOffer(
+          event.offerId,
+          event.text,
+          event.origin,
+          status,
+        )
+        applyAccumulated(before, segments)
+        break
+      }
+
+      case 'escalation-offer-resolved': {
+        const { offerId, status, resolvedByName: offerResolvedBy } = event
+        // Approving hands the ticket to a human; Fae goes silent rather than
+        // resuming, so — unlike an approved command — there is no work to
+        // signal and the busy lock stays untouched.
+        accumulator.updateApprovalStatus(offerId, status, offerResolvedBy)
+        setMessagesInternal(
+          projectApprovalResolutionToMessages(messages, offerId, status, offerResolvedBy),
+        )
+        mirrorApprovalStatus(offerId, status)
+        emit('onEscalationOfferResolved', offerId, status, offerResolvedBy)
+        break
+      }
+
+      case 'ticket-escalated': {
+        // Same `applyAccumulated` routing as the offer, and for the same
+        // reason: the inactivity auto-escalation fires from a scheduler with
+        // no turn open at all, so this block routinely arrives with no
+        // preceding MESSAGE_START.
+        const before = accumulator.getSegments().length
+        const segments = accumulator.addTicketEscalated({
+          ticketId: event.ticketId,
+          ticketNumber: event.ticketNumber,
+          reason: event.reason,
+          text: event.text,
+        })
+        applyAccumulated(before, segments)
+        break
+      }
+
       case 'error': {
         let message: string | undefined
         if (event.details) {

package/src/components/chat/stream/message-mutations.ts

@@ -75,11 +75,37 @@ export function updateTrailingAssistant(
   return [...prev.slice(0, -1), { ...last, segments }]
 }
 
+/**
+ * Identity of a block that must upsert rather than stack when re-appended,
+ * namespaced so two kinds can never collide. `null` for segments that coalesce
+ * by adjacency (text/thinking/guide) or are pushed raw. Legacy approval cards
+ * share one requestId across an unfolded batch, hence the command in the key.
+ *
+ * `ticket_escalated` keys on its dialog-scoped ticketId, which is safe HERE
+ * (two receipts inside one trailing bubble can only be a redelivery) but is NOT
+ * a turn identity — see the deliberate omissions in `turnRequestKeys` and the
+ * host's thread-global dedupe.
+ */
+function upsertKey(seg: MessageSegment): string | null {
+  switch (seg.type) {
+    case 'approval_batch':
+      return `batch:${seg.data.approvalRequestId}`
+    case 'approval_request':
+      return `req:${seg.data.requestId}:${seg.data.command}`
+    case 'escalation_offer':
+      return `offer:${seg.data.offerId}`
+    case 'ticket_escalated':
+      return `escalated:${seg.data.ticketId}`
+    default:
+      return null
+  }
+}
+
 /**
  * Append-mode counterpart of `updateTrailingAssistant` for post-MESSAGE_END
  * continuation fragments (`SegmentsUpdateMetadata.append`). Coalesces
- * trailing fragments of the same type, mirroring the accumulator; approval
- * deltas upsert by request id so a replayed emit stays idempotent.
+ * trailing fragments of the same type, mirroring the accumulator; block deltas
+ * upsert by identity (see `upsertKey`) so a replayed emit stays idempotent.
  */
 export function appendToTrailingAssistant(
   prev: UnifiedChatMessage[],
@@ -96,30 +122,18 @@ export function appendToTrailingAssistant(
   const merged = [...(last.segments ?? [])]
   for (const seg of segments) {
     const tail = merged[merged.length - 1]
+    const key = upsertKey(seg)
     if (seg.type === 'text' && tail?.type === 'text') {
       merged[merged.length - 1] = { type: 'text', text: tail.text + seg.text }
     } else if (seg.type === 'thinking' && tail?.type === 'thinking') {
       merged[merged.length - 1] = { type: 'thinking', text: tail.text + seg.text }
     } else if (seg.type === 'guide' && tail?.type === 'guide') {
       merged[merged.length - 1] = { type: 'guide', text: tail.text + seg.text }
-    } else if (seg.type === 'approval_batch') {
-      // Approval deltas must be IDEMPOTENT: the escalated-result emit can be
-      // seen twice (live + catch-up replay over hydrated history), so upsert
-      // by request id instead of raw-appending a duplicate card.
-      const idx = merged.findIndex(
-        (m) => m.type === 'approval_batch' && m.data.approvalRequestId === seg.data.approvalRequestId,
-      )
-      if (idx !== -1) merged[idx] = seg
-      else merged.push(seg)
-    } else if (seg.type === 'approval_request') {
-      // Legacy cards share one requestId across an unfolded batch — key on
-      // (requestId, command) so each tool's card upserts its own twin.
-      const idx = merged.findIndex(
-        (m) =>
-          m.type === 'approval_request' &&
-          m.data.requestId === seg.data.requestId &&
-          m.data.command === seg.data.command,
-      )
+    } else if (key) {
+      // Block deltas must be IDEMPOTENT: an emit can be seen twice (live plus
+      // the JetStream catch-up replay over hydrated history), so upsert on the
+      // block's identity instead of raw-appending a duplicate card.
+      const idx = merged.findIndex((m) => upsertKey(m) === key)
       if (idx !== -1) merged[idx] = seg
       else merged.push(seg)
     } else {
@@ -177,6 +191,10 @@ function mapSegments(
  *   - `approval_batch` ROW (`toolCalls[].toolExecutionRequestId`) →
  *     tick that row's execution (check on approved, cross otherwise)
  *     without touching the batch status.
+ *   - `escalation_offer` matched on `data.offerId` → status flip +
+ *     resolver stamp. Escalation offers are backed by the SAME
+ *     `ToolApprovalRequest` collection as command approvals, so the two id
+ *     spaces are one and a cross-match is impossible.
  * Returns the SAME reference when nothing matched or changed.
  */
 export function applyApprovalStatusToSegment(
@@ -188,6 +206,15 @@ export function applyApprovalStatusToSegment(
   if (s.type === 'approval_request' && s.data.requestId === requestId && s.status !== status) {
     return { ...s, status }
   }
+  if (s.type === 'escalation_offer') {
+    if (s.data.offerId !== requestId) return s
+    const nextResolvedBy = resolvedByName ?? s.resolvedByName
+    // Status alone is not enough to early-out: the host overlay flips the
+    // status first and the persisted row supplies the resolver name after, so
+    // bailing on an unchanged status drops the "by {name}" stamp.
+    if (s.status === status && nextResolvedBy === s.resolvedByName) return s
+    return { ...s, status, resolvedByName: nextResolvedBy }
+  }
   if (s.type !== 'approval_batch') return s
   const isAnchor = s.data.approvalRequestId === requestId
   const hasRow = s.data.toolCalls?.some((c) => c.toolExecutionRequestId === requestId)

package/src/components/chat/ticket-escalated-message.tsx

@@ -0,0 +1,68 @@
+"use client"
+
+import { forwardRef, type HTMLAttributes } from "react"
+import { cn } from "../../utils/cn"
+import { formatTime } from "../../utils/format-date"
+import { InfoCircleIcon } from "../icons-v2-generated"
+import type { TicketEscalatedSegment } from "./types/message.types"
+
+const TITLE = "Handed Off to a Technician"
+
+/** Shown when the wire omits `text` (the field is nullable). */
+const DEFAULT_BODY = "A technician will reply when available."
+
+export interface TicketEscalatedMessageProps extends HTMLAttributes<HTMLDivElement> {
+  data: TicketEscalatedSegment['data']
+  /** Timestamp of the message row this block came in on. */
+  timestamp?: Date
+}
+
+/**
+ * Handoff receipt — the conversation now belongs to a human technician.
+ * Figma `ai-assistant-info` (type=escalation).
+ *
+ * The body is whatever the backend authored, so the reason it gives stays
+ * server-side; the client never composes an explanation and never branches on
+ * `data.reason`, which is why a reason added server-side needs no change here.
+ *
+ * That body WRAPS, deliberately diverging from the mock's single-line ellipsis:
+ * the mock's 72px comes from its placeholder copy fitting one line, while the
+ * real wire text is a full sentence, and clipping the only explanation of why
+ * the chat was handed off is not recoverable on touch. The title still
+ * truncates — it is a constant, and holding one line keeps the timestamp from
+ * being pushed out of the row at narrow widths.
+ */
+const TicketEscalatedMessage = forwardRef<HTMLDivElement, TicketEscalatedMessageProps>(
+  ({ className, data, timestamp, ...props }, ref) => {
+    const body = data.text?.trim() || DEFAULT_BODY
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "mb-[var(--spacing-system-xsf)] flex items-start gap-[var(--spacing-system-s)] rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-s)]",
+          className,
+        )}
+        {...props}
+      >
+        <div className="flex size-12 shrink-0 items-center justify-center rounded-md border border-ods-border bg-ods-bg">
+          <InfoCircleIcon className="size-6 text-ods-flamingo-pink" />
+        </div>
+        <div className="flex min-w-0 flex-1 flex-col">
+          <div className="flex w-full items-start">
+            <p className="text-h4 min-w-0 flex-1 truncate text-ods-text-primary" title={TITLE}>
+              {TITLE}
+            </p>
+            {timestamp && (
+              <span className="text-h6 shrink-0 text-right text-ods-text-secondary">{formatTime(timestamp)}</span>
+            )}
+          </div>
+          <p className="text-h4 w-full break-words text-ods-text-secondary">{body}</p>
+        </div>
+      </div>
+    )
+  },
+)
+
+TicketEscalatedMessage.displayName = "TicketEscalatedMessage"
+
+export { TicketEscalatedMessage }

package/src/components/chat/types/api.types.ts

@@ -131,6 +131,22 @@ export interface UseJetStreamDialogSubscriptionOptions {
   /** Consumer inactivity threshold in ms before NATS auto-cleans it. Defaults to the
    *  client's, and applies only to the first consumer — recreations use nats.ws's. */
   inactiveThresholdMs?: number
+  /**
+   * A counter the host bumps when it knows, from outside the page, that the tail
+   * may have missed something.
+   *
+   * The hook's own detector is `visibilitychange`, which a browser tab reports
+   * honestly and an embedding shell may not — and which says nothing at all
+   * about a write made on the page's behalf while it was away. A host holding
+   * either kind of knowledge bumps this instead of hoping the page noticed.
+   *
+   * Treated exactly like a reconnect: the consumer is rebuilt from the highest
+   * sequence already seen, and `reconnectionCount` moves so callers refetch
+   * persisted history. Any increase counts; the value itself means nothing, and
+   * an increase arriving alongside a `visibilitychange` costs one rebuild, not
+   * two.
+   */
+  resyncSignal?: number
 }
 
 export interface UseJetStreamDialogSubscriptionReturn {
@@ -138,10 +154,12 @@ export interface UseJetStreamDialogSubscriptionReturn {
   isSubscribed: boolean
   /**
    * Incremented each time the live tail is re-established: a NATS reconnect, a
-   * JetStream ordered-consumer recreation, or the page returning to view after
-   * being hidden long enough to have missed something. All three mean the same
-   * thing to the caller — the tail may have skipped messages, so persisted
-   * history has to be refetched. Starts at 0.
+   * JetStream ordered-consumer recreation, the page returning to view after
+   * being hidden long enough to have missed something, or a host reporting the
+   * same via `resyncSignal`. All of them mean the same thing to the caller —
+   * the tail may have skipped messages, so persisted history has to be
+   * refetched. One absence counts once even when two sources report it.
+   * Starts at 0.
    */
   reconnectionCount: number
   /** Highest JetStream stream sequence observed so far (null before first delivery). */

package/src/components/chat/types/message.types.ts

@@ -16,6 +16,8 @@ export const MESSAGE_TYPE = {
   EXECUTED_TOOL: 'EXECUTED_TOOL',
   APPROVAL_REQUEST: 'APPROVAL_REQUEST',
   APPROVAL_RESULT: 'APPROVAL_RESULT',
+  ESCALATION_OFFER: 'ESCALATION_OFFER',
+  TICKET_ESCALATED: 'TICKET_ESCALATED',
   ERROR: 'ERROR',
   MESSAGE_START: 'MESSAGE_START',
   MESSAGE_END: 'MESSAGE_END',
@@ -121,6 +123,35 @@ export interface ApprovalResultData {
   resolvedByName?: string | null
 }
 
+// ========== Escalation Offer Types ==========
+
+export interface EscalationOfferData {
+  offerId: string
+  /** Backend-fixed card copy; the client never composes it. */
+  text: string
+  /** Why the offer was raised (`TOOL`, `MANUAL`, a trigger reason). Carried
+   *  for telemetry — every origin renders the same card. */
+  origin?: string
+}
+
+// ========== Ticket Escalated Types ==========
+
+/** Open union: the wire currently defines only `INACTIVITY`, and the block
+ *  renders from `text` rather than branching on this, so a reason added
+ *  server-side needs no client change. */
+export type TicketEscalationReason = 'INACTIVITY' | (string & {})
+
+/** The handoff receipt — a real block on the wire, not something the client
+ *  infers from an escalation offer's state. */
+export interface TicketEscalatedData {
+  ticketId: string
+  ticketNumber?: number
+  reason: TicketEscalationReason
+  /** Backend-authored explanation; the card falls back to generic copy when
+   *  the wire omits it (the field is nullable). */
+  text?: string
+}
+
 /**
  * Single tool call inside a batch approval request.
  * Mirrors backend PendingToolCallDto.
@@ -239,6 +270,35 @@ export type ApprovalBatchSegment = {
   onReject?: ApprovalResolutionHandler
 }
 
+/**
+ * Ticket-escalation offer block. Visually the client approval card (same
+ * Figma component), but a SEPARATE segment type on purpose: it resolves
+ * through the ticket-escalation GraphQL mutations rather than the tool
+ * approval endpoint, and hosts that hide pending tool approvals from the
+ * thread must still render this one inline.
+ *
+ * `cancelled` is the wire's SUPERSEDED — the client typed over the offer.
+ */
+export type EscalationOfferSegment = {
+  type: 'escalation_offer'
+  data: EscalationOfferData
+  status?: ChatApprovalStatus
+  resolvedByName?: string | null
+  onApprove?: ApprovalResolutionHandler
+  onReject?: ApprovalResolutionHandler
+}
+
+/**
+ * The conversation was handed off to a human technician. Decoded from the
+ * `TICKET_ESCALATED` block, so it appears for every escalation path the
+ * backend emits it for — including the inactivity auto-escalation, which
+ * raises no offer and therefore has no offer state to infer from.
+ */
+export type TicketEscalatedSegment = {
+  type: 'ticket_escalated'
+  data: TicketEscalatedData
+}
+
 export type ErrorSegment = {
   type: 'error'
   title: string
@@ -251,7 +311,7 @@ export type ContextCompactionSegment = {
   summary?: string
 }
 
-export type MessageSegment = TextSegment | ThinkingSegment | GuideSegment | AskSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
+export type MessageSegment = TextSegment | ThinkingSegment | GuideSegment | AskSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | EscalationOfferSegment | TicketEscalatedSegment | ErrorSegment | ContextCompactionSegment
 
 export type MessageContent = string | MessageSegment[]
 
@@ -329,6 +389,29 @@ export interface ApprovalResultMessageData extends MessageDataBase {
   resolvedByName?: string | null
 }
 
+/**
+ * Persisted escalation-offer row. The PENDING row carries `text`/`origin`;
+ * the resolution is a SECOND row with the same `offerId`, state
+ * APPROVED/DECLINED/SUPERSEDED and no text — matched on replay by id.
+ */
+export interface EscalationOfferMessageData extends MessageDataBase {
+  type: 'ESCALATION_OFFER'
+  offerId?: string
+  state?: string
+  text?: string
+  origin?: string
+  resolvedByUserId?: string | null
+  resolvedByName?: string | null
+}
+
+export interface TicketEscalatedMessageData extends MessageDataBase {
+  type: 'TICKET_ESCALATED'
+  ticketId?: string
+  ticketNumber?: number
+  reason?: TicketEscalationReason
+  text?: string
+}
+
 export interface ErrorMessageData extends MessageDataBase {
   type: 'ERROR'
   error?: string
@@ -373,6 +456,8 @@ export type MessageData =
   | ExecutedToolMessageData
   | ApprovalRequestMessageData
   | ApprovalResultMessageData
+  | EscalationOfferMessageData
+  | TicketEscalatedMessageData
   | ErrorMessageData
   | AIMetadataMessageData
   | SystemMessageData

package/src/components/chat/types/processing.types.ts

@@ -47,6 +47,19 @@ export interface MessageProcessingOptions {
   chatTypeFilter?: string
   /** Map of approval statuses by request ID */
   approvalStatuses?: Record<string, ChatApprovalStatus>
+  /**
+   * Terminal escalation-offer states by offer id, from live chunks the host
+   * has already seen. Needed because an offer and its resolution are two
+   * separate persisted rows: SUPERSEDED is published *because* the client
+   * typed, so a user message always separates them and the two rows land in
+   * different assistant envelopes.
+   */
+  escalationOfferStates?: Record<string, ChatApprovalStatus>
+  /** Escalation approve handler; distinct from `onApprove` because offers
+   *  resolve through the ticket-escalation mutations. */
+  onEscalationApprove?: (offerId?: string) => Promise<void> | void
+  /** Escalation reject handler. See `onEscalationApprove`. */
+  onEscalationReject?: (offerId?: string) => Promise<void> | void
   /** Approval types to display directly (others get escalated) - defaults to all types */
   displayApprovalTypes?: string[]
   /**

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

@@ -930,3 +930,102 @@ describe('mid-stream refetch (turn partially persisted)', () => {
     expect(ids(merged)).toEqual([U0.id, A0.id, PERSISTED_PARTIAL.id, unrelatedLive.id])
   })
 })
+
+describe('ordering of surviving realtime messages', () => {
+  // The merge concatenates: all persisted history, then every realtime message
+  // the coverage rules kept, each side in its own order. These pin that
+  // contract, which nothing asserted before — the suite tested only WHICH
+  // messages survive, never where they land — and which an attempt to
+  // chronologically interleave the two sides repeatedly broke.
+  const H_U0: TestMessage = { ...U0, streamSeq: 5 }
+  const H_A0: TestMessage = { ...A0, streamSeq: 10 }
+  /**
+   * Sent from a notification while the window was away, and persisted. NO
+   * `streamSeq`: the backend does not stamp user MESSAGE_REQUEST rows, which is
+   * the missing signal that makes interleaving guesswork.
+   */
+  const AWAY_U: TestMessage = {
+    id: 'bbbb0001',
+    role: 'user',
+    content: 'replied from a notification',
+    timestamp: t(3000),
+  }
+  /** Mingo's answer to it. Assistant rows DO carry a sequence. */
+  const AWAY_A: TestMessage = {
+    id: 'bbbb0002',
+    role: 'assistant',
+    content: txt('answered while the window was away'),
+    timestamp: t(3100),
+    streamSeq: 80,
+  }
+
+  it('appends surviving realtime messages after all persisted history', () => {
+    // A technician direct message the snapshot has not caught up with. Its own
+    // role's persisted max (H_U0, seq 5) is below it, so coverage keeps it.
+    const unpersistedDirect: TestMessage = {
+      id: 'direct-1500-old',
+      role: 'user',
+      content: 'a direct message history has not persisted yet',
+      timestamp: t(1500),
+      streamSeq: 40,
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [H_U0, H_A0, AWAY_U, AWAY_A],
+      existingMessages: [H_U0, H_A0, unpersistedDirect],
+      streamingMessageId: null,
+      historyFetchedAt: 9000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 40,
+    })
+
+    expect(ids(merged)).toEqual([H_U0.id, H_A0.id, AWAY_U.id, AWAY_A.id, unpersistedDirect.id])
+  })
+
+  it('keeps survivors in store order, sequence or no sequence', () => {
+    // The guard against reordering the two kinds against each other: an
+    // optimistic bubble carries no sequence and a replayed direct message does,
+    // and sorting by sequence would render the user's question below the reply
+    // that came after it.
+    const optimistic: TestMessage = {
+      id: 'optimistic-9400-x',
+      role: 'user',
+      content: 'just typed, no seq of its own',
+      timestamp: t(9400),
+    }
+    const laterDirect: TestMessage = {
+      id: 'direct-9500-x',
+      role: 'user',
+      content: 'and a direct message after it',
+      timestamp: t(9500),
+      streamSeq: 40,
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [H_U0, H_A0, AWAY_U, AWAY_A],
+      existingMessages: [H_U0, H_A0, optimistic, laterDirect],
+      streamingMessageId: null,
+      // Before either was minted, so neither can be in the snapshot.
+      historyFetchedAt: 9000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 40,
+    })
+
+    expect(ids(merged)).toEqual([H_U0.id, H_A0.id, AWAY_U.id, AWAY_A.id, optimistic.id, laterDirect.id])
+  })
+
+  it('keeps history in snapshot order even when its sequences do not climb', () => {
+    // The snapshot is the server's account of the conversation; the merge is
+    // not entitled to second-guess it from a `streamSeq` that looks out of
+    // order, which is what any sort of the two sides together would do.
+    const outOfOrder: TestMessage = { ...H_A0, id: 'aaaa0009', streamSeq: 3 }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [H_U0, outOfOrder, AWAY_U, AWAY_A],
+      existingMessages: [H_U0],
+      streamingMessageId: null,
+      historyFetchedAt: 9000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 0,
+    })
+
+    expect(ids(merged)).toEqual([H_U0.id, outOfOrder.id, AWAY_U.id, AWAY_A.id])
+  })
+})