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

package/src/components/chat/hooks/__tests__/sse-stream-golden.test.ts

@@ -0,0 +1,318 @@
+/**
+ * Phase-0 GOLDEN CHARACTERIZATION TESTS — the SSE wire decoder inside
+ * `useSseChatAdapter` (`createDocStreamFn`), driven through the full
+ * public hook (`useSseChatAdapter` → `useChat` → `useSSE`).
+ *
+ * Wire format (recorded from the hub's /api/docs/chat):
+ *   [JSON frame]\0 [JSON frame]\0 …  \x1E  <raw UTF-8 answer deltas>  \x1F [JSON usage trailer]
+ *
+ * Each fixture feeds a mocked global fetch whose Response body is a
+ * ReadableStream of Uint8Array chunks, then snapshots the resulting
+ * message state. Behaviors captured here — INCLUDING the sentinel-byte
+ * mis-framing in fixture (d) — are the recorded baseline for the
+ * unification reducer. Do NOT "fix" them here.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { createElement, type ReactNode } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { useSseChatAdapter } from '../use-sse-chat-adapter'
+import { ChatRuntimeContext, type ChatRuntime } from '../../../../contexts/chat-runtime-context'
+
+// =============================================================================
+// Harness
+// =============================================================================
+
+const SOURCE = 'goldensrc'
+
+const runtime: ChatRuntime = {
+  endpoints: {
+    chatStreamUrl: '/api/docs/chat',
+    approvalToolUrl: '/api/chat/agent/confirm-tool',
+    commandsUrl: '/api/docs/commands',
+    buildListUrl: () => null,
+    attachmentUploadUrl: '/api/storage/generate-upload-url',
+    attachmentViewUrlPrefix: '/api/storage/view/chat-attachments/',
+    identityUrl: '/api/chat/identity',
+  },
+  navigation: { mode: 'host' },
+  source: SOURCE,
+}
+
+function wrapper({ children }: { children: ReactNode }) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  })
+  return createElement(
+    QueryClientProvider,
+    { client: queryClient },
+    createElement(ChatRuntimeContext.Provider, { value: runtime }, children),
+  )
+}
+
+/** renderHook with the required runtime + react-query providers.
+ *  `active: false` skips the slash-command registry fetch so the mocked
+ *  fetch only ever serves the chat stream. */
+function renderAdapter() {
+  return renderHook(() => useSseChatAdapter(undefined, { active: false }), { wrapper })
+}
+
+const enc = new TextEncoder()
+
+/** Build a ReadableStream that enqueues each chunk (string → UTF-8) then closes. */
+function streamOf(chunks: Array<string | Uint8Array>): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const c of chunks) {
+        controller.enqueue(typeof c === 'string' ? enc.encode(c) : c)
+      }
+      controller.close()
+    },
+  })
+}
+
+/** Mock global fetch to serve ONE streamed chat response. */
+function mockFetchStream(chunks: Array<string | Uint8Array>) {
+  const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {
+    const body = streamOf(chunks)
+    // Honor the caller's AbortSignal like real fetch: error the stream so
+    // pending reader.read() calls reject with AbortError.
+    return { ok: true, status: 200, body } as unknown as Response
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+const tick = () => new Promise<void>((r) => setTimeout(r, 0))
+
+beforeEach(() => {
+  window.localStorage.clear()
+  // Deterministic Date.now: message ids (`user-<now>`) and the 50ms
+  // thinking-throttle both read it. With a frozen clock the FIRST
+  // thinking delta yields immediately (now - 0 >= 50) and every later
+  // delta within the same stream is throttled (now - last = 0 < 50) and
+  // flushed at the \x1E boundary — fully deterministic.
+  vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_000)
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+/** Compact projection of the adapter's public state for snapshots. */
+function snapshotState(result: { current: ReturnType<typeof useSseChatAdapter> }) {
+  const s = result.current
+  return {
+    messages: s.messages,
+    streamingPhase: s.streamingPhase,
+    provider: s.currentProvider,
+    modelLabel: s.currentModelLabel,
+    contextWindowMaxTokens: s.currentContextWindowMaxTokens,
+    inputTokens: s.currentInputTokens,
+    outputTokens: s.currentOutputTokens,
+    cacheHitRatePct: s.currentCacheHitRatePct,
+    usageBreakdown: s.currentUsageBreakdown,
+  }
+}
+
+// Shared leading-frame fixtures (recorded wire shapes).
+const THINKING_STATUS = '{"status":"thinking"}\0'
+const THINKING_DELTA_1 = '{"kind":"thinking-delta","text":"Let me check the docs… "}\0'
+const THINKING_DELTA_2 = '{"kind":"thinking-delta","text":"found it."}\0'
+const METADATA_FRAME =
+  '{"sources":[{"index":1,"name":"Pricing overview","path":"docs/pricing.md","documentType":"markdown","sourceRepo":"markdown"}],"model":"claude-sonnet-x","modelLabel":"Claude Sonnet","provider":"anthropic","contextWindowMaxTokens":200000}\0'
+const ROUTING_FRAME = '{"kind":"routing","routedComplexity":"simple","routedThinkingBudget":0}\0'
+const USAGE_START_FRAME = '{"kind":"usage","stage":"start","input_tokens":1234}\0'
+const USAGE_END_TRAILER =
+  '{"kind":"usage","stage":"end","input_tokens":1234,"output_tokens":56,"hit_rate_pct":81.5,"breakdown":{"haikuRewriter":{"input":10,"output":4},"haikuClassifier":{"input":8,"output":1},"routedAnswer":{"model":"claude-sonnet-x","complexity":"simple","thinkingBudget":0}}}'
+
+describe('SSE wire decode — golden fixtures (full hook path)', () => {
+  it('(a) normal turn: thinking frames → metadata → usage:start → \\x1E → text ×3 → \\x1F trailer', async () => {
+    mockFetchStream([
+      THINKING_STATUS,
+      THINKING_DELTA_1,
+      THINKING_DELTA_2,
+      METADATA_FRAME,
+      ROUTING_FRAME,
+      USAGE_START_FRAME,
+      '\x1E',
+      'Answer part one, ',
+      'part two, ',
+      'part three.',
+      '\x1F' + USAGE_END_TRAILER,
+    ])
+    const { result } = renderAdapter()
+    await act(async () => {
+      await result.current.sendMessage('what is the pricing?')
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+  })
+
+  it('(b) EVERYTHING in one single TCP chunk', async () => {
+    mockFetchStream([
+      THINKING_STATUS +
+        THINKING_DELTA_1 +
+        METADATA_FRAME +
+        USAGE_START_FRAME +
+        '\x1E' +
+        'One-chunk answer.' +
+        '\x1F' +
+        USAGE_END_TRAILER,
+    ])
+    const { result } = renderAdapter()
+    await act(async () => {
+      await result.current.sendMessage('one chunk please')
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+  })
+
+  it('(c) trailer split across two chunks arriving with stream done', async () => {
+    mockFetchStream([
+      METADATA_FRAME,
+      '\x1E',
+      'Split-trailer answer.',
+      '\x1F{"kind":"usage","stage":"end","input_to',
+      'kens":42,"output_tokens":9,"hit_rate_pct":12.5}',
+    ])
+    const { result } = renderAdapter()
+    await act(async () => {
+      await result.current.sendMessage('split the trailer')
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+  })
+
+  it('(d) answer text containing literal \\x1E/\\x1F/\\0 bytes', async () => {
+    // CHARACTERIZATION: current behavior, see unification plan.
+    //  - In text mode only \x1F is scanned: literal \0 and \x1E bytes in
+    //    the answer pass through into the rendered text unchanged.
+    //  - The FIRST literal \x1F flips the decoder into trailer mode:
+    //    everything after it (including later real text) is captured as
+    //    the trailer buffer, fails JSON.parse, and is SILENTLY DROPPED —
+    //    the real \x1F usage trailer is lost too (mis-framing/truncation).
+    mockFetchStream([
+      METADATA_FRAME,
+      '\x1E',
+      'has-nul[\0]and-rs[\x1E]still-text. ',
+      'now-us[\x1F]everything-after-is-swallowed',
+      ' including this and the real trailer:',
+      '\x1F' + USAGE_END_TRAILER,
+    ])
+    const { result } = renderAdapter()
+    await act(async () => {
+      await result.current.sendMessage('sentinel bytes in answer')
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+  })
+
+  it('(e) [card://blog:x] marker in the answer with refs metadata frame', async () => {
+    const refsFrame =
+      '{"refs":{"blog:x":{"type":"blog","id":"x","title":"Post X","url":"/blog/x","metadata":{"slug":"post-x"}}}}\0'
+    mockFetchStream([
+      METADATA_FRAME,
+      refsFrame,
+      '\x1E',
+      'See [card://blog:x] for the full story.',
+      '\x1F' + USAGE_END_TRAILER,
+    ])
+    const { result } = renderAdapter()
+    await act(async () => {
+      await result.current.sendMessage('show me the post')
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+  })
+
+  it('(f) abort mid-stream via AbortController leaves the partial message in place', async () => {
+    // Manually-controlled stream: enqueue the leading frames + first text
+    // delta, keep the stream OPEN, then Stop. The mocked fetch honors the
+    // AbortSignal by erroring the stream with AbortError — same observable
+    // behavior as real fetch cancelling the body.
+    let ctrl!: ReadableStreamDefaultController<Uint8Array>
+    const body = new ReadableStream<Uint8Array>({
+      start(c) {
+        ctrl = c
+        c.enqueue(enc.encode(METADATA_FRAME))
+        c.enqueue(enc.encode('\x1E'))
+        c.enqueue(enc.encode('Partial ans'))
+      },
+    })
+    const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {
+      init?.signal?.addEventListener('abort', () => {
+        try {
+          ctrl.error(new DOMException('The operation was aborted.', 'AbortError'))
+        } catch {
+          /* already closed */
+        }
+      })
+      return { ok: true, status: 200, body } as unknown as Response
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const { result } = renderAdapter()
+    let sendPromise!: Promise<void>
+    act(() => {
+      sendPromise = result.current.sendMessage('will be aborted')
+    })
+    // Let the decoder consume the enqueued chunks.
+    await act(async () => {
+      await tick()
+      await tick()
+      await tick()
+    })
+    act(() => {
+      result.current.stopMessage()
+    })
+    await act(async () => {
+      await sendPromise
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('(g) multi-byte UTF-8 character split across two chunks decodes intact', async () => {
+    // '🦩' = F0 9F A6 A9 — split 2+2 across chunk boundary. The decoder is
+    // created once per stream with {stream:true} reads, so the glyph
+    // survives the split. CHARACTERIZATION: current (correct) behavior.
+    const flamingo = enc.encode('🦩')
+    mockFetchStream([
+      METADATA_FRAME,
+      '\x1E',
+      'A wild ',
+      flamingo.slice(0, 2),
+      flamingo.slice(2),
+      ' appears',
+      '\x1F' + USAGE_END_TRAILER,
+    ])
+    const { result } = renderAdapter()
+    await act(async () => {
+      await result.current.sendMessage('emoji split')
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+  })
+
+  it('leading approval_request + text-leading frames yield a pending approval card', async () => {
+    mockFetchStream([
+      '{"kind":"text-leading","text":"I\'ll open a ticket for you."}\0',
+      '{"kind":"approval_request","proposalId":"prop-1","toolName":"create_ticket","title":"Create ticket","fields":[{"label":"Subject","value":"Printer down"},{"label":"Priority","value":"High"},{"bad":"missing label/value"}]}\0',
+      // Stream closes with NO \x1E answer body — the approval turn ends here.
+    ])
+    const { result } = renderAdapter()
+    await act(async () => {
+      await result.current.sendMessage('open a ticket')
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+  })
+
+  it('non-JSON leading buffer falls through to answer text (legacy no-frame stream)', async () => {
+    // CHARACTERIZATION: a frame-less response whose first \0-terminated
+    // block is not JSON flips straight into text mode and the buffer is
+    // emitted as answer text.
+    mockFetchStream(['plain text answer with no frames\0and more after the nul'])
+    const { result } = renderAdapter()
+    await act(async () => {
+      await result.current.sendMessage('legacy stream')
+    })
+    expect(snapshotState(result)).toMatchSnapshot()
+  })
+})

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

@@ -5,7 +5,6 @@ export * from './use-collapsible'
 export * from './use-scripted-stream'
 export * from './use-jetstream-dialog-subscription'
 export * from './use-nats-dialog-subscription'
-export * from './use-realtime-chunk-processor'
 
 // Chat hooks migrated from hub `hooks/*` (Task #7).
 export * from './use-slash-commands'

package/src/components/chat/hooks/use-chat-history-hydration.ts

@@ -0,0 +1,142 @@
+'use client'
+
+/**
+ * useChatHistoryHydration — mount-time rebuild of the chat message list from
+ * the SERVER-side conversation store (the `chat_conversations` /
+ * `chat_messages` SSOT behind `GET <chatStreamUrl>/history`).
+ *
+ * The client persists ONLY the server-issued conversation id (see
+ * `chat-conversation-storage.ts`); this hook turns that id back into rendered
+ * history: message bubbles, inline entity-card refs (per send index, same
+ * `sendIdx` scheme as live turns), and the send counter.
+ *
+ * Failure semantics: a fetch/parse failure simply leaves the UI empty — the
+ * SERVER still resolves full history for the next turn (it re-reads
+ * `chat_messages` by conversation id on every send), so conversation context
+ * is never lost when hydration misses.
+ */
+
+import { useEffect, useRef, useState, type MutableRefObject } from 'react'
+import type { ChatRef } from '../chat-ref.types'
+import type { Message } from './use-chat'
+import { chatAuthedFetch } from '../utils/chat-authed-fetch'
+import { AUTO_CONTINUATION_DIRECTIVE_PREFIX } from '../utils/auto-continuation-directive'
+
+export interface UseChatHistoryHydrationArgs {
+  /** Mirrors the adapter's `active` gate — an idle (Mingo-mode) mount never fetches. */
+  active: boolean
+  /** Chat source (= platform); part of the once-per-conversation guard key. */
+  source: string
+  /** Resolved history endpoint (`<chatStreamUrl>/history` by default). */
+  historyUrl: string
+  /** The server-issued conversation id (null = nothing to hydrate). */
+  conversationIdRef: MutableRefObject<string | null>
+  /** Per-send inline entity-card refs — repopulated from `chat_refs`. */
+  refsMapRef: MutableRefObject<Map<number, Record<string, ChatRef>>>
+  /** User-send counter — set to the hydrated user-turn count so the next
+   *  live send lands on the following `sendIdx`. */
+  sendCountRef: MutableRefObject<number>
+  /** `useChat`'s injection primitive (replace-or-prepend). */
+  hydrateMessages: (history: Message[]) => void
+  /** Invalidates the adapter's `latestMeta` memo after refs repopulate. */
+  bumpMetaTick: () => void
+}
+
+export interface UseChatHistoryHydrationResult {
+  /** True while the rebuild request is in flight. */
+  isHydratingHistory: boolean
+  /** Once-per-`source:conversationId` guard. The adapter's `clearMessages`
+   *  resets it to null alongside the stored id (a fresh conversation has no
+   *  server history to fetch). */
+  hydratedKeyRef: MutableRefObject<string | null>
+}
+
+export function useChatHistoryHydration({
+  active,
+  source,
+  historyUrl,
+  conversationIdRef,
+  refsMapRef,
+  sendCountRef,
+  hydrateMessages,
+  bumpMetaTick,
+}: UseChatHistoryHydrationArgs): UseChatHistoryHydrationResult {
+  const [isHydratingHistory, setIsHydratingHistory] = useState(false)
+  const hydratedKeyRef = useRef<string | null>(null)
+
+  useEffect(() => {
+    if (!active) return
+    // No stored conversation id → nothing to hydrate (fresh visitor / after
+    // "new chat"); the first send establishes the conversation server-side.
+    const conversationId = conversationIdRef.current
+    if (!conversationId) return
+    const key = `${source}:${conversationId}`
+    if (hydratedKeyRef.current === key) return
+    hydratedKeyRef.current = key
+    let cancelled = false
+    setIsHydratingHistory(true)
+    ;(async () => {
+      try {
+        const res = await chatAuthedFetch(
+          `${historyUrl}?conversationId=${encodeURIComponent(conversationId)}`,
+          { method: 'GET' },
+        )
+        if (!res.ok) return
+        const payload = await res.json().catch(() => null)
+        // route-base successResponse envelope ({ data }) with a raw-body fallback.
+        const body = (payload?.data ?? payload) as
+          | { messages?: Array<Record<string, unknown>> }
+          | null
+        const rows = Array.isArray(body?.messages) ? body!.messages! : []
+        if (cancelled || rows.length === 0) return
+        const hydrated: Message[] = []
+        let userTurns = 0
+        for (const row of rows) {
+          const role =
+            row.role === 'assistant' ? 'assistant' : row.role === 'user' ? 'user' : null
+          if (!role) continue
+          const content = typeof row.content === 'string' ? row.content : ''
+          // The approval placeholder ('') and the server-built auto-continuation
+          // directive are part of the LLM history but never rendered.
+          const hidden =
+            role === 'user' &&
+            (content === '' || content.startsWith(AUTO_CONTINUATION_DIRECTIVE_PREFIX))
+          if (role === 'user') {
+            userTurns += 1
+          } else if (row.chat_refs && typeof row.chat_refs === 'object') {
+            // Re-attach inline entity-card refs at the send index this
+            // assistant row belongs to (same sendIdx scheme as live turns).
+            refsMapRef.current.set(
+              Math.max(0, userTurns - 1),
+              row.chat_refs as Record<string, ChatRef>,
+            )
+          }
+          hydrated.push({
+            id: `hydrated-${String(row.seq ?? hydrated.length)}`,
+            role,
+            content,
+            ...(typeof row.created_at === 'string'
+              ? { timestamp: new Date(row.created_at) }
+              : {}),
+            ...(hidden ? { hidden: true } : {}),
+          } as Message)
+        }
+        if (cancelled || hydrated.length === 0) return
+        sendCountRef.current = userTurns
+        hydrateMessages(hydrated)
+        bumpMetaTick()
+      } catch {
+        // Fetch failed — start empty; the server still owns history (above).
+      } finally {
+        if (!cancelled) setIsHydratingHistory(false)
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+    // Refs are stable across renders — the effect keys on the identity-ish deps only.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active, source, historyUrl, hydrateMessages, bumpMetaTick])
+
+  return { isHydratingHistory, hydratedKeyRef }
+}

package/src/components/chat/hooks/use-chat.ts

@@ -1,5 +1,13 @@
 'use client'
 
+/**
+ * @deprecated Phase 3 of the chat unification moved the SSE adapter off this
+ * hook — its trailing-assistant merge + `decision_resolved` receipt path now
+ * live in `../stream/chat-stream-reducer` (transport: 'sse'). No lib-internal
+ * code consumes `useChat`/`useSSE` anymore; they remain exported for external
+ * consumers until Phase 4 migrates them, then get deleted (Phase 6).
+ */
+
 import { useState, useCallback, useEffect, useRef } from 'react'
 import { useSSE, type StreamFn, type StreamFnExtraOptions } from './use-sse'
 import type {
@@ -476,6 +484,17 @@ export function useChat({
     reset()
   }, [reset])
 
+  /**
+   * Replace-or-prepend server-hydrated history. Called once by the SSE
+   * adapter after `GET /api/docs/chat/history` resolves. If the user already
+   * sent a message before hydration landed, the fetched history is PREPENDED
+   * so nothing typed is lost — correctness is unaffected either way because
+   * the server resolves LLM history from its own store, not from this state.
+   */
+  const hydrateMessages = useCallback((history: Message[]) => {
+    setMessages((prev) => (prev.length === 0 ? history : [...history, ...prev]))
+  }, [])
+
   /**
    * Abort the in-flight streamed message. The fetch's AbortSignal terminates
    * the upstream Anthropic request (so billing stops); the `for await` loop
@@ -496,6 +515,7 @@ export function useChat({
     stopMessage,
     handleQuickAction,
     clearMessages,
+    hydrateMessages,
     hasMessages: messages.length > 0,
   }
 }