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

package/src/chat-protocol/leading-frames.ts

@@ -0,0 +1,175 @@
+/**
+ * Leading-frame → `ChatStreamEvent` table — the ONE mapping both transports read.
+ *
+ * The SSE decoder (`./decode.ts`) reaches it while walking the hub's byte
+ * framing. The NATS decoder (`./nats-decoder.ts`) reaches it for `GUIDE` chunks
+ * carrying a `payload`: the saas-ai-agent re-streams the Product Guide's hub
+ * frames VERBATIM into the Mingo chunk stream (`GuideStreamingService`), so the
+ * bytes a guide answer is made of are the same frames on both transports — only
+ * the envelope differs. Decoding them twice would drift the moment the hub adds
+ * a frame kind, which is why this table lives outside either decoder.
+ *
+ * The NATS side does NOT take every event this table can produce; see
+ * `guideFrameEvent` in `./nats-decoder.ts` for which ones cross over and why.
+ *
+ * Server-safe: no React, no browser APIs.
+ */
+
+import type { ChatStreamEvent } from './events'
+
+/**
+ * Escape `<` so markdown renderers that pass HTML through (rehypeRaw)
+ * don't treat XML-like tokens in Claude's thinking output as elements.
+ * `<` → `&lt;` preserves the visible character without breaking
+ * blockquote `>` markers. Per-character, so it distributes over
+ * concatenation: escape(a + b) === escape(a) + escape(b) — callers may
+ * apply it per-delta or on the accumulated string interchangeably.
+ */
+export function escapeThinkingTags(text: string): string {
+  return text.replace(/</g, '&lt;')
+}
+
+/**
+ * Map one parsed leading frame to normalized events, replicating the
+ * legacy parser's else-if chain ORDER and its exact truthiness/typeof
+ * gates. Frames that matched a branch but failed its inner validation
+ * (e.g. `routing` without a string `routedComplexity`) produce NO event,
+ * exactly like the legacy no-op.
+ *
+ * Every branch pushes AT MOST ONE event — `guideFrameEvent` relies on that
+ * to hand a single event back to `decodeNatsChunk`'s per-chunk contract.
+ */
+export function mapLeadingFrame(meta: any, out: ChatStreamEvent[]): void {
+  if (meta.status === 'thinking') {
+    out.push({ type: 'status', phase: 'thinking' })
+  } else if (meta.kind === 'thinking-delta' && typeof meta.text === 'string') {
+    // Wire is ALREADY delta — emit verbatim, append-only contract.
+    out.push({ type: 'thinking-delta', text: meta.text })
+  } else if (meta.kind === 'usage' && meta.stage === 'start') {
+    out.push({
+      type: 'usage',
+      stage: 'start',
+      input_tokens: meta.input_tokens,
+      cache_read_input_tokens: meta.cache_read_input_tokens,
+      cache_creation_input_tokens: meta.cache_creation_input_tokens,
+    })
+  } else if (meta.kind === 'decision_resolved' && typeof meta.action === 'string') {
+    const status = meta.action === 'rejected' ? 'rejected' : 'approved'
+    const toolName = typeof meta.tool_name === 'string' ? meta.tool_name : undefined
+    const result = meta.result ?? null
+    const card = meta.card ?? null
+    out.push({
+      type: 'approval-resolved',
+      status,
+      ok: meta.ok === true,
+      willAutoContinue: meta.willAutoContinue === true,
+      ...(toolName ? { toolName } : {}),
+      ...(result ? { result } : {}),
+      ...(card?.marker ? { marker: card.marker } : {}),
+      ...(card?.ref ? { cardRef: card.ref } : {}),
+      ...(card?.type ? { cardType: card.type } : {}),
+      ...(typeof meta.receiptText === 'string' ? { receiptText: meta.receiptText } : {}),
+      requestId: typeof meta.proposalId === 'string' ? meta.proposalId : undefined,
+    })
+  } else if (meta.kind === 'approval_batch' && meta.batchId && Array.isArray(meta.proposals)) {
+    // Server-grouped multi-proposal turn → ONE batch event carrying a
+    // tool-call row per proposal. `toolExecutionRequestId` is the row's
+    // PROPOSAL id (each row resolves through its own per-proposal
+    // confirm); the batch's `requestId` is the stable anchor the shell
+    // uses for status flips. Field rows ride as the row's expandable
+    // args so per-proposal detail stays reachable inside the batch.
+    const toolCalls = (meta.proposals as Array<Record<string, any>>)
+      .filter((p) => p && typeof p.proposalId === 'string')
+      .map((p) => {
+        const rawFields = Array.isArray(p.fields)
+          ? (p.fields as Array<{ label?: string; value?: string }>).filter(
+              (f) => f && f.label && f.value,
+            )
+          : []
+        // Prefer human-readable identity labels for the row's
+        // disambiguator; opaque-id labels ("Task", "Ticket") only as
+        // the last-resort first field.
+        const detail =
+          rawFields.find((f) => /^(title|subject|name)$/i.test(String(f.label))) ??
+          rawFields[0]
+        const base =
+          typeof p.title === 'string' && p.title.length > 0 ? p.title : String(p.toolName ?? 'Tool call')
+        return {
+          toolExecutionRequestId: String(p.proposalId),
+          toolName: String(p.toolName ?? 'tool'),
+          toolTitle: detail ? `${base} — ${detail.value}` : base,
+          requiresApproval: true,
+          toolCallArguments:
+            rawFields.length > 0
+              ? Object.fromEntries(rawFields.map((f) => [String(f.label), String(f.value)]))
+              : null,
+        }
+      })
+    if (toolCalls.length > 0) {
+      out.push({
+        type: 'approval-request',
+        requestId: String(meta.batchId),
+        approvalType: 'chat',
+        toolCalls,
+        status: 'pending',
+      })
+    }
+  } else if (meta.kind === 'approval_request' && meta.proposalId) {
+    const proposalId = String(meta.proposalId)
+    const toolName = String(meta.toolName ?? 'tool')
+    const headline =
+      typeof meta.title === 'string' && meta.title.length > 0 ? meta.title : toolName
+    const rawFields = Array.isArray(meta.fields)
+      ? (meta.fields as Array<{ label?: string; value?: string }>)
+      : []
+    const fields: Array<{ label: string; value: string }> = []
+    for (const f of rawFields) {
+      if (!f || !f.label || !f.value) continue
+      fields.push({ label: f.label, value: f.value })
+    }
+    out.push({
+      type: 'approval-request',
+      requestId: proposalId,
+      approvalType: toolName,
+      command: headline,
+      fields,
+      status: 'pending',
+    })
+  } else if (meta.kind === 'text-leading' && typeof meta.text === 'string') {
+    out.push({ type: 'text-delta', text: meta.text, leading: true })
+  } else if (meta.kind === 'tool_error') {
+    const msg =
+      typeof meta.message === 'string' && meta.message.length > 0
+        ? meta.message
+        : 'Could not complete the requested action right now.'
+    out.push({ type: 'error', title: msg })
+  } else if (meta.kind === 'routing') {
+    if (typeof meta.routedComplexity === 'string') {
+      out.push({
+        type: 'metadata',
+        routing: {
+          routedComplexity: meta.routedComplexity,
+          ...(typeof meta.routedModel === 'string' ? { routedModel: meta.routedModel } : {}),
+          routedThinkingBudget:
+            typeof meta.routedThinkingBudget === 'number' ? meta.routedThinkingBudget : null,
+        },
+      })
+    }
+  } else {
+    // Catch-all metadata-ish frame. Raw values pass through UNVALIDATED
+    // (possibly undefined) so the consumer can replicate the legacy
+    // presence/truthiness gates exactly — including the `model`-presence
+    // trigger whose value is never stored.
+    out.push({
+      type: 'metadata',
+      sources: meta.sources,
+      refs: meta.refs,
+      provider: meta.provider,
+      modelLabel: meta.modelLabel,
+      modelName: meta.model,
+      contextWindowMaxTokens: meta.contextWindowMaxTokens,
+      scrollAnchor: meta.scrollAnchor,
+      conversationId: meta.conversationId,
+    })
+  }
+}

