feat(reasoning): expose thinking/reasoning across API + control thinking.display

[arminanton]

What does this PR do?

Exposes model reasoning/thinking through the API server gateway on both /v1/chat/completions and /v1/responses, and adds control over Anthropic's thinking.display. Reasoning already renders in the CLI and messaging paths; this brings the OpenAI-compatible API surface to parity so downstream clients (Open WebUI, etc.) can render the model's thinking.

Everything is gated on the existing display.show_reasoning setting. With it off (the default), the wire output is byte-identical to today, so this is a safe, opt-in change.

Related Issue

Closes #37044
Closes #7556
Closes #21655
Closes #18466
Closes #30449

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

/v1/chat/completions (gateway/platforms/api_server.py) — closes #37044, #7556, #30449

• Non-streaming: reasoning_content as a sibling of content in the message object.
• Streaming: delta.reasoning_content chunks emitted before delta.content, the shape Open WebUI and other OpenAI-compatible frontends already parse.
• Both paths gated on display.show_reasoning ([Bug]: "display.show_reasoning" config option is not honored by the API server adapter #7556).

/v1/responses (gateway/platforms/api_server.py) — closes #21655

• Real token-by-token reasoning sourced from the agent's reasoning_callback, emitted as the spec reasoning event family (response.output_item.added → reasoning_summary_part.added → reasoning_summary_text.delta → .done → output_item.done).
• Sourced from reasoning_callback, not the reasoning.available progress event. The latter carries the stripped assistant content, not the model's reasoning, so surfacing it would duplicate the answer inside the thinking block.
• Non-streaming via _extract_output_items(include_reasoning=...).
• Input hardening: clients echo reasoning items back; they have no role/content, so they are skipped when rebuilding input/conversation_history (avoids empty-turn 400s).

thinking.display control (agent/anthropic_adapter.py)

• New _resolve_thinking_display() reads an optional reasoning_config["display"] (summarized | omitted). Default stays summarized so Hermes always has reasoning to surface; omitted suppresses the reasoning text on the wire (the model still thinks; the signature is preserved for multi-turn continuity). Unknown values fall back to summarized so a bad value can never produce an invalid request.

reasoning_tokens (agent/usage_pricing.py) — closes #18466

• normalize_usage now also reads completion_tokens_details.reasoning_tokens (the chat/completions usage shape). It was always 0 in chat_completions mode because only output_tokens_details was read.

How to Test

1. Set display.show_reasoning: true in ~/.hermes/config.yaml (default is false).
2. Start the API server and call a reasoning-capable model:
   • /v1/chat/completions non-streaming → response message contains reasoning_content.
   • /v1/chat/completions with stream: true → delta.reasoning_content chunks arrive before delta.content.
   • /v1/responses with stream: true → reasoning summary events stream before the answer.
3. With display.show_reasoning: false (default), confirm the wire output is unchanged from before this PR.
4. Anthropic thinking.display: pass reasoning_config["display"] = "omitted" and confirm no reasoning text is returned while the answer is unaffected.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(reasoning):)
• I searched for existing PRs to make sure this isn't a duplicate (this synthesizes fix(gateway): forward reasoning in chat completions (#37044) #39006 + feat(api-server): emit Responses API reasoning output items behind show_reasoning #43644 and supersedes the narrower fix(api-server): honour display.show_reasoning in /v1/chat/completions #40005)
• My PR contains only changes related to this feature (no unrelated commits)
• I've run the tests and all pass (180 api_server tests incl. 24 new reasoning/display tests; 8 new thinking.display resolver tests; 12 usage_pricing tests)
• I've added tests for my changes
• I've tested on my platform: Ubuntu Linux (Python 3.11)

Documentation & Housekeeping

• I've updated relevant documentation (docstrings on the new resolver/extraction helpers) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — N/A (no new config keys; thinking.display is a runtime reasoning_config field, and display.show_reasoning already exists)
• I've updated CONTRIBUTING.md / AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact — N/A (pure Python, no OS-specific primitives; passes the Windows-footgun check)
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

Provider coverage

last_reasoning is sourced from the provider-neutral msg["reasoning"] field, so this works for vendor-direct Anthropic, Copilot-served Claude, and Copilot-served GPT with no per-provider special-casing.

Relation to prior PRs

Synthesizes the approaches in #39006 (chat/completions) and #43644 (Responses API), reusing the reasoning_callback mechanism #43644 established. Supersedes the narrower #40005, which used a text-prepend plus a non-standard SSE event.

[teknium1]

Thanks for consolidating the API reasoning work. The current API server still lacks this capability: /v1/chat/completions wires no reasoning callback at gateway/platforms/api_server.py:2311-2321, and /v1/responses does not wire one at gateway/platforms/api_server.py:3397-3409.

Problems

• The chat streaming branch must not source reasoning from reasoning.available. Current main constructs that event from assistant_message.content in agent/conversation_loop.py:4334-4350, whereas structured reasoning deltas call reasoning_callback through run_agent.py:4745-4751 from agent/chat_completion_helpers.py:2354-2359 and :2675-2679. The proposed path can emit answer text as reasoning and omit native thinking deltas.
• The reasoning_tokens change is already on main in agent/usage_pricing.py:883-906, from 3a122ba4a.

Suggested changes

• Route Chat Completions through reasoning_callback, as the Responses path does, and test a structured callback invocation.
• Salvage only the API/display portions after reconciling the moved API-server lifecycle code; omit the already-landed usage hunk.

Automated hermes-sweeper review.

[teknium1]

Please use reasoning_callback here instead of tool_progress_callback. On current main, reasoning.available is derived from assistant_message.content (agent/conversation_loop.py:4334-4350), while native structured reasoning deltas invoke reasoning_callback (agent/chat_completion_helpers.py:2354-2359, :2675-2679). This would miss structured thinking and can serialize answer content as reasoning_content.

[arminanton]

Rebased onto current main and wired reasoning from the structured source.

Structured reasoning, not reasoning.available (sweeper): both endpoints now wire the agent's reasoning_callback (fired from native reasoning_content/thinking deltas), not the reasoning.available progress event — conversation_loop.py derives reasoning.available from assistant_message.content, so sourcing it would serialize answer text as reasoning and drop native thinking. Threaded reasoning_callback through _create_agent → AIAgent → _run_agent.

Event shapes:

• /v1/chat/completions: stream emits delta.reasoning_content chunks; non-stream adds a reasoning_content sibling of content.
• /v1/responses: stream emits the spec reasoning family (response.output_item.added type reasoning → reasoning_summary_part.added → reasoning_summary_text.delta → .done → output_item.done) before tool-start/text/EOS; non-stream emits reasoning output items. Echoed-back reasoning items are skipped on input to avoid empty-turn 400s.

Gated by display.platforms.api_server.show_reasoning (fails closed, off by default = byte-identical wire), with a thinking.display summarized/omitted control. Also dropped the usage_pricing.reasoning_tokens hunk (already on main).

Tests: test_api_server_reasoning.py + test_anthropic_thinking_display.py → 26 passed; test_api_server.py regression → 108 passed (the one health-detailed red is a pre-existing SQLite-3.26 sandbox artifact, identical on main).