@copilotkit/react-core 1.70.3 → 1.71.1

package/skills/react-core/references/rendering-tool-calls.md

@@ -1,319 +0,0 @@
-# CopilotKit Rendering Tool Calls (React)
-
-This skill builds on `copilotkit/provider-setup` and
-`copilotkit/client-side-tools`.
-
-Four hooks, distinct roles:
-
-| Hook                   | Role                                                              |
-| ---------------------- | ----------------------------------------------------------------- |
-| `useRenderTool`        | Primary registration hook for a named tool's progress/result UI   |
-| `useComponent`         | Register a NEW render-only tool (agent calls it just to render)   |
-| `useDefaultRenderTool` | Sanctioned wildcard fallback for tools without a dedicated render |
-| `useRenderToolCall`    | Resolver — returns a function. For custom chat surfaces only      |
-
-Status is camelCase: `"inProgress" | "executing" | "complete"`. The
-`RenderToolProps` discriminated union narrows `parameters` per state.
-
-## UI-kit detection rule
-
-Before writing raw JSX, check the consumer's `package.json` for shadcn /
-MUI / Chakra / Ant / Mantine and reuse those primitives.
-
-## Setup
-
-```tsx
-"use client";
-import { useRenderTool } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-import { Card, CardContent } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
-
-export function SearchRenderer() {
-  useRenderTool({
-    name: "searchDocs",
-    parameters: z.object({ query: z.string() }),
-    render: ({ status, parameters, result }) => {
-      if (status === "inProgress") return <Skeleton className="h-16 w-full" />;
-      if (status === "executing") {
-        return (
-          <Card>
-            <CardContent>Searching "{parameters.query}"…</CardContent>
-          </Card>
-        );
-      }
-      return (
-        <Card>
-          <CardContent>{result}</CardContent>
-        </Card>
-      );
-    },
-  });
-  return null;
-}
-```
-
-## Core Patterns
-
-### Wildcard fallback with the built-in card
-
-```tsx
-import { useDefaultRenderTool } from "@copilotkit/react-core/v2";
-
-useDefaultRenderTool(); // renders the built-in expandable tool-call card
-```
-
-### Custom wildcard fallback
-
-```tsx
-import { useDefaultRenderTool } from "@copilotkit/react-core/v2";
-
-useDefaultRenderTool({
-  render: ({ name, status, parameters, result }) => {
-    // parameters is unknown — narrow by tool name
-    if (name === "search") {
-      const args = parameters as { q: string };
-      return <SearchCard q={args.q} status={status} result={result} />;
-    }
-    return <GenericCard name={name} status={status} />;
-  },
-});
-```
-
-### Render-only tool (the agent's only reason to call it is to render)
-
-```tsx
-import { useComponent } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-
-useComponent({
-  name: "productCard",
-  parameters: z.object({ productId: z.string() }),
-  render: ({ productId }) => <ProductCard id={productId} />,
-});
-// `useComponent` registers a NEW tool called "productCard".
-// The agent calls it to render; there is no handler to run.
-```
-
-### Custom chat surface (resolver hook)
-
-`useRenderToolCall` is for building your own message list, NOT for
-registering renderers.
-
-```tsx
-import { useRenderToolCall } from "@copilotkit/react-core/v2";
-import { useAgent } from "@copilotkit/react-core/v2";
-
-export function CustomToolList() {
-  const { agent } = useAgent({ agentId: "default" });
-  const renderToolCall = useRenderToolCall();
-
-  const toolCalls = agent.messages.flatMap((m) =>
-    "toolCalls" in m ? (m.toolCalls ?? []) : [],
-  );
-
-  return (
-    <>
-      {toolCalls.map((tc) => (
-        <div key={tc.id}>{renderToolCall({ toolCall: tc })}</div>
-      ))}
-    </>
-  );
-}
-```
-
-## Common Mistakes
-
-### CRITICAL — Using `useRenderToolCall` for registration
-
-Wrong:
-
-```tsx
-useRenderToolCall({
-  name: "search",
-  args: z.object({ q: z.string() }),
-  render: ({ status, args }) => <Card>…</Card>,
-});
-```
-
-Correct:
-
-```tsx
-useRenderTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  render: ({ status, parameters }) => <Card>…</Card>,
-});
-```
-
-`useRenderToolCall` takes no arguments — it returns a resolver function for
-custom chat surfaces. Passing config to it does nothing. `useRenderTool` is
-the registration hook.
-
-Source: `packages/react-core/src/v2/hooks/index.ts:2,7`;
-`packages/react-core/src/v2/hooks/use-render-tool.tsx:37-40`
-
-### CRITICAL — Using hyphenated `"in-progress"` status
-
-Wrong:
-
-```tsx
-render: ({ status, parameters, result }) => {
-  if (status === "in-progress") return <Spinner />;
-  if (status === "executing") return <RunningCard args={parameters} />;
-  return <ResultCard result={result} />;
-};
-```
-
-Correct:
-
-```tsx
-render: ({ status, parameters, result }) => {
-  if (status === "inProgress") return <Spinner />;
-  if (status === "executing") return <RunningCard args={parameters} />;
-  return <ResultCard result={result} />;
-};
-```
-
-Real status values are camelCase: `"inProgress" | "executing" | "complete"`.
-Hyphenated branches never match — users see no progress UI and the fallback
-path fires.
-
-Source: `packages/react-core/src/v2/hooks/use-render-tool.tsx:8-35`
-
-### CRITICAL — Writing JSX from scratch when the app has a UI kit
-
-Wrong:
-
-```tsx
-useRenderTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  render: () => <div className="my-badge">…</div>,
-});
-```
-
-Correct:
-
-```tsx
-import { Badge } from "@/components/ui/badge";
-
-useRenderTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  render: () => <Badge variant="secondary">…</Badge>,
-});
-```
-
-Check consumer `package.json` for shadcn / MUI / Chakra / Ant / Mantine
-first. Raw JSX ignores their design system.
-
-Source: maintainer interview (Phase 2c)
-
-### HIGH — Dereferencing required fields from `Partial<T>` during `inProgress`
-
-Wrong:
-
-```tsx
-render: ({ status, parameters }) => (
-  <span>{parameters.user.id.toUpperCase()}</span>
-);
-// `parameters` is Partial<T> during inProgress — `parameters.user` may be undefined.
-```
-
-Correct:
-
-```tsx
-render: ({ status, parameters }) =>
-  status === "inProgress" ? (
-    <Skeleton />
-  ) : (
-    <span>{parameters.user.id.toUpperCase()}</span>
-  );
-```
-
-During streaming, `RenderToolInProgressProps` has
-`parameters: Partial<InferSchemaOutput<S>>`. Fields are `undefined` until
-the stream completes. Narrow with `status === "inProgress"` first.
-
-Source: `packages/react-core/src/v2/hooks/use-render-tool.tsx:8-14`
-
-### HIGH — Using `useComponent` to decorate an existing tool
-
-Wrong:
-
-```tsx
-useFrontendTool({ name: "search", parameters, handler });
-useComponent({
-  name: "search", // creates a SECOND tool named "search" — collision
-  parameters: z.object({ q: z.string() }),
-  render: ({ q }) => <SearchCard q={q} />,
-});
-```
-
-Correct:
-
-```tsx
-useFrontendTool({ name: "search", parameters, handler });
-useRenderTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  render: ({ status, parameters, result }) => {
-    if (status === "inProgress") return <Skeleton />;
-    if (status === "executing") return <div>Searching {parameters.q}…</div>;
-    return <div>{result}</div>;
-  },
-});
-
-// useComponent is only for render-only tools the agent invokes:
-useComponent({
-  name: "productCard",
-  parameters: z.object({ productId: z.string() }),
-  render: ({ productId }) => <ProductCard id={productId} />,
-});
-```
-
-`useComponent` synthesizes a NEW tool whose only job is to render —
-description is auto-prefixed with "Use this tool to display the …
-component". It does NOT decorate an existing tool. The misleading name
-trap: agents read "useComponent" as "register a component for this tool"
-and end up with two tools colliding on the same name.
-
-Source: `packages/react-core/src/v2/hooks/use-component.tsx:59-88`
-
-### HIGH — Hand-rolling `useRenderTool({ name: "*" })` instead of `useDefaultRenderTool`
-
-Wrong:
-
-```tsx
-useRenderTool({
-  name: "*",
-  render: ({ parameters }) => <pre>{JSON.stringify(parameters)}</pre>,
-});
-```
-
-Correct:
-
-```tsx
-// Use the built-in default card:
-useDefaultRenderTool();
-
-// Or customize, with the correct DefaultRenderProps typing (parameters: unknown):
-useDefaultRenderTool({
-  render: ({ name, status, parameters, result }) => {
-    if (name === "search") {
-      const args = parameters as { q: string };
-      return <SearchCard q={args.q} status={status} />;
-    }
-    return <GenericCard name={name} status={status} />;
-  },
-});
-```
-
-The sanctioned wildcard API is `useDefaultRenderTool`. It wraps
-`useRenderTool({ name: "*" })` with the correct `DefaultRenderProps`
-typing (`parameters: unknown`) and provides a built-in default card when
-no `render` is passed. Hand-rolling loses the default card and invites
-the untyped-args footgun.
-
-Source: `packages/react-core/src/v2/hooks/use-default-render-tool.tsx:15-64`

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

