@flamingo-stack/openframe-frontend-core 0.0.457 → 0.0.458-snapshot.20260720215024

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

@@ -9,7 +9,6 @@ Defines TypeScript interfaces for API interactions and React hook contracts used
 | `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 |
-| `UseRealtimeChunkProcessorOptions` | Controls how streaming chunks are parsed, including approval routing and batch mode |
 
 ### Hook Return Types
 | Interface | Purpose |
@@ -17,7 +16,6 @@ Defines TypeScript interfaces for API interactions and React hook contracts used
 | `UseChunkCatchupReturn` | Exposes catchup, processing, and buffering controls |
 | `UseNatsDialogSubscriptionReturn` | Connection state and reconnection counter |
 | `UseJetStreamDialogSubscriptionReturn` | Connection state plus current stream sequence |
-| `UseRealtimeChunkProcessorReturn` | Chunk processing, segment access, and approval status management |
 
 ### Callbacks
 - **`RealtimeChunkCallbacks`** — Rich event callback map for streaming events: `onStreamStart`, `onStreamEnd`, `onSegmentsUpdate`, `onTokenUsage`, `onApprove`, `onReject`, `onEscalatedApproval`, `onApprovalResolved`, `onToolExecuted`, `onDialogClosed`, and more.
@@ -31,7 +29,7 @@ Defines TypeScript interfaces for API interactions and React hook contracts used
 ## Usage Example
 
 ```typescript
