@copilotkit/react-core 1.57.3 → 1.58.0

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

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

@@ -0,0 +1,226 @@
+# 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>
+      {activeId && (
+        <CopilotChat key={activeId} agentId="default" threadId={activeId} />
+      )}
+    </div>
+  );
+}
+```
+
+## Common Mistakes
+
+### 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: process.env.COPILOTKIT_INTELLIGENCE_API_URL!,
+  wsUrl: process.env.COPILOTKIT_INTELLIGENCE_WS_URL!,
+  apiKey: process.env.COPILOTKIT_INTELLIGENCE_API_KEY!,
+  organizationId: process.env.COPILOTKIT_ORG_ID!,
+});
+
+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 at the Intelligence platform level. 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`

package/.attw.json

@@ -1,3 +0,0 @@
-{
-  "excludeEntrypoints": ["./v2/styles.css"]
-}