@copilotkit/react-core 1.70.3 → 1.71.1

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,229 +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 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`)

package/skills/react-core/references/client-side-tools.md

@@ -1,358 +0,0 @@
-# CopilotKit Client-Side Tools (React)
-
-This skill builds on `copilotkit/provider-setup`. Tools registered via
-`useFrontendTool` execute in the browser and are exposed to the agent over
-AG-UI.
-
-Hook signature:
-
-```ts
-useFrontendTool<T>(tool: ReactFrontendTool<T>, deps?: ReadonlyArray<unknown>);
-```
-
-The hook re-registers when `tool.name`, `tool.available`, or any entry in
-`deps` changes. Closures inside `handler` capture React state at
-registration time — pass `deps` when the handler references state.
-
-## UI-kit detection rule
-
-Before writing any `render` JSX, check the consumer's `package.json` for a
-UI kit and reuse its primitives:
-
-- `components/ui/*` (shadcn)
-- `@mui/material` (MUI)
-- `@chakra-ui/react` (Chakra)
-- `antd` (Ant Design)
-- `@mantine/core` (Mantine)
-
-Only write raw JSX if no kit is present.
-
-## Setup
-
-```tsx
-"use client";
-import { useFrontendTool } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-
-export function SearchToolHost() {
-  useFrontendTool({
-    name: "searchDocs",
-    description: "Search the in-app documentation",
-    parameters: z.object({ query: z.string() }),
-    handler: async ({ query }, { signal }) => {
-      const r = await fetch(`/api/search?q=${encodeURIComponent(query)}`, {
-        signal,
-      });
-      return (await r.json()).results.join("\n");
-    },
-  });
-  return null;
-}
-```
-
-`zod` is a hard peer dependency — install it alongside `@copilotkit/react-core`.
-
-## Core Patterns
-
-### Handler with React state + deps
-
-```tsx
-const [cart, setCart] = useState<string[]>([]);
-
-useFrontendTool(
-  {
-    name: "addItem",
-    parameters: z.object({ id: z.string() }),
-    handler: async ({ id }) => {
-      setCart((c) => [...c, id]);
-    },
-  },
-  [setCart],
-);
-```
-
-### Forward `signal` into fetch (so `stopAgent` cancels in-flight calls)
-
-```tsx
-useFrontendTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  handler: async ({ q }, { signal }) => {
-    const r = await fetch(`/search?q=${q}`, { signal });
-    return r.text();
-  },
-});
-```
-
-### Render progress UI for a tool (reuse the consumer's UI kit)
-
-```tsx
-// Consumer has shadcn → use Card + Skeleton
-import { Card, CardContent } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
-
-useFrontendTool({
-  name: "show",
-  parameters: z.object({ id: z.string() }),
-  handler: async ({ id }) => fetchItem(id),
-  render: ({ status, parameters, result }) => (
-    <Card>
-      {status === "inProgress" ? (
-        <Skeleton className="h-24 w-full" />
-      ) : (
-        <CardContent>{result}</CardContent>
-      )}
-    </Card>
-  ),
-});
-```
-
-### Programmatic invocation with string follow-up
-
-`copilotkit.runTool` accepts `followUp: boolean | "generate" | string`.
-A string is injected as a synthetic user message before the agent runs.
-
-```tsx
-import { useCopilotKit } from "@copilotkit/react-core/v2";
-
-const { copilotkit } = useCopilotKit();
-
-await copilotkit.runTool({
-  name: "searchDocs",
-  parameters: { query: "zod" },
-  followUp: "Summarize these results in 3 bullets", // inject as user message, run agent
-});
-```
-
-## Common Mistakes
-
-### CRITICAL — Writing JSX from scratch for `render` when the app has a UI kit
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "show",
-  parameters: z.object({ id: z.string() }),
-  handler,
-  render: ({ status }) => <div style={{ padding: 12 }}>…</div>,
-});
-```
-
-Correct:
-
-```tsx
-// First check package.json for shadcn / @mui/* / @chakra-ui/* / antd / @mantine/*, then:
-import { Card, CardContent } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
-
-useFrontendTool({
-  name: "show",
-  parameters: z.object({ id: z.string() }),
-  handler,
-  render: ({ status, result }) => (
-    <Card>
-      {status === "inProgress" ? (
-        <Skeleton />
-      ) : (
-        <CardContent>{result}</CardContent>
-      )}
-    </Card>
-  ),
-});
-```
-
-Consumers almost always have a UI kit. Raw JSX produces unbranded output
-and skips the accessibility patterns their existing primitives encode.
-
-Source: maintainer interview (Phase 2c)
-
-### HIGH — Stale closure inside `handler`
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "addItem",
-  parameters: z.object({ id: z.string() }),
-  handler: async ({ id }) => {
-    addTo(cart, id); // `cart` is captured at registration — goes stale
-  },
-});
-```
-
-Correct:
-
-```tsx
-useFrontendTool(
-  {
-    name: "addItem",
-    parameters: z.object({ id: z.string() }),
-    handler: async ({ id }) => {
-      addTo(cart, id);
-    },
-  },
-  [cart],
-);
-```
-
-`useFrontendTool` only re-registers when `name`, `available`, or `deps`
-change. Without `deps`, closures over React state freeze at first mount.
-
-Source: `packages/react-core/src/v2/hooks/use-frontend-tool.tsx:45`
-
-### HIGH — Ignoring `signal` in async handlers
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  handler: async ({ q }) => (await fetch(`/search?q=${q}`)).text(),
-});
-```
-
-Correct:
-
-```tsx
-useFrontendTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  handler: async ({ q }, { signal }) =>
-    (await fetch(`/search?q=${q}`, { signal })).text(),
-});
-```
-
-`stopAgent` / `agent.abortRun` abort via `AbortSignal`. A handler that
-doesn't forward `signal` keeps fetching after cancel, racing the next turn.
-
-Source: `packages/core/src/types.ts:24-30`
-
-### HIGH — Assuming `followUp` defaults to `false`
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "logAnalyticsEvent",
-  parameters: z.object({ name: z.string() }),
-  handler: async ({ name }) => {
-    analytics.track(name);
-  },
-  // followUp omitted → defaults to TRUE. Agent re-runs after every analytics call.
-});
-```
-
-Correct:
-
-```tsx
-useFrontendTool({
-  name: "logAnalyticsEvent",
-  parameters: z.object({ name: z.string() }),
-  handler: async ({ name }) => {
-    analytics.track(name);
-  },
-  followUp: false, // side-effect tool — don't re-invoke the agent
-});
-```
-
-For agent-invoked tools, run-handler checks `tool?.followUp !== false` — so
-`undefined` AND `true` both fire a follow-up `runAgent`. Only explicit
-`false` suppresses it. Pure side-effect tools must opt out or they loop.
-
-Source: `packages/core/src/core/run-handler.ts:607`
-
-### HIGH — Missing `zod` peer dependency
-
-Wrong:
-
-```bash
-pnpm install @copilotkit/react-core
-# zod missing — the CopilotKit provider fails to load
-```
-
-Correct:
-
-```bash
-pnpm install @copilotkit/react-core zod
-```
-
-`zod` is a hard peer of `@copilotkit/react-core` and is imported at
-provider module scope. Without it the provider module throws on load.
-
-Source: `packages/react-core/package.json` (peerDependencies)
-
-### MEDIUM — Duplicate tool name across hooks
-
-Wrong:
-
-```tsx
-// ComponentA
-useFrontendTool({ name: "save", parameters, handler: saveA });
-// ComponentB mounted in same tree:
-useFrontendTool({ name: "save", parameters, handler: saveB });
-// console.warn: "Tool 'save' already exists … Overriding"
-```
-
-Correct:
-
-```tsx
-useFrontendTool({
-  name: "save",
-  agentId: "research",
-  parameters,
-  handler: saveA,
-});
-useFrontendTool({
-  name: "save",
-  agentId: "coding",
-  parameters,
-  handler: saveB,
-});
-```
-
-Tool names must be globally unique per `agentId`. Second mount warns and
-replaces the first. Scope with `agentId` when multiple agents need their
-own "save" handler.
-
-Source: `packages/react-core/src/v2/hooks/use-frontend-tool.tsx:17-22`
-
-### MEDIUM — Passing `"generate"` or a string to `useFrontendTool`'s `followUp`
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "searchDocs",
-  parameters: z.object({ q: z.string() }),
-  handler,
-  followUp: "Summarize these results" as any, // silently truthy on registered tools
-});
-```
-
-Correct:
-
-```tsx
-// Registered tools — boolean only:
-useFrontendTool({
-  name: "searchDocs",
-  parameters: z.object({ q: z.string() }),
-  handler,
-  followUp: true,
-});
-
-// For string follow-ups, call runTool programmatically:
-const { copilotkit } = useCopilotKit();
-await copilotkit.runTool({
-  name: "searchDocs",
-  parameters: { q: "zod" },
-  followUp: "Summarize these results", // injects user message, runs agent
-});
-```
-
-`FrontendTool.followUp` is typed `boolean`. Strings are silently truthy
-(treated as `true`). The `"generate"` and custom-string modes only work
-on `copilotkit.runTool({ followUp })`.
-
-Source: `packages/core/src/types.ts:39`; `packages/core/src/core/run-handler.ts:47,763,848-863`