session.md

Find providerMetadata→providerOptions mapping origin (@general subagent)

Session ID: ses_5230aaf1fffeVBHnEw6TZWhT0O Created: 12/1/2025, 6:47:35 PM Updated: 12/1/2025, 6:51:48 PM

---

User

I need to find exactly when and in what version the providerMetadata → providerOptions mapping was established in this AI SDK codebase.

Specifically:

1. Search for where providerMetadata is mapped/converted to providerOptions in the SDK core
2. Look at the git history/commits to find when this was introduced
3. Check if this mapping exists in LanguageModelV1 or only in LanguageModelV3 types
4. Find any changelogs or version information about when this was added

Key files to investigate:

• packages/ai/src/generate-text/to-response-messages.ts (mentioned in REPORT.md)
• packages/ai/src/ui/convert-to-model-messages.ts
• packages/provider/src/language-model/v1/ directory
• packages/provider/src/language-model/v3/ directory
• Any CHANGELOG files in packages/ai or packages/provider

Return:

1. The exact version this mapping was introduced
2. Whether providerOptions exists in LanguageModelV1 types or only LanguageModelV3
3. The relevant code/type definitions showing this

---

Assistant

Tool: read

Tool: read

Tool: list

Tool: list

Tool: read

Tool: read

---

Assistant

Now I can see the mapping in the code. Let me search for more specific information about when providerMetadata → providerOptions was established, and look at the V1 vs V3 type definitions:

Tool: read

Tool: glob

Tool: grep

Tool: bash

---

Assistant

I found the key commit. Let me get more details about that commit and check if there's a LanguageModelV1 directory:

Tool: bash

Tool: bash

Tool: list

Tool: bash

---

Assistant

Let me also check the V2 prompt to see the providerOptions definition and look at the migration guide for version info:

Tool: read

Tool: read

Tool: bash

---

Assistant

Now let me verify there's no LanguageModelV1 and check the shared provider options to understand the full picture:

Tool: list

Tool: read

Tool: read

---

Assistant

Now I have all the information needed. Let me summarize the findings:

Summary: providerMetadata → providerOptions Mapping

1. Exact Version This Mapping Was Introduced

The providerMetadata → providerOptions rename was introduced in:

• Commit: 33f4a6a4d9d4b549c56a4a87a95fe19fd81a02ad
• Date: April 7, 2025 (10:55:53 +0200)
• PR: #5579
• Version: Part of AI SDK 5.0 (first appeared in @ai-sdk/provider@2.0.0-canary.1)

From the CHANGELOG at packages/provider/CHANGELOG.md:547:

- 33f4a6a: chore (provider): rename providerMetadata inputs to providerOptions

2. LanguageModelV1 vs V2 vs V3

There is no LanguageModelV1 in the current codebase. The provider package only has:

• v2/ - LanguageModelV2 types (uses providerOptions)
• v3/ - LanguageModelV3 types (uses providerOptions)

Both V2 and V3 use providerOptions in their prompt/input types. The V1 spec was removed as part of AI SDK 5.0 (see packages/provider/CHANGELOG.md:175: 0d06df6: chore (ai): remove v1 providers).

3. The Mapping Code

The actual providerMetadata → providerOptions conversion happens in two key files:

packages/ai/src/generate-text/to-response-messages.ts (lines 37, 43, 50, 59, 72, 84, 118):

// Response parts have `providerMetadata`, converted to `providerOptions` in model messages
case 'text':
  return {
    type: 'text',
    text: part.text,
    providerOptions: part.providerMetadata,  // ← The mapping
  };

packages/ai/src/ui/convert-to-model-messages.ts (lines 84, 101, 114, 156, 170):

// UI parts have `providerMetadata`, converted to `providerOptions` in model messages
return {
  type: 'text' as const,
  text: part.text,
  ...(part.providerMetadata != null
    ? { providerOptions: part.providerMetadata }
    : {}),
};

4. Key Distinction

• providerOptions: Used for inputs to the model (in prompts/messages sent TO the model)
• providerMetadata: Used for outputs from the model (in responses received FROM the model)

From the migration guide (content/docs/08-migration-guides/26-migration-guide-5-0.mdx:490):

The providerMetadata input parameter has been renamed to providerOptions. Note that the returned metadata in results is still called providerMetadata.

Type Definitions

V2 Prompt (packages/provider/src/language-model/v2/language-model-v2-prompt.ts:49):

providerOptions?: SharedV2ProviderOptions;

V3 Prompt (packages/provider/src/language-model/v3/language-model-v3-prompt.ts:49):

providerOptions?: SharedV3ProviderOptions;

Both SharedV2ProviderOptions and SharedV3ProviderOptions are defined as:

export type SharedV3ProviderOptions = Record<string, JSONObject>;

---

User

Okay. So are you saying that the providerMetadata->providerOptions mapping happens in ALL language model specs?

---

Assistant

Let me clarify by checking the actual type definitions more carefully:

Tool: read

Tool: read

Tool: read

Tool: read

---

Assistant

Tool: read

Tool: read

---

Assistant

Now I can give you a precise answer:

No, the mapping is NOT in the language model specs themselves. The specs have a clear separation:

In the Language Model Specs (V2 and V3):

Context	Field Name	Type	Purpose
Prompt/Input (what you send TO the model)	providerOptions	SharedV2/V3ProviderOptions	Options for provider-specific input features
Content/Output (what you get FROM the model)	providerMetadata	SharedV2/V3ProviderMetadata	Metadata returned by the provider

For example:

• LanguageModelV3TextPart (in prompt) has providerOptions
• LanguageModelV3Text (in response content) has providerMetadata

The Mapping Happens in the SDK Core Layer

The providerMetadata → providerOptions conversion is not in the language model spec itself. It happens in the SDK's conversion functions when transforming response messages back into prompts for multi-step conversations:

Model Response (providerMetadata) 
    ↓
SDK Core: toResponseMessages() / convertToModelMessages()
    ↓
Model Prompt (providerOptions)

The mapping exists because:

1. When a model returns content with providerMetadata (e.g., Google's thoughtSignature)
2. And you want to send that content back as input in a follow-up request
3. The SDK must convert providerMetadata → providerOptions so the provider can recognize it

Both V2 and V3 specs have this same pattern - they both use providerOptions for inputs and providerMetadata for outputs. There's no difference between them in this regard.

---