@kognitivedev/ui 0.2.11

package/src/primitives/thread-list/thread-list-item.tsx

@@ -0,0 +1,37 @@
+import React, { useCallback, type ReactNode } from "react";
+import type { ThreadSummary } from "../../runtime/types";
+import { useThreadList } from "./use-thread-list";
+
+export interface ThreadListItemProps {
+    thread: ThreadSummary;
+    isActive: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+
+export function ThreadListItem({ thread, isActive, className, children }: ThreadListItemProps) {
+    const { setActiveSessionId } = useThreadList();
+
+    const handleClick = useCallback(() => {
+        setActiveSessionId(thread.sessionId);
+    }, [thread.sessionId, setActiveSessionId]);
+
+    return (
+        <button
+            type="button"
+            className={className}
+            onClick={handleClick}
+            data-active={isActive || undefined}
+            data-status={thread.status}
+            data-session-id={thread.sessionId}
+            aria-current={isActive ? "true" : undefined}
+        >
+            {children ?? (
+                <>
+                    <span>{thread.title || thread.lastUserPreview || "New conversation"}</span>
+                    <span>{thread.lastAssistantPreview}</span>
+                </>
+            )}
+        </button>
+    );
+}

package/src/primitives/thread-list/thread-list-items.tsx

@@ -0,0 +1,19 @@
+import React, { type ReactNode } from "react";
+import type { ThreadSummary } from "../../runtime/types";
+import { useThreadList } from "./use-thread-list";
+
+export interface ThreadListItemsProps {
+    children: (thread: ThreadSummary, isActive: boolean) => ReactNode;
+}
+
+export function ThreadListItems({ children }: ThreadListItemsProps) {
+    const { threads, activeSessionId } = useThreadList();
+
+    return (
+        <>
+            {threads.map((thread) =>
+                children(thread, thread.sessionId === activeSessionId),
+            )}
+        </>
+    );
+}

package/src/primitives/thread-list/thread-list-new.tsx

@@ -0,0 +1,26 @@
+import React, { useCallback, type ReactNode } from "react";
+import { useThreadList } from "./use-thread-list";
+
+export interface ThreadListNewProps {
+    className?: string;
+    children?: ReactNode;
+}
+
+export function ThreadListNew({ className, children }: ThreadListNewProps) {
+    const { createThread } = useThreadList();
+
+    const handleClick = useCallback(() => {
+        void createThread();
+    }, [createThread]);
+
+    return (
+        <button
+            type="button"
+            className={className}
+            onClick={handleClick}
+            aria-label="New conversation"
+        >
+            {children ?? "New conversation"}
+        </button>
+    );
+}

package/src/primitives/thread-list/thread-list-root.tsx

@@ -0,0 +1,29 @@
+import React, { type ReactNode } from "react";
+import { useKognitiveContext } from "../../context/kognitive-context";
+import { ThreadListContextProvider } from "./use-thread-list";
+
+export interface ThreadListRootProps {
+    className?: string;
+    children: ReactNode;
+}
+
+export function ThreadListRoot({ className, children }: ThreadListRootProps) {
+    const { threads, activeSessionId, setActiveSessionId, createThread, refreshThreads } =
+        useKognitiveContext();
+
+    return (
+        <ThreadListContextProvider
+            value={{
+                threads,
+                activeSessionId,
+                setActiveSessionId,
+                createThread,
+                refreshThreads,
+            }}
+        >
+            <div className={className} role="navigation" aria-label="Threads">
+                {children}
+            </div>
+        </ThreadListContextProvider>
+    );
+}

package/src/primitives/thread-list/use-thread-list.ts

@@ -0,0 +1,16 @@
+import { createContext } from "../../utils/create-context";
+import type { ThreadSummary } from "../../runtime/types";
+
+export interface ThreadListContextValue {
+    threads: ThreadSummary[];
+    activeSessionId: string | null;
+    setActiveSessionId: (sessionId: string | null) => void;
+    createThread: () => Promise<void>;
+    refreshThreads: () => Promise<void>;
+}
+
+export const [
+    ThreadListContextProvider,
+    useThreadList,
+    ThreadListContext,
+] = createContext<ThreadListContextValue>("ThreadList");

package/src/primitives/tool-ui/index.ts

@@ -0,0 +1,9 @@
+import { ToolUIRoot } from "./tool-ui-root";
+import { ToolUIFallback } from "./tool-ui-fallback";
+
+export const ToolUIPrimitive = {
+    Root: ToolUIRoot,
+    Fallback: ToolUIFallback,
+};
+
+export { useToolUI } from "./use-tool-ui";

package/src/primitives/tool-ui/tool-ui-fallback.tsx

@@ -0,0 +1,63 @@
+import React, { useState } from "react";
+import type { ToolUIRenderProps } from "../../tool-ui/types";
+
+export interface ToolUIFallbackProps extends ToolUIRenderProps {
+    className?: string;
+}
+
+function stateLabel(state: string): string {
+    switch (state) {
+        case "input-streaming": return "streaming input...";
+        case "input-available": return "calling...";
+        case "approval-requested": return "awaiting approval";
+        case "approval-responded": return "approved";
+        case "output-available": return "done";
+        case "error": return "error";
+        default: return state;
+    }
+}
+
+export function ToolUIFallback({ toolName, toolCallId, input, output, state, className }: ToolUIFallbackProps) {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+        <div
+            className={className}
+            data-tool={toolName}
+            data-tool-state={state}
+            data-tool-call-id={toolCallId}
+        >
+            <button
+                type="button"
+                onClick={() => setExpanded(!expanded)}
+                aria-expanded={expanded}
+                style={{ display: "flex", alignItems: "center", gap: "0.5rem", cursor: "pointer", background: "none", border: "none", padding: "0.5rem", width: "100%", textAlign: "left" }}
+            >
+                <span>&#x1F527;</span>
+                <strong>{toolName}</strong>
+                <span data-tool-state-badge={state}>{stateLabel(state)}</span>
+                <span style={{ marginLeft: "auto" }}>{expanded ? "\u25BC" : "\u25B6"}</span>
+            </button>
+            {expanded && (
+                <div style={{ padding: "0.5rem" }}>
+                    {input !== undefined && (
+                        <div>
+                            <strong>Arguments:</strong>
+                            <pre style={{ overflow: "auto", fontSize: "0.85em" }}>
+                                {JSON.stringify(input, null, 2)}
+                            </pre>
+                        </div>
+                    )}
+                    {output !== undefined && (
+                        <div>
+                            <strong>Result:</strong>
+                            <pre style={{ overflow: "auto", fontSize: "0.85em" }}>
+                                {JSON.stringify(output, null, 2)}
+                            </pre>
+                        </div>
+                    )}
+                </div>
+            )}
+        </div>
+    );
+}

