@copilotkit/react-core 1.57.3 → 1.58.0

package/skills/react-core/references/attachments.md

@@ -0,0 +1,291 @@
+# CopilotKit Attachments (React)
+
+This skill builds on `copilotkit/provider-setup` and
+`copilotkit/chat-components`. `useAttachments` is exposed both as an opt-in
+prop on `<CopilotChat>` and as a direct hook for custom chat surfaces.
+
+## Setup
+
+### Easiest: turn attachments on via `<CopilotChat>`
+
+```tsx
+"use client";
+import { CopilotChat } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-core/v2/styles.css";
+
+export function ChatPanel() {
+  return (
+    <CopilotChat
+      agentId="default"
+      attachments={{
+        enabled: true,
+        accept: "image/*",
+        maxSize: 10 * 1024 * 1024, // 10 MB
+        onUploadFailed: ({ reason, file, message }) => {
+          console.warn(`[attachments] ${reason}: ${file.name} — ${message}`);
+        },
+      }}
+    />
+  );
+}
+```
+
+### Direct hook usage for custom surfaces
+
+```tsx
+"use client";
+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,
+    fileInputRef,
+    handleFileUpload,
+    handleDragOver,
+    handleDragLeave,
+    handleDrop,
+    removeAttachment,
+    consumeAttachments,
+  } = useAttachments({ config: { enabled: true, accept: "*/*" } });
+
+  return (
+    <div
+      ref={containerRef}
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+    >
+      <input type="file" ref={fileInputRef} onChange={handleFileUpload} />
+      {attachments.map((a) => (
+        <button key={a.id} onClick={() => removeAttachment(a.id)}>
+          {a.filename} ({a.status})
+        </button>
+      ))}
+      <button
+        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: contentParts,
+          });
+          await copilotkit.runAgent({ agent });
+        }}
+      >
+        Send
+      </button>
+    </div>
+  );
+}
+```
+
+`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)
+
+`onUpload` replaces the default base64-inline strategy. Return an
+`Attachment.source` describing where the file lives.
+
+```tsx
+useAttachments({
+  config: {
+    enabled: true,
+    accept: "image/*,application/pdf",
+    maxSize: 50 * 1024 * 1024,
+    onUpload: async (file) => {
+      const { url } = await fetch("/api/upload", {
+        method: "POST",
+        body: file,
+      }).then((r) => r.json());
+      return { type: "url", value: url, mimeType: file.type };
+    },
+    onUploadFailed: ({ reason, file, message }) => {
+      toast.error(`${file.name}: ${message}`);
+    },
+  },
+});
+```
+
+### Feedback on failed uploads
+
+```tsx
+useAttachments({
+  config: {
+    enabled: true,
+    maxSize: 5 * 1024 * 1024,
+    onUploadFailed: ({ reason, file, message }) => {
+      // reason: "file-too-large" | "invalid-type" | "upload-failed"
+      toast.error(message);
+    },
+  },
+});
+```
+
+## Common Mistakes
+
+### HIGH — Forgetting to call `consumeAttachments` on submit
+
+Wrong:
+
+```tsx
+const { attachments } = useAttachments({ config: { enabled: true } });
+const onSubmit = () => {
+  sendMessage({ text, attachments });
+  // attachments queue never cleared — sticks around for the next message
+};
+```
+
+Correct:
+
+```tsx
+const { consumeAttachments } = useAttachments({ config: { enabled: true } });
+const onSubmit = () => {
+  const ready = consumeAttachments();
+  sendMessage({ text, attachments: ready });
+};
+```
+
+`consumeAttachments()` returns ready attachments AND drains the internal
+queue. If you submit without calling it, attachments stay in state and
+accompany every subsequent message.
+
+Source: `packages/react-core/src/v2/hooks/use-attachments.tsx:40-46`
+
+### HIGH — Passing `maxSize` in KB or MB
+
+Wrong:
+
+```tsx
+useAttachments({ config: { enabled: true, maxSize: 10 } });
+// 10 bytes! Effectively blocks every file.
+```
+
+Correct:
+
+```tsx
+useAttachments({
+  config: { enabled: true, maxSize: 10 * 1024 * 1024 }, // 10 MB
+});
+```
+
+`maxSize` is bytes. The default is `20 * 1024 * 1024` (20 MB). Passing a
+small number without the multiplier silently rejects every file via
+`onUploadFailed({ reason: "file-too-large" })`.
+
+Source: `packages/react-core/src/v2/hooks/use-attachments.tsx:73-74`
+
+### HIGH — Missing `containerRef` on the paste-scope element
+
+Wrong:
+
+```tsx
+const { enabled } = useAttachments({ config: { enabled: true } });
+return (
+  <div>
+    <input type="text" />
+  </div>
+); // no containerRef attached
+```
+
+Correct:
+
+```tsx
+const { containerRef, handleDragOver, handleDrop } = useAttachments({
+  config: { enabled: true },
+});
+return (
+  <div ref={containerRef} onDragOver={handleDragOver} onDrop={handleDrop}>
+    <input type="text" />
+  </div>
+);
+```
+
+Clipboard paste is scoped to the element `containerRef` points at. Without
+attaching the ref, `Ctrl+V` / `Cmd+V` never reaches the paste handler and
+users silently can't paste images from screenshots.
+
+Source: `packages/react-core/src/v2/hooks/use-attachments.tsx:207-239`
+
+### MEDIUM — Using `imageUploadsEnabled` on `<CopilotChat>`
+
+Wrong:
+
+```tsx
+<CopilotChat imageUploadsEnabled />
+```
+
+Correct:
+
+```tsx
+<CopilotChat
+  attachments={{
+    enabled: true,
+    accept: "image/*",
+    maxSize: 5 * 1024 * 1024,
+  }}
+/>
+```
+
+`imageUploadsEnabled` was the v1 flag. v2 replaces it with the `attachments`
+config object, which is powered by `useAttachments` internally and supports
+any MIME type, not only images.
+
+Source: `docs/content/docs/(root)/migration-guides/migrate-attachments.mdx`
+
+### MEDIUM — Ignoring `onUploadFailed`
+
+Wrong:
+
+```tsx
+useAttachments({ config: { enabled: true } });
+// Rejected files silently disappear. User has no idea why.
+```
+
+Correct:
+
+```tsx
+useAttachments({
+  config: {
+    enabled: true,
+    onUploadFailed: ({ reason, file, message }) => {
+      toast.error(message);
+    },
+  },
+});
+```
+
+Size violations, MIME mismatches, and `onUpload` throws all drop the file
+from the queue with no UI feedback unless `onUploadFailed` is wired.
+
+Source: `packages/react-core/src/v2/hooks/use-attachments.tsx:79-157`

package/skills/react-core/references/capabilities.md

@@ -0,0 +1,138 @@
+# CopilotKit Capabilities (React)
+
+This skill builds on `copilotkit/agent-access`. `useCapabilities` internally
+calls `useAgent` and reads the `capabilities` field populated from the
+runtime `/info` response.
+
+`AgentCapabilities` is from `@ag-ui/core`. The hook is synchronous — there
+is no loading state, but the value is `undefined` until the handshake
+completes.
+
+## Setup
+
+```tsx
+"use client";
+import { useCapabilities } from "@copilotkit/react-core/v2";
+
+export function VoiceButton() {
+  const caps = useCapabilities(); // defaults to DEFAULT_AGENT_ID
+
+  // Handshake pending — show a placeholder
+  if (caps === undefined) return <div className="skeleton h-8 w-8" />;
+
+  // Handshake complete — feature-gate
+  if (!caps.transcription) return null;
+
+  return <button>Record</button>;
+}
+```
+
+## Core Patterns
+
+### Scope to a specific agent
+
+```tsx
+const caps = useCapabilities("research");
+```
+
+### Feature-gate tools UI
+
+```tsx
+const caps = useCapabilities("default");
+
+if (caps === undefined) return <ToolsSkeleton />;
+if (caps.tools?.supported === false) return null;
+return <ToolsPanel />;
+```
+
+### Narrow optional fields defensively
+
+`AgentCapabilities` is a partial declaration — fields may be absent when
+the agent opts not to declare them.
+
+```tsx
+const caps = useCapabilities();
+const maxTokens = caps?.maxOutputTokens ?? "unknown";
+```
+
+## Common Mistakes
+
+### HIGH — Treating `undefined` as "no capabilities"
+
+Wrong:
+
+```tsx
+function VoiceButton() {
+  const caps = useCapabilities();
+  if (!caps?.transcription) return null; // hides button forever while handshake pending
+  return <button>Record</button>;
+}
+```
+
+Correct:
+
+```tsx
+function VoiceButton() {
+  const caps = useCapabilities();
+  if (caps === undefined) return <div className="skeleton h-8 w-8" />;
+  if (!caps.transcription) return null;
+  return <button>Record</button>;
+}
+```
+
+`useCapabilities` returns `undefined` until the runtime `/info` handshake
+completes. Treating `undefined` the same as `{ transcription: false }`
+hides features that should be visible post-handshake.
+
+Source: `packages/react-core/src/v2/hooks/use-capabilities.tsx:7-9`
+
+### MEDIUM — Non-null assertion on optional fields
+
+Wrong:
+
+```tsx
+const caps = useCapabilities();
+return <div>Max tokens: {caps!.maxOutputTokens}</div>;
+// Crashes if agent didn't declare capabilities, or didn't declare maxOutputTokens.
+```
+
+Correct:
+
+```tsx
+const caps = useCapabilities();
+return <div>Max tokens: {caps?.maxOutputTokens ?? "unknown"}</div>;
+```
+
+`AgentCapabilities` is a partial declaration. Agents opt in to each
+capability, so every field is optional. Narrow before deref.
+
+Source: `packages/react-core/src/v2/hooks/use-capabilities.tsx:20-22`
+
+### MEDIUM — Expecting deep merge from server-side `capabilities`
+
+Wrong:
+
+```ts
+// Server:
+new BuiltInAgent({
+  // ...
+  capabilities: { tools: { supported: true } },
+});
+// Client expects caps.tools.clientProvided to still be set by the default
+```
+
+Correct:
+
+```ts
+// Server — provide full category:
+new BuiltInAgent({
+  // ...
+  capabilities: { tools: { supported: true, clientProvided: true } },
+});
+```
+
+BuiltInAgent shallow-merges capabilities at the category level — providing
+`tools: {...}` replaces the whole category, not just the specified fields.
+The client then sees exactly what was declared.
+
+Source: `packages/runtime/src/agent/index.ts:821-829,883-887`

package/skills/react-core/references/chat-components.md

@@ -0,0 +1,221 @@
+# CopilotKit Chat Components (React)
+
+This skill builds on `copilotkit/provider-setup`. Read it first — every
+chat component must be inside `CopilotKitProvider`.
+
+All chat components live on `@copilotkit/react-core/v2`. The legacy
+`@copilotkit/react-ui` package is v1-only; its `/v2` subpath is a CSS-only
+import.
+
+## Setup
+
+```tsx
+"use client";
+import { CopilotChat } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-core/v2/styles.css";
+
+export function ChatPanel() {
+  return <CopilotChat agentId="default" />;
+}
+```
+
+`<CopilotChat>` manages messages, input, streaming, attachments, and
+suggestions internally via `useAgent`. You do not pass `messages` or
+`isRunning` — they are managed for you.
+
+## Core Patterns
+
+### Floating popup
+
+```tsx
+import { CopilotPopup } from "@copilotkit/react-core/v2";
+
+<CopilotPopup agentId="default" isModalDefaultOpen={false} />;
+```
+
+### Persistent sidebar
+
+```tsx
+import { CopilotSidebar } from "@copilotkit/react-core/v2";
+
+<CopilotSidebar agentId="default">
+  <MainAppContent />
+</CopilotSidebar>;
+```
+
+### Headless composition with slot primitives
+
+Use `CopilotChatView` plus the individual slot components when you need
+full control over messages, input, or layout. This is the path when you
+want to manage `messages`/`isRunning` yourself.
+
+```tsx
+import {
+  CopilotChatView,
+  CopilotChatInput,
+  CopilotChatMessageView,
+  useAgent,
+  useCopilotKit,
+} from "@copilotkit/react-core/v2";
+
+export function HeadlessChat() {
+  const { agent } = useAgent({ agentId: "default" });
+  const { copilotkit } = useCopilotKit();
+
+  return (
+    <CopilotChatView
+      messages={agent.messages}
+      isRunning={agent.isRunning}
+      onSubmitInput={async (text) => {
+        agent.addMessage({
+          id: crypto.randomUUID(),
+          role: "user",
+          content: text,
+        });
+        await copilotkit.runAgent({ agent });
+      }}
+    >
+      <CopilotChatMessageView />
+      <CopilotChatInput />
+    </CopilotChatView>
+  );
+}
+```
+
+### Custom labels
+
+```tsx
+<CopilotChat
+  agentId="default"
+  labels={{
+    chatInputPlaceholder: "Ask about the data…",
+    thinking: "Analyzing…",
+  }}
+/>
+```
+
+## Common Mistakes
+
+### CRITICAL — Importing `CopilotPanel`
+
+Wrong:
+
+```tsx
+import { CopilotPanel } from "@copilotkit/react-core/v2";
+```
+
+Correct:
+
+```tsx
+import {
+  CopilotChat,
+  CopilotPopup,
+  CopilotSidebar,
+  CopilotChatView,
+} from "@copilotkit/react-core/v2";
+```
+
+`CopilotPanel` does not exist in v2 (or v1). This is a common hallucination.
+The four chat surfaces are `CopilotChat`, `CopilotPopup`, `CopilotSidebar`,
+and the headless `CopilotChatView`.
+
+Source: `packages/react-core/src/v2/components/chat/index.ts` (no `CopilotPanel` export)
+
+### CRITICAL — Importing chat components from `@copilotkit/react-ui` in v2
+
+Wrong:
+
+```tsx
+import { CopilotPopup } from "@copilotkit/react-ui";
+import "@copilotkit/react-ui/styles.css";
+```
+
+Correct:
+
+```tsx
+import { CopilotPopup } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-core/v2/styles.css";
+```
+
+`@copilotkit/react-ui` is v1 only. The v2 subpath of `react-ui` is a
+CSS-only import — the components are not there. All v2 chat components ship
+from `@copilotkit/react-core/v2`.
+
+Source: `packages/react-ui/src/v2/index.ts` (CSS-only); v2 migration guide
+
+### HIGH — Passing `messages` or `isRunning` to `<CopilotChat>`
+
+Wrong:
+
+```tsx
+<CopilotChat agentId="default" messages={myMessages} isRunning={busy} />
+```
+
+Correct:
+
+```tsx
+// CopilotChat manages messages and isRunning internally.
+<CopilotChat agentId="default" />
+
+// For manual control, drop down to headless CopilotChatView:
+<CopilotChatView
+  messages={myMessages}
+  isRunning={busy}
+  onSubmitInput={handleSubmit}
+>
+  <CopilotChatMessageView />
+  <CopilotChatInput />
+</CopilotChatView>
+```
+
+`CopilotChatProps` explicitly `Omit`s `messages` and `isRunning` — passing
+them is a TypeScript error, and `<CopilotChat>` always reads from its
+internal `useAgent` call.
+
+Source: `packages/react-core/src/v2/components/chat/CopilotChat.tsx:37-52`
+
+### MEDIUM — Two `<CopilotChat>` with the same `agentId` + `threadId`
+
+Wrong:
+
+```tsx
+<CopilotChat agentId="research" threadId="t1" />
+<CopilotChat agentId="research" threadId="t1" />
+```
+
+Correct:
+
+```tsx
+// Either use distinct threadIds...
+<CopilotChat agentId="research" threadId="panel-a" />
+<CopilotChat agentId="research" threadId="panel-b" />
+
+// ...or mount only one <CopilotChat> instance per agent/thread.
+```
+
+Both components resolve to the same per-thread clone (cached in a
+module-level WeakMap) and submit duplicate messages. See `agent-access` for
+the clone semantics.
+
+Source: `packages/react-core/src/v2/hooks/use-agent.tsx:78-119`
+
+### MEDIUM — Missing the v2 CSS import
+
+Wrong:
+
+```tsx
+import { CopilotChat } from "@copilotkit/react-core/v2";
+// …no styles imported
+```
+
+Correct:
+
+```tsx
+import { CopilotChat } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-core/v2/styles.css";
+```
+
+The chat components ship unstyled without the v2 stylesheet. Import it once
+at the root of the app or in the same file that sets up the provider.
+
+Source: `packages/react-core/src/v2/index.ts:3` (imports `./index.css`)