npm - @copilotkit/react-core - Versions diffs - 1.57.2 → 1.57.4 - Mend

@copilotkit/react-core 1.57.2 → 1.57.4

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 (266) hide show

package/LICENSE +21 -0
package/package.json +12 -13
package/skills/react-core/SKILL.md +108 -0
package/skills/react-core/references/agent-access.md +288 -0
package/skills/react-core/references/attachments.md +291 -0
package/skills/react-core/references/capabilities.md +138 -0
package/skills/react-core/references/chat-components.md +221 -0
package/skills/react-core/references/client-side-tools.md +358 -0
package/skills/react-core/references/custom-message-renderers.md +226 -0
package/skills/react-core/references/debug-mode.md +153 -0
package/skills/react-core/references/human-in-the-loop.md +312 -0
package/skills/react-core/references/provider-setup.md +326 -0
package/skills/react-core/references/rendering-activity-messages.md +207 -0
package/skills/react-core/references/rendering-tool-calls.md +319 -0
package/skills/react-core/references/suggestions.md +211 -0
package/skills/react-core/references/switching-agents-recipes.md +160 -0
package/skills/react-core/references/switching-agents.md +231 -0
package/skills/react-core/references/threads.md +226 -0
package/.attw.json +0 -3
package/CHANGELOG.md +0 -5043
package/scripts/scope-preflight.mjs +0 -100
package/src/components/CopilotListeners.tsx +0 -137
package/src/components/__tests__/CopilotListeners.test.tsx +0 -38
package/src/components/copilot-provider/__tests__/copilot-messages-key.test.tsx +0 -92
package/src/components/copilot-provider/__tests__/copilotkit-error.test.tsx +0 -77
package/src/components/copilot-provider/__tests__/error-visibility-prod.test.tsx +0 -70
package/src/components/copilot-provider/__tests__/v1-explicit-threadid-bridge.test.tsx +0 -107
package/src/components/copilot-provider/copilot-messages.tsx +0 -314
package/src/components/copilot-provider/copilotkit-props.tsx +0 -214
package/src/components/copilot-provider/copilotkit.tsx +0 -853
package/src/components/copilot-provider/index.ts +0 -3
package/src/components/dev-console/console-trigger.tsx +0 -283
package/src/components/dev-console/developer-console-modal.tsx +0 -1016
package/src/components/dev-console/icons.tsx +0 -106
package/src/components/error-boundary/error-boundary.tsx +0 -99
package/src/components/error-boundary/error-utils.tsx +0 -105
package/src/components/index.ts +0 -1
package/src/components/toast/exclamation-mark-icon.tsx +0 -27
package/src/components/toast/toast-provider.tsx +0 -448
package/src/components/usage-banner.tsx +0 -266
package/src/context/__tests__/threads-context.test.tsx +0 -141
package/src/context/coagent-state-renders-context.tsx +0 -89
package/src/context/copilot-context.tsx +0 -365
package/src/context/copilot-messages-context.tsx +0 -35
package/src/context/index.ts +0 -22
package/src/context/threads-context.tsx +0 -69
package/src/hooks/__tests__/use-coagent-config.test.ts +0 -352
package/src/hooks/__tests__/use-coagent-state-render-bridge.helpers.test.ts +0 -107
package/src/hooks/__tests__/use-coagent-state-render.e2e.test.tsx +0 -1209
package/src/hooks/__tests__/use-coagent-state-render.test.tsx +0 -356
package/src/hooks/__tests__/use-copilot-chat-internal-connect.test.tsx +0 -241
package/src/hooks/__tests__/use-frontend-tool-available.test.tsx +0 -72
package/src/hooks/__tests__/use-frontend-tool-remount.e2e.test.tsx +0 -102
package/src/hooks/index.ts +0 -33
package/src/hooks/use-agent-nodename.ts +0 -33
package/src/hooks/use-coagent-state-render-bridge.helpers.ts +0 -345
package/src/hooks/use-coagent-state-render-bridge.tsx +0 -222
package/src/hooks/use-coagent-state-render-registry.ts +0 -230
package/src/hooks/use-coagent-state-render.ts +0 -163
package/src/hooks/use-coagent.ts +0 -377
package/src/hooks/use-configure-chat-suggestions.tsx +0 -96
package/src/hooks/use-copilot-action.ts +0 -245
package/src/hooks/use-copilot-additional-instructions.ts +0 -98
package/src/hooks/use-copilot-authenticated-action.ts +0 -73
package/src/hooks/use-copilot-chat-headless_c.ts +0 -264
package/src/hooks/use-copilot-chat-suggestions.tsx +0 -134
package/src/hooks/use-copilot-chat.ts +0 -132
package/src/hooks/use-copilot-chat_internal.ts +0 -875
package/src/hooks/use-copilot-readable.ts +0 -135
package/src/hooks/use-copilot-runtime-client.ts +0 -178
package/src/hooks/use-default-tool.ts +0 -13
package/src/hooks/use-flat-category-store.ts +0 -109
package/src/hooks/use-frontend-tool.ts +0 -113
package/src/hooks/use-human-in-the-loop.ts +0 -138
package/src/hooks/use-langgraph-interrupt.ts +0 -103
package/src/hooks/use-lazy-tool-renderer.tsx +0 -30
package/src/hooks/use-make-copilot-document-readable.ts +0 -30
package/src/hooks/use-render-tool-call.ts +0 -89
package/src/hooks/use-tree.ts +0 -222
package/src/index.tsx +0 -7
package/src/lib/copilot-task.ts +0 -215
package/src/lib/index.ts +0 -1
package/src/lib/status-checker.ts +0 -67
package/src/setupTests.ts +0 -37
package/src/test-helpers/copilot-context.ts +0 -91
package/src/types/chat-suggestion-configuration.ts +0 -23
package/src/types/coagent-action.ts +0 -35
package/src/types/coagent-state.ts +0 -13
package/src/types/crew.ts +0 -89
package/src/types/document-pointer.ts +0 -7
package/src/types/frontend-action.ts +0 -213
package/src/types/index.ts +0 -17
package/src/types/interrupt-action.ts +0 -58
package/src/types/system-message.ts +0 -4
package/src/utils/dev-console.ts +0 -19
package/src/utils/index.ts +0 -2
package/src/utils/suggestions-constants.ts +0 -8
package/src/utils/utils.test.ts +0 -7
package/src/utils/utils.ts +0 -6
package/src/v2/__tests__/A2UIMessageRenderer.test.tsx +0 -240
package/src/v2/__tests__/globalSetup.ts +0 -14
package/src/v2/__tests__/setup.ts +0 -93
package/src/v2/__tests__/utils/test-helpers.tsx +0 -570
package/src/v2/a2ui/A2UICatalogContext.tsx +0 -79
package/src/v2/a2ui/A2UIMessageRenderer.tsx +0 -294
package/src/v2/a2ui/A2UIToolCallRenderer.tsx +0 -290
package/src/v2/components/CopilotKitInspector.tsx +0 -52
package/src/v2/components/MCPAppsActivityRenderer.tsx +0 -815
package/src/v2/components/OpenGenerativeUIRenderer.tsx +0 -598
package/src/v2/components/WildcardToolCallRender.tsx +0 -86
package/src/v2/components/__tests__/OpenGenerativeUIRenderer.test.tsx +0 -665
package/src/v2/components/chat/CopilotChat.tsx +0 -664
package/src/v2/components/chat/CopilotChatAssistantMessage.tsx +0 -393
package/src/v2/components/chat/CopilotChatAttachmentQueue.tsx +0 -374
package/src/v2/components/chat/CopilotChatAttachmentRenderer.tsx +0 -159
package/src/v2/components/chat/CopilotChatAudioRecorder.tsx +0 -350
package/src/v2/components/chat/CopilotChatInput.tsx +0 -1412
package/src/v2/components/chat/CopilotChatMessageView.tsx +0 -716
package/src/v2/components/chat/CopilotChatReasoningMessage.tsx +0 -265
package/src/v2/components/chat/CopilotChatSuggestionPill.tsx +0 -59
package/src/v2/components/chat/CopilotChatSuggestionView.tsx +0 -134
package/src/v2/components/chat/CopilotChatToggleButton.tsx +0 -171
package/src/v2/components/chat/CopilotChatToolCallsView.tsx +0 -40
package/src/v2/components/chat/CopilotChatUserMessage.tsx +0 -445
package/src/v2/components/chat/CopilotChatView.tsx +0 -890
package/src/v2/components/chat/CopilotModalHeader.tsx +0 -129
package/src/v2/components/chat/CopilotPopup.tsx +0 -81
package/src/v2/components/chat/CopilotPopupView.tsx +0 -317
package/src/v2/components/chat/CopilotSidebar.tsx +0 -80
package/src/v2/components/chat/CopilotSidebarView.tsx +0 -269
package/src/v2/components/chat/Lightbox.tsx +0 -103
package/src/v2/components/chat/__tests__/CopilotChat.absentThreadConnect.test.tsx +0 -66
package/src/v2/components/chat/__tests__/CopilotChat.attachments.test.tsx +0 -168
package/src/v2/components/chat/__tests__/CopilotChat.e2e.test.tsx +0 -1239
package/src/v2/components/chat/__tests__/CopilotChat.onError.test.tsx +0 -73
package/src/v2/components/chat/__tests__/CopilotChat.slots.e2e.test.tsx +0 -432
package/src/v2/components/chat/__tests__/CopilotChat.suggestionsAlways.test.tsx +0 -183
package/src/v2/components/chat/__tests__/CopilotChat.welcomeGate.test.tsx +0 -184
package/src/v2/components/chat/__tests__/CopilotChatActivityRendering.e2e.test.tsx +0 -649
package/src/v2/components/chat/__tests__/CopilotChatAssistantMessage.slots.e2e.test.tsx +0 -624
package/src/v2/components/chat/__tests__/CopilotChatAssistantMessage.test.tsx +0 -702
package/src/v2/components/chat/__tests__/CopilotChatAssistantMessage.thumbs.test.tsx +0 -72
package/src/v2/components/chat/__tests__/CopilotChatCopyButton.clipboard.test.tsx +0 -241
package/src/v2/components/chat/__tests__/CopilotChatCssClasses.test.tsx +0 -107
package/src/v2/components/chat/__tests__/CopilotChatInput.slots.e2e.test.tsx +0 -929
package/src/v2/components/chat/__tests__/CopilotChatInput.test.tsx +0 -1567
package/src/v2/components/chat/__tests__/CopilotChatMessageView.slots.e2e.test.tsx +0 -1004
package/src/v2/components/chat/__tests__/CopilotChatMessageView.test.tsx +0 -279
package/src/v2/components/chat/__tests__/CopilotChatPerf.e2e.test.tsx +0 -296
package/src/v2/components/chat/__tests__/CopilotChatPropsRerender.e2e.test.tsx +0 -249
package/src/v2/components/chat/__tests__/CopilotChatSuggestionView.slots.e2e.test.tsx +0 -530
package/src/v2/components/chat/__tests__/CopilotChatToolRendering.e2e.test.tsx +0 -785
package/src/v2/components/chat/__tests__/CopilotChatToolRerenders.e2e.test.tsx +0 -2416
package/src/v2/components/chat/__tests__/CopilotChatUserMessage.slots.e2e.test.tsx +0 -621
package/src/v2/components/chat/__tests__/CopilotChatView.connectingGate.test.tsx +0 -56
package/src/v2/components/chat/__tests__/CopilotChatView.inputOverlay.test.tsx +0 -264
package/src/v2/components/chat/__tests__/CopilotChatView.onClick.e2e.test.tsx +0 -853
package/src/v2/components/chat/__tests__/CopilotChatView.pinToSend.test.tsx +0 -94
package/src/v2/components/chat/__tests__/CopilotChatView.slots.e2e.test.tsx +0 -1050
package/src/v2/components/chat/__tests__/CopilotModalHeader.slots.e2e.test.tsx +0 -484
package/src/v2/components/chat/__tests__/CopilotPopupView.slots.e2e.test.tsx +0 -612
package/src/v2/components/chat/__tests__/CopilotSidebarView.position.test.tsx +0 -159
package/src/v2/components/chat/__tests__/CopilotSidebarView.slots.e2e.test.tsx +0 -502
package/src/v2/components/chat/__tests__/MCPAppsActivityRenderer.e2e.test.tsx +0 -1068
package/src/v2/components/chat/__tests__/MCPAppsProxy.e2e.test.tsx +0 -589
package/src/v2/components/chat/__tests__/MCPAppsUiMessage.e2e.test.tsx +0 -403
package/src/v2/components/chat/__tests__/copilot-chat-throttle.test.tsx +0 -137
package/src/v2/components/chat/__tests__/normalize-auto-scroll.test.ts +0 -37
package/src/v2/components/chat/__tests__/setup.ts +0 -1
package/src/v2/components/chat/index.ts +0 -90
package/src/v2/components/chat/last-user-message-context.ts +0 -21
package/src/v2/components/chat/normalize-auto-scroll.ts +0 -17
package/src/v2/components/chat/scroll-element-context.ts +0 -13
package/src/v2/components/index.ts +0 -8
package/src/v2/components/intelligence-indicator/IntelligenceIndicator.tsx +0 -286
package/src/v2/components/intelligence-indicator/__tests__/IntelligenceIndicator.e2e.test.tsx +0 -464
package/src/v2/components/intelligence-indicator/index.ts +0 -2
package/src/v2/components/license-warning-banner.tsx +0 -217
package/src/v2/components/ui/button.tsx +0 -124
package/src/v2/components/ui/dropdown-menu.tsx +0 -258
package/src/v2/components/ui/tooltip.tsx +0 -60
package/src/v2/context.ts +0 -62
package/src/v2/headless.ts +0 -64
package/src/v2/hooks/__tests__/standard-schema-types.test.tsx +0 -152
package/src/v2/hooks/__tests__/standard-schema.test.tsx +0 -282
package/src/v2/hooks/__tests__/use-agent-context-timing.e2e.test.tsx +0 -140
package/src/v2/hooks/__tests__/use-agent-context.test.tsx +0 -401
package/src/v2/hooks/__tests__/use-agent-error-state.test.tsx +0 -44
package/src/v2/hooks/__tests__/use-agent-stability.test.tsx +0 -211
package/src/v2/hooks/__tests__/use-agent-throttle.test.tsx +0 -1029
package/src/v2/hooks/__tests__/use-agent.e2e.test.tsx +0 -159
package/src/v2/hooks/__tests__/use-attachments.test.tsx +0 -169
package/src/v2/hooks/__tests__/use-capabilities.test.tsx +0 -76
package/src/v2/hooks/__tests__/use-component.test.tsx +0 -126
package/src/v2/hooks/__tests__/use-configure-suggestions.e2e.test.tsx +0 -696
package/src/v2/hooks/__tests__/use-default-render-tool.test.tsx +0 -153
package/src/v2/hooks/__tests__/use-frontend-tool-available.test.tsx +0 -167
package/src/v2/hooks/__tests__/use-frontend-tool.e2e.test.tsx +0 -2148
package/src/v2/hooks/__tests__/use-human-in-the-loop.e2e.test.tsx +0 -1261
package/src/v2/hooks/__tests__/use-interrupt.test.tsx +0 -397
package/src/v2/hooks/__tests__/use-katex-styles.test.tsx +0 -56
package/src/v2/hooks/__tests__/use-keyboard-height.test.tsx +0 -192
package/src/v2/hooks/__tests__/use-pin-to-send.test.tsx +0 -219
package/src/v2/hooks/__tests__/use-render-custom-messages.test.tsx +0 -55
package/src/v2/hooks/__tests__/use-render-tool.test.tsx +0 -259
package/src/v2/hooks/__tests__/use-suggestions.e2e.test.tsx +0 -524
package/src/v2/hooks/__tests__/use-threads.test.tsx +0 -757
package/src/v2/hooks/__tests__/zod-regression.test.tsx +0 -311
package/src/v2/hooks/index.ts +0 -24
package/src/v2/hooks/use-agent-context.tsx +0 -45
package/src/v2/hooks/use-agent.tsx +0 -227
package/src/v2/hooks/use-attachments.tsx +0 -269
package/src/v2/hooks/use-capabilities.tsx +0 -25
package/src/v2/hooks/use-component.tsx +0 -91
package/src/v2/hooks/use-configure-suggestions.tsx +0 -236
package/src/v2/hooks/use-default-render-tool.tsx +0 -271
package/src/v2/hooks/use-frontend-tool.tsx +0 -46
package/src/v2/hooks/use-human-in-the-loop.tsx +0 -81
package/src/v2/hooks/use-interrupt.tsx +0 -305
package/src/v2/hooks/use-keyboard-height.tsx +0 -67
package/src/v2/hooks/use-pin-to-send.ts +0 -94
package/src/v2/hooks/use-render-activity-message.tsx +0 -72
package/src/v2/hooks/use-render-custom-messages.tsx +0 -93
package/src/v2/hooks/use-render-tool-call.tsx +0 -208
package/src/v2/hooks/use-render-tool.tsx +0 -184
package/src/v2/hooks/use-suggestions.tsx +0 -91
package/src/v2/hooks/use-threads.tsx +0 -325
package/src/v2/hooks/useKatexStyles.ts +0 -27
package/src/v2/index.css +0 -1
package/src/v2/index.ts +0 -27
package/src/v2/lib/__tests__/completePartialMarkdown.test.ts +0 -495
package/src/v2/lib/__tests__/processPartialHtml.test.ts +0 -112
package/src/v2/lib/__tests__/renderSlot.test.tsx +0 -588
package/src/v2/lib/__tests__/slots.test.ts +0 -56
package/src/v2/lib/processPartialHtml.ts +0 -45
package/src/v2/lib/react-core.ts +0 -156
package/src/v2/lib/slots.tsx +0 -184
package/src/v2/lib/transcription-client.ts +0 -184
package/src/v2/lib/utils.ts +0 -8
package/src/v2/providers/CopilotChatConfigurationProvider.tsx +0 -196
package/src/v2/providers/CopilotKitProvider.tsx +0 -800
package/src/v2/providers/SandboxFunctionsContext.ts +0 -10
package/src/v2/providers/__tests__/CopilotChatConfigurationProvider.test.tsx +0 -652
package/src/v2/providers/__tests__/CopilotKitProvider.license.test.tsx +0 -101
package/src/v2/providers/__tests__/CopilotKitProvider.onError.test.tsx +0 -69
package/src/v2/providers/__tests__/CopilotKitProvider.renderCustomMessages.e2e.test.tsx +0 -881
package/src/v2/providers/__tests__/CopilotKitProvider.sandboxFunctions.test.tsx +0 -198
package/src/v2/providers/__tests__/CopilotKitProvider.stability.test.tsx +0 -740
package/src/v2/providers/__tests__/CopilotKitProvider.test.tsx +0 -713
package/src/v2/providers/__tests__/CopilotKitProvider.wildcard.test.tsx +0 -294
package/src/v2/providers/index.ts +0 -21
package/src/v2/styles/globals.css +0 -349
package/src/v2/types/__tests__/defineToolCallRenderer.test.tsx +0 -525
package/src/v2/types/defineToolCallRenderer.ts +0 -68
package/src/v2/types/frontend-tool.ts +0 -8
package/src/v2/types/human-in-the-loop.ts +0 -33
package/src/v2/types/index.ts +0 -8
package/src/v2/types/interrupt.ts +0 -15
package/src/v2/types/react-activity-message-renderer.ts +0 -27
package/src/v2/types/react-custom-message-renderer.ts +0 -17
package/src/v2/types/react-tool-call-renderer.ts +0 -35
package/src/v2/types/sandbox-function.ts +0 -11
package/tsconfig.json +0 -8
package/tsdown.config.ts +0 -193
package/typedoc.json +0 -4
package/vitest.config.mjs +0 -31

