@flamingo-stack/openframe-frontend-core 0.0.508 → 0.0.509

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

@@ -770,3 +770,163 @@ describe('page helpers', () => {
     expect(maxPersistedStreamSeq(undefined)).toBe(0)
   })
 })
+
+/**
+ * The scenario the reducer's `streamSeq` stamp exists for: a history refetch
+ * lands MID-STREAM (a reconnect after the window lost focus fires one). History
+ * holds only what the backend has persisted so far — often just the user row —
+ * while the store holds several live assistant bubbles of the turn in flight.
+ */
+describe('mid-stream refetch (live turn not yet persisted)', () => {
+  // Two bubbles of ONE live turn: the backend splits a turn (a preamble, then
+  // the tool bubble), so only ONE of them can be `streamingMessageId`.
+  const LIVE_A: TestMessage = {
+    id: 'assistant-3000-a',
+    role: 'assistant',
+    content: txt('let me check that'),
+    timestamp: t(3000),
+    streamSeq: 41,
+  }
+  const LIVE_B: TestMessage = {
+    id: 'assistant-3100-b',
+    role: 'assistant',
+    content: [tool('exec-7', 'EXECUTING_TOOL')],
+    timestamp: t(3100),
+    streamSeq: 42,
+  }
+  // What history returns mid-turn: the user row only. It carries no
+  // `lastChunkStreamSeq` (the backend does not stamp user rows).
+  const U_LIVE: TestMessage = { id: 'aaaa0009', role: 'user', content: 'check the disk', timestamp: t(2900) }
+
+  it('keeps every live bubble, not just the streaming one', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U_LIVE],
+      existingMessages: [U0, A0, U_LIVE, LIVE_A, LIVE_B],
+      // Only the bubble currently being written is exempt by id — the earlier
+      // one of the same turn has to survive on its own seq evidence.
+      streamingMessageId: LIVE_B.id,
+      // The refetch instant is AFTER both bubbles were created, which is
+      // exactly what the wall-clock fallback misreads as "history has them".
+      historyFetchedAt: 3500,
+      historyMaxStreamSeq: 0,
+      realtimeSeenStreamSeq: 42,
+    })
+
+    expect(ids(merged)).toEqual([U0.id, A0.id, U_LIVE.id, LIVE_A.id, LIVE_B.id])
+  })
+
+  it('drops a live bubble once a persisted row of its role reaches its seq', () => {
+    // Self-healing side of the same rule: when the turn IS persisted, the
+    // synthetic must go or it renders twice.
+    const persisted: TestMessage = {
+      id: 'aaaa0010',
+      role: 'assistant',
+      content: txt('let me check that'),
+      timestamp: t(3000),
+      streamSeq: 41,
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U_LIVE, persisted],
+      existingMessages: [U0, A0, U_LIVE, LIVE_A],
+      streamingMessageId: null,
+      historyFetchedAt: 3500,
+      historyMaxStreamSeq: 41,
+      realtimeSeenStreamSeq: 41,
+    })
+
+    expect(ids(merged)).toEqual([U0.id, A0.id, U_LIVE.id, persisted.id])
+  })
+})
+
+/**
+ * The other half of the mid-stream refetch: history has begun persisting the
+ * turn that is STILL STREAMING. Its snapshot stops at whatever chunk the
+ * backend had written, so the two copies disagree — the same tool row reads
+ * `pending` in one and `failed` in the other. Ids cannot match here: adoption
+ * only happens on a replay, and a refetch mid-stream has none.
+ */
+describe('mid-stream refetch (turn partially persisted)', () => {
+  const LIVE: TestMessage = {
+    id: 'assistant-4000-live',
+    role: 'assistant',
+    content: [tool('exec-1', 'EXECUTED_TOOL'), tool('exec-2', 'EXECUTED_TOOL'), tool('exec-3', 'EXECUTING_TOOL')],
+    timestamp: t(4000),
+    streamSeq: 90,
+  }
+  // History's snapshot of the SAME turn, under its Mongo id, two chunks behind.
+  const PERSISTED_PARTIAL: TestMessage = {
+    id: 'aaaa0020',
+    role: 'assistant',
+    content: [tool('exec-1', 'EXECUTED_TOOL'), tool('exec-2', 'EXECUTING_TOOL')],
+    timestamp: t(3900),
+    streamSeq: 70,
+  }
+
+  it('keeps ONE copy — the live one — when the turn is still streaming', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, PERSISTED_PARTIAL],
+      existingMessages: [U0, A0, LIVE],
+      streamingMessageId: LIVE.id,
+      historyFetchedAt: 4200,
+      historyMaxStreamSeq: 70,
+      realtimeSeenStreamSeq: 90,
+    })
+
+    expect(ids(merged)).toEqual([U0.id, A0.id, LIVE.id])
+  })
+
+  it('keeps the live copy when it is richer even after the stream ends', () => {
+    // No `streamingMessageId` any more, but the turn's own request ids still
+    // identify the twin and the live copy still holds more of it.
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, PERSISTED_PARTIAL],
+      existingMessages: [U0, A0, LIVE],
+      streamingMessageId: null,
+      historyFetchedAt: 4200,
+      historyMaxStreamSeq: 70,
+      realtimeSeenStreamSeq: 90,
+    })
+
+    expect(ids(merged)).toEqual([U0.id, A0.id, LIVE.id])
+  })
+
+  it('lets the persisted copy win once it has caught up (self-heals)', () => {
+    const persistedFull: TestMessage = {
+      ...PERSISTED_PARTIAL,
+      content: [tool('exec-1', 'EXECUTED_TOOL'), tool('exec-2', 'EXECUTED_TOOL'), tool('exec-3', 'EXECUTED_TOOL')],
+      streamSeq: 95,
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, persistedFull],
+      existingMessages: [U0, A0, LIVE],
+      streamingMessageId: null,
+      historyFetchedAt: 4500,
+      historyMaxStreamSeq: 95,
+      realtimeSeenStreamSeq: 90,
+    })
+
+    expect(ids(merged)).toEqual([U0.id, A0.id, persistedFull.id])
+  })
+
+  it('does not pair unrelated turns that merely sit next to each other', () => {
+    // No shared request id → no turn identity → both stand. Guards the widened
+    // match from swallowing a genuinely separate turn.
+    const unrelatedLive: TestMessage = {
+      id: 'assistant-4100-other',
+      role: 'assistant',
+      content: [tool('exec-77', 'EXECUTING_TOOL')],
+      timestamp: t(4100),
+      streamSeq: 91,
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, PERSISTED_PARTIAL],
+      existingMessages: [U0, A0, unrelatedLive],
+      streamingMessageId: unrelatedLive.id,
+      historyFetchedAt: 4200,
+      historyMaxStreamSeq: 70,
+      realtimeSeenStreamSeq: 91,
+    })
+
+    expect(ids(merged)).toEqual([U0.id, A0.id, PERSISTED_PARTIAL.id, unrelatedLive.id])
+  })
+})

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 { createChatStreamReducer } from '../../stream/chat-stream-reducer'
 import type { HistoricalMessage, MessageSegment } from '../../types'
 
 const adminApprovalMessage = (id: string): HistoricalMessage => ({
@@ -95,3 +96,63 @@ describe('processHistoricalMessagesWithErrors — displayApprovalTypes', () => {
     expect(asst?.streamSeq).toBe(50)
   })
 })
