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

package/src/components/chat/utils/extract-incomplete-message-state.ts

@@ -109,6 +109,16 @@ export function extractIncompleteMessageState(
         break
       }
 
+      case 'escalation_offer':
+        // A pending offer leaves the turn unfinished so the reducer holds the
+        // card and the resolution chunk can flip it in place. It never sets
+        // `agentBusy`: Fae is blocked on the user's decision, and on approval
+        // she goes SILENT rather than resuming — there is no work to spin for.
+        if (!segment.status || segment.status === 'pending') {
+          hasIncompleteState = true
+        }
+        break
+
       case 'context_compaction':
         if (segment.status === 'started') {
           hasIncompleteState = true

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

@@ -1,6 +1,7 @@
 import type {
   ApprovalBatchSegment,
   ApprovalRequestSegment,
+  EscalationOfferSegment,
   MessageContent,
   ToolExecutionSegment,
 } from '../types'
@@ -106,6 +107,12 @@ function turnRequestKeys(content: MessageContent): Set<string> {
     } else if (seg.type === 'approval_request') {
       const id = (seg as ApprovalRequestSegment).data?.requestId
       if (id) keys.add(id)
+    } else if (seg.type === 'escalation_offer') {
+      const id = (seg as EscalationOfferSegment).data?.offerId
+      if (id) keys.add(id)
+      // `ticket_escalated` is deliberately absent: its only id is the ticketId,
+      // which is dialog-scoped, so a re-escalated dialog would false-match an
+      // older bubble and slice the newest persisted turn out of the thread.
     } else if (seg.type === 'approval_batch') {
       const data = (seg as ApprovalBatchSegment).data
       if (data?.approvalRequestId) keys.add(data.approvalRequestId)

package/src/components/chat/utils/message-segment-accumulator.ts

@@ -16,6 +16,9 @@ import type {
   ApprovalBatchSegment,
   ApprovalBatchExecutionState,
   ApprovalResolutionHandler,
+  EscalationOfferSegment,
+  TicketEscalatedData,
+  TicketEscalatedSegment,
   ContextCompactionSegment,
   ErrorSegment,
   PendingApproval,
@@ -35,6 +38,12 @@ export interface AccumulatorCallbacks {
    *  approve/reject signature incl. the boolean failure flag. */
   onApprove?: ApprovalResolutionHandler
   onReject?: ApprovalResolutionHandler
+  /** Escalation offers resolve through the ticket-escalation mutations, NOT
+   *  the tool-approval endpoint, so they carry their own pair of handlers.
+   *  Sharing `onApprove`/`onReject` would POST an offer id to the approval
+   *  endpoint, which has no record of it. */
+  onEscalationApprove?: ApprovalResolutionHandler
+  onEscalationReject?: ApprovalResolutionHandler
 }
 
 /**
@@ -432,11 +441,73 @@ export class MessageSegmentAccumulator {
   }
 
   /**
-   * Update status of an existing approval segment (single or batch).
+   * Add a ticket-escalation offer block. Upserts by `offerId` for the same
+   * reason `addApprovalBatch` does: the consumer-store replay path feeds
+   * `[existing..., new...]` back through `replaySegments`, which would
+   * otherwise yield two cards for one offer.
+   */
+  addEscalationOffer(
+    offerId: string,
+    text: string,
+    origin: string | undefined,
+    status: ChatApprovalStatus = 'pending',
+    resolvedByName?: string | null,
+  ): MessageSegment[] {
+    const existingIndex = this.segments.findIndex(
+      (s): s is EscalationOfferSegment =>
+        s.type === 'escalation_offer' && s.data.offerId === offerId,
+    )
+    const existing =
+      existingIndex !== -1 ? (this.segments[existingIndex] as EscalationOfferSegment) : undefined
+
+    const segment: EscalationOfferSegment = {
+      type: 'escalation_offer',
+      // The resolved chunk carries no text/origin — a redelivered offer must
+      // not blank the card the PENDING chunk already painted.
+      data: { offerId, text: text || existing?.data.text || '', origin: origin ?? existing?.data.origin },
+      status,
+      resolvedByName: resolvedByName ?? existing?.resolvedByName,
+      onApprove: this.callbacks.onEscalationApprove,
+      onReject: this.callbacks.onEscalationReject,
+    }
+
+    if (existingIndex !== -1) {
+      this.segments[existingIndex] = segment
+      return this.getSegments()
+    }
+
+    this.segments.push(segment)
+    return this.getSegments()
+  }
+
+  /**
+   * Add the handoff receipt. Upserts by `ticketId` so a redelivered block
+   * (JetStream catch-up over hydrated history) can't stack a second notice.
+   */
+  addTicketEscalated(data: TicketEscalatedData): MessageSegment[] {
+    const segment: TicketEscalatedSegment = { type: 'ticket_escalated', data }
+    const existingIndex = this.segments.findIndex(
+      (s) => s.type === 'ticket_escalated' && s.data.ticketId === data.ticketId,
+    )
+    if (existingIndex !== -1) {
+      this.segments[existingIndex] = segment
+      return this.getSegments()
+    }
+    this.segments.push(segment)
+    return this.getSegments()
+  }
+
+  /**
+   * Update status of an existing approval segment (single, batch, or
+   * escalation offer).
    * `resolvedByName` (when provided) is stamped onto the matching batch segment so the
    * resolved card shows "by {name}"; omit it to leave any existing value untouched.
    */
-  updateApprovalStatus(requestId: string, status: ChatApprovalStatus, resolvedByName?: string | null): MessageSegment[] {
+  updateApprovalStatus(
+    requestId: string,
+    status: ChatApprovalStatus,
+    resolvedByName?: string | null,
+  ): MessageSegment[] {
     // ONE rule, two containers: `applyApprovalStatusToSegment` is the
     // same predicate the message-array projection uses
     // (`projectApprovalResolutionToMessages`) — anchor status flip AND
@@ -571,6 +642,14 @@ export class MessageSegmentAccumulator {
           )
           break
         }
+        case 'escalation_offer': {
+          const { data, status, resolvedByName } = segment
+          this.addEscalationOffer(data.offerId, data.text, data.origin, status, resolvedByName)
+          break
+        }
+        case 'ticket_escalated':
+          this.addTicketEscalated(segment.data)
+          break
         case 'error':
           this.addError(segment.title, segment.details)
           break

package/src/components/chat/utils/process-historical-messages.ts

@@ -37,11 +37,12 @@ import {
   type MessageData,
   type MessageOwner,
 } from '../types'
-import type { ChatStreamEvent } from '../../../chat-protocol/events'
+import { ESCALATION_STATE, escalationResolvedStatus, type ChatStreamEvent } from '../../../chat-protocol/events'
 // One normalizer for ask rows, shared with the live decoder — history and the
 // stream must agree on which options are usable.
 import { normalizeAskOptions } from '../../../chat-protocol/nats-decoder'
 import { MessageSegmentAccumulator, createMessageSegmentAccumulator } from './message-segment-accumulator'
+import { applyApprovalStatusToSegment } from '../stream/message-mutations'
 import { getCommandText } from './tool-call-helpers'
 
 function getOwnerDisplayName(owner?: MessageOwner): string {
@@ -199,6 +200,38 @@ export function decodeHistoricalMessageData(data: MessageData): ChatStreamEvent
       }
       return null
 
+    case MESSAGE_TYPE.ESCALATION_OFFER: {
+      if (!('offerId' in data) || !data.offerId) return null
+      if (data.state === ESCALATION_STATE.PENDING) {
+        return {
+          type: 'escalation-offer',
+          offerId: data.offerId,
+          text: data.text || '',
+          origin: data.origin,
+        }
+      }
+      const status = escalationResolvedStatus(data.state)
+      if (!status) return null
+      return {
+        type: 'escalation-offer-resolved',
+        offerId: data.offerId,
+        status,
+        resolvedByName: data.resolvedByName,
+      }
+    }
+
+    case MESSAGE_TYPE.TICKET_ESCALATED:
+      if ('ticketId' in data && data.ticketId && data.reason) {
+        return {
+          type: 'ticket-escalated',
+          ticketId: data.ticketId,
+          reason: data.reason,
+          ticketNumber: data.ticketNumber,
+          text: data.text,
+        }
+      }
+      return null
+
     case MESSAGE_TYPE.ERROR:
       if ('error' in data) {
         return {
@@ -240,6 +273,18 @@ type EscalatedApprovals = Map<
   { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
 >
 
+/**
+ * Terminal escalation-offer resolutions collected while walking history, so
+ * they can be applied to ALREADY-FLUSHED bubbles after the walk. The offer
+ * row and its resolution row are separated by the user message that caused
+ * SUPERSEDED, which puts them in different assistant envelopes — by the time
+ * the resolution is read, the accumulator holding the card has been reset.
+ */
+type OfferResolutions = Map<
+  string,
+  { status: ChatApprovalStatus; resolvedByName?: string | null }
+>
+
 /**
  * Replay one decoded event into the shared per-turn segment kernel with the
  * HISTORY approval semantics (an omitted `displayApprovalTypes` means
@@ -252,13 +297,43 @@ function applyHistoryEvent(
   approvalStatuses: Record<string, string>,
   options: MessageProcessingOptions,
   escalatedApprovals?: EscalatedApprovals,
+  offerResolutions?: OfferResolutions,
 ): void {
   // batchApprovalsEnabled is owned by the consumer (oss-tenant chat client /
   // openframe-frontend tickets). Defaults to ON so consumers that haven't
   // wired the flag yet get the batch UI; pass `false` to force legacy.
-  const { displayApprovalTypes, batchApprovalsEnabled = true } = options
+  const { displayApprovalTypes, batchApprovalsEnabled = true, escalationOfferStates } = options
 
   switch (event.type) {
+    case 'escalation-offer':
+      // Always a real segment, never the tracked/flushed treatment single
+      // approvals get: the offer belongs inline where it was posted.
+      accumulator.addEscalationOffer(
+        event.offerId,
+        event.text,
+        event.origin,
+        escalationOfferStates?.[event.offerId] ?? 'pending',
+      )
+      break
+
+    case 'ticket-escalated':
+      accumulator.addTicketEscalated({
+        ticketId: event.ticketId,
+        ticketNumber: event.ticketNumber,
+        reason: event.reason,
+        text: event.text,
+      })
+      break
+
+    case 'escalation-offer-resolved':
+      // Recorded, not applied here: `applyOfferResolutions` runs after every
+      // flush and covers the same-bubble case as well as the cross-bubble one.
+      offerResolutions?.set(event.offerId, {
+        status: event.status,
+        resolvedByName: event.resolvedByName,
+      })
+      break
+
     case 'text-delta':
       accumulator.appendText(event.text)
       break
@@ -464,11 +539,20 @@ export function processHistoricalMessages(
     // opt-in: pass the same explicit list to both.
     displayApprovalTypes,
     batchApprovalsEnabled,
+    escalationOfferStates,
+    onEscalationApprove,
+    onEscalationReject,
   } = options
 
   const processedMessages: ProcessedMessage[] = []
-  const accumulator = createMessageSegmentAccumulator({ onApprove, onReject })
+  const accumulator = createMessageSegmentAccumulator({
+    onApprove,
+    onReject,
+    onEscalationApprove,
+    onEscalationReject,
+  })
   const escalatedApprovals: EscalatedApprovals = new Map()
+  const offerResolutions: OfferResolutions = new Map()
 
   let currentAssistantId: string | null = null
   let currentAssistantTimestamp: Date | null = null
@@ -581,8 +665,9 @@ export function processHistoricalMessages(
           event,
           accumulator,
           approvalStatuses,
-          { displayApprovalTypes, batchApprovalsEnabled },
+          { displayApprovalTypes, batchApprovalsEnabled, escalationOfferStates },
           escalatedApprovals,
+          offerResolutions,
         )
       })
 
@@ -614,12 +699,46 @@ export function processHistoricalMessages(
     })
   }
 
+  applyOfferResolutions(processedMessages, offerResolutions)
+
   return {
     messages: processedMessages,
     escalatedApprovals: escalatedApprovals
   }
 }
 
+/**
+ * Flip escalation-offer cards that were flushed into an EARLIER bubble than
+ * their resolution row. Mutates `processedMessages` in place (it is local to
+ * the caller and not yet handed out). Uses the same `applyApprovalStatusToSegment`
+ * rule as the live projection so the two paths cannot drift.
+ */
+function applyOfferResolutions(
+  processedMessages: ProcessedMessage[],
+  offerResolutions: OfferResolutions,
+): void {
+  if (offerResolutions.size === 0) return
+
+  processedMessages.forEach((msg, index) => {
+    if (!Array.isArray(msg.content)) return
+    let changed = false
+    const content = msg.content.map((segment) => {
+      if (segment.type !== 'escalation_offer') return segment
+      const resolution = offerResolutions.get(segment.data.offerId)
+      if (!resolution) return segment
+      const next = applyApprovalStatusToSegment(
+        segment,
+        segment.data.offerId,
+        resolution.status,
+        resolution.resolvedByName,
+      )
+      if (next !== segment) changed = true
+      return next
+    })
+    if (changed) processedMessages[index] = { ...msg, content }
+  })
+}
+
 /**
  * Extract error messages from historical messages
  * Returns a separate array of error messages that should be displayed

package/src/components/features/board/ticket-card.tsx

@@ -4,7 +4,7 @@ import { useSortable } from '@dnd-kit/sortable'
 import { CSS } from '@dnd-kit/utilities'
 import Link from '../../../embed-shims/next-link'
 import * as React from 'react'
-import { LaptopIcon, Flag02Icon, MessagesIcon } from '../../icons-v2-generated'
+import { LaptopIcon, Flag02Icon, MessagesIcon, UserCheckIcon } from '../../icons-v2-generated'
 import { DeletedUserAvatar } from '../../ui/deleted-user-avatar'
 import { SquareAvatar } from '../../ui/square-avatar'
 import { Tag } from '../../ui/tag'
@@ -119,6 +119,12 @@ export function TicketCardBody({ ticket, columnColor, renderAssignSlot, onApprov
           </Tooltip>
         </TooltipProvider>
       )}
+      {ticket.escalatedByUser && (
+        <div className="flex items-center gap-[var(--spacing-system-xxs)] text-h6 text-ods-open-yellow">
+          <UserCheckIcon className="size-4 shrink-0" />
+          <span className="truncate">Escalated by User</span>
+        </div>
+      )}
       {showNewMessage && (
         <Tag
           label="New Message"

package/src/components/features/board/types.ts

@@ -36,6 +36,13 @@ export interface BoardTicket {
   createdAt?: string
   hasNewMessage?: boolean
   pendingApproval?: BoardTicketPendingApproval
+  /**
+   * The client asked for a human and confirmed the handoff, so this ticket
+   * reached its lane by escalation rather than an inactivity auto-escalation or
+   * an admin takeover. Called out on the card because it changes how urgently a
+   * technician should pick it up.
+   */
+  escalatedByUser?: boolean
 }
 
 export interface BoardColumnDef {

package/src/components/ui/modal-v2.tsx

@@ -2,7 +2,7 @@
 
 import * as React from "react"
 import { useEffect, useState } from "react"
-import { RemoveScroll } from "react-remove-scroll"
+import { usePreventScroll } from "@react-aria/overlays"
 import { XmarkIcon } from "../icons-v2-generated"
 import { cn } from "../../utils/cn"
 
@@ -142,19 +142,14 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
       return () => clearTimeout(timeout)
     }, [isOpen])
 
-    // Scroll lock via the SAME library Radix primitives use internally
-    // (react-remove-scroll is ref-counted and composes with itself). The
-    // previous react-aria lock FOUGHT the lock a Radix Select opened inside
-    // the modal added on top — body jumped and the page behind went black
-    // while the select was open.
+    // Shared ref-counted scroll lock (react-aria) — restores prior styles on
+    // release instead of clobbering to 'unset'.
+    usePreventScroll({ isDisabled: !isOpen })
 
     // Escape key (document-level: top-of-stack semantics for modals)
     useEffect(() => {
       const handleKeyDown = (event: KeyboardEvent) => {
-        // A nested Radix layer (Select, DropdownMenu) preventDefaults the
-        // Escape it consumes — without this check, closing a select inside
-        // the modal closed the WHOLE modal.
-        if (event.key === 'Escape' && !event.defaultPrevented) {
+        if (event.key === 'Escape') {
           onClose()
         }
       }
@@ -170,7 +165,6 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
     const state = isOpen ? "open" : "closed"
 
     return (
-      <RemoveScroll enabled={isOpen} removeScrollBar={false}>
       <div className="fixed inset-0 z-[1300] flex items-end md:items-center justify-center">
         <div
           data-state={state}
@@ -224,7 +218,6 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
           </ModalContext.Provider>
         </div>
       </div>
-      </RemoveScroll>
     )
   }
 )

package/src/stories/EscalationOfferMessage.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from "@storybook/nextjs-vite";
+import type React from "react";
+
+import { EscalationOfferMessage } from "../components/chat/escalation-offer-message";
+
+/**
+ * `escalation_offer` message segment — Fae asking the client to confirm a
+ * handoff to a human technician (Figma: fae chat › "escalation to admin").
+ *
+ * Renders THROUGH the client approval card rather than reimplementing it, so
+ * it is pixel-identical to `Chat/Client/ApprovalRequestMessage` down to the
+ * Approve/Reject labels and the resolved pill. What differs is the wiring:
+ * approve/reject call the ticket-escalation GraphQL mutations, never the
+ * tool-approval endpoint — which is why it is a distinct segment type.
+ *
+ * The body copy is backend-fixed; the client never composes it. `origin`
+ * (TOOL / MANUAL / a trigger reason) is decoded for telemetry only — every
+ * origin renders the same card.
+ */
+
+const OFFER_TEXT =
+	"Having issues with the AI assistant? This ticket can be handed off to a technician. Fae will no longer respond in this conversation. A technician will review the ticket and reply when available.";
+
+const baseData = { offerId: "offer-1", text: OFFER_TEXT, origin: "MANUAL" };
+
+const plainDecorator = (Story: React.ComponentType) => (
+	<div style={{ maxWidth: 600, background: "var(--color-bg)" }} className="p-4">
+		<Story />
+	</div>
+);
+
+const meta = {
+	title: "Chat/Client/EscalationOfferMessage",
+	component: EscalationOfferMessage,
+	tags: ["autodocs"],
+	parameters: {
+		docs: {
+			description: {
+				component:
+					"Renders an `escalation_offer` segment: the backend-fixed handoff prompt with Approve/Reject, or a resolved status pill. Approve performs the handoff (ticket → Tech Required, Fae goes silent); Reject just records the choice.",
+			},
+		},
+	},
+	decorators: [plainDecorator],
+} satisfies Meta<typeof EscalationOfferMessage>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Pending — the client has not decided yet. */
+export const Pending: Story = {
+	args: {
+		data: baseData,
+		status: "pending",
+		onApprove: () => {},
+		onReject: () => {},
+	},
+};
+
+/** Approved — the handoff ran. Paired in the thread with `TicketEscalatedMessage`. */
+export const ApprovedByUser: Story = {
+	args: { data: baseData, status: "approved", resolvedByName: "John Smith" },
+};
+
+/** Declined — the client chose to keep working with Fae. */
+export const DeclinedByUser: Story = {
+	args: { data: baseData, status: "rejected", resolvedByName: "John Smith" },
+};
+
+/**
+ * Superseded — the client typed a new message over the pending offer, which
+ * the backend treats as declining it. Maps onto the shared `cancelled` status.
+ */
+export const Superseded: Story = {
+	args: { data: baseData, status: "cancelled", resolvedByName: "John Smith" },
+};
+
+/** Raised by Fae's own `escalateToHuman` tool call rather than the header action. */
+export const FromToolCall: Story = {
+	args: {
+		data: { ...baseData, origin: "TOOL" },
+		status: "pending",
+		onApprove: () => {},
+		onReject: () => {},
+	},
+};

package/src/stories/TicketCard.stories.tsx

@@ -150,6 +150,18 @@ export const WithNewMessage: Story = {
   },
 }
 
+/**
+ * The client asked for a human and confirmed the handoff — an amber footer row
+ * distinguishing it from an inactivity auto-escalation or an admin takeover,
+ * which reach the same lane silently. Driven by the ticket's `escalatedByUser`
+ * field, not by a label.
+ */
+export const EscalatedByUser: Story = {
+  args: {
+    ticket: { ...BASE_TICKET, id: 'ticket-escalated', escalatedByUser: true },
+  },
+}
+
 /**
  * Pending CLIENT approval — collapsed grey "Pending client approval" row with a
  * loader glyph. Expand it to reach the shared approve/reject affordance.

package/src/stories/TicketEscalatedMessage.stories.tsx

@@ -0,0 +1,98 @@
+import type { Meta, StoryObj } from "@storybook/nextjs-vite";
+import type React from "react";
+
+import { TicketEscalatedMessage } from "../components/chat/ticket-escalated-message";
+
+/**
+ * `ticket_escalated` message segment — the handoff receipt (Figma:
+ * `ai-assistant-info`, type=escalation).
+ *
+ * A first-class block on the wire, NOT something the client infers from an
+ * escalation offer's state, so it also covers the inactivity auto-escalation —
+ * a path that raises no offer at all.
+ *
+ * The body is whatever the backend authored, so the reason it gives stays
+ * server-side: the card never branches on `data.reason`, which is why a reason
+ * added server-side needs no client change. The body WRAPS rather than
+ * truncating as the mock does — see the component for why — so the block is
+ * 72px only while the text fits two lines.
+ */
+
+const baseData = {
+	ticketId: "68a1f0c2b3d4e5f6a7b8c9d0",
+	ticketNumber: 1002,
+	reason: "INACTIVITY",
+	text: "Automatically escalated to a human technician because the conversation had no new messages for an extended period.",
+};
+
+/** Fixed so the timestamp doesn't churn between snapshots. */
+const TIMESTAMP = new Date("2026-08-07T14:47:00");
+
+const plainDecorator = (Story: React.ComponentType) => (
+	<div style={{ maxWidth: 600, background: "var(--color-bg)" }} className="p-4">
+		<Story />
+	</div>
+);
+
+const meta = {
+	title: "Chat/Client/TicketEscalatedMessage",
+	component: TicketEscalatedMessage,
+	tags: ["autodocs"],
+	parameters: {
+		docs: {
+			description: {
+				component:
+					"Renders a `TICKET_ESCALATED` block: a bordered info tile, the fixed 'Handed Off to a Technician' title, the message timestamp, and the backend's explanation.",
+			},
+		},
+	},
+	decorators: [plainDecorator],
+} satisfies Meta<typeof TicketEscalatedMessage>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The inactivity auto-escalation — the only reason the wire defines today. */
+export const Inactivity: Story = {
+	args: { data: baseData, timestamp: TIMESTAMP },
+};
+
+/**
+ * `text` is nullable on the wire; the card falls back to the design's generic
+ * line rather than rendering an empty body.
+ */
+export const NoBodyFallback: Story = {
+	args: { data: { ...baseData, text: undefined }, timestamp: TIMESTAMP },
+};
+
+/** No timestamp — the row collapses to title-only, body unchanged. */
+export const WithoutTimestamp: Story = {
+	args: { data: baseData },
+};
+
+/** Long explanation — wraps and the block grows; nothing is clipped. */
+export const LongBody: Story = {
+	args: {
+		data: {
+			...baseData,
+			text: "Automatically escalated to a human technician because the conversation had no new messages for an extended period while the ticket was still assigned to the AI assistant, and no diagnostic step produced a resolution.",
+		},
+		timestamp: TIMESTAMP,
+	},
+};
+
+/**
+ * A reason the client has never seen. The open `TicketEscalationReason` union
+ * plus rendering from `text` mean a reason added server-side needs no client
+ * change — this story is the regression guard for that.
+ */
+export const UnknownReason: Story = {
+	args: {
+		data: {
+			...baseData,
+			reason: "USER_REQUESTED",
+			text: "Escalated at the user's request.",
+		},
+		timestamp: TIMESTAMP,
+	},
+};