@copilotkit/react-core 1.57.3 → 1.58.0-canary.thread-id-propagation

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (292) hide show
  1. package/LICENSE +21 -0
  2. package/dist/{copilotkit-CtXcs1ea.cjs → copilotkit-B4ouY7qC.cjs} +14 -3
  3. package/dist/copilotkit-B4ouY7qC.cjs.map +1 -0
  4. package/dist/copilotkit-BK9CVq9A.d.cts.map +1 -1
  5. package/dist/{copilotkit-CC8DjOiC.mjs → copilotkit-L4mM_JqG.mjs} +14 -3
  6. package/dist/copilotkit-L4mM_JqG.mjs.map +1 -0
  7. package/dist/copilotkit-WlmeVijs.d.mts.map +1 -1
  8. package/dist/index.cjs +3 -77
  9. package/dist/index.cjs.map +1 -1
  10. package/dist/index.d.cts +2 -2
  11. package/dist/index.d.mts +2 -2
  12. package/dist/index.mjs +3 -77
  13. package/dist/index.mjs.map +1 -1
  14. package/dist/index.umd.js +15 -78
  15. package/dist/index.umd.js.map +1 -1
  16. package/dist/v2/headless.cjs +11 -0
  17. package/dist/v2/headless.cjs.map +1 -1
  18. package/dist/v2/headless.d.cts.map +1 -1
  19. package/dist/v2/headless.d.mts.map +1 -1
  20. package/dist/v2/headless.mjs +11 -0
  21. package/dist/v2/headless.mjs.map +1 -1
  22. package/dist/v2/index.cjs +1 -1
  23. package/dist/v2/index.mjs +1 -1
  24. package/dist/v2/index.umd.js +13 -2
  25. package/dist/v2/index.umd.js.map +1 -1
  26. package/package.json +12 -13
  27. package/skills/react-core/SKILL.md +108 -0
  28. package/skills/react-core/references/agent-access.md +288 -0
  29. package/skills/react-core/references/attachments.md +291 -0
  30. package/skills/react-core/references/capabilities.md +138 -0
  31. package/skills/react-core/references/chat-components.md +221 -0
  32. package/skills/react-core/references/client-side-tools.md +358 -0
  33. package/skills/react-core/references/custom-message-renderers.md +226 -0
  34. package/skills/react-core/references/debug-mode.md +153 -0
  35. package/skills/react-core/references/human-in-the-loop.md +312 -0
  36. package/skills/react-core/references/provider-setup.md +326 -0
  37. package/skills/react-core/references/rendering-activity-messages.md +207 -0
  38. package/skills/react-core/references/rendering-tool-calls.md +319 -0
  39. package/skills/react-core/references/suggestions.md +211 -0
  40. package/skills/react-core/references/switching-agents-recipes.md +160 -0
  41. package/skills/react-core/references/switching-agents.md +231 -0
  42. package/skills/react-core/references/threads.md +226 -0
  43. package/.attw.json +0 -3
  44. package/CHANGELOG.md +0 -5043
  45. package/dist/copilotkit-CC8DjOiC.mjs.map +0 -1
  46. package/dist/copilotkit-CtXcs1ea.cjs.map +0 -1
  47. package/scripts/scope-preflight.mjs +0 -100
  48. package/src/components/CopilotListeners.tsx +0 -137
  49. package/src/components/__tests__/CopilotListeners.test.tsx +0 -38
  50. package/src/components/copilot-provider/__tests__/copilot-messages-key.test.tsx +0 -92
  51. package/src/components/copilot-provider/__tests__/copilotkit-error.test.tsx +0 -77
  52. package/src/components/copilot-provider/__tests__/error-visibility-prod.test.tsx +0 -70
  53. package/src/components/copilot-provider/__tests__/v1-explicit-threadid-bridge.test.tsx +0 -107
  54. package/src/components/copilot-provider/copilot-messages.tsx +0 -314
  55. package/src/components/copilot-provider/copilotkit-props.tsx +0 -214
  56. package/src/components/copilot-provider/copilotkit.tsx +0 -853
  57. package/src/components/copilot-provider/index.ts +0 -3
  58. package/src/components/dev-console/console-trigger.tsx +0 -283
  59. package/src/components/dev-console/developer-console-modal.tsx +0 -1016
  60. package/src/components/dev-console/icons.tsx +0 -106
  61. package/src/components/error-boundary/error-boundary.tsx +0 -99
  62. package/src/components/error-boundary/error-utils.tsx +0 -105
  63. package/src/components/index.ts +0 -1
  64. package/src/components/toast/exclamation-mark-icon.tsx +0 -27
  65. package/src/components/toast/toast-provider.tsx +0 -448
  66. package/src/components/usage-banner.tsx +0 -266
  67. package/src/context/__tests__/threads-context.test.tsx +0 -141
  68. package/src/context/coagent-state-renders-context.tsx +0 -89
  69. package/src/context/copilot-context.tsx +0 -365
  70. package/src/context/copilot-messages-context.tsx +0 -35
  71. package/src/context/index.ts +0 -22
  72. package/src/context/threads-context.tsx +0 -69
  73. package/src/hooks/__tests__/use-coagent-config.test.ts +0 -352
  74. package/src/hooks/__tests__/use-coagent-state-render-bridge.helpers.test.ts +0 -107
  75. package/src/hooks/__tests__/use-coagent-state-render.e2e.test.tsx +0 -1209
  76. package/src/hooks/__tests__/use-coagent-state-render.test.tsx +0 -356
  77. package/src/hooks/__tests__/use-copilot-chat-internal-connect.test.tsx +0 -241
  78. package/src/hooks/__tests__/use-frontend-tool-available.test.tsx +0 -72
  79. package/src/hooks/__tests__/use-frontend-tool-remount.e2e.test.tsx +0 -102
  80. package/src/hooks/index.ts +0 -33
  81. package/src/hooks/use-agent-nodename.ts +0 -33
  82. package/src/hooks/use-coagent-state-render-bridge.helpers.ts +0 -345
  83. package/src/hooks/use-coagent-state-render-bridge.tsx +0 -222
  84. package/src/hooks/use-coagent-state-render-registry.ts +0 -230
  85. package/src/hooks/use-coagent-state-render.ts +0 -163
  86. package/src/hooks/use-coagent.ts +0 -377
  87. package/src/hooks/use-configure-chat-suggestions.tsx +0 -96
  88. package/src/hooks/use-copilot-action.ts +0 -245
  89. package/src/hooks/use-copilot-additional-instructions.ts +0 -98
  90. package/src/hooks/use-copilot-authenticated-action.ts +0 -73
  91. package/src/hooks/use-copilot-chat-headless_c.ts +0 -264
  92. package/src/hooks/use-copilot-chat-suggestions.tsx +0 -134
  93. package/src/hooks/use-copilot-chat.ts +0 -132
  94. package/src/hooks/use-copilot-chat_internal.ts +0 -875
  95. package/src/hooks/use-copilot-readable.ts +0 -135
  96. package/src/hooks/use-copilot-runtime-client.ts +0 -178
  97. package/src/hooks/use-default-tool.ts +0 -13
  98. package/src/hooks/use-flat-category-store.ts +0 -109
  99. package/src/hooks/use-frontend-tool.ts +0 -113
  100. package/src/hooks/use-human-in-the-loop.ts +0 -138
  101. package/src/hooks/use-langgraph-interrupt.ts +0 -103
  102. package/src/hooks/use-lazy-tool-renderer.tsx +0 -30
  103. package/src/hooks/use-make-copilot-document-readable.ts +0 -30
  104. package/src/hooks/use-render-tool-call.ts +0 -89
  105. package/src/hooks/use-tree.ts +0 -222
  106. package/src/index.tsx +0 -7
  107. package/src/lib/copilot-task.ts +0 -215
  108. package/src/lib/index.ts +0 -1
  109. package/src/lib/status-checker.ts +0 -67
  110. package/src/setupTests.ts +0 -37
  111. package/src/test-helpers/copilot-context.ts +0 -91
  112. package/src/types/chat-suggestion-configuration.ts +0 -23
  113. package/src/types/coagent-action.ts +0 -35
  114. package/src/types/coagent-state.ts +0 -13
  115. package/src/types/crew.ts +0 -89
  116. package/src/types/document-pointer.ts +0 -7
  117. package/src/types/frontend-action.ts +0 -213
  118. package/src/types/index.ts +0 -17
  119. package/src/types/interrupt-action.ts +0 -58
  120. package/src/types/system-message.ts +0 -4
  121. package/src/utils/dev-console.ts +0 -19
  122. package/src/utils/index.ts +0 -2
  123. package/src/utils/suggestions-constants.ts +0 -8
  124. package/src/utils/utils.test.ts +0 -7
  125. package/src/utils/utils.ts +0 -6
  126. package/src/v2/__tests__/A2UIMessageRenderer.test.tsx +0 -240
  127. package/src/v2/__tests__/globalSetup.ts +0 -14
  128. package/src/v2/__tests__/setup.ts +0 -93
  129. package/src/v2/__tests__/utils/test-helpers.tsx +0 -570
  130. package/src/v2/a2ui/A2UICatalogContext.tsx +0 -79
  131. package/src/v2/a2ui/A2UIMessageRenderer.tsx +0 -294
  132. package/src/v2/a2ui/A2UIToolCallRenderer.tsx +0 -290
  133. package/src/v2/components/CopilotKitInspector.tsx +0 -52
  134. package/src/v2/components/MCPAppsActivityRenderer.tsx +0 -815
  135. package/src/v2/components/OpenGenerativeUIRenderer.tsx +0 -598
  136. package/src/v2/components/WildcardToolCallRender.tsx +0 -86
  137. package/src/v2/components/__tests__/OpenGenerativeUIRenderer.test.tsx +0 -665
  138. package/src/v2/components/chat/CopilotChat.tsx +0 -664
  139. package/src/v2/components/chat/CopilotChatAssistantMessage.tsx +0 -393
  140. package/src/v2/components/chat/CopilotChatAttachmentQueue.tsx +0 -374
  141. package/src/v2/components/chat/CopilotChatAttachmentRenderer.tsx +0 -159
  142. package/src/v2/components/chat/CopilotChatAudioRecorder.tsx +0 -350
  143. package/src/v2/components/chat/CopilotChatInput.tsx +0 -1412
  144. package/src/v2/components/chat/CopilotChatMessageView.tsx +0 -716
  145. package/src/v2/components/chat/CopilotChatReasoningMessage.tsx +0 -265
  146. package/src/v2/components/chat/CopilotChatSuggestionPill.tsx +0 -59
  147. package/src/v2/components/chat/CopilotChatSuggestionView.tsx +0 -134
  148. package/src/v2/components/chat/CopilotChatToggleButton.tsx +0 -171
  149. package/src/v2/components/chat/CopilotChatToolCallsView.tsx +0 -40
  150. package/src/v2/components/chat/CopilotChatUserMessage.tsx +0 -445
  151. package/src/v2/components/chat/CopilotChatView.tsx +0 -890
  152. package/src/v2/components/chat/CopilotModalHeader.tsx +0 -129
  153. package/src/v2/components/chat/CopilotPopup.tsx +0 -81
  154. package/src/v2/components/chat/CopilotPopupView.tsx +0 -317
  155. package/src/v2/components/chat/CopilotSidebar.tsx +0 -80
  156. package/src/v2/components/chat/CopilotSidebarView.tsx +0 -269
  157. package/src/v2/components/chat/Lightbox.tsx +0 -103
  158. package/src/v2/components/chat/__tests__/CopilotChat.absentThreadConnect.test.tsx +0 -66
  159. package/src/v2/components/chat/__tests__/CopilotChat.attachments.test.tsx +0 -168
  160. package/src/v2/components/chat/__tests__/CopilotChat.e2e.test.tsx +0 -1239
  161. package/src/v2/components/chat/__tests__/CopilotChat.onError.test.tsx +0 -73
  162. package/src/v2/components/chat/__tests__/CopilotChat.slots.e2e.test.tsx +0 -432
  163. package/src/v2/components/chat/__tests__/CopilotChat.suggestionsAlways.test.tsx +0 -183
  164. package/src/v2/components/chat/__tests__/CopilotChat.welcomeGate.test.tsx +0 -184
  165. package/src/v2/components/chat/__tests__/CopilotChatActivityRendering.e2e.test.tsx +0 -649
  166. package/src/v2/components/chat/__tests__/CopilotChatAssistantMessage.slots.e2e.test.tsx +0 -624
  167. package/src/v2/components/chat/__tests__/CopilotChatAssistantMessage.test.tsx +0 -702
  168. package/src/v2/components/chat/__tests__/CopilotChatAssistantMessage.thumbs.test.tsx +0 -72
  169. package/src/v2/components/chat/__tests__/CopilotChatCopyButton.clipboard.test.tsx +0 -241
  170. package/src/v2/components/chat/__tests__/CopilotChatCssClasses.test.tsx +0 -107
  171. package/src/v2/components/chat/__tests__/CopilotChatInput.slots.e2e.test.tsx +0 -929
  172. package/src/v2/components/chat/__tests__/CopilotChatInput.test.tsx +0 -1567
  173. package/src/v2/components/chat/__tests__/CopilotChatMessageView.slots.e2e.test.tsx +0 -1004
  174. package/src/v2/components/chat/__tests__/CopilotChatMessageView.test.tsx +0 -279
  175. package/src/v2/components/chat/__tests__/CopilotChatPerf.e2e.test.tsx +0 -336
  176. package/src/v2/components/chat/__tests__/CopilotChatPropsRerender.e2e.test.tsx +0 -249
  177. package/src/v2/components/chat/__tests__/CopilotChatSuggestionView.slots.e2e.test.tsx +0 -530
  178. package/src/v2/components/chat/__tests__/CopilotChatToolRendering.e2e.test.tsx +0 -785
  179. package/src/v2/components/chat/__tests__/CopilotChatToolRerenders.e2e.test.tsx +0 -2416
  180. package/src/v2/components/chat/__tests__/CopilotChatUserMessage.slots.e2e.test.tsx +0 -621
  181. package/src/v2/components/chat/__tests__/CopilotChatView.connectingGate.test.tsx +0 -56
  182. package/src/v2/components/chat/__tests__/CopilotChatView.inputOverlay.test.tsx +0 -264
  183. package/src/v2/components/chat/__tests__/CopilotChatView.onClick.e2e.test.tsx +0 -853
  184. package/src/v2/components/chat/__tests__/CopilotChatView.pinToSend.test.tsx +0 -94
  185. package/src/v2/components/chat/__tests__/CopilotChatView.slots.e2e.test.tsx +0 -1050
  186. package/src/v2/components/chat/__tests__/CopilotModalHeader.slots.e2e.test.tsx +0 -484
  187. package/src/v2/components/chat/__tests__/CopilotPopupView.slots.e2e.test.tsx +0 -612
  188. package/src/v2/components/chat/__tests__/CopilotSidebarView.position.test.tsx +0 -159
  189. package/src/v2/components/chat/__tests__/CopilotSidebarView.slots.e2e.test.tsx +0 -502
  190. package/src/v2/components/chat/__tests__/MCPAppsActivityRenderer.e2e.test.tsx +0 -1068
  191. package/src/v2/components/chat/__tests__/MCPAppsProxy.e2e.test.tsx +0 -589
  192. package/src/v2/components/chat/__tests__/MCPAppsUiMessage.e2e.test.tsx +0 -403
  193. package/src/v2/components/chat/__tests__/copilot-chat-throttle.test.tsx +0 -137
  194. package/src/v2/components/chat/__tests__/normalize-auto-scroll.test.ts +0 -37
  195. package/src/v2/components/chat/__tests__/setup.ts +0 -1
  196. package/src/v2/components/chat/index.ts +0 -90
  197. package/src/v2/components/chat/last-user-message-context.ts +0 -21
  198. package/src/v2/components/chat/normalize-auto-scroll.ts +0 -17
  199. package/src/v2/components/chat/scroll-element-context.ts +0 -13
  200. package/src/v2/components/index.ts +0 -8
  201. package/src/v2/components/intelligence-indicator/IntelligenceIndicator.tsx +0 -286
  202. package/src/v2/components/intelligence-indicator/__tests__/IntelligenceIndicator.e2e.test.tsx +0 -464
  203. package/src/v2/components/intelligence-indicator/index.ts +0 -2
  204. package/src/v2/components/license-warning-banner.tsx +0 -217
  205. package/src/v2/components/ui/button.tsx +0 -124
  206. package/src/v2/components/ui/dropdown-menu.tsx +0 -258
  207. package/src/v2/components/ui/tooltip.tsx +0 -60
  208. package/src/v2/context.ts +0 -62
  209. package/src/v2/headless.ts +0 -64
  210. package/src/v2/hooks/__tests__/standard-schema-types.test.tsx +0 -152
  211. package/src/v2/hooks/__tests__/standard-schema.test.tsx +0 -282
  212. package/src/v2/hooks/__tests__/use-agent-context-timing.e2e.test.tsx +0 -140
  213. package/src/v2/hooks/__tests__/use-agent-context.test.tsx +0 -401
  214. package/src/v2/hooks/__tests__/use-agent-error-state.test.tsx +0 -44
  215. package/src/v2/hooks/__tests__/use-agent-stability.test.tsx +0 -211
  216. package/src/v2/hooks/__tests__/use-agent-throttle.test.tsx +0 -1029
  217. package/src/v2/hooks/__tests__/use-agent.e2e.test.tsx +0 -159
  218. package/src/v2/hooks/__tests__/use-attachments.test.tsx +0 -169
  219. package/src/v2/hooks/__tests__/use-capabilities.test.tsx +0 -76
  220. package/src/v2/hooks/__tests__/use-component.test.tsx +0 -126
  221. package/src/v2/hooks/__tests__/use-configure-suggestions.e2e.test.tsx +0 -696
  222. package/src/v2/hooks/__tests__/use-default-render-tool.test.tsx +0 -153
  223. package/src/v2/hooks/__tests__/use-frontend-tool-available.test.tsx +0 -167
  224. package/src/v2/hooks/__tests__/use-frontend-tool.e2e.test.tsx +0 -2148
  225. package/src/v2/hooks/__tests__/use-human-in-the-loop.e2e.test.tsx +0 -1261
  226. package/src/v2/hooks/__tests__/use-interrupt.test.tsx +0 -397
  227. package/src/v2/hooks/__tests__/use-katex-styles.test.tsx +0 -56
  228. package/src/v2/hooks/__tests__/use-keyboard-height.test.tsx +0 -192
  229. package/src/v2/hooks/__tests__/use-pin-to-send.test.tsx +0 -219
  230. package/src/v2/hooks/__tests__/use-render-custom-messages.test.tsx +0 -55
  231. package/src/v2/hooks/__tests__/use-render-tool.test.tsx +0 -259
  232. package/src/v2/hooks/__tests__/use-suggestions.e2e.test.tsx +0 -524
  233. package/src/v2/hooks/__tests__/use-threads.test.tsx +0 -757
  234. package/src/v2/hooks/__tests__/zod-regression.test.tsx +0 -311
  235. package/src/v2/hooks/index.ts +0 -24
  236. package/src/v2/hooks/use-agent-context.tsx +0 -45
  237. package/src/v2/hooks/use-agent.tsx +0 -227
  238. package/src/v2/hooks/use-attachments.tsx +0 -269
  239. package/src/v2/hooks/use-capabilities.tsx +0 -25
  240. package/src/v2/hooks/use-component.tsx +0 -91
  241. package/src/v2/hooks/use-configure-suggestions.tsx +0 -236
  242. package/src/v2/hooks/use-default-render-tool.tsx +0 -271
  243. package/src/v2/hooks/use-frontend-tool.tsx +0 -46
  244. package/src/v2/hooks/use-human-in-the-loop.tsx +0 -81
  245. package/src/v2/hooks/use-interrupt.tsx +0 -305
  246. package/src/v2/hooks/use-keyboard-height.tsx +0 -67
  247. package/src/v2/hooks/use-pin-to-send.ts +0 -94
  248. package/src/v2/hooks/use-render-activity-message.tsx +0 -72
  249. package/src/v2/hooks/use-render-custom-messages.tsx +0 -93
  250. package/src/v2/hooks/use-render-tool-call.tsx +0 -208
  251. package/src/v2/hooks/use-render-tool.tsx +0 -184
  252. package/src/v2/hooks/use-suggestions.tsx +0 -91
  253. package/src/v2/hooks/use-threads.tsx +0 -325
  254. package/src/v2/hooks/useKatexStyles.ts +0 -27
  255. package/src/v2/index.css +0 -1
  256. package/src/v2/index.ts +0 -27
  257. package/src/v2/lib/__tests__/completePartialMarkdown.test.ts +0 -495
  258. package/src/v2/lib/__tests__/processPartialHtml.test.ts +0 -112
  259. package/src/v2/lib/__tests__/renderSlot.test.tsx +0 -588
  260. package/src/v2/lib/__tests__/slots.test.ts +0 -56
  261. package/src/v2/lib/processPartialHtml.ts +0 -45
  262. package/src/v2/lib/react-core.ts +0 -156
  263. package/src/v2/lib/slots.tsx +0 -184
  264. package/src/v2/lib/transcription-client.ts +0 -184
  265. package/src/v2/lib/utils.ts +0 -8
  266. package/src/v2/providers/CopilotChatConfigurationProvider.tsx +0 -196
  267. package/src/v2/providers/CopilotKitProvider.tsx +0 -800
  268. package/src/v2/providers/SandboxFunctionsContext.ts +0 -10
  269. package/src/v2/providers/__tests__/CopilotChatConfigurationProvider.test.tsx +0 -652
  270. package/src/v2/providers/__tests__/CopilotKitProvider.license.test.tsx +0 -101
  271. package/src/v2/providers/__tests__/CopilotKitProvider.onError.test.tsx +0 -69
  272. package/src/v2/providers/__tests__/CopilotKitProvider.renderCustomMessages.e2e.test.tsx +0 -881
  273. package/src/v2/providers/__tests__/CopilotKitProvider.sandboxFunctions.test.tsx +0 -198
  274. package/src/v2/providers/__tests__/CopilotKitProvider.stability.test.tsx +0 -740
  275. package/src/v2/providers/__tests__/CopilotKitProvider.test.tsx +0 -713
  276. package/src/v2/providers/__tests__/CopilotKitProvider.wildcard.test.tsx +0 -294
  277. package/src/v2/providers/index.ts +0 -21
  278. package/src/v2/styles/globals.css +0 -349
  279. package/src/v2/types/__tests__/defineToolCallRenderer.test.tsx +0 -525
  280. package/src/v2/types/defineToolCallRenderer.ts +0 -68
  281. package/src/v2/types/frontend-tool.ts +0 -8
  282. package/src/v2/types/human-in-the-loop.ts +0 -33
  283. package/src/v2/types/index.ts +0 -8
  284. package/src/v2/types/interrupt.ts +0 -15
  285. package/src/v2/types/react-activity-message-renderer.ts +0 -27
  286. package/src/v2/types/react-custom-message-renderer.ts +0 -17
  287. package/src/v2/types/react-tool-call-renderer.ts +0 -35
  288. package/src/v2/types/sandbox-function.ts +0 -11
  289. package/tsconfig.json +0 -8
  290. package/tsdown.config.ts +0 -193
  291. package/typedoc.json +0 -4
  292. package/vitest.config.mjs +0 -31