package/src/primitives/tool-ui/tool-ui-root.tsx

@@ -0,0 +1,26 @@
+import React from "react";
+import { useToolUIRegistry } from "../../tool-ui/tool-ui-context";
+import type { ToolUIRenderProps } from "../../tool-ui/types";
+import { ToolUIFallback } from "./tool-ui-fallback";
+
+export interface ToolUIRootProps extends ToolUIRenderProps {
+    className?: string;
+}
+
+export function ToolUIRoot(props: ToolUIRootProps) {
+    let registry: ReturnType<typeof useToolUIRegistry> | undefined;
+
+    try {
+        registry = useToolUIRegistry();
+    } catch {
+        // Registry not available
+    }
+
+    const RegisteredUI = registry?.get(props.toolName);
+
+    if (RegisteredUI) {
+        return <RegisteredUI {...props} />;
+    }
+
+    return <ToolUIFallback {...props} />;
+}

package/src/primitives/tool-ui/use-tool-ui.ts

@@ -0,0 +1,7 @@
+import { useToolUIRegistry } from "../../tool-ui/tool-ui-context";
+import type { ToolUIComponent } from "../../tool-ui/types";
+
+export function useToolUI(toolName: string): ToolUIComponent | undefined {
+    const registry = useToolUIRegistry();
+    return registry.get(toolName);
+}

package/src/runtime/kognitive-runtime.ts

