[#281] Add ProviderData for provider-native message parts

[superdav42]

Why this DTO is needed

Providers return native conversation items that are neither text, files, nor client-executed function calls/responses. Dropping these items loses information needed for replay or attribution; representing them as ordinary function calls gives them the wrong meaning. ProviderData gives these items a serializable, provider-tagged place in message history without adding a core type for every provider-specific format.

This extracts the message-data portion previously proposed in #282 into an independent PR. #282 remains focused on function annotations.

Issues this helps resolve

• For Add provider-agnostic deferred tool loading and tool discovery support #281: preserve tool-discovery calls/results in their original position in conversation history so providers can replay them on subsequent turns.
• For Response parser throws "Part has an unexpected type" on server-side tool invocation parts (toolCall / toolResponse) when combining googleSearch with function calling ai-provider-for-google#32: give Google's toolCall / toolResponse parts a representation that retains their payloads, including signatures and search attribution data, instead of throwing or discarding them.

This is the shared DTO foundation, not a complete fix for either issue. Provider adapters still need to parse and replay the new part type; the Google request configuration fix also remains provider-owned.

Changes

• src/Messages/DTO/ProviderData.php: provider ID and opaque data getters, array transformation and JSON schema, following the existing AbstractDataTransferObject pattern.
• src/Messages/DTO/MessagePart.php and src/Messages/Enums/MessagePartTypeEnum.php: a PROVIDER_DATA part with construction, access, serialization and cloning support. Existing message shapes remain unchanged.
• Corresponding tests under tests/unit/Messages/: array/JSON round trips, ordered mixed-message history, signatures/channels, missing fields, schema and clone behavior.

$part = new MessagePart(new ProviderData('google', $partData));

Adapters must check getProviderId() before interpreting or replaying getData(). The DTO does not enforce that check or validate the native payload. No provider implementation, builder API, function annotation or tool-search policy changes are included. PHP 7.4 compatibility is retained.

Verification

• composer test:unit: 1,213 tests / 4,426 assertions passed.
• composer lint: PHPCS and PHPStan passed.
• git diff --check: passed.
• No paid integration calls were run.

---

aidevops.sh v3.32.317 plugin for OpenCode v1.18.30 with gpt-6-astra spent 1d 1h and 2,585,669 tokens on this with the user in an interactive session.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.89%. Comparing base (20a1a6d) to head (82d1296).
⚠️ Report is 11 commits behind head on trunk.

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk     #289      +/-   ##
============================================
+ Coverage     86.54%   86.89%   +0.34%     
- Complexity     1381     1392      +11     
============================================
  Files            69       70       +1     
  Lines          4438     4494      +56     
============================================
+ Hits           3841     3905      +64     
+ Misses          597      589       -8     

Flag	Coverage Δ
unit	86.89% <100.00%> (+0.34%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: superdav42 <[email protected]>
Co-authored-by: JasonTheAdams <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[JasonTheAdams]

@superdav42 Why would provider data be considered part of the content of the MessagePart? This is more like arbitrary data, annotations like the other PR, that describe something about the MessagePart to the provider, right? Is there a scenario where there would be a MessagePart that contains only provider data?

Edit:
Reading this over more, it seems like the answer is yes. Can you please provide reference to some provider docs that shows this behavior? I want to make sure this is the right place to put this sort of thing.

I'm also confused why we're passing the provider ID to the ProviderData. Would a given set of messages potentially contain data for multiple providers?