npm - @copilotkit/react-core - Versions diffs - 1.70.3 → 1.71.1 - Mend

@copilotkit/react-core 1.70.3 → 1.71.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

package/dist/{copilotkit-BU3OvveB.cjs → copilotkit-BkVEkUS0.cjs} +369 -154
package/dist/copilotkit-BkVEkUS0.cjs.map +1 -0
package/dist/{copilotkit-Bs98akp9.d.mts → copilotkit-ChjzWqn6.d.mts} +33 -8
package/dist/copilotkit-ChjzWqn6.d.mts.map +1 -0
package/dist/{copilotkit-Ap_yisA5.mjs → copilotkit-D5BTo0YG.mjs} +368 -153
package/dist/copilotkit-D5BTo0YG.mjs.map +1 -0
package/dist/{copilotkit-X2eGbOwf.d.cts → copilotkit-DCIXZawe.d.cts} +33 -8
package/dist/copilotkit-DCIXZawe.d.cts.map +1 -0
package/dist/index.cjs +3 -3
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +1 -1
package/dist/index.d.mts +1 -1
package/dist/index.mjs +4 -4
package/dist/index.mjs.map +1 -1
package/dist/index.umd.js +180 -139
package/dist/index.umd.js.map +1 -1
package/dist/v2/context.cjs +4 -0
package/dist/v2/context.cjs.map +1 -1
package/dist/v2/context.d.cts +3 -1
package/dist/v2/context.d.cts.map +1 -1
package/dist/v2/context.d.mts +3 -1
package/dist/v2/context.d.mts.map +1 -1
package/dist/v2/context.mjs +3 -1
package/dist/v2/context.mjs.map +1 -1
package/dist/v2/headless.cjs +20 -5
package/dist/v2/headless.cjs.map +1 -1
package/dist/v2/headless.d.cts +9 -4
package/dist/v2/headless.d.cts.map +1 -1
package/dist/v2/headless.d.mts +9 -4
package/dist/v2/headless.d.mts.map +1 -1
package/dist/v2/headless.mjs +21 -6
package/dist/v2/headless.mjs.map +1 -1
package/dist/v2/index.cjs +1 -1
package/dist/v2/index.css +1 -1
package/dist/v2/index.d.cts +1 -1
package/dist/v2/index.d.mts +1 -1
package/dist/v2/index.mjs +1 -1
package/dist/v2/index.umd.js +495 -278
package/dist/v2/index.umd.js.map +1 -1
package/package.json +8 -9
package/dist/copilotkit-Ap_yisA5.mjs.map +0 -1
package/dist/copilotkit-BU3OvveB.cjs.map +0 -1
package/dist/copilotkit-Bs98akp9.d.mts.map +0 -1
package/dist/copilotkit-X2eGbOwf.d.cts.map +0 -1
package/skills/react-core/SKILL.md +0 -110
package/skills/react-core/references/agent-access.md +0 -355
package/skills/react-core/references/attachments.md +0 -311
package/skills/react-core/references/capabilities.md +0 -138
package/skills/react-core/references/chat-components.md +0 -229
package/skills/react-core/references/client-side-tools.md +0 -358
package/skills/react-core/references/custom-message-renderers.md +0 -223
package/skills/react-core/references/debug-mode.md +0 -140
package/skills/react-core/references/human-in-the-loop.md +0 -312
package/skills/react-core/references/provider-setup.md +0 -358
package/skills/react-core/references/rendering-activity-messages.md +0 -201
package/skills/react-core/references/rendering-tool-calls.md +0 -319
package/skills/react-core/references/suggestions.md +0 -211
package/skills/react-core/references/switching-agents-recipes.md +0 -161
package/skills/react-core/references/switching-agents.md +0 -240
package/skills/react-core/references/threads.md +0 -289

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

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

package/skills/react-core/references/rendering-activity-messages.md DELETED Viewed