+
+/**
+ * PAIRED-PATH contract. The history processor and the realtime reducer are the
+ * two halves of one pipeline, and they DISAGREE by default: history renders
+ * every approval type (the deliberate behaviour this file's header argues for),
+ * the reducer defaults to `['CLIENT']`. Each half is pinned on its own — above
+ * for history, in the reducer's own suite for realtime — but NOTHING asserted
+ * the pair, so aligning one default "for consistency" (or a host wiring the
+ * option into one call site only) changed observable behaviour with every test
+ * still green.
+ *
+ * These two fixtures state the divergence and its remedy in one place: omitted
+ * → the SAME approval is an inline card after a reload and invisible live;
+ * explicit list → both paths agree. Read the header for why the asymmetric
+ * defaults are the intended trade-off (a `['CLIENT']` history default made
+ * pending ADMIN cards vanish on every refetch).
+ */
+describe('displayApprovalTypes — history vs realtime default divergence', () => {
+  const liveApprovalSegments = (displayApprovalTypes?: string[]) => {
+    const effects: Array<{ name: string; args: unknown[] }> = []
+    const r = createChatStreamReducer({
+      transport: 'nats',
+      onEffect: (e) => effects.push(e),
+      ...(displayApprovalTypes ? { displayApprovalTypes } : {}),
+    })
+    r.apply({ type: 'turn-start' })
+    r.apply({
+      type: 'approval-request',
+      requestId: 'req-m1',
+      approvalType: 'ADMIN',
+      command: 'systemctl restart nats',
+    })
+    return {
+      rendered: r.state.messages.flatMap((m) => approvalSegments(m.segments)),
+      escalated: effects.filter((e) => e.name === 'onEscalatedApproval'),
+    }
+  }
+
+  it('OMITTED: history renders the ADMIN card inline, realtime escalates it', () => {
+    const history = processHistoricalMessagesWithErrors([adminApprovalMessage('m1')])
+    expect(history.messages.flatMap((m) => approvalSegments(m.content))).toHaveLength(1)
+    expect(history.escalatedApprovals.size).toBe(0)
+
+    const live = liveApprovalSegments()
+    expect(live.rendered).toHaveLength(0)
+    expect(live.escalated).toHaveLength(1)
+  })
+
+  it('EXPLICIT list: both paths render the same ADMIN card', () => {
+    const types = ['CLIENT', 'ADMIN']
+    const history = processHistoricalMessagesWithErrors([adminApprovalMessage('m1')], {
+      displayApprovalTypes: types,
+    })
+    expect(history.messages.flatMap((m) => approvalSegments(m.content))).toHaveLength(1)
+
+    const live = liveApprovalSegments(types)
+    expect(live.rendered).toHaveLength(1)
+    expect(live.escalated).toHaveLength(0)
+  })
+})

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

