Preserve reasoning items across multi-turn Responses API calls - #26

Summary

Reasoning output items returned by gpt-5 and o-series models are currently dropped during response parsing. The encrypted_content blob the Responses API expects back on the next turn is lost, so multi-turn conversations with reasoning models silently degrade in quality and the OpenAI docs guidance on round-tripping reasoning items cannot be followed.

This PR threads reasoning items through OpenAiTextGenerationModel in both directions:

• Inbound: output[].type === 'reasoning' items are turned into thought-channel MessagePart instances and attached to the next message / function_call candidate's message parts (alongside the answer text, matching the Anthropic provider's pattern). The reasoning item's {id, encrypted_content, summary} trio is packed into a JSON blob stored on the part's thoughtSignature so all three fields are recoverable on round-trip. The summary text is also surfaced as the part's text content for human-readable consumption.
• Outbound: thought-channel parts with a signature on any history message are re-emitted as top-level {type: 'reasoning', id, encrypted_content, summary} input items before the corresponding message item. The signature blob is JSON-decoded to restore the original shape.
• Token accounting: usage.output_tokens_details.reasoning_tokens is now threaded into TokenUsage::$thoughtTokens when present.

Resolves #13.

Credit to @Takshil-Kunadia — the JSON-blob signature encoding (commit 2) was cherry-picked from #20.

Why reasoning is attached to the existing candidate, not emitted as a separate one

GenerativeAiResult::toText(), toFile(), toMessage() and friends all inspect only the first candidate (php-ai-client/src/Results/DTO/GenerativeAiResult.php:189). Because output[] from the Responses API always lists reasoning items before the corresponding message item, an alternative design that emits each reasoning item as its own Candidate would put the reasoning candidate first — toText() would then throw RuntimeException('No text content found in first candidate') for every gpt-5 / o-series response, breaking the canonical wp_ai_client_prompt()->generate_text() API.

Attaching reasoning as additional thought-channel parts on the answer's candidate keeps toText() working (it filters to content-channel parts) and matches how the Anthropic provider already surfaces thinking blocks.

SDK compatibility

The thought-signature and thought-token DTO surface (MessagePart::$thoughtSignature, TokenUsage::$thoughtTokens) shipped in wordpress/php-ai-client 1.3.0 (#216). This plugin's current composer.json constraint ^0.4 || dev-trunk straddles that boundary, so all new code paths are runtime-gated:

• MessagePart::getThoughtSignature() / 3-arg MessagePart constructor — guarded by method_exists(MessagePart::class, 'getThoughtSignature').
• 4-arg TokenUsage constructor — guarded by ReflectionMethod::getNumberOfParameters().
• Channel inspection — guarded by method_exists($part, 'getChannel').

On pre-1.3 SDKs the new code paths no-op cleanly; on 1.3+ they activate. No dependency bump needed.

Verification

1. Static analysis: composer phpstan clean against the locked SDK 0.4.2 (CI's resolution).

2. Coding standards: composer phpcs clean.

3. toText() regression check: the canonical answer-extraction path returns "Hello world." when the response contains a leading reasoning item (would throw under an alternative design that emits reasoning as a standalone first candidate).

4. End-to-end round-trip test (mock HTTP transporter, live WP stack, real-shape Responses API body with id + encrypted_content + summary):

   === TURN 1: send a question ===
   tokens: prompt=28 completion=12 total=40 thought=384
   [candidate 0] finish=stop
     part[0] channel=thought type=text sig=YES(557b) text=The phrasing "all but 9 die" means 9 survive.
     part[1] channel=content type=text sig=null  text=Nine sheep are left.
   
   === TURN 2: round-trip the assistant message back ===
   Turn 2 input items: 4
     [0] user      [A farmer has 17 sheep, all but 9 die...]
     [1] reasoning id=rs_live_t1 enc=enc_REASONING_BLOB_T1_AA...(422) summary_count=1
     [2] assistant [Nine sheep are left.]
     [3] user      [Now the farmer buys 5 more sheep. Final count?]
   
   === VERDICT ===
   inbound reasoning part on candidate:        YES
   inbound signature stored (JSON blob):       YES (557b)
   inbound thought tokens (turn 1):            384
   outbound reasoning item in turn 2:          YES
   outbound id preserved:                      YES (rs_live_t1)
   outbound encrypted_content preserved:       YES
   outbound summary preserved:                 YES (1 item)
   turn 2 succeeded:                           YES
   

   The verifier instantiates OpenAiTextGenerationModel through the live ProviderRegistry, swaps in a recording mock HttpTransporterInterface (the configured project API key lacks api.responses.write scope, so the real network call returns 401), and confirms the patched parse + serialize paths handle real-shape gpt-5 response bodies correctly across two consecutive turns.

5. Backwards compatibility: re-ran the same verifier against php-ai-client 0.4.2 (the locked SDK version) — patch silently no-ops, no fatals, parser behaves identically to current trunk for callers without reasoning items.

Risk

• Behaviour change only when the response contains output[].type === 'reasoning' (gpt-5, o-series with reasoning enabled).
• Reasoning items previously dropped become thought-channel parts on the candidate message; callers that iterate Message::getParts() and don't filter by channel will now see those parts. GenerativeAiResult::toText() filters to content channel and is unaffected.
• No changes to existing message / function_call / function_response handling.