@flamingo-stack/openframe-frontend-core 0.0.207 → 0.0.208

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

@@ -0,0 +1,171 @@
+'use client'
+
+/**
+ * useUnifiedChat — the single public entry point for the unified chat
+ * surface. Dispatches between the SSE/Guide and NATS/Mingo transport
+ * adapters based on the active mode. Always calls both underlying
+ * hooks (React rules of hooks) but only one is "live": the inactive
+ * one stays idle (no streams, no subscriptions) while preserving its
+ * local message buffer so a mode-flip restores the user to exactly
+ * where they left off.
+ *
+ * Consumers that only need one mode pass a single `modes` entry —
+ * the inactive adapter's config slot stays empty and the hook
+ * supplies a no-op default so React-hooks-rules are satisfied
+ * without forcing consumers to write throwaway stubs.
+ *
+ * The mode-toggle UI affordance lives in the `<MingoChat>` shell that
+ * consumes this hook, NOT here. This module is pure state plumbing.
+ */
+
+import { useCallback, useMemo, useRef } from 'react'
+import { useSseChatAdapter, type UseSseChatAdapterOptions } from './use-sse-chat-adapter'
+import {
+  useNatsChatAdapter,
+  type UseNatsChatAdapterConfig,
+} from './use-nats-chat-adapter'
+import type { UnifiedChatState } from '../types/unified-chat-state.types'
+
+// =============================================================================
+// Modes
+// =============================================================================
+
+/** Discriminator for the active transport mode. */
+export type ChatMode = 'guide' | 'mingo'
+
+/**
+ * Per-mode configuration. Each slot is optional — consumers that only
+ * need one mode leave the other undefined. The active mode MUST have
+ * its config populated; passing `activeMode: 'mingo'` while `modes.mingo`
+ * is undefined is a programming error and surfaces as a thrown
+ * `sendMessage`.
+ */
+export interface UseUnifiedChatModes {
+  /**
+   * Guide mode (SSE → hub). Currently `useSseChatAdapter` reads its
+   * config from the ambient `ChatRuntimeContext` rather than props,
+   * so this slot is just an opt-in flag plus its adapter options.
+   * The presence of the key signals "guide mode is configured".
+   */
+  guide?: UseSseChatAdapterOptions
+
+  /**
+   * Mingo mode (NATS → openframe). All wiring is explicit: dialog id,
+   * NATS URL builder, publish callback, optional catchup fetcher.
+   * See `UseNatsChatAdapterConfig` for the field-by-field contract.
+   */
+  mingo?: UseNatsChatAdapterConfig
+}
+
+export interface UseUnifiedChatOptions {
+  modes: UseUnifiedChatModes
+  activeMode: ChatMode
+}
+
+// =============================================================================
+// Defaults — fill the inactive slot so both hooks run safely
+// =============================================================================
+
+const EMPTY_SSE_OPTIONS: UseSseChatAdapterOptions = {}
+
+function createDisabledNatsConfig(): UseNatsChatAdapterConfig {
+  return {
+    dialogId: null,
+    getNatsWsUrl: () => null,
+    publishUserMessage: () => {
+      throw new Error(
+        '[useUnifiedChat] publishUserMessage invoked but mingo mode is not configured. ' +
+          'Pass `modes.mingo` to enable Mingo agent transport.',
+      )
+    },
+  }
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useUnifiedChat(
+  options: UseUnifiedChatOptions,
+): UnifiedChatState {
+  const { modes, activeMode } = options
+
+  // The mingo config object identity matters — `useNatsChatAdapter`
+  // wires its `dialogId`/url/publish into deps. Stabilise the disabled
+  // fallback so a guide-only consumer doesn't churn NATS hook state
+  // every render.
+  const disabledNatsRef = useRef<UseNatsChatAdapterConfig | null>(null)
+  if (disabledNatsRef.current === null) {
+    disabledNatsRef.current = createDisabledNatsConfig()
+  }
+
+  // Each adapter receives the user's config OR the disabled fallback,
+  // plus an `active` flag that gates its live network work. Both
+  // hooks are always called — only one is doing real work.
+  const sseActive = activeMode === 'guide' && modes.guide !== undefined
+  const natsActive = activeMode === 'mingo' && modes.mingo !== undefined
+
+  const sseState = useSseChatAdapter(modes.guide ?? EMPTY_SSE_OPTIONS)
+  const natsState = useNatsChatAdapter(
+    modes.mingo ?? disabledNatsRef.current,
+    { active: natsActive },
+  )
+
+  // Mark `sseActive` as used — SSE adapter is request-response so it
+  // doesn't currently consume an `active` gate. Keeping the flag here
+  // documents intent + leaves the door open for future SSE backgrounding.
+  void sseActive
+
+  const activeState = activeMode === 'guide' ? sseState : natsState
+
+  // Re-wrap so the returned identity is stable for the active state.
+  // Consumers shouldn't see the inactive adapter's state at all.
+  const stopMessage = useCallback(() => activeState.stopMessage(), [activeState])
+  const clearMessages = useCallback(
+    () => activeState.clearMessages(),
+    [activeState],
+  )
+  const sendMessage = useCallback(
+    (text: string, opts?: Parameters<UnifiedChatState['sendMessage']>[1]) =>
+      activeState.sendMessage(text, opts),
+    [activeState],
+  )
+  const discussRef = useCallback(
+    (ref: Parameters<UnifiedChatState['discussRef']>[0]) =>
+      activeState.discussRef(ref),
+    [activeState],
+  )
+  const displayRef = useCallback(
+    (ref: Parameters<UnifiedChatState['displayRef']>[0]) =>
+      activeState.displayRef(ref),
+    [activeState],
+  )
+
+  return useMemo<UnifiedChatState>(
+    () => ({
+      messages: activeState.messages,
+      isLoading: activeState.isLoading,
+      streamingPhase: activeState.streamingPhase,
+      sendMessage,
+      stopMessage,
+      clearMessages,
+      discussRef,
+      displayRef,
+      currentProvider: activeState.currentProvider,
+      currentModelLabel: activeState.currentModelLabel,
+      currentContextWindowMaxTokens: activeState.currentContextWindowMaxTokens,
+      currentInputTokens: activeState.currentInputTokens,
+      currentOutputTokens: activeState.currentOutputTokens,
+      currentCacheHitRatePct: activeState.currentCacheHitRatePct,
+      currentUsageBreakdown: activeState.currentUsageBreakdown,
+    }),
+    [
+      activeState,
+      sendMessage,
+      stopMessage,
+      clearMessages,
+      discussRef,
+      displayRef,
+    ],
+  )
+}

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

@@ -5,3 +5,4 @@ export * from './network.types'
 export * from './processing.types'
 export * from './api.types'
 export * from './entities'
+export * from './unified-chat-state.types'

package/src/components/chat/types/unified-chat-state.types.ts

@@ -0,0 +1,215 @@
+'use client'
+
+/**
+ * UnifiedChatState — the return shape that BOTH transport hooks must satisfy.
+ *
+ * Two transport implementations live behind this contract:
+ *   - SSE (Guide mode) — talks to the hub backend
+ *   - NATS (Mingo mode) — talks to the OpenFrame backend
+ *
+ * The public `useChat({ mode })` hook picks one based on `mode.transport` and
+ * returns this shape regardless. Consumers (MingoChat shell, advanced custom
+ * embedders) work against this contract and never see which transport is live.
+ *
+ * Fields that only one transport can populate are typed as nullable (per-turn
+ * LLM metadata is SSE-only) or optional (Guide-only message sub-fields like
+ * `sources` and `chatRefs`). In the off-mode they're null/undefined.
+ */
+
+import type { MessageSegment } from './message.types'
+import type { ScrollAnchor } from './message.types'
+import type { ChatRef } from '../chat-ref.types'
+import type { ChatSource } from '../hooks/use-sse-chat-adapter'
+import type { ChatAttachment } from '../utils/chat-attachment-markdown'
+
+// ─── Streaming phase (unified across transports) ─────────────────────────────
+
+/**
+ * Granular streaming-status enum the chat shell uses to render the
+ * "Thinking..."/"Streaming..." indicator above the input.
+ *
+ * - 'idle'      → no in-flight turn
+ * - 'thinking'  → request fired; no streamed text/segments yet
+ * - 'streaming' → first text/segment chunk arrived; output in progress
+ *
+ * Common to both Guide (SSE) and Mingo (NATS) modes — the phase
+ * machine fires identically in either transport, just driven by
+ * different chunk boundaries.
+ */
+export type StreamingPhase = 'idle' | 'thinking' | 'streaming'
+
+// ─── Usage breakdown (SSE-only telemetry) ────────────────────────────────────
+
+/**
+ * Cross-call token-usage breakdown extracted from the SSE trailing usage
+ * frame. Surfaces sub-call costs for the Haiku rewriter/classifier/summarizer
+ * pipeline plus the routing decision for the main answer.
+ *
+ * Lives on `UnifiedChatState.currentUsageBreakdown` as `null` until the
+ * server's trailing usage frame lands. Always `null` in Mingo mode — NATS
+ * agent doesn't surface this telemetry.
+ */
+export interface UnifiedUsageBreakdown {
+  haikuRewriter?: { input: number; output: number }
+  haikuClassifier?: { input: number; output: number }
+  haikuSummarizer?: { input: number; output: number }
+  routedAnswer?: { model: string; complexity: string; thinkingBudget: number }
+}
+
+// ─── Message ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generic chat message shape — unified between Guide (SSE) and Mingo (NATS).
+ *
+ * Guide-mode messages populate `sources` (RAG document citations) and
+ * `chatRefs` (inline entity-card references). Mingo-mode messages leave
+ * those undefined. Tool-execution and approval events ride inside
+ * `segments` and are common to both modes.
+ */
+export interface UnifiedChatMessage {
+  id: string
+  role: 'user' | 'assistant'
+
+  /**
+   * Flat string form for legacy/simple callers. The structured `segments`
+   * form is preferred — it carries thinking blocks, tool calls, approval
+   * cards, etc., which `<ChatMessageEnhanced>` renders.
+   */
+  content: string
+  segments?: MessageSegment[]
+
+  /** Guide/SSE-only: document citations. Undefined in Mingo mode. */
+  sources?: ChatSource[]
+
+  /**
+   * Guide/SSE-only: per-row refs for inline entity-card rendering.
+   * Keyed by `<documentType>:<primaryKey>`. Undefined in Mingo mode.
+   */
+  chatRefs?: Record<string, ChatRef>
+
+  /**
+   * Per-message viewport-positioning hint. Common to both modes; the
+   * message-list reads it to override default tail-on-stream behaviour
+   * for a single message (e.g. long display-action answers anchor to
+   * the top so the reader starts at the lede).
+   */
+  scrollAnchor?: ScrollAnchor
+
+  /**
+   * When true the message is part of the conversation history but is
+   * NOT rendered in the chat UI. Used for post-approval auto-continuation
+   * turns where we don't want synthetic prompts polluting the visible
+   * thread.
+   */
+  hidden?: boolean
+}
+
+// ─── sendMessage options ─────────────────────────────────────────────────────
+
+/**
+ * Options passed to `sendMessage`. Kept narrow on purpose — transport-specific
+ * extras stay inside the transport implementation, not on the public surface.
+ * Add fields here only when BOTH transports honour them.
+ */
+export interface UnifiedSendMessageOptions {
+  /**
+   * Treat the user message as background context only — added to the LLM
+   * history so the model sees it, but NOT rendered in the UI. Used by hosts
+   * to fire post-approval auto-continuation turns. The assistant response
+   * still renders normally.
+   */
+  hidden?: boolean
+
+  /**
+   * Image attachments uploaded via `useChatAttachments` to ride alongside
+   * the user message. Each entry carries `{ storagePath, viewToken }` —
+   * server-side the transport adapter replaces embedded view-URL markdown
+   * lines with provider-native image content blocks.
+   *
+   * Guide/SSE mode: forwarded to the hub's `/api/docs/chat` endpoint.
+   * Mingo/NATS mode: ignored (agent backend does not currently accept
+   * image attachments — adapter will silently drop).
+   */
+  attachments?: ChatAttachment[]
+}
+
+// ─── Return shape ────────────────────────────────────────────────────────────
+
+/**
+ * The contract every transport hook returns. Stable across SSE and NATS —
+ * consumers depend on this shape and never branch on `mode` themselves.
+ *
+ * Mode-specific telemetry (provider, token counts, cache-hit %) is SSE-only.
+ * In Mingo mode those fields are `null` because NATS-agent doesn't surface
+ * per-turn LLM metadata the same way.
+ */
+export interface UnifiedChatState {
+  // ─── Message thread ───────────────────────────────────────────────────────
+  messages: UnifiedChatMessage[]
+
+  /**
+   * True while a user turn is in progress — server-side thinking, streaming,
+   * or both. Driven by `streamingPhase` under the hood; exposed as a flat
+   * boolean for the chat-input "submit disabled" affordance.
+   */
+  isLoading: boolean
+
+  /** Granular phase for the "Thinking..."/"Streaming..." status row above input. */
+  streamingPhase: StreamingPhase
+
+  // ─── Actions ──────────────────────────────────────────────────────────────
+  sendMessage: (
+    text: string,
+    options?: UnifiedSendMessageOptions,
+  ) => Promise<void>
+
+  /** Abort the in-flight stream. No-op when idle. */
+  stopMessage: () => void
+
+  /** Wipe the local message buffer. Does not touch server-side history. */
+  clearMessages: () => void
+
+  /**
+   * Trigger the chat's "Discuss this row" affordance — opens a focused
+   * thread scoped to a specific RAG entity. Guide-mode only; in Mingo mode
+   * this is a no-op (the agent has no entity-id-filtered retrieval).
+   */
+  discussRef: (ref: ChatRef) => void
+
+  /**
+   * Trigger the chat's "Display this row" affordance — same as `discussRef`
+   * but for read-only card display rather than a question. Guide-mode only.
+   */
+  displayRef: (ref: ChatRef) => void
+
+  // ─── Per-turn LLM metadata (Guide/SSE only) ───────────────────────────────
+  /**
+   * Provider key recognised by `<ModelDisplay>` for icon selection.
+   * Values: 'anthropic' | 'openai' | 'google' (case-insensitive).
+   * Null in Mingo mode and during the brief window before the server's
+   * `message_start` frame arrives.
+   */
+  currentProvider: string | null
+
+  /** Display label for the active model, e.g. "Sonnet 4.6". Null in Mingo. */
+  currentModelLabel: string | null
+
+  /** Model's context-window cap in tokens. Null in Mingo. */
+  currentContextWindowMaxTokens: number | null
+
+  /** Input tokens for the current turn (from `message_start`). Null in Mingo. */
+  currentInputTokens: number | null
+
+  /** Output tokens for the current turn (only known after stream end). */
+  currentOutputTokens: number | null
+
+  /** Cache-hit % (read / total-input × 100). Only known after stream end. */
+  currentCacheHitRatePct: number | null
+
+  /**
+   * Cross-call token-usage breakdown (Haiku rewriter/classifier/summarizer
+   * + routed-answer telemetry). Null until the SSE trailing usage frame
+   * arrives. Always null in Mingo mode.
+   */
+  currentUsageBreakdown: UnifiedUsageBreakdown | null
+}

package/src/components/index.ts

@@ -65,6 +65,14 @@ export * from './shared/onboarding'
 // Product Release components
 export * from './shared/product-release'
 
+// Dev-center shared components (Roadmap / Delivery / DevSectionView chrome)
+export * from './shared/dev-section'
+export * from './shared/roadmap'
+export * from './shared/delivery'
+
+// Legal-document shared component (privacy policy, terms of service)
+export * from './shared/legal-document'
+
 // Detail Page Skeleton
 export { DetailPageSkeleton, type DetailPageSkeletonProps } from './shared/detail-page-skeleton'
 

package/src/components/shared/delivery/delivery-lists.tsx

@@ -0,0 +1,199 @@
+'use client';
+
+/**
+ * DeliveryLists — the delivery section body (two tables: recently
+ * completed + active). Reads `search` and `task_type` URL params
+ * written by the shared `<DevSectionView>` chrome and refetches on
+ * change.
+ *
+ * Endpoint configuration:
+ *   - `completedApiEndpoint` / `inProgressApiEndpoint` are the two
+ *     per-bucket GET endpoints. Defaults match the hub's pre-migration
+ *     routes (`/api/delivery/completed`, `/api/delivery/in-progress`).
+ *
+ * Coupling constraint — `searchParamKey` / `taskTypeParamKey`:
+ *   These props serve TWO purposes:
+ *     1. URL READS — keys this component reads via `useSearchParams()`.
+ *        MUST match the consuming chrome's `section.search.paramKey` /
+ *        `section.filter.paramKey` (the chrome WRITES the URL params).
+ *     2. API WRITES — keys this component sends as query params on the
+ *        outbound fetch to `{completedApiEndpoint,inProgressApiEndpoint}`.
+ *        The hub API contract uses `'search'` / `'task_type'`; embedders
+ *        reverse-proxying those routes must preserve the same names OR
+ *        rewrite the inbound query string on the proxy side.
+ *
+ *   Defaults align with `OPENFRAME_DEV_SECTIONS.delivery.{search.paramKey,filter.paramKey}`
+ *   AND the hub API contract, so the OpenFrame zero-config case "just
+ *   works". Custom chrome overriding the param keys must override BOTH
+ *   ends consistently AND ensure the backend reads the same names.
+ */
+
+import { useEffect, useState } from 'react';
+import { useSearchParams, useRouter, usePathname } from '../../../embed-shims';
+import type { DeliveryResponse } from '../../../types/delivery';
+import { DeliveryTable } from './delivery-table';
+import { EmptyState } from '../../empty-state';
+import { LoadError } from '../../ui/error-state';
+
+const DEFAULT_COMPLETED_ENDPOINT = '/api/delivery/completed';
+const DEFAULT_IN_PROGRESS_ENDPOINT = '/api/delivery/in-progress';
+const DEFAULT_SEARCH_PARAM_KEY = 'search';
+const DEFAULT_TASK_TYPE_PARAM_KEY = 'task_type';
+
+export interface DeliveryListsProps {
+  /** GET endpoint for the "Recently Completed" bucket. Default
+   *  `/api/delivery/completed`. */
+  completedApiEndpoint?: string;
+  /** GET endpoint for the "Active Tasks" bucket. Default
+   *  `/api/delivery/in-progress`. */
+  inProgressApiEndpoint?: string;
+  /** URL param key for the search input. MUST match the consuming
+   *  chrome's `section.search.paramKey`. Default `'search'`. */
+  searchParamKey?: string;
+  /** URL param key for the task-type filter. MUST match the consuming
+   *  chrome's `section.filter.paramKey`. Default `'task_type'`. */
+  taskTypeParamKey?: string;
+}
+
+export function DeliveryLists({
+  completedApiEndpoint = DEFAULT_COMPLETED_ENDPOINT,
+  inProgressApiEndpoint = DEFAULT_IN_PROGRESS_ENDPOINT,
+  searchParamKey = DEFAULT_SEARCH_PARAM_KEY,
+  taskTypeParamKey = DEFAULT_TASK_TYPE_PARAM_KEY,
+}: DeliveryListsProps = {}) {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  const [data, setData] = useState<DeliveryResponse | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Get filter state from URL
+  const searchQuery = searchParams.get(searchParamKey) || '';
+  const taskTypeFilter = searchParams.get(taskTypeParamKey) || 'all';
+
+  useEffect(() => {
+    async function fetchDeliveryData() {
+      try {
+        setIsLoading(true);
+        setError(null);
+
+        // Build query parameters for filtering. The outbound key names
+        // mirror the inbound URL-param keys — see "Coupling constraint"
+        // in the file docblock for why.
+        const params = new URLSearchParams();
+        if (searchQuery) {
+          params.set(searchParamKey, searchQuery);
+        }
+        if (taskTypeFilter && taskTypeFilter !== 'all') {
+          params.set(taskTypeParamKey, taskTypeFilter);
+        }
+        const queryString = params.toString();
+        const queryParam = queryString ? `?${queryString}` : '';
+
+        // Fetch completed and in-progress tasks separately with filters
+        const [completedResponse, inProgressResponse] = await Promise.all([
+          fetch(`${completedApiEndpoint}${queryParam}`),
+          fetch(`${inProgressApiEndpoint}${queryParam}`),
+        ]);
+
+        if (!completedResponse.ok || !inProgressResponse.ok) {
+          throw new Error('Failed to fetch delivery items');
+        }
+
+        const [completedResult, inProgressResult] = await Promise.all([
+          completedResponse.json(),
+          inProgressResponse.json(),
+        ]);
+
+        setData({
+          completed: completedResult.items || [],
+          inProgress: inProgressResult.items || [],
+        });
+      } catch (err) {
+        console.error('Error fetching delivery items:', err);
+        setError('Failed to load delivery items. Please try again later.');
+      } finally {
+        setIsLoading(false);
+      }
+    }
+
+    fetchDeliveryData();
+  }, [searchQuery, taskTypeFilter, completedApiEndpoint, inProgressApiEndpoint, searchParamKey, taskTypeParamKey]);
+
+  const filteredCompleted = data?.completed || [];
+  const filteredInProgress = data?.inProgress || [];
+
+  const showCompleted = true;
+  const showInProgress = true;
+
+  const hasActiveFilters = searchQuery !== '' || taskTypeFilter !== 'all';
+  const hasResults = (showCompleted && filteredCompleted.length > 0) || (showInProgress && filteredInProgress.length > 0);
+
+  // Error state — consume lib's canonical LoadError so ODS tokens +
+  // retry affordance stay in lockstep with every other surface.
+  if (error) {
+    return (
+      <div className="w-full">
+        <LoadError message={error} onRetry={() => window.location.reload()} />
+      </div>
+    );
+  }
+
+  return (
+    <div className="w-full flex flex-col gap-[40px]">
+      {/* Empty state if no results after filtering */}
+      {!isLoading && !hasResults && (
+        hasActiveFilters ? (
+          <EmptyState
+            type="search"
+            title="No tasks found"
+            description="No tasks match your current filters. Try adjusting your search or status filter."
+            showCTA={true}
+            ctaText="Reset Filters"
+            onCtaClick={() => {
+              const params = new URLSearchParams(searchParams.toString());
+              params.delete(searchParamKey);
+              params.delete(taskTypeParamKey);
+              router.replace(`${pathname}?${params.toString()}`, { scroll: false });
+            }}
+          />
+        ) : (
+          <EmptyState
+            type="generic"
+            title="No tasks available"
+            description="Check back soon for upcoming tasks!"
+            showCTA={false}
+          />
+        )
+      )}
+
+      {/* Completed Tasks Table */}
+      {showCompleted && (hasResults || isLoading) && (
+        <div className="w-full">
+          <h3 className="text-h2 text-ods-text-primary tracking-[-0.48px] md:tracking-[-0.56px] lg:tracking-[-0.64px] mb-4">
+            Recently Completed<span className="text-ods-accent">:</span>
+          </h3>
+          <DeliveryTable
+            items={filteredCompleted}
+            isLoading={isLoading}
+          />
+        </div>
+      )}
+
+      {/* In Progress Tasks Table */}
+      {showInProgress && (hasResults || isLoading) && (
+        <div className="w-full">
+          <h3 className="text-h2 text-ods-text-primary tracking-[-0.48px] md:tracking-[-0.56px] lg:tracking-[-0.64px] mb-4">
+            Active Tasks<span className="text-ods-accent">:</span>
+          </h3>
+          <DeliveryTable
+            items={filteredInProgress}
+            isLoading={isLoading}
+          />
+        </div>
+      )}
+    </div>
+  );
+}