Responses API: undocumented reasoning+message pairing constraint breaks multi-turn conversations across all SDKs

Impact

Reasoning+message items must appear as consecutive pairs in input, but the spec doesn't document this. Filtering output items in any natural way silently produces orphaned items → 400 on the next turn. Affects all SDK languages identically.

This broke OpenClaw (64.9k forks) on gpt-5.3-codex. Required 3 PRs (#49301, #50852, #51358) and a dedicated downgradeOpenAIReasoningBlocks() workaround.

Also reported in:

• openai/openai-python#2561: open since Aug 2025, no fix
• openai/openai-agents-python#1660: Agents SDK breaks on GPT-5 + tool calls
• pydantic/pydantic-ai#3230: downstream breakage
• Community threads: 1, 2, 3

Root cause

The spec tells you to include reasoning items in input but doesn't document the pairing constraint:

1. ReasoningItem description says "include these in your input" but doesn't say they must be consecutive pairs with message items. Sending a message without its preceding reasoning → 400. This is the OpenClaw bug.
2. ItemResource (output schema) omits ReasoningItem (#491). The API returns reasoning items in responses, but the output type doesn't model them — so SDKs lack proper typing for the round-trip.
3. EasyInputMessage.content only accepts string | InputMessageContentList — no output_text (#475). Can't pass assistant output back through the easy message path.

Repro

Tested in JS (v6.32.0), Python (v2.29.0), Go (v3.29.0), Java (v4.29.0), .NET (v2.9.1). Identical results — this is API-level, not SDK-specific:

* Nondeterministic — o4-mini sometimes returns reasoning-only output (no message to orphan). Codex with reasoning=high reliably returns both items.

400: Item 'msg_...' of type 'message' was provided without its required preceding item of type 'reasoning'

SDK-specific issues:

• openai/openai-python#3009 (Python)
• openai/openai-node#1791 (Node/TypeScript)
• openai/openai-dotnet#1050 (.NET)
• openai/openai-go#631 (Go)
• openai/openai-java#710 (Java)

Full cross-language repro guide (JS, Python, .NET, curl): https://gist.github.com/achandmsft/57886350885cec3af8ef3f456ed529cf

Fixes needed

1. Document the reasoning+message pairing constraint in the spec
2. Add ReasoningItem to ItemResource (#491)
3. Accept output_text in EasyInputMessage (#475)
4. Document item_reference as the preferred pattern for service-persisted items
5. Add .toInput() / .as_input() helpers in SDKs to make the round-trip safe

Environment

• openai Python v2.29.0, TypeScript v6.32.0, Go v3.29.0, .NET v2.9.1, Java v4.29.0
• Tested on api.openai.com, March 2026

Start with the Responses API definitions for ReasoningItem, ItemResource, and EasyInputMessage, then compare them with the linked cross-language repro and SDK-specific issues. Verify how the specification represents reasoning and message items, including item_reference and output_text. Done means the pairing constraint and supported round-trip shapes are documented and the identified schema gaps are addressed.