@kognitivedev/ui 0.2.11

package/src/index.ts

@@ -0,0 +1,56 @@
+// ── Root Provider ──
+export { KognitiveUI, type KognitiveUIProps } from "./kognitive-ui";
+
+// ── Tool UI System ──
+export { makeToolUI, type MakeToolUIOptions, type MakeToolUIByNameOptions } from "./tool-ui/make-tool-ui";
+export { toolkit, type ToolkitEntry } from "./tool-ui/toolkit";
+export { ToolUIRegistry } from "./tool-ui/registry";
+export type { ToolUIRegistration, ToolUIRenderProps, ToolUIComponent } from "./tool-ui/types";
+
+// ── Primitives ──
+export { ThreadPrimitive } from "./primitives/thread";
+export { MessagePrimitive } from "./primitives/message";
+export { ComposerPrimitive } from "./primitives/composer";
+export { ActionBarPrimitive } from "./primitives/action-bar";
+export { ToolUIPrimitive } from "./primitives/tool-ui";
+export { ThreadListPrimitive } from "./primitives/thread-list";
+
+// ── Composed Components ──
+export { Thread } from "./components/thread";
+export { Message } from "./components/message";
+export { Composer } from "./components/composer";
+export { ThreadList } from "./components/thread-list";
+export { ToolInvocation } from "./components/tool-invocation";
+export { ToolApproval } from "./components/tool-approval";
+export { MarkdownContent } from "./components/markdown-content";
+export { AttachmentPreview } from "./components/attachment-preview";
+export { StatusIndicator } from "./components/status-indicator";
+export { ErrorBanner } from "./components/error-banner";
+export { Suggestions } from "./components/suggestions";
+
+// ── Hooks ──
+export { useKognitiveChat, type UseKognitiveChatConfig, type UseKognitiveChatReturn } from "./hooks/use-kognitive-chat";
+export { useKognitive } from "./context/use-kognitive";
+export { useThreadManager, type UseThreadManagerConfig, type UseThreadManagerReturn } from "./hooks/use-thread-manager";
+export { useAutoScroll } from "./hooks/use-auto-scroll";
+export { useCopyToClipboard } from "./hooks/use-copy-to-clipboard";
+export { useStreamingStatus } from "./hooks/use-streaming-status";
+export { useKeyboardShortcuts, type KeyboardShortcut } from "./hooks/use-keyboard-shortcuts";
+export { useKognitiveEvent, KognitiveEventEmitter, type KognitiveEventType, type KognitiveEventHandler } from "./hooks/use-kognitive-event";
+
+// ── Primitive Hooks ──
+export { useThread } from "./primitives/thread";
+export { useMessage } from "./primitives/message";
+export { useComposer } from "./primitives/composer";
+export { useThreadList } from "./primitives/thread-list";
+
+// ── Runtime (advanced) ──
+export { createKognitiveTransport, type KognitiveTransportConfig } from "./runtime/kognitive-transport";
+export { KognitiveRuntime, type KognitiveRuntimeConfig } from "./runtime/kognitive-runtime";
+export { ThreadManager, type ThreadManagerConfig } from "./runtime/thread-manager";
+export type { ThreadSummary, ThreadDetail, ThreadEvent, ThreadTrace, ThreadRun } from "./runtime/types";
+export type { ToolInvocationState } from "./tool-ui/types";
+
+// ── Utilities ──
+export { cn } from "./utils/cn";
+export { getMessageText, getMessagePreview, getToolInvocations, hasToolInvocations, extractTextContent } from "./utils/message-helpers";

package/src/kognitive-ui.tsx

