feat(inspector): CPK-7193 thread store registry, runtime handlers, and Threads tab UI (CopilotKit#3869)

## What this PR does

Adds the **Threads tab** to the CopilotKit web inspector. The tab lists
every thread the current agent has run and, when you click one, shows
three per-thread sub-tabs:

- **Conversation** — historical messages
- **Agent State** — state snapshot at the end of the thread
- **AG-UI Events** — full AG-UI event stream for the thread (tool calls,
state deltas, text chunks, etc.)

Data flows through new backend endpoints plus a Lit-based UI inside
`@copilotkit/web-inspector`. No extra package required for consumers.

## Changes by layer

### `@copilotkit/core`
- **`ThreadStoreRegistry`** — new class; keyed by `agentId`, lets
`useThreads()` and the inspector share a reference to the same store
without coupling the two packages directly
- **`onAgentRunStarted` subscriber event** — fires before
`agent.runAgent()` snapshots the subscriber list, so the inspector can
subscribe in time to receive run events
- `CopilotKitCore.getThreadStore()` / `registerThreadStore()` /
`unregisterThreadStore()` / `getThreadStores()` — public surface for
hook + inspector to interact with the registry

### `@copilotkit/runtime`
- **Thread HTTP handlers** — `handleListThreads`, `handleUpdateThread`,
`handleArchiveThread`, `handleDeleteThread`, `handleSubscribeToThreads`,
`handleGetThreadMessages`, plus the two new ones below
- **New: `GET /threads/:id/events`** and **`GET /threads/:id/state`** —
return the thread's AG-UI event stream and last `STATE_SNAPSHOT`
payload. Wired through both the in-memory runner and the Intelligence
platform's `_inspect/threads/:id/{events,state}` endpoints (consumed by
`CopilotKitIntelligence.getThreadEvents()` / `getThreadState()`)
- All mutations authenticate via `identifyUser(request)`; `userId` in
the request body is ignored
- **`InMemoryAgentRunner`** — stores thread history (messages +
compacted events per run); new `getThreadEvents()` and
`getThreadState()` methods; `getThreadState()` walks the compacted
events and returns the payload of the last `STATE_SNAPSHOT`

### `@copilotkit/react-core`
- **`useThreads` hook** — fetches threads, subscribes to a Phoenix
WebSocket channel for real-time metadata events, and
registers/unregisters its thread store with `CopilotKitCore` on
mount/unmount

### `@copilotkit/web-inspector`
- **Full Threads tab UI** — implemented in Lit as two custom elements
(`cpk-thread-list`, `ɵCpkThreadDetails`) living in-file alongside the
main `WebInspectorElement`
- Thread details fetches per-thread history via the new endpoints and
renders:
- Conversation: user/assistant bubbles, tool-call blocks with
expand/collapse, tool-call groups, reasoning/state-update chips,
generative-UI placeholders. Tool-call status is derived from parsed-args
presence — frontend-rendered generative-UI tools (charts, custom UI)
read `DONE` once args have streamed in, since they never produce a
`role: tool` result message
  - Agent State: syntax-highlighted JSON of the last state snapshot
- AG-UI Events: colored event rows (by type family) with timestamped,
highlighted payloads. Off-screen rows use `content-visibility: auto` so
reveal cost is independent of total event count
- Right-side detail panel with thread metadata + activity counts,
toggled from the tab bar
- Tab DOM is mounted once per activation and hidden via `display:none`
when inactive, so switching between Conversation / Agent State / AG-UI
Events is a CSS swap rather than a render. Each panel's TemplateResult
is memoized by tuple of input references (`_conversation` + expand-state
Sets for conversation; `_fetchedState` for agent state; events array for
AG-UI events), so when the underlying data hasn't changed Lit's diff
short-circuits. JSON syntax highlighting is WeakMap-memoized by payload
reference
- `attachToCore()` guards the `core.getThreadStores()` call so consumers
still on an older `@copilotkit/core` don't throw when assigning
`inspector.core`

## Architectural notes

**Events/state via Intelligence:** the Intelligence platform persists
every AG-UI event in `cpki.run_events` keyed by run → thread and exposes
them via `_inspect/threads/:id/{events,state}`. The runtime's
`CopilotKitIntelligence.getThreadEvents()` / `getThreadState()` consume
those, so the same per-thread HTTP endpoints used by the in-memory path
serve Intelligence-backed consumers identically.

## Tests added

