fix(react-core): propagate threadId prop from CopilotKit to agent (CopilotKit#5041) (CopilotKit#5042)

## Summary

- Wires `useAgent` to sync `agent.threadId` from
`CopilotChatConfigurationProvider` when the caller marked the threadId
as explicit. AbstractAgent's constructor was auto-minting a UUID, so
`ProxiedCopilotRuntimeAgent` was shipping that random UUID in
`/agent/run`, `/agent/connect`, `/agent/stop` instead of the value the
caller passed via `<CopilotKit threadId={x}>` — breaking thread
persistence and causing 404s on lookup.
- Fixes CopilotKit#5041 (V1 `<CopilotChat>` path) and CopilotKit#4739 (headless `useAgent`
path), which share the same root cause.

## Why this regressed

PR CopilotKit#3525 originally solved this with per-thread agent cloning. That
cloning was reverted in commit `762370a4e5` (May 2026) because it wiped
state on tool calls. The revert restored the explicit `agent.threadId =
resolvedThreadId` assignment only in the V2 `CopilotChat` component —
the V1 chat hook (`use-copilot-chat_internal.ts`) and headless
`useAgent` paths were left without an equivalent sync.
`use-agent-thread-isolation.test.tsx` (333 lines) was deleted in the
revert and never replaced for those surfaces, which is why this
regressed silently.