@@ -0,0 +1,216 @@
+import React, { useMemo, useState, useEffect, useCallback, useRef } from "react";
+import { useChat } from "@ai-sdk/react";
+import type { UIMessage, FileUIPart, ChatStatus } from "ai";
+import { createKognitiveTransport } from "./runtime/kognitive-transport";
+import { ThreadManager } from "./runtime/thread-manager";
+import { ToolUIRegistry } from "./tool-ui/registry";
+import type { ToolUIRegistration } from "./tool-ui/types";
+import { KognitiveContextProvider } from "./context/kognitive-context";
+import { ToolUIRegistryProvider } from "./tool-ui/tool-ui-context";
+import type { ThreadSummary } from "./runtime/types";
+import { Thread } from "./components/thread";
+import { ThreadList } from "./components/thread-list";
+import { Composer } from "./components/composer";
+
+export interface KognitiveUIProps {
+    /**
+     * Explicit API endpoint URL (e.g., "/api/chat").
+     * When set, takes priority over baseUrl + agentName for URL construction.
+     * agentName is sent in the request body instead.
+     */
+    api?: string;
+    /** Agent name to connect to */
+    agentName: string;
+    /** Base URL of the Kognitive runtime (or proxy). Used with agentName to build stream URL. */
+    baseUrl?: string;
+    /** Auth headers */
+    headers?: Record<string, string>;
+    /** User identity */
+    resourceId?: { userId?: string; sessionId?: string; organizationId?: string };
+    /** Session/thread ID (controlled mode — disables thread management) */
+    sessionId?: string;
+    /** Enable thread management */
+    threads?: boolean;
+    /** Thread API base URL. Defaults to {baseUrl}/api/agents/{agentName}/threads */
+    threadApiBase?: string;
+    /** Tool UI registrations from makeToolUI() */
+    toolUIs?: ToolUIRegistration[];
+    /** Tool UI registrations from toolkit() */
+    toolkit?: ToolUIRegistration[];
+    /** Extra body fields merged into every request */
+    body?: Record<string, unknown>;
+    /** Callback when user rates an assistant message (thumbs up/down) */
+    onFeedback?: (messageId: string, type: "positive" | "negative") => void;
+    /** Callback when user approves or rejects a tool call */
+    onToolApproval?: (toolCallId: string, approved: boolean) => void;
+    /** Suggested follow-up prompts shown after assistant response */
+    suggestions?: string[];
+    /** Children */
+    children: React.ReactNode;
+}
+
+function KognitiveUIInner(props: KognitiveUIProps) {
+    const {
+        api,
+        agentName,
+        baseUrl,
+        headers,
+        resourceId,
+        sessionId: controlledSessionId,
+        threads: threadsEnabled,
+        threadApiBase,
+        toolUIs,
+        toolkit: toolkitRegistrations,
+        body: extraBody,
+        onFeedback,
+        onToolApproval,
+        suggestions = [],
+        children,
+    } = props;
+
+    // ── Tool UI Registry ──
+    const toolUIRegistry = useMemo(() => {
+        const registry = new ToolUIRegistry();
+        if (toolUIs) registry.registerAll(toolUIs);
+        if (toolkitRegistrations) registry.registerAll(toolkitRegistrations);
+        return registry;
+    }, [toolUIs, toolkitRegistrations]);
+
+    // ── Thread Management ──
+    const [threadsList, setThreadsList] = useState<ThreadSummary[]>([]);
+    const [activeSessionId, setActiveSessionId] = useState<string | null>(
+        controlledSessionId ?? null,
+    );
+
+    const threadManager = useMemo(() => {
+        if (!threadsEnabled || !baseUrl) return null;
+        const base =
+            threadApiBase ??
+            `${baseUrl.replace(/\/$/, "")}/api/agents/${encodeURIComponent(agentName)}/threads`;
+        return new ThreadManager({ baseUrl: base, headers });
+    }, [threadsEnabled, threadApiBase, baseUrl, agentName, headers]);
+
+    const refreshThreads = useCallback(
+        async (preferredSessionId?: string) => {
+            if (!threadManager) return;
+            const threads = await threadManager.list();
+            setThreadsList(threads);
+            if (preferredSessionId) {
+                setActiveSessionId(preferredSessionId);
+            } else if (!activeSessionId && threads.length > 0) {
+                setActiveSessionId(threads[0].sessionId);
+            } else if (threads.length === 0) {
+                const thread = await threadManager.create();
+                setThreadsList([thread]);
+                setActiveSessionId(thread.sessionId);
+            }
+        },
+        [threadManager, activeSessionId],
+    );
+
+    const createThread = useCallback(async () => {
+        if (!threadManager) return;
+        const thread = await threadManager.create();
+        await refreshThreads(thread.sessionId);
+    }, [threadManager, refreshThreads]);
+
+    useEffect(() => {
+        if (threadManager) {
+            void refreshThreads();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [threadManager]);
+
+    useEffect(() => {
+        if (controlledSessionId !== undefined) {
+            setActiveSessionId(controlledSessionId);
+        }
+    }, [controlledSessionId]);
+
+    // ── Transport + Chat ──
+    const transport = useMemo(
+        () =>
+            createKognitiveTransport({
+                api,
+                baseUrl,
+                agentName,
+                sessionId: activeSessionId ?? undefined,
+                resourceId,
+                headers,
+                body: extraBody,
+            }),
+        [api, baseUrl, agentName, activeSessionId, resourceId, headers, extraBody],
+    );
+
+    const { messages, sendMessage, status, stop, setMessages, error } = useChat({
+        transport,
+    });
+
+    useEffect(() => {
+        setMessages([]);
+    }, [activeSessionId, setMessages]);
+
+    // ── Send helper ──
+    const send = useCallback(
+        (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 });
+        },
+        [sendMessage],
+    );
+
+    // Refresh threads after a stream completes
+    const prevStatusRef = useRef<ChatStatus>(status);
+    useEffect(() => {
+        if (
+            prevStatusRef.current === "streaming" &&
+            status === "ready" &&
+            threadManager
+        ) {
+            void refreshThreads(activeSessionId ?? undefined);
+        }
+        prevStatusRef.current = status;
+    }, [status, threadManager, refreshThreads, activeSessionId]);
+
+    const isStreaming = status === "streaming";
+
+    return (
+        <ToolUIRegistryProvider value={toolUIRegistry}>
+            <KognitiveContextProvider
+                value={{
+                    messages,
+                    send,
+                    status,
+                    isStreaming,
+                    stop,
+                    setMessages,
+                    threadManager,
+                    toolUIRegistry,
+                    activeSessionId,
+                    setActiveSessionId,
+                    threads: threadsList,
+                    refreshThreads: () => refreshThreads(),
+                    createThread,
+                    agentName,
+                    error,
+                    onFeedback,
+                    onToolApproval,
+                    suggestions,
+                }}
+            >
+                {children}
+            </KognitiveContextProvider>
+        </ToolUIRegistryProvider>
+    );
+}
+
+export function KognitiveUI(props: KognitiveUIProps) {
+    return <KognitiveUIInner {...props} />;
+}
+
+KognitiveUI.Thread = Thread;
+KognitiveUI.ThreadList = ThreadList;
+KognitiveUI.Composer = Composer;

