feat(inspector): add thread store registry, runtime handlers, and useThreads hook

- CopilotKitCore gains a ThreadStoreRegistry (register/unregister by agentId)
  and a new onAgentRunStarted subscriber event so the inspector can subscribe
  before agent.runAgent() snapshots the subscriber list
- Runtime gains handleListThreads, handleUpdateThread, handleArchiveThread,
  handleDeleteThread, handleSubscribeToThreads, and handleGetThreadMessages
  handlers; all mutations are authenticated via identifyUser (request body
  userId is ignored)
- InMemoryAgentRunner now stores thread history for the local-dev fallback
  path; debug console.log removed; InMemoryThread uses literal types for
  constant-value fields (organizationId: "", createdById: "", archived: false)
- useThreads hook registers its store with CopilotKitCore on mount and
  unregisters on unmount so the inspector can read thread state

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: marthakelly

examples/v2/angular/demo/src/app/routes/headless/headless-chat.component.ts

@@ -5,6 +5,7 @@ import {
   inject,
   input,
   signal,
+  NgZone,
   OnDestroy,
   OnInit,
 } from "@angular/core";
@@ -17,12 +18,13 @@ import {
   HumanInTheLoopToolRenderer,
   injectAgentStore,
   registerHumanInTheLoop,
-} from "@copilotkit/angular";
-import { RenderToolCalls } from "@copilotkit/angular";
+} from "@copilotkitnext/angular";
+import { RenderToolCalls } from "@copilotkitnext/angular";
 import {
   WEB_INSPECTOR_TAG,
   type WebInspectorElement,
 } from "@copilotkit/web-inspector";
