@copilotkit/react-core 1.57.3 → 1.58.0-canary.thread-id-propagation

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

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

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

@@ -0,0 +1,160 @@
+# 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.
+- Clean up the subscription with `sub.unsubscribe()` in the effect cleanup.