@kognitivedev/ui 0.2.11

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@kognitivedev/ui",
+  "version": "0.2.11",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@kognitivedev/shared": "^0.2.11",
+    "clsx": "^2.1.0",
+    "tailwind-merge": "^3.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "@ai-sdk/react": ">=3.0.0",
+    "ai": ">=6.0.0",
+    "zod": ">=3.23.0"
+  },
+  "optionalDependencies": {
+    "@kognitivedev/tools": "^0.2.11"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/react": "^19",
+    "@types/node": "^20.0.0",
+    "react": "^19.0.0",
+    "@ai-sdk/react": "^3.0.0",
+    "ai": "^6.0.0",
+    "zod": "^3.23.0",
+    "vitest": "^3.0.0"
+  },
+  "description": "React components for building agentic chat UIs with Kognitive",
+  "keywords": [
+    "kognitive",
+    "ai",
+    "chat",
+    "ui",
+    "react",
+    "agent",
+    "tools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kognitivedev/kognitive",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://kognitive.dev"
+}

package/src/__tests__/context-provider.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { ToolUIRegistry } from "../tool-ui/registry";
+
+describe("Context isolation", () => {
+    it("ToolUIRegistry can be constructed standalone", () => {
+        const registry = new ToolUIRegistry();
+        expect(registry.names()).toHaveLength(0);
+    });
+
+    it("ToolUIRegistry supports full CRUD lifecycle", () => {
+        const registry = new ToolUIRegistry();
+
+        // Initially empty
+        expect(registry.has("tool-a")).toBe(false);
+        expect(registry.get("tool-a")).toBeUndefined();
+
+        // Register
+        const component = () => null;
+        registry.register({ toolName: "tool-a", component });
+        expect(registry.has("tool-a")).toBe(true);
+        expect(registry.get("tool-a")).toBe(component);
+        expect(registry.names()).toContain("tool-a");
+
+        // Overwrite
+        const component2 = () => null;
+        registry.register({ toolName: "tool-a", component: component2 });
+        expect(registry.get("tool-a")).toBe(component2);
+
+        // Multiple
+        registry.register({ toolName: "tool-b", component });
+        expect(registry.names()).toHaveLength(2);
+    });
+
+    it("ToolUIRegistry.registerAll registers multiple at once", () => {
+        const registry = new ToolUIRegistry();
+        registry.registerAll([
+            { toolName: "a", component: () => null },
+            { toolName: "b", component: () => null },
+            { toolName: "c", component: () => null },
+        ]);
+        expect(registry.names()).toHaveLength(3);
+    });
+});

package/src/__tests__/event-emitter.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi } from "vitest";
+import { KognitiveEventEmitter } from "../hooks/use-kognitive-event";
+
+describe("KognitiveEventEmitter", () => {
+    it("emits events to registered listeners", () => {
+        const emitter = new KognitiveEventEmitter();
+        const handler = vi.fn();
+        emitter.on("message:send", handler);
+        emitter.emit("message:send", { text: "hello" });
+        expect(handler).toHaveBeenCalledWith({ text: "hello" });
+    });
+
+    it("supports multiple listeners for the same event", () => {
+        const emitter = new KognitiveEventEmitter();
+        const h1 = vi.fn();
+        const h2 = vi.fn();
+        emitter.on("message:received", h1);
+        emitter.on("message:received", h2);
+        emitter.emit("message:received", "data");
+        expect(h1).toHaveBeenCalledOnce();
+        expect(h2).toHaveBeenCalledOnce();
+    });
+
+    it("returns an unsubscribe function", () => {
+        const emitter = new KognitiveEventEmitter();
+        const handler = vi.fn();
+        const unsub = emitter.on("status:change", handler);
+        emitter.emit("status:change", "streaming");
+        expect(handler).toHaveBeenCalledOnce();
+
+        unsub();
+        emitter.emit("status:change", "ready");
+        expect(handler).toHaveBeenCalledOnce(); // not called again
+    });
+
+    it("does not throw when emitting with no listeners", () => {
+        const emitter = new KognitiveEventEmitter();
+        expect(() => emitter.emit("error", new Error("test"))).not.toThrow();
+    });
+
+    it("swallows listener errors", () => {
+        const emitter = new KognitiveEventEmitter();
+        emitter.on("tool:invoked", () => { throw new Error("boom"); });
+        const good = vi.fn();
+        emitter.on("tool:invoked", good);
+
+        expect(() => emitter.emit("tool:invoked", {})).not.toThrow();
+        expect(good).toHaveBeenCalledOnce();
+    });
+
+    it("supports all event types", () => {
+        const emitter = new KognitiveEventEmitter();
+        const events = [
+            "message:send",
+            "message:received",
+            "status:change",
+            "tool:invoked",
+            "tool:completed",
+            "error",
+        ] as const;
+
+        for (const event of events) {
+            const handler = vi.fn();
+            emitter.on(event, handler);
+            emitter.emit(event, "test");
+            expect(handler).toHaveBeenCalledWith("test");
+        }
+    });
+});