+import { defineInspectorElements } from "@copilotkit/web-inspector-angular";
 import { z } from "zod";
 
 @Component({
@@ -123,6 +125,20 @@ export class RequireApprovalComponent implements HumanInTheLoopToolRenderer {
         >
           Send
         </button>
+        <button
+          type="button"
+          (click)="clearThreads()"
+          style="
+            padding: 10px 14px;
+            border-radius: 8px;
+            border: 1px solid #d1d5db;
+            background: #ffffff;
+            color: #374151;
+            cursor: pointer;
+          "
+        >
+          Clear threads
+        </button>
       </form>
     </div>
   `,
@@ -156,9 +172,13 @@ export class HeadlessChatComponent implements OnInit, OnDestroy {
     );
   }
 
+  private ngZone = inject(NgZone);
+
   ngOnInit(): void {
     if (typeof document === "undefined") return;
 
+    this.ngZone.runOutsideAngular(() => defineInspectorElements());
+
     const existing =
       document.querySelector<WebInspectorElement>(WEB_INSPECTOR_TAG);
     const inspector =
@@ -181,6 +201,13 @@ export class HeadlessChatComponent implements OnInit, OnDestroy {
     this.inspectorElement = null;
   }
 
+  async clearThreads() {
+    const runtimeUrl = this.copilotkit.core?.runtimeUrl;
+    if (!runtimeUrl) return;
+    const url = runtimeUrl.replace(/\/$/, "");
+    await fetch(`${url}/threads`, { method: "DELETE", credentials: "include" });
+  }
+
   async send() {
     const content = this.inputValue.trim();
     const agent = this.agent();

lefthook.yml

@@ -38,7 +38,7 @@ pre-commit:
 
         for f in $STAGED; do
           [ ! -f "$f" ] && continue
-          case "$f" in pnpm-lock.yaml|*/package-lock.json) continue ;; esac
+          case "$f" in pnpm-lock.yaml|*/package-lock.json|showcase/shell/src/data/demo-content.json|showcase/shell-dojolike/src/data/demo-content.json) continue ;; esac
           SIZE=$(wc -c < "$f" | tr -d ' ')
           if [ "$SIZE" -gt 1048576 ]; then
             echo "Oversized file: $f ($((SIZE / 1024)) KB)"

packages/core/src/core/core.ts

@@ -20,6 +20,8 @@ import {
   CopilotKitCoreRunToolResult,
 } from "./run-handler";
 import { StateManager } from "./state-manager";
+import { ThreadStoreRegistry } from "./thread-store-registry";
+import { type ɵThreadStore } from "../threads";
 
 /** Configuration options for `CopilotKitCore`. */
 export interface CopilotKitCoreConfig {
@@ -153,10 +155,20 @@ export interface CopilotKitCoreSubscriber {
     code: CopilotKitCoreErrorCode;
     context: Record<string, any>;
   }) => void | Promise<void>;
+  onThreadStoreRegistered?: (event: {
+    copilotkit: CopilotKitCore;
+    agentId: string;
+    store: ɵThreadStore;
+  }) => void | Promise<void>;
+  onThreadStoreUnregistered?: (event: {
+    copilotkit: CopilotKitCore;
+    agentId: string;
+  }) => void | Promise<void>;
   /**
-   * Fired when an agent run or connect begins. The `agent` may be a per-thread
-   * clone that is not present in `core.agents`. Subscribers (e.g. the inspector)
-   * can use this to subscribe to the clone's AG-UI events.
+   * Fired immediately before each agent run, including per-thread clones that
+   * are not in the agent registry and therefore not surfaced via onAgentsChanged.
+   * Subscribers that track agent events (e.g. the web inspector) can use this
+   * to subscribe to the concrete agent instance that will emit events.
    */
   onAgentRunStarted?: (event: {
     copilotkit: CopilotKitCore;
@@ -237,6 +249,7 @@ export class CopilotKitCore {
   private suggestionEngine: SuggestionEngine;
   private runHandler: RunHandler;
   private stateManager: StateManager;
+  private threadStoreRegistry: ThreadStoreRegistry;
 
   constructor({
     runtimeUrl,
@@ -258,6 +271,7 @@ export class CopilotKitCore {
     this.suggestionEngine = new SuggestionEngine(this);
     this.runHandler = new RunHandler(this);
     this.stateManager = new StateManager(this);
+    this.threadStoreRegistry = new ThreadStoreRegistry(this);
 
     // Initialize each subsystem
     this.agentRegistry.initialize(agents__unsafe_dev_only);
@@ -276,6 +290,14 @@ export class CopilotKitCore {
             this.stateManager.subscribeToAgent(agent);
           }
         });
+
+        // Unregister thread stores for agents that are no longer present
+        const currentAgentIds = new Set(Object.keys(agents));
+        for (const agentId of Object.keys(this.threadStoreRegistry.getAll())) {
+          if (!currentAgentIds.has(agentId)) {
+            this.threadStoreRegistry.unregister(agentId);
+          }
+        }
       },
     });
   }
@@ -482,6 +504,25 @@ export class CopilotKitCore {
     this.contextStore.removeContext(id);
   }
 
+  /**
+   * Thread store registry (delegated to ThreadStoreRegistry)
+   */
+  registerThreadStore(agentId: string, store: ɵThreadStore): void {
+    this.threadStoreRegistry.register(agentId, store);
+  }
+
+  unregisterThreadStore(agentId: string): void {
+    this.threadStoreRegistry.unregister(agentId);
+  }
+
+  getThreadStore(agentId: string): ɵThreadStore | undefined {
+    return this.threadStoreRegistry.get(agentId);
+  }
+
+  getThreadStores(): Readonly<Record<string, ɵThreadStore>> {
+    return this.threadStoreRegistry.getAll();
+  }
+
   /**
    * Suggestions management (delegated to SuggestionEngine)
    */

packages/core/src/core/run-handler.ts

@@ -294,15 +294,13 @@ export class RunHandler {
     // does not overwrite the registry agent's subscription.
     this._internal.subscribeAgentToStateManager(agent);
 
-    // Notify subscribers (e.g. the inspector) about the agent that is about
-    // to run. This is critical for per-thread clones that are not present in
-    // the agent registry and would otherwise be invisible to subscribers.
+    // Notify subscribers (e.g. the web inspector) that a run is about to start
+    // on this specific agent instance. Must be awaited so that subscribers can
+    // call agent.subscribe() before agent.runAgent() captures its subscriber
+    // snapshot — agent.runAgent() snapshots [this.subscribers] synchronously.
     await this._internal.notifySubscribers(
       (subscriber) =>
-        subscriber.onAgentRunStarted?.({
-          copilotkit: this.core,
-          agent,
-        }),
+        subscriber.onAgentRunStarted?.({ copilotkit: this.core, agent }),
       "Subscriber onAgentRunStarted error:",
     );
 

packages/core/src/core/thread-store-registry.ts

@@ -0,0 +1,58 @@
+import { type ɵThreadStore } from "../threads";
+import type { CopilotKitCore } from "./core";
+import { CopilotKitCoreFriendsAccess, CopilotKitCoreSubscriber } from "./core";
+
+export class ThreadStoreRegistry {
+  private _stores: Record<string, ɵThreadStore> = {};
+
+  constructor(private core: CopilotKitCore) {}
+
+  register(agentId: string, store: ɵThreadStore): void {
+    this._stores[agentId] = store;
+    void this.notifyRegistered(agentId, store);
+  }
+
+  unregister(agentId: string): void {
+    if (!(agentId in this._stores)) return;
+    delete this._stores[agentId];
+    void this.notifyUnregistered(agentId);
+  }
+
+  get(agentId: string): ɵThreadStore | undefined {
+    return this._stores[agentId];
+  }
+
+  getAll(): Readonly<Record<string, ɵThreadStore>> {
+    return this._stores;
+  }
+
+  private async notifyRegistered(
+    agentId: string,
+    store: ɵThreadStore,
+  ): Promise<void> {
+    await (
+      this.core as unknown as CopilotKitCoreFriendsAccess
+    ).notifySubscribers(
+      (subscriber: CopilotKitCoreSubscriber) =>
+        subscriber.onThreadStoreRegistered?.({
+          copilotkit: this.core,
+          agentId,
+          store,
+        }),
+      "Subscriber onThreadStoreRegistered error:",
+    );
+  }
+
+  private async notifyUnregistered(agentId: string): Promise<void> {
+    await (
+      this.core as unknown as CopilotKitCoreFriendsAccess
+    ).notifySubscribers(
+      (subscriber: CopilotKitCoreSubscriber) =>
+        subscriber.onThreadStoreUnregistered?.({
+          copilotkit: this.core,
+          agentId,
+        }),
+      "Subscriber onThreadStoreUnregistered error:",
+    );
+  }
+}

packages/core/src/threads.ts

@@ -374,6 +374,8 @@ interface ThreadStore {
   start(): void;
   stop(): void;
   setContext(context: ThreadRuntimeContext | null): void;
+  /** Re-fetches the thread list without resetting the current list to empty. */
+  refresh(): void;
   fetchNextPage(): void;
   renameThread(threadId: string, name: string): Promise<void>;
   archiveThread(threadId: string): Promise<void>;
@@ -959,6 +961,11 @@ function createThreadStore(environment: ThreadEnvironment): ThreadStore {
     setContext(context: ThreadRuntimeContext | null): void {
       store.dispatch(threadAdapterEvents.contextChanged({ context }));
     },
+    refresh(): void {
+      const { sessionId, context } = store.getState();
+      if (!context) return;
+      store.dispatch(threadRestEvents.listRequested({ sessionId }));
+    },
     fetchNextPage(): void {
       store.dispatch(threadAdapterEvents.fetchNextPageRequested());
     },

packages/react-core/src/v2/hooks/__tests__/use-threads.test.tsx

@@ -152,6 +152,8 @@ function setupCopilotKit(runtimeUrl = "http://localhost:4000") {
       intelligence: {
         wsUrl: "ws://localhost:4000/client",
       },
+      registerThreadStore: vi.fn(),
+      unregisterThreadStore: vi.fn(),
     },
   });
 }

packages/react-core/src/v2/hooks/use-threads.tsx

@@ -221,6 +221,13 @@ export function useThreads({
     };
   }, [store]);
 
+  useEffect(() => {
+    copilotkit.registerThreadStore(agentId, store);
+    return () => {
+      copilotkit.unregisterThreadStore(agentId);
+    };
+  }, [copilotkit, agentId, store]);
+
   useEffect(() => {
     const context: ɵThreadRuntimeContext | null = copilotkit.runtimeUrl
       ? {

packages/runtime/src/v2/runtime/__tests__/handle-threads.test.ts

@@ -46,18 +46,18 @@ describe("thread handlers", () => {
       body: JSON.stringify(body),
     });
 
-  it("returns 422 when intelligence is not configured for listThreads", async () => {
+  it("returns empty thread list when intelligence is not configured for listThreads", async () => {
     const runtime = new CopilotRuntime({ agents: {} });
 
     const response = await handleListThreads({
       runtime,
       request: new Request("https://example.com/threads?agentId=agent-1"),
     });
 
-    expect(response.status).toBe(422);
+    expect(response.status).toBe(200);
     await expect(response.json()).resolves.toEqual({
-      error:
-        "Missing CopilotKitIntelligence configuration. Thread operations require a CopilotKitIntelligence instance to be provided in CopilotRuntime options.",
+      threads: [],
+      nextCursor: null,
     });
   });
 

packages/runtime/src/v2/runtime/handlers/handle-run.ts

@@ -35,6 +35,10 @@ export async function handleRunAgent({
       return agent;
     }
 
+    // Ensure the clone carries the registry key so InMemoryAgentRunner can
+    // tag historic runs with the correct agentId for filtering.
+    agent.agentId = agentId;
+
     configureAgentForRequest({ runtime, request, agentId, agent });
 
     if (