@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/components/chat/hooks/use-nats-dialog-subscription.ts

@@ -1,35 +1,22 @@
 'use client'
 
-import { useCallback, useEffect, useRef, useState } from 'react'
-import { createNatsClient, type NatsClient, type NatsSubscriptionHandle } from '../../../nats'
+import { useEffect, useRef, useState } from 'react'
+import {
+  acquireClient as acquireSharedClient,
+  releaseClient as releaseSharedClient,
+  startConnectionLifecycle,
+  type NatsClient,
+  type NatsStatus,
+  type NatsSubscriptionHandle,
+  type SharedConnection,
+} from '../../../nats'
 import {
   type NatsConnectionSource,
   type NatsMessageType,
   type UseNatsDialogSubscriptionOptions,
   type UseNatsDialogSubscriptionReturn,
-  NETWORK_CONFIG,
 } from '../types'
 
-type SharedConnection = {
-  wsUrl: string
-  client: NatsClient
-  connectPromise: Promise<void> | null
-  refCount: number
-  closeTimer: ReturnType<typeof setTimeout> | null
-  retryTimer: ReturnType<typeof setTimeout> | null
-}
-
-let shared: SharedConnection | null = null
-
-/**
- * Hook for managing NATS dialog subscriptions.
- * 
- * This hook handles:
- * - Connecting to NATS WebSocket
- * - Subscribing to dialog topics (message and/or admin-message)
- * - Reconnection and error handling
- * - Shared connection management
- */
 export function useNatsDialogSubscription({
   enabled,
   dialogId,
@@ -49,8 +36,7 @@ export function useNatsDialogSubscription({
   
   const clientRef = useRef<NatsClient | null>(null)
   const subscriptionRefs = useRef<Map<NatsMessageType, NatsSubscriptionHandle | null>>(new Map())
-  
-  // Stable refs for callbacks
+
   const onEventRef = useRef(onEvent)
   useEffect(() => {
     onEventRef.current = onEvent
@@ -88,66 +74,24 @@ export function useNatsDialogSubscription({
     reconnectionBackoffRef.current = reconnectionBackoff
   }, [reconnectionBackoff])
 
-  const acquireClient = useCallback((url: string): SharedConnection => {
-    if (shared?.wsUrl !== url) {
-      // Close existing connection if URL changed
-      if (shared) {
-        shared.closeTimer && clearTimeout(shared.closeTimer)
-        const old = shared
-        shared = null
-        void old.client.close().catch(() => {})
-      }
-      
-      const { name = 'openframe-frontend', user = 'machine', pass = '' } = clientConfig
-      
-      const client = createNatsClient({
-        servers: url,
-        name,
-        user,
-        pass,
-        connectTimeoutMs: NETWORK_CONFIG.CONNECT_TIMEOUT_MS,
-        reconnect: false,
-        pingIntervalMs: NETWORK_CONFIG.PING_INTERVAL_MS,
-        maxPingOut: NETWORK_CONFIG.MAX_PING_OUT,
-      })
-      shared = { wsUrl: url, client, connectPromise: null, refCount: 0, closeTimer: null, retryTimer: null }
-    }
-
-    shared.refCount += 1
-    shared.closeTimer && clearTimeout(shared.closeTimer)
-    shared.closeTimer = null
-    return shared
+  const clientConfigRef = useRef(clientConfig)
+  useEffect(() => {
+    clientConfigRef.current = clientConfig
   }, [clientConfig])
 
-  const releaseClient = useCallback((url: string) => {
-    if (!shared || shared.wsUrl !== url) return
-    
-    shared.refCount = Math.max(0, shared.refCount - 1)
-    if (shared.refCount > 0) return
-
-    shared.closeTimer = setTimeout(() => {
-      const s = shared
-      shared = null
-      if (s) {
-        if (s.retryTimer) {
-          clearTimeout(s.retryTimer)
-          s.retryTimer = null
-        }
-        void s.client.close().catch(() => {})
-      }
-    }, NETWORK_CONFIG.SHARED_CLOSE_DELAY_MS)
-  }, [])
-
-  // Store the current WebSocket URL to prevent unnecessary reconnections
   const currentWsUrlRef = useRef<string>('')
-  
-  // Connection effect
+
+  // Resolve the URL synchronously each render so the effect's dep is the URL string
+  // itself, not the (often inline-allocated) getNatsWsUrl callback identity. Without
+  // this the effect re-runs on every render that produces a new callback identity —
+  // e.g. every silent token rotation when `useNatsAppConfig` rebuilds getWsUrl —
+  // tearing the WS down and reacquiring even though the resolved URL hasn't changed.
+  const wsUrl = getNatsWsUrl()
+
   useEffect(() => {
-    const wsUrl = getNatsWsUrl()
     if (!enabled || !wsUrl) {
-      // Clean up if disabled or no URL
       if (currentWsUrlRef.current && clientRef.current) {
-        releaseClient(currentWsUrlRef.current)
+        releaseSharedClient(currentWsUrlRef.current)
         clientRef.current = null
         currentWsUrlRef.current = ''
         setIsConnected(false)
@@ -160,159 +104,81 @@ export function useNatsDialogSubscription({
       return
     }
 
-    // Clean up existing connection if URL changed
     if (currentWsUrlRef.current && currentWsUrlRef.current !== wsUrl && clientRef.current) {
-      releaseClient(currentWsUrlRef.current)
+      releaseSharedClient(currentWsUrlRef.current)
       clientRef.current = null
       setIsConnected(false)
     }
 
     currentWsUrlRef.current = wsUrl
-    const sharedConn = acquireClient(wsUrl)
+    const cfg = clientConfigRef.current
+    const sharedConn = acquireSharedClient(wsUrl, {
+      name: cfg.name ?? 'openframe-frontend',
+      user: cfg.user ?? 'machine',
+      pass: cfg.pass ?? '',
+    })
     const client = sharedConn.client
 
     clientRef.current = client
-    setIsConnected(false)
-
-    let closed = false
-    let retryAttempt = 0
-
-    function scheduleRetry() {
-      if (closed) return
-      if (shared !== sharedConn) return
-
-      if (sharedConn.retryTimer) {
-        clearTimeout(sharedConn.retryTimer)
-        sharedConn.retryTimer = null
-      }
-
-      const cfg = reconnectionBackoffRef.current ?? {}
-      const fastRetries = cfg.fastRetries ?? 0
-      const fastDelay = cfg.fastRetryDelayMs ?? NETWORK_CONFIG.RETRY_INITIAL_DELAY_MS
-      const baseDelay = cfg.initialDelayMs ?? NETWORK_CONFIG.RETRY_INITIAL_DELAY_MS
-      const maxDelay = cfg.maxDelayMs ?? NETWORK_CONFIG.RETRY_MAX_DELAY_MS
-      const multiplier = cfg.multiplier ?? NETWORK_CONFIG.RETRY_BACKOFF_MULTIPLIER
-
-      const delay = retryAttempt < fastRetries
-        ? fastDelay
-        : Math.min(baseDelay * (multiplier ** (retryAttempt - fastRetries)), maxDelay)
-      const jitteredDelay = delay * (0.5 + Math.random() * 0.5)
-      retryAttempt++
-
-      sharedConn.retryTimer = setTimeout(async () => {
-        sharedConn.retryTimer = null
-        if (closed) return
-        if (shared !== sharedConn) return
-
-        try {
-          await onBeforeReconnectRef.current?.()
-        } catch {
-          // Token refresh failed; still try to reconnect
-        }
-
-        if (closed) return
-        if (shared !== sharedConn) return
-
-        const freshUrl = getNatsWsUrlRef.current()
-        if (freshUrl !== wsUrl) return
+    setIsConnected(client.isConnected())
 
+    const tearDownSubscriptions = () => {
+      subscriptionRefs.current.forEach((sub) => {
         try {
-          sharedConn.connectPromise = null
-          sharedConn.connectPromise = client.connect()
-          await sharedConn.connectPromise
-          if (!closed && shared === sharedConn) {
-            retryAttempt = 0
-            setIsConnected(true)
-          }
+          sub?.unsubscribe()
         } catch {
-          sharedConn.connectPromise = null
-          if (!closed && shared === sharedConn) {
-            scheduleRetry()
-          }
+          // ignore
         }
-      }, jitteredDelay)
+      })
+      subscriptionRefs.current.clear()
+      lastSubscribedDialogIdRef.current = null
+      abortControllerRef.current?.abort()
+      abortControllerRef.current = null
     }
 
-    const unsubscribeStatus = client.onStatus((event) => {
-      const connected = event.status === 'connected'
-      const disconnected = ['closed', 'disconnected', 'error'].includes(event.status)
-      if (connected) {
-        setIsConnected(true)
-        if (hadConnectionBeforeRef.current) {
-          setReconnectionCount(c => c + 1)
-        }
-        hadConnectionBeforeRef.current = true
-        retryAttempt = 0
-        onConnectRef.current?.()
-      }
-      if (disconnected) {
-        setIsConnected(false)
-        setIsSubscribed(false)
-        
-        subscriptionRefs.current.forEach((sub) => {
-          try {
-            sub?.unsubscribe()
-          } catch {
-            // ignore
-          }
-        })
-        subscriptionRefs.current.clear()
-        lastSubscribedDialogIdRef.current = null
-        abortControllerRef.current?.abort()
-        abortControllerRef.current = null
-
-        onDisconnectRef.current?.()
-        scheduleRetry()
-      }
-    })
-
-    ;(async () => {
-      try {
-        sharedConn.connectPromise ||= client.connect()
-        await sharedConn.connectPromise
-        if (!closed) {
+    // This hook treats 'error' as a disconnect (pre-existing behaviour); JetStream's
+    // hook does not — it skips retry on protocol errors.
+    const isDisconnectStatus = (status: NatsStatus) =>
+      status === 'closed' || status === 'disconnected' || status === 'error'
+
+    const lifecycle = startConnectionLifecycle({
+      conn: sharedConn,
+      wsUrl,
+      onBeforeReconnect: () => onBeforeReconnectRef.current?.(),
+      backoff: reconnectionBackoffRef.current,
+      getFreshUrl: () => getNatsWsUrlRef.current(),
+      shouldRetryOn: isDisconnectStatus,
+      onStatusChange: (status) => {
+        if (status === 'connected') {
           setIsConnected(true)
+          if (hadConnectionBeforeRef.current) {
+            setReconnectionCount((c) => c + 1)
+          }
           hadConnectionBeforeRef.current = true
+          onConnectRef.current?.()
         }
-      } catch {
-        sharedConn.connectPromise = null
-        if (!closed) {
+        if (isDisconnectStatus(status)) {
           setIsConnected(false)
+          setIsSubscribed(false)
+          tearDownSubscriptions()
           onDisconnectRef.current?.()
-          scheduleRetry()
         }
-      }
-    })()
+      },
+    })
 
     return () => {
-      closed = true
+      lifecycle.stop()
       setIsConnected(false)
       setIsSubscribed(false)
-      unsubscribeStatus()
-
-      if (sharedConn.retryTimer) {
-        clearTimeout(sharedConn.retryTimer)
-        sharedConn.retryTimer = null
-      }
-
-      // Unsubscribe all subscriptions
-      subscriptionRefs.current.forEach((sub) => {
-        try {
-          sub?.unsubscribe()
-        } catch {
-          // ignore
-        }
-      })
-      subscriptionRefs.current.clear()
-      lastSubscribedDialogIdRef.current = null
+      tearDownSubscriptions()
 
       if (clientRef.current && currentWsUrlRef.current) {
-        releaseClient(currentWsUrlRef.current)
+        releaseSharedClient(currentWsUrlRef.current)
         clientRef.current = null
         currentWsUrlRef.current = ''
       }
     }
-  }, [enabled, getNatsWsUrl, acquireClient, releaseClient])
+  }, [enabled, wsUrl])
 
   const topicsKey = topics.join(',')
   const lastSubscribedDialogIdRef = useRef<string | null>(null)
@@ -322,16 +188,13 @@ export function useNatsDialogSubscription({
     isConnectedRef.current = isConnected
   }, [isConnected])
 
-  // Track subscription state separately from dialog changes
   const currentDialogIdRef = useRef<string | null>(null)
   const abortControllerRef = useRef<AbortController | null>(null)
-  
-  // Handle dialog changes and subscription lifecycle
+
   useEffect(() => {
     currentDialogIdRef.current = dialogId
-    
+
     if (!enabled || !dialogId) {
-      // Clean up if disabled or no dialog
       if (subscriptionRefs.current.size > 0) {
         setIsSubscribed(false)
         subscriptionRefs.current.forEach((sub) => {
@@ -357,7 +220,6 @@ export function useNatsDialogSubscription({
       return
     }
     
-    // Clean up any existing subscriptions before creating new ones
     if (subscriptionRefs.current.size > 0) {
       subscriptionRefs.current.forEach((sub) => {
         try {
@@ -369,8 +231,7 @@ export function useNatsDialogSubscription({
       subscriptionRefs.current.clear()
       abortControllerRef.current?.abort()
     }
-    
-    // Create new abort controller for this subscription set
+
     abortControllerRef.current = new AbortController()
     const abort = abortControllerRef.current
 
@@ -397,7 +258,6 @@ export function useNatsDialogSubscription({
         }
       }
       
-      // Subscribe to all configured topics
       topics.forEach((topic) => {
         const subscription = client.subscribeBytes(
           `chat.${dialogId}.${topic}`,
@@ -431,8 +291,7 @@ export function useNatsDialogSubscription({
       abortControllerRef.current = null
     }
   }, [enabled, dialogId, topicsKey, topics])
-  
-  // Separate effect to handle connection state changes
+
   useEffect(() => {
     if (!enabled || !currentDialogIdRef.current || !isConnected) {
       return
@@ -461,7 +320,6 @@ export function useNatsDialogSubscription({
         }
       }
       
-      // Subscribe to all configured topics
       topics.forEach((topic) => {
         const subscription = client.subscribeBytes(
           `chat.${dialogId}.${topic}`,
@@ -475,7 +333,6 @@ export function useNatsDialogSubscription({
       setIsSubscribed(true)
       onSubscribedRef.current?.()
     } else if (subscriptionRefs.current.size > 0) {
-      // We have subscriptions, just update the state
       setIsSubscribed(true)
     }
   }, [isConnected, enabled, topics, topicsKey])

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

@@ -1,48 +1,62 @@
-<!-- source-hash: a73867ba07ef4db1732d63872e920f29 -->
-Comprehensive TypeScript definitions for API interactions and React hooks in a chat system with real-time messaging capabilities. Includes types for NATS subscriptions, chunk processing, dialog management, and approval workflows.
+<!-- 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 Options:**
-- `UseChunkCatchupOptions` - Configuration for catching up on missed message chunks
-- `UseNatsDialogSubscriptionOptions` - NATS WebSocket subscription configuration with client settings
-- `UseRealtimeChunkProcessorOptions` - Real-time message processing with approval filtering
-
-**Hook Return Types:**
-- `UseChunkCatchupReturn` - Chunk catchup functionality with buffering controls
-- `UseNatsDialogSubscriptionReturn` - Connection status for NATS subscriptions
-- `UseRealtimeChunkProcessorReturn` - Message segment processing and approval management
-
-**API Request/Response Types:**
-- Chat API endpoints (`ChatAPIRequest`, `ChatAPIResponse`)
-- Dialog management (`DialogCreateRequest`, `DialogListResponse`)
-- Approval workflows (`ApprovalRequest`, `ApprovalResponse`)
-- Settings management (`ChatSettings`, `UpdateSettingsRequest`)
-
-**Callback Interfaces:**
-- `RealtimeChunkCallbacks` - Comprehensive event handlers for streaming, metadata, approvals, and escalations
+### 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 |
+| `UseRealtimeChunkProcessorOptions` | Controls how streaming chunks are parsed, including approval routing and batch mode |
+
+### 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 |
+| `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.
+
+### API Request/Response Types
+- **Chat** — `ChatAPIRequest` / `ChatAPIResponse`
+- **Dialogs** — `DialogCreateRequest/Response`, `DialogListRequest/Response`
+- **Approvals** — `ApprovalRequest` / `ApprovalResponse`
+- **Settings** — `ChatSettings`, `UpdateSettingsRequest/Response`
 
 ## Usage Example
 
 ```typescript
-// Configure real-time chunk processing
-const processorOptions: UseRealtimeChunkProcessorOptions = {
+const options: UseRealtimeChunkProcessorOptions = {
   callbacks: {
-    onStreamStart: () => console.log('Stream started'),
-    onSegmentsUpdate: (segments) => updateUI(segments),
-    onApprove: async (requestId) => await approveRequest(requestId),
-    onEscalatedApproval: (id, data) => handleEscalation(id, data)
+    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),
+  },
+  batchApprovalsEnabled: true,
+  displayApprovalTypes: ['CLIENT'],
+  enableThinking: false,
+}
+
+const natsOptions: UseNatsDialogSubscriptionOptions = {
+  enabled: true,
+  dialogId: 'dialog-123',
+  getNatsWsUrl: () => 'wss://nats.example.com',
+  reconnectionBackoff: {
+    fastRetries: 3,
+    fastRetryDelayMs: 500,
+    maxDelayMs: 30000,
+    multiplier: 2,
   },
-  displayApprovalTypes: ['CLIENT', 'ADMIN'],
-  initialState: {
-    existingSegments: previousSegments,
-    pendingApprovals: new Map()
-  }
-};
-
-// Dialog creation request
-const createDialog: DialogCreateRequest = {
-  name: 'Support Session',
-  metadata: { customer: 'user123', priority: 'high' }
-};
+  onBeforeReconnect: async () => refreshAuthToken(),
+}
 ```

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

@@ -1,47 +1,56 @@
-<!-- source-hash: 64e087729cbab55280b984028a72489d -->
-Core TypeScript type definitions for Flamingo's AI-powered chat system, providing strongly-typed constants and interfaces for chat operations across MSP platform interactions.
+<!-- source-hash: 38493d239449552957a80bb746221c21 -->
+Defines core constants, enums, types, and utility functions for the Flamingo chat system, covering chat participants, message roles, connection states, and SSE wire shapes.
 
 ## Key Components
 
-- **CHAT_TYPE** - Defines client and admin chat channel types
-- **OWNER_TYPE** - Specifies message ownership (CLIENT, ADMIN, ASSISTANT)
-- **MESSAGE_ROLE** - Standard chat roles (user, assistant, system, error)
-- **ASSISTANT_TYPE** - Flamingo AI assistants (Fae for clients, Mingo for technicians)
-- **APPROVAL_STATUS** - Chat message approval workflow states
-- **CONNECTION_STATUS** - WebSocket connection state management
-- **MessageOwner** - Interface for tracking message attribution and metadata
+| Export | Kind | Description |
+|--------|------|-------------|
+| `CHAT_TYPE` / `ChatType` | Const + Type | Distinguishes `CLIENT_CHAT` from `ADMIN_AI_CHAT` contexts |
+| `OWNER_TYPE` / `OwnerType` | Const + Type | Message ownership: `CLIENT`, `ADMIN`, or `ASSISTANT` |
+| `MESSAGE_ROLE` / `MessageRole` | Const + Type | Conversation roles: `user`, `assistant`, `error`, `system` |
+| `ASSISTANT_TYPE` / `AssistantType` | Const + Type | AI assistants: `fae` (client-facing) and `mingo` (technician-facing) |
+| `AUTHOR_TYPE` / `AuthorType` | Const + Type | Full author roster including `user`, `admin`, `fae`, `mingo`, `system` |
+| `APPROVAL_STATUS` / `ChatApprovalStatus` | Const + Type | Approval workflow states: `pending`, `approved`, `rejected` |
+| `CONNECTION_STATUS` / `ConnectionStatus` | Const + Type | WebSocket/SSE lifecycle states |
+| `MessageOwner` | Interface | Identifies who owns a message, with optional user profile fields |
+| `buildChatRefKey` | Function | Builds canonical `docType:externalId` keys for `chatRefs` map lookups |
+| `isStructuredContent` | Function | Type guard — checks if `MessageContent` is a `MessageSegment[]` |
+| `normalizeContent` | Function | Coerces string or segment array to a uniform `MessageSegment[]` |
+| `TextEventData` / `ToolExecutionEventData` / `SSEEventData` | Interfaces + Union | Wire shapes for SSE streaming events |
+| `QuickAction` | Interface | Shape for quick-reply chip components (`id` + `text`) |
 
 ## Usage Example
 
 ```typescript
-import { 
-  CHAT_TYPE, 
-  MESSAGE_ROLE, 
-  ASSISTANT_TYPE, 
-  MessageOwner,
-  ConnectionStatus 
+import {
+  CHAT_TYPE,
+  MESSAGE_ROLE,
+  ASSISTANT_TYPE,
+  APPROVAL_STATUS,
+  CONNECTION_STATUS,
+  buildChatRefKey,
+  isStructuredContent,
+  normalizeContent,
 } from './chat.types'
 
-// Create a client chat message
-const clientMessage = {
-  role: MESSAGE_ROLE.USER,
-  content: "Help with server issues",
-  chatType: CHAT_TYPE.CLIENT
-}
+// Route to the correct AI assistant based on chat context
+const assistant =
+  chatType === CHAT_TYPE.CLIENT ? ASSISTANT_TYPE.FAE : ASSISTANT_TYPE.MINGO
 
-// Define assistant response owner
-const faeOwner: MessageOwner = {
-  type: OWNER_TYPE.ASSISTANT,
-  machineId: 'fae-01',
-  model: ASSISTANT_TYPE.FAE
-}
+// Build a chatRefs lookup key matching inline [card://ticket:42] markers
+const refKey = buildChatRefKey('ticket', '42') // → "ticket:42"
 
-// Handle connection states
-const handleConnectionChange = (status: ConnectionStatus) => {
-  if (status === CONNECTION_STATUS.CONNECTED) {
-    console.log('Chat service ready')
-  }
+// Normalize incoming content before rendering
+const segments = normalizeContent(message.content)
+// → always MessageSegment[], safe to iterate
+
+// Check approval before displaying an action
+if (approval === APPROVAL_STATUS.PENDING) {
+  showApprovalBanner()
 }
-```
 
-This type system ensures type safety across Flamingo's chat components while supporting both client-facing (Fae) and technician-focused (Mingo) AI interactions within the unified OpenFrame platform.
+// Handle SSE connection lifecycle
+if (status === CONNECTION_STATUS.RECONNECTING) {
+  showReconnectingSpinner()
+}
+```