@copilotkit/react-core 1.70.3 → 1.71.1

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`)

package/skills/react-core/references/human-in-the-loop.md

@@ -1,312 +0,0 @@
-# CopilotKit Human-in-the-Loop (React)
-
-This skill builds on `copilotkit/provider-setup`, `copilotkit/client-side-tools`,
-and `copilotkit/rendering-tool-calls`.
-
-`useHumanInTheLoop` is `useFrontendTool` minus the `handler` plus a
-`render` that receives a `respond` function. The hook synthesizes a
-Promise-based handler — the Promise resolves when `respond(result)` is
-called. No `respond` call → infinite hang.
-
-Status is camelCase: `"inProgress" | "executing" | "complete"`. `respond`
-is `undefined` except during `"executing"`.
-
-## UI-kit detection rule
-
-Before writing the approval UI, check the consumer's `package.json` for a
-UI kit (shadcn `AlertDialog`, MUI `Dialog`, Chakra `Modal`, Ant `Modal`,
-Mantine `Modal`) and reuse it. Don't hand-roll an overlay.
-
-## Setup
-
-```tsx
-"use client";
-import { useHumanInTheLoop } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle,
-} from "@/components/ui/alert-dialog";
-
-export function DeleteConfirmHITL() {
-  useHumanInTheLoop({
-    name: "confirmDelete",
-    description: "Confirm a destructive delete with the user",
-    parameters: z.object({ id: z.string(), label: z.string() }),
-    render: ({ status, args, respond }) => (
-      <AlertDialog open>
-        <AlertDialogContent>
-          <AlertDialogHeader>
-            <AlertDialogTitle>Delete {args.label}?</AlertDialogTitle>
-            <AlertDialogDescription>
-              This action cannot be undone.
-            </AlertDialogDescription>
-          </AlertDialogHeader>
-          <AlertDialogFooter>
-            <AlertDialogCancel
-              disabled={status !== "executing"}
-              onClick={() => respond?.("denied")}
-            >
-              Cancel
-            </AlertDialogCancel>
-            <AlertDialogAction
-              disabled={status !== "executing"}
-              onClick={() => respond?.("approved")}
-            >
-              Delete
-            </AlertDialogAction>
-          </AlertDialogFooter>
-        </AlertDialogContent>
-      </AlertDialog>
-    ),
-  });
-  return null;
-}
-```
-
-## Core Patterns
-
-### Always call `respond` in every branch
-
-```tsx
-render: ({ status, args, respond }) => {
-  if (status !== "executing" || !respond) {
-    return <div>Awaiting decision…</div>;
-  }
-  return (
-    <div>
-      <button onClick={() => respond("approved")}>Approve</button>
-      <button onClick={() => respond("denied")}>Reject</button>
-      <button onClick={() => respond({ action: "skip", reason: "timeout" })}>
-        Skip
-      </button>
-    </div>
-  );
-};
-```
-
-### Abort the run on unmount so threads unlock
-
-```tsx
-import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";
-import { useEffect, useRef } from "react";
-
-function HITLHost() {
-  const { agent } = useAgent({
-    agentId: "default",
-    updates: [UseAgentUpdate.OnRunStatusChanged],
-  });
-  // Track isRunning in a ref so the unmount cleanup reads the latest value
-  // without re-firing on every transition.
-  const runningRef = useRef(false);
-  useEffect(() => {
-    runningRef.current = agent.isRunning;
-  }, [agent.isRunning]);
-
-  useEffect(() => {
-    return () => {
-      if (runningRef.current) agent.abortRun();
-    };
-  }, [agent]);
-
-  return <DeleteConfirmHITL />;
-}
-```
-
-`useAgent` returns `{ agent }` only — run status lives on `agent.isRunning`.
-Depending the cleanup effect directly on `agent.isRunning` would fire the
-cleanup on every status flip (not just unmount), aborting active runs.
-The ref pattern captures the latest value while the cleanup runs only
-when the host component truly unmounts.
-
-### Collect structured user input mid-run
-
-```tsx
-useHumanInTheLoop({
-  name: "askUserForPriority",
-  parameters: z.object({ taskId: z.string() }),
-  render: ({ status, args, respond }) => {
-    if (status !== "executing" || !respond) return <div>Waiting…</div>;
-    return (
-      <div>
-        {["low", "medium", "high"].map((p) => (
-          <button
-            key={p}
-            onClick={() => respond({ taskId: args.taskId, priority: p })}
-          >
-            {p}
-          </button>
-        ))}
-      </div>
-    );
-  },
-});
-```
-
-## Common Mistakes
-
-### CRITICAL — Never calling `respond()`
-
-Wrong:
-
-```tsx
-useHumanInTheLoop({
-  name: "confirmDelete",
-  parameters: z.object({ id: z.string() }),
-  render: ({ args, status, respond }) => (
-    <div>
-      <p>Delete {args.id}?</p>
-      <button>OK</button>
-    </div>
-  ),
-});
-```
-
-Correct:
-
-```tsx
-useHumanInTheLoop({
-  name: "confirmDelete",
-  parameters: z.object({ id: z.string() }),
-  render: ({ args, status, respond }) => (
-    <div>
-      <p>Delete {args.id}?</p>
-      <button onClick={() => respond?.("approved")}>OK</button>
-      <button onClick={() => respond?.("denied")}>Cancel</button>
-    </div>
-  ),
-});
-```
-
-The synthesized handler returns a Promise that resolves only when `respond`
-is called. Never calling it (including reject / cancel paths) hangs the
-run indefinitely and leaves the thread locked on the server.
-
-Source: `packages/react-core/src/v2/hooks/use-human-in-the-loop.tsx:13-26`
-
-### CRITICAL — Writing a custom overlay when the app has a Dialog primitive
-
-Wrong:
-
-```tsx
-render: ({ respond }) => (
-  <div style={{ position: "fixed", inset: 0, background: "rgba(0,0,0,0.5)" }}>
-    …
-  </div>
-);
-```
-
-Correct:
-
-```tsx
-import {
-  AlertDialog,
-  AlertDialogContent,
-  AlertDialogAction,
-} from "@/components/ui/alert-dialog";
-
-render: ({ respond }) => (
-  <AlertDialog open>
-    <AlertDialogContent>
-      …
-      <AlertDialogAction onClick={() => respond?.("approved")}>
-        OK
-      </AlertDialogAction>
-    </AlertDialogContent>
-  </AlertDialog>
-);
-```
-
-Check `package.json` for shadcn / MUI / Chakra / Ant / Mantine before
-writing an overlay. Their dialog primitives handle focus trapping,
-escape-to-close, and accessibility — raw JSX skips all of that.
-
-Source: maintainer interview (Phase 2c)
-
-### HIGH — Calling `respond` during `inProgress` or `complete`
-
-Wrong:
-
-```tsx
-render: ({ status, respond }) => (
-  <button onClick={() => (respond as any)("yes")}>Yes</button>
-);
-```
-
-Correct:
-
-```tsx
-render: ({ status, respond }) =>
-  status === "executing" && respond ? (
-    <button onClick={() => respond("yes")}>Yes</button>
-  ) : (
-    <p>Waiting…</p>
-  );
-```
-
-`respond` is `undefined` outside `status === "executing"`. Widening it to
-`any` silently no-ops — the button click appears to work, but nothing
-resolves the Promise.
-
-Source: `packages/react-core/src/v2/types/human-in-the-loop.ts:8-32`
-
-### HIGH — Unmounting the render mid-executing
-
-Wrong:
-
-```tsx
-// User clicks away to a different route while the agent is waiting on respond()
-```
-
-Correct:
-
-```tsx
-// Keep the HITL prompt at a layout level that persists across route changes, OR abort on unmount:
-const { agent } = useAgent({
-  agentId: "default",
-  updates: [UseAgentUpdate.OnRunStatusChanged],
-});
-const runningRef = useRef(false);
-useEffect(() => {
-  runningRef.current = agent.isRunning;
-}, [agent.isRunning]);
-useEffect(
-  () => () => {
-    if (runningRef.current) agent.abortRun();
-  },
-  [agent],
-);
-```
-
-`useHumanInTheLoop` removes its renderer on unmount (unlike
-`useFrontendTool`, which keeps renderers for history). If the renderer
-unmounts mid-`executing`, the pending Promise is abandoned and the run
-hangs. Either lift the HITL UI to a layout-level component, or abort the
-run on unmount.
-
-Source: `packages/react-core/src/v2/hooks/use-human-in-the-loop.tsx:76-80`
-
-### MEDIUM — Using hyphenated `"in-progress"` status
-
-Wrong:
-
-```tsx
-render: ({ status }) => (status === "in-progress" ? <Spinner /> : <Form />);
-```
-
-Correct:
-
-```tsx
-render: ({ status }) => (status === "inProgress" ? <Spinner /> : <Form />);
-```
-
-Same camelCase rule as `rendering-tool-calls`: the discriminated union
-only matches `"inProgress" | "executing" | "complete"`.
-
-Source: `packages/react-core/src/v2/types/human-in-the-loop.ts:8-32`