| File | What's new |
|---|---|
| `packages/core/src/__tests__/thread-store-registry.test.ts` | New —
register/get, replacement, no-op unregister, subscriber events |
| `packages/runtime/src/v2/runtime/__tests__/handle-threads.test.ts` |
`handleClearThreads`, `handleGetThreadMessages`, plus new
`handleGetThreadEvents` and `handleGetThreadState` describe blocks |
|
`packages/runtime/src/v2/runtime/runner/__tests__/in-memory-runner.test.ts`
| `getThreadMessages`, new `getThreadEvents` (stored events, unknown
thread, multi-run flattening), new `getThreadState` (null without
snapshot, returns last STATE_SNAPSHOT, most-recent across runs) |
| `packages/react-core/src/v2/hooks/__tests__/use-threads.test.tsx` |
Registry lifecycle (register on mount, unregister on unmount) |
| `packages/web-inspector/src/__tests__/web-inspector.spec.ts` | New
`ɵCpkThreadDetails caching` describe — threadId-change drops all panel
caches; conversation cache invalidates on `_conversation` reassignment
and on expand-state change; state and events caches invalidate on their
fetched-data reassignment |

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: tylerslaton

examples/v2/angular/demo/angular.json

@@ -15,7 +15,7 @@
             "browser": "src/main.ts",
             "tsConfig": "tsconfig.app.json",
             "assets": ["src/favicon.ico", "src/assets"],
-            "styles": ["node_modules/@copilotkit/angular/dist/styles.css"],
+            "styles": ["node_modules/@copilotkitnext/angular/dist/styles.css"],
             "optimization": false
           }
         },

examples/v2/angular/demo/package.json

@@ -23,6 +23,7 @@
     "@angular/forms": "^19.0.0",
     "@angular/platform-browser": "^19.0.0",
     "@angular/platform-browser-dynamic": "^19.0.0",
+    "@copilotkit/angular": "link:../../../../packages/angular",
     "@copilotkit/web-inspector": "workspace:*",
     "@copilotkitnext/angular": "workspace:*",
     "compare-versions": "^6.1.1",

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

@@ -1,28 +1,27 @@
+import type { OnDestroy, OnInit } from "@angular/core";
 import {
   Component,
   ChangeDetectionStrategy,
   computed,
   inject,
   input,
   signal,
-  OnDestroy,
-  OnInit,
 } from "@angular/core";
 import { CommonModule } from "@angular/common";
 import { FormsModule } from "@angular/forms";
