refactor: extract react-core context and headless hook exports

Extract CopilotKitContext, useCopilotKit, and LicenseContext into
src/v2/context.ts. Add src/v2/headless.ts barrel export for
platform-agnostic hooks. Add v2/context and v2/headless entry
points to tsdown config and package.json exports. Update all hook
imports to use the new context module. Always subscribe to onError
in web provider (matching RN pattern). Use batchedForceUpdate for
onMessagesChanged. Replace extraDeps spread with JSON.stringify in
useFrontendTool and useRenderTool dependency arrays.

Author: mxmzb

packages/react-core/package.json

@@ -46,6 +46,14 @@
       "require": "./dist/v2/index.cjs"
     },
     "./package.json": "./package.json",
+    "./v2/context": {
+      "import": "./dist/v2/context.mjs",
+      "require": "./dist/v2/context.cjs"
+    },
+    "./v2/headless": {
+      "import": "./dist/v2/headless.mjs",
+      "require": "./dist/v2/headless.cjs"
+    },
     "./v2/styles.css": "./dist/v2/index.css"
   },
   "publishConfig": {

packages/react-core/src/v2/context.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { createContext, useContext, useEffect, useReducer } from "react";
+import { CopilotKitCoreReact } from "./lib/react-core";
+import type { CopilotKitCoreReactConfig } from "./lib/react-core";
+import type { LicenseContextValue } from "@copilotkit/shared";
+
+// Re-export so headless.ts (and consumers) reference the same type declaration.
+export { CopilotKitCoreReact };
+export type { CopilotKitCoreReactConfig };
+
+export interface CopilotKitContextValue {
+  copilotkit: CopilotKitCoreReact;
+  /**
+   * Set of tool call IDs currently being executed.
+   * This is tracked at the provider level to ensure tool execution events
+   * are captured even before child components mount.
+   */
+  executingToolCallIds: ReadonlySet<string>;
+}
+
+export const EMPTY_SET: ReadonlySet<string> = new Set();
+
+export const CopilotKitContext = createContext<CopilotKitContextValue | null>(
+  null,
+);
+
+export const useCopilotKit = (): CopilotKitContextValue => {
+  const context = useContext(CopilotKitContext);
+  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
+
+  if (!context) {
+    throw new Error("useCopilotKit must be used within CopilotKitProvider");
+  }
+  useEffect(() => {
+    const subscription = context.copilotkit.subscribe({
+      onRuntimeConnectionStatusChanged: () => {
+        forceUpdate();
+      },
+    });
+    return () => {
+      subscription.unsubscribe();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return context;
+};
+
+// License context — shared between web and RN providers.
+// Default is permissive (all features allowed) — providers override via createLicenseContextValue.
+// Inlined here to avoid a runtime import from @copilotkit/shared, which pulls in
+// Node-only deps (jose) that break React Native's Metro bundler.
+export const LicenseContext = createContext<LicenseContextValue>({
+  status: null,
+  license: null,
+  checkFeature: () => true,
+  getLimit: () => null,
+} as LicenseContextValue);
+
+export const useLicenseContext = (): LicenseContextValue =>
+  useContext(LicenseContext);

packages/react-core/src/v2/headless.ts

@@ -0,0 +1,42 @@
+/**
+ * Headless (platform-agnostic) exports from @copilotkit/react-core/v2.
+ *
+ * No CSS, no web UI components, no DOM dependencies.
+ * Used by @copilotkit/react-native.
+ */
+
+// Re-export from context (which is external in this build) so the .d.ts
+// references the same type declaration. This avoids a nominal type mismatch
+// caused by private class members being declared in two separate .d.ts files.
+export { CopilotKitCoreReact } from "./context";
+export type { CopilotKitCoreReactConfig } from "./context";
+
+// Chat configuration provider (no UI, just context)
+export {
+  CopilotChatConfigurationProvider,
+  useCopilotChatConfiguration,
+  CopilotChatDefaultLabels,
+  type CopilotChatLabels,
+  type CopilotChatConfigurationValue,
+  type CopilotChatConfigurationProviderProps,
+} from "./providers/CopilotChatConfigurationProvider";
+
+// Platform-agnostic hooks
+export { useAgent, type UseAgentUpdate } from "./hooks/use-agent";
+export { useFrontendTool } from "./hooks/use-frontend-tool";
+export { useComponent } from "./hooks/use-component";
+export { useHumanInTheLoop } from "./hooks/use-human-in-the-loop";
+export { useInterrupt, type UseInterruptConfig } from "./hooks/use-interrupt";
+export { useSuggestions } from "./hooks/use-suggestions";
+export { useConfigureSuggestions } from "./hooks/use-configure-suggestions";
+export {
+  useAgentContext,
+  type AgentContextInput,
+  type JsonSerializable,
+} from "./hooks/use-agent-context";
+export {
+  useThreads,
+  type Thread,
+  type UseThreadsInput,
+  type UseThreadsResult,
+} from "./hooks/use-threads";

packages/react-core/src/v2/hooks/use-agent-context.tsx

@@ -1,4 +1,4 @@
-import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotKit } from "../context";
 import { useLayoutEffect, useMemo } from "react";
 
 /**

packages/react-core/src/v2/hooks/use-agent.tsx

@@ -1,4 +1,4 @@
-import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotKit } from "../context";
 import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
 import { useMemo, useEffect, useReducer, useRef } from "react";
 import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
@@ -290,7 +290,7 @@ export function useAgent({
     };
 
     if (updateFlags.includes(UseAgentUpdate.OnMessagesChanged)) {
-      handlers.onMessagesChanged = forceUpdate;
+      handlers.onMessagesChanged = batchedForceUpdate;
     }
 
     if (updateFlags.includes(UseAgentUpdate.OnStateChanged)) {

packages/react-core/src/v2/hooks/use-configure-suggestions.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef } from "react";
-import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotKit } from "../context";
 import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
 import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
 import type {

packages/react-core/src/v2/hooks/use-frontend-tool.tsx

@@ -1,5 +1,5 @@
 import { useEffect } from "react";
-import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotKit } from "../context";
 import type { ReactFrontendTool } from "../types/frontend-tool";
 
 const EMPTY_DEPS: ReadonlyArray<unknown> = [];
@@ -42,5 +42,5 @@ export function useFrontendTool<
     // Depend on stable keys by default and allow callers to opt into
     // additional dependencies for dynamic tool configuration.
     // tool.available is included so toggling availability re-registers the tool.
-  }, [tool.name, tool.available, copilotkit, extraDeps.length, ...extraDeps]);
+  }, [tool.name, tool.available, copilotkit, JSON.stringify(extraDeps)]);
 }

packages/react-core/src/v2/hooks/use-human-in-the-loop.tsx

@@ -1,4 +1,4 @@
-import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotKit } from "../context";
 import type { ReactFrontendTool } from "../types/frontend-tool";
 import type { ReactHumanInTheLoop } from "../types/human-in-the-loop";
 import type { ReactToolCallRenderer } from "../types/react-tool-call-renderer";

packages/react-core/src/v2/hooks/use-interrupt.tsx

@@ -5,7 +5,7 @@ import React, {
   useMemo,
   useRef,
 } from "react";
-import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotKit } from "../context";
 import { useAgent } from "./use-agent";
 import type {
   InterruptEvent,

packages/react-core/src/v2/hooks/use-render-tool-call.tsx

@@ -1,7 +1,7 @@
 import React, { useCallback, useMemo, useSyncExternalStore } from "react";
 import { ToolCall, ToolMessage } from "@ag-ui/core";
 import { ToolCallStatus } from "@copilotkit/core";
-import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotKit } from "../context";
 import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
 import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
 import { partialJSONParse } from "@copilotkit/shared";