docs(react-core): fix CR findings in v2 skills

- useAgent: isRunning is not on the return type; sourced from agent
- addContext: agentId is not accepted; remove "per-agent escape hatch"
- provider-setup: publicApiKey is canonical, publicLicenseKey is alias
- chat-components/attachments: add missing copilotkit.runAgent call
- attachments: map Attachment[] to InputContent[] before spreading
- rendering-activity-messages: fix Rules-of-Hooks violation in "Correct" example
- custom-message-renderers: guard runId.slice against missing-run-id fallback
- human-in-the-loop: abort-on-unmount effect was capturing stale isRunning
- client-side-tools: Skeleton imports from @/components/ui/skeleton
- threads: CopilotKitIntelligence ships on @copilotkit/runtime/v2 with apiUrl/wsUrl/apiKey/organizationId config
- provider-setup: remove stale-token useMemo lead example
- package.json: add per-condition types to exports map

Author: jpr5

packages/react-core/package.json

@@ -43,12 +43,24 @@
   "jsdelivr": "./dist/index.umd.js",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./v2": {
-      "import": "./dist/v2/index.mjs",
-      "require": "./dist/v2/index.cjs"
+      "import": {
+        "types": "./dist/v2/index.d.mts",
+        "default": "./dist/v2/index.mjs"
+      },
+      "require": {
+        "types": "./dist/v2/index.d.cts",
+        "default": "./dist/v2/index.cjs"
+      }
     },
     "./package.json": "./package.json",
     "./v2/styles.css": "./dist/v2/index.css"

packages/react-core/skills/agent-access/SKILL.md

@@ -5,9 +5,11 @@ description: >
   push JSON-serializable shared state via useAgentContext({ description,
   value }). Covers per-thread clone WeakMap, UseAgentUpdate filter,
   ProxiedCopilotRuntimeAgent provisional agent, agent.addMessage /
-  setState / abortRun. useAgentContext has no agentId parameter — context
-  is intentionally global. For rare per-agent scoping, use
-  copilotkit.addContext({ agentId }).
+  setState / abortRun. useAgent returns { agent }; run status comes from
+  agent.isRunning (subscribe via UseAgentUpdate.OnRunStatusChanged).
+  useAgentContext has no agentId parameter and context is always global —
+  the core addContext API also ignores any agentId field, so per-agent
+  context scoping is not supported.
 type: framework
 framework: react
 library: copilotkit
