fix(openai): keep Chat Completions reasoning on its assistant message - #1669

Summary

Chat Completions responses that carry reasoning do not round trip. Providers that return reasoning on the assistant message get it recorded as a standalone reasoning item placed before the assistant message item, and on replay the converter turns that one provider message back into two assistant messages, with the reasoning on the one that has no content.

Captured live against OpenRouter and deepseek/deepseek-r1 on @openai/[email protected]. Provider response, choices[0].message:

{
  "role": "assistant",
  "content": "The capital of France is **Paris**.",
  "refusal": null,
  "reasoning": "Okay, the user asked a straightforward question: [truncated]",
  "reasoning_details": [ { "type": "reasoning.text", "text": "[truncated]", "format": "unknown", "index": 0 } ]
}

Second turn request from the same run:

[
  { "role": "user", "content": "What is the capital of France?" },
  { "role": "assistant", "content": null, "reasoning": "[truncated]" },
  { "role": "assistant", "content": [ { "type": "text", "text": "The capital of France is **Paris**." } ] },
  { "role": "user", "content": "And Germany?" }
]

It compounds, because a reasoning item is added per turn. Assistant messages in each outgoing request over five turns:

turn | assistant msgs | contentless (content: null, no tool_calls)
  1  |       0        |      0
  2  |       2        |      1
  3  |       4        |      2
  4  |       6        |      3
  5  |       8        |      4

So a reasoning model on the Chat Completions path currently replays twice the assistant messages it needs, growing with conversation length, and the caller pays input tokens for the empty ones. The same applies to the streaming path, which produces the same history items.

OpenRouter documents passing reasoning back on the assistant message, via message.reasoning or message.reasoning_details, to preserve reasoning continuity across calls: https://openrouter.ai/docs/guides/best-practices/reasoning-tokens

This is not an OpenAI Chat Completions field, and the SDK already targets it deliberately on both sides. hasReasoningContent() in openaiChatCompletionsModel.ts reads message.reasoning, the streaming converter accumulates delta.reasoning, and ChatCompletionAssistantMessageWithReasoning exists in the converter so it can be written back out. The read path and the write path just do not line up.

Fix

When the pending assistant message was created only by a reasoning item, hand its reasoning to the assistant message that immediately follows instead of flushing it as a separate turn:

[
  { "role": "user", "content": "What is the capital of France?" },
  {
    "role": "assistant",
    "content": [ { "type": "text", "text": "The capital of France is **Paris**." } ],
    "reasoning": "[truncated]"
  },
  { "role": "user", "content": "And Germany?" }
]

19 lines in one function. No public API change.

Behavior that is deliberately unchanged, and now covered by tests:

• Reasoning followed by a tool call still shares a single assistant message, which is how tool call turns already replayed.
• A trailing reasoning item with no following assistant message is still emitted on its own.
• Reasoning is never merged into a following user or system message.
• providerData.reasoning on the assistant message still wins, since provider data is spread last.
• Only the reasoning item directly before an assistant message is merged into it, so a later assistant message is unaffected.

A reasoning item with empty rawContent no longer produces an assistant message with neither content nor reasoning.

Out of scope here, happy to follow up if wanted: reasoning_details is not carried onto the assistant message at all, and the nested copy of reasoning inside the text content part comes from the existing providerData passthrough in extractAllAssistantContent.

Test plan

Six cases in packages/agents-openai/test/openaiChatCompletionsConverter.test.ts. Four fail on main and pass with the change; two are guards that pass in both states so the unchanged paths stay pinned:

• keeps reasoning on the assistant message it belongs to
• drops an empty reasoning item instead of emitting an empty assistant turn
• does not steal reasoning from a previous assistant message
• does not accumulate contentless assistant messages across turns
• keeps reasoning with the tool call message when a tool call follows (guard)
• does not attach reasoning to a following user message (guard)

Commands run locally on Windows:

• pnpm build (0 errors)
• pnpm test for packages/agents-openai: 21 files, 665 tests passing
• full pnpm test: the only failures are pre-existing on this platform and unrelated to this change (the sandbox suites that require POSIX path separators, and the RunState fixture hash check that trips on CRLF checkouts)
• pnpm lint
• pnpm -r build-check

Issue number

N/A

Checks

• I've added new tests (if relevant)
• I've added/updated the relevant documentation
• I've run pnpm test and pnpm test:examples
  • (If you made a major change) I've run pnpm test:integration (see details)
• I've run .agents/skills/code-change-verification/scripts/run.sh
• I've confirmed all verification steps pass
• If using Codex, I've run /review before submitting this PR
• I've added a changeset using pnpm changeset to indicate my changes