docs(threads): align pagination API names and document lock tuning options

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: BenTaylorDev

docs/content/docs/(root)/threads.mdx

@@ -42,10 +42,23 @@ CopilotKit threads enable persistent, resumable multi-turn conversations. The `u
       // Thread names are auto-generated by default.
       // Set to false to disable:
       // generateThreadNames: false,
+
+      // Optional: tune thread lock behavior
+      // lockTtlSeconds: 20,              // Lock TTL (default 20s, max 3600s)
+      // lockHeartbeatIntervalSeconds: 15, // Heartbeat interval (default 15s, max 3000s)
+      // lockKeyPrefix: "my-app",          // Custom Redis key prefix for the lock
     });
     ```
 
     If you're using Copilot Cloud, thread storage is handled automatically. For self-hosted Enterprise, configure your database connection per the Enterprise setup guide.
+
+    **Thread lock options:** When an agent run starts, the runtime acquires a lock on the thread to prevent concurrent runs. You can tune this behavior:
+
+    | Option | Default | Max | Description |
+    |--------|---------|-----|-------------|
+    | `lockTtlSeconds` | `20` | `3600` (1 hour) | How long the lock is held before it expires automatically. |
+    | `lockHeartbeatIntervalSeconds` | `15` | `3000` (50 min) | How often the runtime renews the lock during a run. |
+    | `lockKeyPrefix` | — | — | Custom Redis key prefix for the thread lock. Useful when multiple apps share a Redis instance. |
   </Step>
 
   <Step>
@@ -122,21 +135,21 @@ CopilotKit threads enable persistent, resumable multi-turn conversations. The `u
     ```tsx title="ThreadSidebar.tsx"
     const {
       threads,
-      hasNextPage,
-      isFetchingNextPage,
-      fetchNextPage,
+      hasMoreThreads,
+      isFetchingMoreThreads,
+      fetchMoreThreads,
     } = useThreads({
       agentId: "my-agent",
       limit: 20, // [!code highlight]
     });
 
     // In your JSX:
-    {hasNextPage && (
+    {hasMoreThreads && (
       <button
-        onClick={fetchNextPage}
-        disabled={isFetchingNextPage}
+        onClick={fetchMoreThreads}
+        disabled={isFetchingMoreThreads}
       >
-        {isFetchingNextPage ? "Loading..." : "Load more"}
+        {isFetchingMoreThreads ? "Loading..." : "Load more"}
       </button>
     )}
     ```

docs/content/docs/learn/threads.mdx

@@ -23,7 +23,7 @@ From a developer's perspective, threads involve three things:
 
 | What you use | What it does |
 |-------------|-------------|
-| `useThreads` hook | Lists, renames, archives, and deletes threads. Stays in sync across tabs and devices via WebSocket. |
+| `useThreads` hook | Lists, renames, archives, and deletes threads. Pagination via `hasMoreThreads` / `fetchMoreThreads`. Stays in sync across tabs and devices via WebSocket. |
 | `CopilotChat` with `threadId` | Connects to a specific thread, loads its history, and streams new events in realtime. |
 | `CopilotRuntime` | Server-side layer that executes agents, stores thread data on the Intelligence Platform, and relays events to connected clients. |
 
@@ -114,6 +114,16 @@ If the WebSocket connection drops (network change, server restart, laptop sleep)
 
 If a thread already has an active run and another client tries to start a new run on the same thread, the request is rejected with a **409 Conflict**. This prevents two agent runs from interleaving events on the same thread. The existing run must complete or be stopped before a new one can begin.
 
+The runtime acquires a Redis-backed lock on the thread for the duration of each run. You can tune this behavior on the runtime:
+
+| Option | Default | Max | Description |
+|--------|---------|-----|-------------|
+| `lockTtlSeconds` | `20` | `3600` (1 hour) | How long the lock is held before it expires automatically. |
+| `lockHeartbeatIntervalSeconds` | `15` | `3000` (50 min) | How often the runtime renews the lock during a run. The heartbeat always runs — you only need to adjust the interval. |
+| `lockKeyPrefix` | — | — | Custom Redis key prefix for the thread lock. Useful when multiple apps share a Redis instance. |
+
+If a run completes normally, the lock is released immediately. The TTL is a safety net for cases where the runtime crashes without releasing the lock.
+
 ## Design decisions
 
 ### Why event replay instead of message snapshots?

docs/content/docs/learn/tutorials/multi-conversation-chat.mdx

@@ -228,9 +228,9 @@ A chat application with a thread sidebar — similar to ChatGPT or Claude's conv
     const {
       threads,
       isLoading,
-      hasNextPage, // [!code highlight]
-      isFetchingNextPage, // [!code highlight]
-      fetchNextPage, // [!code highlight]
+      hasMoreThreads, // [!code highlight]
+      isFetchingMoreThreads, // [!code highlight]
+      fetchMoreThreads, // [!code highlight]
       renameThread,
       archiveThread,
     } = useThreads({
@@ -239,13 +239,13 @@ A chat application with a thread sidebar — similar to ChatGPT or Claude's conv
     });
 
     // At the bottom of the thread list:
-    {hasNextPage && (
+    {hasMoreThreads && (
       <button
         className="m-3 p-2 text-sm text-gray-500 hover:text-gray-700"
-        onClick={fetchNextPage}
-        disabled={isFetchingNextPage}
+        onClick={fetchMoreThreads}
+        disabled={isFetchingMoreThreads}
       >
-        {isFetchingNextPage ? "Loading..." : "Load older conversations"}
+        {isFetchingMoreThreads ? "Loading..." : "Load older conversations"}
       </button>
     )}
     ```

docs/content/docs/reference/v2/hooks/useThreads.mdx

@@ -32,7 +32,7 @@ function useThreads(input: UseThreadsInput): UseThreadsResult
   </PropertyReference>
 
   <PropertyReference name="limit" type="number" default="undefined">
-    Maximum number of threads to fetch per page. When set, enables cursor-based pagination via `fetchNextPage()` and `hasNextPage`.
+    Maximum number of threads to fetch per page. When set, enables cursor-based pagination via `fetchMoreThreads()` and `hasMoreThreads`.
   </PropertyReference>
 </PropertyReference>
 
@@ -45,6 +45,7 @@ function useThreads(input: UseThreadsInput): UseThreadsResult
   <PropertyReference name="threads" type="Thread[]">
     Array of threads for the current user and agent, sorted by most recently updated first. Each `Thread` contains:
     - `id: string` — unique thread identifier
+    - `agentId: string` — the agent this thread belongs to
     - `name: string | null` — thread name (auto-generated by the LLM on first run, or set manually via `renameThread`)
     - `archived: boolean` — whether the thread is archived
     - `createdAt: string` — ISO 8601 timestamp
@@ -59,18 +60,18 @@ function useThreads(input: UseThreadsInput): UseThreadsResult
     The most recent error from fetching or mutating threads, or `null` if no error has occurred.
   </PropertyReference>
 
-  <PropertyReference name="hasNextPage" type="boolean">
+  <PropertyReference name="hasMoreThreads" type="boolean">
     `true` when more threads are available beyond the current page. Only meaningful when `limit` is set.
   </PropertyReference>
 
-  <PropertyReference name="isFetchingNextPage" type="boolean">
-    `true` while the next page of threads is being fetched.
+  <PropertyReference name="isFetchingMoreThreads" type="boolean">
+    `true` while additional threads are being fetched.
   </PropertyReference>
 
   ### Methods
 
-  <PropertyReference name="fetchNextPage" type="() => void">
-    Fetch the next page of threads. No-op if `hasNextPage` is `false` or a fetch is already in progress.
+  <PropertyReference name="fetchMoreThreads" type="() => void">
+    Fetch the next page of threads. No-op if `hasMoreThreads` is `false` or a fetch is already in progress.
   </PropertyReference>
 
   <PropertyReference name="renameThread" type="(threadId: string, name: string) => Promise<void>">

docs/snippets/shared/threads/threads.mdx

@@ -35,6 +35,11 @@ CopilotKit threads enable persistent, resumable multi-turn conversations. The `u
       // Thread names are auto-generated by default.
       // Set to false to disable:
       // generateThreadNames: false,
+
+      // Optional: tune thread lock behavior
+      // lockTtlSeconds: 20,              // Lock TTL (default 20s, max 3600s)
+      // lockHeartbeatIntervalSeconds: 15, // Heartbeat interval (default 15s, max 3000s)
+      // lockKeyPrefix: "my-app",          // Custom Redis key prefix for the lock
     });
     ```
 
@@ -115,21 +120,21 @@ CopilotKit threads enable persistent, resumable multi-turn conversations. The `u
     ```tsx title="ThreadSidebar.tsx"
     const {
       threads,
-      hasNextPage,
-      isFetchingNextPage,
-      fetchNextPage,
+      hasMoreThreads,
+      isFetchingMoreThreads,
+      fetchMoreThreads,
     } = useThreads({
       agentId: "my-agent",
       limit: 20, // [!code highlight]
     });
 
     // In your JSX:
-    {hasNextPage && (
+    {hasMoreThreads && (
       <button
-        onClick={fetchNextPage}
-        disabled={isFetchingNextPage}
+        onClick={fetchMoreThreads}
+        disabled={isFetchingMoreThreads}
       >
-        {isFetchingNextPage ? "Loading..." : "Load more"}
+        {isFetchingMoreThreads ? "Loading..." : "Load more"}
       </button>
     )}
     ```