+import type {
+  HumanInTheLoopToolCall,
+  HumanInTheLoopToolRenderer,
+} from "@copilotkitnext/angular";
 import {
   connectAgentContext,
   CopilotKit,
-  HumanInTheLoopToolCall,
-  HumanInTheLoopToolRenderer,
   injectAgentStore,
   registerHumanInTheLoop,
-} from "@copilotkit/angular";
-import { RenderToolCalls } from "@copilotkit/angular";
-import {
-  WEB_INSPECTOR_TAG,
-  type WebInspectorElement,
-} from "@copilotkit/web-inspector";
+} from "@copilotkitnext/angular";
+import { RenderToolCalls } from "@copilotkitnext/angular";
+import { WEB_INSPECTOR_TAG } from "@copilotkit/web-inspector";
+import type { WebInspectorElement } from "@copilotkit/web-inspector";
 import { z } from "zod";
 
 @Component({
@@ -123,6 +122,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>
   `,
@@ -181,6 +194,25 @@ export class HeadlessChatComponent implements OnInit, OnDestroy {
     this.inspectorElement = null;
   }
 
+  async clearThreads() {
+    const runtimeUrl = this.copilotkit.core?.runtimeUrl;
+    if (!runtimeUrl) return;
+    const url = runtimeUrl.replace(/\/$/, "");
+    try {
+      const res = await fetch(`${url}/threads/clear`, {
+        method: "POST",
+        credentials: "include",
+      });
+      if (!res.ok) {
+        console.error(
+          `Failed to clear threads: HTTP ${res.status} ${res.statusText}`,
+        );
+      }
+    } catch (err) {
+      console.error("Failed to clear threads", err);
+    }
+  }
+
   async send() {
     const content = this.inputValue.trim();
     const agent = this.agent();

examples/v2/angular/demo/tsconfig.json

@@ -14,7 +14,7 @@
     "paths": {
       "@copilotkit/angular": [
         "../../packages/angular/dist/index.d.ts",
-        "../../packages/angular/dist/fesm2022/copilotkit-angular.mjs"
+        "../../packages/angular/dist/fesm2022/copilotkitnext-angular.mjs"
       ],
       "@copilotkit/core": [
         "../../packages/core/dist/index.d.ts",

packages/core/src/__tests__/core-thread-store-auto-unregister.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi } from "vitest";
+import { CopilotKitCore } from "../core";
+import type { CopilotKitCoreSubscriber } from "../core/core";
+import type { ɵThreadStore } from "../threads";
+import { MockAgent } from "./test-utils";
+
+/**
+ * Pins the integration contract between `CopilotKitCore.onAgentsChanged`
+ * and the thread-store registry.
+ *
+ * Background: when `agents` change, the core auto-unregisters thread stores
+ * for any agentId that has been removed. The "previously had" guard exists
+ * so that the FIRST onAgentsChanged({ agents: {} }) notification — which
+ * fires for published cores BEFORE the published agents are merged in —
+ * does not rip out a store that a consumer (e.g. useThreads) just
+ * registered.
+ */
+
+function makeStore(id = "store"): ɵThreadStore & { __testId: string } {
+  const store: ɵThreadStore = {
+    start: vi.fn(),
+    stop: vi.fn(),
+    setContext: vi.fn(),
+    refresh: vi.fn(),
+    fetchNextPage: vi.fn(),
+    renameThread: vi.fn(),
+    archiveThread: vi.fn(),
+    deleteThread: vi.fn(),
+    getState: vi.fn(),
+    select: vi.fn(),
+  };
+  return Object.assign(store, { __testId: id });
+}
+
+describe("CopilotKitCore — onAgentsChanged auto-unregister", () => {
+  it("unregisters a thread store when its agent is removed from agents", async () => {
+    // Start with agent-1 registered. Add a thread store for it. Then remove
+    // agent-1 and confirm the store is auto-unregistered AND the
+    // onThreadStoreUnregistered subscriber is notified with the previous
+    // store as `prevStore`.
+    const agent1 = new MockAgent({ agentId: "agent-1" });
+    const core = new CopilotKitCore({
+      agents__unsafe_dev_only: { "agent-1": agent1 as never },
+    });
+
+    const store = makeStore("agent-1-store");
+    core.registerThreadStore("agent-1", store);
+    expect(core.getThreadStore("agent-1")).toBe(store);
+
+    const onUnregistered = vi.fn();
+    const subscriber: CopilotKitCoreSubscriber = {
+      onThreadStoreUnregistered: onUnregistered,
+    };
+    core.subscribe(subscriber);
+
+    // Removing agent-1 triggers onAgentsChanged({ agents: {} }) — but agent-1
+    // WAS in the previous snapshot, so the auto-unregister must fire here.
+    core.removeAgent__unsafe_dev_only("agent-1");
+    // Subscriber notification is fire-and-forget; flush microtasks.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(core.getThreadStore("agent-1")).toBeUndefined();
+    expect(onUnregistered).toHaveBeenCalledWith(
+      expect.objectContaining({ agentId: "agent-1", prevStore: store }),
+    );
+  });
+
+  it("does NOT unregister a freshly-registered store on the FIRST empty-agents notification", async () => {
+    // Reproduces the published-core race: the core is created with no agents
+    // (agents are populated asynchronously), a consumer registers a thread
+    // store immediately, and the very first onAgentsChanged({ agents: {} })
+    // notification arrives. Without the "previously had" guard, that empty
+    // notification would rip out the freshly-registered store.
+    const core = new CopilotKitCore({});
+
+    const store = makeStore("agent-1-store");
+    core.registerThreadStore("agent-1", store);
+
+    const onUnregistered = vi.fn();
+    const subscriber: CopilotKitCoreSubscriber = {
+      onThreadStoreUnregistered: onUnregistered,
+    };
+    core.subscribe(subscriber);
+
+    // Trigger an onAgentsChanged({ agents: {} }) notification by calling
+    // setAgents__unsafe_dev_only({}) — this models the initial empty-agents
+    // notification a published core receives before its agents are merged in.
+    core.setAgents__unsafe_dev_only({});
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // The store must survive — agent-1 was never in the previous snapshot,
+    // so there is no transition from "had" to "missing" and nothing to
+    // unregister.
+    expect(core.getThreadStore("agent-1")).toBe(store);
+    expect(onUnregistered).not.toHaveBeenCalled();
+  });
+
+  it("unregisters on the SECOND notification when agent appears then disappears", async () => {
+    // Add agent-1, register a store, then remove agent-1. This time the
+    // previous snapshot DID contain agent-1, so the auto-unregister must
+    // fire. Complements the "first empty notification" test by exercising
+    // the same code path's positive branch.
+    const agent1 = new MockAgent({ agentId: "agent-1" });
+    const core = new CopilotKitCore({});
+
+    core.addAgent__unsafe_dev_only({ id: "agent-1", agent: agent1 as never });
+    const store = makeStore("agent-1-store");
+    core.registerThreadStore("agent-1", store);
+
+    const onUnregistered = vi.fn();
+    core.subscribe({
+      onThreadStoreUnregistered: onUnregistered,
+    });
+
+    core.removeAgent__unsafe_dev_only("agent-1");
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(core.getThreadStore("agent-1")).toBeUndefined();
+    expect(onUnregistered).toHaveBeenCalledTimes(1);
+  });
+});