@@ -1,201 +0,0 @@
-# CopilotKit Rendering Activity Messages (React)
-This skill builds on `copilotkit/provider-setup`. Activity-message
-renderers are registered as entries in the `renderActivityMessages` array
-prop on the `CopilotKit` provider and resolved at render time by
-`useRenderActivityMessage` (consumed internally by chat components).
-User renderers are placed first in the array so they override the built-in
-`MCPAppsActivityType` and `OpenGenerativeUIActivityType` renderers for the
-same `activityType`.
-Resolver order:
-1. `(activityType, agentId)` match
-2. `(activityType, unscoped)` match
-3. `'*'` wildcard
-4. `null`
-## Setup
-```tsx
-"use client";
-import { CopilotKit } from "@copilotkit/react-core/v2";
-import type { ReactActivityMessageRenderer } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-import { useMemo } from "react";
-import { Card, CardContent } from "@/components/ui/card";
-import { Progress } from "@/components/ui/progress";
-const progressRenderer: ReactActivityMessageRenderer<{
-  percent: number;
-  label: string;
-}> = {
-  activityType: "progress",
-  content: z.object({ percent: z.number().min(0).max(1), label: z.string() }),
-  render: ({ content }) => (
-    <Card>
-      <CardContent>
-        <div>{content.label}</div>
-        <Progress value={content.percent * 100} />
-      </CardContent>
-    </Card>
-  ),
-};
-export function Providers({ children }: { children: React.ReactNode }) {
-  const renderers = useMemo(() => [progressRenderer], []);
-  return (
-    <CopilotKit runtimeUrl="/api/copilotkit" renderActivityMessages={renderers}>
-      {children}
-    </CopilotKit>
-  );
-}
-```
-## Core Patterns
-### Agent-scoped renderer
-```tsx
-const researchProgress: ReactActivityMessageRenderer<{ step: string }> = {
-  activityType: "research-step",
-  agentId: "research",
-  content: z.object({ step: z.string() }),
-  render: ({ content }) => <ResearchStepBadge step={content.step} />,
-};
-```
-### Override a built-in (MCP Apps)
-Place your renderer for the same `activityType` — user renderers are
-evaluated before built-ins.
-```tsx
-import { MCPAppsActivityType } from "@copilotkit/react-core/v2";
-const customMcpRenderer: ReactActivityMessageRenderer<unknown> = {
-  activityType: MCPAppsActivityType, // "mcp-apps" — must match the exported constant
-  content: z.unknown(),
-  render: ({ content, message }) => <CustomMCPCard payload={content} />,
-};
-```
-### Using the hook directly (custom chat surface)
-```tsx
-import { useRenderActivityMessage } from "@copilotkit/react-core/v2";
-import type { ActivityMessage } from "@ag-ui/core";
-export function ActivityList({ messages }: { messages: ActivityMessage[] }) {
-  const { renderActivityMessage } = useRenderActivityMessage();
-  return (
-    <div>
-      {messages.map((m) => (
-        <div key={m.id}>{renderActivityMessage(m)}</div>
-      ))}
-    </div>
-  );
-}
-```
-## Common Mistakes
-### HIGH — Incompatible content schema
-Wrong:
-```tsx
-// Renderer expects `pct`
-const r: ReactActivityMessageRenderer<{ pct: number }> = {
-  activityType: "progress",
-  content: z.object({ pct: z.number() }),
-  render: ({ content }) => <Bar value={content.pct} />,
-};
-// But the server emits { percent: 0.5 } — mismatched field name
-```
-Correct:
-```tsx
-const r: ReactActivityMessageRenderer<{ percent: number }> = {
-  activityType: "progress",
-  content: z.object({ percent: z.number() }),
-  render: ({ content }) => <Bar value={content.percent} />,
-};
-```
-`safeParse` is called on every incoming activity message. Mismatched
-schemas return `null` with only a `console.warn("Failed to parse content
-for activity message …")` — the UI renders nothing and the failure is
-silent unless you read the console.
-Source: `packages/react-core/src/v2/hooks/use-render-activity-message.tsx:44-50`
-### MEDIUM — Side effects in `render`
-Wrong:
-```tsx
-render: ({ content }) => {
-  trackEvent(content); // fires on every re-render
-  return <Badge>{content.label}</Badge>;
-};
-```
-Wrong (Rules of Hooks violation):
-```tsx
-render: ({ content }) => {
-  // `render` is invoked as a plain function by the resolver — NOT as a
-  // React component — so calling hooks directly inside it is illegal.
-  useEffect(() => trackEvent(content), [content]);
-  return <Badge>{content.label}</Badge>;
-};
-```
-Correct:
-```tsx
-function TrackedBadge({ content }: { content: { label: string } }) {
-  useEffect(() => {
-    trackEvent(content);
-  }, [content]);
-  return <Badge>{content.label}</Badge>;
-}
-// In the renderer:
-render: ({ content }) => <TrackedBadge content={content} />;
-```
-Activity-message renderers re-render on every message-list tick. Side
-effects in the render body fire repeatedly. Hooks cannot be called
-directly inside `render` because the resolver invokes it as a plain
-function; hoist the effect into a wrapper component that React mounts as
-a real element.
-Source: `packages/react-core/src/v2/hooks/use-render-activity-message.tsx`
-### MEDIUM — Building the `renderActivityMessages` array inline
-Wrong:
-```tsx
-<CopilotKit
-  runtimeUrl="/api/copilotkit"
-  renderActivityMessages={[progressRenderer, customMcpRenderer]}
-/>
-```
-Correct:
-```tsx
-const renderers = useMemo(() => [progressRenderer, customMcpRenderer], []);
-<CopilotKit runtimeUrl="/api/copilotkit" renderActivityMessages={renderers} />;
-```
-The provider uses `useStableArrayProp` and console-errors when a new array
-identity appears every render. Memoize or hoist the array to module
-scope.
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (useStableArrayProp)