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

package/src/components/chat/index.ts

@@ -74,11 +74,6 @@ export * from './types'
 // Chat hooks
 export * from './hooks'
 
-// Chat stream module — master reducer + dialog store + React wrapper
-// (Phase 3 of the chat unification; ONE accumulation path for SSE + NATS
-// + history replay).
-export * from './stream'
-
 // Chat utilities
 export * from './utils'
 

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/markdown/simple-markdown-renderer"
+import { SimpleMarkdownRenderer } from "../ui/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

@@ -9,6 +9,7 @@ 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 |
@@ -16,6 +17,7 @@ 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.
@@ -29,7 +31,7 @@ Defines TypeScript interfaces for API interactions and React hook contracts used
 ## Usage Example
 
 ```typescript
-const options: ChatStreamReducerOptions = {
+const options: UseRealtimeChunkProcessorOptions = {
   callbacks: {
     onSegmentsUpdate: (segments, meta) => {
       if (meta?.append) appendToLastMessage(segments)

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

@@ -5,9 +5,13 @@ 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 |
@@ -17,11 +21,29 @@ 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 = {
@@ -43,9 +65,4 @@ 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,12 +213,79 @@ export interface RealtimeChunkCallbacks {
   onDialogClosed?: () => void
 }
 
-// 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`.
+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[] }
+  >
+}
 
 // ========== API Request Types ==========
 

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

@@ -3,14 +3,37 @@
  * Contains types for message parsing, accumulation, and processing
  */
 
-import type { MessageSegment, PendingToolCallData, ExecutingToolState } from './message.types'
+import type { MessageSegment, ProcessedMessage, ToolExecutionSegment, TokenUsageData, PendingToolCallData, ExecutingToolState } from './message.types'
 import type { ChatApprovalStatus, AssistantType } from './chat.types'
