refactor(meta): unify response types into Actions

[iBotPeaches]

What:

• Bug Fix
• New Feature

Description:

During development of #658 I learned the Conversation API has both items (ListInputItems) and output (Response output) that the Response API offers - they are an exact duplication. This is an insane level of duplication of code with the strict typing in place. Earlier iterations of this library had simple endpoints (completion, chat, etc) - as AI has evolved so has the endpoints which means we need to get creative.

The Response API is massive and we are missing a chunk of typed support, this means following the pattern of other endpoints we have a typed response for the Create endpoint, the Retrieve endpoint, the List endpoint, etc. For the most part these endpoints duplicate logic for parsing nested structures like items, data, tools, tool choices, etc.

(duplicated between create, retrieve and list)

---

This massive amount of duplication has led to bugs (#667) where a new typed thing may be added but not added to all endpoints which is a poor developer experience. You add support for a type and it should naturally work in create, retrieve, etc.

I've introduced Actions/Responses (sub-folder after Responses) to house a few parsers:

• ItemObjects - The input/output messages that you get when you list a conversation/response. The individual chunks of both input & output.
• OutputObjects - The output messages you get from a Response/Conversation.
• OutputText - The SDK specific string that parses all text messages from any Output that contains a content message.
• ToolChoiceObjects - The tool choice preference between auto, hosted, etc.
• ToolObjects - The wide variety of growing tools output (file, web, function, computer, image, mcp, code, container, etc)

For Response/Conversation classes this means the parsing of complex objects becomes as easy as this.

       $output = OutputObjects::parse($attributes['output']);
       $toolChoice = ToolChoiceObjects::parse($attributes['tool_choice']);
       $tools = ToolObjects::parse($attributes['tools']);

So code that needs these objects can unify their parsing into one central area. This is a big because updating types and concrete implementations across 6 files is terrible and it shows with how often PRs fail CI.

So now when I return to #658 I can leverage those helpers without adding an insane amount of duplication.

I want the complex types to be managed in these Actions and classes that leverage those Actions (Create, Retrieve and List) can import the types from the Actions. That means they are managed in 1 place!