package/src/__tests__/keyboard-shortcuts.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from "vitest";
+
+// Test the shortcut matching logic directly (not the hook, since it needs React)
+describe("Keyboard shortcut matching", () => {
+    function matchShortcut(
+        shortcut: { key: string; ctrl?: boolean; meta?: boolean; shift?: boolean },
+        event: { key: string; ctrlKey?: boolean; metaKey?: boolean; shiftKey?: boolean },
+    ): boolean {
+        const ctrlOrMeta = shortcut.ctrl || shortcut.meta;
+        const matchesMod = ctrlOrMeta ? !!(event.ctrlKey || event.metaKey) : true;
+        const matchesShift = shortcut.shift ? !!event.shiftKey : !event.shiftKey;
+        return event.key.toLowerCase() === shortcut.key.toLowerCase() && matchesMod && matchesShift;
+    }
+
+    it("matches simple key", () => {
+        expect(matchShortcut({ key: "Escape" }, { key: "Escape" })).toBe(true);
+    });
+
+    it("does not match different key", () => {
+        expect(matchShortcut({ key: "Escape" }, { key: "Enter" })).toBe(false);
+    });
+
+    it("matches Ctrl+key", () => {
+        expect(matchShortcut({ key: "c", ctrl: true }, { key: "c", ctrlKey: true })).toBe(true);
+    });
+
+    it("matches Meta+key (Mac Cmd)", () => {
+        expect(matchShortcut({ key: "c", meta: true }, { key: "c", metaKey: true })).toBe(true);
+    });
+
+    it("matches Ctrl+Shift+key", () => {
+        expect(matchShortcut(
+            { key: "c", ctrl: true, shift: true },
+            { key: "c", ctrlKey: true, shiftKey: true },
+        )).toBe(true);
+    });
+
+    it("does not match when shift is required but not pressed", () => {
+        expect(matchShortcut(
+            { key: "c", ctrl: true, shift: true },
+            { key: "c", ctrlKey: true, shiftKey: false },
+        )).toBe(false);
+    });
+
+    it("does not match when shift is pressed but not required", () => {
+        expect(matchShortcut(
+            { key: "c", ctrl: true },
+            { key: "c", ctrlKey: true, shiftKey: true },
+        )).toBe(false);
+    });
+
+    it("is case insensitive", () => {
+        expect(matchShortcut({ key: "escape" }, { key: "Escape" })).toBe(true);
+    });
+});

package/src/__tests__/kognitive-runtime.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { KognitiveRuntime } from "../runtime/kognitive-runtime";
+
+describe("KognitiveRuntime", () => {
+    it("creates a transport from config", () => {
+        const runtime = new KognitiveRuntime({
+            baseUrl: "http://localhost:3001",
+            agentName: "test-agent",
+        });
+        const transport = runtime.createTransport();
+        expect(transport).toBeDefined();
+    });
+
+    it("creates a transport with custom sessionId", () => {
+        const runtime = new KognitiveRuntime({
+            baseUrl: "http://localhost:3001",
+            agentName: "test-agent",
+        });
+        const transport = runtime.createTransport("session-123");
+        expect(transport).toBeDefined();
+    });
+
+    it("creates ThreadManager when threads=true", () => {
+        const runtime = new KognitiveRuntime({
+            baseUrl: "http://localhost:3001",
+            agentName: "test-agent",
+            threads: true,
+        });
+        expect(runtime.threadManager).not.toBeNull();
+    });
+
+    it("does not create ThreadManager when threads=false", () => {
+        const runtime = new KognitiveRuntime({
+            baseUrl: "http://localhost:3001",
+            agentName: "test-agent",
+        });
+        expect(runtime.threadManager).toBeNull();
+    });
+
+    it("uses custom threadApiBase", () => {
+        const runtime = new KognitiveRuntime({
+            baseUrl: "http://localhost:3001",
+            agentName: "test-agent",
+            threads: true,
+            threadApiBase: "http://custom:4000/threads",
+        });
+        expect(runtime.threadManager).not.toBeNull();
+    });
+
+    it("stores config for later access", () => {
+        const config = {
+            baseUrl: "http://localhost:3001",
+            agentName: "test-agent",
+            headers: { Authorization: "Bearer token" },
+            resourceId: { userId: "user-1" },
+        };
+        const runtime = new KognitiveRuntime(config);
+        expect(runtime.config.baseUrl).toBe(config.baseUrl);
+        expect(runtime.config.agentName).toBe(config.agentName);
+        expect(runtime.config.headers).toEqual(config.headers);
+    });
+});

