@copilotkit/react-core 1.57.0 → 1.57.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/react-core",
-  "version": "1.57.0",
+  "version": "1.57.1",
   "private": false,
   "keywords": [
     "ai",
@@ -46,6 +46,14 @@
       "require": "./dist/v2/index.cjs"
     },
     "./package.json": "./package.json",
+    "./v2/context": {
+      "import": "./dist/v2/context.mjs",
+      "require": "./dist/v2/context.cjs"
+    },
+    "./v2/headless": {
+      "import": "./dist/v2/headless.mjs",
+      "require": "./dist/v2/headless.cjs"
+    },
     "./v2/styles.css": "./dist/v2/index.css"
   },
   "publishConfig": {
@@ -73,11 +81,11 @@
     "untruncate-json": "^0.0.1",
     "use-stick-to-bottom": "^1.1.1",
     "zod-to-json-schema": "^3.24.5",
-    "@copilotkit/core": "1.57.0",
-    "@copilotkit/shared": "1.57.0",
-    "@copilotkit/a2ui-renderer": "1.57.0",
-    "@copilotkit/runtime-client-gql": "1.57.0",
-    "@copilotkit/web-inspector": "1.57.0"
+    "@copilotkit/a2ui-renderer": "1.57.1",
+    "@copilotkit/core": "1.57.1",
+    "@copilotkit/web-inspector": "1.57.1",
+    "@copilotkit/runtime-client-gql": "1.57.1",
+    "@copilotkit/shared": "1.57.1"
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.1.11",

package/src/hooks/__tests__/use-copilot-chat-internal-connect.test.tsx

@@ -179,10 +179,9 @@ describe("useCopilotChatInternal – connectAgent guard", () => {
   });
 
   it("does not call connectAgent when threadId matches (same agent instance, no re-render)", async () => {
-    // useAgent now returns a per-thread clone, so the wrapper guards via
-    // lastConnectedAgentRef: connect fires once per agent instance, not once
-    // per render. After the first connect, further re-renders with the same
-    // agent do not trigger another connect.
+    // The wrapper guards via lastConnectedAgentRef: connect fires once per
+    // agent instance, not once per render. After the first connect, further
+    // re-renders with the same agent do not trigger another connect.
     mockRuntimeConnectionStatus =
       CopilotKitCoreRuntimeConnectionStatus.Connected;
     mockAgent.threadId = "config-thread-id";
@@ -230,13 +229,13 @@ describe("useCopilotChatInternal – connectAgent guard", () => {
     });
   });
 
-  it("passes config threadId to useAgent", () => {
+  it("passes resolved agentId to useAgent", () => {
     applyMocks();
 
     renderHook(() => useCopilotChatInternal(), { wrapper: createWrapper() });
 
     expect(vi.mocked(useAgent)).toHaveBeenCalledWith(
-      expect.objectContaining({ threadId: "config-thread-id" }),
+      expect.objectContaining({ agentId: "test-agent" }),
     );
   });
 });

package/src/hooks/use-copilot-chat_internal.ts

@@ -339,7 +339,6 @@ export function useCopilotChatInternal({
   const resolvedAgentId = existingConfig?.agentId ?? "default";
   const { agent } = useAgent({
     agentId: resolvedAgentId,
-    threadId: existingConfig?.threadId,
   });
 
   // Track the last agent instance we called connect() on. Without this,

package/src/v2/components/chat/CopilotChat.tsx

@@ -118,7 +118,6 @@ export function CopilotChat({
 
   const { agent } = useAgent({
     agentId: resolvedAgentId,
-    threadId: resolvedThreadId,
     throttleMs,
   });
   const { copilotkit } = useCopilotKit();
@@ -235,6 +234,8 @@ export function CopilotChat({
       agent.abortController = connectAbortController;
     }
 
+    agent.threadId = resolvedThreadId;
+
     const connect = async (agent: AbstractAgent) => {
       try {
         await copilotkit.connectAgent({ agent });

package/src/v2/components/chat/CopilotChatMessageView.tsx

@@ -8,11 +8,12 @@ import React, {
 } from "react";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { ScrollElementContext } from "./scroll-element-context";
-import { WithSlots, renderSlot, isReactComponentType } from "../../lib/slots";
+import type { WithSlots } from "../../lib/slots";
+import { renderSlot, isReactComponentType } from "../../lib/slots";
 import CopilotChatAssistantMessage from "./CopilotChatAssistantMessage";
 import CopilotChatUserMessage from "./CopilotChatUserMessage";
 import CopilotChatReasoningMessage from "./CopilotChatReasoningMessage";
-import {
+import type {
   ActivityMessage,
   AssistantMessage,
   Message,
@@ -22,9 +23,10 @@ import {
 } from "@ag-ui/core";
 import { twMerge } from "tailwind-merge";
 import { useRenderActivityMessage, useRenderCustomMessages } from "../../hooks";
-import { getThreadClone } from "../../hooks/use-agent";
 import { useCopilotKit } from "../../providers/CopilotKitProvider";
 import { useCopilotChatConfiguration } from "../../providers/CopilotChatConfigurationProvider";
+import { IntelligenceIndicator } from "../intelligence-indicator";
+import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
 
 /**
  * Resolves a slot value into a { Component, slotProps } pair, handling the three
@@ -392,18 +394,14 @@ export function CopilotChatMessageView({
   // Subscribe to state changes so custom message renderers re-render when state updates.
   useEffect(() => {
     if (!config?.agentId) return;
-    const registryAgent = copilotkit.getAgent(config.agentId);
-    // Prefer the per-thread clone so that state changes from the running agent
-    // (which is the clone, not the registry) trigger re-renders.
-    const agent =
-      getThreadClone(registryAgent, config.threadId) ?? registryAgent;
+    const agent = copilotkit.getAgent(config.agentId);
     if (!agent) return;
 
     const subscription = agent.subscribe({
       onStateChanged: forceUpdate,
     });
     return () => subscription.unsubscribe();
-  }, [config?.agentId, config?.threadId, copilotkit, forceUpdate]);
+  }, [config?.agentId, copilotkit, forceUpdate]);
 
   // Subscribe to interrupt element changes for in-chat rendering.
   const [interruptElement, setInterruptElement] =
@@ -608,6 +606,23 @@ export function CopilotChatMessageView({
       );
     }
 
+    // Auto-mount the IntelligenceIndicator on assistant message slots
+    // when the runtime is in intelligence mode. The component self-gates
+    // further (latest matching-assistant slot, pending tool-call grace
+    // window) so only one pill renders at a time — mounting only for
+    // assistant messages avoids the per-slot `useAgent` subscription
+    // and four effects on user/reasoning/activity slots that would just
+    // return null at the role gate anyway.
+    if (copilotkit.intelligence !== undefined && message.role === "assistant") {
+      elements.push(
+        <IntelligenceIndicator
+          key={`${message.id}-intelligence`}
+          message={message}
+          agentId={config?.agentId ?? DEFAULT_AGENT_ID}
+        />,
+      );
+    }
+
     return elements.filter(Boolean) as React.ReactElement[];
   };
 

package/src/v2/components/chat/CopilotChatView.tsx

@@ -89,8 +89,8 @@ export type CopilotChatViewProps = WithSlots<
     /**
      * When `true`, suppresses the welcome screen while a thread's initial
      * connect is in flight. Prevents the "How can I help you today?" flash
-     * that would otherwise appear between mounting an empty cloned agent and
-     * the bootstrap messages arriving from /connect.
+     * that would otherwise appear between mounting an empty agent instance
+     * and the bootstrap messages arriving from /connect.
      */
     isConnecting?: boolean;
     /**

package/src/v2/components/chat/__tests__/CopilotChat.welcomeGate.test.tsx

@@ -9,8 +9,7 @@ import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
 
 /**
  * Mock agent that records every connectAgent() invocation and resolves
- * immediately with an empty run result. Tracking lives on the class so
- * per-thread clones (from useAgent's WeakMap) share the counter.
+ * immediately with an empty run result.
  */
 class TrackingAgent extends MockStepwiseAgent {
   static connectCalls: Array<{
@@ -107,7 +106,6 @@ describe("CopilotChat welcome / connect integration", () => {
         expect(TrackingAgent.connectCalls.length).toBeGreaterThan(0);
       });
 
-      // The per-thread clone carries threadId; agentId is the default.
       expect(
         TrackingAgent.connectCalls.some((c) => c.threadId === "real-thread"),
       ).toBe(true);

package/src/v2/components/chat/__tests__/CopilotChatActivityRendering.e2e.test.tsx

@@ -1,6 +1,7 @@
 import React from "react";
 import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { z } from "zod";
+import type { AbstractAgent } from "@ag-ui/client";
 import { EventType } from "@ag-ui/client";
 import {
   MockReconnectableAgent,
@@ -17,9 +18,7 @@ import {
   CopilotKitProvider,
   useCopilotKit,
 } from "../../../providers";
-import type { AbstractAgent } from "@ag-ui/client";
 import { IntelligenceAgent } from "@copilotkit/core";
-import { getThreadClone } from "../../../hooks/use-agent";
 import { createA2UIMessageRenderer } from "../../../a2ui/A2UIMessageRenderer";
 import type { Theme } from "@copilotkit/a2ui-renderer";
 import { CopilotChat } from "..";
@@ -306,18 +305,28 @@ describe("CopilotChat activity message rendering", () => {
     expect(capturedCopilotkit).toBeDefined();
   });
 
-  it("passes the per-thread clone (not the registry agent) to activity message renderers", async () => {
-    // Regression test for: A2UI button clicks firing runAgent on the registry
-    // agent instead of the per-thread clone that CopilotChat renders from.
-    // Caused by useRenderActivityMessage calling copilotkit.getAgent() directly
-    // instead of getThreadClone(registryAgent, threadId) ?? registryAgent.
-    const agent = new MockStepwiseAgent();
-    const agentId = "action-agent";
-    agent.agentId = agentId;
-    const threadId = "thread-for-action-test";
+  it("activity renderers receive the agent under the config agentId, not any other registered agent", async () => {
+    // Regression: the renderer's `agent` prop must come from
+    // `copilotkit.getAgent(config.agentId)` — the local registry id from
+    // CopilotChatConfigurationProvider — not from any other agent in the
+    // registry (e.g. a sibling chat's agent).
+    //
+    // The trap this catches is a refactor where the renderer pipeline keys
+    // on something other than `config.agentId` (e.g. for proxied
+    // registrations, accidentally keying on `proxy.runtimeAgentId`). The
+    // assertion shape — "two agents in the registry, the renderer must
+    // receive the one matching config.agentId" — is generic to that bug
+    // class. The proxy-routing-specific behavior (registering a
+    // ProxiedCopilotRuntimeAgent with `runtimeAgentId !== agentId` and
+    // verifying `getAgent(agentId)` returns the proxy, not the agent at
+    // runtimeAgentId) is covered by `core-register-proxied-agent.test.ts`
+    // at the registry level.
+    const localAgent = new MockStepwiseAgent();
+    localAgent.agentId = "chat-1";
+    const otherAgent = new MockStepwiseAgent();
+    otherAgent.agentId = "default";
 
     let capturedAgent: AbstractAgent | undefined;
-
     const activityRenderer: ReactActivityMessageRenderer<{ label: string }> = {
       activityType: "button-action",
       content: z.object({ label: z.string() }),
@@ -328,9 +337,9 @@ describe("CopilotChat activity message rendering", () => {
     };
 
     renderWithCopilotKit({
-      agents: { [agentId]: agent },
-      agentId,
-      threadId,
+      agents: { "chat-1": localAgent, default: otherAgent },
+      agentId: "chat-1",
+      threadId: "thread-for-action-test",
       renderActivityMessages: [activityRenderer],
     });
 
@@ -342,27 +351,22 @@ describe("CopilotChat activity message rendering", () => {
       expect(screen.getByText("show me buttons")).toBeDefined();
     });
 
-    agent.emit(runStartedEvent());
-    agent.emit(
+    localAgent.emit(runStartedEvent());
+    localAgent.emit(
       activitySnapshotEvent({
         messageId: testId("activity-action"),
         activityType: "button-action",
         content: { label: "Click Me" },
       }),
     );
-    agent.emit(runFinishedEvent());
+    localAgent.emit(runFinishedEvent());
 
     await waitFor(() => {
       expect(screen.getByTestId("action-button")).toBeDefined();
     });
 
-    // CopilotChat creates a per-thread clone via useAgent. The activity renderer
-    // must receive that clone so that handleAction → runAgent targets the same
-    // instance chat is rendering from.
-    const clone = getThreadClone(agent, threadId);
-    expect(clone).toBeDefined();
-    expect(capturedAgent).toBe(clone);
-    expect(capturedAgent).not.toBe(agent); // must NOT be the registry agent
+    expect(capturedAgent).toBe(localAgent);
+    expect(capturedAgent).not.toBe(otherAgent);
   });
 
   it("restores a completed A2UI surface after reconnect from an event-native baseline", async () => {

package/src/v2/components/chat/__tests__/MCPAppsUiMessage.e2e.test.tsx

@@ -49,6 +49,11 @@ class MockMCPProxyAgent extends AbstractAgent {
     this.runAgentResponses.set(method, response);
   }
 
+  addMessage(msg: Parameters<AbstractAgent["addMessage"]>[0]) {
+    this.addMessageCalls.push(msg as any);
+    return super.addMessage(msg);
+  }
+
   emit(event: BaseEvent) {
     if (event.type === EventType.RUN_STARTED) {
       this.isRunning = true;
@@ -70,66 +75,6 @@ class MockMCPProxyAgent extends AbstractAgent {
     });
   }
 
-  clone(): MockMCPProxyAgent {
-    const cloned = new MockMCPProxyAgent();
-    cloned.agentId = this.agentId;
-    type Internal = {
-      subject: Subject<BaseEvent>;
-      runAgentCalls: Array<{ input: Partial<RunAgentInput> }>;
-      addMessageCalls: Array<{ id: string; role: string; content: string }>;
-      runAgentResponses: Map<string, unknown>;
-    };
-    (cloned as unknown as Internal).subject = (
-      this as unknown as Internal
-    ).subject;
-    (cloned as unknown as Internal).runAgentCalls = (
-      this as unknown as Internal
-    ).runAgentCalls;
-    (cloned as unknown as Internal).addMessageCalls = (
-      this as unknown as Internal
-    ).addMessageCalls;
-    (cloned as unknown as Internal).runAgentResponses = (
-      this as unknown as Internal
-    ).runAgentResponses;
-
-    const registry = this;
-    Object.defineProperty(cloned, "isRunning", {
-      get() {
-        return registry.isRunning;
-      },
-      set(v: boolean) {
-        registry.isRunning = v;
-      },
-      configurable: true,
-      enumerable: true,
-    });
-
-    const proto = MockMCPProxyAgent.prototype;
-    cloned.runAgent = async function (
-      input?: Partial<RunAgentInput>,
-    ): Promise<RunAgentResult> {
-      const proxiedRequest = input?.forwardedProps?.__proxiedMCPRequest;
-      if (proxiedRequest) {
-        return registry.runAgent(input);
-      }
-      return proto.runAgent.call(cloned, input);
-    };
-
-    // Track addMessage calls on the clone (the component uses the clone)
-    const origAddMessage = cloned.addMessage.bind(cloned);
-    cloned.addMessage = function (msg: Parameters<typeof origAddMessage>[0]) {
-      registry.addMessageCalls.push(msg as any);
-      return origAddMessage(msg);
-    };
-
-    // Proxy run() calls so spies on the registry's run() see clone invocations
-    cloned.run = function (input: RunAgentInput): Observable<BaseEvent> {
-      return registry.run(input);
-    };
-
-    return cloned;
-  }
-
   async detachActiveRun(): Promise<void> {}
 
   run(_input: RunAgentInput): Observable<BaseEvent> {

package/src/v2/components/index.ts

@@ -5,3 +5,4 @@ export * from "./chat";
 export * from "./WildcardToolCallRender";
 export * from "./CopilotKitInspector";
 export * from "./MCPAppsActivityRenderer";
+export * from "./intelligence-indicator";

package/src/v2/components/intelligence-indicator/IntelligenceIndicator.tsx

@@ -0,0 +1,286 @@
+import React, { useEffect, useMemo, useState } from "react";
+import type { Message } from "@ag-ui/core";
+import { useCopilotKit } from "../../providers/CopilotKitProvider";
+import { useCopilotChatConfiguration } from "../../providers/CopilotChatConfigurationProvider";
+import { useAgent, UseAgentUpdate } from "../../hooks/use-agent";
+
+/**
+ * Grace window before showing the spinner. A matching tool call must
+ * remain unresolved (no `tool`-role result message in `agent.messages`)
+ * for at least this long before the pill appears. This filters out
+ * history-replay flashes — during `connectAgent` replay, tool calls and
+ * their results arrive back-to-back in sub-millisecond bursts, so the
+ * timer is cancelled before it fires. Live runs cross the threshold
+ * easily because the tool actually has to execute.
+ */
+const PENDING_THRESHOLD_MS = 100;
+
+/** Hold the checkmark briefly before fading out. */
+const CHECK_HOLD_MS = 800;
+
+/**
+ * Duration of the fade-out animation. Must match
+ * `cpk-intelligence-pill-fade-out` keyframes in `v2/styles/globals.css`.
+ */
+const FADE_OUT_ANIMATION_MS = 480;
+
+/**
+ * Tool-name regex patterns that trigger the indicator. Currently
+ * hardcoded to the Intelligence MCP server's canonical tool name. If
+ * we add per-instance customization later (e.g. a `CopilotKitProvider`
+ * prop or a runtime-info field), this constant becomes the fallback.
+ */
+const DEFAULT_TOOL_PATTERNS: readonly RegExp[] = [
+  /^copilotkit_knowledge_base_shell$/,
+];
+
+type Phase = "idle" | "spinner" | "check" | "fading" | "hidden";
+
+export interface IntelligenceIndicatorProps {
+  /** The message this indicator is attached to. */
+  message: Message;
+  /**
+   * Agent id whose run state the indicator tracks. Pass through from
+   * the surrounding chat configuration; mounting from
+   * `CopilotChatMessageView` resolves this automatically.
+   */
+  agentId: string;
+  /**
+   * Optional override for the visible label. Defaults to "Using
+   * CopilotKit Intelligence".
+   */
+  label?: string;
+}
+
+const isMatchingToolCallName = (name: unknown): boolean =>
+  typeof name === "string" && DEFAULT_TOOL_PATTERNS.some((p) => p.test(name));
+
+/**
+ * "Tool-call-like" messages do NOT count as a real follow-up: tool
+ * result messages, assistant messages that carry tool calls, and
+ * empty-content assistant messages (which some providers emit as a
+ * standalone wrapper around a batch of tool calls). A real follow-up
+ * is anything else — most importantly an assistant message with prose
+ * content, or a fresh user message.
+ */
+const isToolCallLikeMessage = (m: Message): boolean => {
+  if (m.role === "tool") return true;
+  if (m.role === "assistant") {
+    const tcs = Array.isArray(m.toolCalls) ? m.toolCalls : [];
+    if (tcs.length > 0) return true;
+    const content = m.content;
+    return typeof content !== "string" || content.trim().length === 0;
+  }
+  return false;
+};
+
+/**
+ * The "Using CopilotKit Intelligence" pill. Auto-mounted by
+ * `CopilotChatMessageView` for every message slot when
+ * `copilotkit.intelligence` is configured — callers do not register
+ * this themselves. Self-gates so only the canonical message renders a
+ * pill.
+ *
+ * Render gates (all must hold):
+ *   1. `copilotkit.intelligence !== undefined`
+ *   2. The message is an assistant message with at least one tool call
+ *      whose name matches {@link DEFAULT_TOOL_PATTERNS}
+ *   3. The message is the *latest* such matching-assistant message in
+ *      `agent.messages` — tool-result messages and prose-only assistant
+ *      messages don't invalidate the slot, so the pill stays
+ *      continuously through a multi-step tool chain.
+ *   4. The phase machine is past `idle` (the pending-grace timer fired)
+ *      and not yet `hidden`.
+ *
+ * Phase machine (per-instance, all timers local):
+ *   - Starts in `idle` — nothing rendered.
+ *   - `idle → spinner` once a matching tool call has been pending
+ *     (no `tool`-role result with a matching `toolCallId`) for
+ *     {@link PENDING_THRESHOLD_MS}. Replay flashes (tool call + result
+ *     in the same tick) never cross this threshold.
+ *   - `spinner → check` as soon as EITHER `agent.isRunning` flips
+ *     false OR a non-tool-call-like message appears later in
+ *     `agent.messages` (i.e. the agent has produced a "real"
+ *     follow-up — prose answer or a new user turn).
+ *   - `check → fading` after {@link CHECK_HOLD_MS}.
+ *   - `fading → hidden` after {@link FADE_OUT_ANIMATION_MS}.
+ *
+ * Once `hidden`, the phase is sticky — a finished pill never re-spawns
+ * on the same message. New runs mount fresh indicator instances on
+ * their own assistant messages.
+ *
+ * The "exactly one pill at a time" guarantee is structural: only one
+ * message satisfies the latest-matching-assistant gate at any moment.
+ */
+export function IntelligenceIndicator(
+  props: IntelligenceIndicatorProps,
+): React.ReactElement | null {
+  const { message, agentId, label = "Using CopilotKit Intelligence" } = props;
+
+  const { copilotkit } = useCopilotKit();
+  const config = useCopilotChatConfiguration();
+  const { agent } = useAgent({
+    agentId,
+    updates: [
+      UseAgentUpdate.OnRunStatusChanged,
+      UseAgentUpdate.OnMessagesChanged,
+    ],
+  });
+
+  // IDs of matching tool calls on this message.
+  const matchingToolCallIds = useMemo<readonly string[]>(() => {
+    if (message.role !== "assistant") return [];
+    const tcs = Array.isArray(message.toolCalls) ? message.toolCalls : [];
+    const ids: string[] = [];
+    for (const tc of tcs) {
+      if (isMatchingToolCallName(tc?.function?.name) && tc?.id) {
+        ids.push(tc.id);
+      }
+    }
+    return ids;
+  }, [message]);
+
+  // Pending = at least one matching tool call has no corresponding
+  // `tool`-role result message in `agent.messages`.
+  const hasPending = useMemo(() => {
+    if (matchingToolCallIds.length === 0) return false;
+    const resolved = new Set<string>();
+    for (const m of agent.messages) {
+      if (m.role === "tool" && m.toolCallId) resolved.add(m.toolCallId);
+    }
+    return matchingToolCallIds.some((id) => !resolved.has(id));
+  }, [matchingToolCallIds, agent.messages]);
+
+  // True once the agent has produced a "real" message *after* this
+  // assistant message — prose, a new user turn, etc. Tool-call-like
+  // messages do not count (they're part of the same tool flow).
+  const sawRealFollowup = useMemo(() => {
+    const idx = agent.messages.findIndex((m) => m.id === message.id);
+    if (idx < 0) return false;
+    for (let i = idx + 1; i < agent.messages.length; i += 1) {
+      if (!isToolCallLikeMessage(agent.messages[i]!)) return true;
+    }
+    return false;
+  }, [agent.messages, message.id]);
+
+  const [phase, setPhase] = useState<Phase>("idle");
+
+  // idle → spinner: pending tool call hasn't been resolved within the
+  // grace window. Cleared if the result arrives first (replay) or if
+  // there's nothing to wait on.
+  useEffect(() => {
+    if (phase !== "idle") return undefined;
+    if (!hasPending) return undefined;
+    const t = setTimeout(() => setPhase("spinner"), PENDING_THRESHOLD_MS);
+    return () => clearTimeout(t);
+  }, [phase, hasPending]);
+
+  // spinner → check: agent stopped running OR a real follow-up
+  // message arrived. Both are independent signals; whichever fires
+  // first wins.
+  useEffect(() => {
+    if (phase !== "spinner") return undefined;
+    if (!agent.isRunning || sawRealFollowup) {
+      setPhase("check");
+    }
+    return undefined;
+  }, [phase, agent.isRunning, sawRealFollowup]);
+
+  // check → fading after the hold.
+  useEffect(() => {
+    if (phase !== "check") return undefined;
+    const t = setTimeout(() => setPhase("fading"), CHECK_HOLD_MS);
+    return () => clearTimeout(t);
+  }, [phase]);
+
+  // fading → hidden after the fade animation.
+  useEffect(() => {
+    if (phase !== "fading") return undefined;
+    const t = setTimeout(() => setPhase("hidden"), FADE_OUT_ANIMATION_MS);
+    return () => clearTimeout(t);
+  }, [phase]);
+
+  // ─── Render gates ────────────────────────────────────────────────────
+  // Hooks above MUST run unconditionally; bail with `null` only after.
+
+  if (copilotkit.intelligence === undefined) return null;
+  if (!config) return null;
+  if (phase === "idle" || phase === "hidden") return null;
+
+  if (message.role !== "assistant") return null;
+  // Defensive: a malformed `toolCalls` (non-array, missing nested
+  // `function.name`) would otherwise throw inside `.some(...)` and take
+  // down the chat tree. Treat as "no match" instead.
+  const toolCalls = Array.isArray(message.toolCalls) ? message.toolCalls : [];
+  const hasMatch = toolCalls.some((tc) =>
+    isMatchingToolCallName(tc?.function?.name),
+  );
+  if (!hasMatch) return null;
+
+  // Walk `agent.messages` from the end and find the latest assistant
+  // message that itself has a matching tool call. If that's not us,
+  // we're not the canonical slot — return `null`.
+  let latestMatchingAssistantId: string | undefined;
+  for (let i = agent.messages.length - 1; i >= 0; i -= 1) {
+    const m = agent.messages[i]!;
+    if (m.role !== "assistant") continue;
+    const tcs = Array.isArray(m.toolCalls) ? m.toolCalls : [];
+    if (tcs.some((tc) => isMatchingToolCallName(tc?.function?.name))) {
+      latestMatchingAssistantId = m.id;
+      break;
+    }
+  }
+  if (latestMatchingAssistantId !== message.id) return null;
+
+  // ─── Visual ──────────────────────────────────────────────────────────
+
+  const showSpinner = phase === "spinner";
+  const isFading = phase === "fading";
+
+  return (
+    <span
+      className={
+        "cpk-intelligence-pill" +
+        (isFading ? " cpk-intelligence-pill--fading" : "")
+      }
+      role="status"
+      aria-live="polite"
+      aria-hidden={isFading || undefined}
+      data-testid={`cpk-intelligence-pill-${message.id}`}
+      title={label}
+    >
+      <svg
+        className="cpk-intelligence-pill__icon"
+        viewBox="0 0 24 24"
+        width="14"
+        height="14"
+        aria-hidden="true"
+      >
+        <circle
+          cx="12"
+          cy="12"
+          r="9"
+          fill="none"
+          strokeWidth="2.5"
+          strokeLinecap="round"
+          className={
+            "cpk-intelligence-pill__ring" +
+            (showSpinner ? "" : " cpk-intelligence-pill__ring--done")
+          }
+        />
+        <path
+          d="M8 12.5l3 3 5-6"
+          fill="none"
+          strokeWidth="2.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          className={
+            "cpk-intelligence-pill__check" +
+            (showSpinner ? "" : " cpk-intelligence-pill__check--shown")
+          }
+        />
+      </svg>
+      <span>{label}</span>
+    </span>
+  );
+}