@@ -49,7 +51,7 @@ export function ChatDriver({
   route: string;
   userId: string;
 }) {
-  const { agent, isRunning } = useAgent({
+  const { agent } = useAgent({
     agentId: "default",
     threadId: "main",
     updates: [
@@ -64,7 +66,8 @@ export function ChatDriver({
 
   return (
     <div>
-      {isRunning ? "…thinking" : "idle"} — {agent.messages.length} messages
+      {agent.isRunning ? "…thinking" : "idle"} — {agent.messages.length}{" "}
+      messages
     </div>
   );
 }
@@ -87,12 +90,17 @@ async function ask(text: string) {
 ### Subscribe only to run-status to reduce re-renders
 
 ```tsx
-const { isRunning } = useAgent({
+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
@@ -103,31 +111,6 @@ const value = useMemo(
 useAgentContext({ description: "user cart + route", value });
 ```
 
-### Per-agent context (rare — escape hatch)
-
-`useAgentContext` is intentionally global. For the rare case where a
-specific agent should see a different context, use the imperative API.
-
-```tsx
-import { useCopilotKit } from "@copilotkit/react-core/v2";
-import { useEffect, useMemo } from "react";
-
-const { copilotkit } = useCopilotKit();
-const value = useMemo(
-  () => ({ papers: researchState.papers }),
-  [researchState.papers],
-);
-
-useEffect(() => {
-  const id = copilotkit.addContext({
-    description: "paper list",
-    value: JSON.stringify(value),
-    agentId: "research",
-  });
-  return () => copilotkit.removeContext(id);
-}, [copilotkit, value]);
-```
-
 ### Abort the run
 
 ```tsx
@@ -265,34 +248,37 @@ 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` to accept `agentId`
+### 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
-const { copilotkit } = useCopilotKit();
-useEffect(() => {
-  const id = copilotkit.addContext({
-    description: "paper list",
-    value: JSON.stringify(value),
-    agentId: "research",
-  });
-  return () => copilotkit.removeContext(id);
-}, [copilotkit, value]);
+// 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.
 ```
 
-`useAgentContext` is intentionally global by design — context is "state of
-the world" and flows to every agent. Per-agent scoping is the escape hatch
-via `copilotkit.addContext({ agentId })`. Most of the time you want the
-ambient (global) version.
+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)
+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
 

packages/react-core/skills/attachments/SKILL.md

@@ -56,10 +56,16 @@ export function ChatPanel() {
 
 ```tsx
 "use client";
-import { useAttachments, useAgent } from "@copilotkit/react-core/v2";
+import {
+  useAttachments,
+  useAgent,
+  useCopilotKit,
+} from "@copilotkit/react-core/v2";
+import type { InputContent } from "@ag-ui/core";
 
 export function CustomChatInput() {
   const { agent } = useAgent({ agentId: "default" });
+  const { copilotkit } = useCopilotKit();
   const {
     attachments,
     containerRef,
@@ -86,13 +92,30 @@ export function CustomChatInput() {
         </button>
       ))}
       <button
-        onClick={() => {
+        onClick={async () => {
           const ready = consumeAttachments();
+          // `ready` is Attachment[] — map each to an AG-UI InputContent part
+          // before spreading into the message content array.
+          const contentParts: InputContent[] = [
+            { type: "text", text: "See attachments." },
+            ...ready.map(
+              (att) =>
+                ({
+                  type: att.type,
+                  source: att.source,
+                  metadata: {
+                    ...(att.filename ? { filename: att.filename } : {}),
+                    ...att.metadata,
+                  },
+                }) as InputContent,
+            ),
+          ];
           agent.addMessage({
             id: crypto.randomUUID(),
             role: "user",
-            content: [{ type: "text", text: "See attachments." }, ...ready],
+            content: contentParts,
           });
+          await copilotkit.runAgent({ agent });
         }}
       >
         Send
@@ -102,6 +125,13 @@ export function CustomChatInput() {
 }
 ```
 
+`consumeAttachments()` returns the `Attachment[]` queue — each entry has
+`{ id, type, source, filename, status, metadata }` and is NOT a valid
+AG-UI content part. Map each attachment to an `InputContent` shape
+(`{ type, source, metadata }`) before spreading into a message's `content`
+array. See `packages/react-core/src/v2/components/chat/CopilotChat.tsx:247-268`
+for the canonical transform.
+
 ## Core Patterns
 
 ### Custom upload backend (S3 / presigned URL)

packages/react-core/skills/chat-components/SKILL.md

@@ -76,21 +76,24 @@ import {
   CopilotChatInput,
   CopilotChatMessageView,
   useAgent,
+  useCopilotKit,
 } from "@copilotkit/react-core/v2";
 
 export function HeadlessChat() {
-  const { agent, isRunning } = useAgent({ agentId: "default" });
+  const { agent } = useAgent({ agentId: "default" });
+  const { copilotkit } = useCopilotKit();
 
   return (
     <CopilotChatView
       messages={agent.messages}
-      isRunning={isRunning}
-      onSubmitInput={(text) => {
+      isRunning={agent.isRunning}
+      onSubmitInput={async (text) => {
         agent.addMessage({
           id: crypto.randomUUID(),
           role: "user",
           content: text,
         });
+        await copilotkit.runAgent({ agent });
       }}
     >
       <CopilotChatMessageView />

packages/react-core/skills/client-side-tools/SKILL.md

@@ -167,7 +167,8 @@ Correct:
 
 ```tsx
 // First check package.json for shadcn / @mui/* / @chakra-ui/* / antd / @mantine/*, then:
-import { Card, CardContent, Skeleton } from "@/components/ui/card";
+import { Card, CardContent } from "@/components/ui/card";
+import { Skeleton } from "@/components/ui/skeleton";
 
 useFrontendTool({
   name: "show",

packages/react-core/skills/custom-message-renderers/SKILL.md

@@ -118,9 +118,15 @@ const ResearchNotes: ReactCustomMessageRenderer = {
 const DebugBefore: ReactCustomMessageRenderer = {
   render: ({ message, position, messageIndex, runId }) => {
     if (position !== "before" || message.role !== "user") return null;
+    // `runId` is always a string, but it falls back to a synthetic
+    // "missing-run-id:<messageId>" value before a run is registered.
+    // Slice only when it looks like a real id, otherwise show a dash.
+    const shortId = runId?.startsWith("missing-run-id:")
+      ? "—"
+      : (runId?.slice(0, 6) ?? "—");
     return (
       <div style={{ opacity: 0.5, fontSize: 11 }}>
-        #{messageIndex} · run {runId.slice(0, 6)}
+        #{messageIndex} · run {shortId}
       </div>
     );
   },

packages/react-core/skills/human-in-the-loop/SKILL.md

@@ -119,20 +119,37 @@ render: ({ status, args, respond }) => {
 ### Abort the run on unmount so threads unlock
 
 ```tsx
-import { useAgent } from "@copilotkit/react-core/v2";
-import { useEffect } from "react";
+import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";
+import { useEffect, useRef } from "react";
 
 function HITLHost() {
-  const { agent, isRunning } = useAgent({ agentId: "default" });
+  const { agent } = useAgent({
+    agentId: "default",
+    updates: [UseAgentUpdate.OnRunStatusChanged],
+  });
+  // Track isRunning in a ref so the unmount cleanup reads the latest value
+  // without re-firing on every transition.
+  const runningRef = useRef(false);
+  useEffect(() => {
+    runningRef.current = agent.isRunning;
+  }, [agent.isRunning]);
+
   useEffect(() => {
     return () => {
-      if (isRunning) agent.abortRun();
+      if (runningRef.current) agent.abortRun();
     };
-  }, [agent, isRunning]);
+  }, [agent]);
+
   return <DeleteConfirmHITL />;
 }
 ```
 
+`useAgent` returns `{ agent }` only — run status lives on `agent.isRunning`.
+Depending the cleanup effect directly on `agent.isRunning` would fire the
+cleanup on every status flip (not just unmount), aborting active runs.
+The ref pattern captures the latest value while the cleanup runs only
+when the host component truly unmounts.
+
 ### Collect structured user input mid-run
 
 ```tsx
@@ -276,12 +293,19 @@ Correct:
 
 ```tsx
 // Keep the HITL prompt at a layout level that persists across route changes, OR abort on unmount:
-const { agent, isRunning } = useAgent({ agentId: "default" });
+const { agent } = useAgent({
+  agentId: "default",
+  updates: [UseAgentUpdate.OnRunStatusChanged],
+});
+const runningRef = useRef(false);
+useEffect(() => {
+  runningRef.current = agent.isRunning;
+}, [agent.isRunning]);
 useEffect(
   () => () => {
-    if (isRunning) agent.abortRun();
+    if (runningRef.current) agent.abortRun();
   },
-  [agent, isRunning],
+  [agent],
 );
 ```