Implement state management (#15)

Author: mme

PLAN.md

@@ -0,0 +1,17 @@
+# Plan: Centralize render tool management in CopilotKitCoreReact
+
+## Objective
+Finish moving `renderToolCalls` / `currentRenderToolCalls` handling from `CopilotKitProvider` state into `CopilotKitCoreReact`, letting React consumers react to core-managed updates while keeping the core API as-is.
+
+## Remaining Workstreams
+1. **Provider refactor** – replace the provider’s `CopilotKitCore` instance with a single `CopilotKitCoreReact`, keep the static render list fixed from construction, and push dynamic renderer updates through `setRenderToolCalls`. Mirror updates into React by reusing the provider’s existing merge logic inside a lightweight subscription effect.
+2. **Hooks & utilities** – update `useFrontendTool`, `useHumanInTheLoop`, and related helpers to manage their merge bookkeeping locally and call `copilotkit.setRenderToolCalls` with the updated dynamic list.
+3. **Surface & docs** – adjust context types, tests, and documentation to reflect the new contract (no more `setCurrentRenderToolCalls`).
+4. **Validation** – run the focused provider/chat rendering test suites and spot-check wildcard & human-in-the-loop flows.
+
+## Implementation Details
+- In `CopilotKitProvider`, instantiate `CopilotKitCoreReact` (instead of `CopilotKitCore`), replace the `useState` store with a `useEffect`-driven subscription that listens for `onRenderToolCallsChanged` and forces a re-render (e.g., via `useReducer`). Use memoized helpers to compute the dynamic list, call `copilotkit.setRenderToolCalls(dynamicList)` when it changes, and read the combined list directly from the core.
+- Update the context value to share `copilotkit`, the merged render list from the core, and any helper needed for hooks to compute their dynamic lists; drop `setCurrentRenderToolCalls` from the public surface.
+- Adjust hooks to pull the current dynamic list, perform their simple merge/replacement locally, and push the result back through `setRenderToolCalls`; ensure cleanup maintains historical renderers where required.
+- Refresh docs/tests to cover the new API surface and ensure wildcard precedence expectations still hold.
+- Validate with targeted unit/integration tests (e.g., `pnpm test --filter CopilotKitProvider`, chat rendering suites).

apps/docs/reference/copilotkit-provider.mdx

@@ -113,7 +113,7 @@ const devAgent = new HttpAgent({
 
 ### renderToolCalls
 
-`ReactToolCallRender[]` **(optional)**
+`ReactToolCallRenderer[]` **(optional)**
 
 A static list of components to render when specific tools are called. Enables visual feedback for tool execution.
 
@@ -210,9 +210,9 @@ The provider makes a `CopilotKitContextValue` available to child components thro
 ```typescript
 interface CopilotKitContextValue {
   copilotkit: CopilotKitCore;
-  renderToolCalls: ReactToolCallRender<any>[];
-  currentRenderToolCalls: ReactToolCallRender<unknown>[];
-  setCurrentRenderToolCalls: React.Dispatch<React.SetStateAction<ReactToolCallRender<unknown>[]>>;
+  renderToolCalls: ReactToolCallRenderer<any>[];
+  currentRenderToolCalls: ReactToolCallRenderer<unknown>[];
+  setCurrentRenderToolCalls: React.Dispatch<React.SetStateAction<ReactToolCallRenderer<unknown>[]>>;
 }
 ```
 

apps/docs/reference/use-copilotkit.mdx

@@ -47,20 +47,20 @@ for interacting with CopilotKit programmatically.
 
 ### renderToolCalls
 
-`ReactToolCallRender<any>[]`
+`ReactToolCallRenderer<any>[]`
 
 An array of tool call render configurations defined at the provider level. These are used to render visual feedback when
 tools are executed.
 
 ### currentRenderToolCalls
 
-`ReactToolCallRender<unknown>[]`
+`ReactToolCallRenderer<unknown>[]`
 
 The current list of render tool calls, including both static configurations and dynamically registered ones.
 
 ### setCurrentRenderToolCalls
 
-`React.Dispatch<React.SetStateAction<ReactToolCallRender<unknown>[]>>`
+`React.Dispatch<React.SetStateAction<ReactToolCallRenderer<unknown>[]>>`
 
 A setter function to update the current render tool calls. Useful for dynamically adding or removing tool renderers.
 

apps/docs/reference/use-render-tool-call.mdx

@@ -140,9 +140,9 @@ The hook works with tool renderers defined at various levels:
 Renderers defined in `CopilotKitProvider`:
 
 ```tsx
-import { CopilotKitProvider, defineToolCallRender } from "@copilotkitnext/react";
+import { CopilotKitProvider, defineToolCallRenderer } from "@copilotkitnext/react";
 
-const searchRenderer = defineToolCallRender({
+const searchRenderer = defineToolCallRenderer({
   name: "search",
   render: ({ args, status }) => <SearchDisplay {...args} status={status} />,
 });
@@ -180,7 +180,7 @@ function DynamicTool() {
 A fallback renderer for unmatched tools:
 
 ```tsx
-const wildcardRenderer = defineToolCallRender({
+const wildcardRenderer = defineToolCallRenderer({
   name: "*",
   render: ({ name, args, status }) => (
     <div className="unknown-tool">

apps/react/demo/src/app/api/copilotkit/[[...slug]]/route.ts

@@ -11,9 +11,8 @@ const getModelConfig = () => {
   } else if (process.env.GOOGLE_API_KEY?.trim()) {
     return "google/gemini-2.5-pro";
   }
-  throw new Error(
-    "No API key found. Please set OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY environment variable.",
-  );
+  // Default to OpenAI (will fail at runtime if no key is set)
+  return "openai/gpt-4o";
 };
 
 const agent = new BasicAgent({

apps/react/demo/src/app/page.tsx

@@ -5,7 +5,7 @@ import {
   CopilotChat,
   CopilotKitProvider,
   useFrontendTool,
-  defineToolCallRender,
+  defineToolCallRenderer,
   useConfigureSuggestions,
 } from "@copilotkitnext/react";
 import { z } from "zod";
@@ -15,7 +15,7 @@ export const dynamic = "force-dynamic";
 
 export default function Home() {
   // Define a wildcard renderer for any undefined tools
-  const wildcardRenderer = defineToolCallRender({
+  const wildcardRenderer = defineToolCallRenderer({
     name: "*",
     // No args needed for wildcard - defaults to z.any()
     render: ({ name, args, status }) => (

apps/react/demo/src/app/sidebar/page.tsx

@@ -3,7 +3,7 @@
 import {
   CopilotKitProvider,
   CopilotSidebar,
-  defineToolCallRender,
+  defineToolCallRenderer,
   useConfigureSuggestions,
   useFrontendTool,
 } from "@copilotkitnext/react";
@@ -12,7 +12,7 @@ import { z } from "zod";
 export const dynamic = "force-dynamic";
 
 export default function SidebarDemoPage() {
-  const wildcardRenderer = defineToolCallRender({
+  const wildcardRenderer = defineToolCallRenderer({
     name: "*",
     render: ({ name, args, status }) => (
       <div className="rounded-lg border border-slate-200 bg-slate-50 p-3 text-sm text-slate-700 shadow-sm">

docs/REACT_API.md

@@ -10,7 +10,7 @@ Creates and owns a `CopilotKitCore` instance that manages agents, frontend tools
 - `headers?: Record<string,string>` – request headers forwarded with runtime calls; default `{}`.
 - `properties?: Record<string,unknown>` – runtime metadata payload; default `{}`.
 - `agents?: Record<string, AbstractAgent>` – preinstantiated agents, keyed by id.
-- `renderToolCalls?: ReactToolCallRender[]` – static set of tool renderers. The provider expects a stable array identity; changing the structure logs a console error.
+- `renderToolCalls?: ReactToolCallRenderer[]` – static set of tool renderers. The provider expects a stable array identity; changing the structure logs a console error.
 - `frontendTools?: ReactFrontendTool[]` – static tool handlers defined up front. Like `renderToolCalls`, the array should be stable.
 - `humanInTheLoop?: ReactHumanInTheLoop[]` – declarative human-in-the-loop tool definitions. Each becomes both a tool handler and a tool call renderer.
 
@@ -29,8 +29,8 @@ import { CopilotKitProvider } from "@copilotkitnext/react";
 ### `useCopilotKit`
 Context hook that returns:
 - `copilotkit: CopilotKitCore` – the live core instance.
-- `renderToolCalls: ReactToolCallRender[]` – full render list derived from provider props.
-- `currentRenderToolCalls: ReactToolCallRender[]` – current stateful render list used by `useRenderToolCall`.
+- `renderToolCalls: ReactToolCallRenderer[]` – full render list derived from provider props.
+- `currentRenderToolCalls: ReactToolCallRenderer[]` – current stateful render list used by `useRenderToolCall`.
 - `setCurrentRenderToolCalls` – setter for augmenting renderers (used internally by tooling hooks).
 
 The hook subscribes to runtime load events so components re-render if the core finishes loading or fails to load.