@flamingo-stack/openframe-frontend-core 0.0.532 → 0.0.533

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

@@ -10,6 +10,7 @@
 
 import { describe, it, expect } from 'vitest'
 import { processHistoricalMessagesWithErrors } from '../process-historical-messages'
+import { decodeNatsChunk } from '../../../../chat-protocol/nats-decoder'
 import { createChatStreamReducer } from '../../stream/chat-stream-reducer'
 import type { HistoricalMessage, MessageSegment } from '../../types'
 
@@ -156,3 +157,94 @@ describe('displayApprovalTypes — history vs realtime default divergence', () =
     expect(live.escalated).toHaveLength(0)
   })
 })
+
+/**
+ * A Product Guide card must survive a reload UNCHANGED.
+ *
+ * It arrives as a hub frame the agent re-streams into the dialog, so it is
+ * typed by TOOL and resolves through the hub's confirm route — the tier gate
+ * these tests are about simply does not apply to it. When the rule lived only
+ * in the realtime kernel, the same card rendered inline while streaming and
+ * then, on the next page load, was tier-gated: lifted out of its turn into the
+ * consumer's sticky pending-approvals envelope, stripped of the `fields` that
+ * are its entire body, and stripped of the `origin` that routes its buttons —
+ * so clicking Approve hit the agent's endpoint and 404'd.
+ */
+describe('Product Guide approvals — history and realtime agree', () => {
+  const guideProposalMessage = (id: string): HistoricalMessage => ({
+    id,
+    createdAt: '2026-07-17T12:00:00Z',
+    owner: { type: 'ASSISTANT' },
+    messageData: [
+      {
+        type: 'GUIDE',
+        payload: {
+          kind: 'approval_request',
+          proposalId: 'prop-1',
+          toolName: 'create_ticket',
+          title: 'Open a support ticket',
+          fields: [{ label: 'Subject', value: 'Agent will not enroll' }],
+        },
+      } as any,
+    ],
+  })
+
+  // The narrowest possible tier list: it excludes the guide's tool name, so a
+  // card that still renders proves the gate was bypassed, not merely satisfied.
+  const NARROW_TIERS = ['CLIENT']
+
+  it('renders inline on reload despite a tier list that excludes it', () => {
+    const { messages, escalatedApprovals } = processHistoricalMessagesWithErrors(
+      [guideProposalMessage('m1')],
+      { displayApprovalTypes: NARROW_TIERS },
+    )
+    const rendered = messages.flatMap((m) => approvalSegments(m.content))
+    expect(rendered).toHaveLength(1)
+    expect(escalatedApprovals.size).toBe(0)
+  })
+
+  it('keeps the card in its own turn, not in the sticky pending-approvals envelope', () => {
+    const { messages } = processHistoricalMessagesWithErrors([guideProposalMessage('m1')], {
+      displayApprovalTypes: NARROW_TIERS,
+    })
+    expect(messages.some((m) => String(m.id).startsWith('pending-approvals-'))).toBe(false)
+    const turn = messages.find((m) => m.id === 'm1')
+    expect(approvalSegments(turn?.content)).toHaveLength(1)
+  })
+
+  it('carries the same fields and origin as the live stream', () => {
+    /** The single card's `data`, narrowed off the segment union. */
+    const cardData = (segments: MessageSegment[]) => {
+      const card = segments.find((s) => s.type === 'approval_request')
+      return card?.type === 'approval_request' ? card.data : undefined
+    }
+
+    const { messages } = processHistoricalMessagesWithErrors([guideProposalMessage('m1')], {
+      displayApprovalTypes: NARROW_TIERS,
+    })
+    const replayed = cardData(messages.flatMap((m) => approvalSegments(m.content)))
+
+    const live = createChatStreamReducer({ transport: 'nats', displayApprovalTypes: NARROW_TIERS })
+    live.apply({ type: 'turn-start' })
+    live.apply(
+      decodeNatsChunk({
+        type: 'GUIDE',
+        payload: {
+          kind: 'approval_request',
+          proposalId: 'prop-1',
+          toolName: 'create_ticket',
+          title: 'Open a support ticket',
+          fields: [{ label: 'Subject', value: 'Agent will not enroll' }],
+        },
+      })!,
+    )
+    const streamed = cardData(live.state.messages.flatMap((m) => approvalSegments(m.segments)))
+
+    // Same card either way — down to the rows that ARE its body, and the marker
+    // that decides which backend its buttons talk to.
+    expect(replayed).toEqual(streamed)
+    expect(replayed?.origin).toBe('guide')
+    expect(replayed?.approvalType).toBe('create_ticket')
+    expect(replayed?.fields).toEqual([{ label: 'Subject', value: 'Agent will not enroll' }])
+  })
+})