@@ -0,0 +1,394 @@
+/**
+ * Phase-0 GOLDEN CHARACTERIZATION TESTS — `processHistoricalMessages`.
+ *
+ * Pins the CURRENT GraphQL-history → ProcessedMessage[] transformation
+ * before the stream-reader unification. A recorded corpus of messageData
+ * rows is processed and the FULL output array is snapshotted.
+ *
+ * NOTE: `process-historical-messages-approvals.test.ts` already guards
+ * displayApprovalTypes semantics — this file deliberately does not
+ * duplicate it and instead records the full-output shape.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { processHistoricalMessages, extractErrorMessages, processHistoricalMessagesWithErrors } from '../process-historical-messages'
+import type { HistoricalMessage } from '../../types'
+
+// Deterministic Date.now for the `pending-approvals-${Date.now()}` synthetic
+// message id + its `new Date()` timestamp.
+const FIXED_NOW = new Date('2026-07-20T10:00:00.000Z')
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(FIXED_NOW)
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/** Recorded corpus — one realistic dialog covering every row shape. */
+const CORPUS: HistoricalMessage[] = [
+  // 1. User message with contextItems (CLIENT owner).
+  {
+    id: 'u1',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:00:00Z',
+    owner: { type: 'CLIENT', userId: 'user-42' },
+    lastChunkStreamSeq: 10,
+    messageData: [
+      {
+        type: 'TEXT',
+        text: 'diagnose this device please',
+        // wire shape: [{ type, id }] — label falls back to id
+        contextItems: [
+          { type: 'device', id: 'dev-1' },
+          { type: 'bad' }, // missing id → filtered
+        ],
+      } as any,
+    ],
+  },
+  // 2. Assistant: thinking + text (grouped into one bubble).
+  {
+    id: 'a1',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:00:05Z',
+    owner: { type: 'ASSISTANT', model: 'claude-sonnet-x' },
+    lastChunkStreamSeq: 20,
+    messageData: [
+      { type: 'THINKING', text: 'Checking device state… ' },
+      { type: 'THINKING', text: 'looks like disk pressure.' },
+      { type: 'TEXT', text: 'The device is low on disk. ' },
+    ],
+  },
+  // 3. Assistant continued: EXECUTING + EXECUTED tool pair merges in place.
+  {
+    id: 'a2',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:00:10Z',
+    owner: { type: 'ASSISTANT' },
+    lastChunkStreamSeq: 15, // lower than a1's — MAX (20) must win on the flushed turn
+    messageData: [
+      {
+        type: 'EXECUTING_TOOL',
+        integratedToolType: 'TACTICAL_RMM',
+        toolFunction: 'run_script',
+        title: 'Run cleanup script',
+        parameters: { script: 'cleanup.sh' },
+        toolExecutionRequestId: 'exec-1',
+      },
+      {
+        type: 'EXECUTED_TOOL',
+        integratedToolType: 'TACTICAL_RMM',
+        toolFunction: 'run_script',
+        parameters: { script: 'cleanup.sh' },
+        result: 'Freed 2.3 GB',
+        success: true,
+        toolExecutionRequestId: 'exec-1',
+      },
+      { type: 'TEXT', text: 'Cleanup done.' },
+    ],
+  },
+  // 4. ADMIN-owned user message (owner-type author resolution: display name from user).
+  {
+    id: 'u2',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:01:00Z',
+    owner: {
+      type: 'ADMIN',
+      user: {
+        id: 'admin-7',
+        firstName: 'Jane',
+        lastName: 'Admin',
+        image: { imageUrl: '/avatars/jane.png' },
+      },
+    },
+    messageData: [{ type: 'TEXT', text: 'please restart the broker' }],
+  },
+  // 5. Assistant: single approval request + result (resolved in-history).
+  {
+    id: 'a3',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:01:05Z',
+    owner: { type: 'ASSISTANT' },
+    lastChunkStreamSeq: 30,
+    messageData: [
+      { type: 'TEXT', text: 'I need approval to restart it.' },
+      {
+        type: 'APPROVAL_REQUEST',
+        approvalRequestId: 'req-1',
+        approvalType: 'CLIENT',
+        command: 'systemctl restart nats',
+        explanation: 'Restart the message broker',
+      },
+      {
+        type: 'APPROVAL_RESULT',
+        approvalRequestId: 'req-1',
+        approved: true,
+        approvalType: 'CLIENT',
+        resolvedByName: 'Jane Admin',
+      },
+    ],
+  },
+  // 6. Assistant: batch approval + per-tool executions merged into the batch.
+  {
+    id: 'a4',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:02:00Z',
+    owner: { type: 'ASSISTANT' },
+    messageData: [
+      {
+        type: 'APPROVAL_REQUEST',
+        approvalRequestId: 'batch-1',
+        approvalType: 'CLIENT',
+        toolCalls: [
+          {
+            toolExecutionRequestId: 'exec-a',
+            toolName: 'create_ticket',
+            toolTitle: 'Create ticket',
+            requiresApproval: true,
+            approvalType: 'CLIENT',
+            toolCallArguments: { subject: 'Printer down' },
+          },
+          {
+            toolExecutionRequestId: 'exec-b',
+            toolName: 'read_kb',
+            requiresApproval: false,
+          },
+        ],
+      },
+      {
+        type: 'APPROVAL_RESULT',
+        approvalRequestId: 'batch-1',
+        approved: true,
+        resolvedByName: 'Alice Client',
+      },
+      {
+        type: 'EXECUTING_TOOL',
+        integratedToolType: 'PSA',
+        toolFunction: 'create_ticket',
+        toolExecutionRequestId: 'exec-a',
+      },
+      {
+        type: 'EXECUTED_TOOL',
+        integratedToolType: 'PSA',
+        toolFunction: 'create_ticket',
+        result: 'Ticket #77 created',
+        success: true,
+        toolExecutionRequestId: 'exec-a',
+      },
+    ],
+  },
+  // 7. Standalone SYSTEM message row — flushes the assistant turn and
+  //    renders as a system-authored row.
+  {
+    id: 's1',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:03:00Z',
+    owner: { type: 'ASSISTANT' },
+    lastChunkStreamSeq: 40,
+    messageData: [{ type: 'SYSTEM', text: 'Technician joined the chat' } as any],
+  },
+  // 8. DIRECT_MESSAGE row. CHARACTERIZATION: DIRECT_MESSAGE is a
+  //    realtime-only concept — the history processors have NO branch for
+  //    it. This ADMIN-owned row takes the user-message path, which only
+  //    renders TEXT data, so it contributes NOTHING to the output (the
+  //    bubble is lost on reload). Recording current behavior as-is; see
+  //    unification plan.
+  {
+    id: 'd1',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:03:30Z',
+    owner: { type: 'ADMIN', user: { id: 'admin-7', firstName: 'Jane' } },
+    messageData: [{ type: 'DIRECT_MESSAGE', text: 'Human here, taking over' } as any],
+  },
+  // 9. Error row inside an assistant turn.
+  {
+    id: 'a5',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:04:00Z',
+    owner: { type: 'ASSISTANT' },
+    messageData: [
+      { type: 'TEXT', text: 'Attempting one more thing… ' },
+      { type: 'ERROR', error: 'Agent crashed', details: '{"error":{"message":"boom"}}' },
+    ],
+  },
+]
+
+describe('processHistoricalMessages — golden corpus', () => {
+  it('processes the full recorded dialog (snapshot)', () => {
+    const result = processHistoricalMessages(CORPUS, {
+      assistantName: 'Mingo AI',
+      assistantType: 'mingo',
+      assistantAvatar: '/avatars/mingo.png',
+    })
+    expect({
+      messages: result.messages,
+      escalatedApprovals: Array.from(result.escalatedApprovals.entries()),
+    }).toMatchSnapshot()
+  })
+
+  it('unresolved single approval is resurrected as a synthetic pending-approvals bubble', () => {
+    const result = processHistoricalMessages([
+      {
+        id: 'a1',
+        createdAt: '2026-07-19T09:00:00Z',
+        owner: { type: 'ASSISTANT' },
+        messageData: [
+          {
+            type: 'APPROVAL_REQUEST',
+            approvalRequestId: 'req-pending',
+            approvalType: 'CLIENT',
+            command: 'reboot server',
+          },
+        ],
+      },
+    ])
+    // Date.now is frozen → deterministic synthetic id.
+    expect(result.messages).toMatchSnapshot()
+  })
+
+  it('owner-type author resolution: CLIENT vs ADMIN vs ADMIN-without-name display names/avatars', () => {
+    const rows: HistoricalMessage[] = [
+      {
+        id: 'u-client',
+        createdAt: '2026-07-19T09:00:00Z',
+        owner: { type: 'CLIENT', userId: 'user-1' },
+        messageData: [{ type: 'TEXT', text: 'from client' }],
+      },
+      {
+        id: 'u-admin-named',
+        createdAt: '2026-07-19T09:00:01Z',
+        owner: {
+          type: 'ADMIN',
+          user: { id: 'adm', firstName: 'Jane', lastName: 'Admin', image: { imageUrl: '/a.png' } },
+        },
+        messageData: [{ type: 'TEXT', text: 'from named admin' }],
+      },
+      {
+        id: 'u-admin-anon',
+        createdAt: '2026-07-19T09:00:02Z',
+        owner: { type: 'ADMIN' },
+        messageData: [{ type: 'TEXT', text: 'from anonymous admin' }],
+      },
+    ]
+    expect(processHistoricalMessages(rows).messages).toMatchSnapshot()
+  })
+
+  it('chatTypeFilter drops rows of other chat types', () => {
+    const rows: HistoricalMessage[] = [
+      {
+        id: 'u1',
+        chatType: 'CLIENT_CHAT',
+        createdAt: '2026-07-19T09:00:00Z',
+        owner: { type: 'CLIENT' },
+        messageData: [{ type: 'TEXT', text: 'visible' }],
+      },
+      {
+        id: 'u2',
+        chatType: 'ADMIN_AI_CHAT',
+        createdAt: '2026-07-19T09:00:01Z',
+        owner: { type: 'CLIENT' },
+        messageData: [{ type: 'TEXT', text: 'filtered out' }],
+      },
+    ]
+    expect(
+      processHistoricalMessages(rows, { chatTypeFilter: 'CLIENT_CHAT' }).messages,
+    ).toMatchSnapshot()
+  })
+})
+
+describe('extractErrorMessages / processHistoricalMessagesWithErrors — golden', () => {
+  it('extractErrorMessages surfaces ERROR rows as standalone error-role messages', () => {
+    expect(extractErrorMessages(CORPUS, { assistantName: 'Mingo AI', assistantType: 'mingo' })).toMatchSnapshot()
+  })
+
+  it('processHistoricalMessagesWithErrors output parity on the same corpus (snapshot)', () => {
+    const result = processHistoricalMessagesWithErrors(CORPUS, {
+      assistantName: 'Mingo AI',
+      assistantType: 'mingo',
+      assistantAvatar: '/avatars/mingo.png',
+    })
+    expect({
+      messages: result.messages,
+      escalatedApprovals: Array.from(result.escalatedApprovals.entries()),
+    }).toMatchSnapshot()
+  })
+})
+
+// ─── GUIDE rows (#1583) ────────────────────────────────────────────────────
+//
+// The realtime path decodes a `GUIDE` chunk into a `guide-delta` event; the
+// history path must decode the persisted `GUIDE` row into the SAME event so a
+// reloaded dialog renders the guide card instead of silently dropping it.
+// Explicit assertions rather than a corpus snapshot — the point is the exact
+// coalescing shape, not the whole-dialog record.
+
+describe('processHistoricalMessages — GUIDE rows', () => {
+  const guideDialog: HistoricalMessage[] = [
+    {
+      id: 'u1',
+      chatType: 'CLIENT_CHAT',
+      createdAt: '2026-07-19T09:00:00Z',
+      owner: { type: 'CLIENT', userId: 'user-42' },
+      messageData: [{ type: 'TEXT', text: 'how do I enroll a device?' }],
+    },
+    {
+      id: 'a1',
+      chatType: 'CLIENT_CHAT',
+      createdAt: '2026-07-19T09:00:05Z',
+      owner: { type: 'ASSISTANT', model: 'claude-sonnet-x' },
+      messageData: [
+        { type: 'GUIDE', text: '## Enroll a device\n' },
+        { type: 'GUIDE', text: '1. Open Settings' },
+      ],
+    },
+  ]
+
+  it('replays consecutive GUIDE rows into ONE coalesced guide segment', () => {
+    const { messages } = processHistoricalMessages(guideDialog, {
+      assistantName: 'Mingo AI',
+      assistantType: 'mingo',
+    })
+    expect(messages).toHaveLength(2)
+    expect(messages[1]).toMatchObject({
+      role: 'assistant',
+      content: [{ type: 'guide', text: '## Enroll a device\n1. Open Settings' }],
+    })
+  })
+
+  it('keeps GUIDE and TEXT as separate segments in wire order', () => {
+    const mixed: HistoricalMessage[] = [
+      {
+        id: 'a1',
+        chatType: 'CLIENT_CHAT',
+        createdAt: '2026-07-19T09:00:05Z',
+        owner: { type: 'ASSISTANT' },
+        messageData: [
+          { type: 'TEXT', text: 'Here is the walkthrough.' },
+          { type: 'GUIDE', text: '## Steps' },
+          { type: 'TEXT', text: 'Anything else?' },
+        ],
+      },
+    ]
+    const { messages } = processHistoricalMessages(mixed)
+    expect(messages[0].content).toEqual([
+      { type: 'text', text: 'Here is the walkthrough.' },
+      { type: 'guide', text: '## Steps' },
+      { type: 'text', text: 'Anything else?' },
+    ])
+  })
+
+  it('a GUIDE row with no text decodes to nothing (no empty card)', () => {
+    const empty: HistoricalMessage[] = [
+      {
+        id: 'a1',
+        chatType: 'CLIENT_CHAT',
+        createdAt: '2026-07-19T09:00:05Z',
+        owner: { type: 'ASSISTANT' },
+        messageData: [{ type: 'GUIDE' } as any],
+      },
+    ]
+    expect(processHistoricalMessages(empty).messages).toEqual([])
+  })
+})