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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.523-1675.4360.1",
+  "version": "0.0.523",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -393,8 +393,7 @@
     "tailwindcss-animate": "^1.0.7",
     "unist-util-visit": "^5.0.0",
     "use-stick-to-bottom": "^1.1.4",
-    "vaul": "^1.1.2",
-    "react-remove-scroll": "^2.7.1"
+    "vaul": "^1.1.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",

package/src/chat-protocol/__tests__/__snapshots__/nats-decoder-golden.test.ts.snap

@@ -179,6 +179,26 @@ exports[`decodeNatsChunk — golden corpus > maps the full recorded corpus to no
     "title": "Agent crashed",
     "type": "error",
   },
+  "escalation_offer_approved": {
+    "offerId": "offer-1",
+    "resolvedByName": "John Smith",
+    "status": "approved",
+    "type": "escalation-offer-resolved",
+  },
+  "escalation_offer_missing_id": null,
+  "escalation_offer_pending": {
+    "offerId": "offer-1",
+    "origin": "MANUAL",
+    "text": "This ticket can be handed off to a technician.",
+    "type": "escalation-offer",
+  },
+  "escalation_offer_superseded": {
+    "offerId": "offer-1",
+    "resolvedByName": "John Smith",
+    "status": "cancelled",
+    "type": "escalation-offer-resolved",
+  },
+  "escalation_offer_unknown_state": null,
   "executed_tool": {
     "data": {
       "integratedToolType": "TACTICAL_RMM",
@@ -307,6 +327,15 @@ exports[`decodeNatsChunk — golden corpus > maps the full recorded corpus to no
     "type": "thinking-delta",
   },
   "thinking_missing_text": null,