package/src/components/chat/utils/approval-display.ts

@@ -0,0 +1,70 @@
+/**
+ * WHERE an approval card renders — the one rule, read by every path that turns
+ * an approval into segments.
+ *
+ * There are three such paths and they must agree: the NATS kernel (live chunks),
+ * the SSE kernel, and the history replay that rebuilds a dialog after a reload.
+ * When the rule lived only in the live kernel, a Product Guide card rendered
+ * inline while streaming and then moved into the escalation treatment on the
+ * next page load — same card, two behaviors, and its buttons pointed at the
+ * wrong backend once it moved.
+ *
+ * The rule itself: a card is gated on approval TIER (`displayApprovalTypes`,
+ * the agent's own privilege model) UNLESS it came from the Product Guide, whose
+ * proposals are typed by TOOL and are resolved through the hub's confirm route.
+ * A hub proposal has no tier to gate on, so tier-gating one means escalating it
+ * to a human who has no way to act on it.
+ */
+
+import type { GuideOrigin } from '../../../chat-protocol/events'
+import { GUIDE_ORIGIN, isGuideOrigin } from '../../../chat-protocol/events'
+import type { MessageSegment } from '../types/message.types'
+
+/** Anything carrying the optional `origin` marker: a stream event, or the
+ *  `data` of a rendered segment. */
+interface OriginBearing {
+  origin?: GuideOrigin | string
+}
+
+/** True when this approval was minted by the Product Guide (the hub) rather
+ *  than by the agent's own tool-approval tiering. */
+export function isGuideApproval(source: OriginBearing | null | undefined): boolean {
+  return isGuideOrigin(source)
+}
+
+/** The marker to stamp onto a built segment, or undefined for agent approvals.
+ *  Keeps `origin` out of segment data unless it means something. */
+export function guideApprovalOrigin(
+  source: OriginBearing | null | undefined,
+): GuideOrigin | undefined {
+  return isGuideApproval(source) ? GUIDE_ORIGIN : undefined
+}
+
+/**
+ * Does this approval render inline in its turn (true), or take the consumer's
+ * escalation treatment (false)?
+ *
+ * `displayApprovalTypes` undefined means "no tier gate configured" and every
+ * agent approval displays — the pre-existing history-replay default, preserved
+ * here so both kernels can share one predicate.
+ */
+export function approvalDisplaysInline(
+  source: OriginBearing | null | undefined,
+  approvalType: string,
+  displayApprovalTypes?: readonly string[],
+): boolean {
+  if (isGuideApproval(source)) return true
+  return !displayApprovalTypes || displayApprovalTypes.includes(approvalType)
+}
+
+/**
+ * True for a rendered segment that holds a Product Guide card (single or batch).
+ *
+ * Consumers use it to keep such a card in the message flow, where the hub's own
+ * chat puts it, instead of lifting it into their sticky pending-approvals
+ * footer — and to route its buttons to the hub rather than to the agent.
+ */
+export function isGuideApprovalSegment(segment: MessageSegment): boolean {
+  if (segment.type !== 'approval_request' && segment.type !== 'approval_batch') return false
+  return isGuideApproval(segment.data)
+}

package/src/components/chat/utils/index.ts

@@ -14,6 +14,15 @@ export {
   type AccumulatorCallbacks,
 } from './message-segment-accumulator'
 
