feat: preserve governed OpenAI tool messages in 1.4.0

Add faithful single-choice chat results, tool stream activity, error-frame retries, and isolated protocol caching.

Reject empty cached completions with the same value predicate as transport, add regression coverage, and adopt Apache-2.0.

README.md

@@ -19,6 +19,7 @@
 | 调用期限 | 一次逻辑调用可选一条**墙钟硬边界**(`{SCOPE}__CALL_DEADLINE_S` 或 `chat(call_deadline_s=...)`,缺省不启用):治理的是**等待**——重试退避、配额轮询、熔断冷却、结构化重问与 embedding 分批共享同一份期限。三条须知:①**返回时刻 = 期限 + 清理耗时**(遥测/结算/缓存收尾在 `finally` 里跑完,允许超期;实测构造达期限的 5–7 倍),库只承诺切断等待、不给返回上界;②**到期 ≠ 未产出、≠ 未计费**,上游可能已算完并计费;③**不配置即逐字保持 1.3.5 语义**(纯 429 序列仍可能长等、有限大 `Retry-After` 仍照睡)。到期抛 `CallDeadlineExceeded`,**不属四分类、不属 `GatewayUnavailableError` 族** |
 | 长尾对冲 | **默认关闭**的可选加速(`{SCOPE}__HEDGE__AFTER_S`,仅 chat):一次尝试挂起超阈值时向**异源**并发再发一次,先回者赢、输家取消。流式以「首 token 未至」为触发判据(不误杀慢生成),非流式只有纯总时长阈值;对冲走完整限流/熔断准入,拿不到配额静默放弃。成本须知:开启即用配额换延迟(触发窗口内 in-flight 翻倍),输家取消按 est 保留预扣且**可能已被上游计费**(取消止不住上游);输家不喂熔断,遥测 attempt 行标 `error="hedge_cancelled"` 可按 `logical_call_id` join 对账;两路皆败只计一次重试预算;与 `call_deadline_s` 正交组合(装配守卫强制对冲阈值 < 期限)
 | 中段沉默对冲(可选,超业界现状能力) | **默认关闭**(`{SCOPE}__HEDGE__STALL_AFTER_S`,仅流式 chat):主路**首 token 之后**相邻增量 chunk 沉默超阈值时向异源并发再发一次,与首 token 对冲 `HEDGE__AFTER_S` **独立生效**、可独设可组合;仅设它且请求非流式 → 逐字走单路(中段沉默无非流式概念)。**诚实标注:中段沉默触发并发副本在主流网关/库中无公开先例**(业界收敛为看门狗掐流重试)。成本须知:下游实测沉默 >20s 占 19.0%,触发率远高于首 token 对冲,开启即用配额换延迟,输家可能已被上游计费;看门狗掐死**喂**熔断而对冲输家取消**不喂**(不对称声明),详见[1.3.8 生成时间口径与中段沉默对冲](#138-生成时间口径与中段沉默对冲) |
+| OpenAI 消息保真(1.4.0) | `chat(response_mode="openai")` 返回完整 assistant 消息/工具调用、finish_reason、上游 ID 与 usage；单 choice，复用治理，不执行工具；默认仍为文本模式 |
 | 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace(缓存隔离单位)+ salt + 采样参数 + 请求级推理档位(同 messages 跑 low 与 max 不互相命中),多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
 | 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 |
 | 推理可观测性 | "这次到底推理没推理"由多信号裁定(推理正文压倒 usage 明细),三态落在 `LLMResponse.thinking_observation`:`observed` / `absent` / `unknown`——**`unknown` 是"本次判不出",不是"没推理"**;本次实发档位与实测观测矛盾时按 `(源, 模型, 生效档位)` 各告警一次(能力表过期、开启未生效、注入了却观测不到;同一模型的 low 与 max 是两个独立的矛盾,不共用节流键);裁定结果随遥测落库 |
@@ -137,7 +138,7 @@ stats.total_latency_ms             # 含缓存 IO、退避、准入等待、重
 | `{SCOPE}__STREAM__STALL_THRESHOLD_MS` | 正整数毫秒 | **1000** | 仅改计量口径,不改任何行为;三层调整接口同权(env 键 / `GatewaySettings.stall_threshold_ms` / `GatewayClient(stall_threshold_ms=...)`);无 per-call 覆盖,不做自适应(防与对冲阈值耦出反馈环) |
 | `{SCOPE}__HEDGE__STALL_AFTER_S` | 有限正数秒 | **未设 = 关闭** | 独立于 `HEDGE__AFTER_S` 生效;守卫: `≥ min(各源 inter_token_timeout_s 或 timeout_s)`(对冲窗永不开)或 `≥ call_deadline_s` → 装配期 **ValueError**,单源 scope → warning;三层调整接口同权(env 键 / `GatewaySettings.hedge_stall_after_s` / `GatewayClient(hedge_stall_after_s=...)`);Embedding/OCR scope 配任一对冲键 → warning 后静默退化 |
 
-对冲语义(两阶段触发窗/复检防误触发/取消穿透)与成本披露见 [CHANGELOG 未发布段](CHANGELOG.md);运维「挂起率」统计须知不对称:看门狗掐死**喂**熔断失败计数,对冲输家取消**不喂**熔断。
+对冲语义(两阶段触发窗/复检防误触发/取消穿透)与成本披露见 [CHANGELOG 1.3.8 段](CHANGELOG.md);运维「挂起率」统计须知不对称:看门狗掐死**喂**熔断失败计数,对冲输家取消**不喂**熔断。
 
 ## 安装
 
@@ -145,7 +146,7 @@ stats.total_latency_ms             # 含缓存 IO、退避、准入等待、重
 
 ```bash
 pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
-    "polygateway[redis,postgres,structured]>=1.3.8,<2"
+    "polygateway[redis,postgres,structured]>=1.4.0,<2"
 ```
 
 核心仅依赖 `httpx` + `pydantic`;按需选 extras:
@@ -610,3 +611,72 @@ make ci        # 只读全量验证
 ## 兼容性承诺
 
 `LLMResponse` 等被下游消费的公共类型,字段**只增不删不改名**且新增字段必带默认值;`{SCOPE}__{PROVIDER}__{N}__{FIELD}` 与平铺韧性键名(`LLM_TIMEOUT` 等)沿用三项目既有习惯,不做破坏性改名。实验室内部库,随实验室项目需求演进。
+
+## 1.4.0 OpenAI 工具消息保真（单 choice）
+
+`chat(..., response_mode="openai")` 仍返回 `LLMResponse`，完整协议结果在
+`response.completion`：`message`、`finish_reason`、`response_id`、`usage`。
+`content/thinking` 是旧文本投影（可剥离 think 标签）；回传代理或继续对话应使用
+completion.message，不能从旧投影重建工具响应。嵌套 JSON 是独立快照但仍可修改。
+
+```python
+response = await client.chat(
+    messages,
+    response_mode="openai",
+    overlay={"tools": tools, "tool_choice": "auto"},
+)
+completion = response.completion
+messages.append(completion.message)
+# 工具执行与 role=tool 结果由调用方添加；库不会执行工具。
+```
+
+保真是 JSON 字段和值保真，不是 HTTP 字节透明代理。仅支持单 choice（`n=1`），
+可含多个并行 function tool_calls；arguments 逐字拼接，不解析、修复或执行。
+SSE 支持 role/content/reasoning_content/tool_calls，未知增量字段会明确失败；
+非流式保留整个 message 扩展字段，不返回顶层 logprobs/created 等其他字段。
+上游实际模型仍读 `model_reported`，配置别名是 `model`。
+
+| 边界 | 行为 |
+|---|---|
+| 空文本且有完整工具 | 正常成功；不完整工具或无任何有效产物仍失败 |
+| error 帧 | 所有模式立即判失败并走已有重试；后续 DONE 不挽救 |
+| 缺 DONE | 保真模式不受 salvage 放宽，防截断工具被执行 |
+| finish_reason=length | 原样返回，不修补参数；调用方自行判断是否执行 |
+| structured | 不可与保真并用；自行传 overlay.response_format 不启用库的修复/重问阶梯 |
+| raw 推理 | 保真不是校验逃生口；raw-only 要求源 ENABLE_THINKING/REASONING_EFFORT 均未设置，请求档为 None，再通过 overlay.reasoning_effort 传原值 |
+
+工具实际增量与正文/推理共用首 token、inter-token、stall 对冲及沉默计量；注释、
+usage、role-only、重复工具身份不算进展。非流式无中段事件，保持纯时长阈值对冲。
+`Transport.complete` 的自定义实现须接收必填 `response_mode`；不支持保真时明确
+RequestRejected，不能伪造 completion 或静默退回文本。
+
+缓存按返回模式隔离；缺协议、畸形协议或无正文无工具的条目按 miss 回源。命中保留历史上游 response_id/usage，生成本次治理 call_id，
+本次 attempts=0、cost=0。**旧文本缓存可能含修复前 error+DONE 的截断产物**：
+受影响调用集合须在首次读写前更换从未承载旧语义的 namespace 或 salt，包含工厂、
+全量注入和 per-call 覆盖，保留租户前缀与 epoch。未迁移仍可能读旧值，库不自动清除。
+遥测继续单一出口，不新增工具全文列；既有 TEXT_CAP 不覆盖 tool_calls.arguments。
+
+### 线程模型的异步桥接
+
+库不新增同步客户端。socketserver 等工作线程应向**一个常驻事件循环线程**提交：
+client 必须在该 loop 内创建、使用并关闭，不能每请求 asyncio.run 或跨 loop 共用
+httpx/Redis 组件。下例的 loop 和 client 已由宿主完成初始化：
+
+```python
+future = asyncio.run_coroutine_threadsafe(
+    client.chat(messages, response_mode="openai", overlay=overlay), loop
+)
+try:
+    response = future.result(timeout=timeout_s)
+except TimeoutError:
+    future.cancel()  # 断连也应取消；取消不等于上游未计费。
+    raise
+```
+
+应用退出时先停止接单、取消/等待在途调用，在同一个 loop 中 await client.aclose()，
+再停 loop 并 join 线程；注入组件仍由所有者关闭。不要从 loop 本身阻塞调用 future.result。
+
+## 许可证
+
+PolyGateway 使用 [Apache License 2.0](LICENSE)。内部移植代码的原创 owner 已明确授权；
+分发范围不包含 `reference/` 外部参考仓。