@kognitivedev/ui 0.2.11

package/src/components/thread.tsx

@@ -0,0 +1,89 @@
+import React from "react";
+import { cn } from "../utils/cn";
+import { ThreadPrimitive } from "../primitives/thread";
+import { Message } from "./message";
+import { Composer } from "./composer";
+import { StatusIndicator } from "./status-indicator";
+import { ErrorBanner } from "./error-banner";
+import { Suggestions } from "./suggestions";
+import { useKognitiveContext } from "../context/kognitive-context";
+import type { ComponentType } from "react";
+
+export interface ThreadProps {
+    className?: string;
+    emptyState?: React.ReactNode;
+    allowAttachments?: boolean;
+    components?: {
+        Message?: ComponentType<{ message: any; index: number }>;
+        Composer?: ComponentType;
+    };
+}
+
+export function Thread({
+    className,
+    emptyState,
+    allowAttachments = false,
+    components,
+}: ThreadProps) {
+    const { status } = useKognitiveContext();
+    const MessageComponent = components?.Message ?? Message;
+    const ComposerComponent = components?.Composer ?? Composer;
+
+    return (
+        <ThreadPrimitive.Root
+            className={cn("flex h-full flex-col", className)}
+        >
+            {/* Status indicator */}
+            <div className="flex items-center justify-between border-b border-zinc-200 px-4 py-2 dark:border-zinc-700">
+                <StatusIndicator status={status} />
+            </div>
+
+            {/* Error banner */}
+            <ThreadPrimitive.Error className="px-4 pt-3">
+                {(error: Error) => <ErrorBanner message={error.message} />}
+            </ThreadPrimitive.Error>
+
+            {/* Messages area */}
+            <div className="flex-1 overflow-y-auto px-4" data-kognitive-thread-root>
+                <ThreadPrimitive.Empty>
+                    {emptyState ?? (
+                        <div className="flex h-full items-center justify-center text-zinc-400">
+                            <p>Start a conversation</p>
+                        </div>
+                    )}
+                </ThreadPrimitive.Empty>
+
+                <ThreadPrimitive.Messages>
+                    {(message, index) => (
+                        <MessageComponent key={message.id} message={message} index={index} />
+                    )}
+                </ThreadPrimitive.Messages>
+
+                <ThreadPrimitive.Loading>
+                    <div className="flex gap-3 py-4">
+                        <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-zinc-100 text-sm text-zinc-600 dark:bg-zinc-800 dark:text-zinc-400">
+                            A
+                        </div>
+                        <div className="flex items-center">
+                            <div className="flex gap-1">
+                                <div className="h-2 w-2 animate-bounce rounded-full bg-zinc-400" style={{ animationDelay: "0ms" }} />
+                                <div className="h-2 w-2 animate-bounce rounded-full bg-zinc-400" style={{ animationDelay: "150ms" }} />
+                                <div className="h-2 w-2 animate-bounce rounded-full bg-zinc-400" style={{ animationDelay: "300ms" }} />
+                            </div>
+                        </div>
+                    </div>
+                </ThreadPrimitive.Loading>
+
+                {/* Suggested follow-ups */}
+                <Suggestions />
+            </div>
+
+            {/* Composer */}
+            {components?.Composer ? (
+                <ComposerComponent />
+            ) : (
+                <Composer allowAttachments={allowAttachments} />
+            )}
+        </ThreadPrimitive.Root>
+    );
+}

