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

package/src/components/chat/utils/chunk-parser.ts

@@ -0,0 +1,262 @@
+/**
+ * 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.GUIDE:
+      if (typeof data.text === 'string') {
+        return { action: 'guide', 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,
+            toolExplanation: typeof data.toolExplanation === 'string' ? data.toolExplanation : 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
+}

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

@@ -9,18 +9,6 @@ import type {
   PendingApproval,
   ExecutingToolState,
 } from '../types'
-import type { InitializeExtras } from '../stream/chat-stream-reducer'
-
-/**
- * What the realtime accumulator needs to RESUME an unfinished turn.
- *
- * DERIVED, not restated: this is exactly the reducer's `InitializeExtras`
- * minus `escalatedApprovals` (which only the live stream can produce — it has
- * no historical representation to extract). Hosts pass the result straight
- * into `reducer.initializeWithState(messages, extras)`, so the two must not
- * drift; a structural coincidence is not a contract.
- */
-export type IncompleteMessageState = Omit<InitializeExtras, 'escalatedApprovals'>
 
 /**
  * Extract incomplete message state from the last historical assistant message
@@ -28,7 +16,11 @@ export type IncompleteMessageState = Omit<InitializeExtras, 'escalatedApprovals'
  */
 export function extractIncompleteMessageState(
   lastMessage: ProcessedMessage | undefined
-): IncompleteMessageState | undefined {
+): {
+  existingSegments?: MessageSegment[]
+  pendingApprovals?: Map<string, PendingApproval>
+  executingTools?: Map<string, ExecutingToolState>
+} | undefined {
   if (!lastMessage || lastMessage.role !== 'assistant' || typeof lastMessage.content === 'string') {
     return undefined
   }
@@ -100,54 +92,4 @@ export function extractIncompleteMessageState(
     pendingApprovals: pendingApprovals.size > 0 ? pendingApprovals : undefined,
     executingTools: executingTools.size > 0 ? executingTools : undefined,
   }
-}
-
-/**
- * THREAD-level generalization of `extractIncompleteMessageState`: given a
- * processed thread, look at the TRAILING RUN of consecutive assistant
- * messages (not just the very last row), flatten it to one segment list, and
- * ask the single-message extractor whether that tail is unfinished.
- *
- * Why the run and not the last row: the backend can split one logical turn
- * across several assistant messages (a preamble bubble, then the approval
- * card, then the continuation). The unfinished artifact — a pending approval,
- * an EXECUTING_TOOL with no result, an open compaction — can therefore sit in
- * an EARLIER bubble of the same trailing run, and a last-row-only check
- * reports "complete" while the turn is very much still in flight.
- *
- * SSOT for every "is the tail incomplete?" question — the NATS adapter (which
- * used to inline the single-row check) and hosts replaying a stored thread
- * both call this instead of re-deriving the walk.
- *
- * A trailing non-assistant row (user / error) means the last turn closed →
- * `undefined`.
- */
-export function extractIncompleteTailState(
-  messages: readonly ProcessedMessage[] | undefined,
-): IncompleteMessageState | undefined {
-  if (!messages || messages.length === 0) return undefined
-
-  // Walk back over the trailing consecutive assistant run.
-  let start = messages.length
-  while (start > 0 && messages[start - 1]?.role === 'assistant') start -= 1
-  if (start === messages.length) return undefined
-
-  const segments: MessageSegment[] = []
-  for (let i = start; i < messages.length; i += 1) {
-    const content = messages[i]?.content
-    // A string-content assistant row is a plain-text bubble with nothing to
-    // resume; skip it rather than aborting — a later row in the same run may
-    // still hold the unfinished segment.
-    if (Array.isArray(content)) segments.push(...(content as MessageSegment[]))
-  }
-  if (segments.length === 0) return undefined
-
-  // Reuse the single-message extractor verbatim by handing it a synthetic
-  // assistant row carrying the flattened run — one incompleteness rule set,
-  // not two.
-  return extractIncompleteMessageState({
-    ...messages[messages.length - 1],
-    role: 'assistant',
-    content: segments,
-  } as ProcessedMessage)
 }

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

@@ -3,9 +3,14 @@
  * Export all utilities for processing chat messages
  */
 
-// NOTE: NATS chunk parsing lives in `chat-protocol/nats-decoder`
-// (`decodeNatsChunk`) — the legacy `chunk-parser` module was deleted once the
-// reducer became the single reading path.
+// Chunk parsing utilities
+export {
+  parseChunkToAction,
+  isControlChunk,
+  isErrorChunk,
+  isMetadataChunk,
+  extractTextFromChunk,
+} from './chunk-parser'
 
 // Segment accumulator
 export {
@@ -19,13 +24,11 @@ export {
   processHistoricalMessages,
   extractErrorMessages,
   processHistoricalMessagesWithErrors,
-  decodeHistoricalMessageData,
 } from './process-historical-messages'
 
 // Incomplete message state extraction
 export {
   extractIncompleteMessageState,
-  extractIncompleteTailState,
 } from './extract-incomplete-message-state'
 
 // History <-> realtime reconciliation

package/src/components/chat/utils/message-segment-accumulator.ts

@@ -139,6 +139,22 @@ export class MessageSegmentAccumulator {
     return this.getSegments()
   }
 
+  /**
+   * Append guide text to the current message.
+   * If the last segment is guide, append to it; otherwise start a new guide segment.
+   */
+  appendGuide(text: string): MessageSegment[] {
+    const lastSegment = this.segments[this.segments.length - 1]
+
+    if (lastSegment && lastSegment.type === 'guide') {
+      this.segments[this.segments.length - 1] = { type: 'guide', text: lastSegment.text + text }
+    } else {
+      this.segments.push({ type: 'guide', text })
+    }
+
+    return this.getSegments()
+  }
+
   /**
    * Add a tool execution segment.
    *
@@ -516,6 +532,9 @@ export class MessageSegmentAccumulator {
         case 'thinking':
           if (segment.text) this.appendThinking(segment.text)
           break
+        case 'guide':
+          if (segment.text) this.appendGuide(segment.text)
+          break
         case 'tool_execution':
           this.addToolExecution(segment)
           break