@flamingo-stack/openframe-frontend-core 0.0.579-1952.5335.1 → 0.0.579

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

@@ -886,6 +886,96 @@ describe('createChatStreamReducer — mergeApprovalStatuses precedence', () => {
   });
 });
 
+// ─── GUIDE segments (#1583 threaded through the unified reader) ─────────────
+//
+// A `GUIDE` chunk is an APPEND-ONLY body stream like TEXT/THINKING, but it
+// renders as a titled "OpenFrame Guide" card. It must therefore coalesce the
+// same way (extend the trailing `guide` segment, never push a new one per
+// chunk) and satisfy the same reducer invariants — seq idempotency,
+// referential stability, and post-MESSAGE_END append mode.
+
+describe('createChatStreamReducer — guide segments', () => {
+  it('coalesces consecutive guide deltas into ONE trailing guide segment', () => {
+    const r = createChatStreamReducer({ transport: 'nats' });
+    r.apply({ type: 'turn-start', seq: 1 });
+    r.apply({ type: 'guide-delta', text: '## Enroll a device\n', seq: 2 });
+    r.apply({ type: 'guide-delta', text: '1. Open Settings', seq: 3 });
+    const last = r.state.messages[r.state.messages.length - 1];
+    expect(last.segments).toEqual([{ type: 'guide', text: '## Enroll a device\n1. Open Settings' }]);
+  });
+
+  it('starts a NEW guide segment when a non-guide segment interrupts', () => {
+    const r = createChatStreamReducer({ transport: 'nats' });
+    r.apply({ type: 'turn-start', seq: 1 });
+    r.apply({ type: 'guide-delta', text: 'step one', seq: 2 });
+    r.apply({ type: 'text-delta', text: 'aside', seq: 3 });
+    r.apply({ type: 'guide-delta', text: 'step two', seq: 4 });
+    const last = r.state.messages[r.state.messages.length - 1];
+    expect(last.segments).toEqual([
+      { type: 'guide', text: 'step one' },
+      { type: 'text', text: 'aside' },
+      { type: 'guide', text: 'step two' },
+    ]);
+  });
+
+  it('drops a redelivered guide delta via the shared seq gate (no double text)', () => {
+    const r = createChatStreamReducer({ transport: 'nats' });
+    r.apply({ type: 'turn-start', seq: 1 });
+    r.apply({ type: 'guide-delta', text: 'a', seq: 2 });
+    r.apply({ type: 'guide-delta', text: 'b', seq: 3 });
+    r.apply({ type: 'guide-delta', text: 'b', seq: 3 });
+    r.apply({ type: 'guide-delta', text: 'a', seq: 2 });
+    const last = r.state.messages[r.state.messages.length - 1];
+    expect(last.segments).toEqual([{ type: 'guide', text: 'ab' }]);
+  });
+
+  it('reclones ONLY the touched message — earlier rows keep identity', () => {
+    const r = createChatStreamReducer({ transport: 'nats' });
+    r.apply({ type: 'participant', kind: 'message-request', text: 'how do I enroll?', seq: 1 });
+    r.apply({ type: 'turn-start', seq: 2 });
+    r.apply({ type: 'guide-delta', text: 'first', seq: 3 });
+    const userRow = r.state.messages[0];
+    r.apply({ type: 'guide-delta', text: ' more', seq: 4 });
+    expect(r.state.messages[0]).toBe(userRow);
+  });
+
+  it('post-MESSAGE_END continuation emits a DELTA guide segment with append:true', () => {
+    const effects: Array<{ name: string; args: unknown[] }> = [];
+    const r = createChatStreamReducer({
+      transport: 'nats',
+      onEffect: e => effects.push(e),
+    });
+    r.apply({ type: 'turn-start', seq: 1 });
+    r.apply({ type: 'guide-delta', text: 'in-stream ', seq: 2 });
+    r.apply({ type: 'turn-end', seq: 3 });
+    r.apply({ type: 'guide-delta', text: 'post-end', seq: 4 });
+
+    const appendEmits = effects.filter(
+      e => e.name === 'onSegmentsUpdate' && (e.args[1] as { append?: boolean } | undefined)?.append === true,
+    );
+    expect(appendEmits).toHaveLength(1);
+    expect(appendEmits[0].args[0]).toEqual([{ type: 'guide', text: 'post-end' }]);
+    // …and the bubble carries ONE coalesced guide segment, not two.
+    const last = r.state.messages[r.state.messages.length - 1];
+    expect(last.segments).toEqual([{ type: 'guide', text: 'in-stream post-end' }]);
+  });
+});
+
+/**
+ * `setMessages` is a RAW setter and must not be used to hydrate history.
+ *
+ * It assigns the thread and nothing else — in particular it does not mark the
+ * reducer resumed, which is what makes a later chunk with no preceding
+ * `turn-start` take the APPEND branch. Hydrating with it leaves the reducer
+ * looking cold, so the first such chunk goes down the cumulative path and
+ * REPLACES the restored bubble's segments. When that bubble holds a pending
+ * approval card, the control the agent is blocked on disappears with it and
+ * there is no way back.
+ *
+ * `initializeWithState` derives `resumed` from the restored thread, which is
+ * why every hydration path must go through it (the SSE adapter always did; the
+ * NATS adapter used `setMessages` and hit exactly this).
+ */
 describe('createChatStreamReducer — history hydration must declare resumed', () => {
   const hydrated = () => [
     {

package/src/components/chat/stream/chat-dialog-store.ts

@@ -207,7 +207,7 @@ const EMPTY_STATE: ChatReducerState = Object.freeze({
   dialogTokenUsage: null,
   liveModel: null,
   approvalStatuses: Object.freeze({}) as ChatReducerState['approvalStatuses'],
-});
+}) as ChatReducerState;
 
 /** Shared frozen empty list for a key with no send in flight. */
 const EMPTY_PENDING_ECHOES: readonly PendingEcho[] = Object.freeze([]);

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

@@ -51,7 +51,7 @@
  */
 
 import { escapeThinkingTags } from '../../../chat-protocol/decode';
-import { errorDetailsMessage } from '../../../chat-protocol/events';
+import { errorDetailsMessage, isGuideOrigin } from '../../../chat-protocol/events';
 import {
   CHAT_OWNER_ADMIN,
   type ChatStreamEvent,
@@ -77,7 +77,7 @@ import type {
   UnifiedChatMessage,
   UnifiedUsageBreakdown,
 } from '../types/unified-chat-state.types';
-import { approvalDisplaysInline } from '../utils/approval-display';
+import { approvalDisplaysInline, guideApprovalOrigin } from '../utils/approval-display';
 import {
   type MessageSegmentAccumulator,
   createMessageSegmentAccumulator,
@@ -161,6 +161,15 @@ export interface ChatReducerState {
     contextWindowMaxTokens: number | null;
   } | null;
   approvalStatuses: Record<string, ChatApprovalStatus>;
+  /**
+   * Hub conversation id for the Product Guide half of this dialog, learned from
+   * a guide metadata frame. The hub mints it and requires it back on every
+   * confirm-tool call, so a host resolving a guide approval card reads it from
+   * here. Null until a guide turn has streamed — an approval that arrives from
+   * history (after a reload) has no live frame to learn it from, which is why
+   * the agent should also expose it per dialog.
+   */
+  guideConversationId: string | null;
 }
 
 /** Escalated-approval bookkeeping entry (mirrors the legacy processor). */
@@ -530,6 +539,7 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
   let streamingPhase: StreamingPhase = 'idle';
   let dialogTokenUsage: DialogTokenUsage | null = null;
   let liveModel: ChatReducerState['liveModel'] = null;
+  let guideConversationId: string | null = null;
   let approvalStatuses: Record<string, ChatApprovalStatus> = {
     ...(options.approvalStatuses ?? {}),
   };
@@ -691,6 +701,7 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
         dialogTokenUsage,
         liveModel,
         approvalStatuses,
+        guideConversationId,
       };
     }
     return stateCache;
@@ -985,6 +996,17 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
       }
 
       case 'metadata': {
+        // A guide metadata event carries ONLY the hub's conversation id (the
+        // decoder strips the rest): record it and stop. Falling through would
+        // rebuild `liveModel` from an event with no model in it and blank the
+        // dialog's model badge mid-answer.
+        if (isGuideOrigin(event)) {
+          if (typeof event.conversationId === 'string' && event.conversationId) {
+            guideConversationId = event.conversationId;
+            invalidate();
+          }
+          break;
+        }
         // Legacy `parseChunkToAction` action shape, reconstructed for the
         // callback contract.
         emit('onMetadata', {
@@ -1003,13 +1025,21 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
         break;
       }
 
-      // Both APPEND-ONLY body streams share one shape: accumulate the verbatim
-      // slice into the trailing segment of the matching kind (the accumulator
-      // coalesces), then emit.
+      // The three APPEND-ONLY body streams share one shape: accumulate the
+      // verbatim slice into the trailing segment of the matching kind (the
+      // accumulator coalesces), then emit. `guide-delta` is NATS-only today
+      // but rides the identical path so a guide body streams, coalesces and
+      // continues post-MESSAGE_END exactly like answer text.
       case 'text-delta':
-      case 'thinking-delta': {
-        const kind = event.type === 'text-delta' ? 'text' : 'thinking';
-        const segments = kind === 'text' ? accumulator.appendText(event.text) : accumulator.appendThinking(event.text);
+      case 'thinking-delta':
+      case 'guide-delta': {
+        const kind = event.type === 'text-delta' ? 'text' : event.type === 'thinking-delta' ? 'thinking' : 'guide';
+        const segments =
+          kind === 'text'
+            ? accumulator.appendText(event.text)
+            : kind === 'thinking'
+              ? accumulator.appendThinking(event.text)
+              : accumulator.appendGuide(event.text);
         // Append-mode only for *true* post-stream continuation (after a
         // MESSAGE_END we actually saw). Cold-start chunks (no prior
         // MESSAGE_START) emit cumulative segments so the consumer can spawn
@@ -1085,8 +1115,10 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
         const approvalType = event.approvalType ?? 'USER';
         const toolCalls = event.toolCalls;
         // Where this card renders is ONE rule, shared with the SSE kernel and
-        // the history replay (`approval-display`).
-        const displayInline = (type: string) => approvalDisplaysInline(type, displayApprovalTypes);
+        // the history replay (`approval-display`) — a Product Guide proposal
+        // that renders inline live must not move on the next page load.
+        const guideOrigin = guideApprovalOrigin(event);
+        const displayInline = (type: string) => approvalDisplaysInline(event, type, displayApprovalTypes);
 
         if (toolCalls && toolCalls.length > 0) {
           // ── Batch form ──
@@ -1118,6 +1150,7 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
               status,
               undefined,
               undefined,
+              guideOrigin,
             );
             applyAccumulated(before, segments);
             break;
@@ -1137,6 +1170,7 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
               approvalType,
               status,
               undefined,
+              guideOrigin,
             );
           }
           applyAccumulated(before, segments);
@@ -1155,8 +1189,10 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
             explanation,
             approvalType,
             status,
-            // SSE-shaped cards carry their body as structured rows rather than prose.
+            // SSE-shaped cards (a re-streamed Product Guide proposal) carry
+            // their body as structured rows rather than prose.
             event.fields,
+            guideOrigin,
           );
           applyAccumulated(before, segments);
         } else {
@@ -1668,6 +1704,7 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
     streamingPhase = 'idle';
     dialogTokenUsage = null;
     liveModel = null;
+    guideConversationId = null;
     approvalStatuses = {};
     accumulator.reset();
     pendingEscalated.clear();
@@ -1715,6 +1752,7 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
     streamingPhase = 'idle';
     dialogTokenUsage = null;
     liveModel = null;
+    guideConversationId = null;
     accumulator.reset();
     pendingEscalated.clear();
     isInStream = false;

package/src/components/chat/stream/delta-batcher.ts

@@ -1,6 +1,6 @@
 /**
  * createDeltaBatcher — framework-free, append-only batching of the
- * `text-delta` / `thinking-delta` events.
+ * `text-delta` / `thinking-delta` / `guide-delta` events.
  *
  * WHY THIS IS SHARED (and not a hook-private detail): every host that drives a
  * `ChatStreamReducer` from a raw transport needs the SAME batching, and a
@@ -23,14 +23,19 @@
  *     deltas never land on the wrong dialog/side.
  */
 
-import type { ChatStreamEvent, TextDeltaEvent, ThinkingDeltaEvent } from '../../../chat-protocol/events';
+import type {
+  ChatStreamEvent,
+  GuideDeltaEvent,
+  TextDeltaEvent,
+  ThinkingDeltaEvent,
+} from '../../../chat-protocol/events';
 
 export const DELTA_FLUSH_FALLBACK_MS = 50;
 
-export type DeltaEvent = TextDeltaEvent | ThinkingDeltaEvent;
+export type DeltaEvent = TextDeltaEvent | ThinkingDeltaEvent | GuideDeltaEvent;
 
 export function isDeltaEvent(event: ChatStreamEvent): event is DeltaEvent {
-  return event.type === 'text-delta' || event.type === 'thinking-delta';
+  return event.type === 'text-delta' || event.type === 'thinking-delta' || event.type === 'guide-delta';
 }
 
 export interface CreateDeltaBatcherOptions<K> {

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

@@ -126,6 +126,8 @@ export function appendToTrailingAssistant(
       merged[merged.length - 1] = { type: 'text', text: tail.text + seg.text };
     } else if (seg.type === 'thinking' && tail?.type === 'thinking') {
       merged[merged.length - 1] = { type: 'thinking', text: tail.text + seg.text };
+    } else if (seg.type === 'guide' && tail?.type === 'guide') {
+      merged[merged.length - 1] = { type: 'guide', text: tail.text + seg.text };
     } else if (key) {
       // Block deltas must be IDEMPOTENT: an emit can be seen twice (live plus
       // the JetStream catch-up replay over hydrated history), so upsert on the

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

@@ -578,6 +578,15 @@ export interface ThinkingDisplayProps extends HTMLAttributes<HTMLDivElement> {
   isStreaming?: boolean;
 }
 
+// ========== Guide Display Props ==========
+
+export interface GuideDisplayProps extends HTMLAttributes<HTMLDivElement> {
+  /** Rendered guide body. `ChatMessageEnhanced` passes the SAME markdown
+   *  output a text segment gets, so `[card://]` cards and mention chips
+   *  behave identically inside a guide. */
+  children?: ReactNode;
+}
+
 // ========== Ask Display Props ==========
 
 export interface AskDisplayProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {

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

@@ -10,6 +10,7 @@ import type { AssistantType, AuthorType, ChatApprovalStatus, MessageOwner } from
 export const MESSAGE_TYPE = {
   TEXT: 'TEXT',
   THINKING: 'THINKING',
+  GUIDE: 'GUIDE',
   ASK: 'ASK',
   EXECUTING_TOOL: 'EXECUTING_TOOL',
   EXECUTED_TOOL: 'EXECUTED_TOOL',
@@ -113,6 +114,12 @@ export interface ApprovalRequestData {
   requestId?: string;
   approvalRequestId?: string;
   approvalType?: string;
+  /** `'guide'` when the card came from a Product Guide frame (see `GuideOrigin`
+   *  in `chat-protocol/events`). Carried onto the segment because hosts route
+   *  and filter approvals by where they came from: mingo lifts its OWN pending
+   *  cards into a sticky footer, and a guide card must stay inline in the turn
+   *  the way it does in the hub's chat. */
+  origin?: 'guide';
 }
 
 export interface ApprovalResultData {
@@ -220,6 +227,11 @@ export interface ApprovalBatchData {
    * batch itself is approved.
    */
   executions?: Record<string, ApprovalBatchExecutionState>;
+  /** `'guide'` when the batch came from a Product Guide `approval_batch` frame.
+   *  Same contract and the same reasons as `ApprovalRequestData.origin` — the
+   *  hub groups multiple proposals into one card, and that card resolves
+   *  through the hub exactly like a single one. */
+  origin?: 'guide';
 }
 
 /** Approve/reject handler stamped onto approval segments. MAY resolve a
@@ -242,6 +254,15 @@ export type ThinkingSegment = {
   text: string;
 };
 
+/** Guide answer body — the assistant's how-to/documentation reply, rendered as
+ *  a titled "OpenFrame Guide" card instead of a bare paragraph. `text` is
+ *  markdown, streamed in fragments like a `text` segment and coalesced by the
+ *  accumulator. */
+export type GuideSegment = {
+  type: 'guide';
+  text: string;
+};
+
 /** One reading the assistant offers in an `ask` card. `label` is BOTH the row's
  *  headline and the exact text sent back when the row is picked — the backend's
  *  guide classifier resolves the user's next message against the labels it
@@ -359,6 +380,7 @@ export type ContextCompactionSegment = {
 export type MessageSegment =
   | TextSegment
   | ThinkingSegment
+  | GuideSegment
   | AskSegment
   | ToolExecutionSegment
   | ApprovalRequestSegment
@@ -391,6 +413,15 @@ export interface ThinkingMessageData extends MessageDataBase {
   text?: string;
 }
 
+export interface GuideMessageData extends MessageDataBase {
+  type: 'GUIDE';
+  text?: string;
+  /** Persisted Product Guide frame (GraphQL `GuideData.payload`, a JSON scalar)
+   *  for rows that carry a card instead of answer text — replayed through the
+   *  live path's `guideFrameEvent`. */
+  payload?: Record<string, unknown>;
+}
+
 /** Persisted `ASK` row (GraphQL `AskData`). `text` is the intro sentence, which
  *  history replays as a text segment ahead of the card — same split the live
  *  `ASK` chunk carries. */
@@ -532,6 +563,7 @@ export interface ContextCompactionEndMessageData extends MessageDataBase {
 export type MessageData =
   | TextMessageData
   | ThinkingMessageData
+  | GuideMessageData
   | AskMessageData
   | ExecutingToolMessageData
   | ExecutedToolMessageData

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

@@ -63,7 +63,9 @@ export interface ChunkData {
   /** Batch-approval rows. Coerced by `normalizeToolCalls` in the NATS decoder
    *  — the wire shape is per-backend, so entries stay opaque here. */
   toolCalls?: unknown[];
-  /** Opaque per-chunk payload some backends attach beside `text`. */
+  /** On GUIDE chunks: a Product Guide frame the agent re-streamed verbatim from
+   *  the hub, instead of the answer text `text` carries. Decoded by
+   *  `decodeNatsChunk` through the shared leading-frame table. */
   payload?: Record<string, unknown>;
   modelName?: string;
   providerName?: string;

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

@@ -18,9 +18,12 @@ export interface PendingApproval {
   command: string;
   explanation?: string;
   approvalType: string;
-  /** Structured label/value rows — a card can be almost entirely
+  /** Structured label/value rows — a Product Guide card is almost entirely
    *  these, so a path that forgets them renders a bare title. */
   fields?: ApprovalRequestField[];
+  /** Where the card came from; `'guide'` keeps it inline and routes its
+   *  buttons to the hub (see `ApprovalRequestData.origin`). */
+  origin?: 'guide';
 }
 
 export interface AccumulatorState {

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

@@ -9,6 +9,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { decodeNatsChunk } from '../../../../chat-protocol/nats-decoder';
 import { createChatStreamReducer } from '../../stream/chat-stream-reducer';
 import type { HistoricalMessage, MessageSegment } from '../../types';
 import { processHistoricalMessagesWithErrors } from '../process-historical-messages';
@@ -150,3 +151,95 @@ 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' }],
+        },
+      },
+    ],
+  });
+
+  // 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' });
+    const guideChunk = 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' }],
+      },
+    });
+    // A decoder that declines this frame is the failure the test exists to
+    // catch — say so rather than applying `undefined` to the reducer.
+    if (!guideChunk) throw new Error('decodeNatsChunk did not decode the GUIDE approval_request frame');
+    live.apply(guideChunk);
+    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/__tests__/process-historical-messages-golden.test.ts

@@ -318,9 +318,86 @@ describe('extractErrorMessages / processHistoricalMessagesWithErrors — golden'
   });
 });
 
+// ─── 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' }],
+      },
+    ];
+    expect(processHistoricalMessages(empty).messages).toEqual([]);
+  });
+});
+
 // ─── ASK rows ──────────────────────────────────────────────────────────────
 //
-// History must replay a persisted `ASK` row into
+// Same contract as GUIDE above: history must replay a persisted `ASK` row into
 // the SAME shape the live `ASK` chunk produces — the intro sentence as answer
 // text, then the card — or a reloaded dialog loses the clarification the user
 // was about to answer.