@@ -1,211 +0,0 @@
-# CopilotKit Suggestions (React)
-
-This skill builds on `copilotkit/provider-setup` and
-`copilotkit/chat-components`. Suggestions render via
-`CopilotChatSuggestionView` which `<CopilotChat>` mounts automatically.
-
-Two sides:
-
-- `useConfigureSuggestions(config, deps?)` — register dynamic (LLM) or
-  static suggestions.
-- `useSuggestions({ agentId })` — read current suggestions + trigger
-  reload / clear.
-
-## Setup
-
-### Dynamic suggestions (LLM-generated)
-
-```tsx
-"use client";
-import { useConfigureSuggestions } from "@copilotkit/react-core/v2";
-import { useMemo } from "react";
-
-export function DynamicSuggestionsHost({ page }: { page: string }) {
-  const instructions = useMemo(
-    () => `Suggest 3 follow-up questions about the "${page}" page.`,
-    [page],
-  );
-
-  useConfigureSuggestions(
-    {
-      instructions,
-      minSuggestions: 2,
-      maxSuggestions: 4,
-      available: "always",
-    },
-    [page],
-  );
-
-  return null;
-}
-```
-
-### Static suggestions
-
-```tsx
-"use client";
-import { useConfigureSuggestions } from "@copilotkit/react-core/v2";
-
-export function StaticStarters() {
-  useConfigureSuggestions({
-    suggestions: [
-      { title: "Summarize this page", message: "Summarize the current page." },
-      { title: "Explain like I'm 5", message: "Explain this in simple terms." },
-    ],
-    available: "before-first-message",
-  });
-  return null;
-}
-```
-
-## Core Patterns
-
-### Read and refresh suggestions from any component
-
-```tsx
-import { useSuggestions } from "@copilotkit/react-core/v2";
-
-export function RefreshButton() {
-  const { suggestions, reloadSuggestions, clearSuggestions, isLoading } =
-    useSuggestions({ agentId: "default" });
-  return (
-    <div>
-      <button onClick={reloadSuggestions} disabled={isLoading}>
-        {isLoading ? "Loading…" : "Refresh"}
-      </button>
-      <button onClick={clearSuggestions}>Clear</button>
-      <span>{suggestions.length} suggestions</span>
-    </div>
-  );
-}
-```
-
-### Feature-flag the suggestions config
-
-```tsx
-const enabled = useFeatureFlag("suggestions");
-useConfigureSuggestions(
-  enabled ? { instructions: "Suggest 3 follow-ups" } : null,
-);
-```
-
-### Agent-scoped dynamic suggestions
-
-```tsx
-useConfigureSuggestions({
-  instructions: "Suggest follow-ups for the research agent.",
-  consumerAgentId: "research",
-});
-```
-
-## Common Mistakes
-
-### MEDIUM — Using `available: "disabled"` expecting reload to still fire
-
-Wrong:
-
-```tsx
-useConfigureSuggestions({
-  instructions: "Suggest 3 follow-ups",
-  available: "disabled",
-});
-// Then calling reloadSuggestions() — no-op
-```
-
-Correct:
-
-```tsx
-const enabled = useFeatureFlag("suggestions");
-useConfigureSuggestions(
-  enabled ? { instructions: "Suggest 3 follow-ups" } : null,
-);
-```
-
-`available: "disabled"` is normalized to a `null` config — the same as
-passing `null`/`undefined`. Reloads become no-ops. Pass `null` (or gate on
-a condition) when you want to fully disable suggestions.
-
-Source: `packages/react-core/src/v2/hooks/use-configure-suggestions.tsx:59-62`
-
-### MEDIUM — Inline config object without `deps`
-
-Wrong:
-
-```tsx
-useConfigureSuggestions({ instructions: `about ${currentPage}` });
-// Config re-serialized every render — reload may or may not fire depending on cache equality
-```
-
-Correct:
-
-```tsx
-useConfigureSuggestions({ instructions: `about ${currentPage}` }, [
-  currentPage,
-]);
-```
-
-`useConfigureSuggestions` uses a serialized-config cache keyed off the
-JSON-stringified value. Without `deps`, React invariance + inline objects
-produce unstable identities that thrash the cache. Always pass `deps` that
-cover the values interpolated into the config.
-
-Source: `packages/react-core/src/v2/hooks/use-configure-suggestions.tsx:166-171`
-
-### MEDIUM — Calling `reloadSuggestions` mid-run
-
-Wrong:
-
-```tsx
-<button onClick={() => reloadSuggestions()}>Refresh</button>
-// Fires during agent streaming → competes with the running agent
-```
-
-Correct:
-
-```tsx
-import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";
-
-const { agent } = useAgent({
-  agentId: "default",
-  updates: [UseAgentUpdate.OnRunStatusChanged],
-});
-const isRunning = agent.isRunning;
-<button
-  disabled={isRunning}
-  onClick={() => {
-    if (!isRunning) reloadSuggestions();
-  }}
->
-  Refresh
-</button>;
-```
-
-The internal auto-reload skips when `isRunning`, but the user-triggered
-`reloadSuggestions()` does not guard itself. Guard the caller, or the
-suggestion generation races the active agent run.
-
-Source: `packages/react-core/src/v2/hooks/use-configure-suggestions.tsx:121-124`
-
-### MEDIUM — Expecting `maxSuggestions` above 3 without setting it
-
-Wrong:
-
-```tsx
-useConfigureSuggestions({ instructions: "…" });
-// Then surprised the UI only shows 3 pills even when the LLM returned 8
-```
-
-Correct:
-
-```tsx
-useConfigureSuggestions({
-  instructions: "…",
-  minSuggestions: 1,
-  maxSuggestions: 6,
-});
-```
-
-`minSuggestions` and `maxSuggestions` default to 1 and 3 respectively. Set
-them explicitly when you want a different count.
-
-Source: `packages/core/src/types.ts` (DynamicSuggestionsConfig defaults)