package/src/chat-protocol/nats-decoder.ts

@@ -18,13 +18,19 @@
 
 import { MESSAGE_TYPE } from '../components/chat/types/message.types'
 import type { AskOptionData } from '../components/chat/types/message.types'
-import { ESCALATION_STATE, escalationResolvedStatus } from './events'
+import { ESCALATION_STATE, GUIDE_ORIGIN, escalationResolvedStatus } from './events'
 import type { ApprovalToolCall, ChatStreamEvent } from './events'
+import { escapeThinkingTags, mapLeadingFrame } from './leading-frames'
 
 /** Minimal structural view of a NATS chunk (see `ChunkData` in
  *  `src/components/chat/types/network.types.ts`). */
 type NatsChunk = Record<string, any>
 
+// `GUIDE_ORIGIN` moved to `./events`, beside the `GuideOrigin` type it is the
+// only value of — the SSE half reads it too, so it never belonged to the NATS
+// decoder. Re-exported here because that is the import path consumers know.
+export { GUIDE_ORIGIN } from './events'
+
 /** Coerce the wire's `toolCalls[]` into the batch-approval shape, dropping
  *  non-object entries and defaulting every field. */
 function normalizeToolCalls(raw: unknown): ApprovalToolCall[] {
@@ -61,6 +67,99 @@ export function normalizeAskOptions(raw: unknown): AskOptionData[] {
     .filter((option) => option.label.length > 0)
 }
 
+/**
+ * Events whose meaning belongs to the AGENT's dialog rather than to the guide
+ * turn embedded inside it. The hub emits its own copies of these, and the Mingo
+ * dialog already has authoritative ones: letting the hub's through would
+ * double-count the dialog's tokens or fight the agent's own phase chunks.
+ *
+ * Note this is a DENYLIST, and that is the point. `./leading-frames` is the ONE
+ * place a hub frame kind is taught to the client; whatever it learns to emit —
+ * including kinds that do not exist yet — must reach a Mingo dialog without a
+ * second edit here. An allowlist would silently swallow every card the hub adds
+ * next, and the guide half would quietly lag the guide chat.
+ */
+const AGENT_OWNED_EVENTS: ReadonlySet<ChatStreamEvent['type']> = new Set([
+  'usage',
+  'token-usage',
+  'status',
+  'compaction',
+  'participant',
+  'dialog-closed',
+])
+
+/** Event types that declare `origin` (see `GuideOrigin`). Data rather than a
+ *  branch per type, so a future hub card opts in by adding the field to its
+ *  interface and its name here — the pass-through below needs no edit. */
+const ORIGIN_BEARING_EVENTS: ReadonlySet<ChatStreamEvent['type']> = new Set([
+  'approval-request',
+  'approval-resolved',
+])
+
+/**
+ * Adapt ONE Product Guide event to the NATS kernel.
+ *
+ * The guide half of a Mingo dialog is the hub's own stream, so it is decoded by
+ * the shared table in `./leading-frames` and then passed through here — the ONE
+ * place that reconciles the two kernels. Both entry points use it: frames
+ * re-streamed by the agent inside `GUIDE` chunks, and the SSE response of the
+ * hub's confirm-tool route, which a host replays into the same dialog.
+ *
+ * Pass-through is the DEFAULT; only these rules alter an event, and each exists
+ * because the two kernels genuinely disagree:
+ *
+ *   - `text-delta` becomes `guide-delta`: the body of a guide turn belongs
+ *     inside the "OpenFrame Guide" card, and a `text` segment would strand part
+ *     of the same answer outside it.
+ *   - thinking is escaped HERE. The SSE kernel escapes `<` on the way in, the
+ *     NATS kernel does not, and the guide's thinking is full of XML-ish tokens
+ *     that would otherwise render as markup.
+ *   - `metadata` survives ONLY to carry `conversationId`, which the hub mints
+ *     and every confirm-tool call must quote back. Everything else on that
+ *     frame (the hub's model, routing) is dropped: `applyNats` rebuilds the
+ *     dialog's live model from a metadata event, so letting it through would
+ *     relabel a Mingo turn with the hub's model, and a routing frame — which
+ *     carries no model at all — would blank the badge mid-answer.
+ *   - dialog-level events stop here (`AGENT_OWNED_EVENTS`).
+ *
+ * Everything else crosses over as the hub typed it, gaining only `origin`.
+ * `approvalType` in particular stays the TOOL NAME, exactly as in the hub's own
+ * chat: the NATS kernel gates approvals on approval TIER and escalates the rest,
+ * which is an agent-side concept a hub proposal has no tier for. Rewriting the
+ * tool name into a fake tier to slip past that gate would make the guide half of
+ * the stream diverge from the guide chat itself.
+ */
+export function guideEventForNats(event: ChatStreamEvent): ChatStreamEvent | null {
+  switch (event.type) {
+    case 'text-delta':
+      return { type: 'guide-delta', text: event.text }
+    case 'thinking-delta':
+      return { type: 'thinking-delta', text: escapeThinkingTags(event.text) }
+    case 'metadata':
+      return typeof event.conversationId === 'string' && event.conversationId
+        ? { type: 'metadata', conversationId: event.conversationId, origin: GUIDE_ORIGIN }
+        : null
+    default:
+      if (AGENT_OWNED_EVENTS.has(event.type)) return null
+      return ORIGIN_BEARING_EVENTS.has(event.type)
+        ? ({ ...event, origin: GUIDE_ORIGIN } as ChatStreamEvent)
+        : event
+  }
+}
+
+/**
+ * Decode one re-streamed Product Guide frame (a `GUIDE` chunk's `payload`) into
+ * a NATS event. The frame grammar is decoded by the shared table, never by a
+ * second copy here; the kernel reconciliation is `guideEventForNats`.
+ */
+export function guideFrameEvent(frame: Record<string, unknown>): ChatStreamEvent | null {
+  const events: ChatStreamEvent[] = []
+  // Every branch of the table pushes at most one event, so the first is the one.
+  mapLeadingFrame(frame, events)
+  const event = events[0]
+  return event ? guideEventForNats(event) : null
+}
+
 /**
  * Parse one raw NATS chunk into a normalized event. Returns `null` for
  * unknown/malformed chunks — an unrecognized `type`, a missing required
@@ -111,11 +210,20 @@ export function decodeNatsChunk(chunk: unknown): ChatStreamEvent | null {
       }
       return null
 
-    case MESSAGE_TYPE.GUIDE:
+    // Two shapes share this chunk type. `text` is the answer body the agent
+    // streams (and persists). `payload` is a Product Guide frame re-streamed
+    // verbatim from the hub — decoded through the shared frame table, with the
+    // narrowing `guideFrameEvent` documents.
+    case MESSAGE_TYPE.GUIDE: {
       if (typeof data.text === 'string') {
         return { type: 'guide-delta', text: data.text, ...seq }
       }
-      return null
+      const frame = data.payload
+      if (!frame || typeof frame !== 'object' || Array.isArray(frame)) return null
+      const event = guideFrameEvent(frame as Record<string, unknown>)
+      if (!event) return null
+      return { ...event, ...seq }
+    }
 
     // An ask card is only an ask card with something to pick: a question and at
     // least one option. Anything less is dropped rather than rendered as an

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

@@ -82,6 +82,7 @@ import {
   type UseUnifiedChatModes,
 } from './hooks/use-unified-chat'
 import type { UnifiedChatState } from './types/unified-chat-state.types'
+import type { MessageSegment } from './types/message.types'
 import type {
   UseNatsChatAdapterConfig,
   FetchDialogsParams,
@@ -209,6 +210,19 @@ export interface EmbeddableChatProps {
    */
   mingoState?: UnifiedChatState
 
+  /**
+   * Approval cards to pin as the sticky footer under the thread.
+   *
+   * Hosts that lift PENDING approvals out of the message list (mingo does:
+   * a pending card is filtered out of its bubble so an interrupted retry cannot
+   * render the same request twice) must hand them back here — otherwise the
+   * card exists in the reducer, is stripped on the way to the view, and is
+   * displayed nowhere at all. `ChatMessageList` renders them with the same
+   * component the inline path uses, so the approve/reject handlers stamped on
+   * the segments keep working.
+   */
+  pendingApprovals?: MessageSegment[]
+
   /**
    * Dialog-management capabilities for injected Mingo mode (`mingoState`).
    *
@@ -909,6 +923,7 @@ function EmbeddableChatInner({
   tableIdForDocumentType,
   modes,
   mingoState,
+  pendingApprovals,
   mingoDialogCapabilities,
   activeMode: controlledActiveMode,
   onActiveModeChange,
@@ -2350,6 +2365,9 @@ function EmbeddableChatInner({
                     <ChatMessageList
                       messages={messages}
                       isTyping={chatLoading}
+                      // Sticky footer for approvals the host lifted out of the
+                      // thread — see the prop's docblock.
+                      pendingApprovals={pendingApprovals}
                       // Real drawer: the library's smart follow. Passive in-page
                       // demo (previewMode): deterministic hard pin instead — a
                       // scripted assistant-only stream from a cold mount never

package/src/components/chat/hooks/use-sse-chat-adapter.ts

@@ -59,6 +59,7 @@ import type { MessageSegment } from '../types/message.types'
 import { useSlashCommandRegistry, type SlashCommandSummary } from './use-slash-commands'
 import { chatAuthedFetch } from '../utils/chat-authed-fetch'
 import type { ScrollAnchor } from '../utils/scroll-anchor'
+import { buildConfirmToolBody, readServerErrorMessage } from '../../../chat-protocol/confirm-tool'
 import { createSseFrameDecoder } from '../../../chat-protocol/decode'
 import type { ChatStreamEvent } from '../../../chat-protocol/events'
 import {
@@ -437,13 +438,11 @@ export function useSseChatAdapter(
         ? endpointsRef.current.approvalToolUrl
         : endpointsRef.current.chatStreamUrl
       const requestBody = approvalAction
-        ? {
-            proposal_id: approvalAction.proposalId,
-            action: approvalAction.action,
-            // Always present here — an approval can only happen inside an
-            // established conversation (the proposal turn captured the id).
-            conversationId,
-          }
+        ? // Shared with every other transport that resolves a hub proposal —
+          // the body shape is the hub's, not this adapter's. `conversationId`
+          // is always present here: an approval can only happen inside an
+          // established conversation (the proposal turn captured the id).
+          buildConfirmToolBody({ ...approvalAction, conversationId })
         : {
             messages: [{ role: 'user', content: text }],
             ...(commandOverride ? { commandOverride } : {}),
@@ -476,15 +475,7 @@ export function useSseChatAdapter(
           // `{error, code}`) — a bare "Chat request failed: 409" told
           // the user nothing when e.g. a batch approval expired; the
           // server ships real copy ("This approval expired — ...").
-          let serverMessage: string | null = null
-          try {
-            const errBody = (await response.json()) as { error?: unknown }
-            if (typeof errBody?.error === 'string' && errBody.error.length > 0) {
-              serverMessage = errBody.error
-            }
-          } catch {
-            /* non-JSON error body — fall through to the generic copy */
-          }
+          const serverMessage = await readServerErrorMessage(response)
           throw new Error(serverMessage ?? `Chat request failed: ${response.status}`)
         }
         const reader = response.body?.getReader()

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

