@copilotkit/react-core 1.57.3 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/react-core",
-  "version": "1.57.3",
+  "version": "1.58.0",
   "private": false,
   "keywords": [
     "ai",
@@ -12,6 +12,7 @@
     "nextjs",
     "nodejs",
     "react",
+    "tanstack-intent",
     "textarea"
   ],
   "homepage": "https://github.com/CopilotKit/CopilotKit",
@@ -20,6 +21,10 @@
     "type": "git",
     "url": "https://github.com/CopilotKit/CopilotKit.git"
   },
+  "files": [
+    "dist",
+    "skills"
+  ],
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -27,13 +32,6 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
-  "typesVersions": {
-    "*": {
-      "v2": [
-        "./dist/v2/index.d.cts"
-      ]
-    }
-  },
   "unpkg": "./dist/index.umd.js",
   "jsdelivr": "./dist/index.umd.js",
   "exports": {
@@ -81,16 +79,17 @@
     "untruncate-json": "^0.0.1",
     "use-stick-to-bottom": "^1.1.1",
     "zod-to-json-schema": "^3.24.5",
-    "@copilotkit/a2ui-renderer": "1.57.3",
-    "@copilotkit/core": "1.57.3",
-    "@copilotkit/runtime-client-gql": "1.57.3",
-    "@copilotkit/shared": "1.57.3",
-    "@copilotkit/web-inspector": "1.57.3"
+    "@copilotkit/a2ui-renderer": "1.58.0",
+    "@copilotkit/runtime-client-gql": "1.58.0",
+    "@copilotkit/shared": "1.58.0",
+    "@copilotkit/core": "1.58.0",
+    "@copilotkit/web-inspector": "1.58.0"
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.1.11",
     "@tailwindcss/postcss": "^4.1.11",
     "@tailwindcss/typography": "^0.5.16",
+    "@tanstack/intent": "^0.0.29",
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.3.0",
     "@testing-library/react-hooks": "^8.0.1",

package/skills/react-core/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: react-core
+description: >
+  @copilotkit/react-core — mount CopilotKitProvider in a Next.js App Router / React Router
+  v7 / TanStack Start / SPA app, drop in CopilotChat/CopilotPopup/CopilotSidebar (v2 chat
+  components ship from react-core/v2 — NOT react-ui, which is CSS-only in v2), access and
+  subscribe to agents with useAgent / useAgentContext / useCapabilities, switch between
+  multiple agents, manage durable Intelligence threads with useThreads, register
+  browser-side tools via useFrontendTool, render tool calls with useRenderTool /
+  useComponent / useDefaultRenderTool, gate execution with useHumanInTheLoop, wire file
+  attachments with useAttachments, configure suggestion pills, and register activity- and
+  custom-message renderers. publicLicenseKey is canonical (publicApiKey is deprecated
+  alias). Load the reference under references/ that matches your task.
+type: framework
+library: copilotkit
+library_version: "1.56.2"
+requires:
+  - copilotkit/runtime
+sources:
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/providers/CopilotKitProvider.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/index.ts"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/components/chat/index.ts"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/components/chat/CopilotChat.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/components/chat/CopilotChatView.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/components/CopilotKitInspector.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-agent.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-agent-context.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-capabilities.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-threads.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-frontend-tool.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-render-tool.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-render-tool-call.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-default-render-tool.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-component.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-human-in-the-loop.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-attachments.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-configure-suggestions.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-suggestions.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-render-activity-message.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-render-custom-messages.tsx"
+  - "CopilotKit/CopilotKit:packages/react-core/src/v2/lib/slots.tsx"
+  - "CopilotKit/CopilotKit:packages/core/src/core/core.ts"
+  - "CopilotKit/CopilotKit:packages/core/src/core/agent-registry.ts"
+  - "CopilotKit/CopilotKit:packages/core/src/core/run-handler.ts"
+  - "CopilotKit/CopilotKit:packages/core/src/types.ts"
+---
+
+# CopilotKit React Core
+
+`@copilotkit/react-core` is the React frontend half of CopilotKit: it mounts a provider,
+speaks AG-UI over SSE to a runtime (or directly to CopilotKit Cloud in SPA mode), and
+exposes hooks for every interaction surface.
+
+This SKILL.md is the **index**. Read the reference under `references/` that matches
+your task — do not try to absorb the whole package from this file.
+
+## Mental model — three shells you compose
+
+1. **Provider shell** — `CopilotKitProvider` at or near the root (inside `"use client"` for
+   Next.js App Router). Carries `runtimeUrl` (or `publicLicenseKey` for SPA), `headers`,
+   `credentials`, `properties`, `onError`, `debug`, `showDevConsole`.
+2. **Chat shell** — `CopilotChat` / `CopilotPopup` / `CopilotSidebar` or a composed
+   `CopilotChatView` + slot primitives (`CopilotChatInput`, `CopilotChatMessageView`, etc.).
+   All chat components ship from `@copilotkit/react-core/v2`. **`CopilotPanel` does not
+   exist** — it's a common hallucination.
+3. **Hook shell** — inside any component under the provider, call `useAgent`,
+   `useFrontendTool`, `useRenderTool`, etc. Every hook takes optional `{ agentId }` for
+   agent-scoped registration.
+
+## When to load which reference
+
+| Task                                                                                                      | Reference                                                                               |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Mount `CopilotKitProvider`, pick `runtimeUrl` vs `publicLicenseKey`, RSC boundary rules                   | `references/provider-setup.md`                                                          |
+| Drop in `CopilotChat` / `CopilotPopup` / `CopilotSidebar`, compose `CopilotChatView` with slot primitives | `references/chat-components.md`                                                         |
+| File / image attachments via `useAttachments` — drag-drop, click, paste, custom upload                    | `references/attachments.md`                                                             |
+| Client-side debug tooling — `showDevConsole`, `debug` prop, lazy-loaded web inspector                     | `references/debug-mode.md`                                                              |
+| Read / subscribe to an agent (`useAgent`) and push global context (`useAgentContext`)                     | `references/agent-access.md`                                                            |
+| Feature-gate UI on declared agent capabilities (`useCapabilities`)                                        | `references/capabilities.md`                                                            |
+| Build a multi-agent UI (per-panel `useAgent`, agent-scoped tools, key-remount pattern)                    | `references/switching-agents.md` (+ `switching-agents-recipes.md` for concrete layouts) |
+| List / rename / archive / delete durable Intelligence threads (`useThreads`)                              | `references/threads.md` (**requires runtime Intelligence mode**)                        |
+| Register browser-side tools (`useFrontendTool`)                                                           | `references/client-side-tools.md`                                                       |
+| Render per-tool UI (`useRenderTool`, `useComponent`, `useDefaultRenderTool`, `useRenderToolCall`)         | `references/rendering-tool-calls.md`                                                    |
+| Gate tool execution behind user approval (`useHumanInTheLoop`)                                            | `references/human-in-the-loop.md`                                                       |
+| Configure dynamic or static suggestion pills (`useConfigureSuggestions`, `useSuggestions`)                | `references/suggestions.md`                                                             |
+| Render non-chat activity messages (`useRenderActivityMessage`)                                            | `references/rendering-activity-messages.md`                                             |
+| Inject custom UI before/after specific messages (`useRenderCustomMessages`)                               | `references/custom-message-renderers.md`                                                |
+
+## Invariants and gotchas (load-once, before any reference)
+
+- `publicLicenseKey` is canonical. `publicApiKey` is a **deprecated alias** — expect it in legacy code.
+- `agents__unsafe_dev_only` and `selfManagedAgents` are dev-only aliases of each other. **Not production-safe.** See `packages/a2ui-renderer` or the `spa-without-runtime` lifecycle skill for the supported SPA path.
+- `CopilotPanel` does not exist. v2 chat components ship from `react-core/v2` — **not** `react-ui` (v2 `react-ui` is CSS-only).
+- No `useAgents()` hook exists. Discover agents via `copilotkit.subscribe({ onAgentsChanged })`.
+- `useRenderToolCall` is a **resolver** (for custom chat surfaces), **not** a registration hook. Register with `useRenderTool` / `useComponent` / `useDefaultRenderTool`.
+- UI-kit detection rule — any `render` or tool-call UI MUST reuse the consumer's shadcn / MUI / Chakra / Ant / Mantine primitives before writing raw JSX. This applies across `client-side-tools`, `rendering-tool-calls`, and `human-in-the-loop`.
+- Tool-call `status` values are camelCase: `'inProgress' | 'executing' | 'complete'`. In-progress args are `Partial<T>`.
+- `useHumanInTheLoop` synthesized handler **MUST** call `respond(result)` (including reject paths), otherwise the agent run hangs. `respond` is `undefined` outside `Executing` status. Unmounting mid-Executing abandons the run.
+- `useThreads` errors with `'Runtime URL is not configured'` outside Intelligence mode.
+- `v1 → v2` migration renames: `useCopilotAction` → `useFrontendTool` + `useHumanInTheLoop`; `imageUploadsEnabled` → `attachments`. See the `v1-to-v2-migration` lifecycle skill.
+
+## Reading order for a first-time reader
+
+1. `provider-setup` — mount the provider.
+2. `chat-components` — wire a chat surface.
+3. `agent-access` — talk to agents.
+4. `client-side-tools` + `rendering-tool-calls` — add tool-call UI.
+5. Anything else as your feature requires.

package/skills/react-core/references/agent-access.md

@@ -0,0 +1,288 @@
+# CopilotKit Agent Access (React)
+
+This skill builds on `copilotkit/provider-setup`. `useAgent` reads from the
+same registry the provider populates from `/info`.
+
+Two complementary surfaces:
+
+- `useAgent` — imperative access to an agent instance, subscribe to
+  messages/state/run-status changes.
+- `useAgentContext` — declarative push of app state to every agent run.
+
+## Setup
+
+```tsx
+"use client";
+import {
+  useAgent,
+  useAgentContext,
+  UseAgentUpdate,
+} from "@copilotkit/react-core/v2";
+import { useMemo } from "react";
+
+export function ChatDriver({
+  route,
+  userId,
+}: {
+  route: string;
+  userId: string;
+}) {
+  const { agent } = useAgent({
+    agentId: "default",
+    threadId: "main",
+    updates: [
+      UseAgentUpdate.OnMessagesChanged,
+      UseAgentUpdate.OnRunStatusChanged,
+    ],
+    throttleMs: 100,
+  });
+
+  const context = useMemo(() => ({ route, userId }), [route, userId]);
+  useAgentContext({ description: "app context", value: context });
+
+  return (
+    <div>
+      {agent.isRunning ? "…thinking" : "idle"} — {agent.messages.length}{" "}
+      messages
+    </div>
+  );
+}
+```
+
+## Core Patterns
+
+### Send a message and stream the response
+
+```tsx
+const { agent } = useAgent({ agentId: "default" });
+const { copilotkit } = useCopilotKit();
+
+async function ask(text: string) {
+  agent.addMessage({ id: crypto.randomUUID(), role: "user", content: text });
+  await copilotkit.runAgent({ agent });
+}
+```
+
+### Subscribe only to run-status to reduce re-renders
+
+```tsx
+const { agent } = useAgent({
+  agentId: "default",
+  updates: [UseAgentUpdate.OnRunStatusChanged],
+});
+const isRunning = agent.isRunning;
+```
+
+`useAgent` returns `{ agent }` only; `isRunning` lives on the agent
+itself. Subscribing to `OnRunStatusChanged` forces a re-render when the
+value flips, so reading `agent.isRunning` stays live.
+
+### Share app state with every agent run (global)
+
+```tsx
+const value = useMemo(
+  () => ({ cartItems: cart.items, currentRoute: router.pathname }),
+  [cart.items, router.pathname],
+);
+useAgentContext({ description: "user cart + route", value });
+```
+
+### Abort the run
+
+```tsx
+const { agent } = useAgent({ agentId: "default" });
+<button onClick={() => agent.abortRun()}>Stop</button>;
+```
+
+## Common Mistakes
+
+### CRITICAL — Custom `AbstractAgent.clone()` that returns `this`
+
+Wrong:
+
+```tsx
+class MyAgent extends AbstractAgent {
+  clone() {
+    return this; // wrong — same instance is reused across threads
+  }
+}
+```
+
+Correct:
+
+```tsx
+class MyAgent extends AbstractAgent {
+  clone() {
+    const next = new MyAgent(this.config);
+    next.state = { ...this.state };
+    return next;
+  }
+}
+```
+
+`useAgent` calls `source.clone()` to build a per-thread clone and throws
+`clone() must return a new, independent object` if the clone is the same
+instance. This guards per-thread isolation.
+
+Source: `packages/react-core/src/v2/hooks/use-agent.tsx:58-69`
+
+### HIGH — Mutating `agent.messages` directly
+
+Wrong:
+
+```tsx
+agent.messages.push({ id, role: "user", content: "hi" });
+```
+
+Correct:
+
+```tsx
+agent.addMessage({ id: crypto.randomUUID(), role: "user", content: "hi" });
+// or:
+agent.setMessages([...agent.messages, newMessage]);
+```
+
+AG-UI fires `onMessagesChanged` subscribers via `addMessage` /
+`setMessages`. Direct array mutation bypasses subscribers and the UI never
+re-renders.
+
+Source: `packages/react-core/src/v2/hooks/use-agent.tsx` (throughout)
+
+### HIGH — Registering non-serializable values via `useAgentContext`
+
+Wrong:
+
+```tsx
+useAgentContext({
+  description: "user",
+  value: {
+    name: "Alice",
+    lastLogin: new Date(),
+    onLogout: () => logout(), // dropped silently
+  },
+});
+```
+
+Correct:
+
+```tsx
+useAgentContext({
+  description: "user",
+  value: { name: "Alice", lastLogin: new Date().toISOString() },
+});
+```
+
+`useAgentContext` runs the value through `JSON.stringify`. Functions are
+dropped, `Date` coerces to an ISO string (which the agent has to parse), and
+circular references throw.
+
+Source: `packages/react-core/src/v2/hooks/use-agent-context.tsx:30-35`
+
+### MEDIUM — Expecting lifecycle callbacks to be throttled
+
+Wrong:
+
+```tsx
+useAgent({
+  agentId: "default",
+  throttleMs: 300,
+  // expecting onRunInitialized / onRunFinalized / onRunFailed to also be throttled
+});
+```
+
+Correct:
+
+```tsx
+// Only OnMessagesChanged / OnStateChanged / OnRunStatusChanged are throttled.
+// Lifecycle callbacks always fire immediately — handle them synchronously.
+useAgent({ agentId: "default", throttleMs: 300 });
+```
+
+`throttleMs` only applies to the three subscribed updates enumerated in
+`UseAgentUpdate`. Lifecycle callbacks bypass the throttler.
+
+Source: `packages/react-core/src/v2/hooks/use-agent.tsx:36-48`
+
+### MEDIUM — Unstable context value identity
+
+Wrong:
+
+```tsx
+useAgentContext({ description: "cart", value: { items: cart.items } });
+```
+
+Correct:
+
+```tsx
+const value = useMemo(() => ({ items: cart.items }), [cart.items]);
+useAgentContext({ description: "cart", value });
+```
+
+A fresh object literal on every render invalidates the `useMemo` inside
+`useAgentContext` that serializes the value, causing constant
+remove/re-add churn in the core context store.
+
+Source: `packages/react-core/src/v2/hooks/use-agent-context.tsx:30-35`
+
+### MEDIUM — Expecting `useAgentContext` or `copilotkit.addContext` to scope context per agent
+
+Wrong:
+
+```tsx
+useAgentContext({ agentId: "research", description: "paper list", value });
+// or the imperative form:
+copilotkit.addContext({
+  description: "paper list",
+  value: JSON.stringify(value),
+  agentId: "research",
+});
+```
+
+Correct:
+
+```tsx
+// Context is global — every agent run sees every registered entry.
+useAgentContext({ description: "paper list", value });
+
+// When only one agent should key off a value, branch inside its prompt
+// or tool logic instead of trying to scope the context entry.
+```
+
+Context is intentionally global and there is no per-agent scoping hook.
+`useAgentContext` has no `agentId` parameter, and `copilotkit.addContext`
+destructures only `{ description, value }` — any `agentId` passed is
+silently dropped. Treat context as "state of the world" that every agent
+sees.
+
+Source: `packages/react-core/src/v2/hooks/use-agent-context.tsx` (no `agentId` parameter); `packages/core/src/core/context-store.ts:26-31`
+
+### MEDIUM — Two components using the same `(agentId, threadId)` expecting isolation
+
+Wrong:
+
+```tsx
+function A() {
+  const { agent } = useAgent({ agentId: "default", threadId: "t1" });
+}
+function B() {
+  const { agent } = useAgent({ agentId: "default", threadId: "t1" });
+}
+```
+
+Correct:
+
+```tsx
+function A() {
+  useAgent({ agentId: "default", threadId: "a" });
+}
+function B() {
+  useAgent({ agentId: "default", threadId: "b" });
+}
+```
+
+Per-thread clones are cached in a module-level WeakMap keyed by
+`(registryAgent, threadId)`. Two consumers of the same `(agentId,
+threadId)` observe the same state. Give each surface a distinct `threadId`
+when isolation is intentional.
+
+Source: `packages/react-core/src/v2/hooks/use-agent.tsx:78-119`