chore (ai): rename CoreMessage to ModelMessage (#6105)

## Background

The name `CoreMessage` was an artifact of needed to introduce a separate
message type. Over time it became clear that we have threee distinct
message types:

- messages used on the client that are displayed to the user
(`UIMessage`)
- messages that are sent to our user-facing APIs (currently
`CoreMessage`)
- messages that are sent to the providers (`LanguageModelV2Message`)

They all have distinct DX considerations and are different by design.

The name `CoreMessage` is not clear here.

## Summary

Rename `CoreMessage` to `ModelMessage` to make the distinction
`UIMessage <> ModelMessage` clear (most users are not exposed to
internal provider messages).

## Future Work
`CoreMessages` and related types and functions are deprecated and will
be removed in AI SDK 6

Author: lgrammel

.changeset/young-dingos-march.md

@@ -0,0 +1,5 @@
+---
+'ai': major
+---
+
+chore (ai): rename CoreMessage to ModelMessage

content/cookbook/01-next/11-generate-text-with-chat-prompt.mdx

@@ -31,12 +31,12 @@ Let's start by creating a simple chat interface with an input field that sends t
 ```tsx filename='app/page.tsx'
 'use client';
 
-import { CoreMessage } from 'ai';
+import { ModelMessage } from 'ai';
 import { useState } from 'react';
 
 export default function Page() {
   const [input, setInput] = useState('');
-  const [messages, setMessages] = useState<CoreMessage[]>([]);
+  const [messages, setMessages] = useState<ModelMessage[]>([]);
 
   return (
     <div>
@@ -90,11 +90,11 @@ export default function Page() {
 Next, let's create the `/api/chat` endpoint that generates the assistant's response based on the conversation history.
 
 ```typescript filename='app/api/chat/route.ts'
-import { CoreMessage, generateText } from 'ai';
+import { ModelMessage, generateText } from 'ai';
 import { openai } from '@ai-sdk/openai';
 
 export async function POST(req: Request) {
-  const { messages }: { messages: CoreMessage[] } = await req.json();
+  const { messages }: { messages: ModelMessage[] } = await req.json();
 
   const { response } = await generateText({
     model: openai('gpt-4'),

content/cookbook/01-next/24-stream-text-multistep.mdx

@@ -55,7 +55,7 @@ export async function POST(req: Request) {
           'You are a helpful assistant with a different system prompt. Repeat the extract user goal in your answer.',
         // continue the workflow stream with the messages from the previous step:
         messages: [
-          ...convertToCoreMessages(messages),
+          ...convertToModelMessages(messages),
           ...(await result1.response).messages,
         ],
       });

content/cookbook/01-next/75-human-in-the-loop.mdx

@@ -336,7 +336,7 @@ The solution above is low-level and not very friendly to use in a production env
 import {
   formatDataStreamPart,
   Message,
-  convertToCoreMessages,
+  convertToModelMessages,
   DataStreamWriter,
   ToolExecutionOptions,
   ToolSet,
@@ -419,7 +419,7 @@ export async function processToolCalls<
         const toolInstance = executeFunctions[toolName];
         if (toolInstance) {
           result = await toolInstance(toolInvocation.args, {
-            messages: convertToCoreMessages(messages),
+            messages: convertToModelMessages(messages),
             toolCallId: toolInvocation.toolCallId,
           });
         } else {

content/docs/02-foundations/03-prompts.mdx

@@ -164,9 +164,9 @@ const messages = [
   AI SDK UI hooks like [`useChat`](/docs/reference/ai-sdk-ui/use-chat) return
   arrays of `UIMessage` objects, which do not support provider options. We
   recommend using the
-  [`convertToCoreMessages`](/docs/reference/ai-sdk-ui/convert-to-core-messages)
+  [`convertToModelMessages`](/docs/reference/ai-sdk-ui/convert-to-core-messages)
   function to convert `UIMessage` objects to
-  [`CoreMessage`](/docs/reference/ai-sdk-core/core-message) objects before
+  [`ModelMessage`](/docs/reference/ai-sdk-core/core-message) objects before
   applying or appending message(s) or message parts with `providerOptions`.
 </Note>
 

content/docs/02-getting-started/06-nodejs.mdx

@@ -76,7 +76,7 @@ Create an `index.ts` file in the root of your project and add the following code
 
 ```ts filename="index.ts"
 import { openai } from '@ai-sdk/openai';
-import { CoreMessage, streamText } from 'ai';
+import { ModelMessage, streamText } from 'ai';
 import dotenv from 'dotenv';
 import * as readline from 'node:readline/promises';
 
@@ -87,7 +87,7 @@ const terminal = readline.createInterface({
   output: process.stdout,
 });
 
-const messages: CoreMessage[] = [];
+const messages: ModelMessage[] = [];
 
 async function main() {
   while (true) {
@@ -151,7 +151,7 @@ Modify your `index.ts` file to include the new weather tool:
 
 ```ts filename="index.ts" highlight="2,4,25-38"
 import { openai } from '@ai-sdk/openai';
-import { CoreMessage, streamText, tool } from 'ai';
+import { ModelMessage, streamText, tool } from 'ai';
 import dotenv from 'dotenv';
 import { z } from 'zod';
 import * as readline from 'node:readline/promises';
@@ -163,7 +163,7 @@ const terminal = readline.createInterface({
   output: process.stdout,
 });
 
-const messages: CoreMessage[] = [];
+const messages: ModelMessage[] = [];
 
 async function main() {
   while (true) {
@@ -221,7 +221,7 @@ Notice the blank "assistant" response? This is because instead of generating a t
 
 ```typescript highlight="47-48"
 import { openai } from '@ai-sdk/openai';
-import { CoreMessage, streamText, tool } from 'ai';
+import { ModelMessage, streamText, tool } from 'ai';
 import dotenv from 'dotenv';
 import { z } from 'zod';
 import * as readline from 'node:readline/promises';
@@ -233,7 +233,7 @@ const terminal = readline.createInterface({
   output: process.stdout,
 });
 
-const messages: CoreMessage[] = [];
+const messages: ModelMessage[] = [];
 
 async function main() {
   while (true) {
@@ -291,7 +291,7 @@ Modify your `index.ts` file to include the `maxSteps` option:
 
 ```ts filename="index.ts" highlight="39-42"
 import { openai } from '@ai-sdk/openai';
-import { CoreMessage, streamText, tool } from 'ai';
+import { ModelMessage, streamText, tool } from 'ai';
 import dotenv from 'dotenv';
 import { z } from 'zod';
 import * as readline from 'node:readline/promises';
@@ -303,7 +303,7 @@ const terminal = readline.createInterface({
   output: process.stdout,
 });
 
-const messages: CoreMessage[] = [];
+const messages: ModelMessage[] = [];
 
 async function main() {
   while (true) {
@@ -364,7 +364,7 @@ Update your `index.ts` file to add a new tool to convert the temperature from Ce
 
 ```ts filename="index.ts" highlight="38-49"
 import { openai } from '@ai-sdk/openai';
-import { CoreMessage, streamText, tool } from 'ai';
+import { ModelMessage, streamText, tool } from 'ai';
 import dotenv from 'dotenv';
 import { z } from 'zod';
 import * as readline from 'node:readline/promises';
@@ -376,7 +376,7 @@ const terminal = readline.createInterface({
   output: process.stdout,
 });
 
-const messages: CoreMessage[] = [];
+const messages: ModelMessage[] = [];
 
 async function main() {
   while (true) {

content/docs/02-guides/03-slackbot.mdx

@@ -318,10 +318,10 @@ Here's how to implement it:
 
 ```typescript filename="lib/generate-response.ts"
 import { openai } from '@ai-sdk/openai';
-import { CoreMessage, generateText } from 'ai';
+import { ModelMessage, generateText } from 'ai';
 
 export const generateResponse = async (
-  messages: CoreMessage[],
+  messages: ModelMessage[],
   updateStatus?: (status: string) => void,
 ) => {
   const { text } = await generateText({
@@ -349,12 +349,12 @@ The real power of the AI SDK comes from tools that enable your bot to perform ac
 
 ```typescript filename="lib/generate-response.ts"
 import { openai } from '@ai-sdk/openai';
-import { CoreMessage, generateText, tool } from 'ai';
+import { ModelMessage, generateText, tool } from 'ai';
 import { z } from 'zod';
 import { exa } from './utils';
 
 export const generateResponse = async (
-  messages: CoreMessage[],
+  messages: ModelMessage[],
   updateStatus?: (status: string) => void,
 ) => {
   const { text } = await generateText({

content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

@@ -191,12 +191,12 @@ Both `generateText` and `streamText` have a `response.messages` property that yo
 add the assistant and tool messages to your conversation history.
 It is also available in the `onFinish` callback of `streamText`.
 
-The `response.messages` property contains an array of `CoreMessage` objects that you can add to your conversation history:
+The `response.messages` property contains an array of `ModelMessage` objects that you can add to your conversation history:
 
 ```ts
 import { generateText } from 'ai';
 
-const messages: CoreMessage[] = [
+const messages: ModelMessage[] = [
   // ...
 ];
 

content/docs/04-ai-sdk-ui/03-chatbot-message-persistence.mdx

@@ -124,14 +124,14 @@ We have enabled the `sendExtraMessageFields` option to send the id and createdAt
 meaning that we store messages in the `useChat` message format.
 
 <Note>
-  The `useChat` message format is different from the `CoreMessage` format. The
+  The `useChat` message format is different from the `ModelMessage` format. The
   `useChat` message format is designed for frontend display, and contains
   additional fields such as `id` and `createdAt`. We recommend storing the
   messages in the `useChat` message format.
 </Note>
 
 Storing messages is done in the `onFinish` callback of the `streamText` function.
-`onFinish` receives the messages from the AI response as a `CoreMessage[]`,
+`onFinish` receives the messages from the AI response as a `ModelMessage[]`,
 and we use the [`appendResponseMessages`](/docs/reference/ai-sdk-ui/append-response-messages)
 helper to append the AI response messages to the chat messages.
 

content/docs/05-ai-sdk-rsc/10-migrating-to-ui.mdx

@@ -483,12 +483,12 @@ With AI SDK UI, you will save chats using the `onFinish` callback function of `s
 ```ts filename="@/app/api/chat/route.ts"
 import { openai } from '@ai-sdk/openai';
 import { saveChat } from '@/utils/queries';
-import { streamText, convertToCoreMessages } from 'ai';
+import { streamText, convertToModelMessages } from 'ai';
 
 export async function POST(request) {
   const { id, messages } = await request.json();
 
-  const coreMessages = convertToCoreMessages(messages);
+  const coreMessages = convertToModelMessages(messages);
 
   const result = streamText({
     model: openai('gpt-4o'),