@@ -0,0 +1,56 @@
+import type { DefaultChatTransport, UIMessage } from "ai";
+import { createKognitiveTransport, type KognitiveTransportConfig } from "./kognitive-transport";
+import { ThreadManager, type ThreadManagerConfig } from "./thread-manager";
+import type { ToolUIRegistry } from "../tool-ui/registry";
+
+export interface KognitiveRuntimeConfig {
+    /** Base URL of the Kognitive runtime */
+    baseUrl: string;
+    /** Agent name to connect to */
+    agentName: string;
+    /** Additional headers (e.g., auth) */
+    headers?: Record<string, string>;
+    /** User identity */
+    resourceId?: { userId?: string };
+    /** Initial session/thread ID */
+    sessionId?: string;
+    /** Enable thread management. When true, uses threadApiBase for CRUD. */
+    threads?: boolean;
+    /** Thread API base URL. Defaults to {baseUrl}/api/agents/{agentName}/threads */
+    threadApiBase?: string;
+    /** Tool UI registry */
+    toolUIRegistry?: ToolUIRegistry;
+}
+
+export class KognitiveRuntime {
+    readonly config: KognitiveRuntimeConfig;
+    readonly threadManager: ThreadManager | null;
+    readonly toolUIRegistry: ToolUIRegistry | null;
+
+    constructor(config: KognitiveRuntimeConfig) {
+        this.config = config;
+        this.toolUIRegistry = config.toolUIRegistry ?? null;
+
+        if (config.threads) {
+            const threadApiBase =
+                config.threadApiBase ??
+                `${config.baseUrl.replace(/\/$/, "")}/api/agents/${encodeURIComponent(config.agentName)}/threads`;
+            this.threadManager = new ThreadManager({
+                baseUrl: threadApiBase,
+                headers: config.headers,
+            });
+        } else {
+            this.threadManager = null;
+        }
+    }
+
+    createTransport(sessionId?: string): DefaultChatTransport<UIMessage> {
+        return createKognitiveTransport({
+            baseUrl: this.config.baseUrl,
+            agentName: this.config.agentName,
+            sessionId: sessionId ?? this.config.sessionId,
+            resourceId: this.config.resourceId,
+            headers: this.config.headers,
+        });
+    }
+}

package/src/runtime/kognitive-transport.ts

@@ -0,0 +1,56 @@
+import { DefaultChatTransport, convertToModelMessages, type UIMessage } from "ai";
+
+export interface KognitiveTransportConfig {
+    /**
+     * Explicit API endpoint URL for streaming.
+     * When set, takes priority over baseUrl + agentName URL construction.
+     * Use this for custom proxy routes (e.g., "/api/chat").
+     */
+    api?: string;
+    /** Base URL of the Kognitive runtime. Combined with agentName to construct the stream URL. */
+    baseUrl?: string;
+    /** Agent name. Used with baseUrl to build the URL. Also sent in body when using `api` mode. */
+    agentName?: string;
+    /** Current session/thread ID — sent in every request body */
+    sessionId?: string;
+    /** User identity — sent in every request body as resourceId */
+    resourceId?: { userId?: string; sessionId?: string; organizationId?: string };
+    /** Additional headers (e.g., auth) */
+    headers?: Record<string, string>;
+    /** Extra fields merged into every request body (e.g., { agentName: "assistant" }) */
+    body?: Record<string, unknown>;
+}
+
+export function createKognitiveTransport(
+    config: KognitiveTransportConfig,
+): DefaultChatTransport<UIMessage> {
+    let apiUrl: string;
+    if (config.api) {
+        apiUrl = config.api;
+    } else if (config.baseUrl && config.agentName) {
+        apiUrl = `${config.baseUrl.replace(/\/$/, "")}/api/agents/${encodeURIComponent(config.agentName)}/stream`;
+    } else {
+        throw new Error(
+            "createKognitiveTransport requires either `api` or both `baseUrl` and `agentName`.",
+        );
+    }
+
+    return new DefaultChatTransport<UIMessage>({
+        api: apiUrl,
+        headers: config.headers ?? {},
+        body: () => ({
+            ...(config.body ?? {}),
+            ...(config.agentName && config.api ? { agentName: config.agentName } : {}),
+            ...(config.sessionId ? { sessionId: config.sessionId } : {}),
+            ...(config.resourceId ? { resourceId: config.resourceId } : {}),
+        }),
+        prepareSendMessagesRequest: async ({ messages, body }) => ({
+            body: {
+                ...(body ?? {}),
+                messages: await convertToModelMessages(
+                    messages.map(({ id: _id, ...message }) => message),
+                ),
+            },
+        }),
+    });
+}

package/src/runtime/thread-manager.ts

