feat: collect reasoning_tokens from the provider usage payload (issue #6)

Reasoning tokens are already counted inside completion_tokens, so the
cost total was never wrong -- what was missing is the attribution: how
much of a call was spent thinking rather than answering.

LLMResponse and TransportResult each gain a trailing reasoning_tokens
field, and the telemetry port grows from 21 to 22 columns with the new
column appended in both backends so fresh and migrated schemas keep the
same physical order.

None means this particular call did not report the field, not that the
source never reports it: a relay that falls back to a local tokenizer
replaces the whole usage object and drops completion_tokens_details.
Downstream checks must therefore read "in (None, 0)"; no provider was
observed reporting a literal zero.

src/polygateway/middleware/retry.py

@@ -438,6 +438,7 @@ class RetryMW:
             usage_source=result.usage_source,
             cached_prompt_tokens=result.cached_prompt_tokens,
             model_reported=result.model_reported,
+            reasoning_tokens=result.reasoning_tokens,
         )
 
     async def _settle_and_release(self, permit: Permit, actual: int) -> None:

src/polygateway/middleware/telemetry.py

@@ -64,6 +64,7 @@ class TelemetryEmitter:
             error=error,
             cached_prompt_tokens=response.cached_prompt_tokens if response else None,
             model_reported=response.model_reported if response else None,
+            reasoning_tokens=response.reasoning_tokens if response else None,
             # 唯一有"生效源"的入口,故是唯一能并上 extra_body 的(设计决策 D)
             sampling=canonical_sampling_json(merge_sampling(source.extra_body, request.sampling)),
         )
@@ -90,6 +91,7 @@ class TelemetryEmitter:
             # 统计供应商缓存命中率必须带 WHERE cache_hit = false,否则重复计数。
             cached_prompt_tokens=response.cached_prompt_tokens,
             model_reported=response.model_reported,
+            reasoning_tokens=response.reasoning_tokens,
             # 由最外层 TelemetryMW 调用,手上没有 source。缓存命中行无损:
             # sampling 已进缓存 key,能命中即意味调用级参数与历史那次逐字相同
             sampling=canonical_sampling_json(request.sampling),
@@ -117,6 +119,7 @@ class TelemetryEmitter:
             error=error,
             cached_prompt_tokens=None,
             model_reported=None,
+            reasoning_tokens=None,
             # 无具体源,与 model/provider/source_name 置空同一先例(设计决策 D)
             sampling=canonical_sampling_json(request.sampling),
         )
@@ -142,6 +145,7 @@ class TelemetryEmitter:
         cached_prompt_tokens: int | None,
         model_reported: str | None,
         sampling: str | None,
+        reasoning_tokens: int | None,
     ) -> None:
         try:
             # 成本换算(M2 §6): 成功行按单价换算;缓存命中 0.0(未产生新调用);
@@ -182,6 +186,7 @@ class TelemetryEmitter:
                 cached_prompt_tokens=cached_prompt_tokens,
                 model_reported=model_reported,
                 sampling=sampling,
+                reasoning_tokens=reasoning_tokens,
             )
         except asyncio.CancelledError:
             raise

src/polygateway/ports.py

@@ -275,4 +275,5 @@ class TelemetryRecorder(Protocol):
         cached_prompt_tokens: int | None,
         model_reported: str | None,
         sampling: str | None,
+        reasoning_tokens: int | None,
     ) -> None: ...

src/polygateway/telemetry/postgres.py

@@ -42,7 +42,8 @@ CREATE TABLE IF NOT EXISTS llm_calls (
     created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
     cached_prompt_tokens INTEGER,
     model_reported       TEXT,
-    sampling             TEXT
+    sampling             TEXT,
+    reasoning_tokens     INTEGER
 );
 """
 
@@ -51,6 +52,7 @@ _BACKFILL = (
     ("cached_prompt_tokens", "ALTER TABLE llm_calls ADD COLUMN cached_prompt_tokens INTEGER"),
     ("model_reported", "ALTER TABLE llm_calls ADD COLUMN model_reported TEXT"),
     ("sampling", "ALTER TABLE llm_calls ADD COLUMN sampling TEXT"),
+    ("reasoning_tokens", "ALTER TABLE llm_calls ADD COLUMN reasoning_tokens INTEGER"),
 )
 
 # 探测现有列;尊重 search_path(to_regclass 按当前 search_path 解析)
@@ -81,6 +83,7 @@ _COLUMNS = (
     "cached_prompt_tokens",
     "model_reported",
     "sampling",
+    "reasoning_tokens",
 )
 
 _INSERT = (

src/polygateway/telemetry/sqlite.py

@@ -37,7 +37,8 @@ CREATE TABLE IF NOT EXISTS llm_calls (
     created_at         TEXT    NOT NULL DEFAULT (datetime('now')),
     cached_prompt_tokens INTEGER,
     model_reported       TEXT,
-    sampling             TEXT
+    sampling             TEXT,
+    reasoning_tokens     INTEGER
 );
 """
 