package/src/primitives/action-bar/action-bar-copy.tsx

@@ -0,0 +1,30 @@
+import React, { useCallback, type ReactNode } from "react";
+import { useMessage } from "../message/use-message";
+import { useCopyToClipboard } from "../../hooks/use-copy-to-clipboard";
+import { getMessageText } from "../../utils/message-helpers";
+
+export interface ActionBarCopyProps {
+    className?: string;
+    children?: ReactNode | ((copied: boolean) => ReactNode);
+}
+
+export function ActionBarCopy({ className, children }: ActionBarCopyProps) {
+    const { message } = useMessage();
+    const { copied, copy } = useCopyToClipboard();
+
+    const handleCopy = useCallback(() => {
+        void copy(getMessageText(message));
+    }, [copy, message]);
+
+    return (
+        <button
+            type="button"
+            className={className}
+            onClick={handleCopy}
+            aria-label={copied ? "Copied" : "Copy message"}
+            data-copied={copied || undefined}
+        >
+            {typeof children === "function" ? children(copied) : children ?? (copied ? "Copied" : "Copy")}
+        </button>
+    );
+}

package/src/primitives/action-bar/action-bar-edit.tsx

@@ -0,0 +1,24 @@
+import React, { type ReactNode } from "react";
+import { useMessage } from "../message/use-message";
+
+export interface ActionBarEditProps {
+    className?: string;
+    children?: ReactNode;
+}
+
+export function ActionBarEdit({ className, children }: ActionBarEditProps) {
+    const { message, startEdit, isEditing } = useMessage();
+
+    if (message.role !== "user" || isEditing) return null;
+
+    return (
+        <button
+            type="button"
+            className={className}
+            onClick={startEdit}
+            aria-label="Edit message"
+        >
+            {children ?? "Edit"}
+        </button>
+    );
+}

package/src/primitives/action-bar/action-bar-feedback.tsx