package/src/components/tool-approval.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import { cn } from "../utils/cn";
+import { useKognitiveContext } from "../context/kognitive-context";
+
+export interface ToolApprovalProps {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    className?: string;
+}
+
+export function ToolApproval({ toolCallId, toolName, input, className }: ToolApprovalProps) {
+    const { onToolApproval } = useKognitiveContext();
+
+    if (!onToolApproval) return null;
+
+    return (
+        <div
+            className={cn(
+                "my-2 rounded-lg border border-amber-200 bg-amber-50 p-4 dark:border-amber-800 dark:bg-amber-950/30",
+                className,
+            )}
+            data-tool-approval={toolCallId}
+        >
+            <div className="mb-2 flex items-center gap-2">
+                <span className="text-amber-600">&#x26A0;</span>
+                <span className="text-sm font-medium">
+                    <strong>{toolName}</strong> requires approval
+                </span>
+            </div>
+            {input !== undefined && input !== null && (
+                <pre className="mb-3 overflow-auto rounded bg-amber-100/50 p-2 text-xs dark:bg-amber-900/20">
+                    {JSON.stringify(input, null, 2)}
+                </pre>
+            )}
+            <div className="flex gap-2">
+                <button
+                    type="button"
+                    onClick={() => onToolApproval(toolCallId, true)}
+                    className="rounded-lg bg-emerald-600 px-4 py-1.5 text-sm font-medium text-white hover:bg-emerald-700"
+                >
+                    Approve
+                </button>
+                <button
+                    type="button"
+                    onClick={() => onToolApproval(toolCallId, false)}
+                    className="rounded-lg border border-zinc-300 px-4 py-1.5 text-sm font-medium text-zinc-700 hover:bg-zinc-100 dark:border-zinc-600 dark:text-zinc-300 dark:hover:bg-zinc-800"
+                >
+                    Reject
+                </button>
+            </div>
+        </div>
+    );
+}

package/src/components/tool-invocation.tsx

@@ -0,0 +1,94 @@
+import React, { useState } from "react";
+import { cn } from "../utils/cn";
+import type { ToolUIRenderProps } from "../tool-ui/types";
+import { ToolApproval } from "./tool-approval";
+
+export interface ToolInvocationProps extends ToolUIRenderProps {
+    className?: string;
+}
+
+function isComplete(state: string): boolean {
+    return state === "output-available";
+}
+
+function stateLabel(state: string): string {
+    switch (state) {
+        case "input-streaming": return "streaming...";
+        case "input-available": return "calling...";
+        case "approval-requested": return "awaiting approval";
+        case "approval-responded": return "approved";
+        case "output-available": return "completed";
+        case "error": return "error";
+        default: return state;
+    }
+}
+
+export function ToolInvocation({
+    toolName,
+    toolCallId,
+    input,
+    output,
+    state,
+    className,
+}: ToolInvocationProps) {
+    const [expanded, setExpanded] = useState(false);
+    const done = isComplete(state);
+
+    if (state === "approval-requested") {
+        return <ToolApproval toolCallId={toolCallId} toolName={toolName} input={input} className={className} />;
+    }
+
+    return (
+        <div
+            className={cn(
+                "my-2 rounded-lg border border-zinc-200 dark:border-zinc-700",
+                className,
+            )}
+            data-tool={toolName}
+            data-tool-state={state}
+        >
+            <button
+                type="button"
+                onClick={() => setExpanded(!expanded)}
+                className="flex w-full items-center gap-2 px-3 py-2 text-left text-sm hover:bg-zinc-50 dark:hover:bg-zinc-800/50"
+                aria-expanded={expanded}
+            >
+                <span className="text-amber-500">&#x1F527;</span>
+                <span className="font-medium">{toolName}</span>
+                <span
+                    className={cn(
+                        "ml-auto rounded-full px-2 py-0.5 text-xs",
+                        done
+                            ? "bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-400"
+                            : state === "error"
+                              ? "bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400"
+                              : "bg-amber-100 text-amber-700 dark:bg-amber-900/30 dark:text-amber-400",
+                    )}
+                >
+                    {stateLabel(state)}
+                </span>
+                <span className="text-zinc-400">{expanded ? "\u25BC" : "\u25B6"}</span>
+            </button>
+            {expanded && (
+                <div className="border-t border-zinc-200 px-3 py-2 dark:border-zinc-700">
+                    {input !== undefined && (
+                        <div className="mb-2">
+                            <div className="mb-1 text-xs font-medium text-zinc-500">Arguments</div>
+                            <pre className="overflow-auto rounded bg-zinc-50 p-2 text-xs dark:bg-zinc-800/50">
+                                {JSON.stringify(input, null, 2)}
+                            </pre>
+                        </div>
+                    )}
+                    {output !== undefined && (
+                        <div>
+                            <div className="mb-1 text-xs font-medium text-zinc-500">Result</div>
+                            <pre className="overflow-auto rounded bg-zinc-50 p-2 text-xs dark:bg-zinc-800/50">
+                                {JSON.stringify(output, null, 2)}
+                            </pre>
+                        </div>
+                    )}
+                </div>
+            )}
+        </div>
+    );
+}

