@copilotkit/react-core 1.71.0 → 1.71.1

package/skills/react-core/references/client-side-tools.md

@@ -1,358 +0,0 @@
-# CopilotKit Client-Side Tools (React)
-
-This skill builds on `copilotkit/provider-setup`. Tools registered via
-`useFrontendTool` execute in the browser and are exposed to the agent over
-AG-UI.
-
-Hook signature:
-
-```ts
-useFrontendTool<T>(tool: ReactFrontendTool<T>, deps?: ReadonlyArray<unknown>);
-```
-
-The hook re-registers when `tool.name`, `tool.available`, or any entry in
-`deps` changes. Closures inside `handler` capture React state at
-registration time — pass `deps` when the handler references state.
-
-## UI-kit detection rule
-
-Before writing any `render` JSX, check the consumer's `package.json` for a
-UI kit and reuse its primitives:
-
-- `components/ui/*` (shadcn)
-- `@mui/material` (MUI)
-- `@chakra-ui/react` (Chakra)
-- `antd` (Ant Design)
-- `@mantine/core` (Mantine)
-
-Only write raw JSX if no kit is present.
-
-## Setup
-
-```tsx
-"use client";
-import { useFrontendTool } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-
-export function SearchToolHost() {
-  useFrontendTool({
-    name: "searchDocs",
-    description: "Search the in-app documentation",
-    parameters: z.object({ query: z.string() }),
-    handler: async ({ query }, { signal }) => {
-      const r = await fetch(`/api/search?q=${encodeURIComponent(query)}`, {
-        signal,
-      });
-      return (await r.json()).results.join("\n");
-    },
-  });
-  return null;
-}
-```
-
-`zod` is a hard peer dependency — install it alongside `@copilotkit/react-core`.
-
-## Core Patterns
-
-### Handler with React state + deps
-
-```tsx
-const [cart, setCart] = useState<string[]>([]);
-
-useFrontendTool(
-  {
-    name: "addItem",
-    parameters: z.object({ id: z.string() }),
-    handler: async ({ id }) => {
-      setCart((c) => [...c, id]);
-    },
-  },
-  [setCart],
-);
-```
-
-### Forward `signal` into fetch (so `stopAgent` cancels in-flight calls)
-
-```tsx
-useFrontendTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  handler: async ({ q }, { signal }) => {
-    const r = await fetch(`/search?q=${q}`, { signal });
-    return r.text();
-  },
-});
-```
-
-### Render progress UI for a tool (reuse the consumer's UI kit)
-
-```tsx
-// Consumer has shadcn → use Card + Skeleton
-import { Card, CardContent } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
-
-useFrontendTool({
-  name: "show",
-  parameters: z.object({ id: z.string() }),
-  handler: async ({ id }) => fetchItem(id),
-  render: ({ status, parameters, result }) => (
-    <Card>
-      {status === "inProgress" ? (
-        <Skeleton className="h-24 w-full" />
-      ) : (
-        <CardContent>{result}</CardContent>
-      )}
-    </Card>
-  ),
-});
-```
-
-### Programmatic invocation with string follow-up
-
-`copilotkit.runTool` accepts `followUp: boolean | "generate" | string`.
-A string is injected as a synthetic user message before the agent runs.
-
-```tsx
-import { useCopilotKit } from "@copilotkit/react-core/v2";
-
-const { copilotkit } = useCopilotKit();
-
-await copilotkit.runTool({
-  name: "searchDocs",
-  parameters: { query: "zod" },
-  followUp: "Summarize these results in 3 bullets", // inject as user message, run agent
-});
-```
-
-## Common Mistakes
-
-### CRITICAL — Writing JSX from scratch for `render` when the app has a UI kit
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "show",
-  parameters: z.object({ id: z.string() }),
-  handler,
-  render: ({ status }) => <div style={{ padding: 12 }}>…</div>,
-});
-```
-
-Correct:
-
-```tsx
-// First check package.json for shadcn / @mui/* / @chakra-ui/* / antd / @mantine/*, then:
-import { Card, CardContent } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
-
-useFrontendTool({
-  name: "show",
-  parameters: z.object({ id: z.string() }),
-  handler,
-  render: ({ status, result }) => (
-    <Card>
-      {status === "inProgress" ? (
-        <Skeleton />
-      ) : (
-        <CardContent>{result}</CardContent>
-      )}
-    </Card>
-  ),
-});
-```
-
-Consumers almost always have a UI kit. Raw JSX produces unbranded output
-and skips the accessibility patterns their existing primitives encode.
-
-Source: maintainer interview (Phase 2c)
-
-### HIGH — Stale closure inside `handler`
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "addItem",
-  parameters: z.object({ id: z.string() }),
-  handler: async ({ id }) => {
-    addTo(cart, id); // `cart` is captured at registration — goes stale
-  },
-});
-```
-
-Correct:
-
-```tsx
-useFrontendTool(
-  {
-    name: "addItem",
-    parameters: z.object({ id: z.string() }),
-    handler: async ({ id }) => {
-      addTo(cart, id);
-    },
-  },
-  [cart],
-);
-```
-
-`useFrontendTool` only re-registers when `name`, `available`, or `deps`
-change. Without `deps`, closures over React state freeze at first mount.
-
-Source: `packages/react-core/src/v2/hooks/use-frontend-tool.tsx:45`
-
-### HIGH — Ignoring `signal` in async handlers
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  handler: async ({ q }) => (await fetch(`/search?q=${q}`)).text(),
-});
-```
-
-Correct:
-
-```tsx
-useFrontendTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  handler: async ({ q }, { signal }) =>
-    (await fetch(`/search?q=${q}`, { signal })).text(),
-});
-```
-
-`stopAgent` / `agent.abortRun` abort via `AbortSignal`. A handler that
-doesn't forward `signal` keeps fetching after cancel, racing the next turn.
-
-Source: `packages/core/src/types.ts:24-30`
-
-### HIGH — Assuming `followUp` defaults to `false`
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "logAnalyticsEvent",
-  parameters: z.object({ name: z.string() }),
-  handler: async ({ name }) => {
-    analytics.track(name);
-  },
-  // followUp omitted → defaults to TRUE. Agent re-runs after every analytics call.
-});
-```
-
-Correct:
-
-```tsx
-useFrontendTool({
-  name: "logAnalyticsEvent",
-  parameters: z.object({ name: z.string() }),
-  handler: async ({ name }) => {
-    analytics.track(name);
-  },
-  followUp: false, // side-effect tool — don't re-invoke the agent
-});
-```
-
-For agent-invoked tools, run-handler checks `tool?.followUp !== false` — so
-`undefined` AND `true` both fire a follow-up `runAgent`. Only explicit
-`false` suppresses it. Pure side-effect tools must opt out or they loop.
-
-Source: `packages/core/src/core/run-handler.ts:607`
-
-### HIGH — Missing `zod` peer dependency
-
-Wrong:
-
-```bash
-pnpm install @copilotkit/react-core
-# zod missing — the CopilotKit provider fails to load
-```
-
-Correct:
-
-```bash
-pnpm install @copilotkit/react-core zod
-```
-
-`zod` is a hard peer of `@copilotkit/react-core` and is imported at
-provider module scope. Without it the provider module throws on load.
-
-Source: `packages/react-core/package.json` (peerDependencies)
-
-### MEDIUM — Duplicate tool name across hooks
-
-Wrong:
-
-```tsx
-// ComponentA
-useFrontendTool({ name: "save", parameters, handler: saveA });
-// ComponentB mounted in same tree:
-useFrontendTool({ name: "save", parameters, handler: saveB });
-// console.warn: "Tool 'save' already exists … Overriding"
-```
-
-Correct:
-
-```tsx
-useFrontendTool({
-  name: "save",
-  agentId: "research",
-  parameters,
-  handler: saveA,
-});
-useFrontendTool({
-  name: "save",
-  agentId: "coding",
-  parameters,
-  handler: saveB,
-});
-```
-
-Tool names must be globally unique per `agentId`. Second mount warns and
-replaces the first. Scope with `agentId` when multiple agents need their
-own "save" handler.
-
-Source: `packages/react-core/src/v2/hooks/use-frontend-tool.tsx:17-22`
-
-### MEDIUM — Passing `"generate"` or a string to `useFrontendTool`'s `followUp`
-
-Wrong:
-
-```tsx
-useFrontendTool({
-  name: "searchDocs",
-  parameters: z.object({ q: z.string() }),
-  handler,
-  followUp: "Summarize these results" as any, // silently truthy on registered tools
-});
-```
-
-Correct:
-
-```tsx
-// Registered tools — boolean only:
-useFrontendTool({
-  name: "searchDocs",
-  parameters: z.object({ q: z.string() }),
-  handler,
-  followUp: true,
-});
-
-// For string follow-ups, call runTool programmatically:
-const { copilotkit } = useCopilotKit();
-await copilotkit.runTool({
-  name: "searchDocs",
-  parameters: { q: "zod" },
-  followUp: "Summarize these results", // injects user message, runs agent
-});
-```
-
-`FrontendTool.followUp` is typed `boolean`. Strings are silently truthy
-(treated as `true`). The `"generate"` and custom-string modes only work
-on `copilotkit.runTool({ followUp })`.
-
-Source: `packages/core/src/types.ts:39`; `packages/core/src/core/run-handler.ts:47,763,848-863`

