@copilotkit/react-core 1.71.0 → 1.71.1

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`

package/skills/react-core/references/provider-setup.md

@@ -1,358 +0,0 @@
-# CopilotKit Provider Setup (React)
-
-Mount the `CopilotKit` provider (from `@copilotkit/react-core/v2`) once
-near the root of the React tree. Every CopilotKit hook (`useAgent`,
-`useFrontendTool`, `useRenderTool`, etc.) and every chat component
-(`CopilotChat`, `CopilotPopup`, `CopilotSidebar`) must be rendered inside
-this provider.
-
-> **Which provider component?** Use `CopilotKit` imported from `@copilotkit/react-core/v2`. It is the compatibility bridge across v1 and v2 and a superset of `CopilotKitProvider`, which is also exported from `/v2` and is a perfectly good choice if you do not need the v1 bridge. Do **not** use `CopilotKit` from the package root (`@copilotkit/react-core`) — that is the legacy v1 entry point and will not work with v2 hooks or components.
-
-## Transport
-
-You do not normally configure the transport. Both providers leave
-`useSingleEndpoint` unset by default, and the client then negotiates: it probes
-`GET {runtimeUrl}/info` and falls back to the single-route `POST` envelope. That
-works against a multi-route handler (the default for every `createCopilot*`
-handler) and a single-route one alike.
-
-Set the prop only to pin one mode deliberately:
-
-| `useSingleEndpoint`       | Transport                    | Requires                                      |
-| ------------------------- | ---------------------------- | --------------------------------------------- |
-| omitted (**recommended**) | negotiated                   | either handler mode                           |
-| `{true}`                  | single-route `POST` envelope | a handler mounted with `mode: "single-route"` |
-| `{false}`                 | multi-route REST routes      | a handler in the default multi-route mode     |
-
-Pinning the wrong one is the classic first-run failure: a single-route envelope
-sent to a multi-route runtime matches no route, so the runtime 404s while
-`GET /info` still returns 200 and the app looks connected. If you see that, drop
-the prop rather than guessing the other value.
-
-All v2 imports use the `@copilotkit/react-core/v2` subpath. Imports from the
-package root are v1 and will not work with v2 hooks or components.
-
-## Setup
-
-### Next.js App Router (and any RSC-based framework)
-
-`@copilotkit/react-core/v2` is marked `"use client"`. You must mount the
-provider from a client component, not a server component. The cleanest
-pattern is a dedicated client-only `providers.tsx`.
-
-```tsx
-// app/providers.tsx
-"use client";
-
-import { CopilotKit } from "@copilotkit/react-core/v2";
-import "@copilotkit/react-core/v2/styles.css";
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <CopilotKit
-      runtimeUrl="/api/copilotkit"
-      credentials="include"
-      onError={({ code, error, context }) => {
-        console.error("[copilotkit]", code, error, context);
-      }}
-    >
-      {children}
-    </CopilotKit>
-  );
-}
-```
-
-For auth headers that change over the session (rotating bearer tokens,
-refreshed cookies), see the "Stable headers for rotating auth tokens"
-pattern below. Avoid putting a `useMemo(() => ({ Authorization: ... }),
-[])` on the provider — an empty deps array captures the token at mount
-and never refreshes.
-
-```tsx
-// app/layout.tsx — server component
-import { Providers } from "./providers";
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang="en">
-      <body>
-        <Providers>{children}</Providers>
-      </body>
-    </html>
-  );
-}
-```
-
-### Vite / React Router v7 / SPA
-
-```tsx
-import { CopilotKit } from "@copilotkit/react-core/v2";
-import "@copilotkit/react-core/v2/styles.css";
-
-export function App({ children }: { children: React.ReactNode }) {
-  return <CopilotKit runtimeUrl="/api/copilotkit">{children}</CopilotKit>;
-}
-```
-
-### SPA with CopilotKit Intelligence (no self-hosted runtime)
-
-```tsx
-<CopilotKit publicLicenseKey="ck_pub_..." />
-```
-
-`publicLicenseKey` is the canonical prop for running CopilotKit from a
-pure client bundle. `publicApiKey` is a deprecated alias that resolves to
-the same value — accept it in old code, but always write
-`publicLicenseKey` in new code.
-
-## Core Patterns
-
-### Stable headers for rotating auth tokens
-
-For tokens that change during the session, use the imperative setter instead
-of re-rendering the provider with a new `headers` prop.
-
-```tsx
-"use client";
-import { useCopilotKit } from "@copilotkit/react-core/v2";
-import { useEffect } from "react";
-
-export function AuthTokenSync({ token }: { token: string | null }) {
-  const { copilotkit } = useCopilotKit();
-  useEffect(() => {
-    // setHeaders is an overwrite, not a merge — spread the current headers so
-    // entries set elsewhere (e.g. the public license key) survive. A `null`
-    // value clears that header, so logging out removes `Authorization` instead
-    // of sending an empty one.
-    copilotkit.setHeaders({
-      ...copilotkit.headers,
-      Authorization: token ? `Bearer ${token}` : null,
-    });
-  }, [copilotkit, token]);
-  return null;
-}
-```
-
-`setHeaders` accepts `null`/`undefined` values and drops those keys, so passing
-`Authorization: null` is the supported way to clear a header. Setting it to an
-empty string would keep the header present with a blank value.
-
-Do not set the same header through both the `headers` prop and imperative
-`setHeaders`. Whenever any provider prop changes, the provider calls
-`setHeaders` with its prop-derived headers — a full overwrite that drops every
-imperatively-set header, not just keys the prop also defines. Keep rotating
-values like the auth token out of the `headers` prop and manage them only
-through `setHeaders` (as above).
-
-### Global error handler
-
-`onError` fires for every `CopilotKitCoreErrorCode` emitted by core. Keeps
-UI from getting stuck in "connecting..." when the runtime URL is wrong or
-CORS is misconfigured.
-
-```tsx
-<CopilotKit
-  runtimeUrl="/api/copilotkit"
-  onError={({ code, error, context }) => {
-    telemetry.capture({ code, message: error.message, context });
-  }}
-/>
-```
-
-### Sharing app properties with every run
-
-`properties` flows to the runtime on each agent run — useful for tenant IDs,
-feature flags, or anything the server needs.
-
-```tsx
-const properties = useMemo(
-  () => ({ tenantId: user.tenantId, locale: user.locale }),
-  [user.tenantId, user.locale],
-);
-
-<CopilotKit runtimeUrl="/api/copilotkit" properties={properties} />;
-```
-
-## Common Mistakes
-
-### CRITICAL — Mounting the provider from a Server Component
-
-Wrong:
-
-```tsx
-// app/page.tsx (server component — no "use client")
-import { CopilotKit } from "@copilotkit/react-core/v2";
-
-export default function Page() {
-  return <CopilotKit runtimeUrl="/api/copilotkit">...</CopilotKit>;
-}
-```
-
-Correct:
-
-```tsx
-// app/providers.tsx
-"use client";
-import { CopilotKit } from "@copilotkit/react-core/v2";
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return <CopilotKit runtimeUrl="/api/copilotkit">{children}</CopilotKit>;
-}
-
-// app/layout.tsx imports <Providers>.
-```
-
-`@copilotkit/react-core/v2` begins with `"use client"`. Importing it from a
-server component silently strips interactivity — the provider renders but
-none of the hooks wire up.
-
-Source: `packages/react-core/src/v2/index.ts:1`
-
-### CRITICAL — Using `agents__unsafe_dev_only` or `selfManagedAgents` in production
-
-Wrong:
-
-```tsx
-<CopilotKit
-  agents__unsafe_dev_only={{
-    default: new BuiltInAgent({ apiKey: process.env.OPENAI_KEY! }),
-  }}
-/>
-// or the alias (same thing):
-<CopilotKit
-  selfManagedAgents={{ default: new BuiltInAgent({ apiKey: "..." }) }}
-/>
-```
-
-Correct:
-
-```tsx
-// Route through a runtime that keeps secrets server-side:
-<CopilotKit runtimeUrl="/api/copilotkit" />
-
-// Or for a pure SPA, use CopilotKit Intelligence:
-<CopilotKit publicLicenseKey="ck_pub_..." />
-```
-
-Both props are aliases for the same dev-only mechanism and ship any embedded
-credentials to the browser bundle. Never use either for production agents.
-
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:136-138,393`
-
-### HIGH — Inline object props rebuilt every render
-
-Wrong:
-
-```tsx
-<CopilotKit
-  runtimeUrl="/api/copilotkit"
-  headers={{ Authorization: `Bearer ${token}` }}
-  properties={{ tenantId: user.tenantId }}
-/>
-```
-
-Correct:
-
-```tsx
-const headers = useMemo(() => ({ Authorization: `Bearer ${token}` }), [token]);
-const properties = useMemo(
-  () => ({ tenantId: user.tenantId }),
-  [user.tenantId],
-);
-
-<CopilotKit
-  runtimeUrl="/api/copilotkit"
-  headers={headers}
-  properties={properties}
-/>;
-```
-
-New object identity on every render causes the provider to diff-churn
-internal state and may thrash tool/renderer registration. `useStableArrayProp`
-also logs a `console.error` when array-prop shape changes without
-memoization.
-
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:324-340,399-410`
-
-### HIGH — Missing `onError` leaves users stuck in "connecting..."
-
-Wrong:
-
-```tsx
-<CopilotKit runtimeUrl="/api/copilotkit" />
-```
-
-Correct:
-
-```tsx
-<CopilotKit
-  runtimeUrl="/api/copilotkit"
-  onError={({ code, error, context }) => {
-    telemetry.capture({ code, error, context });
-  }}
-/>
-```
-
-Without `onError`, connection failures (bad runtime URL, CORS, network) keep
-the provider in a provisional state with `ProxiedCopilotRuntimeAgent`
-instances that never resolve. The chat UI keeps showing "connecting..."
-forever and users never see the actual error.
-
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx:638-660`
-
-### HIGH — Writing `publicApiKey` in new code
-
-Wrong:
-
-```tsx
-<CopilotKit publicApiKey="ck_pub_..." />
-```
-
-Correct:
-
-```tsx
-<CopilotKit publicLicenseKey="ck_pub_..." />
-```
-
-`publicApiKey` still works as a deprecated alias, but `publicLicenseKey`
-is the canonical name. The `CopilotKit` provider resolves
-`publicLicenseKey || publicApiKey`. Always write the canonical form in
-new code.
-
-Source: `packages/react-core/src/v1-deprecated/components/copilot-provider/copilotkit.tsx:172`
-
-### MEDIUM — Putting the provider below a layout that uses CopilotKit
-
-Wrong:
-
-```tsx
-<html>
-  <body>
-    <Header>{/* Header uses useFrontendTool internally */}</Header>
-    <CopilotKit>{children}</CopilotKit>
-  </body>
-</html>
-```
-
-Correct:
-
-```tsx
-<html>
-  <body>
-    <CopilotKit>
-      <Header />
-      {children}
-    </CopilotKit>
-  </body>
-</html>
-```
-
-Any component that calls `useCopilotKit`, `useFrontendTool`, `useAgent`, or
-any other CopilotKit hook must be a descendant of the `CopilotKit`
-provider. Placing the provider beside or below a consumer throws at mount.
-
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (context)