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

package/src/components/chat/thinking-display.tsx

@@ -4,7 +4,7 @@ import { forwardRef, useState } from "react"
 
 import { cn } from "../../utils/cn"
 import { DotsLoaderIcon } from "../icons-v2-generated"
-import { SimpleMarkdownRenderer } from "../ui/simple-markdown-renderer"
+import { SimpleMarkdownRenderer } from "../ui/markdown/simple-markdown-renderer"
 import { ExpandChevron } from "./expand-chevron"
 import { useCollapsible } from "./hooks/use-collapsible"
 import type { ThinkingDisplayProps } from "./types"

package/src/components/chat/types/.api.types.md

@@ -1,70 +1,60 @@
-<!-- source-hash: 76966dd4845d1486e56288fc8033df68 -->
-Defines TypeScript interfaces for API interactions and React hook contracts used in the OpenFrame real-time chat and NATS messaging system.
+<!-- source-hash: 60ad035125eceb97fa074f58783d5bc8 -->
+Defines TypeScript interfaces for API interactions and React hook contracts used across Flamingo's chat and dialog systems, covering NATS/JetStream subscriptions, real-time chunk processing, and REST-style request/response shapes.
 
 ## Key Components
 
-### Hook Option Interfaces
-- **`UseChunkCatchupOptions`** — Configuration for chunk catch-up logic, including dialog ID, chunk callbacks, chat type filters, and an optional custom fetch function
-- **`UseNatsDialogSubscriptionOptions`** — NATS WebSocket subscription config with reconnection backoff tuning, auth lifecycle hooks, and client credentials
-- **`UseJetStreamDialogSubscriptionOptions`** — JetStream-specific variant adding stream name, sequence-based replay (`optStartSeq`), and consumer inactivity threshold
-- **`UseRealtimeChunkProcessorOptions`** — Controls chunk processing behavior: approval type routing, batch approvals, direct-mode barrier, and initial accumulator state for reconnection
-
-### Hook Return Interfaces
-- **`UseChunkCatchupReturn`** — Exposes `catchUpChunks`, `processChunk`, `resetAndCatchUp`, and buffering state controls
-- **`UseNatsDialogSubscriptionReturn`** / **`UseJetStreamDialogSubscriptionReturn`** — Connection/subscription status and reconnection counters; JetStream variant also tracks `currentStreamSeq`
-- **`UseRealtimeChunkProcessorReturn`** — `processChunk`, `getSegments`, `reset`, and `updateApprovalStatus`
-
-### Callback & Metadata Interfaces
-- **`RealtimeChunkCallbacks`** — Comprehensive event callback surface covering stream lifecycle (`onStreamStart`, `onStreamEnd`), message types (user, direct, system), tool execution (`onToolExecuted`, `onAgentBusy`), approval flows (`onApprove`, `onReject`, `onEscalatedApproval`, `onApprovalResolved`), token usage, and dialog closure
-- **`SegmentsUpdateMetadata`** — Carries append mode, compaction flags, and JetStream `streamSeq` for history deduplication
+### Hook Options
+| Interface | Purpose |
+|---|---|
+| `UseChunkCatchupOptions` | Configure chunk catch-up replay with optional custom fetch function |
+| `UseNatsDialogSubscriptionOptions` | Core NATS WebSocket subscription config with reconnection backoff tuning |
+| `UseJetStreamDialogSubscriptionOptions` | JetStream-based subscription with sequence-based resume support |
+
+### Hook Return Types
+| Interface | Purpose |
+|---|---|
+| `UseChunkCatchupReturn` | Exposes catchup, processing, and buffering controls |
+| `UseNatsDialogSubscriptionReturn` | Connection state and reconnection counter |
+| `UseJetStreamDialogSubscriptionReturn` | Connection state plus current stream sequence |
+
+### Callbacks
+- **`RealtimeChunkCallbacks`** — Rich event callback map for streaming events: `onStreamStart`, `onStreamEnd`, `onSegmentsUpdate`, `onTokenUsage`, `onApprove`, `onReject`, `onEscalatedApproval`, `onApprovalResolved`, `onToolExecuted`, `onDialogClosed`, and more.
+
+### API Request/Response Types
+- **Chat** — `ChatAPIRequest` / `ChatAPIResponse`
+- **Dialogs** — `DialogCreateRequest/Response`, `DialogListRequest/Response`
+- **Approvals** — `ApprovalRequest` / `ApprovalResponse`
+- **Settings** — `ChatSettings`, `UpdateSettingsRequest/Response`
 
 ## Usage Example
 
 ```typescript
-import type {
-  UseNatsDialogSubscriptionOptions,
-  UseRealtimeChunkProcessorOptions,
-  RealtimeChunkCallbacks,
-} from './api.types'
-
-const callbacks: RealtimeChunkCallbacks = {
-  onStreamStart: () => setStreaming(true),
-  onStreamEnd: () => setStreaming(false),
-  onSegmentsUpdate: (segments, meta) => {
-    if (meta?.append) appendSegments(segments)
-    else setSegments(segments)
-  },
-  onToolExecuted: (segment) => mergeToolResult(segment),
-  onApprovalResolved: (requestId, status, approvalType) => {
-    updateApprovalCard(requestId, status)
+const options: ChatStreamReducerOptions = {
+  callbacks: {
+    onSegmentsUpdate: (segments, meta) => {
+      if (meta?.append) appendToLastMessage(segments)
+      else setSegments(segments)
+    },
+    onApprovalResolved: (requestId, status, approvalType) => {
+      updateApprovalBadge(requestId, status)
+    },
+    onTokenUsage: (data) => console.log('Tokens used:', data),
   },
-}
-
-const processorOptions: UseRealtimeChunkProcessorOptions = {
-  callbacks,
-  displayApprovalTypes: ['CLIENT'],
   batchApprovalsEnabled: true,
-  initialState: {
-    existingSegments: historicalSegments,
-    executingTools: new Map(),
-  },
+  displayApprovalTypes: ['CLIENT'],
+  enableThinking: false,
 }
 
 const natsOptions: UseNatsDialogSubscriptionOptions = {
   enabled: true,
   dialogId: 'dialog-123',
-  topics: ['message'],
   getNatsWsUrl: () => 'wss://nats.example.com',
-  onBeforeReconnect: async () => refreshAuthToken(),
   reconnectionBackoff: {
     fastRetries: 3,
     fastRetryDelayMs: 500,
-    maxDelayMs: 30_000,
+    maxDelayMs: 30000,
     multiplier: 2,
   },
+  onBeforeReconnect: async () => refreshAuthToken(),
 }
-```
-
-## Source
-
-[`api.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/api.types.ts)
+```

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

@@ -1,80 +1,51 @@
-<!-- source-hash: bdb71cca9908cf9cfebf089a00d84db8 -->
-Defines TypeScript types for the message processing pipeline, covering chunk parsing, state accumulation, stream control, and buffer management.
+<!-- source-hash: 118d3a4cacf89174498282067448e4bf -->
+Defines TypeScript types for message processing pipeline operations, including chunk parsing, accumulator state management, stream control, and buffer management for AI chat message flows.
 
 ## Key Components
 
-### Union Types
-- **`ParsedChunkAction`** — Discriminated union of all possible chunk parse results: `message_start`, `message_end`, `error`, `metadata`, `text`, `thinking`, `tool_execution`, `approval_request`, `approval_batch`, `approval_result`, `token_usage`, `direct_message`, `system`, `context_compaction_start/end`, `dialog_closed`
-
-### Accumulator State
-- **`AccumulatorState`** — Tracks in-flight message segments, pending approvals, and executing tool states during streaming
-- **`PendingApproval`** — Holds command, explanation, and approval type for a deferred approval card
-
-### Processing Configuration
-- **`MessageProcessingOptions`** — Runtime options passed to the processor: assistant identity, approval callbacks, chat type filter, approval status map, `displayApprovalTypes`, and `batchApprovalsEnabled` (consumer-owned feature flag)
-
-### Chunk Processing
-- **`ChunkProcessor`** — Interface for stateful chunk parsing with `processChunk` and `reset`
-- **`ChunkProcessorOptions`** — Lifecycle callbacks for chunk events (`onText`, `onToolExecution`, `onApprovalRequest`, etc.)
-
-### Message Transformation
-- **`MessageTransformer`** — Single and batch transform interface producing `ProcessedMessage` outputs
-- **`TransformationOptions`** — Flags for segment merging, timestamp formatting, and metadata inclusion
-
-### Stream & Buffer Management
-- **`StreamProcessor`** — Lifecycle control (`start`, `stop`, `pause`, `resume`, `reset`, `getState`)
-- **`StreamState`** — Runtime counters: active state, pause flag, processed message count, buffered chunks, error log
-- **`BufferManager`** — FIFO buffer operations (`add`, `flush`, `clear`, `size`, `isEmpty`, `isFull`)
-- **`BufferOptions`** — Max size, flush interval, and overflow/flush callbacks
+| Export | Type | Description |
+|--------|------|-------------|
+| `AccumulatorState` | Interface | Stateful container tracking message segments, pending approvals, and executing tools during stream processing |
+| `PendingApproval` | Interface | Represents an approval request awaiting user action (command, explanation, type) |
+| `MessageProcessingOptions` | Interface | Configuration for assistant rendering, approval callbacks, chat filtering, and batch approval UI |
+| `StreamProcessor` | Interface | Full lifecycle control (start/stop/pause/resume/reset) for stream consumers |
+| `StreamState` | Interface | Snapshot of stream health: active status, buffered chunks, error log, and last activity timestamp |
+| `BufferManager` | Interface | CRUD-style contract for managing `ChunkData` buffers |
+| `BufferOptions` | Interface | Configuration for buffer capacity, flush intervals, and overflow handling callbacks |
 
 ## Usage Example
 
 ```typescript
 import type {
-  ParsedChunkAction,
   AccumulatorState,
   MessageProcessingOptions,
-  StreamState,
+  StreamState
 } from './processing.types'
 
-// Narrow a parsed chunk action by discriminant
-function handleChunk(action: ParsedChunkAction) {
-  switch (action.action) {
-    case 'text':
-      console.log('Text received:', action.text)
-      break
-    case 'tool_execution':
-      console.log('Tool segment:', action.segment)
-      break
-    case 'approval_batch':
-      console.log('Batch approval', action.requestId, action.toolCalls)
-      break
-    case 'error':
-      console.error(action.error, action.details)
-      break
-  }
+
+// Initializing accumulator state
+const state: AccumulatorState = {
+  segments: [],
+  pendingApprovals: new Map(),
+  executingTools: new Map()
 }
 
-// Configure message processing with batch approvals enabled
+// Configuring message processing
 const options: MessageProcessingOptions = {
   assistantName: 'Mingo',
   assistantType: 'mingo',
-  batchApprovalsEnabled: true, // consumer sets this from their feature flag
-  displayApprovalTypes: ['shell', 'file_write'],
+  batchApprovalsEnabled: true,
+  displayApprovalTypes: ['shell', 'file'],
   onApprove: async (requestId) => {
-    await fetch(`/api/approvals/${requestId}/approve`, { method: 'POST' })
-  },
-  onReject: async (requestId) => {
-    await fetch(`/api/approvals/${requestId}/reject`, { method: 'POST' })
+    await submitApproval(requestId)
   },
-}
-
-// Initialize accumulator state
-const state: AccumulatorState = {
-  segments: [],
-  pendingApprovals: new Map(),
-  executingTools: new Map(),
+  onReject: (requestId) => {
+    logRejection(requestId)
+  }
 }
 ```
 
-**Source:** [`processing.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/processing.types.ts)
+> NOTE: the wire-chunk vocabulary now lives in `src/chat-protocol/events.ts`
+> (`ChatStreamEvent`, produced by `decodeNatsChunk`). The old
+> `ParsedChunkAction` union and the `ChunkProcessor` contract were deleted
+> together with the legacy `chunk-parser`.

package/src/components/chat/types/.unified-chat-state.types.md

@@ -1,4 +1,4 @@
-<!-- source-hash: cae6679d748353879069b316add2f081 -->
+<!-- source-hash: c1ee0588313988b2559f2016a0a5d7cf -->
 Unified contract type definitions for the `useChat` hook's transport-agnostic return shape, shared by both the SSE (Guide mode) and NATS (Mingo mode) transport adapters.
 
 ## Key Components
@@ -9,7 +9,7 @@ Unified contract type definitions for the `useChat` hook's transport-agnostic re
 | `ChatConnectionState` | Type | Transport-level connection status: `'connected' \| 'connecting' \| 'disconnected'` |
 | `StreamingPhase` | Type | Granular streaming indicator: `'idle' \| 'thinking' \| 'streaming'` |
 | `UnifiedUsageBreakdown` | Interface | SSE-only sub-call token costs for the Haiku rewriter/classifier/summarizer pipeline |
-| `UnifiedChatMessage` | Interface | Transport-agnostic message shape; Guide-only fields (`sources`, `chatRefs`) are optional |
+| `UnifiedChatMessage` | Interface | Transport-agnostic message shape; Guide-only fields (`sources`, `chatRefs`) are optional. `streamSeq` is not render input — it is the per-message coverage signal `mergeHistoryWithRealtime` decides with, and omitting it makes a mid-stream history refetch drop live bubbles |
 | `UnifiedSendMessageOptions` | Interface | Options accepted by `sendMessage` honoured by both transports |
 | `UnifiedChatState` | Interface | **Primary contract** — the full return shape both transport hooks must satisfy |
 

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

@@ -220,79 +220,12 @@ export interface RealtimeChunkCallbacks {
   onDialogClosed?: () => void
 }
 
-export interface UseRealtimeChunkProcessorOptions {
-  callbacks: RealtimeChunkCallbacks
-  /**
-   * Filter approval types that should be displayed directly
-   * Others will trigger onEscalatedApproval
-   * Default: ['CLIENT']
-   */
-  displayApprovalTypes?: string[]
-  /**
-   * Map of existing approval statuses
-   */
-  approvalStatuses?: Record<string, ChatApprovalStatus>
-  /**
-   * Initialize accumulator with existing state from incomplete historical message
-   * Used to continue building messages across page refreshes or reconnections
-   */
-  initialState?: {
-    /** Existing segments to continue building upon */
-    existingSegments?: MessageSegment[]
-    /** Pending approvals that haven't been resolved */
-    pendingApprovals?: Map<string, { command: string; explanation?: string; approvalType: string }>
-    /** Executing tools waiting for completion */
-    executingTools?: Map<string, ExecutingToolState>
-    /** Escalated approvals */
-    escalatedApprovals?: Map<
-      string,
-      { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
-    >
-  }
-  /**
-   * Consumer-owned (e.g. set in `openframe-oss-tenant` chat client via the
-   * `'batch-approvals'` feature flag and forwarded here). The lib does NOT
-   * default this to a batch-on behavior — when omitted it falls back to the
-   * legacy single-card rendering.
-   *
-   * When true: `APPROVAL_REQUEST` chunks containing `toolCalls[]` are rendered
-   * as a single batch card. When false / omitted: the batch is split into N
-   * legacy approval cards (one per tool that requires approval), all sharing
-   * the same `approvalRequestId`. Tools with `requiresApproval=false` are
-   * dropped from the UI in the unfolded mode.
-   */
-  batchApprovalsEnabled?: boolean
-  /**
-   * Engages the direct-mode barrier optimistically: once true, all AI-assistant
-   * chunks (text, thinking, tool executions, approvals, metadata, errors, etc.)
-   * are dropped and any open stream is torn down, leaving only human/control
-   * messages. A `DIRECT_MESSAGE` chunk engages the same barrier automatically
-   * regardless of this flag. Pass this from a host that already knows the dialog
-   * switched to direct mode (e.g. an optimistic mode toggle) to close the race
-   * window before the server emits the first `DIRECT_MESSAGE`.
-   *
-   * Do NOT set this when the host reconstructs history by replaying chunks
-   * through `processChunk` — a static flag would drop legitimate pre-switch AI
-   * history. Rely on the in-order `DIRECT_MESSAGE` detection instead.
-   */
-  isDirectMode?: boolean
-}
-
-export interface UseRealtimeChunkProcessorReturn {
-  /** Process a single chunk */
-  processChunk: (chunk: unknown) => void
-  /** Get current segments */
-  getSegments: () => MessageSegment[]
-  /** Reset the accumulator */
-  reset: () => void
-  /** Update approval status for a request */
-  updateApprovalStatus: (requestId: string, status: ChatApprovalStatus, resolvedByName?: string | null) => MessageSegment[]
-  /** Get pending approval requests */
-  getPendingApprovals: () => Map<
-    string,
-    { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
-  >
-}
+// NOTE: `UseRealtimeChunkProcessorOptions` / `UseRealtimeChunkProcessorReturn`
+// were DELETED along with the `useRealtimeChunkProcessor` compat hook. The
+// equivalents are `ChatStreamReducerOptions` + `ChatStreamReducer` in
+// `../stream/chat-stream-reducer`. `RealtimeChunkCallbacks` above SURVIVES:
+// it is still the canonical description of the effect names/args the reducer
+// emits via `ChatReducerEffect`.
 
 // ========== API Request Types ==========
 

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

@@ -3,38 +3,14 @@
  * Contains types for message parsing, accumulation, and processing
  */
 
-import type { MessageSegment, ProcessedMessage, ToolExecutionSegment, TokenUsageData, PendingToolCallData, ExecutingToolState } from './message.types'
+import type { MessageSegment, PendingToolCallData, ExecutingToolState } from './message.types'
 import type { ChatApprovalStatus, AssistantType } from './chat.types'
-import type { ChunkData, NatsMessageType } from './network.types'
-
-// ========== Parsed Chunk Result Types ==========
-
-export type ParsedChunkAction =
-  | { action: 'message_start' }
-  | { action: 'message_end' }
-  | { action: 'error'; error: string; details?: string }
-  | { action: 'metadata'; modelDisplayName: string; modelName: string; providerName: string; contextWindow: number }
-  | { action: 'text'; text: string }
-  | { action: 'thinking'; text: string }
-  | { action: 'guide'; text: string }
-  | { action: 'tool_execution'; segment: ToolExecutionSegment }
-  | { action: 'approval_request'; requestId: string; command: string; explanation?: string; approvalType: string }
-  | { action: 'approval_batch'; requestId: string; approvalType: string; toolCalls: PendingToolCallData[] }
-  | { action: 'approval_result'; requestId: string; approved: boolean; approvalType: string; resolvedByName?: string | null }
-  | {
-      action: 'message_request'
-      text: string
-      ownerType?: string
-      displayName?: string
-      userId?: string
-      contextItems?: Array<{ type: string; id: string }>
-    }
-  | { action: 'token_usage'; data: TokenUsageData }
-  | { action: 'direct_message'; text: string; ownerType?: string; displayName?: string; userId?: string }
-  | { action: 'system'; text: string }
-  | { action: 'context_compaction_start' }
-  | { action: 'context_compaction_end'; summary?: string }
-  | { action: 'dialog_closed' }
+import type { ChunkData } from './network.types'
+
+// NOTE: the `ParsedChunkAction` union that used to live here was DELETED
+// alongside the legacy `chunk-parser`. The wire → normalized-event
+// vocabulary is now `ChatStreamEvent` in `src/chat-protocol/events.ts`,
+// produced by `decodeNatsChunk`.
 
 // ========== Accumulator State ==========
 
@@ -82,31 +58,13 @@ export interface MessageProcessingOptions {
   batchApprovalsEnabled?: boolean
 }
 
-// ========== Chunk Processing Types ==========
-
-export interface ChunkProcessor {
-  processChunk: (chunk: ChunkData, messageType: NatsMessageType) => ParsedChunkAction | null
-  reset: () => void
-}
-
-export interface ChunkProcessorOptions {
-  onMessageStart?: () => void
-  onMessageEnd?: () => void
-  onError?: (error: string, details?: string) => void
-  onText?: (text: string) => void
-  onToolExecution?: (segment: MessageSegment) => void
-  onApprovalRequest?: (data: any) => void
-  onApprovalResult?: (data: any) => void
-  onMetadata?: (data: any) => void
-}
+// NOTE: `ChunkProcessorOptions` (the options bag of the deleted
+// `ChunkProcessor`) and `MessageTransformer` were DELETED — both were left
+// behind by the chunk-processor removal with zero references in lib, hub, or
+// app.
 
 // ========== Message Transformation Types ==========
 
-export interface MessageTransformer {
-  transform: (input: any) => ProcessedMessage | null
-  batch: (inputs: any[]) => ProcessedMessage[]
-}
-
 export interface TransformationOptions {
   preserveOriginal?: boolean
   mergeSegments?: boolean

package/src/components/chat/types/unified-chat-state.types.ts

@@ -144,6 +144,22 @@ export interface UnifiedChatMessage {
   content: string
   segments?: MessageSegment[]
 
+  /**
+   * Highest chunk `streamSeq` consumed into THIS row. Not render input — it is
+   * the per-message coverage signal `mergeHistoryWithRealtime` decides with:
+   * a live synthetic is a twin of a persisted row only once history reaches
+   * its seq.
+   *
+   * Load-bearing, not bookkeeping. Without it the merge falls through to its
+   * wall-clock fallback ("created before the fetch instant ⇒ history has it"),
+   * which is wrong for every turn the backend has not finished persisting: a
+   * history refetch mid-stream then drops every live bubble except the single
+   * `streamingMessageId`, collapsing the thread to the persisted user prompt.
+   * The reducer stamps it on the rows it owns; hosts stamp the persisted value
+   * on history rows.
+   */
+  streamSeq?: number
+
   /**
    * Optional host-supplied message timestamp (creation/send time). Rendered
    * as the message-row time and, critically, fed into the memoized message's

package/src/components/chat/utils/.extract-incomplete-message-state.md

@@ -1,4 +1,4 @@
-<!-- source-hash: d829899f7bd3695292f7399c706c0b38 -->
+<!-- source-hash: 954138e90e8f1d0354f644a2df37cd43 -->
 Extracts incomplete message state from the last historical assistant message, enabling the realtime chunk processor to resume building messages across reconnected sessions.
 
 ## Key Components
@@ -10,17 +10,35 @@ Inspects a `ProcessedMessage` and returns resumable state if any in-progress seg
 **Parameters:**
 - `lastMessage` — A `ProcessedMessage` or `undefined`
 
-**Returns:** An object with optional `existingSegments`, `pendingApprovals`, and `executingTools`, or `undefined` if the message is complete or ineligible.
+**Returns:** An object with optional `existingSegments`, `pendingApprovals`, `executingTools`, and `agentBusy`, or `undefined` if the message is complete or ineligible.
 
 **Incomplete state detection by segment type:**
 
 | Segment Type | Condition Flagged Incomplete |
 |---|---|
 | `tool_execution` | Status is `EXECUTING_TOOL` |
-| `approval_request` | Status is `pending` with a `requestId` |
+| `approval_request` | Status is `pending` with a `requestId`, **or** `approved` as the trailing segment |
 | `approval_batch` | Not `rejected` and not all tool calls have `done` executions |
 | `context_compaction` | Status is `started` |
 
+### `agentBusy` — incomplete ≠ working
+
+Unfinished says nothing about WHO the turn is waiting on, and only the activity
+indicator's answer to that is user-visible. `agentBusy` is the second, narrower
+question, derived here so every host answers it the same way (the reducer raises
+`idle → thinking` off it on `initializeWithState`; callback-contract hosts fire
+`onAgentBusy`). Nothing on the wire restores this after a reload: a run's
+EXECUTING chunk is long past and its EXECUTED one may be minutes away.
+
+| Tail state | Busy | Why |
+|---|---|---|
+| `EXECUTING_TOOL` with no result | ✅ | The tool is running now |
+| `approval_batch` `approved`, calls outstanding | ✅ | Runs are recorded inside the batch, so `executingTools` is empty — gating on that map missed the whole approval path |
+| `approval_request` `approved`, trailing | ✅ | A single request carries no execution record; work that followed it is the only "it came back" signal |
+| `context_compaction` `started` | ✅ | Compaction is the agent's own work |
+| Any approval still `pending` | ❌ | Blocked on the USER — spinning claims work that is not happening |
+| `rejected` / `cancelled`, or all calls `done` | ❌ | Nothing outstanding |
+
 ## Usage Example
 
 ```typescript

package/src/components/chat/utils/.history-merge.md

@@ -1,4 +1,4 @@
-<!-- source-hash: 5df51000b55f2d031915f5b4412ac8e6 -->
+<!-- source-hash: f5c3c4354e937c99e37f2acc47057b09 -->
 Reconciles persisted dialog history (processed GraphQL pages) with realtime messages accumulated from streaming chunks, preventing both duplicate and lost turns across MSP chat interfaces (Mingo, tickets, openframe-chat).
 
 ## Key Components
@@ -49,11 +49,17 @@ store.setMessages(merged)
 
 ```mermaid
 graph TD
-    A[Synthetic message] --> B{"Per-row streamSeq\navailable?"}
-    B -->|Yes| C{"Same-role history\nmax seq >= synthetic seq?"}
+    A[Synthetic message] --> B{"Synthetic carries\nits own streamSeq?"}
+    B -->|Yes| B2{"Any history row\nseq-stamped?"}
+    B2 -->|Yes| C{"Same-role history\nmax seq >= synthetic seq?"}
+    B2 -->|No| I{"Global\nhistoryMaxStreamSeq > 0?"}
     B -->|No| D{"Global seq\ncoverage known?"}
     C -->|Yes| E[Drop synthetic]
     C -->|No| F[Keep synthetic]
+    I -->|Yes| G2{"historyMaxStreamSeq\n>= synthetic seq?"}
+    I -->|No| F
+    G2 -->|Yes| E
+    G2 -->|No| F
     D -->|Yes| G{"historyMaxStreamSeq\n>= realtimeSeenSeq?"}
     D -->|No| H{"Created after\nhistoryFetchedAt?"}
     G -->|Yes| E
@@ -62,4 +68,39 @@ graph TD
     H -->|No| E
 ```
 
+**A seq'd synthetic never falls back to wall-clock.** When nothing in history is
+seq-stamped, `historyMaxStreamSeq === 0` is not "unknown, guess by clock" — it is
+evidence that no persisted row has reached any seq, so the snapshot cannot
+contain this turn. That case is the mid-stream refetch (a reconnect after the
+window loses focus): the only persisted row of a turn in flight is the user
+`MESSAGE_REQUEST`, which the backend does not stamp. Judging live bubbles by
+wall-clock there read them all as "older than the fetch instant, therefore
+persisted" and dropped every one except the single `streamingMessageId`,
+collapsing the thread to the user's prompt.
+
+This is why the reducer stamps `streamSeq` on the rows it owns — a live bubble
+with no seq at all still lands in the wall-clock branch.
+
+## Turn identity (twins whose ids differ)
+
+Keeping a live bubble is only half the job: history may hold its own PARTIAL
+copy of the same in-flight turn, and then the turn renders twice with the two
+copies disagreeing (a tool row `pending` in one, `failed` in the other) because
+each stopped at a different chunk.
+
+Ids do not help — they converge only through adoption, and adoption happens on a
+REPLAY (a reload re-streams the turn into the persisted row). A refetch that
+lands mid-stream has no replay, so the live copy keeps the synthetic id the
+reducer minted.
+
+`turnRequestKeys` supplies the missing identity: the backend's per-call request
+ids (tool-call ids, approval request ids, batch ids) are carried by BOTH copies.
+When history's trailing assistant shares one with a live assistant, they are the
+same turn, and the trailing pin keeps the live copy if it is **streaming** (the
+chunks are landing there, so history's snapshot is stale by construction) or
+strictly richer. Once persistence catches up the live copy is no longer richer,
+seq coverage drops it, and the persisted row wins — self-healing, no sticky
+state. A turn that has produced only text yields no keys, which is treated as
+"no signal", never as a match.
+
 > **Source:** [`history-merge.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/history-merge.ts)

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

@@ -1,57 +1,48 @@
-<!-- source-hash: 0435e7889d0ba1d3a5186507e28737c9 -->
-Barrel export module for the message processing utilities library, re-exporting all public APIs from specialized sub-modules covering chat message parsing, navigation, attachments, icons, and more.
+<!-- source-hash: 85c0af6cd361347beeabcd097260378a -->
+Barrel export module that consolidates and re-exports all message processing, chat navigation, UI styling, and content utility functions for chat interfaces.
 
 ## Key Components
 
-| Export Group | Source Module | Description |
-|---|---|---|
-| Chunk parsing | `chunk-parser` | Parse streaming chunks into actions, detect control/error/metadata chunks |
-| Segment accumulator | `message-segment-accumulator` | Accumulate streaming message segments with callbacks |
-| Historical messages | `process-historical-messages` | Process and reconcile chat history with error extraction |
-| History merge | `history-merge` | Reconcile persisted history with realtime stream data |
-| Navigation | `execute-navigation`, `nav-click-handler`, `decide-new-tab` | Unified navigation primitive for new-tab/same-tab, internal/external, embed/host routing |
-| Chat attachment | `chat-attachment-markdown` | Format and strip attachment markdown, URL/token helpers |
-| Icon registry | `icon-registry`, `icon-library`, `source-icons` | Single source of truth for icon-name → component lookups |
-| Proxy auth | `chat-proxy-auth-storage`, `chat-authed-fetch` | localStorage adapter and authenticated fetch wrapper |
-| Slash commands | `slash-dispatch-utils` | Command parsing, entity filtering, and dispatch utilities |
-| Compact card | `compact-card-classes` | Shared CSS class constants and safe-href guard |
-| Scripted stream | `scripted-stream` | Re-exported wholesale via `export *` |
+| Category | Exports |
+|----------|---------|
+| **Message Accumulation** | `MessageSegmentAccumulator`, `createMessageSegmentAccumulator`, `AccumulatorCallbacks` |
+| **Historical Messages** | `processHistoricalMessages`, `extractErrorMessages`, `processHistoricalMessagesWithErrors` |
+| **Chat Navigation** | `handleChatNavClick`, `resolveExternalNavigation`, `decideNewTab`, `computeIsNewTab`, `buildAnchorProps` |
+| **Proxy Auth** | `getChatProxyAuth`, `setChatProxyAuth`, `clearChatProxyAuth`, `applyProxyAuth`, `chatAuthedFetch` |
+| **Attachments** | `formatChatAttachmentMarkdownForBubble`, `stripChatAttachmentMarkdown`, `buildChatAttachmentViewUrl` |
+| **UI / Styling** | `chatChipClass`, compact card class constants (`COMPACT_CARD_*`), `getStatusColorScheme` |
+| **Icon Registry** | `ICON_REGISTRY`, `getIconComponent`, `normalizeIconKey`, `getDynamicIcon` |
+| **Source Utilities** | `getSourceIconName`, `getSourceLabel`, `resolveSourceRowCTA`, `resolveSourceIcon` |
+| **Slash Commands** | `parseWireCommandOverride`, `sanitizeTitleForChat`, `buildDiscussAddendum` |
 
 ## Usage Example
 
 ```typescript
 import {
-  parseChunkToAction,
   createMessageSegmentAccumulator,
-  executeNavigation,
-  resolveIcon,
-  getStatusColorScheme,
-  mergeHistoryWithRealtime,
+  handleChatNavClick,
+  getChatProxyAuth,
+  getIconComponent,
   formatChatAttachmentMarkdownForBubble,
-} from '@openframe/chat-utils'
-
-// Parse a streaming chunk
-const action = parseChunkToAction(rawChunk)
+  decideNewTab,
+  getStatusColorScheme,
+} from '@flamingo/chat-utils'
 
-// Accumulate message segments from a stream
+// Accumulate streamed message segments
 const accumulator = createMessageSegmentAccumulator({
-  onSegmentComplete: (segment) => console.log('Segment done:', segment),
+  onSegmentComplete: (segment) => console.log('Segment:', segment),
 })
 
-// Execute navigation respecting new-tab rules
-executeNavigation({
-  href: '/tickets/123',
-  event: clickEvent,
-  surface: 'chat',
+// Resolve navigation target for a chat link
+const { openInNewTab } = decideNewTab({
+  href: 'https://app.example.com/tickets/123',
+  surface: 'chat-bubble',
+  mode: 'web',
 })
 
-// Resolve an icon by name
-const Icon = resolveIcon('clickup')
-
-// Get agent status color scheme
-const colors = getStatusColorScheme('online')
-```
-
-## Source
+// Look up a registered icon by kebab-case key
+const Icon = getIconComponent('clickup')
 
-[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)
+// Apply agent status color scheme to UI
+const colors = getStatusColorScheme('running')
+```