package/src/context/kognitive-context.tsx

@@ -0,0 +1,8 @@
+import { createContext } from "../utils/create-context";
+import type { KognitiveContextValue } from "./types";
+
+export const [
+    KognitiveContextProvider,
+    useKognitiveContext,
+    KognitiveContext,
+] = createContext<KognitiveContextValue>("Kognitive");

package/src/context/types.ts

@@ -0,0 +1,43 @@
+import type { UIMessage, ChatStatus, FileUIPart } from "ai";
+import type { ThreadManager } from "../runtime/thread-manager";
+import type { ToolUIRegistry } from "../tool-ui/registry";
+import type { ThreadSummary } from "../runtime/types";
+
+export interface KognitiveContextValue {
+    /** Current messages in the thread */
+    messages: UIMessage[];
+    /** Send a message to the agent */
+    send: (text: string, options?: { files?: FileUIPart[] }) => void;
+    /** Current runtime status */
+    status: ChatStatus;
+    /** Whether the agent is currently streaming */
+    isStreaming: boolean;
+    /** Stop the current stream */
+    stop: () => void;
+    /** Replace the message list */
+    setMessages: (messages: UIMessage[]) => void;
+    /** Thread manager (null if threads not enabled) */
+    threadManager: ThreadManager | null;
+    /** Tool UI registry */
+    toolUIRegistry: ToolUIRegistry;
+    /** Active session ID */
+    activeSessionId: string | null;
+    /** Switch to a different thread */
+    setActiveSessionId: (sessionId: string | null) => void;
+    /** List of threads (empty if threads not enabled) */
+    threads: ThreadSummary[];
+    /** Reload threads list */
+    refreshThreads: () => Promise<void>;
+    /** Create a new thread and switch to it */
+    createThread: () => Promise<void>;
+    /** Agent name */
+    agentName: string;
+    /** Current error (from stream or network failure) */
+    error: Error | undefined;
+    /** Feedback callback — called when user rates a message */
+    onFeedback?: (messageId: string, type: "positive" | "negative") => void;
+    /** Tool approval callback — called when user approves/rejects a tool call */
+    onToolApproval?: (toolCallId: string, approved: boolean) => void;
+    /** Suggested follow-up prompts shown after assistant responds */
+    suggestions: string[];
+}

package/src/context/use-kognitive.ts

@@ -0,0 +1,5 @@
+import { useKognitiveContext } from "./kognitive-context";
+
+export function useKognitive() {
+    return useKognitiveContext();
+}

package/src/hooks/use-auto-scroll.ts