@@ -0,0 +1,59 @@
+import React, { useState, useCallback, type ReactNode } from "react";
+import { useMessage } from "../message/use-message";
+import { useKognitiveContext } from "../../context/kognitive-context";
+
+export interface ActionBarFeedbackProps {
+    className?: string;
+    children?: (props: {
+        selected: "positive" | "negative" | null;
+        onPositive: () => void;
+        onNegative: () => void;
+    }) => ReactNode;
+}
+
+export function ActionBarFeedback({ className, children }: ActionBarFeedbackProps) {
+    const { message } = useMessage();
+    const { onFeedback } = useKognitiveContext();
+    const [selected, setSelected] = useState<"positive" | "negative" | null>(null);
+
+    const handlePositive = useCallback(() => {
+        const next = selected === "positive" ? null : "positive" as const;
+        setSelected(next);
+        if (next && onFeedback) onFeedback(message.id, "positive");
+    }, [selected, onFeedback, message.id]);
+
+    const handleNegative = useCallback(() => {
+        const next = selected === "negative" ? null : "negative" as const;
+        setSelected(next);
+        if (next && onFeedback) onFeedback(message.id, "negative");
+    }, [selected, onFeedback, message.id]);
+
+    if (!onFeedback) return null;
+
+    if (children) {
+        return <>{children({ selected, onPositive: handlePositive, onNegative: handleNegative })}</>;
+    }
+
+    return (
+        <div className={className} role="group" aria-label="Message feedback">
+            <button
+                type="button"
+                onClick={handlePositive}
+                aria-label="Good response"
+                aria-pressed={selected === "positive"}
+                data-selected={selected === "positive" || undefined}
+            >
+                {selected === "positive" ? "\u{1F44D}" : "\u{1F44D}\u{200D}"}
+            </button>
+            <button
+                type="button"
+                onClick={handleNegative}
+                aria-label="Bad response"
+                aria-pressed={selected === "negative"}
+                data-selected={selected === "negative" || undefined}
+            >
+                {selected === "negative" ? "\u{1F44E}" : "\u{1F44E}\u{200D}"}
+            </button>
+        </div>
+    );
+}

package/src/primitives/action-bar/action-bar-retry.tsx

@@ -0,0 +1,38 @@
+import React, { useCallback, type ReactNode } from "react";
+import { useKognitiveContext } from "../../context/kognitive-context";
+
+export interface ActionBarRetryProps {
+    className?: string;
+    children?: ReactNode;
+}
+
+export function ActionBarRetry({ className, children }: ActionBarRetryProps) {
+    const { messages, send } = useKognitiveContext();
+
+    const handleRetry = useCallback(() => {
+        // Find the last user message and re-send it
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === "user") {
+                const text = messages[i].parts
+                    .filter((p): p is Extract<typeof p, { type: "text" }> => p.type === "text")
+                    .map((p) => p.text)
+                    .join("\n");
+                if (text) {
+                    send(text);
+                    return;
+                }
+            }
+        }
+    }, [messages, send]);
+
+    return (
+        <button
+            type="button"
+            className={className}
+            onClick={handleRetry}
+            aria-label="Retry"
+        >
+            {children ?? "Retry"}
+        </button>
+    );
+}

package/src/primitives/action-bar/action-bar-root.tsx

@@ -0,0 +1,14 @@
+import React, { type ReactNode } from "react";
+
+export interface ActionBarRootProps {
+    className?: string;
+    children: ReactNode;
+}
+
+export function ActionBarRoot({ className, children }: ActionBarRootProps) {
+    return (
+        <div className={className} role="toolbar" aria-label="Message actions">
+            {children}
+        </div>
+    );
+}

package/src/primitives/action-bar/action-bar-stop.tsx

@@ -0,0 +1,24 @@
+import React, { type ReactNode } from "react";
+import { useKognitiveContext } from "../../context/kognitive-context";
+
+export interface ActionBarStopProps {
+    className?: string;
+    children?: ReactNode;
+}
+
+export function ActionBarStop({ className, children }: ActionBarStopProps) {
+    const { stop, isStreaming } = useKognitiveContext();
+
+    if (!isStreaming) return null;
+
+    return (
+        <button
+            type="button"
+            className={className}
+            onClick={stop}
+            aria-label="Stop"
+        >
+            {children ?? "Stop"}
+        </button>
+    );
+}

package/src/primitives/action-bar/index.ts

@@ -0,0 +1,15 @@
+import { ActionBarRoot } from "./action-bar-root";
+import { ActionBarCopy } from "./action-bar-copy";
+import { ActionBarRetry } from "./action-bar-retry";
+import { ActionBarStop } from "./action-bar-stop";
+import { ActionBarFeedback } from "./action-bar-feedback";
+import { ActionBarEdit } from "./action-bar-edit";
+
+export const ActionBarPrimitive = {
+    Root: ActionBarRoot,
+    Copy: ActionBarCopy,
+    Retry: ActionBarRetry,
+    Stop: ActionBarStop,
+    Feedback: ActionBarFeedback,
+    Edit: ActionBarEdit,
+};

