[pull] main from CopilotKit:main

.claude/skills/showcase-demo-debugging/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: showcase-demo-debugging
 description: Build, debug, and regression-test CopilotKit showcase demos. Use when working under showcase/, creating new showcase demos/items/cells/pills, implementing showcase features, investigating showcase demo bugs, D5/e2e-deep failures, aimock fixture gaps, direct-LLM versus aimock behavior, recording fixtures, testing every demo pill/cell, verifying repeated and interleaved suggestion-pill fixture stability, enforcing langgraph-python 1:1 parity, or migrating a demo to the v2 CopilotKit showcase flow.
+metadata:
+  internal: true
 ---
 
 # Showcase Demo Work

.github/workflows/prerelease.yml

@@ -74,11 +74,24 @@ jobs:
       - name: Run tests
         run: pnpm run test
 
+      # Exclude node_modules and build caches from the artifact. Including
+      # them produces ~6M files for this monorepo, which OOMs
+      # upload-artifact's Node process at its 4GB heap limit during
+      # enumeration (each pnpm symlink resolves to a separate entry, and
+      # the action holds the full manifest in memory before streaming).
+      # The publish job runs `pnpm install --frozen-lockfile` after
+      # download to restore node_modules from pnpm-lock.yaml — mirrors
+      # publish-release.yml.
       - name: Upload workspace
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: workspace
-          path: .
+          path: |
+            .
+            !**/node_modules/**
+            !**/.next/**
+            !**/.turbo/**
+            !**/.nx/**
           include-hidden-files: true
           retention-days: 1
 
@@ -107,6 +120,14 @@ jobs:
           node-version: 22.x
           registry-url: https://registry.npmjs.org
 
+      # Restore node_modules — the build job excludes them from the
+      # uploaded workspace artifact (see "Upload workspace" above). Uses
+      # pnpm-lock.yaml from the artifact, so this is a deterministic
+      # restore of exactly what the build job ran with. `pnpm tsx` in the
+      # publish step below requires tsx to be installed locally.
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
       - name: Publish prerelease
         env:
           NODE_AUTH_TOKEN: ""

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,
   };