@copilotkit/react-core 1.71.0 → 1.71.1

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

@@ -1,311 +0,0 @@
-# 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}`);
-    },
-  },
-});
-```
-
-### Upload concurrency
-
-Multi-file selections upload one file at a time by default, and the whole
-selection is queued as `status: "uploading"` right away. Raise
-`maxConcurrentUploads` to run several together — the rest then start as slots
-free up, `Infinity` lifts the limit, and `onUpload` may be called concurrently,
-so above `1` it must not assume the previous file finished. The pool is per hook,
-not per call, so a paste landing mid-upload shares the same slots instead of
-opening its own.
-
-```tsx
-useAttachments({
-  config: {
-    enabled: true,
-    maxConcurrentUploads: 6,
-    onUpload: async (file) => uploadToStorage(file),
-  },
-});
-```
-
-### 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

@@ -1,138 +0,0 @@
-# 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

@@ -1,246 +0,0 @@
-# CopilotKit Chat Components (React)
-
-This skill builds on `copilotkit/provider-setup`. Read it first — every
-chat component must be inside the `CopilotKit` provider (from
-`@copilotkit/react-core/v2`).
-
-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" defaultOpen={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,
-  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}
-      onSubmitMessage={async (text) => {
-        agent.addMessage({
-          id: crypto.randomUUID(),
-          role: "user",
-          content: text,
-        });
-        await copilotkit.runAgent({ agent });
-      }}
-    >
-      {({ messageView, input }) => (
-        <>
-          {messageView}
-          {input}
-        </>
-      )}
-    </CopilotChatView>
-  );
-}
-```
-
-### Custom labels
-
-```tsx
-<CopilotChat
-  agentId="default"
-  labels={{
-    chatInputPlaceholder: "Ask about the data…",
-    welcomeMessageText: "What would you like to analyze?",
-  }}
-/>
-```
-
-## 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. Its `children`
-// is a render prop that receives the bound slot elements:
-<CopilotChatView
-  messages={myMessages}
-  isRunning={busy}
-  onSubmitMessage={handleSubmit}
->
-  {({ messageView, input }) => (
-    <>
-      {messageView}
-      {input}
-    </>
-  )}
-</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 the same shared agent. `CopilotChat` binds with
-`useAgent({ agentId })` — the shared-instance shape — and then writes
-`agent.threadId` onto it. There is no per-thread clone, so two instances
-naming one `(agentId, threadId)` pair drive a single instance:
-
-- Each runs its own connect effect against that instance, so the same thread is
-  connected twice.
-- Each assigns `agent.abortController`, so the later mount replaces the
-  earlier one and unmounting either can abort the other's in-flight request.
-- Each calls `setMessages` on it, so whichever connect resolves last wins.
-
-The bookkeeping that would prevent this (`lastConnectedThreadId`,
-`activeConnectCountRef`) is per component, so it does not coordinate across
-two instances.
-
-See `agent-access` for the two shapes `useAgent` admits and which one owns a
-private instance.
-
-Source: `packages/react-core/src/v2/components/chat/CopilotChat.tsx:138-141`
-(the shared bind), `:395` (the threadId write), `:421-423` (the shared
-abortController), `:429` (the connect call), `:261-266` (the per-instance
-bookkeeping)
-
-### 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`)