+// Where an approval card renders — one rule for both live kernels, the history
+// replay, and hosts that sort cards between their own footer and the flow.
+export {
+  isGuideApproval,
+  guideApprovalOrigin,
+  approvalDisplaysInline,
+  isGuideApprovalSegment,
+} from './approval-display'
+
 // Historical message processing
 export {
   processHistoricalMessages,

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

@@ -12,6 +12,7 @@ import type {
   AskOptionData,
   MessageSegment,
   ToolExecutionSegment,
+  ApprovalRequestField,
   ApprovalRequestSegment,
   ApprovalBatchSegment,
   ApprovalBatchExecutionState,
@@ -324,23 +325,55 @@ export class MessageSegmentAccumulator {
     command: string,
     explanation: string | undefined,
     approvalType: string,
-    status: ChatApprovalStatus = 'pending'
+    status: ChatApprovalStatus = 'pending',
+    /** Structured label/value rows. The card prefers them over `explanation`
+     *  (see `ApprovalRequestData.fields`). Optional because the agent's own
+     *  approvals carry prose; a Product Guide card is almost entirely fields —
+     *  dropping them here left it as a bare title. */
+    fields?: ApprovalRequestField[],
+    /** Where the card came from; `'guide'` keeps it inline (see
+     *  `ApprovalRequestData.origin`). */
+    origin?: 'guide'
   ): MessageSegment[] {
-    const segment: ApprovalRequestSegment = {
+    this.segments.push(
+      this.buildApprovalRequestSegment(
+        requestId,
+        { command, explanation, approvalType, fields, origin },
+        status,
+      ),
+    )
+    return this.getSegments()
+  }
+
+  /**
+   * Build one approval-request segment — THE constructor for this segment type.
+   *
+   * Three paths produce these: `addApprovalRequest` (live stream and replay),
+   * `flushPendingApprovals` (tracked-but-unresolved after a history replay) and
+   * `processApprovalResult` (a result arriving for a tracked request). They used
+   * to hand-write the object each, which is how `fields` and `origin` reached
+   * the card down one path and not the others — the same proposal rendering as a
+   * bare title, or losing the marker that routes its buttons to the hub.
+   */
+  private buildApprovalRequestSegment(
+    requestId: string,
+    approval: PendingApproval,
+    status: ChatApprovalStatus,
+  ): ApprovalRequestSegment {
+    return {
       type: 'approval_request',
       data: {
-        command,
-        explanation,
+        command: approval.command,
+        explanation: approval.explanation,
         requestId,
-        approvalType,
+        approvalType: approval.approvalType,
+        ...(approval.fields && approval.fields.length > 0 ? { fields: approval.fields } : {}),
+        ...(approval.origin ? { origin: approval.origin } : {}),
       },
       status,
       onApprove: this.callbacks.onApprove,
       onReject: this.callbacks.onReject,
     }
-
-    this.segments.push(segment)
-    return this.getSegments()
   }
 
   /**
@@ -363,6 +396,9 @@ export class MessageSegmentAccumulator {
     status: ChatApprovalStatus = 'pending',
     executions?: Record<string, ApprovalBatchExecutionState>,
     resolvedByName?: string | null,
+    /** Where the batch came from; `'guide'` keeps it inline and routes it to
+     *  the hub, exactly as for a single card (see `ApprovalBatchData.origin`). */
+    origin?: 'guide',
   ): MessageSegment[] {
     const existingIndex = this.segments.findIndex(
       (s): s is ApprovalBatchSegment =>
@@ -372,6 +408,9 @@ export class MessageSegmentAccumulator {
     if (existingIndex !== -1) {
       const existing = this.segments[existingIndex] as ApprovalBatchSegment
       const mergedExecutions = executions ?? existing.data.executions
+      // An upsert must not strip the marker: the flip to `approved` comes from
+      // a later event that carries no origin of its own.
+      const mergedOrigin = origin ?? existing.data.origin
       this.segments[existingIndex] = {
         ...existing,
         data: {
@@ -379,6 +418,7 @@ export class MessageSegmentAccumulator {
           approvalType,
           toolCalls,
           ...(mergedExecutions ? { executions: mergedExecutions } : {}),
+          ...(mergedOrigin ? { origin: mergedOrigin } : {}),
         },
         status,
         resolvedByName: resolvedByName ?? existing.resolvedByName,
@@ -395,6 +435,7 @@ export class MessageSegmentAccumulator {
         approvalType,
         toolCalls,
         ...(executions ? { executions } : {}),
+        ...(origin ? { origin } : {}),
       },
       status,
       resolvedByName,
@@ -417,20 +458,17 @@ export class MessageSegmentAccumulator {
   ): { segment: ApprovalRequestSegment; pendingData: PendingApproval | null } | null {
     const pendingApproval = this.pendingApprovals.get(requestId)
     const status: ChatApprovalStatus = approved ? 'approved' : 'rejected'
-    
-    const segment: ApprovalRequestSegment = {
-      type: 'approval_request',
-      data: {
+
+    const segment = this.buildApprovalRequestSegment(
+      requestId,
+      {
+        ...pendingApproval,
         command: pendingApproval?.command || '',
-        explanation: pendingApproval?.explanation,
-        requestId,
         approvalType: pendingApproval?.approvalType || approvalType,
       },
       status,
-      onApprove: this.callbacks.onApprove,
-      onReject: this.callbacks.onReject,
-    }
-    
+    )
+
     this.segments.push(segment)
     
     if (pendingApproval) {
@@ -538,22 +576,11 @@ export class MessageSegmentAccumulator {
    */
   flushPendingApprovals(): ApprovalRequestSegment[] {
     const segments: ApprovalRequestSegment[] = []
-    
+
     this.pendingApprovals.forEach((approval, requestId) => {
-      segments.push({
-        type: 'approval_request',
-        data: {
-          command: approval.command,
-          explanation: approval.explanation,
-          requestId,
-          approvalType: approval.approvalType,
-        },
-        status: 'pending',
-        onApprove: this.callbacks.onApprove,
-        onReject: this.callbacks.onReject,
-      })
+      segments.push(this.buildApprovalRequestSegment(requestId, approval, 'pending'))
     })
-    
+
     return segments
   }
 
@@ -627,6 +654,8 @@ export class MessageSegmentAccumulator {
             data.explanation,
             data.approvalType || '',
             status,
+            data.fields,
+            data.origin,
           )
           break
         }
@@ -639,6 +668,7 @@ export class MessageSegmentAccumulator {
             status,
             data.executions,
             resolvedByName,
+            data.origin,
           )
           break
         }

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

@@ -40,7 +40,8 @@ import {
 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 { guideFrameEvent, normalizeAskOptions } from '../../../chat-protocol/nats-decoder'
+import { approvalDisplaysInline, guideApprovalOrigin } from './approval-display'
 import { MessageSegmentAccumulator, createMessageSegmentAccumulator } from './message-segment-accumulator'
 import { applyApprovalStatusToSegment } from '../stream/message-mutations'
 import { getCommandText } from './tool-call-helpers'
@@ -115,11 +116,21 @@ export function decodeHistoricalMessageData(data: MessageData): ChatStreamEvent
       }
       return null
 
-    case MESSAGE_TYPE.GUIDE:
+    // Two persisted shapes, mirroring the live `GUIDE` chunk: the answer body
+    // (`text`) and a Product Guide frame the agent re-streamed (`payload`,
+    // persisted so a card survives a reload). Decoded through the SAME
+    // `guideFrameEvent` the live path uses — a second mapping here would let
+    // history and realtime disagree about the same bytes.
+    case MESSAGE_TYPE.GUIDE: {
       if ('text' in data && data.text) {
         return { type: 'guide-delta', text: data.text }
       }
+      const payload = 'payload' in data ? data.payload : undefined
+      if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        return guideFrameEvent(payload as Record<string, unknown>)
+      }
       return null
+    }
 
     // Same completeness gate as the live decoder (`decodeNatsChunk`): a
     // persisted row without a question or without options is not a card the
@@ -361,12 +372,24 @@ function applyHistoryEvent(
       const approvalType = event.approvalType || 'CLIENT'
       const toolCalls = event.toolCalls as PendingToolCallData[] | undefined
       const isBatch = !!toolCalls && toolCalls.length > 0
+      // Same rule the live kernels use — a card must not change where it
+      // renders (or which backend its buttons hit) just because the page was
+      // reloaded and it came back through history instead of the stream.
+      const guideOrigin = guideApprovalOrigin(event)
 
-      if (!displayApprovalTypes || displayApprovalTypes.includes(approvalType)) {
+      if (approvalDisplaysInline(event, approvalType, displayApprovalTypes)) {
         if (isBatch) {
           const status = (approvalStatuses[event.requestId] as ChatApprovalStatus) || 'pending'
           if (batchApprovalsEnabled) {
-            accumulator.addApprovalBatch(event.requestId, approvalType, toolCalls!, status)
+            accumulator.addApprovalBatch(
+              event.requestId,
+              approvalType,
+              toolCalls!,
+              status,
+              undefined,
+              undefined,
+              guideOrigin,
+            )
           } else {
             // Flag OFF — unfold batch into N legacy approval cards (same id).
             for (const call of toolCalls!) {
@@ -377,6 +400,8 @@ function applyHistoryEvent(
                 call.toolExplanation,
                 approvalType,
                 status,
+                undefined,
+                guideOrigin,
               )
             }
           }
@@ -389,19 +414,28 @@ function applyHistoryEvent(
           // sticky card on every history re-process. Mirror the batch path
           // and honor `approvalStatuses`.
           const resolvedStatus = approvalStatuses[event.requestId] as ChatApprovalStatus | undefined
-          if (resolvedStatus === 'approved' || resolvedStatus === 'rejected') {
+          const isResolved = resolvedStatus === 'approved' || resolvedStatus === 'rejected'
+          // A guide card is added inline even while pending. The tracked path
+          // below ends in `flushPendingApprovals`, whose segments the consumer
+          // lifts into a sticky footer — that is the treatment for the
+          // consumer's OWN approvals, and it is not how the hub's chat renders
+          // a proposal (nor where its preamble expects it).
+          if (guideOrigin || isResolved) {
             accumulator.addApprovalRequest(
               event.requestId,
               event.command || '',
               event.explanation,
               approvalType,
-              resolvedStatus,
+              resolvedStatus ?? 'pending',
+              event.fields,
+              guideOrigin,
             )
           } else {
             accumulator.trackApprovalRequest(event.requestId, {
               command: event.command || '',
               explanation: event.explanation,
               approvalType,
+              fields: event.fields,
             })
           }
         }