package/skills/react-core/references/custom-message-renderers.md

@@ -1,223 +0,0 @@
-# CopilotKit Custom Message Renderers (React)
-
-This skill builds on `copilotkit/provider-setup` and
-`copilotkit/chat-components`. `useRenderCustomMessages` is consumed
-internally by `<CopilotChat>` / `<CopilotChatView>`.
-
-Key rules:
-
-- Renderers are passed to the `CopilotKit` provider via `renderCustomMessages`.
-- The hook returns `null` when called outside `CopilotChatConfigurationProvider`.
-- First non-null result wins — agent-scoped renderers evaluated first.
-- `stateSnapshot` is `undefined` before the run's `runId` resolves.
-
-## Setup
-
-```tsx
-"use client";
-import { CopilotKit } from "@copilotkit/react-core/v2";
-import type { ReactCustomMessageRenderer } from "@copilotkit/react-core/v2";
-import { useMemo } from "react";
-import { Button } from "@/components/ui/button";
-
-const CopyButton: ReactCustomMessageRenderer = {
-  render: ({ message, position }) => {
-    if (position !== "after") return null;
-    if (message.role !== "assistant") return null;
-    const content = typeof message.content === "string" ? message.content : "";
-    if (!content) return null;
-    return (
-      <Button
-        variant="ghost"
-        size="sm"
-        onClick={() => navigator.clipboard.writeText(content)}
-      >
-        Copy
-      </Button>
-    );
-  },
-};
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  const renderers = useMemo(() => [CopyButton], []);
-  return (
-    <CopilotKit runtimeUrl="/api/copilotkit" renderCustomMessages={renderers}>
-      {children}
-    </CopilotKit>
-  );
-}
-```
-
-## Core Patterns
-
-### State-snapshot viewer after completed runs
-
-```tsx
-const StateSnapshotRenderer: ReactCustomMessageRenderer = {
-  render: ({ message, position, stateSnapshot }) => {
-    if (position !== "after") return null;
-    if (message.role !== "assistant") return null;
-    if (!stateSnapshot) return null; // run not yet resolved
-    return (
-      <details>
-        <summary>Agent state</summary>
-        <pre>{JSON.stringify(stateSnapshot, null, 2)}</pre>
-      </details>
-    );
-  },
-};
-```
-
-### Agent-scoped renderer
-
-```tsx
-const ResearchNotes: ReactCustomMessageRenderer = {
-  agentId: "research",
-  render: ({ message, position, stateSnapshot }) => {
-    if (position !== "after" || !stateSnapshot) return null;
-    const notes = (stateSnapshot as { notes?: string[] }).notes ?? [];
-    return (
-      <ul>
-        {notes.map((n, i) => (
-          <li key={i}>{n}</li>
-        ))}
-      </ul>
-    );
-  },
-};
-```
-
-### Debug panel before user messages
-
-```tsx
-const DebugBefore: ReactCustomMessageRenderer = {
-  render: ({ message, position, messageIndex, runId }) => {
-    if (position !== "before" || message.role !== "user") return null;
-    // `runId` is always a string, but it falls back to a synthetic
-    // "missing-run-id:<messageId>" value before a run is registered.
-    // Slice only when it looks like a real id, otherwise show a dash.
-    const shortId = runId?.startsWith("missing-run-id:")
-      ? "—"
-      : (runId?.slice(0, 6) ?? "—");
-    return (
-      <div style={{ opacity: 0.5, fontSize: 11 }}>
-        #{messageIndex} · run {shortId}
-      </div>
-    );
-  },
-};
-```
-
-## Common Mistakes
-
-### HIGH — Using the hook outside a chat configuration provider
-
-Wrong:
-
-```tsx
-// Component mounted outside <CopilotChat>/<CopilotChatView>
-function StandaloneRenderer() {
-  const render = useRenderCustomMessages(); // returns null — no chat config in tree
-  return render ? render({ message, position: "after" }) : null;
-}
-```
-
-Correct:
-
-```tsx
-// Option A — register renderers via the provider prop so <CopilotChat> picks them up:
-<CopilotKit renderCustomMessages={renderers}>
-  <CopilotChat agentId="default" />
-</CopilotKit>;
-
-// Option B — call the hook only inside a chat-configured subtree:
-import { CopilotChatConfigurationProvider } from "@copilotkit/react-core/v2";
-<CopilotChatConfigurationProvider agentId="default">
-  <ComponentThatCallsUseRenderCustomMessages />
-</CopilotChatConfigurationProvider>;
-```
-
-`useRenderCustomMessages` returns `null` when there is no
-`CopilotChatConfigurationProvider` in the tree. `<CopilotChat>` wraps its
-children in one automatically; direct use outside a chat component
-requires the explicit wrapper.
-
-Source: `packages/react-core/src/v2/hooks/use-render-custom-messages.tsx:15-17`
-
-### MEDIUM — Relying on `stateSnapshot` during early streaming
-
-Wrong:
-
-```tsx
-render: ({ stateSnapshot }) => <pre>{JSON.stringify(stateSnapshot.items)}</pre>;
-// Crashes during the first token — stateSnapshot is undefined before runId resolves.
-```
-
-Correct:
-
-```tsx
-render: ({ stateSnapshot }) => (
-  <pre>{stateSnapshot ? JSON.stringify(stateSnapshot.items) : "…"}</pre>
-);
-```
-
-`stateSnapshot` comes from `copilotkit.getStateByRun(agentId, threadId,
-runId)`. `runId` is `undefined` until the run is registered, so the
-snapshot starts `undefined` and only becomes truthy after the first
-state emit. Guard with a fallback.
-
-Source: `packages/react-core/src/v2/hooks/use-render-custom-messages.tsx:69-71`
-
-### MEDIUM — Expecting every renderer in the array to run
-
-Wrong:
-
-```tsx
-// Both renderers want to add an "after assistant" button and return <div>…</div>
-// Only the first one (or the agent-scoped one) fires — the second is skipped.
-const renderers = [Renderer1, Renderer2];
-```
-
-Correct:
-
-```tsx
-// Merge the two into a single renderer that returns one element:
-const Combined: ReactCustomMessageRenderer = {
-  render: (props) => (
-    <div className="flex gap-1">
-      <Renderer1Inner {...props} />
-      <Renderer2Inner {...props} />
-    </div>
-  ),
-};
-```
-
-The hook iterates the sorted renderer list and breaks at the first non-null
-result. Two independent renderers returning JSX for the same
-`(message, position)` pair will have only one fire. Compose them into a
-single renderer if you want both to appear.
-
-Source: `packages/react-core/src/v2/hooks/use-render-custom-messages.tsx:73-95`
-
-### MEDIUM — Memoization miss on `renderCustomMessages` array
-
-Wrong:
-
-```tsx
-<CopilotKit
-  renderCustomMessages={[CopyButton, DebugBefore]} // fresh array every render
-/>
-```
-
-Correct:
-
-```tsx
-const renderers = useMemo(() => [CopyButton, DebugBefore], []);
-<CopilotKit renderCustomMessages={renderers} />;
-```
-
-The provider's stable-array-prop diff console-errors when a new array
-identity appears every render and thrashes renderer registration.
-Memoize or hoist.
-
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (useStableArrayProp)

