@flamingo-stack/openframe-frontend-core 0.0.489 → 0.0.490-1506.3944.1

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/api.types.ts

@@ -213,79 +213,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,37 +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: '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 ==========
 
@@ -81,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/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')
+```