@copilotkit/react-core 1.71.0 → 1.71.1

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.

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

@@ -1,240 +0,0 @@
-# CopilotKit Switching Agents (React)
-
-This skill builds on `copilotkit/agent-access`, `copilotkit/client-side-tools`,
-and `copilotkit/rendering-tool-calls`.
-
-Three main patterns:
-
-1. **Parallel panels** — one `useAgent({ agentId })` per surface.
-2. **Slot swap** — `<CopilotChat key={agentId} agentId={agentId} />`.
-3. **Discovery** — subscribe to `onAgentsChanged` (no `useAgents()` hook).
-
-## Setup
-
-```tsx
-"use client";
-import { CopilotChat } from "@copilotkit/react-core/v2";
-import { useState } from "react";
-
-export function AgentSwitcherChat() {
-  const [activeAgent, setActiveAgent] = useState("research");
-
-  return (
-    <div>
-      <div>
-        <button onClick={() => setActiveAgent("research")}>Research</button>
-        <button onClick={() => setActiveAgent("coding")}>Coding</button>
-      </div>
-
-      {/* key={activeAgent} forces remount so thread state doesn't leak */}
-      <CopilotChat key={activeAgent} agentId={activeAgent} />
-    </div>
-  );
-}
-```
-
-## Core Patterns
-
-### Side-by-side chat panels
-
-```tsx
-<div className="grid grid-cols-2 gap-4">
-  <CopilotChat agentId="research" threadId="research-main" />
-  <CopilotChat agentId="coding" threadId="coding-main" />
-</div>
-```
-
-### Agent-scoped tool
-
-```tsx
-import { useFrontendTool } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-
-useFrontendTool({
-  name: "saveFindings",
-  agentId: "research", // ← only the research agent sees this tool
-  parameters: z.object({ summary: z.string() }),
-  handler: async ({ summary }) => {
-    await fetch("/api/findings", { method: "POST", body: summary });
-  },
-});
-```
-
-### Agent-scoped renderer
-
-```tsx
-import { useRenderTool } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-
-useRenderTool({
-  name: "search",
-  agentId: "research", // ← only applies to research's "search" tool
-  parameters: z.object({ q: z.string() }),
-  render: ({ status, parameters, result }) => {
-    if (status === "inProgress") return <div>Preparing...</div>;
-    if (status === "executing") return <div>Searching {parameters.q}</div>;
-    return <div>{result}</div>;
-  },
-});
-```
-
-### Discover available agents (no `useAgents` hook)
-
-```tsx
-"use client";
-import { useCopilotKit } from "@copilotkit/react-core/v2";
-import { useEffect, useState } from "react";
-
-export function useAvailableAgents() {
-  const { copilotkit } = useCopilotKit();
-  const [ids, setIds] = useState<string[]>(() =>
-    Object.keys(copilotkit.agents ?? {}),
-  );
-
-  useEffect(() => {
-    const subscription = copilotkit.subscribe({
-      onAgentsChanged: ({ agents }) => {
-        setIds(Object.keys(agents ?? {}));
-      },
-    });
-    return () => subscription.unsubscribe();
-  }, [copilotkit]);
-
-  return ids;
-}
-```
-
-## Common Mistakes
-
-### HIGH — Switching `agentId` on a persisted `<CopilotChat>` without `key`
-
-Wrong:
-
-```tsx
-<CopilotChat agentId={activeAgent} />
-```
-
-Correct:
-
-```tsx
-<CopilotChat key={activeAgent} agentId={activeAgent} />
-```
-
-Without remount via `key`, prior thread state and in-flight runs leak into
-the new agent's view. The remount pattern gives each agent a clean slate.
-
-Keep the `key` on `<CopilotChat>` itself. It discards all state below it, so
-hoisting it onto a wrapper or a layout-level provider also destroys app
-state that has nothing to do with the agent — correlation maps, in-flight
-request records, refs — with no error and no warning. If a component
-dispatches requests and matches the responses back, it must sit outside the
-keyed subtree. See "Keying a subtree on the active thread id above app
-state" in `references/threads.md` for the thread-switching version of the
-same trap.
-
-Source: `examples/v2/react-router/app/routes/_index.tsx:38-39`
-
-### MEDIUM — Omitting `agentId` when multiple agents share a tool name
-
-Wrong:
-
-```tsx
-// Both research and coding agents have a "search" tool — unscoped wins globally
-useRenderToolCall({
-  name: "search",
-  args: z.object({ q: z.string() }),
-  render,
-});
-```
-
-Correct:
-
-```tsx
-useRenderTool({
-  name: "search",
-  agentId: "research",
-  parameters: z.object({ q: z.string() }),
-  render: researchSearchRender,
-});
-useRenderTool({
-  name: "search",
-  agentId: "coding",
-  parameters: z.object({ q: z.string() }),
-  render: codingSearchRender,
-});
-```
-
-Unscoped renderers apply to every agent. When two agents have a tool with
-the same name and only one has a renderer, the unscoped renderer wins
-globally and the other agent never gets its intended renderer.
-
-Source: `packages/react-core/src/v2/hooks/use-render-tool-call.tsx:145-154`
-
-### MEDIUM — Tools registered without `agentId` leak across panels
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "saveFindings",
-  parameters: z.object({ summary: z.string() }),
-  handler,
-});
-// Both research and coding agents now see saveFindings.
-```
-
-Correct:
-
-```tsx
-useFrontendTool({
-  name: "saveFindings",
-  agentId: "research",
-  parameters: z.object({ summary: z.string() }),
-  handler,
-});
-```
-
-Omitting `agentId` attaches the tool to every agent. In a multi-agent UI
-this leaks the handler across panels. Scope tools explicitly when they
-should only apply to one agent.
-
-Source: `packages/react-core/src/v2/hooks/use-frontend-tool.tsx`
-
-### MEDIUM — Using `useAgents()` (does not exist)
-
-Wrong:
-
-```tsx
-import { useAgents } from "@copilotkit/react-core/v2"; // not exported
-const agents = useAgents();
-```
-
-Correct:
-
-```tsx
-import { useCopilotKit } from "@copilotkit/react-core/v2";
-import { useEffect, useState } from "react";
-
-function useAvailableAgents() {
-  const { copilotkit } = useCopilotKit();
-  const [ids, setIds] = useState<string[]>(() =>
-    Object.keys(copilotkit.agents ?? {}),
-  );
-  useEffect(() => {
-    const sub = copilotkit.subscribe({
-      onAgentsChanged: ({ agents }) => setIds(Object.keys(agents ?? {})),
-    });
-    return () => sub.unsubscribe();
-  }, [copilotkit]);
-  return ids;
-}
-```
-
-There is no `useAgents` hook in v2. Discover agents by subscribing to
-`onAgentsChanged` on the core client.
-
-Source: `packages/react-core/src/v2/hooks/index.ts` (no `useAgents` export)
-
-## References
-
-- [Agent switcher recipes](switching-agents-recipes.md) — dropdown, tabs, keyboard shortcuts