@surf-kit/agent 0.1.1

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 surf-kit contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @surf-kit/agent
+
+> AI agent interface components — the building blocks no other design system has
+
+Part of the [surf-kit](https://github.com/barney-w/surf-kit) design system.
+
+## Install
+
+```bash
+npm install @surf-kit/agent @surf-kit/core @surf-kit/theme @surf-kit/tokens
+```
+
+## Quick Example
+
+```tsx
+import { ThemeProvider } from '@surf-kit/theme';
+import { AgentChat } from '@surf-kit/agent';
+import '@surf-kit/tokens/css';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <AgentChat
+        agentName="Assistant"
+        messages={messages}
+        onSend={handleSend}
+      />
+    </ThemeProvider>
+  );
+}
+```
+
+## What's Included
+
+**Chat** — AgentChat, MessageThread, MessageBubble, MessageComposer, WelcomeScreen, ConversationList
+
+**Streaming** — StreamingMessage, ThinkingIndicator, ToolExecution, RetrievalProgress, VerificationProgress, TypewriterText
+
+**Trust & Confidence** — ConfidenceBadge, ConfidenceMeter, ConfidenceBreakdown, VerificationBadge, VerificationDetail
+
+**Sources** — SourceCard, SourceList, SourceInline, SourceDrawer, SourceBadge
+
+**Agent Identity** — AgentAvatar, AgentLabel, AgentHandoff, RoutingIndicator
+
+**Feedback** — ThumbsFeedback, FeedbackDialog, FeedbackConfirmation
+
+**Response** — AgentResponse, ResponseMessage, StructuredResponse, FollowUpChips, ErrorResponse
+
+**Layouts** — AgentFullPage, AgentPanel, AgentWidget, AgentEmbed
+
+**Hooks** (via `@surf-kit/agent/hooks`) — useAgentChat, useStreaming, useConversation, useFeedback, useAgentTheme, useCharacterDrain
+
+## Docs
+
+- [Storybook](https://barney-w.github.io/surf-kit/storybook)
+- [Contributing](https://github.com/barney-w/surf-kit/blob/main/CONTRIBUTING.md)
+
+## License
+
+[0BSD](./LICENSE)

package/dist/hooks-B8CSeOsn.d.cts

@@ -0,0 +1,232 @@
+import React from 'react';
+
+interface Source {
+    title: string;
+    section?: string;
+    document_id: string;
+    url: string;
+    confidence: number;
+    snippet: string;
+}
+interface ConfidenceBreakdown {
+    overall: 'high' | 'medium' | 'low';
+    retrieval_quality: number;
+    source_authority: number;
+    answer_groundedness: number;
+    recency: number;
+    reasoning: string;
+}
+interface VerificationResult {
+    status: 'passed' | 'flagged' | 'failed';
+    flags: string[];
+    claims_checked: number;
+    claims_verified: number;
+}
+interface AgentResponse {
+    message: string;
+    sources: Source[];
+    confidence: ConfidenceBreakdown;
+    verification: VerificationResult;
+    ui_hint: 'text' | 'table' | 'card' | 'list' | 'steps' | 'warning';
+    structured_data: Record<string, unknown> | null;
+    follow_up_suggestions: string[];
+}
+interface AgentInfo {
+    id: string;
+    label: string;
+    accent?: string;
+    icon?: React.ComponentType<{
+        size?: number;
+        className?: string;
+    }>;
+}
+
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    response?: AgentResponse;
+    agent?: string;
+    timestamp: Date;
+}
+interface ConversationSummary {
+    id: string;
+    title: string;
+    lastMessage: string;
+    updatedAt: Date;
+    messageCount: number;
+}
+interface ChatError {
+    code: 'NETWORK_ERROR' | 'API_ERROR' | 'STREAM_ERROR' | 'TIMEOUT';
+    message: string;
+    retryable: boolean;
+}
+
+type StreamEvent = {
+    type: 'phase';
+    phase: 'thinking' | 'retrieving' | 'generating' | 'verifying' | 'waiting';
+} | {
+    type: 'delta';
+    content: string;
+} | {
+    type: 'source';
+    source: Source;
+} | {
+    type: 'agent';
+    agent: string;
+} | {
+    type: 'verification';
+    result: VerificationResult;
+} | {
+    type: 'confidence';
+    breakdown: ConfidenceBreakdown;
+} | {
+    type: 'done';
+    response: AgentResponse;
+    conversation_id?: string;
+} | {
+    type: 'error';
+    error: ChatError;
+};
+interface StreamState {
+    active: boolean;
+    phase: 'idle' | 'thinking' | 'retrieving' | 'generating' | 'verifying' | 'waiting';
+    content: string;
+    sources: Source[];
+    agent: string | null;
+    agentLabel: string | null;
+}
+
+interface AgentChatConfig {
+    /** Base URL for the agent API */
+    apiUrl: string;
+    /** SSE endpoint path (appended to apiUrl) */
+    streamPath?: string;
+    /** Feedback endpoint path (appended to apiUrl) */
+    feedbackPath?: string;
+    /** Conversations endpoint path (appended to apiUrl) */
+    conversationsPath?: string;
+    /** Request headers (e.g. Authorization) */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Enable localStorage persistence for conversations */
+    persistConversations?: boolean;
+    /** Map of agent IDs to their display config */
+    agentThemes?: Record<string, AgentInfo>;
+}
+
+interface AgentChatState {
+    messages: ChatMessage[];
+    conversationId: string | null;
+    isLoading: boolean;
+    error: ChatError | null;
+    inputValue: string;
+    streamPhase: StreamState['phase'];
+    streamingContent: string;
+}
+interface AgentChatActions {
+    sendMessage: (content: string) => Promise<void>;
+    setInputValue: (value: string) => void;
+    loadConversation: (conversationId: string, messages: ChatMessage[]) => void;
+    submitFeedback: (messageId: string, rating: 'positive' | 'negative', comment?: string) => Promise<void>;
+    retry: () => Promise<void>;
+    reset: () => void;
+}
+declare function useAgentChat(config: AgentChatConfig): {
+    state: AgentChatState;
+    actions: AgentChatActions;
+};
+
+interface UseStreamingOptions {
+    /** SSE endpoint URL */
+    url: string;
+    /** Additional headers for fetch-based SSE (not used with native EventSource) */
+    headers?: Record<string, string>;
+    /** Called when a complete response is received */
+    onDone?: (event: Extract<StreamEvent, {
+        type: 'done';
+    }>) => void;
+    /** Called on error */
+    onError?: (event: Extract<StreamEvent, {
+        type: 'error';
+    }>) => void;
+}
+declare function useStreaming(options: UseStreamingOptions): {
+    state: StreamState;
+    start: (body: Record<string, unknown>) => Promise<void>;
+    stop: () => void;
+};
+
+interface Conversation {
+    id: string;
+    title: string;
+    messages: ChatMessage[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface UseConversationOptions {
+    /** Enable localStorage persistence */
+    persist?: boolean;
+    /** localStorage key prefix */
+    storageKey?: string;
+}
+declare function useConversation(options?: UseConversationOptions): {
+    conversations: Conversation[];
+    current: Conversation | null;
+    create: (title?: string) => Conversation;
+    list: () => ConversationSummary[];
+    load: (id: string) => Conversation | null;
+    delete: (id: string) => void;
+    rename: (id: string, title: string) => void;
+    addMessage: (conversationId: string, message: ChatMessage) => void;
+};
+
+type FeedbackState = 'idle' | 'submitting' | 'submitted' | 'error';
+interface UseFeedbackOptions {
+    /** API endpoint URL for feedback submission */
+    url: string;
+    /** Additional request headers */
+    headers?: Record<string, string>;
+}
+interface FeedbackPayload {
+    messageId: string;
+    rating: 'positive' | 'negative';
+    comment?: string;
+}
+declare function useFeedback(options: UseFeedbackOptions): {
+    state: FeedbackState;
+    error: string | null;
+    submit: (messageId: string, rating: "positive" | "negative", comment?: string) => Promise<void>;
+    reset: () => void;
+};
+
+interface AgentThemeResult {
+    accent: string;
+    icon: AgentInfo['icon'] | null;
+    label: string;
+}
+declare function useAgentTheme(agentId: string | null | undefined, agentThemes?: Record<string, AgentInfo>): AgentThemeResult;
+
+interface CharacterDrainResult {
+    displayed: string;
+    isDraining: boolean;
+}
+/**
+ * Smoothly drains a growing `target` string character-by-character using
+ * `requestAnimationFrame`, decoupling visual rendering from network packet
+ * timing so text appears to type out instead of arriving in chunks.
+ *
+ * When `target` resets to empty (e.g. stream finished), the hook continues
+ * draining the previous content to completion before resetting, so the
+ * typing animation isn't cut short.
+ *
+ * Design: the RAF loop is long-lived — it does NOT restart on every delta.
+ * The tick function is stored in a ref (updated each render) so the loop
+ * always reads the latest drainTarget without being cancelled/restarted.
+ * A separate kick-start effect re-fires the loop when it was idle and new
+ * content arrives.
+ */
+declare function useCharacterDrain(target: string, msPerChar?: number): CharacterDrainResult;
+
+export { type AgentResponse as A, type ChatMessage as C, type FeedbackPayload as F, type Source as S, type UseConversationOptions as U, type VerificationResult as V, type ChatError as a, type ConfidenceBreakdown as b, type AgentInfo as c, type StreamState as d, type ConversationSummary as e, type AgentChatActions as f, type AgentChatConfig as g, type AgentChatState as h, type AgentThemeResult as i, type CharacterDrainResult as j, type Conversation as k, type FeedbackState as l, type StreamEvent as m, type UseFeedbackOptions as n, type UseStreamingOptions as o, useAgentTheme as p, useCharacterDrain as q, useConversation as r, useFeedback as s, useStreaming as t, useAgentChat as u };

package/dist/hooks-B8CSeOsn.d.ts

@@ -0,0 +1,232 @@
+import React from 'react';
+
+interface Source {
+    title: string;
+    section?: string;
+    document_id: string;
+    url: string;
+    confidence: number;
+    snippet: string;
+}
+interface ConfidenceBreakdown {
+    overall: 'high' | 'medium' | 'low';
+    retrieval_quality: number;
+    source_authority: number;
+    answer_groundedness: number;
+    recency: number;
+    reasoning: string;
+}
+interface VerificationResult {
+    status: 'passed' | 'flagged' | 'failed';
+    flags: string[];
+    claims_checked: number;
+    claims_verified: number;
+}
+interface AgentResponse {
+    message: string;
+    sources: Source[];
+    confidence: ConfidenceBreakdown;
+    verification: VerificationResult;
+    ui_hint: 'text' | 'table' | 'card' | 'list' | 'steps' | 'warning';
+    structured_data: Record<string, unknown> | null;
+    follow_up_suggestions: string[];
+}
+interface AgentInfo {
+    id: string;
+    label: string;
+    accent?: string;
+    icon?: React.ComponentType<{
+        size?: number;
+        className?: string;
+    }>;
+}
+
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    response?: AgentResponse;
+    agent?: string;
+    timestamp: Date;
+}
+interface ConversationSummary {
+    id: string;
+    title: string;
+    lastMessage: string;
+    updatedAt: Date;
+    messageCount: number;
+}
+interface ChatError {
+    code: 'NETWORK_ERROR' | 'API_ERROR' | 'STREAM_ERROR' | 'TIMEOUT';
+    message: string;
+    retryable: boolean;
+}
+
+type StreamEvent = {
+    type: 'phase';
+    phase: 'thinking' | 'retrieving' | 'generating' | 'verifying' | 'waiting';
+} | {
+    type: 'delta';
+    content: string;
+} | {
+    type: 'source';
+    source: Source;
+} | {
+    type: 'agent';
+    agent: string;
+} | {
+    type: 'verification';
+    result: VerificationResult;
+} | {
+    type: 'confidence';
+    breakdown: ConfidenceBreakdown;
+} | {
+    type: 'done';
+    response: AgentResponse;
+    conversation_id?: string;
+} | {
+    type: 'error';
+    error: ChatError;
+};
+interface StreamState {
+    active: boolean;
+    phase: 'idle' | 'thinking' | 'retrieving' | 'generating' | 'verifying' | 'waiting';
+    content: string;
+    sources: Source[];
+    agent: string | null;
+    agentLabel: string | null;
+}
+
+interface AgentChatConfig {
+    /** Base URL for the agent API */
+    apiUrl: string;
+    /** SSE endpoint path (appended to apiUrl) */
+    streamPath?: string;
+    /** Feedback endpoint path (appended to apiUrl) */
+    feedbackPath?: string;
+    /** Conversations endpoint path (appended to apiUrl) */
+    conversationsPath?: string;
+    /** Request headers (e.g. Authorization) */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Enable localStorage persistence for conversations */
+    persistConversations?: boolean;
+    /** Map of agent IDs to their display config */
+    agentThemes?: Record<string, AgentInfo>;
+}
+
+interface AgentChatState {
+    messages: ChatMessage[];
+    conversationId: string | null;
+    isLoading: boolean;
+    error: ChatError | null;
+    inputValue: string;
+    streamPhase: StreamState['phase'];
+    streamingContent: string;
+}
+interface AgentChatActions {
+    sendMessage: (content: string) => Promise<void>;
+    setInputValue: (value: string) => void;
+    loadConversation: (conversationId: string, messages: ChatMessage[]) => void;
+    submitFeedback: (messageId: string, rating: 'positive' | 'negative', comment?: string) => Promise<void>;
+    retry: () => Promise<void>;
+    reset: () => void;
+}
+declare function useAgentChat(config: AgentChatConfig): {
+    state: AgentChatState;
+    actions: AgentChatActions;
+};
+
+interface UseStreamingOptions {
+    /** SSE endpoint URL */
+    url: string;
+    /** Additional headers for fetch-based SSE (not used with native EventSource) */
+    headers?: Record<string, string>;
+    /** Called when a complete response is received */
+    onDone?: (event: Extract<StreamEvent, {
+        type: 'done';
+    }>) => void;
+    /** Called on error */
+    onError?: (event: Extract<StreamEvent, {
+        type: 'error';
+    }>) => void;
+}
+declare function useStreaming(options: UseStreamingOptions): {
+    state: StreamState;
+    start: (body: Record<string, unknown>) => Promise<void>;
+    stop: () => void;
+};
+
+interface Conversation {
+    id: string;
+    title: string;
+    messages: ChatMessage[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface UseConversationOptions {
+    /** Enable localStorage persistence */
+    persist?: boolean;
+    /** localStorage key prefix */
+    storageKey?: string;
+}
+declare function useConversation(options?: UseConversationOptions): {
+    conversations: Conversation[];
+    current: Conversation | null;
+    create: (title?: string) => Conversation;
+    list: () => ConversationSummary[];
+    load: (id: string) => Conversation | null;
+    delete: (id: string) => void;
+    rename: (id: string, title: string) => void;
+    addMessage: (conversationId: string, message: ChatMessage) => void;
+};
+
+type FeedbackState = 'idle' | 'submitting' | 'submitted' | 'error';
+interface UseFeedbackOptions {
+    /** API endpoint URL for feedback submission */
+    url: string;
+    /** Additional request headers */
+    headers?: Record<string, string>;
+}
+interface FeedbackPayload {
+    messageId: string;
+    rating: 'positive' | 'negative';
+    comment?: string;
+}
+declare function useFeedback(options: UseFeedbackOptions): {
+    state: FeedbackState;
+    error: string | null;
+    submit: (messageId: string, rating: "positive" | "negative", comment?: string) => Promise<void>;
+    reset: () => void;
+};
+
+interface AgentThemeResult {
+    accent: string;
+    icon: AgentInfo['icon'] | null;
+    label: string;
+}
+declare function useAgentTheme(agentId: string | null | undefined, agentThemes?: Record<string, AgentInfo>): AgentThemeResult;
+
+interface CharacterDrainResult {
+    displayed: string;
+    isDraining: boolean;
+}
+/**
+ * Smoothly drains a growing `target` string character-by-character using
+ * `requestAnimationFrame`, decoupling visual rendering from network packet
+ * timing so text appears to type out instead of arriving in chunks.
+ *
+ * When `target` resets to empty (e.g. stream finished), the hook continues
+ * draining the previous content to completion before resetting, so the
+ * typing animation isn't cut short.
+ *
+ * Design: the RAF loop is long-lived — it does NOT restart on every delta.
+ * The tick function is stored in a ref (updated each render) so the loop
+ * always reads the latest drainTarget without being cancelled/restarted.
+ * A separate kick-start effect re-fires the loop when it was idle and new
+ * content arrives.
+ */
+declare function useCharacterDrain(target: string, msPerChar?: number): CharacterDrainResult;
+
+export { type AgentResponse as A, type ChatMessage as C, type FeedbackPayload as F, type Source as S, type UseConversationOptions as U, type VerificationResult as V, type ChatError as a, type ConfidenceBreakdown as b, type AgentInfo as c, type StreamState as d, type ConversationSummary as e, type AgentChatActions as f, type AgentChatConfig as g, type AgentChatState as h, type AgentThemeResult as i, type CharacterDrainResult as j, type Conversation as k, type FeedbackState as l, type StreamEvent as m, type UseFeedbackOptions as n, type UseStreamingOptions as o, useAgentTheme as p, useCharacterDrain as q, useConversation as r, useFeedback as s, useStreaming as t, useAgentChat as u };