@flamingo-stack/openframe-frontend-core 0.0.518 → 0.0.519

package/src/components/chat/embeddable-chat.tsx

@@ -1584,6 +1584,24 @@ function EmbeddableChatInner({
     [sendMessage, readyAttachments, viewUrlPrefix, clearAttachments, contextItems],
   )
 
+  /**
+   * Picking an option on a clarification card — deliberately NOT `handleSend`.
+   *
+   * `handleSend` belongs to the composer: it appends the staged attachments'
+   * markdown to the text, ships the staged context items, and then clears both.
+   * Routing an ask click through it would (a) send `label + attachment markdown`
+   * where the backend's classifier expects the label VERBATIM to resolve which
+   * reading was picked, and (b) consume a draft's attachments/context into a
+   * one-word answer the user never attached them to. So the label goes out on
+   * its own and whatever is staged in the composer stays staged.
+   */
+  const handleAskSelect = useCallback(
+    (label: string) => {
+      sendMessage(label)
+    },
+    [sendMessage],
+  )
+
   // Admin "try-asking chips" → GUIDE-mode quick-action chips only (Mingo mode
   // deliberately doesn't surface them). Clicking one SENDS the query immediately
   // via the GuideWelcome `onQuickAction` → `handleSend` at the render site (no
@@ -2351,6 +2369,10 @@ function EmbeddableChatInner({
                       resolveContextIcon={resolveContextIcon}
                       renderContextItem={renderContextItem}
                       renderMention={renderMention}
+                      // Gated on `chatLoading` for the same reason the composer
+                      // is: no second send while a turn is in flight. Passive
+                      // demo hosts (previewMode) stay read-only.
+                      onAskSelect={chatLoading || previewMode ? undefined : handleAskSelect}
                       NavLinkAnchor={NavLinkAnchorViaRuntime}
                       // Real Mingo drawer: hide the message-list scrollbar
                       // (scroll stays functional). Scoped here via `className`

package/src/components/chat/index.ts

@@ -7,6 +7,7 @@ export * from './context-compaction-display'
 export * from './expand-chevron'
 export * from './thinking-display'
 export * from './guide-display'
+export * from './ask-display'
 export * from './error-message-display'
 export * from './chat-container'
 export * from './chat-input'

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

@@ -1328,3 +1328,75 @@ describe('agentBusy on initializeWithState', () => {
     expect(r.state.streamingPhase).toBe('idle')
   })
 })
+
+/**
+ * `ask` — the guide-routing clarification card. Not a delta: one chunk carries
+ * the whole card, plus the intro sentence that must render as ordinary answer
+ * text IN FRONT of it. The post-MESSAGE_END path is the interesting one — the
+ * card routinely lands in a continuation, where the delta is appended to the
+ * finished bubble rather than replacing it.
+ */
+describe('createChatStreamReducer — ask cards', () => {
+  const ask = (question: string, seq?: number, text?: string): ChatStreamEvent => ({
+    type: 'ask',
+    ...(text ? { text } : {}),
+    question,
+    options: [
+      { label: 'Find documentation', description: 'How the feature works' },
+      { label: 'Work with workspace data' },
+    ],
+    ...(seq != null ? { seq } : {}),
+  })
+
+  it('renders the intro as text ahead of the card, in one bubble', () => {
+    const r = createChatStreamReducer({ transport: 'nats' })
+    r.apply({ type: 'turn-start', seq: 1 })
+    r.apply(ask('What do you want to work on?', 2, 'Docs, or your own workspace?'))
+
+    const last = r.state.messages[r.state.messages.length - 1]
+    expect(last.segments).toEqual([
+      { type: 'text', text: 'Docs, or your own workspace?' },
+      {
+        type: 'ask',
+        question: 'What do you want to work on?',
+        options: [
+          { label: 'Find documentation', description: 'How the feature works' },
+          { label: 'Work with workspace data' },
+        ],
+      },
+    ])
+  })
+
+  it('appends into the finished bubble after MESSAGE_END, keeping the reply', () => {
+    const r = createChatStreamReducer({ transport: 'nats' })
+    r.apply({ type: 'turn-start', seq: 1 })
+    r.apply({ type: 'text-delta', text: 'Working on it. ', seq: 2 })
+    r.apply({ type: 'turn-end', seq: 3 })
+    r.apply(ask('Which one?', 4, 'One thing first: '))
+
+    const last = r.state.messages[r.state.messages.length - 1]
+    // The intro COALESCES onto the completed reply (same rule as a post-END
+    // `text-delta`) — a slice off the accumulator used to drop it here.
+    expect(last.segments).toEqual([
+      { type: 'text', text: 'Working on it. One thing first: ' },
+      {
+        type: 'ask',
+        question: 'Which one?',
+        options: [
+          { label: 'Find documentation', description: 'How the feature works' },
+          { label: 'Work with workspace data' },
+        ],
+      },
+    ])
+  })
+
+  it('keeps two cards in one turn as separate segments (the card pages them)', () => {
+    const r = createChatStreamReducer({ transport: 'nats' })
+    r.apply({ type: 'turn-start', seq: 1 })
+    r.apply(ask('First?', 2))
+    r.apply(ask('Second?', 3))
+
+    const last = r.state.messages[r.state.messages.length - 1]
+    expect(last.segments?.map((s) => s.type)).toEqual(['ask', 'ask'])
+  })
+})

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

@@ -1041,6 +1041,33 @@ export function createChatStreamReducer(
         break
       }
 
+      // A clarification card arrives whole, not as deltas. The intro sentence
+      // riding the same chunk goes in FIRST as ordinary answer text so it runs
+      // through the markdown body pipeline (and coalesces with any preamble the
+      // turn already streamed); the card follows as its own segment. Both land
+      // in one emit, so the bubble never shows the card ahead of its lead-in.
+      case 'ask': {
+        if (event.text) accumulator.appendText(event.text)
+        const segments = accumulator.addAsk(event.question, event.options)
+        if (isInStream || !hasEverStreamed) {
+          emitSegments(segments)
+          applySegmentsToState(segments, withSeqMeta(undefined))
+          break
+        }
+        // Post-MESSAGE_END: the delta is spelled out rather than sliced off the
+        // accumulator. `appendText` COALESCES into a trailing text segment, so a
+        // slice would silently drop the intro whenever the continuation already
+        // had text in flight; `appendToTrailingAssistant` re-coalesces it here
+        // instead, exactly like a `text-delta`.
+        const delta: MessageSegment[] = [
+          ...(event.text ? [{ type: 'text' as const, text: event.text }] : []),
+          { type: 'ask' as const, question: event.question, options: event.options },
+        ]
+        emitSegments(delta, { append: true })
+        applySegmentsToState(delta, withSeqMeta({ append: true }))
+        break
+      }
+
       case 'tool-execution': {
         const segment: ToolExecutionSegment = { type: 'tool_execution', data: event.data }
         // A starting tool run means the agent's turn is in progress even

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

@@ -4,7 +4,7 @@
 
 import type { ComponentType, HTMLAttributes, ReactNode, TextareaHTMLAttributes } from 'react'
 import type { ApprovalBlockVariant, AssistantType, AuthorType, ChatApprovalStatus, ConnectionStatus } from './chat.types'
-import type { ApprovalRequestData, Message, MessageSegment, ToolExecutionData,
+import type { ApprovalRequestData, AskSegment, Message, MessageSegment, ToolExecutionData,
   ApprovalResolutionHandler,
 } from './message.types'
 import type { ChatRef } from '../chat-ref.types'
@@ -212,6 +212,15 @@ export interface ChatMessageEnhancedProps extends Omit<HTMLAttributes<HTMLDivEle
    * simply default to undefined on the receiver.
    */
   NavLinkAnchor?: NavLinkAnchorComponent
+  /**
+   * Picks an option on an `ask` (clarification) card in this message. Receives
+   * the option's label VERBATIM — the host sends it as the user's next message
+   * and the backend resolves the reply against the labels it offered.
+   *
+   * Omit to render ask cards read-only. Keep the identity stable
+   * (`useCallback` / module const): the message memo compares it by reference.
+   */
+  onAskSelect?: (label: string) => void
 }
 
 // ========== Chat Message List Props ==========
@@ -285,6 +294,10 @@ export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
    *  message's ChatMessageEnhanced. Owns the unified click rule
    *  (same-origin soft nav, cross-origin new tab). */
   NavLinkAnchor?: NavLinkAnchorComponent
+  /** Ask-card option pick. Forwarded verbatim to every message's
+   *  ChatMessageEnhanced; the host sends the received label as the user's next
+   *  message. Omit to render ask cards read-only. */
+  onAskSelect?: (label: string) => void
 }
 
 export interface ChatMessageListRef {
@@ -567,6 +580,20 @@ export interface GuideDisplayProps extends HTMLAttributes<HTMLDivElement> {
   children?: ReactNode
 }
 
+// ========== Ask Display Props ==========
+
+export interface AskDisplayProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /** The clarification cards to show. One entry per `ask` segment; a run of
+   *  consecutive segments is passed as ONE card with a pager, so a multi-question
+   *  turn reads as a single block instead of a stack of near-identical cards. */
+  cards: AskSegment[]
+  /** Picks an option. Receives the option's `label` VERBATIM — that string is
+   *  sent as the user's next message and the backend's classifier resolves it
+   *  against the labels it offered, so it must not be reworded. Omit to render
+   *  the card read-only (replayed history, observer surfaces). */
+  onSelect?: (label: string) => void
+}
+
 // ========== Model Display Props ==========
 
 export interface ModelDisplayProps extends HTMLAttributes<HTMLDivElement> {

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

@@ -11,6 +11,7 @@ export const MESSAGE_TYPE = {
   TEXT: 'TEXT',
   THINKING: 'THINKING',
   GUIDE: 'GUIDE',
+  ASK: 'ASK',
   EXECUTING_TOOL: 'EXECUTING_TOOL',
   EXECUTED_TOOL: 'EXECUTED_TOOL',
   APPROVAL_REQUEST: 'APPROVAL_REQUEST',
@@ -190,6 +191,28 @@ export type GuideSegment = {
   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
+ *  offered, so the reply must be the label verbatim. `description` is a short
+ *  clarifying line rendered under it. */
+export type AskOptionData = {
+  label: string
+  description?: string
+}
+
+/** Clarification card — the assistant asking WHICH reading of an ambiguous
+ *  question it should answer, rendered as a heading plus a list of clickable
+ *  options instead of prose bullets. NATS-only (the `ASK` chunk); the intro
+ *  sentence riding the same chunk becomes an ordinary `text` segment in front
+ *  of the card, so it goes through the normal markdown body pipeline. Unlike
+ *  the three delta streams an ask arrives whole — it is never coalesced. */
+export type AskSegment = {
+  type: 'ask'
+  question: string
+  options: AskOptionData[]
+}
+
 export type ToolExecutionSegment = {
   type: 'tool_execution'
   data: ToolExecutionData
@@ -228,7 +251,7 @@ export type ContextCompactionSegment = {
   summary?: string
 }
 
-export type MessageSegment = TextSegment | ThinkingSegment | GuideSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
+export type MessageSegment = TextSegment | ThinkingSegment | GuideSegment | AskSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
 
 export type MessageContent = string | MessageSegment[]
 
@@ -253,6 +276,16 @@ export interface GuideMessageData extends MessageDataBase {
   text?: string
 }
 
+/** 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. */
+export interface AskMessageData extends MessageDataBase {
+  type: 'ASK'
+  text?: string
+  question?: string
+  options?: AskOptionData[]
+}
+
 export interface ExecutingToolMessageData extends MessageDataBase {
   type: 'EXECUTING_TOOL'
   integratedToolType?: string
@@ -335,6 +368,7 @@ export type MessageData =
   | TextMessageData
   | ThinkingMessageData
   | GuideMessageData
+  | AskMessageData
   | ExecutingToolMessageData
   | ExecutedToolMessageData
   | ApprovalRequestMessageData

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

@@ -392,3 +392,77 @@ describe('processHistoricalMessages — GUIDE rows', () => {
     expect(processHistoricalMessages(empty).messages).toEqual([])
   })
 })
+
+// ─── ASK rows ──────────────────────────────────────────────────────────────
+//
+// 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.
+
+describe('processHistoricalMessages — ASK rows', () => {
+  const askRow = {
+    type: 'ASK',
+    text: 'Do you want the docs, or your own workspace?',
+    question: 'What do you want to work on?',
+    options: [
+      { label: 'Find documentation', description: 'How scripting works and how to set it up' },
+      { label: 'Your scripts', description: 'List, edit or run the scripts in your workspace' },
+    ],
+  }
+
+  it('replays an ASK row as intro text followed by the card', () => {
+    const dialog: HistoricalMessage[] = [
+      {
+        id: 'a1',
+        chatType: 'CLIENT_CHAT',
+        createdAt: '2026-07-19T09:00:05Z',
+        owner: { type: 'ASSISTANT' },
+        messageData: [askRow as any],
+      },
+    ]
+    expect(processHistoricalMessages(dialog).messages[0].content).toEqual([
+      { type: 'text', text: 'Do you want the docs, or your own workspace?' },
+      {
+        type: 'ask',
+        question: 'What do you want to work on?',
+        options: [
+          { label: 'Find documentation', description: 'How scripting works and how to set it up' },
+          { label: 'Your scripts', description: 'List, edit or run the scripts in your workspace' },
+        ],
+      },
+    ])
+  })
+
+  it('keeps consecutive ASK rows as SEPARATE segments (the card pages them)', () => {
+    const dialog: HistoricalMessage[] = [
+      {
+        id: 'a1',
+        chatType: 'CLIENT_CHAT',
+        createdAt: '2026-07-19T09:00:05Z',
+        owner: { type: 'ASSISTANT' },
+        messageData: [
+          { type: 'ASK', question: 'First?', options: [{ label: 'A' }] } as any,
+          { type: 'ASK', question: 'Second?', options: [{ label: 'B' }] } as any,
+        ],
+      },
+    ]
+    expect(processHistoricalMessages(dialog).messages[0].content).toEqual([
+      { type: 'ask', question: 'First?', options: [{ label: 'A', description: undefined }] },
+      { type: 'ask', question: 'Second?', options: [{ label: 'B', description: undefined }] },
+    ])
+  })
+
+  it('an ASK row with no answerable options decodes to nothing', () => {
+    const dialog: HistoricalMessage[] = [
+      {
+        id: 'a1',
+        chatType: 'CLIENT_CHAT',
+        createdAt: '2026-07-19T09:00:05Z',
+        owner: { type: 'ASSISTANT' },
+        messageData: [{ type: 'ASK', question: 'Which one?', options: [{ description: 'no label' }] } as any],
+      },
+    ]
+    expect(processHistoricalMessages(dialog).messages).toEqual([])
+  })
+})

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

@@ -9,6 +9,7 @@
  */
 
 import type {
+  AskOptionData,
   MessageSegment,
   ToolExecutionSegment,
   ApprovalRequestSegment,
@@ -163,6 +164,17 @@ export class MessageSegmentAccumulator {
     return this.getSegments()
   }
 
+  /**
+   * Add a clarification (ask) card. Unlike the three delta streams an ask
+   * arrives whole in one chunk, so it is always a NEW segment — never merged
+   * into a trailing one. Consecutive cards stay separate segments; the renderer
+   * is what pages through a run of them.
+   */
+  addAsk(question: string, options: AskOptionData[]): MessageSegment[] {
+    this.segments.push({ type: 'ask', question, options })
+    return this.getSegments()
+  }
+
   /**
    * Add a tool execution segment.
    *
@@ -530,6 +542,9 @@ export class MessageSegmentAccumulator {
         case 'guide':
           if (segment.text) this.appendGuide(segment.text)
           break
+        case 'ask':
+          this.addAsk(segment.question, segment.options)
+          break
         case 'tool_execution':
           this.addToolExecution(segment)
           break

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

@@ -38,6 +38,9 @@ import {
   type MessageOwner,
 } from '../types'
 import 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 { getCommandText } from './tool-call-helpers'
 
@@ -117,6 +120,22 @@ export function decodeHistoricalMessageData(data: MessageData): ChatStreamEvent
       }
       return null
 
+    // Same completeness gate as the live decoder (`decodeNatsChunk`): a
+    // persisted row without a question or without options is not a card the
+    // user can answer, so it replays as nothing rather than as empty chrome.
+    case MESSAGE_TYPE.ASK: {
+      if (!('question' in data)) return null
+      const question = typeof data.question === 'string' ? data.question.trim() : ''
+      const options = normalizeAskOptions(data.options)
+      if (!question || options.length === 0) return null
+      return {
+        type: 'ask',
+        ...(data.text ? { text: data.text } : {}),
+        question,
+        options,
+      }
+    }
+
     case MESSAGE_TYPE.EXECUTING_TOOL:
       if ('integratedToolType' in data) {
         return {
@@ -252,6 +271,13 @@ function applyHistoryEvent(
       accumulator.appendGuide(event.text)
       break
 
+    // Mirror of the live path: the intro sentence replays as answer text in
+    // front of the card, so a reloaded thread reads exactly like the stream did.
+    case 'ask':
+      if (event.text) accumulator.appendText(event.text)
+      accumulator.addAsk(event.question, event.options)
+      break
+
     case 'tool-execution':
       accumulator.addToolExecution({ type: 'tool_execution', data: event.data })
       break