package/src/primitives/composer/composer-attachment-trigger.tsx

@@ -0,0 +1,70 @@
+import React, { useRef, useCallback, type ReactNode, type ChangeEvent } from "react";
+import { useComposer } from "./use-composer";
+
+export interface ComposerAttachmentTriggerProps {
+    accept?: string;
+    className?: string;
+    children?: ReactNode;
+}
+
+export function ComposerAttachmentTrigger({
+    accept = "image/*",
+    className,
+    children,
+}: ComposerAttachmentTriggerProps) {
+    const { addFile } = useComposer();
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const handleClick = useCallback(() => {
+        inputRef.current?.click();
+    }, []);
+
+    const handleChange = useCallback(
+        async (e: ChangeEvent<HTMLInputElement>) => {
+            const fileList = e.target.files;
+            if (!fileList) return;
+
+            for (const file of Array.from(fileList)) {
+                const buffer = await file.arrayBuffer();
+                const base64 = btoa(
+                    new Uint8Array(buffer).reduce(
+                        (data, byte) => data + String.fromCharCode(byte),
+                        "",
+                    ),
+                );
+                addFile({
+                    type: "file",
+                    mediaType: file.type,
+                    url: `data:${file.type};base64,${base64}`,
+                    filename: file.name,
+                });
+            }
+
+            // Reset input so the same file can be selected again
+            if (inputRef.current) inputRef.current.value = "";
+        },
+        [addFile],
+    );
+
+    return (
+        <>
+            <input
+                ref={inputRef}
+                type="file"
+                accept={accept}
+                multiple
+                onChange={handleChange}
+                style={{ display: "none" }}
+                aria-hidden
+            />
+            <button
+                type="button"
+                className={className}
+                onClick={handleClick}
+                aria-label="Attach file"
+            >
+                {children ?? "+"}
+            </button>
+        </>
+    );
+}

package/src/primitives/composer/composer-attachments.tsx

@@ -0,0 +1,36 @@
+import React, { type ReactNode } from "react";
+import type { FileUIPart } from "ai";
+import { useComposer } from "./use-composer";
+
+export interface ComposerAttachmentsProps {
+    className?: string;
+    children?: (file: FileUIPart, index: number, remove: () => void) => ReactNode;
+}
+
+export function ComposerAttachments({ className, children }: ComposerAttachmentsProps) {
+    const { files, removeFile } = useComposer();
+
+    if (files.length === 0) return null;
+
+    return (
+        <div className={className} data-attachment-count={files.length}>
+            {files.map((file, index) => {
+                if (children) {
+                    return children(file, index, () => removeFile(index));
+                }
+                return (
+                    <div key={index} data-attachment>
+                        <span>{file.mediaType}</span>
+                        <button
+                            type="button"
+                            onClick={() => removeFile(index)}
+                            aria-label="Remove attachment"
+                        >
+                            x
+                        </button>
+                    </div>
+                );
+            })}
+        </div>
+    );
+}

package/src/primitives/composer/composer-input.tsx

@@ -0,0 +1,46 @@
+import React, { useCallback, type KeyboardEvent, type ChangeEvent } from "react";
+import { useComposer } from "./use-composer";
+
+export interface ComposerInputProps {
+    placeholder?: string;
+    className?: string;
+    rows?: number;
+}
+
+export function ComposerInput({
+    placeholder = "Send a message...",
+    className,
+    rows = 1,
+}: ComposerInputProps) {
+    const { input, setInput, submit, isDisabled } = useComposer();
+
+    const handleKeyDown = useCallback(
+        (e: KeyboardEvent<HTMLTextAreaElement>) => {
+            if (e.key === "Enter" && !e.shiftKey) {
+                e.preventDefault();
+                submit();
+            }
+        },
+        [submit],
+    );
+
+    const handleChange = useCallback(
+        (e: ChangeEvent<HTMLTextAreaElement>) => {
+            setInput(e.target.value);
+        },
+        [setInput],
+    );
+
+    return (
+        <textarea
+            className={className}
+            value={input}
+            onChange={handleChange}
+            onKeyDown={handleKeyDown}
+            placeholder={placeholder}
+            disabled={isDisabled}
+            rows={rows}
+            aria-label="Message input"
+        />
+    );
+}