@@ -0,0 +1,19 @@
+import { useEffect, useRef, type RefObject } from "react";
+
+export function useAutoScroll(
+    deps: unknown[],
+    containerRef?: RefObject<HTMLElement | null>,
+): RefObject<HTMLDivElement | null> {
+    const endRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (containerRef?.current) {
+            containerRef.current.scrollTop = containerRef.current.scrollHeight;
+        } else {
+            endRef.current?.scrollIntoView({ behavior: "smooth" });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+
+    return endRef;
+}

package/src/hooks/use-copy-to-clipboard.ts

@@ -0,0 +1,16 @@
+import { useState, useCallback } from "react";
+
+export function useCopyToClipboard(resetDelay = 2000) {
+    const [copied, setCopied] = useState(false);
+
+    const copy = useCallback(
+        async (text: string) => {
+            await navigator.clipboard.writeText(text);
+            setCopied(true);
+            setTimeout(() => setCopied(false), resetDelay);
+        },
+        [resetDelay],
+    );
+
+    return { copied, copy };
+}

package/src/hooks/use-keyboard-shortcuts.ts

@@ -0,0 +1,34 @@
+import { useEffect } from "react";
+
+export interface KeyboardShortcut {
+    key: string;
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+    handler: () => void;
+}
+
+export function useKeyboardShortcuts(shortcuts: KeyboardShortcut[]) {
+    useEffect(() => {
+        function handleKeyDown(e: KeyboardEvent) {
+            for (const shortcut of shortcuts) {
+                const ctrlOrMeta = shortcut.ctrl || shortcut.meta;
+                const matchesMod = ctrlOrMeta ? (e.ctrlKey || e.metaKey) : true;
+                const matchesShift = shortcut.shift ? e.shiftKey : !e.shiftKey;
+
+                if (
+                    e.key.toLowerCase() === shortcut.key.toLowerCase() &&
+                    matchesMod &&
+                    matchesShift
+                ) {
+                    e.preventDefault();
+                    shortcut.handler();
+                    return;
+                }
+            }
+        }
+
+        document.addEventListener("keydown", handleKeyDown);
+        return () => document.removeEventListener("keydown", handleKeyDown);
+    }, [shortcuts]);
+}

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

@@ -0,0 +1,73 @@
+import { useMemo } from "react";
+import { useChat } from "@ai-sdk/react";
+import type { UIMessage, FileUIPart, ChatStatus } from "ai";
+import { createKognitiveTransport } from "../runtime/kognitive-transport";
+
+export interface UseKognitiveChatConfig {
+    /** Explicit API endpoint URL (e.g., "/api/chat"). Takes priority over baseUrl+agentName. */
+    api?: string;
+    /** Agent name to connect to */
+    agentName?: string;
+    /** Base URL of the Kognitive runtime */
+    baseUrl?: string;
+    /** Current session/thread ID */
+    sessionId?: string;
+    /** User identity */
+    resourceId?: { userId?: string; sessionId?: string; organizationId?: string };
+    /** Additional headers (e.g., auth) */
+    headers?: Record<string, string>;
+    /** Extra body fields merged into every request */
+    body?: Record<string, unknown>;
+}
+
+export interface UseKognitiveChatReturn {
+    /** Current messages */
+    messages: UIMessage[];
+    /** Send a text message, optionally with file attachments */
+    send: (text: string, options?: { files?: FileUIPart[] }) => void;
+    /** Current status */
+    status: ChatStatus;
+    /** Whether the agent is streaming */
+    isStreaming: boolean;
+    /** Stop the current stream */
+    stop: () => void;
+    /** Replace the message list */
+    setMessages: (messages: UIMessage[]) => void;
+}
+
+export function useKognitiveChat(config: UseKognitiveChatConfig): UseKognitiveChatReturn {
+    const transport = useMemo(
+        () =>
+            createKognitiveTransport({
+                api: config.api,
+                baseUrl: config.baseUrl,
+                agentName: config.agentName,
+                sessionId: config.sessionId,
+                resourceId: config.resourceId,
+                headers: config.headers,
+                body: config.body,
+            }),
+        [config.api, config.baseUrl, config.agentName, config.sessionId, config.resourceId, config.headers, config.body],
+    );
+
+    const { messages, sendMessage, status, stop, setMessages } = useChat({
+        transport,
+    });
+
+    const send = (text: string, options?: { files?: FileUIPart[] }) => {
+        const parts: UIMessage["parts"] = [{ type: "text" as const, text }];
+        if (options?.files) {
+            parts.push(...options.files);
+        }
+        sendMessage({ role: "user", parts });
+    };
+
+    return {
+        messages,
+        send,
+        status,
+        isStreaming: status === "streaming",
+        stop,
+        setMessages,
+    };
+}

package/src/hooks/use-kognitive-event.ts

@@ -0,0 +1,56 @@
+import { useEffect, useRef } from "react";
+
+export type KognitiveEventType =
+    | "message:send"
+    | "message:received"
+    | "status:change"
+    | "tool:invoked"
+    | "tool:completed"
+    | "error";
+
+export type KognitiveEventHandler = (data: unknown) => void;
+
+export class KognitiveEventEmitter {
+    private listeners = new Map<KognitiveEventType, Set<KognitiveEventHandler>>();
+
+    on(event: KognitiveEventType, handler: KognitiveEventHandler): () => void {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event)!.add(handler);
+        return () => {
+            this.listeners.get(event)?.delete(handler);
+        };
+    }
+
+    emit(event: KognitiveEventType, data?: unknown): void {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(data);
+                } catch {
+                    // Swallow listener errors
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Subscribe to Kognitive lifecycle events.
+ * The handler is automatically cleaned up on unmount.
+ */
+export function useKognitiveEvent(
+    emitter: KognitiveEventEmitter | undefined,
+    event: KognitiveEventType,
+    handler: KognitiveEventHandler,
+): void {
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+
+    useEffect(() => {
+        if (!emitter) return;
+        return emitter.on(event, (data) => handlerRef.current(data));
+    }, [emitter, event]);
+}

package/src/hooks/use-streaming-status.ts

@@ -0,0 +1,7 @@
+import { useKognitiveContext } from "../context/kognitive-context";
+import type { ChatStatus } from "ai";
+
+export function useStreamingStatus(): ChatStatus {
+    const { status } = useKognitiveContext();
+    return status;
+}

package/src/hooks/use-thread-manager.ts

@@ -0,0 +1,114 @@
+import { useState, useEffect, useCallback } from "react";
+import { ThreadManager, type ThreadManagerConfig } from "../runtime/thread-manager";
+import type { ThreadSummary, ThreadDetail } from "../runtime/types";
+
+export interface UseThreadManagerConfig extends ThreadManagerConfig {
+    /** Auto-create a thread if none exist */
+    autoCreate?: boolean;
+}
+
+export interface UseThreadManagerReturn {
+    threads: ThreadSummary[];
+    activeSessionId: string | null;
+    threadDetail: ThreadDetail | null;
+    loadingThreads: boolean;
+    loadingThread: boolean;
+    setActiveSessionId: (sessionId: string | null) => void;
+    createThread: () => Promise<ThreadSummary>;
+    forkThread: (sessionId: string) => Promise<ThreadSummary>;
+    interruptThread: (sessionId: string) => Promise<void>;
+    refreshThreads: () => Promise<void>;
+    refreshThreadDetail: () => Promise<void>;
+}
+
+export function useThreadManager(config: UseThreadManagerConfig): UseThreadManagerReturn {
+    const [manager] = useState(() => new ThreadManager(config));
+    const [threads, setThreads] = useState<ThreadSummary[]>([]);
+    const [activeSessionId, setActiveSessionId] = useState<string | null>(null);
+    const [threadDetail, setThreadDetail] = useState<ThreadDetail | null>(null);
+    const [loadingThreads, setLoadingThreads] = useState(true);
+    const [loadingThread, setLoadingThread] = useState(false);
+
+    const refreshThreads = useCallback(
+        async (preferredSessionId?: string) => {
+            setLoadingThreads(true);
+            try {
+                const nextThreads = await manager.list();
+                setThreads(nextThreads);
+
+                if (preferredSessionId) {
+                    setActiveSessionId(preferredSessionId);
+                } else if (!activeSessionId && nextThreads.length > 0) {
+                    setActiveSessionId(nextThreads[0].sessionId);
+                } else if (nextThreads.length === 0 && config.autoCreate) {
+                    const thread = await manager.create();
+                    setThreads([thread]);
+                    setActiveSessionId(thread.sessionId);
+                }
+            } finally {
+                setLoadingThreads(false);
+            }
+        },
+        [manager, activeSessionId, config.autoCreate],
+    );
+
+    const refreshThreadDetail = useCallback(async () => {
+        if (!activeSessionId) return;
+        setLoadingThread(true);
+        try {
+            const detail = await manager.get(activeSessionId);
+            setThreadDetail(detail);
+        } finally {
+            setLoadingThread(false);
+        }
+    }, [manager, activeSessionId]);
+
+    const createThread = useCallback(async () => {
+        const thread = await manager.create();
+        await refreshThreads(thread.sessionId);
+        return thread;
+    }, [manager, refreshThreads]);
+
+    const forkThread = useCallback(
+        async (sessionId: string) => {
+            const thread = await manager.fork(sessionId);
+            await refreshThreads(thread.sessionId);
+            return thread;
+        },
+        [manager, refreshThreads],
+    );
+
+    const interruptThread = useCallback(
+        async (sessionId: string) => {
+            await manager.interrupt(sessionId);
+            await refreshThreads(sessionId);
+            await refreshThreadDetail();
+        },
+        [manager, refreshThreads, refreshThreadDetail],
+    );
+
+    useEffect(() => {
+        void refreshThreads();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    useEffect(() => {
+        if (activeSessionId) {
+            void refreshThreadDetail();
+        }
+    }, [activeSessionId, refreshThreadDetail]);
+
+    return {
+        threads,
+        activeSessionId,
+        threadDetail,
+        loadingThreads,
+        loadingThread,
+        setActiveSessionId,
+        createThread,
+        forkThread,
+        interruptThread,
+        refreshThreads: () => refreshThreads(),
+        refreshThreadDetail,
+    };
+}