-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`.
+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' }
 
 // ========== Accumulator State ==========
 
@@ -58,13 +81,31 @@ export interface MessageProcessingOptions {
   batchApprovalsEnabled?: boolean
 }
 
-// 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.
+// ========== 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
+}
 
 // ========== 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/.chunk-parser.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 637d22f77dbdb02b04013632095ddfdb -->
+Utilities for parsing raw NATS message chunks into typed, structured action objects consumed by the AI message pipeline.
+
+## Key Components
+
+### `parseChunkToAction(chunk)`
+Core export that maps a raw `ChunkData` object to a `ParsedChunkAction` union type. Uses a `switch` on `MESSAGE_TYPE` to handle all supported message variants:
+
+| Action | Description |
+|---|---|
+| `message_start` / `message_end` | Lifecycle control signals |
+| `metadata` | AI model/provider info |
+| `text` / `thinking` / `system` | Content streaming |
+| `tool_execution` | Tool start/completion events |
+| `approval_request` / `approval_batch` | Single or multi-tool approval flows |
+| `approval_result` | Approval outcome |
+| `token_usage` | Token consumption stats |
+| `context_compaction_start/end` | Context window management |
+| `direct_message` | Owner-attributed messages |
+| `dialog_closed` | Session termination |
+
+Returns `null` for unknown or malformed chunks.
+
+### `normalizeToolCalls(raw)` *(internal)*
+Coerces an unknown array into `PendingToolCallData[]`, safely defaulting missing fields and enforcing correct types.
+
+### Guard Helpers
+Lightweight boolean checks for common chunk classifications:
+
+- `isControlChunk(chunk)` — start/end signals
+- `isErrorChunk(chunk)` — error type
+- `isMetadataChunk(chunk)` — AI metadata
+- `extractTextFromChunk(chunk)` — returns text content or `null`
+
+## Usage Example
+
+```typescript
+import { parseChunkToAction, isErrorChunk } from './chunk-parser'
+
+// Incoming NATS message payload
+const raw = { type: 'TEXT', text: 'Hello from Mingo AI' }
+
+if (isErrorChunk(raw)) {
+  console.error('Stream error received')
+}
+
+const action = parseChunkToAction(raw)
+if (action?.action === 'text') {
+  renderText(action.text) // "Hello from Mingo AI"
+}
+```

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

@@ -5,6 +5,7 @@ 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` |
@@ -19,6 +20,7 @@ Barrel export module that consolidates and re-exports all message processing, ch
 
 ```typescript
 import {
+  parseChunkToAction,
   createMessageSegmentAccumulator,
   handleChatNavClick,
   getChatProxyAuth,
@@ -28,6 +30,9 @@ 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/chunk-parser.ts

@@ -0,0 +1,255 @@
+/**
+ * Utilities for parsing NATS chunks into structured actions
+ */
+
+import { MESSAGE_TYPE, type ChunkData, type ParsedChunkAction, type ToolExecutionSegment, type PendingToolCallData } from '../types'
+
+function normalizeToolCalls(raw: unknown): PendingToolCallData[] {
+  if (!Array.isArray(raw)) return []
+  return raw
+    .filter((item): item is Record<string, any> => !!item && typeof item === 'object')
+    .map((item) => ({
+      toolExecutionRequestId: String(item.toolExecutionRequestId ?? ''),
+      toolName: String(item.toolName ?? ''),
+      toolTitle: typeof item.toolTitle === 'string' ? item.toolTitle : undefined,
+      toolExplanation: typeof item.toolExplanation === 'string' ? item.toolExplanation : undefined,
+      toolType: typeof item.toolType === 'string' ? item.toolType : undefined,
+      requiresApproval: item.requiresApproval === true,
+      approvalType: typeof item.approvalType === 'string' ? item.approvalType : null,
+      toolCallArguments:
+        item.toolCallArguments && typeof item.toolCallArguments === 'object'
+          ? (item.toolCallArguments as Record<string, any>)
+          : null,
+    }))
+}
+
+/**
+ * Parse a raw NATS chunk into a structured action
+ */
+export function parseChunkToAction(chunk: unknown): ParsedChunkAction | null {
+  if (!chunk || typeof chunk !== 'object') return null
+  
+  const data = chunk as ChunkData
+  const type = String(data.type || '')
+
+  switch (type) {
+    case MESSAGE_TYPE.MESSAGE_START:
+      return { action: 'message_start' }
+      
+    case MESSAGE_TYPE.MESSAGE_END:
+      return { action: 'message_end' }
+      
+    case MESSAGE_TYPE.AI_METADATA: {
+      const providerName = data.providerName || data.provider
+      if (typeof data.modelName === 'string' && typeof providerName === 'string') {
+        return {
+          action: 'metadata',
+          modelDisplayName: data.modelDisplayName,
+          modelName: data.modelName,
+          providerName,
+          contextWindow: typeof data.contextWindow === 'number' ? data.contextWindow : 0,
+        }
+      }
+      return null
+    }
+    
+    case MESSAGE_TYPE.TEXT:
+      if (typeof data.text === 'string') {
+        return { action: 'text', text: data.text }
+      }
+      return null
+
+    case MESSAGE_TYPE.THINKING:
+      if (typeof data.text === 'string') {
+        return { action: 'thinking', text: data.text }
+      }
+      return null
+
+    case MESSAGE_TYPE.EXECUTING_TOOL:
+      return {
+        action: 'tool_execution',
+        segment: {
+          type: 'tool_execution',
+          data: {
+            type: 'EXECUTING_TOOL',
+            integratedToolType: data.integratedToolType || '',
+            toolFunction: data.toolFunction || '',
+            toolTitle: typeof data.title === 'string' ? data.title : undefined,
+            parameters: data.parameters,
+            toolExecutionRequestId: typeof data.toolExecutionRequestId === 'string' ? data.toolExecutionRequestId : undefined,
+          }
+        }
+      }
+
+    case MESSAGE_TYPE.EXECUTED_TOOL:
+      return {
+        action: 'tool_execution',
+        segment: {
+          type: 'tool_execution',
+          data: {
+            type: 'EXECUTED_TOOL',
+            integratedToolType: data.integratedToolType || '',
+            toolFunction: data.toolFunction || '',
+            toolTitle: typeof data.title === 'string' ? data.title : undefined,
+            parameters: data.parameters,
+            result: data.result,
+            success: data.success,
+            toolExecutionRequestId: typeof data.toolExecutionRequestId === 'string' ? data.toolExecutionRequestId : undefined,
+          }
+        }
+      }
+      
+    case MESSAGE_TYPE.APPROVAL_REQUEST: {
+      const requestId = data.approvalRequestId || data.approval_request_id || ''
+      const approvalType = data.approvalType || 'USER'
+      const toolCalls = normalizeToolCalls(data.toolCalls)
+
+      if (toolCalls.length > 0) {
+        return {
+          action: 'approval_batch',
+          requestId,
+          approvalType,
+          toolCalls,
+        }
+      }
+
+      return {
+        action: 'approval_request',
+        requestId,
+        command: data.command || '',
+        explanation: data.explanation,
+        approvalType,
+      }
+    }
+      
+    case MESSAGE_TYPE.APPROVAL_RESULT: {
+      // The realtime NATS chunk carries the resolver's name as `displayName`; the
+      // persisted GraphQL message exposes the same value as `resolvedByName`. Accept
+      // either so realtime and history-replay render "by {name}" identically.
+      const resolvedByName =
+        typeof data.resolvedByName === 'string'
+          ? data.resolvedByName
+          : typeof data.displayName === 'string'
+            ? data.displayName
+            : undefined
+      return {
+        action: 'approval_result',
+        requestId: data.approvalRequestId || data.approval_request_id || '',
+        approved: data.approved === true,
+        approvalType: data.approvalType || 'CLIENT',
+        resolvedByName,
+      }
+    }
+      
+    case MESSAGE_TYPE.ERROR:
+      return {
+        action: 'error',
+        error: data.error || 'An error occurred',
+        details: data.details,
+      }
+      
+    case MESSAGE_TYPE.MESSAGE_REQUEST:
+      return {
+        action: 'message_request',
+        text: String(data.text || ''),
+        ownerType: typeof data.ownerType === 'string' ? data.ownerType : undefined,
+        displayName: typeof data.displayName === 'string' ? data.displayName : undefined,
+        userId: typeof data.userId === 'string' ? data.userId : undefined,
+        // Entity-context refs the user attached to this message (backend
+        // `MESSAGE_REQUEST` chunk → `contextItems: [{ type, id }]`). The wire
+        // shape carries no label; the host resolves display text + icon. `label`
+        // is REQUIRED on `ChatContextItem`, so fall back to the id (same as the
+        // historical path in `process-historical-messages.ts`) — keeps both
+        // message sources producing an identical shape.
+        contextItems: Array.isArray(data.contextItems)
+          ? (data.contextItems as Array<{ type?: unknown; id?: unknown }>)
+              .filter((it) => typeof it?.type === 'string' && typeof it?.id === 'string')
+              .map((it) => ({ type: it.type as string, id: it.id as string, label: it.id as string }))
+          : undefined,
+      }
+
+    case MESSAGE_TYPE.TOKEN_USAGE:
+      return {
+        action: 'token_usage',
+        data: {
+          inputTokensSize: data.inputTokensSize ?? 0,
+          outputTokensSize: data.outputTokensSize ?? 0,
+          totalTokensSize: data.totalTokensSize ?? 0,
+          contextSize: data.contextSize ?? 0,
+        },
+      }
+
+    case MESSAGE_TYPE.CONTEXT_COMPACTION_START:
+      return { action: 'context_compaction_start' }
+
+    case MESSAGE_TYPE.CONTEXT_COMPACTION_END:
+      return {
+        action: 'context_compaction_end',
+        summary: typeof data.text === 'string' ? data.text : undefined,
+      }
+
+    case MESSAGE_TYPE.SYSTEM:
+      if (typeof data.text === 'string') {
+        return { action: 'system', text: data.text }
+      }
+      return null
+
+    case MESSAGE_TYPE.DIRECT_MESSAGE:
+      if (typeof data.text === 'string') {
+        return {
+          action: 'direct_message',
+          text: data.text,
+          ownerType: typeof data.ownerType === 'string' ? data.ownerType : undefined,
+          displayName: typeof data.displayName === 'string' ? data.displayName : undefined,
+          userId: typeof data.userId === 'string' ? data.userId : undefined,
+        }
+      }
+      return null
+
+    case MESSAGE_TYPE.DIALOG_CLOSED:
+      return { action: 'dialog_closed' }
+
+    default:
+      return null
+  }
+}
+
+/**
+ * Check if a chunk represents a control message (start/end)
+ */
+export function isControlChunk(chunk: unknown): boolean {
+  if (!chunk || typeof chunk !== 'object') return false
+  const data = chunk as ChunkData
+  const type = String(data.type || '')
+  return type === MESSAGE_TYPE.MESSAGE_START || type === MESSAGE_TYPE.MESSAGE_END
+}
+
+/**
+ * Check if a chunk represents an error
+ */
+export function isErrorChunk(chunk: unknown): boolean {
+  if (!chunk || typeof chunk !== 'object') return false
+  const data = chunk as ChunkData
+  return data.type === MESSAGE_TYPE.ERROR
+}
+
+/**
+ * Check if a chunk represents metadata
+ */
+export function isMetadataChunk(chunk: unknown): boolean {
+  if (!chunk || typeof chunk !== 'object') return false
+  const data = chunk as ChunkData
+  return data.type === MESSAGE_TYPE.AI_METADATA
+}
+
+/**
+ * Extract text content from a chunk if it's a text chunk
+ */
+export function extractTextFromChunk(chunk: unknown): string | null {
+  if (!chunk || typeof chunk !== 'object') return null
+  const data = chunk as ChunkData
+  if (data.type === MESSAGE_TYPE.TEXT && typeof data.text === 'string') {
+    return data.text
+  }
+  return null
+}