docs(spec): document the Responses stream termination patch and E2E-248

Author: yexisu

docs/spec/03-runtime/11-provider-model-system.md

@@ -610,6 +610,19 @@ model-level pin the provider-wide style applies unchanged.
 
 This is the **universal escape hatch** guaranteeing market coverage beyond native integrations.
 
+### 16.1 Responses stream termination (pi-ai patch)
+
+The OpenAI Responses adapter must treat `response.completed` (and
+`response.incomplete`) as the end of the stream: after finalizing the
+response, it stops consuming the stream instead of awaiting the server's
+TCP FIN. Upstream pi-ai keeps iterating until the server closes the
+connection, which hangs the turn behind reverse proxies that hold the idle
+connection open. Until the fix ships upstream, `patches/` carries a pnpm
+patch on `@earendil-works/pi-ai@0.85.1` that breaks the event loop on the
+terminal event (the OpenAI SDK aborts the underlying request when the
+consumer stops iterating). Drop the patch once a pi-ai release includes the
+fix.
+
 ## 17. Multi-provider product rules
 
 1. Multiple providers of the same `vendorKey` are allowed and independent (for

docs/spec/06-delivery/04-e2e-test-plan.md

@@ -660,6 +660,29 @@ Each scenario is documented in this format:
 - **Status**: Unit-covered (preset matching, catalog aliases, Completions
   compat); rendered UI scenario Draft
 
+#### E2E-248: Responses turn completes without waiting for the server to close the connection
+
+- **Preconditions**: A provider whose model pins `api: "openai-responses"` (or
+  a provider with `apiStyle: "responses"`) is configured; the endpoint is
+  fronted by a proxy that holds the HTTP connection open after the final
+  SSE event (a local reverse proxy or a stub server that never sends FIN).
+- **Steps**: 1) Start a session with that model and send a short prompt. 2)
+  Capture the SSE frames and confirm the server emitted
+  `response.completed` with `status: "completed"` and usage. 3) Keep the
+  stub/proxy connection open without sending a TCP FIN. 4) Observe the
+  assistant turn state and send a follow-up prompt.
+- **Expected**: The turn completes as soon as `response.completed` is
+  finalized: usage is recorded, `stopReason` is `stop`, and the client stops
+  consuming the stream (the underlying request is aborted) instead of
+  blocking on the idle connection. The composer becomes idle immediately and
+  the follow-up turn starts normally. The stream must not hang when the
+  server never closes the connection.
+- **Specs linked**: `03-runtime/11-provider-model-system.md` (§16.1)
+- **Acceptance**: B (provider Responses compatibility)
+- **Milestone**: M2
+- **Status**: Unit-covered (stream processor terminates on the terminal
+  event via the pi-ai patch); live-proxy scenario Draft
+
 #### E2E-005E: DeepSeek thinking replay includes reasoning_content on aggregator endpoints
 
 - **Preconditions**: An OpenAI-compatible provider whose base URL is not

docs/zh-CN/spec/03-runtime/11-provider-model-system.md

@@ -542,6 +542,17 @@ UI 可能会显示层级提示，但默认情况下不得硬阻止未知模型
 
 目录条目还可以额外固定模型级 wire API（例如 `api: "openai-responses"`）。存在时它优先于 provider 级 `apiStyle`，因此 `opencode_go` 下的 responses-only 模型会走 Responses adapter 而非 Chat Completions；没有模型级固定时保持 provider 级风格不变。
 
+### 16.1 Responses 流终止（pi-ai 补丁）
+
+OpenAI Responses 适配器必须把 `response.completed`（以及
+`response.incomplete`）视为流的终点：完成响应收尾后即停止消费流，
+而不是继续等待服务端的 TCP FIN。上游 pi-ai 会一直迭代直到服务端关闭
+连接，在保持空闲连接不关的反向代理后面会导致整个回合挂起。在该修复
+随上游发布之前，`patches/` 通过 pnpm patch 修改
+`@earendil-works/pi-ai@0.85.1`，在终态事件处跳出事件循环（消费方停止
+迭代时 OpenAI SDK 会中止底层请求）。待 pi-ai 发布包含该修复的版本后
+移除补丁。
+
 ## 17. 多提供商产品规则
 
 1. 允许多个提供商具有相同的供应商密钥（例如两个 OpenRouter 帐户）。