package/src/__tests__/kognitive-transport.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import { createKognitiveTransport } from "../runtime/kognitive-transport";
+
+describe("createKognitiveTransport", () => {
+    describe("URL resolution", () => {
+        it("uses baseUrl + agentName to construct URL", () => {
+            const transport = createKognitiveTransport({
+                baseUrl: "http://localhost:3001",
+                agentName: "my-agent",
+            });
+            expect(transport).toBeDefined();
+        });
+
+        it("uses explicit api URL when provided", () => {
+            const transport = createKognitiveTransport({
+                api: "/api/chat",
+            });
+            expect(transport).toBeDefined();
+        });
+
+        it("api takes priority over baseUrl + agentName", () => {
+            const transport = createKognitiveTransport({
+                api: "/api/custom",
+                baseUrl: "http://localhost:3001",
+                agentName: "agent",
+            });
+            expect(transport).toBeDefined();
+        });
+
+        it("throws when neither api nor baseUrl+agentName provided", () => {
+            expect(() =>
+                createKognitiveTransport({}),
+            ).toThrow("requires either `api` or both `baseUrl` and `agentName`");
+        });
+
+        it("throws when only baseUrl provided (no agentName)", () => {
+            expect(() =>
+                createKognitiveTransport({ baseUrl: "http://localhost:3001" }),
+            ).toThrow();
+        });
+
+        it("throws when only agentName provided (no baseUrl)", () => {
+            expect(() =>
+                createKognitiveTransport({ agentName: "my-agent" }),
+            ).toThrow();
+        });
+    });
+
+    describe("URL construction", () => {
+        it("URL-encodes the agent name", () => {
+            const transport = createKognitiveTransport({
+                baseUrl: "http://localhost:3001",
+                agentName: "agent with spaces",
+            });
+            expect(transport).toBeDefined();
+        });
+
+        it("strips trailing slash from baseUrl", () => {
+            const transport = createKognitiveTransport({
+                baseUrl: "http://localhost:3001/",
+                agentName: "test",
+            });
+            expect(transport).toBeDefined();
+        });
+    });
+
+    describe("config passthrough", () => {
+        it("accepts sessionId", () => {
+            const transport = createKognitiveTransport({
+                api: "/api/chat",
+                sessionId: "sess-123",
+            });
+            expect(transport).toBeDefined();
+        });
+
+        it("accepts full resourceId with userId, sessionId, organizationId", () => {
+            const transport = createKognitiveTransport({
+                api: "/api/chat",
+                resourceId: {
+                    userId: "user-1",
+                    sessionId: "sess-1",
+                    organizationId: "org-1",
+                },
+            });
+            expect(transport).toBeDefined();
+        });
+
+        it("accepts custom headers", () => {
+            const transport = createKognitiveTransport({
+                api: "/api/chat",
+                headers: { Authorization: "Bearer token123" },
+            });
+            expect(transport).toBeDefined();
+        });
+
+        it("accepts extra body fields", () => {
+            const transport = createKognitiveTransport({
+                api: "/api/chat",
+                body: { agentName: "assistant", customField: true },
+            });
+            expect(transport).toBeDefined();
+        });
+
+        it("sends agentName in body when using api mode", () => {
+            // When api is set and agentName is provided, agentName should be in body
+            const transport = createKognitiveTransport({
+                api: "/api/chat",
+                agentName: "assistant",
+            });
+            expect(transport).toBeDefined();
+        });
+    });
+});

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

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import { makeToolUI } from "../tool-ui/make-tool-ui";
+import { ToolUIRegistry } from "../tool-ui/registry";
+
+describe("makeToolUI", () => {
+    it("creates a registration from a tool object with id", () => {
+        const render = () => null;
+        const reg = makeToolUI({
+            tool: { id: "weather" },
+            render,
+        });
+
+        expect(reg.toolName).toBe("weather");
+        expect(reg.component).toBe(render);
+    });
+
+    it("creates a registration from toolName string", () => {
+        const render = () => null;
+        const reg = makeToolUI({
+            toolName: "database_query",
+            render,
+        });
+
+        expect(reg.toolName).toBe("database_query");
+        expect(reg.component).toBe(render);
+    });
+
+    it("integrates with ToolUIRegistry", () => {
+        const reg = makeToolUI({
+            tool: { id: "my-tool" },
+            render: () => null,
+        });
+
+        const registry = new ToolUIRegistry();
+        registry.register(reg);
+
+        expect(registry.has("my-tool")).toBe(true);
+        expect(registry.get("my-tool")).toBe(reg.component);
+    });
+
+    it("tool.id takes priority over toolName in tool-based registration", () => {
+        const reg = makeToolUI({
+            tool: { id: "from-tool-id" },
+            render: () => null,
+        });
+
+        expect(reg.toolName).toBe("from-tool-id");
+    });
+
+    it("multiple registrations can coexist in registry", () => {
+        const reg1 = makeToolUI({ tool: { id: "tool-a" }, render: () => "a" });
+        const reg2 = makeToolUI({ toolName: "tool-b", render: () => "b" });
+
+        const registry = new ToolUIRegistry();
+        registry.register(reg1);
+        registry.register(reg2);
+
+        expect(registry.names()).toEqual(expect.arrayContaining(["tool-a", "tool-b"]));
+    });
+});

