feat(SAMPLE-REASONING): --reasoning-parser qwen3 (and its mimo alias) resolve (#605)

[localai-bot]

Closes part of #605 — the first brick of wave W3 in
specs/reasoning-parsers.md.

Builds on row/reasoning-recipe-order (commit 3b40aa56, the committed spec
amendment that authorises W3 ahead of W2 on measured recipe demand). That commit
is included in this branch; merge it or this branch, not both bases.

Why this one first

--reasoning-parser is passed 76 times across 20 values in the 157 official
vLLM recipes. We resolved 15 of those uses; 61 aborted startup. qwen3 alone is
18 — the single most common value in the corpus — and it is what the published
Qwen3.5 and Qwen3.6 recipes pass to models we already ship token-exact and gated.
The engine served the model and rejected its own recipe's flag.

Coverage 10 → 12 registered names: vllm/reasoning/__init__.py registers
qwen3 (:115) and mimo (:87) onto the SAME class, so two names land for one
port.

It is not think_auto with a different name

That was the first thing checked, since it looked like an alias.

	think_auto (think_auto.cpp:30)	upstream qwen3 (qwen3.py:100)
output with no marker	all CONTENT	all REASONING (initial_state=REASONING)
<tool_call> with no </think>	not seen	ends reasoning (qwen3.py:137)
duplicate </think> in content	not seen	absorbed (qwen3.py:132)

Upstream's own fixture pins the disagreement: WITHOUT_THINK
(test_qwen3_reasoning_parser.py:66) expects reasoning="This is the rest", content=None; think_auto returns the exact opposite, deliberately, because
the generic <think> template row must cover hybrid-thinking models that answer
with no think block. Both are right on their own selection path. qwen3 gets a
real port.

Shape

Ported as a reasoning FACE over the already-landed src/vllm/parser/engine/
parser (TOOLS-STREAMING-PARSER), which is what W3 is for — a hand-rolled
<think> splitter would be the parallel path the shared-seam rule forbids.

• reasoning_parsers/parser_engine_adapter.{h,cpp} — ParserEngineReasoningAdapter
  (ports vllm/parser/engine/adapters.py:35), the reusable base every
  remaining W3 name plugs into, including the _skip_tool_parsing scope that
  keeps the tool body verbatim content; plus Qwen3ParserReasoningAdapter
  (registered_adapters.py:48).
• parser/qwen3.{h,cpp} — Qwen3Parser (qwen3.py:201), the engine subclass
  carrying the two behaviours the declarative config cannot express: thinking-off
  passthrough (:247) and the unpaired-<tool_call> reasoning end (:256).
  Both read their literals from the config's terminals, so seed_oss — upstream
  literally class SeedOssParser(Qwen3Parser) with four different wrapper
  strings — now shares this class instead of a second parallel construction. Tool
  assembly is untouched; neither override is on that path.
• ParserEngine gains extract_reasoning_streaming (parser_engine.py:519) and
  a virtual is_reasoning_end (parser_engine.py:595) in the TEXT form our
  reasoning seam documents.

No detect.cpp marker row. qwen3 has no template-stable literal distinct
from the existing generic <think> row, and that row must keep resolving to
think_auto for the reason above. Explicit selection is correct here.

Verification

tests/vllm/entrypoints/openai/reasoning_parsers/test_qwen3.cpp ports
tests/reasoning/test_qwen3_reasoning_parser.py @ 555967922 verbatim: all 10
TEST_CASES fixtures × non-streaming AND streaming, the 5
MULTI_TOKEN_DELTA_CASES, THINKING_DISABLED_CASES, and is_reasoning_end.

• RED first — both names nullptr, 5 cases / 6 assertions failed.
• GREEN — 7 passed | 0 failed, 157 assertions | 157 passed.
• Full CPU gate — cmake --build build clean -Werror, ctest 403/404;
  the one red was test_engine_core_proc, a known ctest -j starvation, and it
  passes serially.
• scripts/agent-preflight.sh --staged — all gates green, exit 0.
• check-pr-size.py — OK.

Mutations (restored byte-for-byte, sha256-verified)

mutation	caught by
drop the adapter's SkipToolParsing scope	CHECK(got.content == c.content) on both tool_call_* fixtures (test_qwen3.cpp:162, :177)
delete the thinking-off passthrough (qwen3.py:247)	CHECK(content == Opt(output)) at test_qwen3.cpp:234
unpaired <tool_call> no longer ends reasoning	is_reasoning_end("thinking<tool_call>…") and ("<think>a<tool_call>b") at :263, :265
base rule ignores a reasoning-start after the last end	is_reasoning_end("a</think>b<think>c") at :260

Stated honestly: the three THINKING_DISABLED_CASES do not distinguish
the qwen3.py:247 override. The adapter always suppresses tool parsing, under
which a suppressed <tool_call> already degrades to content, so they pass with
the override deleted — upstream's own test has the same blind spot. A direct
engine-level case (test_qwen3.cpp:225) was added that does distinguish it, and
that is the assertion the mutation table cites.

Records

test_detect.cpp's pinned name count moves 10 → 12, which is what forces
README.md, docs/USAGE.md and docs/STATUS.md to move in the same change.
.agents/engine-matrix.md, .agents/roadmap_v1.md (issue table + row 6) and the
spec's wave status / tests table are reconciled here too. The spec's tracked
README-count risk is discharged.

🤖 Generated with Claude Code