The fix lives in `useAgent` rather than the V1 chat hook because V1 chat
already routes through `useAgent` for agent acquisition, and a headless
`useAgent` user (issue CopilotKit#4739) gets the sync for free. The gate on
`hasExplicitThreadId` matches V2 `CopilotChat`'s gating so a
`ThreadsProvider`-minted placeholder doesn't overwrite the agent's
auto-minted UUID before a real thread exists.

## Test plan

- [x] 4 new unit tests in `use-agent-threadid-sync.test.tsx` covering:
explicit sync, the non-explicit no-op path, threadId change re-sync, and
the no-provider headless case.
- [x] 2 new integration tests in `v1-explicit-threadid-bridge.test.tsx`
covering the customer's exact scenario: `<CopilotKit threadId={x}>` →
`useAgent` → `agent.threadId === x`.
- [x] All 1177 existing `@copilotkit/react-core` tests still pass.
- [x] `@copilotkit/react-core:build` succeeds.

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

Author: BenTaylorDev

packages/react-core/src/__tests__/threadid-propagation.contract.test.tsx

@@ -0,0 +1,173 @@
+import React from "react";
+import { render, act } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { AbstractAgent } from "@ag-ui/client";
+import { useCopilotKit } from "../v2/context";
+import { useAgent } from "../v2/hooks/use-agent";
+import { CopilotChatConfigurationProvider } from "../v2/providers/CopilotChatConfigurationProvider";
+import { CopilotKitCoreRuntimeConnectionStatus } from "@copilotkit/core";
+
+vi.mock("../v2/context", () => ({
+  useCopilotKit: vi.fn(),
+}));
+
+const mockUseCopilotKit = useCopilotKit as ReturnType<typeof vi.fn>;
+
+/**
+ * Contract-level regression coverage for the threadId-propagation invariant.
+ *
+ * Lives at the package root (src/__tests__) rather than next to any one
+ * implementation site on purpose: the previous regression (issue #5041, root
+ * cause shared with #4739) slipped through because the original coverage
+ * (use-agent-thread-isolation.test.tsx, 333 lines) lived next to the
+ * per-thread-cloning feature and was deleted alongside it in May 2026 when
+ * cloning was reverted. The threadId-propagation invariant survived the
+ * feature change but its tests didn't.
+ *
+ * The invariant under test: a caller-supplied threadId (via <CopilotKit>,
+ * <ThreadsProvider>, or <CopilotChatConfigurationProvider>) MUST end up on
+ * the underlying agent's `threadId` field, because ProxiedCopilotRuntimeAgent
+ * uses that field to address /agent/run, /agent/connect, /agent/stop. Without
+ * it the agent ships its own auto-minted UUID and the backend sees a different
+ * thread than the app code reads via useThreads/useCopilotChatConfiguration.
+ *
+ * This file should outlive any specific implementation strategy (cloning,
+ * effect-based sync, prop drilling, context bridge). If you change the
+ * mechanism, keep this contract.
+ */
+describe("useAgent → agent.threadId sync from chat configuration", () => {
+  let mockCopilotkit: {
+    getAgent: ReturnType<typeof vi.fn>;
+    runtimeUrl: string | undefined;
+    runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
+    runtimeTransport: string;
+    headers: Record<string, string>;
+    agents: Record<string, AbstractAgent>;
+    subscribeToAgentWithOptions: (
+      agent: AbstractAgent,
+      subscriber: any,
+    ) => { unsubscribe: () => void };
+  };
+
+  beforeEach(() => {
+    mockCopilotkit = {
+      getAgent: vi.fn(() => undefined),
+      runtimeUrl: "http://localhost:3000/api/copilotkit",
+      runtimeConnectionStatus:
+        CopilotKitCoreRuntimeConnectionStatus.Disconnected,
+      runtimeTransport: "rest",
+      headers: {},
+      agents: {},
+      subscribeToAgentWithOptions: (agent, subscriber) =>
+        agent.subscribe(subscriber),
+    };
+
+    mockUseCopilotKit.mockReturnValue({
+      copilotkit: mockCopilotkit,
+      executingToolCallIds: new Set(),
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("sets agent.threadId from CopilotChatConfigurationProvider when explicit", () => {
+    // The agent's threadId is mutable state outside React's render tracking,
+    // so we assert against the captured reference rather than rendered DOM —
+    // mutating agent.threadId after commit doesn't trigger a re-render, but
+    // downstream consumers (HTTP run/connect/stop, syncDelegate) read it
+    // imperatively at call time, which is the actual contract the fix repairs.
+    const callerThreadId = "caller-supplied-thread-id";
+    let capturedAgent: AbstractAgent | null = null;
+
+    function Probe() {
+      const { agent } = useAgent({ agentId: "test-agent" });
+      capturedAgent = agent;
+      return null;
+    }
+
+    render(
+      <CopilotChatConfigurationProvider threadId={callerThreadId}>
+        <Probe />
+      </CopilotChatConfigurationProvider>,
+    );
+
+    expect(capturedAgent).not.toBeNull();
+    expect(capturedAgent!.threadId).toBe(callerThreadId);
+  });
+
+  it("does NOT overwrite the auto-minted threadId when hasExplicitThreadId is false", () => {
+    // Mirrors the v1 CopilotKit bridge: ThreadsProvider auto-mints a UUID, the
+    // bridge forwards it but marks it non-explicit so downstream consumers
+    // don't treat the placeholder as a real backend thread.
+    const placeholderThreadId = "placeholder-from-threads-provider";
+    let capturedAgent: AbstractAgent | null = null;
+
+    function Probe() {
+      const { agent } = useAgent({ agentId: "test-agent" });
+      capturedAgent = agent;
+      return null;
+    }
+
+    render(
+      <CopilotChatConfigurationProvider
+        threadId={placeholderThreadId}
+        hasExplicitThreadId={false}
+      >
+        <Probe />
+      </CopilotChatConfigurationProvider>,
+    );
+
+    expect(capturedAgent).not.toBeNull();
+    expect(capturedAgent!.threadId).not.toBe(placeholderThreadId);
+    // AbstractAgent's constructor auto-mints a UUID; just confirm it's a
+    // non-empty string distinct from the placeholder.
+    expect(capturedAgent!.threadId).toBeTruthy();
+  });
+
+  it("re-syncs agent.threadId when the configuration's threadId changes", () => {
+    let capturedAgent: AbstractAgent | null = null;
+
+    function Probe() {
+      const { agent } = useAgent({ agentId: "test-agent" });
+      capturedAgent = agent;
+      return null;
+    }
+
+    const { rerender } = render(
+      <CopilotChatConfigurationProvider threadId="first-thread">
+        <Probe />
+      </CopilotChatConfigurationProvider>,
+    );
+
+    expect(capturedAgent!.threadId).toBe("first-thread");
+
+    act(() => {
+      rerender(
+        <CopilotChatConfigurationProvider threadId="second-thread">
+          <Probe />
+        </CopilotChatConfigurationProvider>,
+      );
+    });
+
+    // Same agent instance (provisional cache keeps reference stable), updated threadId
+    expect(capturedAgent!.threadId).toBe("second-thread");
+  });
+
+  it("is a no-op when no CopilotChatConfigurationProvider is in scope", () => {
+    // Headless / pure-v2 use without any configuration provider — useAgent
+    // should leave the agent's auto-minted threadId alone instead of throwing.
+    let capturedAgent: AbstractAgent | null = null;
+
+    function Probe() {
+      const { agent } = useAgent({ agentId: "test-agent" });
+      capturedAgent = agent;
+      return null;
+    }
+
+    expect(() => render(<Probe />)).not.toThrow();
+    expect(capturedAgent).not.toBeNull();
+    expect(capturedAgent!.threadId).toBeTruthy();
+  });
+});

packages/react-core/src/components/copilot-provider/__tests__/v1-explicit-threadid-bridge.test.tsx

@@ -3,8 +3,9 @@ import { render, screen, act } from "@testing-library/react";
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { CopilotKit } from "../copilotkit";
 import { useCopilotContext } from "../../../context/copilot-context";
-import { useCopilotChatConfiguration } from "../../../v2";
+import { useCopilotChatConfiguration, useAgent } from "../../../v2";
 import type { CopilotKitProps } from "../copilotkit-props";
+import type { AbstractAgent } from "@ag-ui/client";
 
 /**
  * Probe that reads hasExplicitThreadId from the CopilotChatConfigurationProvider
@@ -105,3 +106,66 @@ describe("v1 <CopilotKit> bridge → hasExplicitThreadId", () => {
     expect(screen.getByTestId("explicit").textContent).toBe("true");
   });
 });
+
+/**
+ * Regression coverage for issue #5041 (and #4739) at the customer-facing
+ * surface: a threadId prop on <CopilotKit> must end up on the underlying
+ * agent so that ProxiedCopilotRuntimeAgent ships it in /agent/run,
+ * /agent/connect, /agent/stop. The cloning-revert in May 2026 broke this
+ * for headless useAgent and V1 chat; CopilotChatConfigurationProvider got
+ * the value but useAgent never copied it down onto agent.threadId.
+ */
+describe("v1 <CopilotKit> → useAgent → agent.threadId", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  function AgentProbe({
+    onCapture,
+  }: {
+    onCapture: (agent: AbstractAgent) => void;
+  }) {
+    const { agent } = useAgent({ agentId: "default" });
+    React.useEffect(() => {
+      onCapture(agent);
+    });
+    return null;
+  }
+
+  it("sets agent.threadId to the explicit threadId from the <CopilotKit> prop", () => {
+    let captured: AbstractAgent | null = null;
+    render(
+      <CopilotKitAny publicApiKey="test-key" threadId="customer-thread-id">
+        <AgentProbe onCapture={(agent) => (captured = agent)} />
+      </CopilotKitAny>,
+    );
+
+    expect(captured).not.toBeNull();
+    expect((captured as unknown as AbstractAgent).threadId).toBe(
+      "customer-thread-id",
+    );
+  });
+
+  it("leaves the agent's auto-minted threadId untouched when no threadId prop is supplied", () => {
+    // Without an explicit threadId, the ThreadsProvider mints a placeholder
+    // UUID that's marked non-explicit. The agent should keep its own
+    // constructor-generated UUID rather than adopt the placeholder, so the
+    // backend isn't asked to look up a thread it never created.
+    let captured: AbstractAgent | null = null;
+    render(
+      <CopilotKitAny publicApiKey="test-key">
+        <AgentProbe onCapture={(agent) => (captured = agent)} />
+      </CopilotKitAny>,
+    );
+
+    expect(captured).not.toBeNull();
+    expect((captured as unknown as AbstractAgent).threadId).toBeTruthy();
+    expect((captured as unknown as AbstractAgent).threadId).not.toBe(
+      "mock-thread-id",
+    );
+  });
+});

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

@@ -1,12 +1,14 @@
 import { useCopilotKit } from "../context";
 import { useMemo, useEffect, useReducer, useRef } from "react";
 import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
-import { AbstractAgent, HttpAgent } from "@ag-ui/client";
+import type { AbstractAgent } from "@ag-ui/client";
+import { HttpAgent } from "@ag-ui/client";
 import {
   ProxiedCopilotRuntimeAgent,
   CopilotKitCoreRuntimeConnectionStatus,
-  type SubscribeToAgentSubscriber,
 } from "@copilotkit/core";
+import type { SubscribeToAgentSubscriber } from "@copilotkit/core";
+import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
 
 export enum UseAgentUpdate {
   OnMessagesChanged = "OnMessagesChanged",
@@ -221,6 +223,22 @@ export function useAgent({ agentId, updates, throttleMs }: UseAgentProps = {}) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [agent, JSON.stringify(copilotkit.headers)]);
 
+  // Propagate the caller-supplied threadId from the chat configuration onto
+  // the agent. AbstractAgent's constructor auto-mints a UUID when no threadId
+  // is passed, so without this sync the agent ships its own random UUID in
+  // /agent/run, /agent/connect, /agent/stop — diverging from the threadId the
+  // app code reads via useThreads/useCopilotChatConfiguration. Gated on
+  // hasExplicitThreadId so a ThreadsProvider-minted placeholder UUID doesn't
+  // overwrite the auto-minted agent UUID (both are random and useless to the
+  // backend; the explicit gate keeps the agent's UUID stable across renders).
+  const chatConfig = useCopilotChatConfiguration();
+  const configThreadId = chatConfig?.threadId;
+  const configHasExplicitThreadId = chatConfig?.hasExplicitThreadId;
+  useEffect(() => {
+    if (!configHasExplicitThreadId || !configThreadId) return;
+    agent.threadId = configThreadId;
+  }, [agent, configThreadId, configHasExplicitThreadId]);
+
   return {
     agent,
   };