package/src/__tests__/message-helpers.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "vitest";
+import type { UIMessage } from "ai";
+import {
+    extractTextContent,
+    getMessageText,
+    getMessagePreview,
+    getToolInvocations,
+    hasToolInvocations,
+} from "../utils/message-helpers";
+
+function makeMessage(parts: UIMessage["parts"], role: "user" | "assistant" = "assistant"): UIMessage {
+    return {
+        id: "msg-1",
+        role,
+        parts,
+        createdAt: new Date(),
+    } as UIMessage;
+}
+
+describe("extractTextContent", () => {
+    it("returns string content as-is", () => {
+        expect(extractTextContent("hello")).toBe("hello");
+    });
+
+    it("extracts text from an array of parts", () => {
+        expect(
+            extractTextContent([
+                { text: "hello" },
+                { text: "world" },
+            ]),
+        ).toBe("hello\nworld");
+    });
+
+    it("returns empty string for non-string non-array input", () => {
+        expect(extractTextContent(42)).toBe("");
+        expect(extractTextContent(null)).toBe("");
+        expect(extractTextContent(undefined)).toBe("");
+    });
+
+    it("skips non-text parts", () => {
+        expect(
+            extractTextContent([
+                { text: "keep" },
+                { type: "image" },
+                { text: "this" },
+            ]),
+        ).toBe("keep\nthis");
+    });
+});
+
+describe("getMessageText", () => {
+    it("extracts text from message parts", () => {
+        const msg = makeMessage([
+            { type: "text", text: "Hello " },
+            { type: "text", text: "world" },
+        ]);
+        expect(getMessageText(msg)).toBe("Hello \nworld");
+    });
+
+    it("skips non-text parts", () => {
+        const msg = makeMessage([
+            { type: "text", text: "before" },
+            { type: "text", text: "after" },
+        ]);
+        expect(getMessageText(msg)).toBe("before\nafter");
+    });
+
+    it("returns empty string for message with no text parts", () => {
+        const msg = makeMessage([]);
+        expect(getMessageText(msg)).toBe("");
+    });
+});
+
+describe("getMessagePreview", () => {
+    it("returns full text when under maxLength", () => {
+        const msg = makeMessage([{ type: "text", text: "Short" }]);
+        expect(getMessagePreview(msg)).toBe("Short");
+    });
+
+    it("truncates and adds ellipsis when over maxLength", () => {
+        const longText = "A".repeat(100);
+        const msg = makeMessage([{ type: "text", text: longText }]);
+        const preview = getMessagePreview(msg, 50);
+        expect(preview.length).toBeLessThanOrEqual(53); // 50 + "..."
+        expect(preview.endsWith("...")).toBe(true);
+    });
+});
+
+describe("getToolInvocations", () => {
+    it("returns empty array when no tool invocations", () => {
+        const msg = makeMessage([{ type: "text", text: "hello" }]);
+        expect(getToolInvocations(msg)).toHaveLength(0);
+    });
+});
+
+describe("hasToolInvocations", () => {
+    it("returns false when message has no tool invocations", () => {
+        const msg = makeMessage([{ type: "text", text: "hello" }]);
+        expect(hasToolInvocations(msg)).toBe(false);
+    });
+});

