@copilotkit/react-core 1.70.3 → 1.71.1

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

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

@@ -1,289 +0,0 @@
-# CopilotKit Threads (React)
-
-This skill builds on `copilotkit/agent-access`. Durable threads only exist
-in Intelligence mode — a runtime pointed at `api.cloud.copilotkit.ai` or a
-self-managed Intelligence instance. In plain SSE mode the hook errors.
-
-## Setup
-
-```tsx
-"use client";
-import { useThreads } from "@copilotkit/react-core/v2";
-
-export function ThreadSidebar({ agentId }: { agentId: string }) {
-  const {
-    threads,
-    isLoading,
-    error,
-    hasMoreThreads,
-    fetchMoreThreads,
-    renameThread,
-    archiveThread,
-    deleteThread,
-  } = useThreads({ agentId });
-
-  if (error) return <div className="text-red-500">{error.message}</div>;
-  if (isLoading) return <div>Loading threads…</div>;
-
-  return (
-    <ul className="space-y-1">
-      {threads.map((t) => (
-        <li key={t.id} className="flex gap-2">
-          <span>{t.name ?? "Untitled"}</span>
-          <button onClick={() => renameThread(t.id, "Renamed")}>Rename</button>
-          <button onClick={() => archiveThread(t.id)}>Archive</button>
-        </li>
-      ))}
-      {hasMoreThreads && <button onClick={fetchMoreThreads}>Load more</button>}
-    </ul>
-  );
-}
-```
-
-## Core Patterns
-
-### Paginated list
-
-```tsx
-const { threads, hasMoreThreads, fetchMoreThreads, isFetchingMoreThreads } =
-  useThreads({ agentId: "default", limit: 25 });
-```
-
-### Include archived threads
-
-```tsx
-const { threads: archived } = useThreads({
-  agentId: "default",
-  includeArchived: true,
-});
-```
-
-### Optimistic archive with error rollback
-
-```tsx
-const { threads, archiveThread } = useThreads({ agentId: "default" });
-
-async function onArchive(id: string) {
-  try {
-    await archiveThread(id);
-    toast.success("Archived");
-  } catch (err) {
-    toast.error(`Failed to archive: ${String(err)}`);
-  }
-}
-```
-
-### Thread-switcher + `<CopilotChat>`
-
-```tsx
-import { CopilotChat, useThreads } from "@copilotkit/react-core/v2";
-import { useState } from "react";
-
-export function ThreadSwitcher() {
-  const { threads } = useThreads({ agentId: "default" });
-  const [activeId, setActiveId] = useState<string | null>(null);
-
-  return (
-    <div className="grid grid-cols-[200px_1fr]">
-      <ul>
-        {threads.map((t) => (
-          <li key={t.id}>
-            <button onClick={() => setActiveId(t.id)}>
-              {t.name ?? "Untitled"}
-            </button>
-          </li>
-        ))}
-      </ul>
-      {/*
-        `key` here remounts ONLY <CopilotChat>. Keep it that way: a `key` on
-        an ancestor would remount the app tree below it too. See
-        "Keying a subtree on the active thread id" below.
-      */}
-      {activeId && (
-        <CopilotChat key={activeId} agentId="default" threadId={activeId} />
-      )}
-    </div>
-  );
-}
-```
-
-`activeId` starts as `null` and becomes a real thread id only after the
-`useThreads` fetch resolves — so this is an **asynchronous, post-mount**
-change, not something settled during the first render.
-
-## Common Mistakes
-
-### HIGH — Keying a subtree on the active thread id above app state
-
-Wrong:
-
-```tsx
-// app/layout.tsx
-const { threadId } = useThreadSelection();
-
-return (
-  <CopilotKitProvider runtimeUrl="/api/copilotkit">
-    {/* Remounts EVERYTHING below on every thread change. */}
-    <MyAppProvider key={threadId}>{children}</MyAppProvider>
-  </CopilotKitProvider>
-);
-```
-
-Correct:
-
-```tsx
-// app/layout.tsx — app state stays mounted across thread changes.
-return (
-  <CopilotKitProvider runtimeUrl="/api/copilotkit">
-    <MyAppProvider>{children}</MyAppProvider>
-  </CopilotKitProvider>
-);
-```
-
-```tsx
-// Reset only what is genuinely per-thread, as deep as possible.
-<ThreadScopedTranscript key={threadId} />
-```
-
-`key={threadId}` is a legitimate way to reset per-thread state, but it
-discards **all** state below it — refs, correlation maps, in-flight request
-bookkeeping, scroll positions. Placed on a layout-level provider it wipes
-the whole page, with no error and no warning; the symptom surfaces
-somewhere unrelated, as "our response routing is flaky".
-
-Two properties make this hard to catch:
-
-- The reset is asynchronous. Durable threads only exist in Intelligence
-  mode, so with a plain SSE runtime `useThreads` returns nothing, the
-  selected thread never changes, and the remount never fires. It appears
-  the moment Intelligence is wired.
-- It is timing-dependent. Whether state survives depends on whether the
-  user acted before the thread list resolved.
-
-Put the `key` on the smallest subtree that genuinely owns per-thread
-state, and never above state the application expects to keep. If a
-component both dispatches requests and correlates the responses, it must
-sit **outside** the keyed subtree.
-
-Source: `packages/react-core/src/v2/hooks/use-threads.tsx:282-289` (thread
-endpoints exist only in Intelligence mode), `364-368` (the list fetch is
-deferred until `/info` resolves)
-
-### HIGH — Using `useThreads` with an SSE-only runtime
-
-Wrong:
-
-```tsx
-// Runtime has no Intelligence configured
-new CopilotRuntime({ agents });
-
-// Client side:
-const { threads, error } = useThreads({ agentId: "default" });
-// error: "Runtime URL is not configured" or empty list forever
-```
-
-Correct:
-
-```ts
-// Server — upgrade to Intelligence mode:
-import {
-  CopilotIntelligenceRuntime,
-  CopilotKitIntelligence,
-} from "@copilotkit/runtime/v2";
-
-const intelligence = new CopilotKitIntelligence({
-  // apiUrl / wsUrl default to cloud-hosted CopilotKit Intelligence — leave unset.
-  apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
-});
-
-const runtime = new CopilotIntelligenceRuntime({
-  agents,
-  intelligence,
-  identifyUser: async (req) => ({ userId: await getUserId(req) }),
-});
-```
-
-`CopilotKitIntelligence` and `CopilotIntelligenceRuntime` are only exposed
-on the `@copilotkit/runtime/v2` subpath — the package root exports SSE
-primitives only.
-
-Thread routes only exist in Intelligence mode. In plain SSE the list fetch
-fails and mutations reject.
-
-Source: `packages/react-core/src/v2/hooks/use-threads.tsx:207-213,229`
-
-### HIGH — Expecting `deleteThread` to be recoverable
-
-Wrong:
-
-```tsx
-await deleteThread(id); // user expected a trash bin
-```
-
-Correct:
-
-```tsx
-// For soft-delete UX, use archive:
-await archiveThread(id);
-
-// Then expose archived threads in a separate view:
-const { threads: archived } = useThreads({
-  agentId: "default",
-  includeArchived: true,
-});
-```
-
-`deleteThread` is irreversible in CopilotKit Intelligence. Use
-`archiveThread` for user-facing delete UX and only call `deleteThread` for
-genuine "permanently erase" flows.
-
-Source: `packages/react-core/src/v2/hooks/use-threads.tsx:101-105`
-
-### MEDIUM — Assuming archived threads appear by default
-
-Wrong:
-
-```tsx
-const { threads } = useThreads({ agentId: "default" });
-// User archived a thread. User opens the "Archived" tab. It's empty.
-```
-
-Correct:
-
-```tsx
-const { threads: activeThreads } = useThreads({ agentId: "default" });
-const { threads: archivedThreads } = useThreads({
-  agentId: "default",
-  includeArchived: true,
-});
-```
-
-`includeArchived` defaults to `false`. Archived threads are filtered out of
-the default list; opt in explicitly for an archived-view tab.
-
-Source: `packages/react-core/src/v2/hooks/use-threads.tsx:60-62`
-
-### MEDIUM — Not handling `error`
-
-Wrong:
-
-```tsx
-const { threads } = useThreads({ agentId: "default" });
-return <ul>{threads.map(...)}</ul>;
-// Silent failures — handshake errors, network errors all vanish.
-```
-
-Correct:
-
-```tsx
-const { threads, isLoading, error } = useThreads({ agentId: "default" });
-if (error) return <ErrorBanner message={error.message} />;
-if (isLoading) return <Spinner />;
-return <ul>{threads.map(...)}</ul>;
-```
-
-`error` holds the most recent fetch/mutation error until the next
-successful fetch clears it. Surface it or you'll miss Intelligence-mode
-mis-configuration.
-
-Source: `packages/react-core/src/v2/hooks/use-threads.tsx:70-74`