feat: add thread list and deletion API with new component

- switch docs, stories, and UI to the slot-based CopilotThreadList API
- surface delete controls with optimistic updates and error feedback
- extend useThreads with deleteThread/currentThreadId helpers plus tests
- prevent suggestion-generated runs from polluting thread history
- wire DELETE handler through runtime endpoints and runner backends
- harden CopilotChat reconnect flow and tool-call rendering keys

Signed-off-by: Tyler Slaton <[email protected]>

Author: tylerslaton

apps/docs/guides/thread-management.mdx

@@ -0,0 +1,375 @@
+---
+title: "Thread Management"
+description: "Learn how to retrieve, list, and switch between conversation threads in CopilotKit"
+---
+
+# Thread Management
+
+CopilotKit provides built-in support for managing multiple conversation threads, allowing you to build chat applications with conversation history similar to ChatGPT.
+
+## Overview
+
+Threads are automatically created and stored when you use CopilotChat. Each thread maintains:
+- Complete conversation history
+- Message metadata
+- Running state
+- Creation and last activity timestamps
+
+## Using the Thread List Component
+
+The easiest way to add thread management is using the `CopilotThreadList` component:
+
+```tsx
+import {
+  CopilotKitProvider,
+  CopilotThreadList,
+  CopilotChat,
+  CopilotChatConfigurationProvider,
+  useCopilotChatConfiguration,
+} from "@copilotkitnext/react";
+
+function ThreadSidebar() {
+  return (
+    <aside className="w-80 border-r">
+      <CopilotThreadList limit={20} />
+    </aside>
+  );
+}
+
+function ChatPanel() {
+  const config = useCopilotChatConfiguration();
+
+  if (!config?.threadId) {
+    return (
+      <div className="flex h-full items-center justify-center text-muted-foreground">
+        Select a conversation to start chatting
+      </div>
+    );
+  }
+
+  return <CopilotChat agentId="my-agent" threadId={config.threadId} className="h-full" />;
+}
+
+export function ChatApp() {
+  return (
+    <CopilotKitProvider>
+      <CopilotChatConfigurationProvider>
+        <div className="flex h-screen">
+          <ThreadSidebar />
+          <div className="flex-1">
+            <ChatPanel />
+          </div>
+        </div>
+      </CopilotChatConfigurationProvider>
+    </CopilotKitProvider>
+  );
+}
+```
+
+## Using the useThreads Hook
+
+For more control over thread data, use the `useThreads` hook:
+
+```tsx
+import { useThreads } from "@copilotkitnext/react";
+
+function MyThreadManager() {
+  const {
+    threads,
+    total,
+    isLoading,
+    error,
+    fetchThreads,
+    getThreadMetadata,
+    refresh,
+  } = useThreads({
+    limit: 20,
+    autoFetch: true,
+  });
+
+  if (isLoading) return <div>Loading threads...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>Your Conversations ({total})</h2>
+      {threads.map((thread) => (
+        <div key={thread.threadId}>
+          <h3>{thread.firstMessage || "New conversation"}</h3>
+          <p>{thread.messageCount} messages</p>
+          <p>Last active: {new Date(thread.lastActivityAt).toLocaleString()}</p>
+        </div>
+      ))}
+      <button onClick={refresh}>Refresh</button>
+    </div>
+  );
+}
+```
+
+## Thread Metadata
+
+Each thread includes the following metadata:
+
+```typescript
+interface ThreadMetadata {
+  threadId: string;         // Unique thread identifier
+  createdAt: number;         // Timestamp (ms)
+  lastActivityAt: number;    // Timestamp (ms)
+  isRunning: boolean;        // Is thread currently active?
+  messageCount: number;      // Total messages in thread
+  firstMessage?: string;     // Preview of first message (100 chars)
+}
+```
+
+## Creating New Threads
+
+To create a new thread, simply generate a new UUID and pass it to CopilotChat:
+
+```tsx
+import { CopilotChat } from "@copilotkitnext/react";
+import { useState } from "react";
+
+function ChatWithNewThread() {
+  const [threadId, setThreadId] = useState<string>(crypto.randomUUID());
+
+  const handleNewThread = () => {
+    setThreadId(crypto.randomUUID());
+  };
+
+  return (
+    <div>
+      <button onClick={handleNewThread}>New Conversation</button>
+      <CopilotChat
+        agentId="my-agent"
+        threadId={threadId}
+      />
+    </div>
+  );
+}
+```
+
+## Switching Between Threads
+
+CopilotChat automatically handles thread switching when the `threadId` prop changes:
+
+```tsx
+function MultiThreadChat() {
+  const [currentThread, setCurrentThread] = useState("thread-1");
+  const { threads } = useThreads();
+
+  return (
+    <div>
+      {/* Thread selector */}
+      <select
+        value={currentThread}
+        onChange={(e) => setCurrentThread(e.target.value)}
+      >
+        {threads.map((thread) => (
+          <option key={thread.threadId} value={thread.threadId}>
+            {thread.firstMessage || thread.threadId}
+          </option>
+        ))}
+      </select>
+
+      {/* Chat will automatically load the selected thread */}
+      <CopilotChat
+        agentId="my-agent"
+        threadId={currentThread}
+      />
+    </div>
+  );
+}
+```
+
+## Customizing the Thread List
+
+### Custom Thread Renderer
+
+```tsx
+<CopilotThreadList
+  threadItem={({ thread, isActive, onClick }) => (
+    <button
+      type="button"
+      onClick={onClick}
+      className={[
+        "flex w-full flex-col items-start gap-1 rounded-md border p-3 text-left transition",
+        isActive ? "border-primary bg-primary/10" : "hover:bg-muted",
+      ].join(" ")}
+    >
+      <h4 className="text-sm font-medium">{thread.firstMessage || "Untitled conversation"}</h4>
+      <span className="text-xs text-muted-foreground">
+        {thread.messageCount} messages {thread.isRunning ? "• Running" : ""}
+      </span>
+    </button>
+  )}
+/>
+```
+
+### Custom Empty State
+
+```tsx
+import { randomUUID } from "@copilotkitnext/shared";
+import { CopilotThreadList, useThreads, useCopilotChatConfiguration } from "@copilotkitnext/react";
+
+function ThreadListWithEmptyState() {
+  const { threads, isLoading } = useThreads();
+  const config = useCopilotChatConfiguration();
+
+  if (isLoading) {
+    return <div className="p-6 text-sm text-muted-foreground">Loading threads…</div>;
+  }
+
+  if (threads.length === 0) {
+    return (
+      <div className="flex flex-col items-center gap-3 rounded-lg border border-dashed p-8 text-center">
+        <p className="text-muted-foreground">No conversations yet</p>
+        <button
+          type="button"
+          className="rounded bg-primary px-4 py-2 text-primary-foreground"
+          onClick={() => config?.setThreadId(randomUUID())}
+        >
+          Start chatting
+        </button>
+      </div>
+    );
+  }
+
+  return <CopilotThreadList />;
+}
+```
+
+### Pagination
+
+```tsx
+function PaginatedThreadList() {
+  const [offset, setOffset] = useState(0);
+  const limit = 20;
+  const { threads, total, fetchThreads } = useThreads({ limit });
+
+  const handleNextPage = () => {
+    const newOffset = offset + limit;
+    setOffset(newOffset);
+    fetchThreads(newOffset);
+  };
+
+  const handlePrevPage = () => {
+    const newOffset = Math.max(0, offset - limit);
+    setOffset(newOffset);
+    fetchThreads(newOffset);
+  };
+
+  return (
+    <div>
+      <CopilotThreadList limit={limit} />
+      <div>
+        <button onClick={handlePrevPage} disabled={offset === 0}>
+          Previous
+        </button>
+        <span>Showing {offset + 1}-{Math.min(offset + limit, total)} of {total}</span>
+        <button onClick={handleNextPage} disabled={offset + limit >= total}>
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Backend Configuration
+
+Thread storage is handled automatically by the AgentRunner. Choose the appropriate runner for your deployment:
+
+### In-Memory (Development)
+
+```typescript
+import { CopilotRuntime, InMemoryAgentRunner } from "@copilotkitnext/runtime";
+
+const runtime = new CopilotRuntime({
+  agents: myAgents,
+  runner: new InMemoryAgentRunner(), // Default
+});
+```
+
+### SQLite (Single Server)
+
+```typescript
+import { SqliteAgentRunner } from "@copilotkitnext/runtime";
+
+const runtime = new CopilotRuntime({
+  agents: myAgents,
+  runner: new SqliteAgentRunner({
+    dbPath: "./copilot.db", // Persistent storage
+  }),
+});
+```
+
+### Enterprise (Multi-Server with Redis)
+
+```typescript
+import { EnterpriseAgentRunner } from "@copilotkitnext/runtime";
+import { Kysely } from "kysely";
+import Redis from "ioredis";
+
+const runtime = new CopilotRuntime({
+  agents: myAgents,
+  runner: new EnterpriseAgentRunner({
+    kysely: new Kysely({
+      // Your database config
+    }),
+    redis: new Redis({
+      // Your Redis config
+    }),
+  }),
+});
+```
+
+## API Reference
+
+### Components
+
+- [`CopilotThreadList`](/reference/copilot-thread-list) - Thread list UI component
+
+### Hooks
+
+- [`useThreads`](/reference/use-threads) - Hook for managing threads
+
+### Core Methods
+
+- `core.listThreads(params)` - List all threads
+- `core.getThreadMetadata(threadId)` - Get single thread metadata
+
+## Best Practices
+
+1. **Always use stable thread IDs**: Generate thread IDs once and persist them in your app state
+2. **Handle loading states**: Thread fetching is async, show loading indicators
+3. **Implement error handling**: Network requests can fail, provide fallback UI
+4. **Consider pagination**: For apps with many threads, implement pagination
+5. **Provide visual feedback**: Show active threads, running status, etc.
+
+## Examples
+
+Check out our Storybook for interactive examples:
+- Basic thread list
+- Thread list with chat integration
+- Custom thread renderers
+- Pagination examples
+
+## Troubleshooting
+
+### Threads not showing up
+
+- Ensure `runtimeUrl` is set in CopilotKitProvider
+- Check that threads have been created (send at least one message)
+- Verify your backend is running and accessible
+
+### Thread switching not working
+
+- Ensure `threadId` prop on CopilotChat changes when selecting a new thread
+- Check browser console for connection errors
+- Verify the thread exists by calling `getThreadMetadata`
+
+### Performance issues with many threads
+
+- Implement pagination using the `limit` and `offset` parameters
+- Consider implementing search/filter functionality
+- Use custom renderers to optimize rendering