package/skills/react-core/references/debug-mode.md

@@ -1,140 +0,0 @@
-# CopilotKit Debug Mode (React)
-
-This skill builds on `copilotkit/provider-setup`. Both debug surfaces are
-props on the `CopilotKit` provider (from `@copilotkit/react-core/v2`).
-
-Two independent knobs:
-
-1. `enableInspector` disables the development-only visual Inspector when set
-   to `false`.
-2. `debug` controls console logging for the event pipeline.
-
-The Inspector is always off in production. Configure `debug` separately for
-the logging behavior you need.
-
-## Setup
-
-```tsx
-"use client";
-import { CopilotKit } from "@copilotkit/react-core/v2";
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <CopilotKit
-      runtimeUrl="/api/copilotkit"
-      debug={{ events: true, lifecycle: true, verbose: false }}
-    >
-      {children}
-    </CopilotKit>
-  );
-}
-```
-
-The Inspector is enabled automatically in development browser builds on any
-host. Production builds never load it.
-
-## Core Patterns
-
-### Full payload logging during a repro
-
-`debug: true` enables `events + lifecycle` but keeps `verbose` off to avoid
-leaking PII by default. For a bug repro, explicitly set `verbose: true` to
-dump full message/tool-call payloads.
-
-```tsx
-<CopilotKit
-  runtimeUrl="/api/copilotkit"
-  debug={{ events: true, lifecycle: true, verbose: true }}
-/>
-```
-
-### Disable the Inspector in development
-
-```tsx
-<CopilotKit runtimeUrl="/api/copilotkit" enableInspector={false} />
-```
-
-Use this when you want no Inspector FAB in local development. Production
-builds never load the Inspector.
-
-## Common Mistakes
-
-### HIGH — Using `showDevConsole` to control the Inspector
-
-Wrong:
-
-```tsx
-<CopilotKit runtimeUrl="/api/copilotkit" showDevConsole="auto" />
-```
-
-Correct:
-
-```tsx
-<CopilotKit runtimeUrl="/api/copilotkit" />
-```
-
-`showDevConsole` no longer controls Inspector visibility. Omit it. The
-Inspector is on in development and off in production.
-
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:301-321`
-
-### MEDIUM — Expecting `debug: true` to log full payloads
-
-Wrong:
-
-```tsx
-<CopilotKit debug={true} />
-// Then wondering why message contents aren't in the console
-```
-
-Correct:
-
-```tsx
-<CopilotKit debug={{ events: true, lifecycle: true, verbose: true }} />
-```
-
-`debug: true` is shorthand for `{ events: true, lifecycle: true, verbose: false }`.
-`verbose` defaults to `false` to avoid logging user message bodies / tool
-arguments / state snapshots — it must be opted into explicitly.
-
-Source: `docs/snippets/shared/troubleshooting/debug-mode.mdx:85-93`
-
-### MEDIUM — Passing fields that aren't in `DebugConfig`
-
-Wrong:
-
-```tsx
-<CopilotKit debug={{ events: true, network: true, errors: true }} />
-```
-
-Correct:
-
-```tsx
-<CopilotKit debug={{ events: true, lifecycle: true, verbose: true }} />
-```
-
-`DebugConfig` has exactly three fields: `events`, `lifecycle`, `verbose`.
-Anything else is silently ignored by the type-narrowing at the provider.
-
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (DebugConfig type)
-
-### MEDIUM — Inspector crashing in sandboxed iframes
-
-Wrong:
-
-```tsx
-// App embedded in a sandboxed iframe with the development Inspector enabled
-<CopilotKit runtimeUrl="..." />
-```
-
-Correct:
-
-```tsx
-<CopilotKit runtimeUrl="..." enableInspector={false} />
-```
-
-The inspector persists its anchor via `localStorage`. In sandboxed iframes
-without storage access, `loadInspectorState` throws on mount. Disable it for
-an iframe deployment or whitelist storage in the sandbox attrs.
-
-Source: `packages/web-inspector/src/lib/persistence.ts` (`loadInspectorState`)