+  "ticket_escalated": {
+    "reason": "INACTIVITY",
+    "text": "Automatically escalated to a human technician.",
+    "ticketId": "ticket-1",
+    "ticketNumber": 1002,
+    "type": "ticket-escalated",
+  },
+  "ticket_escalated_missing_reason": null,
+  "ticket_escalated_missing_ticket_id": null,
   "token_usage": {
     "contextSize": 180000,
     "inputTokensSize": 1200,

package/src/chat-protocol/__tests__/nats-decoder-golden.test.ts

@@ -161,6 +161,38 @@ const CORPUS: Record<string, unknown> = {
     command: 'echo hi',
   },
 
+  escalation_offer_pending: {
+    type: 'ESCALATION_OFFER',
+    offerId: 'offer-1',
+    state: 'PENDING',
+    text: 'This ticket can be handed off to a technician.',
+    origin: 'MANUAL',
+  },
+  escalation_offer_approved: {
+    type: 'ESCALATION_OFFER',
+    offerId: 'offer-1',
+    state: 'APPROVED',
+    displayName: 'John Smith',
+  },
+  escalation_offer_superseded: {
+    type: 'ESCALATION_OFFER',
+    offerId: 'offer-1',
+    state: 'SUPERSEDED',
+    resolvedByName: 'John Smith',
+  },
+  escalation_offer_unknown_state: { type: 'ESCALATION_OFFER', offerId: 'offer-1', state: 'WAT' },
+  escalation_offer_missing_id: { type: 'ESCALATION_OFFER', state: 'PENDING' },
+
+  ticket_escalated: {
+    type: 'TICKET_ESCALATED',
+    ticketId: 'ticket-1',
+    ticketNumber: 1002,
+    reason: 'INACTIVITY',
+    text: 'Automatically escalated to a human technician.',
+  },
+  ticket_escalated_missing_reason: { type: 'TICKET_ESCALATED', ticketId: 'ticket-1' },
+  ticket_escalated_missing_ticket_id: { type: 'TICKET_ESCALATED', reason: 'INACTIVITY' },
+
   approval_result_approved: {
     type: 'APPROVAL_RESULT',
     approvalRequestId: 'req-1',

package/src/chat-protocol/events.ts

@@ -160,6 +160,69 @@ export interface ApprovalResolvedEvent extends ChatStreamEventBase {
   willAutoContinue?: boolean
 }
 
+/** The client is offered a handoff of this ticket to a human technician
+ *  (NATS `ESCALATION_OFFER` chunk in state PENDING). Distinct from
+ *  `approval-request`: it resolves through the ticket-escalation mutations,
+ *  never the tool-approval flow, and it is raised by four different origins
+ *  (Fae's own tool call, the client's header button, a deterministic
+ *  trigger, or a deferred surfacing at turn end) that all render alike. */
+export interface EscalationOfferEvent extends ChatStreamEventBase {
+  type: 'escalation-offer'
+  offerId: string
+  text: string
+  origin?: string
+}
+
+/** Wire vocabulary of `EscalationOfferData.state`. */
+export const ESCALATION_STATE = {
+  PENDING: 'PENDING',
+  APPROVED: 'APPROVED',
+  DECLINED: 'DECLINED',
+  SUPERSEDED: 'SUPERSEDED',
+} as const
+
+/** Terminal wire state → the shared `ChatApprovalStatus` vocabulary; `null`
+ *  for PENDING or anything unrecognized. Shared by BOTH decoders (live
+ *  chunks and persisted rows) so a state can never mean two things. */
+export function escalationResolvedStatus(
+  state: unknown,
+): EscalationOfferResolvedEvent['status'] | null {
+  switch (state) {
+    case ESCALATION_STATE.APPROVED:
+      return 'approved'
+    case ESCALATION_STATE.DECLINED:
+      return 'rejected'
+    case ESCALATION_STATE.SUPERSEDED:
+      return 'cancelled'
+    default:
+      return null
+  }
+}
+
+/** An escalation offer reached a terminal state. The wire's SUPERSEDED
+ *  (the client typed over a pending offer) maps onto `cancelled` so the
+ *  whole stack keeps ONE status vocabulary (`ChatApprovalStatus`). The
+ *  resolved chunk carries no text — consumers flip the existing block. */
+export interface EscalationOfferResolvedEvent extends ChatStreamEventBase {
+  type: 'escalation-offer-resolved'
+  offerId: string
+  status: 'approved' | 'rejected' | 'cancelled'
+  resolvedByName?: string | null
+}
+
+/** The conversation was handed off to a human technician (`TICKET_ESCALATED`).
+ *  A first-class block rather than something inferred from an offer's state,
+ *  so paths that raise no offer at all — the inactivity auto-escalation — still
+ *  produce a receipt. `text` is nullable on the wire; consumers supply the
+ *  fallback copy. */
+export interface TicketEscalatedEvent extends ChatStreamEventBase {
+  type: 'ticket-escalated'
+  ticketId: string
+  ticketNumber?: number
+  reason: string
+  text?: string
+}
+
 /** Per-turn metadata. Raw wire values pass through UNVALIDATED — the
  *  consumer replicates the legacy truthiness/typeof gates (so a
  *  malformed frame degrades identically to the pre-SSOT parser). */
@@ -265,6 +328,9 @@ export type ChatStreamEvent =
   | ToolExecutionEvent
   | ApprovalRequestEvent
   | ApprovalResolvedEvent
+  | EscalationOfferEvent
+  | EscalationOfferResolvedEvent
+  | TicketEscalatedEvent
   | ChatMetadataEvent
   | UsageEvent
   | TokenUsageEvent

package/src/chat-protocol/nats-decoder.ts

@@ -18,6 +18,7 @@
 
 import { MESSAGE_TYPE } from '../components/chat/types/message.types'
 import type { AskOptionData } from '../components/chat/types/message.types'
+import { ESCALATION_STATE, escalationResolvedStatus } from './events'
 import type { ApprovalToolCall, ChatStreamEvent } from './events'
 
 /** Minimal structural view of a NATS chunk (see `ChunkData` in
@@ -215,6 +216,52 @@ export function decodeNatsChunk(chunk: unknown): ChatStreamEvent | null {
       }
     }
 
+    case MESSAGE_TYPE.ESCALATION_OFFER: {
+      const offerId = typeof data.offerId === 'string' ? data.offerId : ''
+      if (!offerId) return null
+      if (data.state === ESCALATION_STATE.PENDING) {
+        return {
+          type: 'escalation-offer',
+          offerId,
+          text: typeof data.text === 'string' ? data.text : '',
+          origin: typeof data.origin === 'string' ? data.origin : undefined,
+          ...seq,
+        }
+      }
+      const status = escalationResolvedStatus(data.state)
+      if (!status) return null
+      // Same realtime/history field split as APPROVAL_RESULT: the chunk names
+      // the resolver `displayName`, the persisted row `resolvedByName`.
+      return {
+        type: 'escalation-offer-resolved',
+        offerId,
+        status,
+        resolvedByName:
+          typeof data.resolvedByName === 'string'
+            ? data.resolvedByName
+            : typeof data.displayName === 'string'
+              ? data.displayName
+              : undefined,
+        ...seq,
+      }
+    }
+
+    case MESSAGE_TYPE.TICKET_ESCALATED: {
+      const ticketId = typeof data.ticketId === 'string' ? data.ticketId : ''
+      const reason = typeof data.reason === 'string' ? data.reason : ''
+      // Both are non-null on the wire; a payload missing either is malformed
+      // rather than a variant to render.
+      if (!ticketId || !reason) return null
+      return {
+        type: 'ticket-escalated',
+        ticketId,
+        reason,
+        ticketNumber: typeof data.ticketNumber === 'number' ? data.ticketNumber : undefined,
+        text: typeof data.text === 'string' ? data.text : undefined,
+        ...seq,
+      }
+    }
+
     case MESSAGE_TYPE.ERROR:
       return {
         type: 'error',

package/src/components/chat/__tests__/escalation-offer.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Ticket-escalation offer: decode → accumulate → resolve, across both the
+ * live NATS path and history replay.
+ *
+ * The two behaviours worth pinning are the ones that were expensive to get
+ * right, not the happy path:
+ *   - an offer arriving with NO preceding MESSAGE_START must APPEND to the
+ *     trailing bubble, never replace its segments (the backend surfaces
+ *     deferred offers after the turn ends, so this is the normal shape, and
+ *     a cumulative emit there wipes the reply the user is reading);
+ *   - an offer and its resolution are two persisted rows separated by the
+ *     user message that caused SUPERSEDED, so the flip has to reach a bubble
+ *     that was already flushed.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { decodeNatsChunk } from '../../../chat-protocol/nats-decoder'
+import { createChatStreamReducer } from '../stream/chat-stream-reducer'
+import { processHistoricalMessages } from '../utils/process-historical-messages'
+import type { EscalationOfferSegment, HistoricalMessage, MessageSegment } from '../types'
+
+const OFFER_ID = 'offer-1'
+const OFFER_TEXT = 'Having issues with the AI assistant? This ticket can be handed off to a technician.'
+
+const offerChunk = (streamSeq: number) => ({
+  type: 'ESCALATION_OFFER',
+  offerId: OFFER_ID,
+  state: 'PENDING',
+  text: OFFER_TEXT,
+  origin: 'MANUAL',
+  streamSeq,
+})
+
+const resolvedChunk = (state: string, streamSeq: number) => ({
+  type: 'ESCALATION_OFFER',
+  offerId: OFFER_ID,
+  state,
+  displayName: 'John Smith',
+  streamSeq,
+})
+
+const offers = (segments: MessageSegment[] | string | undefined): EscalationOfferSegment[] =>
+  Array.isArray(segments)
+    ? (segments.filter((s) => s.type === 'escalation_offer') as EscalationOfferSegment[])
+    : []
+
+const historyRow = (id: string, data: Record<string, unknown>): HistoricalMessage => ({
+  id,
+  createdAt: '2026-08-06T12:00:00Z',
+  owner: { type: 'ASSISTANT' },
+  messageData: [data as never],
+})
+
+describe('decodeNatsChunk — ESCALATION_OFFER', () => {
+  it('decodes the PENDING chunk as an offer', () => {
+    expect(decodeNatsChunk(offerChunk(1))).toEqual({
+      type: 'escalation-offer',
+      offerId: OFFER_ID,
+      text: OFFER_TEXT,
+      origin: 'MANUAL',
+      seq: 1,
+    })
+  })
+
+  it('maps the terminal states onto the shared approval-status vocabulary', () => {
+    expect(decodeNatsChunk(resolvedChunk('APPROVED', 2))).toMatchObject({ status: 'approved' })
+    expect(decodeNatsChunk(resolvedChunk('DECLINED', 3))).toMatchObject({ status: 'rejected' })
+    expect(decodeNatsChunk(resolvedChunk('SUPERSEDED', 4))).toMatchObject({ status: 'cancelled' })
+  })
+
+  it('reads the resolver from `displayName` (chunk) or `resolvedByName` (row)', () => {
+    expect(decodeNatsChunk(resolvedChunk('APPROVED', 5))).toMatchObject({
+      resolvedByName: 'John Smith',
+    })
+    expect(
+      decodeNatsChunk({ ...resolvedChunk('APPROVED', 6), displayName: undefined, resolvedByName: 'Ada' }),
+    ).toMatchObject({ resolvedByName: 'Ada' })
+  })
+
+  it('drops malformed chunks instead of emitting a card with no id', () => {
+    expect(decodeNatsChunk({ type: 'ESCALATION_OFFER', state: 'PENDING' })).toBeNull()
+    expect(decodeNatsChunk({ type: 'ESCALATION_OFFER', offerId: OFFER_ID, state: 'WAT' })).toBeNull()
+  })
+})
+
+describe('chat stream reducer — escalation offer', () => {
+  const trailingSegments = (reducer: ReturnType<typeof createChatStreamReducer>): MessageSegment[] => {
+    const { messages } = reducer.state
+    return messages[messages.length - 1]?.segments ?? []
+  }
+
+  const feed = (reducer: ReturnType<typeof createChatStreamReducer>, chunks: unknown[]) => {
+    for (const chunk of chunks) {
+      const event = decodeNatsChunk(chunk)
+      if (event) reducer.apply(event)
+    }
+  }
+
+  it('appends to the trailing bubble when the offer arrives after MESSAGE_END', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' })
+    feed(reducer, [
+      { type: 'MESSAGE_START', streamSeq: 1 },
+      { type: 'TEXT', text: 'Let me take a look at that.', streamSeq: 2 },
+      { type: 'MESSAGE_END', streamSeq: 3 },
+      offerChunk(4),
+    ])
+
+    const segments = trailingSegments(reducer)
+    // The prose the user was reading survives — this is the whole point.
+    expect(segments.find((s: MessageSegment) => s.type === 'text')).toMatchObject({
+      text: 'Let me take a look at that.',
+    })
+    expect(offers(segments)).toHaveLength(1)
+  })
+
+  it('flips the card in place on resolution and stamps the resolver', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' })
+    feed(reducer, [
+      { type: 'MESSAGE_START', streamSeq: 1 },
+      offerChunk(2),
+      resolvedChunk('APPROVED', 3),
+    ])
+
+    const rendered = offers(trailingSegments(reducer))
+    expect(rendered).toHaveLength(1)
+    expect(rendered[0]).toMatchObject({ status: 'approved', resolvedByName: 'John Smith' })
+  })
+
+  it('does not claim the agent is working while an offer is pending', () => {
+    const busy: unknown[] = []
+    const reducer = createChatStreamReducer({
+      transport: 'nats',
+      onEffect: (effect) => {
+        if (effect.name === 'onAgentBusy') busy.push(effect)
+      },
+    })
+    feed(reducer, [{ type: 'MESSAGE_START', streamSeq: 1 }, offerChunk(2), resolvedChunk('APPROVED', 3)])
+    expect(busy).toHaveLength(0)
+  })
+
+  it('is idempotent across a redelivered offer (JetStream catch-up)', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' })
+    feed(reducer, [{ type: 'MESSAGE_START', streamSeq: 1 }, offerChunk(2), { type: 'MESSAGE_END', streamSeq: 3 }])
+    // A replay re-decodes the same chunk with its original seq; the seq gate
+    // drops it, but the upsert must hold even if the gate ever moves.
+    const event = decodeNatsChunk({ ...offerChunk(2), streamSeq: 9 })
+    if (event) reducer.apply(event)
+    expect(offers(trailingSegments(reducer))).toHaveLength(1)
+  })
+})
+
+describe('processHistoricalMessages — escalation offer', () => {
+  it('renders the offer inline rather than deferring it to the sticky flush', () => {
+    const { messages } = processHistoricalMessages([
+      historyRow('m1', {
+        type: 'ESCALATION_OFFER',
+        offerId: OFFER_ID,
+        state: 'PENDING',
+        text: OFFER_TEXT,
+        origin: 'MANUAL',
+      }),
+    ])
+    expect(messages).toHaveLength(1)
+    expect(offers(messages[0].content)[0]).toMatchObject({ status: 'pending' })
+  })
+
+  it('flips a card that was flushed into an EARLIER bubble than its resolution', () => {
+    const { messages } = processHistoricalMessages([
+      historyRow('m1', {
+        type: 'ESCALATION_OFFER',
+        offerId: OFFER_ID,
+        state: 'PENDING',
+        text: OFFER_TEXT,
+      }),
+      // The user typing is exactly what produces SUPERSEDED, so this message
+      // is not incidental — it is what splits the two rows apart.
+      {
+        id: 'm2',
+        createdAt: '2026-08-06T12:01:00Z',
+        owner: { type: 'CLIENT' },
+        messageData: [{ type: 'TEXT', text: 'actually, never mind' } as never],
+      },
+      historyRow('m3', {
+        type: 'ESCALATION_OFFER',
+        offerId: OFFER_ID,
+        state: 'SUPERSEDED',
+        resolvedByName: 'John Smith',
+      }),
+    ])
+
+    const rendered = messages.flatMap((m) => offers(m.content))
+    expect(rendered).toHaveLength(1)
+    expect(rendered[0]).toMatchObject({ status: 'cancelled', resolvedByName: 'John Smith' })
+    // Card text comes from the PENDING row; the resolution row carries none.
+    expect(rendered[0].data.text).toBe(OFFER_TEXT)
+  })
+
+  it('honours the host overlay when the resolution row is not in the fetched pages', () => {
+    const { messages } = processHistoricalMessages(
+      [
+        historyRow('m1', {
+          type: 'ESCALATION_OFFER',
+          offerId: OFFER_ID,
+          state: 'PENDING',
+          text: OFFER_TEXT,
+        }),
+      ],
+      { escalationOfferStates: { [OFFER_ID]: 'approved' } },
+    )
+    expect(messages.flatMap((m) => offers(m.content))[0]).toMatchObject({ status: 'approved' })
+  })
+})
+
+describe('TICKET_ESCALATED — the handoff receipt', () => {
+  const escalated = (over = {}) => ({
+    type: 'TICKET_ESCALATED',
+    ticketId: 't-1',
+    ticketNumber: 1002,
+    reason: 'INACTIVITY',
+    text: 'Automatically escalated to a human technician because the conversation had no new messages.',
+    ...over,
+  })
+
+  const receipts = (segments: MessageSegment[] | string | undefined) =>
+    Array.isArray(segments) ? segments.filter((s) => s.type === 'ticket_escalated') : []
+
+  it('decodes the chunk, keeping the backend copy verbatim', () => {
+    expect(decodeNatsChunk({ ...escalated(), streamSeq: 42 })).toEqual({
+      type: 'ticket-escalated',
+      ticketId: 't-1',
+      ticketNumber: 1002,
+      reason: 'INACTIVITY',
+      text: 'Automatically escalated to a human technician because the conversation had no new messages.',
+      seq: 42,
+    })
+  })
+
+  it('drops payloads missing a non-null wire field', () => {
+    expect(decodeNatsChunk({ type: 'TICKET_ESCALATED', reason: 'INACTIVITY' })).toBeNull()
+    expect(decodeNatsChunk({ type: 'TICKET_ESCALATED', ticketId: 't-1' })).toBeNull()
+  })
+
+  it('survives an unknown reason without a client change', () => {
+    expect(decodeNatsChunk(escalated({ reason: 'USER_REQUESTED' }))).toMatchObject({
+      reason: 'USER_REQUESTED',
+    })
+  })
+
+  it('appends to the trailing bubble when it arrives with no turn open', () => {
+    // The inactivity auto-escalation fires from a scheduler: no MESSAGE_START
+    // precedes it, so a cumulative emit here would wipe the last reply.
+    const reducer = createChatStreamReducer({ transport: 'nats' })
+    for (const chunk of [
+      { type: 'MESSAGE_START', streamSeq: 1 },
+      { type: 'TEXT', text: 'Let me look into that.', streamSeq: 2 },
+      { type: 'MESSAGE_END', streamSeq: 3 },
+      { ...escalated(), streamSeq: 4 },
+    ]) {
+      const event = decodeNatsChunk(chunk)
+      if (event) reducer.apply(event)
+    }
+    const { messages } = reducer.state
+    const segments = messages[messages.length - 1]?.segments ?? []
+    expect(segments.find((s: MessageSegment) => s.type === 'text')).toMatchObject({
+      text: 'Let me look into that.',
+    })
+    expect(receipts(segments)).toHaveLength(1)
+  })
+
+  it('renders on history replay with no escalation offer anywhere in the thread', () => {
+    const { messages } = processHistoricalMessages([historyRow('m1', escalated())])
+    const rendered = messages.flatMap((m) => receipts(m.content))
+    expect(rendered).toHaveLength(1)
+    expect(rendered[0]).toMatchObject({ data: { ticketId: 't-1', reason: 'INACTIVITY' } })
+  })
+})

package/src/components/chat/chat-message-enhanced.tsx

@@ -8,6 +8,8 @@ import { SquareAvatar } from "../ui/square-avatar"
 import { ToolExecutionDisplay } from "./tool-execution-display"
 import { ApprovalRequestMessage } from "./approval-request-message"
 import { ApprovalBatchMessage } from "./approval-batch-message"
+import { EscalationOfferMessage } from "./escalation-offer-message"
+import { TicketEscalatedMessage } from "./ticket-escalated-message"
 import { ErrorMessageDisplay } from "./error-message-display"
 import { ContextCompactionDisplay } from "./context-compaction-display"
 import { ThinkingDisplay } from "./thinking-display"
@@ -725,6 +727,19 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
                       variant={approvalVariant}
                     />
                   )
+                } else if (segment.type === 'escalation_offer') {
+                  return (
+                    <EscalationOfferMessage
+                      key={index}
+                      data={segment.data}
+                      status={segment.status}
+                      resolvedByName={segment.resolvedByName}
+                      onApprove={segment.onApprove}
+                      onReject={segment.onReject}
+                    />
+                  )
+                } else if (segment.type === 'ticket_escalated') {
+                  return <TicketEscalatedMessage key={index} data={segment.data} timestamp={timestamp} />
                 } else if (segment.type === 'error') {
                   return (
                     <ErrorMessageDisplay

package/src/components/chat/chat-message-list.tsx

@@ -897,7 +897,9 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
     const lastSegment = lastSegments?.[lastSegments.length - 1]
     const isPausedOnApproval =
       !!lastSegment &&
-      (lastSegment.type === 'approval_request' || lastSegment.type === 'approval_batch') &&
+      (lastSegment.type === 'approval_request' ||
+        lastSegment.type === 'approval_batch' ||
+        lastSegment.type === 'escalation_offer') &&
       (lastSegment.status === undefined || lastSegment.status === 'pending')
     const showStreamingLoader =
       isTyping &&

package/src/components/chat/escalation-offer-message.tsx

@@ -0,0 +1,49 @@
+"use client"
+
+import { forwardRef, type HTMLAttributes } from "react"
+import { cn } from "../../utils/cn"
+import { ApprovalRequestMessage } from "./approval-request-message"
+import type { EscalationOfferSegment } from "./types/message.types"
+
+export interface EscalationOfferMessageProps extends HTMLAttributes<HTMLDivElement> {
+  data: EscalationOfferSegment['data']
+  status?: EscalationOfferSegment['status']
+  resolvedByName?: string | null
+  onApprove?: EscalationOfferSegment['onApprove']
+  onReject?: EscalationOfferSegment['onReject']
+}
+
+/**
+ * Ticket-escalation offer block.
+ *
+ * Renders THROUGH the client approval card rather than reimplementing it:
+ * per Figma (fae chat › "escalation to admin") the offer is that exact
+ * component, down to the Approve/Reject labels and the resolved
+ * "Approved by {name}" pill. Only the wiring differs — approve/reject call
+ * the ticket-escalation mutations, never the tool-approval endpoint — which
+ * is why this is a distinct segment type with its own handlers.
+ *
+ * The handoff receipt that follows an approval is NOT rendered here: it is its
+ * own `TICKET_ESCALATED` block on the wire, which also covers the inactivity
+ * auto-escalation — a path that raises no offer to infer from.
+ */
+const EscalationOfferMessage = forwardRef<HTMLDivElement, EscalationOfferMessageProps>(
+  ({ className, data, status = 'pending', resolvedByName, onApprove, onReject, ...props }, ref) => (
+    <div ref={ref} className={cn("flex flex-col", className)} {...props}>
+      <ApprovalRequestMessage
+        variant="client"
+        // The client card renders `explanation` as its body and never shows
+        // `command`; the offer's whole payload is that one backend-fixed line.
+        data={{ command: '', explanation: data.text, requestId: data.offerId }}
+        status={status}
+        resolvedByName={resolvedByName}
+        onApprove={onApprove}
+        onReject={onReject}
+      />
+    </div>
+  )
+)
+
+EscalationOfferMessage.displayName = "EscalationOfferMessage"
+
+export { EscalationOfferMessage }

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

@@ -13,22 +13,29 @@ The single exported hook. Accepts `UseJetStreamDialogSubscriptionOptions` and re
 |---|---|
 | `isConnected` | Whether the NATS WebSocket connection is live |
 | `isSubscribed` | Whether the JetStream consumer is active |
-| `reconnectionCount` | Increments whenever the live tail is re-established: a NATS reconnect, a JetStream ordered-consumer recreation, or a resync after the page was hidden. Callers refetch persisted history on every increment |
+| `reconnectionCount` | Increments whenever the live tail is re-established: a NATS reconnect, a JetStream ordered-consumer recreation, a resync after the page was hidden, or a host reporting either via `resyncSignal`. Callers refetch persisted history on every increment; one absence counts once even when two sources report it |
 | `currentStreamSeq` | Highest stream sequence number observed |
 
+**Host-supplied resync (`resyncSignal` option):**
+
+A counter the embedder bumps when it knows, from outside the page, that the tail may have missed something — an absence the page could not observe (a native shell whose window visibility never reaches `document.visibilityState`), or a write made on the page's behalf while it was away. Any increase is treated exactly like a reconnect. The value at mount is a baseline, rebased on every `dialogId` change so switching to a conversation with a lower count cannot swallow later resyncs.
+
 **Internal refs (stable across renders):**
 
 - `clientRef` — shared `NatsClient` instance
 - `lastRecoveryReportRef` — timestamp floor so a flapping consumer cannot storm callers with refetches
+- `resyncTimerRef` — trailing-edge timer collapsing resync requests within `RESYNC_COALESCE_MS`; cleared on dialog change and unmount so a request never crosses a conversation boundary
+- `lastResyncSignalRef` — baseline for `resyncSignal`, rebased per dialog
 - `subscriptionRef` — active `JetStreamSubscriptionHandle`
 - `highestStreamSeqRef` — tracks max stream sequence for gap-free resume
 
 **Effect order (declaration order matters):**
 
 1. **Connection effect** — acquires/releases the shared NATS client when `enabled` or `wsUrl` changes; drives the `startConnectionLifecycle` which emits status events.
-2. **Dialog reset effect** — resets `highestStreamSeqRef` when `dialogId` changes so a new dialog never inherits a stale start sequence.
-3. **Visibility effect** — after the page has been hidden longer than `RESYNC_AFTER_HIDDEN_MS`, returning to view bumps the counter: a hidden page can stop receiving without the socket ever closing, and nothing else reports that.
-4. **Subscription effect** — creates or recreates the ephemeral consumer when `isConnected`, `dialogId`, `topic`, `streamName`, or the reconnect counter change.
+2. **Dialog reset effect** — resets `highestStreamSeqRef`, rebases the `resyncSignal` baseline, and drops any pending resync when `dialogId` changes, so a new dialog never inherits a stale start sequence or the previous dialog's refetch.
+3. **Visibility effect** — after the page has been hidden longer than `RESYNC_AFTER_HIDDEN_MS`, returning to view requests a resync: a hidden page can stop receiving without the socket ever closing, and nothing else reports that.
+4. **Host-signal effect** — an increase in `resyncSignal` requests a resync on the same path, for absences and out-of-band writes the page cannot see.
+5. **Subscription effect** — creates or recreates the ephemeral consumer when `isConnected`, `dialogId`, `topic`, `streamName`, or the reconnect counter change.
 
 **Deliver policy logic:**