@@ -47,6 +48,7 @@ _BACKFILL_COLUMNS = (
     ("cached_prompt_tokens", "INTEGER"),
     ("model_reported", "TEXT"),
     ("sampling", "TEXT"),
+    ("reasoning_tokens", "INTEGER"),
 )
 
 _COLUMNS = (
@@ -71,6 +73,7 @@ _COLUMNS = (
     "cached_prompt_tokens",
     "model_reported",
     "sampling",
+    "reasoning_tokens",
 )
 
 _INSERT = (

src/polygateway/transports/openai_compat.py

@@ -177,6 +177,25 @@ def _coerce_cached_tokens(usage: Any) -> int | None:
     return cached
 
 
+def _coerce_reasoning_tokens(usage: Any) -> int | None:
+    """取 usage.completion_tokens_details.reasoning_tokens(issue #6);形态异常一律 None。
+
+    与 `_coerce_cached_tokens` 逐条同构(两者是 OpenAI 兼容 usage 里对称的一对):
+    `0` 如实保留、负数与非整数归 None、`bool` 显式排除。差别只在语义——本字段
+    的 None 是"**本次调用**未上报"而非"该源不上报": 中转在上游不返回 usage 时
+    会本地补算并整体替换 usage 对象,把 details 一并吃掉(findings §4c)。
+    """
+    if not isinstance(usage, dict):
+        return None
+    details = usage.get("completion_tokens_details")
+    if not isinstance(details, dict):
+        return None
+    reasoning = details.get("reasoning_tokens")
+    if isinstance(reasoning, bool) or not isinstance(reasoning, int) or reasoning < 0:
+        return None
+    return reasoning
+
+
 def _coerce_model_reported(value: Any) -> str | None:
     """取响应体的 model 字段(issue #3);非 str 或空白串一律 None,收口时去空白。
 
@@ -400,6 +419,7 @@ class OpenAICompatTransport:
             raw={"usage": sink.get("usage")},
             cached_prompt_tokens=_coerce_cached_tokens(sink.get("usage")),
             model_reported=_coerce_model_reported(sink.get("model")),
+            reasoning_tokens=_coerce_reasoning_tokens(sink.get("usage")),
         )
 
     def _check_done(
@@ -484,6 +504,7 @@ class OpenAICompatTransport:
             raw={"usage": body.get("usage")},
             cached_prompt_tokens=_coerce_cached_tokens(body.get("usage")),
             model_reported=_coerce_model_reported(body.get("model")),
+            reasoning_tokens=_coerce_reasoning_tokens(body.get("usage")),
         )
 
     async def aclose(self) -> None:

src/polygateway/types.py

@@ -99,6 +99,15 @@ class LLMResponse:
     model_reported: str | None = None
     """API 响应体里的 model 字段;None = 未上报。与 `model`(配置别名)可能
     分叉——供应商把别名指向新权重时,实验复现必须认这个串。"""
+    reasoning_tokens: int | None = None
+    """推理消耗的输出 token 数(含在 `completion_tokens` 内,故不影响成本总额,
+    只补归因;issue #6)。
+
+    `None` = **本次调用**未上报,**不是**"该源不上报"——中转网关在上游不返回
+    usage 时会用本地 tokenizer 补算并整体替换 usage 对象,把
+    `completion_tokens_details` 一并吃掉(findings §4c 实测同一请求 10 轮呈
+    6:4 双峰)。实测三家供应商在未推理时都是整个 details 缺失、无人上报 `0`,
+    故下游判据须为 `in (None, 0)`,写 `== 0` 的条件永远不成立。"""
 
 
 @dataclass(frozen=True)
@@ -151,9 +160,10 @@ class TransportResult:
     ttft_ms: float | None
     max_inter_token_ms: float | None
     raw: dict[str, Any]
-    # —— 可观测字段(issue #3;带默认值,非 OpenAI 兼容的 transport 可不填)——
+    # —— 可观测字段(issue #3/#6;带默认值,非 OpenAI 兼容的 transport 可不填)——
     cached_prompt_tokens: int | None = None
     model_reported: str | None = None
+    reasoning_tokens: int | None = None
 
 
 @dataclass(frozen=True)