@@ -58,6 +58,8 @@ import {
 import { getCommandText } from '../utils/tool-call-helpers'
 import { parseScrollAnchor, type ScrollAnchor } from '../utils/scroll-anchor'
 import { escapeThinkingTags } from '../../../chat-protocol/decode'
+import { isGuideOrigin } from '../../../chat-protocol/events'
+import { approvalDisplaysInline, guideApprovalOrigin } from '../utils/approval-display'
 import { buildChatRefKey } from '../types/chat.types'
 import type {
   ApprovalBatchSegment,
@@ -162,6 +164,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). */
@@ -520,6 +531,7 @@ export function createChatStreamReducer(
   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 ?? {}),
   }
@@ -682,6 +694,7 @@ export function createChatStreamReducer(
         dialogTokenUsage,
         liveModel,
         approvalStatuses,
+        guideConversationId,
       }
     }
     return stateCache
@@ -989,6 +1002,17 @@ export function createChatStreamReducer(
       }
 
       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', {
@@ -1101,11 +1125,17 @@ export function createChatStreamReducer(
         const requestId = event.requestId
         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`) — 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 ──
           const status = (approvalStatuses[requestId] || 'pending') as ChatApprovalStatus
-          if (!displayApprovalTypes.includes(approvalType)) {
+          if (!displayInline(approvalType)) {
             // Escalated: keep batch context locally for replay on result;
             // surface a summary command via the legacy escalation callback.
             const required = toolCalls.find((c) => c.requiresApproval) ?? toolCalls[0]
@@ -1127,7 +1157,15 @@ export function createChatStreamReducer(
           }
           if (batchApprovalsEnabled) {
             const before = accumulator.getSegments().length
-            const segments = accumulator.addApprovalBatch(requestId, approvalType, toolCalls, status)
+            const segments = accumulator.addApprovalBatch(
+              requestId,
+              approvalType,
+              toolCalls,
+              status,
+              undefined,
+              undefined,
+              guideOrigin,
+            )
             applyAccumulated(before, segments)
             break
           }
@@ -1145,6 +1183,8 @@ export function createChatStreamReducer(
               call.toolExplanation,
               approvalType,
               status,
+              undefined,
+              guideOrigin,
             )
           }
           applyAccumulated(before, segments)
@@ -1154,7 +1194,7 @@ export function createChatStreamReducer(
         // ── Single form ──
         const command = event.command ?? ''
         const explanation = event.explanation
-        if (displayApprovalTypes.includes(approvalType)) {
+        if (displayInline(approvalType)) {
           const status = (approvalStatuses[requestId] || 'pending') as ChatApprovalStatus
           const before = accumulator.getSegments().length
           const segments = accumulator.addApprovalRequest(
@@ -1163,6 +1203,10 @@ export function createChatStreamReducer(
             explanation,
             approvalType,
             status,
+            // 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 {
@@ -1707,6 +1751,7 @@ export function createChatStreamReducer(
     streamingPhase = 'idle'
     dialogTokenUsage = null
     liveModel = null
+    guideConversationId = null
     approvalStatuses = {}
     accumulator.reset()
     pendingEscalated.clear()
@@ -1755,6 +1800,7 @@ export function createChatStreamReducer(
     streamingPhase = 'idle'
     dialogTokenUsage = null
     liveModel = null
+    guideConversationId = null
     accumulator.reset()
     pendingEscalated.clear()
     isInStream = false

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

@@ -113,6 +113,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 {
@@ -189,6 +195,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
@@ -334,6 +345,10 @@ export interface ThinkingMessageData extends MessageDataBase {
 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

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

@@ -61,6 +61,10 @@ export interface ChunkData {
   /** On APPROVAL_RESULT chunks: display name of the user who resolved the request. */
   resolvedByName?: string
   toolCalls?: any[]
+  /** 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
   provider?: string

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

@@ -3,7 +3,12 @@
  * Contains types for message parsing, accumulation, and processing
  */
 
-import type { MessageSegment, PendingToolCallData, ExecutingToolState } from './message.types'
+import type {
+  ApprovalRequestField,
+  MessageSegment,
+  PendingToolCallData,
+  ExecutingToolState,
+} from './message.types'
 import type { ChatApprovalStatus, AssistantType } from './chat.types'
 import type { ChunkData } from './network.types'
 
@@ -18,6 +23,12 @@ export interface PendingApproval {
   command: string
   explanation?: string
   approvalType: string
+  /** 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 {