package/skills/react-core/references/provider-setup.md ADDED Viewed

@@ -0,0 +1,326 @@
+# CopilotKit Provider Setup (React)
+Mount `CopilotKitProvider` once near the root of the React tree. Every
+CopilotKit hook (`useAgent`, `useFrontendTool`, `useRenderTool`, etc.) and
+every chat component (`CopilotChat`, `CopilotPopup`, `CopilotSidebar`) must
+be rendered inside this provider.
+All v2 imports use the `@copilotkit/react-core/v2` subpath. Imports from the
+package root are v1 and will not work with v2 hooks or components.
+## Setup
+### Next.js App Router (and any RSC-based framework)
+`@copilotkit/react-core/v2` is marked `"use client"`. You must mount the
+provider from a client component, not a server component. The cleanest
+pattern is a dedicated client-only `providers.tsx`.
+```tsx
+// app/providers.tsx
+"use client";
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-core/v2/styles.css";
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <CopilotKitProvider
+      runtimeUrl="/api/copilotkit"
+      credentials="include"
+      onError={({ code, error, context }) => {
+        console.error("[copilotkit]", code, error, context);
+      }}
+    >
+      {children}
+    </CopilotKitProvider>
+  );
+}
+```
+For auth headers that change over the session (rotating bearer tokens,
+refreshed cookies), see the "Stable headers for rotating auth tokens"
+pattern below. Avoid putting a `useMemo(() => ({ Authorization: ... }),
+[])` on the provider — an empty deps array captures the token at mount
+and never refreshes.
+```tsx
+// app/layout.tsx — server component
+import { Providers } from "./providers";
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+### Vite / React Router v7 / SPA
+```tsx
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-core/v2/styles.css";
+export function App({ children }: { children: React.ReactNode }) {
+  return (
+    <CopilotKitProvider runtimeUrl="/api/copilotkit">
+      {children}
+    </CopilotKitProvider>
+  );
+}
+```
+### SPA with CopilotKit Cloud (no self-hosted runtime)
+```tsx
+<CopilotKitProvider publicApiKey="ck_pub_..." />
+```
+`publicApiKey` is the canonical prop for running CopilotKit from a pure
+client bundle. `publicLicenseKey` is an alias that resolves to the same
+value (`publicApiKey ?? publicLicenseKey`) — accept in old code, but
+always write `publicApiKey` in new code.
+## Core Patterns
+### Stable headers for rotating auth tokens
+For tokens that change during the session, use the imperative setter instead
+of re-rendering the provider with a new `headers` prop.
+```tsx
+"use client";
+import { useCopilotKit } from "@copilotkit/react-core/v2";
+import { useEffect } from "react";
+export function AuthTokenSync({ token }: { token: string }) {
+  const { copilotkit } = useCopilotKit();
+  useEffect(() => {
+    copilotkit.setHeaders({ Authorization: `Bearer ${token}` });
+  }, [copilotkit, token]);
+  return null;
+}
+```
+### Global error handler
+`onError` fires for every `CopilotKitCoreErrorCode` emitted by core. Keeps
+UI from getting stuck in "connecting..." when the runtime URL is wrong or
+CORS is misconfigured.
+```tsx
+<CopilotKitProvider
+  runtimeUrl="/api/copilotkit"
+  onError={({ code, error, context }) => {
+    telemetry.capture({ code, message: error.message, context });
+  }}
+/>
+```
+### Sharing app properties with every run
+`properties` flows to the runtime on each agent run — useful for tenant IDs,
+feature flags, or anything the server needs.
+```tsx
+const properties = useMemo(
+  () => ({ tenantId: user.tenantId, locale: user.locale }),
+  [user.tenantId, user.locale],
+);
+<CopilotKitProvider runtimeUrl="/api/copilotkit" properties={properties} />;
+```
+## Common Mistakes
+### CRITICAL — Mounting the provider from a Server Component
+Wrong:
+```tsx
+// app/page.tsx (server component — no "use client")
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
+export default function Page() {
+  return (
+    <CopilotKitProvider runtimeUrl="/api/copilotkit">...</CopilotKitProvider>
+  );
+}
+```
+Correct:
+```tsx
+// app/providers.tsx
+"use client";
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <CopilotKitProvider runtimeUrl="/api/copilotkit">
+      {children}
+    </CopilotKitProvider>
+  );
+}
+// app/layout.tsx imports <Providers>.
+```
+`@copilotkit/react-core/v2` begins with `"use client"`. Importing it from a
+server component silently strips interactivity — the provider renders but
+none of the hooks wire up.
+Source: `packages/react-core/src/v2/index.ts:1`
+### CRITICAL — Using `agents__unsafe_dev_only` or `selfManagedAgents` in production
+Wrong:
+```tsx
+<CopilotKitProvider
+  agents__unsafe_dev_only={{
+    default: new BuiltInAgent({ apiKey: process.env.OPENAI_KEY! }),
+  }}
+/>
+// or the alias (same thing):
+<CopilotKitProvider
+  selfManagedAgents={{ default: new BuiltInAgent({ apiKey: "..." }) }}
+/>
+```
+Correct:
+```tsx
+// Route through a runtime that keeps secrets server-side:
+<CopilotKitProvider runtimeUrl="/api/copilotkit" />
+// Or for a pure SPA, use CopilotKit Cloud:
+<CopilotKitProvider publicApiKey="ck_pub_..." />
+```
+Both props are aliases for the same dev-only mechanism and ship any embedded
+credentials to the browser bundle. Never use either for production agents.
+Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:136-138,393`
+### HIGH — Inline object props rebuilt every render
+Wrong:
+```tsx
+<CopilotKitProvider
+  runtimeUrl="/api/copilotkit"
+  headers={{ Authorization: `Bearer ${token}` }}
+  properties={{ tenantId: user.tenantId }}
+/>
+```
+Correct:
+```tsx
+const headers = useMemo(() => ({ Authorization: `Bearer ${token}` }), [token]);
+const properties = useMemo(
+  () => ({ tenantId: user.tenantId }),
+  [user.tenantId],
+);
+<CopilotKitProvider
+  runtimeUrl="/api/copilotkit"
+  headers={headers}
+  properties={properties}
+/>;
+```
+New object identity on every render causes the provider to diff-churn
+internal state and may thrash tool/renderer registration. `useStableArrayProp`
+also logs a `console.error` when array-prop shape changes without
+memoization.
+Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:324-340,399-410`
+### HIGH — Missing `onError` leaves users stuck in "connecting..."
+Wrong:
+```tsx
+<CopilotKitProvider runtimeUrl="/api/copilotkit" />
+```
+Correct:
+```tsx
+<CopilotKitProvider
+  runtimeUrl="/api/copilotkit"
+  onError={({ code, error, context }) => {
+    telemetry.capture({ code, error, context });
+  }}
+/>
+```
+Without `onError`, connection failures (bad runtime URL, CORS, network) keep
+the provider in a provisional state with `ProxiedCopilotRuntimeAgent`
+instances that never resolve. The chat UI keeps showing "connecting..."
+forever and users never see the actual error.
+Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:638-660`
+### HIGH — Writing `publicLicenseKey` in new code
+Wrong:
+```tsx
+<CopilotKitProvider publicLicenseKey="ck_pub_..." />
+```
+Correct:
+```tsx
+<CopilotKitProvider publicApiKey="ck_pub_..." />
+```
+`publicLicenseKey` still works as an alias, but `publicApiKey` is the
+canonical name in v2. The provider resolves
+`publicApiKey ?? publicLicenseKey`. Always write the canonical form in
+new code.
+Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:122-128,391`
+### MEDIUM — Putting the provider below a layout that uses CopilotKit
+Wrong:
+```tsx
+<html>
+  <body>
+    <Header>{/* Header uses useFrontendTool internally */}</Header>
+    <CopilotKitProvider>{children}</CopilotKitProvider>
+  </body>
+</html>
+```
+Correct:
+```tsx
+<html>
+  <body>
+    <CopilotKitProvider>
+      <Header />
+      {children}
+    </CopilotKitProvider>
+  </body>
+</html>
+```
+Any component that calls `useCopilotKit`, `useFrontendTool`, `useAgent`, or
+any other CopilotKit hook must be a descendant of `CopilotKitProvider`.
+Placing the provider beside or below a consumer throws at mount.
+Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (context)

package/skills/react-core/references/rendering-activity-messages.md ADDED Viewed

@@ -0,0 +1,207 @@
+# CopilotKit Rendering Activity Messages (React)
+This skill builds on `copilotkit/provider-setup`. Activity-message
+renderers are registered as entries in the `renderActivityMessages` array
+prop on `CopilotKitProvider` and resolved at render time by
+`useRenderActivityMessage` (consumed internally by chat components).
+User renderers are placed first in the array so they override the built-in
+`MCPAppsActivityType` and `OpenGenerativeUIActivityType` renderers for the
+same `activityType`.
+Resolver order:
+1. `(activityType, agentId)` match
+2. `(activityType, unscoped)` match
+3. `'*'` wildcard
+4. `null`
+## Setup
+```tsx
+"use client";
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
+import type { ReactActivityMessageRenderer } from "@copilotkit/react-core/v2";
+import { z } from "zod";
+import { useMemo } from "react";
+import { Card, CardContent } from "@/components/ui/card";
+import { Progress } from "@/components/ui/progress";
+const progressRenderer: ReactActivityMessageRenderer<{
+  percent: number;
+  label: string;
+}> = {
+  activityType: "progress",
+  content: z.object({ percent: z.number().min(0).max(1), label: z.string() }),
+  render: ({ content }) => (
+    <Card>
+      <CardContent>
+        <div>{content.label}</div>
+        <Progress value={content.percent * 100} />
+      </CardContent>
+    </Card>
+  ),
+};
+export function Providers({ children }: { children: React.ReactNode }) {
+  const renderers = useMemo(() => [progressRenderer], []);
+  return (
+    <CopilotKitProvider
+      runtimeUrl="/api/copilotkit"
+      renderActivityMessages={renderers}
+    >
+      {children}
+    </CopilotKitProvider>
+  );
+}
+```
+## Core Patterns
+### Agent-scoped renderer
+```tsx
+const researchProgress: ReactActivityMessageRenderer<{ step: string }> = {
+  activityType: "research-step",
+  agentId: "research",
+  content: z.object({ step: z.string() }),
+  render: ({ content }) => <ResearchStepBadge step={content.step} />,
+};
+```
+### Override a built-in (MCP Apps)
+Place your renderer for the same `activityType` — user renderers are
+evaluated before built-ins.
+```tsx
+import { MCPAppsActivityType } from "@copilotkit/react-core/v2";
+const customMcpRenderer: ReactActivityMessageRenderer<unknown> = {
+  activityType: MCPAppsActivityType, // "mcp-apps" — must match the exported constant
+  content: z.unknown(),
+  render: ({ content, message }) => <CustomMCPCard payload={content} />,
+};
+```
+### Using the hook directly (custom chat surface)
+```tsx
+import { useRenderActivityMessage } from "@copilotkit/react-core/v2";
+import type { ActivityMessage } from "@ag-ui/core";
+export function ActivityList({ messages }: { messages: ActivityMessage[] }) {
+  const { renderActivityMessage } = useRenderActivityMessage();
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>{renderActivityMessage(m)}</div>
+      ))}
+    </div>
+  );
+}
+```
+## Common Mistakes
+### HIGH — Incompatible content schema
+Wrong:
+```tsx
+// Renderer expects `pct`
+const r: ReactActivityMessageRenderer<{ pct: number }> = {
+  activityType: "progress",
+  content: z.object({ pct: z.number() }),
+  render: ({ content }) => <Bar value={content.pct} />,
+};
+// But the server emits { percent: 0.5 } — mismatched field name
+```
+Correct:
+```tsx
+const r: ReactActivityMessageRenderer<{ percent: number }> = {
+  activityType: "progress",
+  content: z.object({ percent: z.number() }),
+  render: ({ content }) => <Bar value={content.percent} />,
+};
+```
+`safeParse` is called on every incoming activity message. Mismatched
+schemas return `null` with only a `console.warn("Failed to parse content
+for activity message …")` — the UI renders nothing and the failure is
+silent unless you read the console.
+Source: `packages/react-core/src/v2/hooks/use-render-activity-message.tsx:44-50`
+### MEDIUM — Side effects in `render`
+Wrong:
+```tsx
+render: ({ content }) => {
+  trackEvent(content); // fires on every re-render
+  return <Badge>{content.label}</Badge>;
+};
+```
+Wrong (Rules of Hooks violation):
+```tsx
+render: ({ content }) => {
+  // `render` is invoked as a plain function by the resolver — NOT as a
+  // React component — so calling hooks directly inside it is illegal.
+  useEffect(() => trackEvent(content), [content]);
+  return <Badge>{content.label}</Badge>;
+};
+```
+Correct:
+```tsx
+function TrackedBadge({ content }: { content: { label: string } }) {
+  useEffect(() => {
+    trackEvent(content);
+  }, [content]);
+  return <Badge>{content.label}</Badge>;
+}
+// In the renderer:
+render: ({ content }) => <TrackedBadge content={content} />;
+```
+Activity-message renderers re-render on every message-list tick. Side
+effects in the render body fire repeatedly. Hooks cannot be called
+directly inside `render` because the resolver invokes it as a plain
+function; hoist the effect into a wrapper component that React mounts as
+a real element.
+Source: `packages/react-core/src/v2/hooks/use-render-activity-message.tsx`
+### MEDIUM — Building the `renderActivityMessages` array inline
+Wrong:
+```tsx
+<CopilotKitProvider
+  runtimeUrl="/api/copilotkit"
+  renderActivityMessages={[progressRenderer, customMcpRenderer]}
+/>
+```
+Correct:
+```tsx
+const renderers = useMemo(() => [progressRenderer, customMcpRenderer], []);
+<CopilotKitProvider
+  runtimeUrl="/api/copilotkit"
+  renderActivityMessages={renderers}
+/>;
+```
+The provider uses `useStableArrayProp` and console-errors when a new array
+identity appears every render. Memoize or hoist the array to module
+scope.
+Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (useStableArrayProp)