@@ -0,0 +1,92 @@
+import type { ThreadSummary, ThreadDetail } from "./types";
+
+export interface ThreadManagerConfig {
+    /** Base URL for thread API endpoints */
+    baseUrl: string;
+    /** Additional headers (e.g., auth) */
+    headers?: Record<string, string>;
+}
+
+export class ThreadManager {
+    private baseUrl: string;
+    private headers: Record<string, string>;
+
+    constructor(config: ThreadManagerConfig) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.headers = {
+            "Content-Type": "application/json",
+            ...(config.headers ?? {}),
+        };
+    }
+
+    async list(): Promise<ThreadSummary[]> {
+        const res = await fetch(this.baseUrl, { headers: this.headers });
+        if (!res.ok) {
+            throw new Error(
+                (await res.json().catch(() => ({ error: "Failed to list threads" }))).error,
+            );
+        }
+        const data = await res.json();
+        return (data.threads ?? []) as ThreadSummary[];
+    }
+
+    async get(sessionId: string): Promise<ThreadDetail> {
+        const res = await fetch(`${this.baseUrl}/${encodeURIComponent(sessionId)}`, {
+            headers: this.headers,
+        });
+        if (!res.ok) {
+            throw new Error(
+                (await res.json().catch(() => ({ error: "Failed to get thread" }))).error,
+            );
+        }
+        return (await res.json()) as ThreadDetail;
+    }
+
+    async create(): Promise<ThreadSummary> {
+        const res = await fetch(this.baseUrl, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify({}),
+        });
+        if (!res.ok) {
+            throw new Error(
+                (await res.json().catch(() => ({ error: "Failed to create thread" }))).error,
+            );
+        }
+        const data = await res.json();
+        return data.thread as ThreadSummary;
+    }
+
+    async fork(sessionId: string): Promise<ThreadSummary> {
+        const res = await fetch(
+            `${this.baseUrl}/${encodeURIComponent(sessionId)}/fork`,
+            {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify({}),
+            },
+        );
+        if (!res.ok) {
+            throw new Error(
+                (await res.json().catch(() => ({ error: "Failed to fork thread" }))).error,
+            );
+        }
+        const data = await res.json();
+        return data.thread as ThreadSummary;
+    }
+
+    async interrupt(sessionId: string): Promise<void> {
+        const res = await fetch(
+            `${this.baseUrl}/${encodeURIComponent(sessionId)}/interrupt`,
+            {
+                method: "POST",
+                headers: this.headers,
+            },
+        );
+        if (!res.ok) {
+            throw new Error(
+                (await res.json().catch(() => ({ error: "Failed to interrupt thread" }))).error,
+            );
+        }
+    }
+}

package/src/runtime/types.ts

@@ -0,0 +1,63 @@
+export type ThreadSummary = {
+    sessionDbId: string;
+    sessionId: string;
+    title: string;
+    status: string;
+    updatedAt: string;
+    messageCount: number;
+    lastUserPreview: string;
+    lastAssistantPreview: string;
+    lastError?: string | null;
+    lastTraceDbId?: string | null;
+};
+
+export type ThreadEvent = {
+    id: string;
+    sequence: number;
+    eventType: "user_message" | "assistant_message" | "tool_call" | "tool_result" | "status";
+    payload: Record<string, unknown>;
+    createdAt: string;
+};
+
+export type ThreadTrace = {
+    id: string;
+    traceId: string;
+    state: string;
+    durationMs: number | null;
+    totalCostCents: number;
+    inputTokens: number;
+    outputTokens: number;
+    modelId: string | null;
+    createdAt: string;
+};
+
+export type ThreadRun = {
+    id: string;
+    runId: string;
+    agentName: string;
+    status: string;
+    triggerType: string;
+    inputPreview: string | null;
+    outputPreview: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    totalCostCents: number;
+    durationMs: number | null;
+    startedAt: string;
+    completedAt: string | null;
+    parentRunId: string | null;
+};
+
+export type ThreadDetail = {
+    session: {
+        id: string;
+        sessionId: string;
+        messageCount: number;
+        metadata?: Record<string, unknown> | null;
+    };
+    events: ThreadEvent[];
+    traces: ThreadTrace[];
+    runs: ThreadRun[];
+};
+
+export type RuntimeStatus = "ready" | "submitted" | "streaming" | "error";

package/src/tool-ui/make-tool-ui.ts