package/src/__tests__/thread-manager.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ThreadManager } from "../runtime/thread-manager";
+
+describe("ThreadManager", () => {
+    const mockFetch = vi.fn();
+
+    beforeEach(() => {
+        vi.stubGlobal("fetch", mockFetch);
+        mockFetch.mockReset();
+    });
+
+    const manager = new ThreadManager({
+        baseUrl: "http://localhost:3001/api/agents/my-agent/threads",
+    });
+
+    it("list() fetches threads", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ threads: [{ sessionId: "s1", title: "Hello" }] }),
+        });
+
+        const threads = await manager.list();
+        expect(threads).toHaveLength(1);
+        expect(threads[0].sessionId).toBe("s1");
+        expect(mockFetch).toHaveBeenCalledWith(
+            "http://localhost:3001/api/agents/my-agent/threads",
+            expect.objectContaining({ headers: expect.any(Object) }),
+        );
+    });
+
+    it("get() fetches a single thread", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                session: { id: "1", sessionId: "s1", messageCount: 5 },
+                events: [],
+                traces: [],
+                runs: [],
+            }),
+        });
+
+        const detail = await manager.get("s1");
+        expect(detail.session.sessionId).toBe("s1");
+        expect(mockFetch).toHaveBeenCalledWith(
+            "http://localhost:3001/api/agents/my-agent/threads/s1",
+            expect.objectContaining({ headers: expect.any(Object) }),
+        );
+    });
+
+    it("create() POSTs to create a thread", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ thread: { sessionId: "new-s", title: "" } }),
+        });
+
+        const thread = await manager.create();
+        expect(thread.sessionId).toBe("new-s");
+        expect(mockFetch).toHaveBeenCalledWith(
+            "http://localhost:3001/api/agents/my-agent/threads",
+            expect.objectContaining({ method: "POST" }),
+        );
+    });
+
+    it("fork() POSTs to fork a thread", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ thread: { sessionId: "forked-s", title: "" } }),
+        });
+
+        const thread = await manager.fork("s1");
+        expect(thread.sessionId).toBe("forked-s");
+        expect(mockFetch).toHaveBeenCalledWith(
+            "http://localhost:3001/api/agents/my-agent/threads/s1/fork",
+            expect.objectContaining({ method: "POST" }),
+        );
+    });
+
+    it("interrupt() POSTs to interrupt a thread", async () => {
+        mockFetch.mockResolvedValueOnce({ ok: true, json: async () => ({}) });
+
+        await manager.interrupt("s1");
+        expect(mockFetch).toHaveBeenCalledWith(
+            "http://localhost:3001/api/agents/my-agent/threads/s1/interrupt",
+            expect.objectContaining({ method: "POST" }),
+        );
+    });
+
+    it("throws on HTTP error", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            json: async () => ({ error: "Not found" }),
+        });
+
+        await expect(manager.get("bad-id")).rejects.toThrow("Not found");
+    });
+
+    it("includes custom headers", async () => {
+        const authManager = new ThreadManager({
+            baseUrl: "http://localhost:3001/api/threads",
+            headers: { Authorization: "Bearer secret" },
+        });
+
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ threads: [] }),
+        });
+
+        await authManager.list();
+        expect(mockFetch).toHaveBeenCalledWith(
+            expect.any(String),
+            expect.objectContaining({
+                headers: expect.objectContaining({
+                    Authorization: "Bearer secret",
+                }),
+            }),
+        );
+    });
+});