package/skills/react-core/references/provider-setup.md ADDED
@@ -0,0 +1,326 @@
1
+ # CopilotKit Provider Setup (React)
2
+
3
+ Mount `CopilotKitProvider` once near the root of the React tree. Every
4
+ CopilotKit hook (`useAgent`, `useFrontendTool`, `useRenderTool`, etc.) and
5
+ every chat component (`CopilotChat`, `CopilotPopup`, `CopilotSidebar`) must
6
+ be rendered inside this provider.
7
+
8
+ All v2 imports use the `@copilotkit/react-core/v2` subpath. Imports from the
9
+ package root are v1 and will not work with v2 hooks or components.
10
+
11
+ ## Setup
12
+
13
+ ### Next.js App Router (and any RSC-based framework)
14
+
15
+ `@copilotkit/react-core/v2` is marked `"use client"`. You must mount the
16
+ provider from a client component, not a server component. The cleanest
17
+ pattern is a dedicated client-only `providers.tsx`.
18
+
19
+ ```tsx
20
+ // app/providers.tsx
21
+ "use client";
22
+
23
+ import { CopilotKitProvider } from "@copilotkit/react-core/v2";
24
+ import "@copilotkit/react-core/v2/styles.css";
25
+
26
+ export function Providers({ children }: { children: React.ReactNode }) {
27
+ return (
28
+ <CopilotKitProvider
29
+ runtimeUrl="/api/copilotkit"
30
+ credentials="include"
31
+ onError={({ code, error, context }) => {
32
+ console.error("[copilotkit]", code, error, context);
33
+ }}
34
+ >
35
+ {children}
36
+ </CopilotKitProvider>
37
+ );
38
+ }
39
+ ```
40
+
41
+ For auth headers that change over the session (rotating bearer tokens,
42
+ refreshed cookies), see the "Stable headers for rotating auth tokens"
43
+ pattern below. Avoid putting a `useMemo(() => ({ Authorization: ... }),
44
+ [])` on the provider — an empty deps array captures the token at mount
45
+ and never refreshes.
46
+
47
+ ```tsx
48
+ // app/layout.tsx — server component
49
+ import { Providers } from "./providers";
50
+
51
+ export default function RootLayout({
52
+ children,
53
+ }: {
54
+ children: React.ReactNode;
55
+ }) {
56
+ return (
57
+ <html lang="en">
58
+ <body>
59
+ <Providers>{children}</Providers>
60
+ </body>
61
+ </html>
62
+ );
63
+ }
64
+ ```
65
+
66
+ ### Vite / React Router v7 / SPA
67
+
68
+ ```tsx
69
+ import { CopilotKitProvider } from "@copilotkit/react-core/v2";
70
+ import "@copilotkit/react-core/v2/styles.css";
71
+
72
+ export function App({ children }: { children: React.ReactNode }) {
73
+ return (
74
+ <CopilotKitProvider runtimeUrl="/api/copilotkit">
75
+ {children}
76
+ </CopilotKitProvider>
77
+ );
78
+ }
79
+ ```
80
+
81
+ ### SPA with CopilotKit Cloud (no self-hosted runtime)
82
+
83
+ ```tsx
84
+ <CopilotKitProvider publicApiKey="ck_pub_..." />
85
+ ```
86
+
87
+ `publicApiKey` is the canonical prop for running CopilotKit from a pure
88
+ client bundle. `publicLicenseKey` is an alias that resolves to the same
89
+ value (`publicApiKey ?? publicLicenseKey`) — accept in old code, but
90
+ always write `publicApiKey` in new code.
91
+
92
+ ## Core Patterns
93
+
94
+ ### Stable headers for rotating auth tokens
95
+
96
+ For tokens that change during the session, use the imperative setter instead
97
+ of re-rendering the provider with a new `headers` prop.
98
+
99
+ ```tsx
100
+ "use client";
101
+ import { useCopilotKit } from "@copilotkit/react-core/v2";
102
+ import { useEffect } from "react";
103
+
104
+ export function AuthTokenSync({ token }: { token: string }) {
105
+ const { copilotkit } = useCopilotKit();
106
+ useEffect(() => {
107
+ copilotkit.setHeaders({ Authorization: `Bearer ${token}` });
108
+ }, [copilotkit, token]);
109
+ return null;
110
+ }
111
+ ```
112
+
113
+ ### Global error handler
114
+
115
+ `onError` fires for every `CopilotKitCoreErrorCode` emitted by core. Keeps
116
+ UI from getting stuck in "connecting..." when the runtime URL is wrong or
117
+ CORS is misconfigured.
118
+
119
+ ```tsx
120
+ <CopilotKitProvider
121
+ runtimeUrl="/api/copilotkit"
122
+ onError={({ code, error, context }) => {
123
+ telemetry.capture({ code, message: error.message, context });
124
+ }}
125
+ />
126
+ ```
127
+
128
+ ### Sharing app properties with every run
129
+
130
+ `properties` flows to the runtime on each agent run — useful for tenant IDs,
131
+ feature flags, or anything the server needs.
132
+
133
+ ```tsx
134
+ const properties = useMemo(
135
+ () => ({ tenantId: user.tenantId, locale: user.locale }),
136
+ [user.tenantId, user.locale],
137
+ );
138
+
139
+ <CopilotKitProvider runtimeUrl="/api/copilotkit" properties={properties} />;
140
+ ```
141
+
142
+ ## Common Mistakes
143
+
144
+ ### CRITICAL — Mounting the provider from a Server Component
145
+
146
+ Wrong:
147
+
148
+ ```tsx
149
+ // app/page.tsx (server component — no "use client")
150
+ import { CopilotKitProvider } from "@copilotkit/react-core/v2";
151
+
152
+ export default function Page() {
153
+ return (
154
+ <CopilotKitProvider runtimeUrl="/api/copilotkit">...</CopilotKitProvider>
155
+ );
156
+ }
157
+ ```
158
+
159
+ Correct:
160
+
161
+ ```tsx
162
+ // app/providers.tsx
163
+ "use client";
164
+ import { CopilotKitProvider } from "@copilotkit/react-core/v2";
165
+
166
+ export function Providers({ children }: { children: React.ReactNode }) {
167
+ return (
168
+ <CopilotKitProvider runtimeUrl="/api/copilotkit">
169
+ {children}
170
+ </CopilotKitProvider>
171
+ );
172
+ }
173
+
174
+ // app/layout.tsx imports <Providers>.
175
+ ```
176
+
177
+ `@copilotkit/react-core/v2` begins with `"use client"`. Importing it from a
178
+ server component silently strips interactivity — the provider renders but
179
+ none of the hooks wire up.
180
+
181
+ Source: `packages/react-core/src/v2/index.ts:1`
182
+
183
+ ### CRITICAL — Using `agents__unsafe_dev_only` or `selfManagedAgents` in production
184
+
185
+ Wrong:
186
+
187
+ ```tsx
188
+ <CopilotKitProvider
189
+ agents__unsafe_dev_only={{
190
+ default: new BuiltInAgent({ apiKey: process.env.OPENAI_KEY! }),
191
+ }}
192
+ />
193
+ // or the alias (same thing):
194
+ <CopilotKitProvider
195
+ selfManagedAgents={{ default: new BuiltInAgent({ apiKey: "..." }) }}
196
+ />
197
+ ```
198
+
199
+ Correct:
200
+
201
+ ```tsx
202
+ // Route through a runtime that keeps secrets server-side:
203
+ <CopilotKitProvider runtimeUrl="/api/copilotkit" />
204
+
205
+ // Or for a pure SPA, use CopilotKit Cloud:
206
+ <CopilotKitProvider publicApiKey="ck_pub_..." />
207
+ ```
208
+
209
+ Both props are aliases for the same dev-only mechanism and ship any embedded
210
+ credentials to the browser bundle. Never use either for production agents.
211
+
212
+ Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:136-138,393`
213
+
214
+ ### HIGH — Inline object props rebuilt every render
215
+
216
+ Wrong:
217
+
218
+ ```tsx
219
+ <CopilotKitProvider
220
+ runtimeUrl="/api/copilotkit"
221
+ headers={{ Authorization: `Bearer ${token}` }}
222
+ properties={{ tenantId: user.tenantId }}
223
+ />
224
+ ```
225
+
226
+ Correct:
227
+
228
+ ```tsx
229
+ const headers = useMemo(() => ({ Authorization: `Bearer ${token}` }), [token]);
230
+ const properties = useMemo(
231
+ () => ({ tenantId: user.tenantId }),
232
+ [user.tenantId],
233
+ );
234
+
235
+ <CopilotKitProvider
236
+ runtimeUrl="/api/copilotkit"
237
+ headers={headers}
238
+ properties={properties}
239
+ />;
240
+ ```
241
+
242
+ New object identity on every render causes the provider to diff-churn
243
+ internal state and may thrash tool/renderer registration. `useStableArrayProp`
244
+ also logs a `console.error` when array-prop shape changes without
245
+ memoization.
246
+
247
+ Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:324-340,399-410`
248
+
249
+ ### HIGH — Missing `onError` leaves users stuck in "connecting..."
250
+
251
+ Wrong:
252
+
253
+ ```tsx
254
+ <CopilotKitProvider runtimeUrl="/api/copilotkit" />
255
+ ```
256
+
257
+ Correct:
258
+
259
+ ```tsx
260
+ <CopilotKitProvider
261
+ runtimeUrl="/api/copilotkit"
262
+ onError={({ code, error, context }) => {
263
+ telemetry.capture({ code, error, context });
264
+ }}
265
+ />
266
+ ```
267
+
268
+ Without `onError`, connection failures (bad runtime URL, CORS, network) keep
269
+ the provider in a provisional state with `ProxiedCopilotRuntimeAgent`
270
+ instances that never resolve. The chat UI keeps showing "connecting..."
271
+ forever and users never see the actual error.
272
+
273
+ Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:638-660`
274
+
275
+ ### HIGH — Writing `publicLicenseKey` in new code
276
+
277
+ Wrong:
278
+
279
+ ```tsx
280
+ <CopilotKitProvider publicLicenseKey="ck_pub_..." />
281
+ ```
282
+
283
+ Correct:
284
+
285
+ ```tsx
286
+ <CopilotKitProvider publicApiKey="ck_pub_..." />
287
+ ```
288
+
289
+ `publicLicenseKey` still works as an alias, but `publicApiKey` is the
290
+ canonical name in v2. The provider resolves
291
+ `publicApiKey ?? publicLicenseKey`. Always write the canonical form in
292
+ new code.
293
+
294
+ Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:122-128,391`
295
+
296
+ ### MEDIUM — Putting the provider below a layout that uses CopilotKit
297
+
298
+ Wrong:
299
+
300
+ ```tsx
301
+ <html>
302
+ <body>
303
+ <Header>{/* Header uses useFrontendTool internally */}</Header>
304
+ <CopilotKitProvider>{children}</CopilotKitProvider>
305
+ </body>
306
+ </html>
307
+ ```
308
+
309
+ Correct:
310
+
311
+ ```tsx
312
+ <html>
313
+ <body>
314
+ <CopilotKitProvider>
315
+ <Header />
316
+ {children}
317
+ </CopilotKitProvider>
318
+ </body>
319
+ </html>
320
+ ```
321
+
322
+ Any component that calls `useCopilotKit`, `useFrontendTool`, `useAgent`, or
323
+ any other CopilotKit hook must be a descendant of `CopilotKitProvider`.
324
+ Placing the provider beside or below a consumer throws at mount.
325
+
326
+ Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (context)
package/skills/react-core/references/rendering-activity-messages.md ADDED
@@ -0,0 +1,207 @@
1
+ # CopilotKit Rendering Activity Messages (React)
2
+
3
+ This skill builds on `copilotkit/provider-setup`. Activity-message
4
+ renderers are registered as entries in the `renderActivityMessages` array
5
+ prop on `CopilotKitProvider` and resolved at render time by
6
+ `useRenderActivityMessage` (consumed internally by chat components).
7
+
8
+ User renderers are placed first in the array so they override the built-in
9
+ `MCPAppsActivityType` and `OpenGenerativeUIActivityType` renderers for the
10
+ same `activityType`.
11
+
12
+ Resolver order:
13
+
14
+ 1. `(activityType, agentId)` match
15
+ 2. `(activityType, unscoped)` match
16
+ 3. `'*'` wildcard
17
+ 4. `null`
18
+
19
+ ## Setup
20
+
21
+ ```tsx
22
+ "use client";
23
+ import { CopilotKitProvider } from "@copilotkit/react-core/v2";
24
+ import type { ReactActivityMessageRenderer } from "@copilotkit/react-core/v2";
25
+ import { z } from "zod";
26
+ import { useMemo } from "react";
27
+ import { Card, CardContent } from "@/components/ui/card";
28
+ import { Progress } from "@/components/ui/progress";
29
+
30
+ const progressRenderer: ReactActivityMessageRenderer<{
31
+ percent: number;
32
+ label: string;
33
+ }> = {
34
+ activityType: "progress",
35
+ content: z.object({ percent: z.number().min(0).max(1), label: z.string() }),
36
+ render: ({ content }) => (
37
+ <Card>
38
+ <CardContent>
39
+ <div>{content.label}</div>
40
+ <Progress value={content.percent * 100} />
41
+ </CardContent>
42
+ </Card>
43
+ ),
44
+ };
45
+
46
+ export function Providers({ children }: { children: React.ReactNode }) {
47
+ const renderers = useMemo(() => [progressRenderer], []);
48
+ return (
49
+ <CopilotKitProvider
50
+ runtimeUrl="/api/copilotkit"
51
+ renderActivityMessages={renderers}
52
+ >
53
+ {children}
54
+ </CopilotKitProvider>
55
+ );
56
+ }
57
+ ```
58
+
59
+ ## Core Patterns
60
+
61
+ ### Agent-scoped renderer
62
+
63
+ ```tsx
64
+ const researchProgress: ReactActivityMessageRenderer<{ step: string }> = {
65
+ activityType: "research-step",
66
+ agentId: "research",
67
+ content: z.object({ step: z.string() }),
68
+ render: ({ content }) => <ResearchStepBadge step={content.step} />,
69
+ };
70
+ ```
71
+
72
+ ### Override a built-in (MCP Apps)
73
+
74
+ Place your renderer for the same `activityType` — user renderers are
75
+ evaluated before built-ins.
76
+
77
+ ```tsx
78
+ import { MCPAppsActivityType } from "@copilotkit/react-core/v2";
79
+
80
+ const customMcpRenderer: ReactActivityMessageRenderer<unknown> = {
81
+ activityType: MCPAppsActivityType, // "mcp-apps" — must match the exported constant
82
+ content: z.unknown(),
83
+ render: ({ content, message }) => <CustomMCPCard payload={content} />,
84
+ };
85
+ ```
86
+
87
+ ### Using the hook directly (custom chat surface)
88
+
89
+ ```tsx
90
+ import { useRenderActivityMessage } from "@copilotkit/react-core/v2";
91
+ import type { ActivityMessage } from "@ag-ui/core";
92
+
93
+ export function ActivityList({ messages }: { messages: ActivityMessage[] }) {
94
+ const { renderActivityMessage } = useRenderActivityMessage();
95
+ return (
96
+ <div>
97
+ {messages.map((m) => (
98
+ <div key={m.id}>{renderActivityMessage(m)}</div>
99
+ ))}
100
+ </div>
101
+ );
102
+ }
103
+ ```
104
+
105
+ ## Common Mistakes
106
+
107
+ ### HIGH — Incompatible content schema
108
+
109
+ Wrong:
110
+
111
+ ```tsx
112
+ // Renderer expects `pct`
113
+ const r: ReactActivityMessageRenderer<{ pct: number }> = {
114
+ activityType: "progress",
115
+ content: z.object({ pct: z.number() }),
116
+ render: ({ content }) => <Bar value={content.pct} />,
117
+ };
118
+ // But the server emits { percent: 0.5 } — mismatched field name
119
+ ```
120
+
121
+ Correct:
122
+
123
+ ```tsx
124
+ const r: ReactActivityMessageRenderer<{ percent: number }> = {
125
+ activityType: "progress",
126
+ content: z.object({ percent: z.number() }),
127
+ render: ({ content }) => <Bar value={content.percent} />,
128
+ };
129
+ ```
130
+
131
+ `safeParse` is called on every incoming activity message. Mismatched
132
+ schemas return `null` with only a `console.warn("Failed to parse content
133
+ for activity message …")` — the UI renders nothing and the failure is
134
+ silent unless you read the console.
135
+
136
+ Source: `packages/react-core/src/v2/hooks/use-render-activity-message.tsx:44-50`
137
+
138
+ ### MEDIUM — Side effects in `render`
139
+
140
+ Wrong:
141
+
142
+ ```tsx
143
+ render: ({ content }) => {
144
+ trackEvent(content); // fires on every re-render
145
+ return <Badge>{content.label}</Badge>;
146
+ };
147
+ ```
148
+
149
+ Wrong (Rules of Hooks violation):
150
+
151
+ ```tsx
152
+ render: ({ content }) => {
153
+ // `render` is invoked as a plain function by the resolver — NOT as a
154
+ // React component — so calling hooks directly inside it is illegal.
155
+ useEffect(() => trackEvent(content), [content]);
156
+ return <Badge>{content.label}</Badge>;
157
+ };
158
+ ```
159
+
160
+ Correct:
161
+
162
+ ```tsx
163
+ function TrackedBadge({ content }: { content: { label: string } }) {
164
+ useEffect(() => {
165
+ trackEvent(content);
166
+ }, [content]);
167
+ return <Badge>{content.label}</Badge>;
168
+ }
169
+
170
+ // In the renderer:
171
+ render: ({ content }) => <TrackedBadge content={content} />;
172
+ ```
173
+
174
+ Activity-message renderers re-render on every message-list tick. Side
175
+ effects in the render body fire repeatedly. Hooks cannot be called
176
+ directly inside `render` because the resolver invokes it as a plain
177
+ function; hoist the effect into a wrapper component that React mounts as
178
+ a real element.
179
+
180
+ Source: `packages/react-core/src/v2/hooks/use-render-activity-message.tsx`
181
+
182
+ ### MEDIUM — Building the `renderActivityMessages` array inline
183
+
184
+ Wrong:
185
+
186
+ ```tsx
187
+ <CopilotKitProvider
188
+ runtimeUrl="/api/copilotkit"
189
+ renderActivityMessages={[progressRenderer, customMcpRenderer]}
190
+ />
191
+ ```
192
+
193
+ Correct:
194
+
195
+ ```tsx
196
+ const renderers = useMemo(() => [progressRenderer, customMcpRenderer], []);
197
+ <CopilotKitProvider
198
+ runtimeUrl="/api/copilotkit"
199
+ renderActivityMessages={renderers}
200
+ />;
201
+ ```
202
+
203
+ The provider uses `useStableArrayProp` and console-errors when a new array
204
+ identity appears every render. Memoize or hoist the array to module
205
+ scope.
206
+
207
+ Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (useStableArrayProp)