[Priority: Med] [Reliability] 增加上游并发控制与背压保护

[liujuanjuan1984]

背景

当前 OpencodeUpstreamClient 负责对 OpenCode 上游发起普通请求与流式请求，但主干里尚未看到统一的并发阈值或背压控制机制。若实例在高负载下同时向上游发起大量请求，适配层可能积压过多未决任务与连接。

当前问题

1. OpencodeUpstreamClient 当前没有统一的并发上限控制。
2. 没有明确的请求排队/拒绝策略。
3. 在上游延迟突增或下游并发放大场景下，实例内存与连接占用边界不够清晰。

这与 task persistence、session binding 或日志指标问题不同，属于适配层的 runtime reliability 议题。

期望方向

评估是否为 upstream adapter 增加最小背压保护：

• 为普通请求与流式请求定义统一或分类的并发限制；
• 明确超限时是排队、快速失败，还是按不同请求类型采用不同策略；
• 保持当前 API 语义不变，不把调度复杂度扩散到调用方。

非目标

• 不在本 issue 内同时引入完整队列系统或复杂 rate limiting 平台。
• 不把 peer A2A client cache / session cache 与 upstream concurrency 混为一谈。
• 不改变现有 A2A 对外协议契约。

建议实施步骤

1. 盘点 OpencodeUpstreamClient 各类请求入口及其资源占用模式。
2. 明确普通请求、streaming、abort、session query 是否需要共享同一限流策略。
3. 设计最小并发/背压机制及其配置边界。
4. 若进入实现阶段，补压力测试或最小并发回归测试。

验收标准

• 明确 upstream adapter 的并发保护范围。
• 明确超限行为与配置边界。
• 若进入实现阶段，补齐并发/背压相关测试。

[liujuanjuan1984]

补充建议 (借鉴 swival 设计):
在实现并发控制时，建议在 _handle_jsonrpc 层级针对 message/send 和 message/stream 方法引入基于 asyncio.Semaphore 的全局并发计数。同时，在应用层引入基于滑动窗口的请求频率限制（Rate Limiting），当达到阈值时直接返回 A2A 标准错误码 -32003 (Rate limited)。这可以防止单一 Client 的突发流量耗尽所有下游 OpenCode 运行时资源。

[liujuanjuan1984]

基于当前主干复审，建议的最小实施方案如下：

方案收敛

只在 upstream adapter 层增加最小并发保护，不引入复杂队列系统。

• 为 long-lived streaming 请求与普通 unary/control 请求分开建预算；
• 超限时采用快速失败，而不是默认排队；
• 保护逻辑留在 OpencodeUpstreamClient 内部，对上层 handler / executor 保持现有调用方式；
• 同步补齐超限错误映射与最小回归测试。

建议实现边界

1. 新增 adapter-level concurrency limiter。
2. 对 stream_events() 使用独立 stream budget。
3. 对 send_message() / create_session() / session_command() / list_sessions() / list_messages() / permission_reply() / question_reply() / question_reject() / abort_session() / session_prompt_async() / list_provider_catalog() 使用 unary budget。
4. 超限时抛出稳定的本地错误类型，避免裸露底层细节。
5. server 侧将该错误映射为稳定的 A2A failure contract。

配置建议

• OPENCODE_MAX_CONCURRENT_REQUESTS
• OPENCODE_MAX_CONCURRENT_STREAMS

语义建议：

• 0 表示不限制；
• >0 表示启用快速失败式并发上限。

非目标

• 不在本次引入等待队列或优先级调度。
• 不把 peer A2A client cache 与 upstream backpressure 混在一起。
• 不改变现有 A2A 对外协议。

[liujuanjuan1984]

已基于当前分支完成首版实现，当前结果如下：

已实施

• 在 OpencodeUpstreamClient 内增加 fast-fail 并发预算；
• 新增两个运行时配置：
  • OPENCODE_MAX_CONCURRENT_REQUESTS
  • OPENCODE_MAX_CONCURRENT_STREAMS
• 0 表示不限制，>0 表示启用快速失败式并发上限；
• stream_events() 使用独立 stream budget；
• 普通 unary/control upstream 调用统一使用 request budget；
• 超限时抛出稳定本地错误 UpstreamConcurrencyLimitError；
• executor 将该错误收敛为稳定 task failure metadata：UPSTREAM_BACKPRESSURE；
• JSON-RPC extension methods 将该错误映射为稳定 UPSTREAM_UNREACHABLE 响应，并附带 detail；
• guide 已补充新配置项说明。

回归验证

• uv run pytest --no-cov tests/upstream/test_opencode_upstream_client_params.py tests/execution/test_agent_errors.py tests/jsonrpc/test_error_responses.py tests/jsonrpc/test_opencode_session_extension_queries.py tests/jsonrpc/test_opencode_session_extension_prompt_async.py tests/jsonrpc/test_opencode_session_extension_interrupts.py
• ./scripts/doctor.sh

结果：392 passed，coverage 91.79%。

提交

• 3f63b9d fix(upstream): add fast-fail concurrency guards

[liujuanjuan1984]

当前实现已经通过 PR 提交审查：#327

• PR: fix(upstream): add fast-fail concurrency guards #327
• 标题：fix(upstream): add fast-fail concurrency guards

本轮复审结论：

• Closes #276 的关联准确；
• 未发现新的阻塞性问题；
• 当前残余风险是 fast-fail 设计在突发流量下会优先返回超限错误，而不是排队，这属于本次有意为之的边界选择。