package/skills/react-core/references/switching-agents-recipes.md

@@ -1,161 +0,0 @@
-# Agent Switcher Recipes
-
-Three copy-paste patterns for multi-agent UIs. All subscribe to
-`copilotkit.subscribe({ onAgentsChanged })` for live agent discovery — there
-is no `useAgents()` hook.
-
-## Recipe 1 — Dropdown switcher
-
-```tsx
-"use client";
-import { CopilotChat, useCopilotKit } from "@copilotkit/react-core/v2";
-import { useEffect, useState } from "react";
-
-export function DropdownAgentSwitcher() {
-  const { copilotkit } = useCopilotKit();
-  const [agentIds, setAgentIds] = useState<string[]>(() =>
-    Object.keys(copilotkit.agents ?? {}),
-  );
-  const [activeAgent, setActiveAgent] = useState<string>(
-    () => Object.keys(copilotkit.agents ?? {})[0] ?? "default",
-  );
-
-  useEffect(() => {
-    const sub = copilotkit.subscribe({
-      onAgentsChanged: ({ agents }) => {
-        setAgentIds(Object.keys(agents ?? {}));
-      },
-    });
-    return () => sub.unsubscribe();
-  }, [copilotkit]);
-
-  return (
-    <div className="flex flex-col gap-3">
-      <select
-        value={activeAgent}
-        onChange={(e) => setActiveAgent(e.target.value)}
-      >
-        {agentIds.map((id) => (
-          <option key={id} value={id}>
-            {id}
-          </option>
-        ))}
-      </select>
-      <CopilotChat key={activeAgent} agentId={activeAgent} />
-    </div>
-  );
-}
-```
-
-## Recipe 2 — Tabs switcher
-
-```tsx
-"use client";
-import { CopilotChat, useCopilotKit } from "@copilotkit/react-core/v2";
-import { useEffect, useRef, useState } from "react";
-
-export function TabsAgentSwitcher() {
-  const { copilotkit } = useCopilotKit();
-  const [agentIds, setAgentIds] = useState<string[]>(() =>
-    Object.keys(copilotkit.agents ?? {}),
-  );
-  const [activeAgent, setActiveAgent] = useState<string>(
-    () => agentIds[0] ?? "default",
-  );
-
-  // Hold activeAgent in a ref so the subscribe effect only re-binds when
-  // `copilotkit` changes. Depending on `activeAgent` would tear down and
-  // re-establish the subscription on every tab click.
-  const activeAgentRef = useRef(activeAgent);
-  useEffect(() => {
-    activeAgentRef.current = activeAgent;
-  }, [activeAgent]);
-
-  useEffect(() => {
-    const sub = copilotkit.subscribe({
-      onAgentsChanged: ({ agents }) => {
-        const ids = Object.keys(agents ?? {});
-        setAgentIds(ids);
-        if (!ids.includes(activeAgentRef.current) && ids.length > 0) {
-          setActiveAgent(ids[0]);
-        }
-      },
-    });
-    return () => sub.unsubscribe();
-  }, [copilotkit]);
-
-  return (
-    <div>
-      <div role="tablist" className="flex gap-2 border-b">
-        {agentIds.map((id) => (
-          <button
-            key={id}
-            role="tab"
-            aria-selected={id === activeAgent}
-            onClick={() => setActiveAgent(id)}
-          >
-            {id}
-          </button>
-        ))}
-      </div>
-      <CopilotChat key={activeAgent} agentId={activeAgent} />
-    </div>
-  );
-}
-```
-
-## Recipe 3 — Keyboard shortcut switcher
-
-Cycles through agents with `Cmd/Ctrl + Shift + A`.
-
-```tsx
-"use client";
-import { CopilotChat, useCopilotKit } from "@copilotkit/react-core/v2";
-import { useEffect, useState } from "react";
-
-export function KeyboardAgentSwitcher() {
-  const { copilotkit } = useCopilotKit();
-  const [agentIds, setAgentIds] = useState<string[]>(() =>
-    Object.keys(copilotkit.agents ?? {}),
-  );
-  const [activeAgent, setActiveAgent] = useState<string>(
-    () => agentIds[0] ?? "default",
-  );
-
-  useEffect(() => {
-    const sub = copilotkit.subscribe({
-      onAgentsChanged: ({ agents }) => setAgentIds(Object.keys(agents ?? {})),
-    });
-    return () => sub.unsubscribe();
-  }, [copilotkit]);
-
-  useEffect(() => {
-    function onKey(e: KeyboardEvent) {
-      const isCombo = (e.metaKey || e.ctrlKey) && e.shiftKey && e.key === "A";
-      if (!isCombo || agentIds.length === 0) return;
-      e.preventDefault();
-      const idx = agentIds.indexOf(activeAgent);
-      const next = agentIds[(idx + 1) % agentIds.length];
-      setActiveAgent(next);
-    }
-    window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [agentIds, activeAgent]);
-
-  return (
-    <div>
-      <div className="text-xs opacity-60">
-        Active: {activeAgent} — press ⌘/Ctrl+Shift+A to cycle
-      </div>
-      <CopilotChat key={activeAgent} agentId={activeAgent} />
-    </div>
-  );
-}
-```
-
-## Key rules across all three recipes
-
-- Use `copilotkit.subscribe({ onAgentsChanged })` — there is no `useAgents()` hook.
-- Always `key={activeAgent}` on `<CopilotChat>` so thread state doesn't leak when swapping agents in the same slot.
-- Keep that `key` on `<CopilotChat>` and nowhere higher. A `key` discards every bit of state beneath it, so on a wrapper or a layout provider it silently wipes app state too.
-- Clean up the subscription with `sub.unsubscribe()` in the effect cleanup.