@@ -0,0 +1,71 @@
+import type { ReactNode } from "react";
+import type { ToolUIRenderProps, ToolUIRegistration } from "./types";
+
+/**
+ * Options for makeToolUI when using a @kognitivedev/tools Tool definition.
+ * The tool's inputSchema and outputSchema provide type inference.
+ */
+export interface MakeToolUIOptions<TInput = any, TOutput = any> {
+    /** The tool definition from createTool(). Provides name and type info. */
+    tool: { id: string; inputSchema?: unknown; outputSchema?: unknown };
+    /** Render function with fully typed props from the tool definition. */
+    render: (props: ToolUIRenderProps<TInput, TOutput>) => ReactNode;
+}
+
+/**
+ * Options for makeToolUI when registering by tool name string.
+ */
+export interface MakeToolUIByNameOptions {
+    /** The tool name (must match the tool ID used on the server) */
+    toolName: string;
+    /** Render function for the tool UI */
+    render: (props: ToolUIRenderProps) => ReactNode;
+}
+
+/**
+ * Create a type-safe tool UI registration from a @kognitivedev/tools Tool definition.
+ *
+ * @example
+ * ```tsx
+ * const weatherTool = createTool({
+ *   id: "get_weather",
+ *   inputSchema: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => ({ temp: 22 }),
+ * });
+ *
+ * const WeatherUI = makeToolUI({
+ *   tool: weatherTool,
+ *   render: ({ input, output, state }) => (
+ *     <div>{input.city}: {output?.temp}°</div>
+ *   ),
+ * });
+ * ```
+ */
+export function makeToolUI<TInput, TOutput>(
+    options: MakeToolUIOptions<TInput, TOutput>,
+): ToolUIRegistration;
+
+/**
+ * Create a tool UI registration by tool name string.
+ *
+ * @example
+ * ```tsx
+ * const SearchUI = makeToolUI({
+ *   toolName: "search",
+ *   render: ({ input, output, state }) => (
+ *     <div>Searching for {input.query}...</div>
+ *   ),
+ * });
+ * ```
+ */
+export function makeToolUI(options: MakeToolUIByNameOptions): ToolUIRegistration;
+
+export function makeToolUI(
+    options: MakeToolUIOptions | MakeToolUIByNameOptions,
+): ToolUIRegistration {
+    const toolName = "tool" in options ? options.tool.id : options.toolName;
+    return {
+        toolName,
+        component: options.render as any,
+    };
+}

package/src/tool-ui/registry.ts

@@ -0,0 +1,27 @@
+import type { ToolUIComponent, ToolUIRegistration } from "./types";
+
+export class ToolUIRegistry {
+    private map = new Map<string, ToolUIComponent>();
+
+    register(registration: ToolUIRegistration): void {
+        this.map.set(registration.toolName, registration.component);
+    }
+
+    registerAll(registrations: ToolUIRegistration[]): void {
+        for (const reg of registrations) {
+            this.register(reg);
+        }
+    }
+
+    get(toolName: string): ToolUIComponent | undefined {
+        return this.map.get(toolName);
+    }
+
+    has(toolName: string): boolean {
+        return this.map.has(toolName);
+    }
+
+    names(): string[] {
+        return Array.from(this.map.keys());
+    }
+}

package/src/tool-ui/tool-ui-context.tsx

@@ -0,0 +1,8 @@
+import { createContext } from "../utils/create-context";
+import type { ToolUIRegistry } from "./registry";
+
+export const [
+    ToolUIRegistryProvider,
+    useToolUIRegistry,
+    ToolUIRegistryContext,
+] = createContext<ToolUIRegistry>("ToolUIRegistry");

package/src/tool-ui/toolkit.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react";
+import type { ToolUIRenderProps, ToolUIRegistration } from "./types";
+
+export interface ToolkitEntry {
+    /** Render function for this tool's UI */
+    render: (props: ToolUIRenderProps) => ReactNode;
+}
+
+/**
+ * Register multiple tool UIs at once by tool name.
+ *
+ * Useful when you don't have the Tool objects on the client
+ * (e.g., backend-only tools) but still want custom renderers.
+ *
+ * @example
+ * ```tsx
+ * const myToolkit = toolkit({
+ *   get_weather: {
+ *     render: ({ input, output, state }) => (
+ *       <WeatherCard city={input.city} data={output} />
+ *     ),
+ *   },
+ *   search_database: {
+ *     render: ({ input, output }) => (
+ *       <QueryResults query={input.query} results={output?.rows} />
+ *     ),
+ *   },
+ * });
+ *
+ * <KognitiveUI toolkit={myToolkit} ... />
+ * ```
+ */
+export function toolkit(
+    map: Record<string, ToolkitEntry>,
+): ToolUIRegistration[] {
+    return Object.entries(map).map(([toolName, entry]) => ({
+        toolName,
+        component: entry.render as any,
+    }));
+}