-const options: UseRealtimeChunkProcessorOptions = {
+const options: ChatStreamReducerOptions = {
   callbacks: {
     onSegmentsUpdate: (segments, meta) => {
       if (meta?.append) appendToLastMessage(segments)

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

@@ -5,13 +5,9 @@ Defines TypeScript types for message processing pipeline operations, including c
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `ParsedChunkAction` | Union type | Discriminated union of all possible chunk parse results (text, tool execution, approvals, metadata, etc.) |
 | `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 |
-| `ChunkProcessor` | Interface | Contract for processing raw `ChunkData` into `ParsedChunkAction` results |
-| `ChunkProcessorOptions` | Interface | Lifecycle callbacks for chunk processing events |
-| `MessageTransformer` | Interface | Contract for transforming raw inputs into `ProcessedMessage` objects |
 | `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 |
@@ -21,29 +17,11 @@ Defines TypeScript types for message processing pipeline operations, including c
 
 ```typescript
 import type {
-  ParsedChunkAction,
   AccumulatorState,
   MessageProcessingOptions,
   StreamState
 } from './processing.types'
 
-// Handling a parsed chunk action via discriminated union
-function handleChunkAction(action: ParsedChunkAction): void {
-  switch (action.action) {
-    case 'text':
-      console.log('Received text:', action.text)
-      break
-    case 'tool_execution':
-      console.log('Tool executing:', action.segment)
-      break
-    case 'approval_batch':
-      console.log('Batch approval request:', action.requestId, action.toolCalls)
-      break
-    case 'error':
-      console.error('Processing error:', action.error, action.details)
-      break
-  }
-}
 
 // Initializing accumulator state
 const state: AccumulatorState = {
@@ -65,4 +43,9 @@ const options: MessageProcessingOptions = {
     logRejection(requestId)
   }
 }
-```
+```
+
+> 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

@@ -5,7 +5,6 @@ Barrel export module that consolidates and re-exports all message processing, ch
 
 | Category | Exports |
 |----------|---------|
-| **Chunk Parsing** | `parseChunkToAction`, `isControlChunk`, `isErrorChunk`, `isMetadataChunk`, `extractTextFromChunk` |
 | **Message Accumulation** | `MessageSegmentAccumulator`, `createMessageSegmentAccumulator`, `AccumulatorCallbacks` |
 | **Historical Messages** | `processHistoricalMessages`, `extractErrorMessages`, `processHistoricalMessagesWithErrors` |
 | **Chat Navigation** | `handleChatNavClick`, `resolveExternalNavigation`, `decideNewTab`, `computeIsNewTab`, `buildAnchorProps` |
@@ -20,7 +19,6 @@ Barrel export module that consolidates and re-exports all message processing, ch
 
 ```typescript
 import {
-  parseChunkToAction,
   createMessageSegmentAccumulator,
   handleChatNavClick,
   getChatProxyAuth,
@@ -30,9 +28,6 @@ import {
   getStatusColorScheme,
 } from '@flamingo/chat-utils'
 
-// Parse a streaming chunk from the AI response
-const action = parseChunkToAction(rawChunk)
-
 // Accumulate streamed message segments
 const accumulator = createMessageSegmentAccumulator({
   onSegmentComplete: (segment) => console.log('Segment:', segment),

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

@@ -0,0 +1,418 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`extractErrorMessages / processHistoricalMessagesWithErrors — golden > extractErrorMessages surfaces ERROR rows as standalone error-role messages 1`] = `
+[
+  {
+    "assistantType": "mingo",
+    "avatar": undefined,
+    "content": "Agent crashed",
+    "id": "a5-error",
+    "name": "Mingo AI",
+    "role": "error",
+    "timestamp": 2026-07-19T09:04:00.000Z,
+  },
+]
+`;
+
+exports[`extractErrorMessages / processHistoricalMessagesWithErrors — golden > processHistoricalMessagesWithErrors output parity on the same corpus (snapshot) 1`] = `
+{
+  "escalatedApprovals": [],
+  "messages": [
+    {
+      "authorType": "user",
+      "avatar": undefined,
+      "content": "diagnose this device please",
+      "contextItems": [
+        {
+          "id": "dev-1",
+          "label": "dev-1",
+          "type": "device",
+        },
+      ],
+      "id": "u1",
+      "name": "You",
+      "role": "user",
+      "streamSeq": 10,
+      "timestamp": 2026-07-19T09:00:00.000Z,
+    },
+    {
+      "assistantType": "mingo",
+      "authorType": "mingo",
+      "avatar": "/avatars/mingo.png",
+      "content": [
+        {
+          "text": "Checking device state… looks like disk pressure.",
+          "type": "thinking",
+        },
+        {
+          "text": "The device is low on disk. ",
+          "type": "text",
+        },
+        {
+          "data": {
+            "integratedToolType": "TACTICAL_RMM",
+            "parameters": {
+              "script": "cleanup.sh",
+            },
+            "result": "Freed 2.3 GB",
+            "success": true,
+            "toolExecutionRequestId": "exec-1",
+            "toolFunction": "run_script",
+            "toolTitle": "Run cleanup script",
+            "type": "EXECUTED_TOOL",
+          },
+          "type": "tool_execution",
+        },
+        {
+          "text": "Cleanup done.",
+          "type": "text",
+        },
+      ],
+      "id": "a2",
+      "name": "Mingo AI",
+      "role": "assistant",
+      "streamSeq": 20,
+      "timestamp": 2026-07-19T09:00:05.000Z,
+    },
+    {
+      "authorType": "admin",
+      "avatar": "/avatars/jane.png",
+      "content": "please restart the broker",
+      "id": "u2",
+      "name": "Jane Admin",
+      "role": "user",
+      "timestamp": 2026-07-19T09:01:00.000Z,
+    },
+    {
+      "assistantType": "mingo",
+      "authorType": "mingo",
+      "avatar": "/avatars/mingo.png",
+      "content": [
+        {
+          "text": "I need approval to restart it.",
+          "type": "text",
+        },
+        {
+          "data": {
+            "approvalType": "CLIENT",
+            "command": "systemctl restart nats",
+            "explanation": "Restart the message broker",
+            "requestId": "req-1",
+          },
+          "onApprove": undefined,
+          "onReject": undefined,
+          "status": "approved",
+          "type": "approval_request",
+        },
+        {
+          "data": {
+            "approvalRequestId": "batch-1",
+            "approvalType": "CLIENT",
+            "executions": {
+              "exec-a": {
+                "result": "Ticket #77 created",
+                "status": "done",
+                "success": true,
+              },
+            },
+            "toolCalls": [
+              {
+                "approvalType": "CLIENT",
+                "requiresApproval": true,
+                "toolCallArguments": {
+                  "subject": "Printer down",
+                },
+                "toolExecutionRequestId": "exec-a",
+                "toolName": "create_ticket",
+                "toolTitle": "Create ticket",
+              },
+              {
+                "requiresApproval": false,
+                "toolExecutionRequestId": "exec-b",
+                "toolName": "read_kb",
+              },
+            ],
+          },
+          "onApprove": undefined,
+          "onReject": undefined,
+          "resolvedByName": "Alice Client",
+          "status": "approved",
+          "type": "approval_batch",
+        },
+      ],
+      "id": "a4",
+      "name": "Mingo AI",
+      "role": "assistant",
+      "streamSeq": 30,
+      "timestamp": 2026-07-19T09:01:05.000Z,
+    },
+    {
+      "authorType": "system",
+      "content": "",
+      "id": "s1",
+      "name": "Technician joined the chat",
+      "role": "user",
+      "streamSeq": 40,
+      "timestamp": 2026-07-19T09:03:00.000Z,
+    },
+    {
+      "assistantType": "mingo",
+      "authorType": "mingo",
+      "avatar": "/avatars/mingo.png",
+      "content": [
+        {
+          "text": "Attempting one more thing… ",
+          "type": "text",
+        },
+        {
+          "details": "boom",
+          "title": "Agent crashed",
+          "type": "error",
+        },
+      ],
+      "id": "a5",
+      "name": "Mingo AI",
+      "role": "assistant",
+      "timestamp": 2026-07-19T09:04:00.000Z,
+    },
+  ],
+}
+`;
+
+exports[`processHistoricalMessages — golden corpus > chatTypeFilter drops rows of other chat types 1`] = `
+[
+  {
+    "authorType": "user",
+    "avatar": undefined,
+    "content": "visible",
+    "id": "u1",
+    "name": "You",
+    "role": "user",
+    "timestamp": 2026-07-19T09:00:00.000Z,
+  },
+]
+`;
+
+exports[`processHistoricalMessages — golden corpus > owner-type author resolution: CLIENT vs ADMIN vs ADMIN-without-name display names/avatars 1`] = `
+[
+  {
+    "authorType": "user",
+    "avatar": undefined,
+    "content": "from client",
+    "id": "u-client",
+    "name": "You",
+    "role": "user",
+    "timestamp": 2026-07-19T09:00:00.000Z,
+  },
+  {
+    "authorType": "admin",
+    "avatar": "/a.png",
+    "content": "from named admin",
+    "id": "u-admin-named",
+    "name": "Jane Admin",
+    "role": "user",
+    "timestamp": 2026-07-19T09:00:01.000Z,
+  },
+  {
+    "authorType": "admin",
+    "avatar": undefined,
+    "content": "from anonymous admin",
+    "id": "u-admin-anon",
+    "name": "Admin",
+    "role": "user",
+    "timestamp": 2026-07-19T09:00:02.000Z,
+  },
+]
+`;
+
+exports[`processHistoricalMessages — golden corpus > processes the full recorded dialog (snapshot) 1`] = `
+{
+  "escalatedApprovals": [],
+  "messages": [
+    {
+      "authorType": "user",
+      "avatar": undefined,
+      "content": "diagnose this device please",
+      "contextItems": [
+        {
+          "id": "dev-1",
+          "label": "dev-1",
+          "type": "device",
+        },
+      ],
+      "id": "u1",
+      "name": "You",
+      "role": "user",
+      "streamSeq": 10,
+      "timestamp": 2026-07-19T09:00:00.000Z,
+    },
+    {
+      "assistantType": "mingo",
+      "authorType": "mingo",
+      "avatar": "/avatars/mingo.png",
+      "content": [
+        {
+          "text": "Checking device state… looks like disk pressure.",
+          "type": "thinking",
+        },
+        {
+          "text": "The device is low on disk. ",
+          "type": "text",
+        },
+        {
+          "data": {
+            "integratedToolType": "TACTICAL_RMM",
+            "parameters": {
+              "script": "cleanup.sh",
+            },
+            "result": "Freed 2.3 GB",
+            "success": true,
+            "toolExecutionRequestId": "exec-1",
+            "toolFunction": "run_script",
+            "toolTitle": "Run cleanup script",
+            "type": "EXECUTED_TOOL",
+          },
+          "type": "tool_execution",
+        },
+        {
+          "text": "Cleanup done.",
+          "type": "text",
+        },
+      ],
+      "id": "a2",
+      "name": "Mingo AI",
+      "role": "assistant",
+      "streamSeq": 20,
+      "timestamp": 2026-07-19T09:00:05.000Z,
+    },
+    {
+      "authorType": "admin",
+      "avatar": "/avatars/jane.png",
+      "content": "please restart the broker",
+      "id": "u2",
+      "name": "Jane Admin",
+      "role": "user",
+      "timestamp": 2026-07-19T09:01:00.000Z,
+    },
+    {
+      "assistantType": "mingo",
+      "authorType": "mingo",
+      "avatar": "/avatars/mingo.png",
+      "content": [
+        {
+          "text": "I need approval to restart it.",
+          "type": "text",
+        },
+        {
+          "data": {
+            "approvalType": "CLIENT",
+            "command": "systemctl restart nats",
+            "explanation": "Restart the message broker",
+            "requestId": "req-1",
+          },
+          "onApprove": undefined,
+          "onReject": undefined,
+          "status": "approved",
+          "type": "approval_request",
+        },
+        {
+          "data": {
+            "approvalRequestId": "batch-1",
+            "approvalType": "CLIENT",
+            "executions": {
+              "exec-a": {
+                "result": "Ticket #77 created",
+                "status": "done",
+                "success": true,
+              },
+            },
+            "toolCalls": [
+              {
+                "approvalType": "CLIENT",
+                "requiresApproval": true,
+                "toolCallArguments": {
+                  "subject": "Printer down",
+                },
+                "toolExecutionRequestId": "exec-a",
+                "toolName": "create_ticket",
+                "toolTitle": "Create ticket",
+              },
+              {
+                "requiresApproval": false,
+                "toolExecutionRequestId": "exec-b",
+                "toolName": "read_kb",
+              },
+            ],
+          },
+          "onApprove": undefined,
+          "onReject": undefined,
+          "resolvedByName": "Alice Client",
+          "status": "approved",
+          "type": "approval_batch",
+        },
+      ],
+      "id": "a4",
+      "name": "Mingo AI",
+      "role": "assistant",
+      "streamSeq": 30,
+      "timestamp": 2026-07-19T09:01:05.000Z,
+    },
+    {
+      "authorType": "system",
+      "content": "",
+      "id": "s1",
+      "name": "Technician joined the chat",
+      "role": "user",
+      "streamSeq": 40,
+      "timestamp": 2026-07-19T09:03:00.000Z,
+    },
+    {
+      "assistantType": "mingo",
+      "authorType": "mingo",
+      "avatar": "/avatars/mingo.png",
+      "content": [
+        {
+          "text": "Attempting one more thing… ",
+          "type": "text",
+        },
+        {
+          "details": "boom",
+          "title": "Agent crashed",
+          "type": "error",
+        },
+      ],
+      "id": "a5",
+      "name": "Mingo AI",
+      "role": "assistant",
+      "timestamp": 2026-07-19T09:04:00.000Z,
+    },
+  ],
+}
+`;
+
+exports[`processHistoricalMessages — golden corpus > unresolved single approval is resurrected as a synthetic pending-approvals bubble 1`] = `
+[
+  {
+    "assistantType": "fae",
+    "avatar": undefined,
+    "content": [
+      {
+        "data": {
+          "approvalType": "CLIENT",
+          "command": "reboot server",
+          "explanation": undefined,
+          "requestId": "req-pending",
+        },
+        "onApprove": undefined,
+        "onReject": undefined,
+        "status": "pending",
+        "type": "approval_request",
+      },
+    ],
+    "id": "pending-approvals-1784541600000",
+    "name": "Fae",
+    "role": "assistant",
+    "timestamp": 2026-07-20T10:00:00.000Z,
+  },
+]
+`;