fix(upstream): add fast-fail concurrency guards

[liujuanjuan1984]

概述

本 PR 在当前分支上合并了三类改动：

• 修正 Quick Start 中的服务端启动示例，明确带上本地 durable task store 的 SQLite URL。
• 保持 opencode-a2a call 示例只表达 outbound peer credential 注入，不再混入服务端 database store 配置。
• 实现 #276 所跟踪的 upstream adapter 最小并发保护，采用 fast-fail 策略收敛 unary/control 与 streaming 请求的资源边界。

模块一：README 启动示例修正

对应提交：91a68e7、ee8547c

• 在 Quick Start 的 opencode-a2a 服务启动命令中补充 A2A_TASK_STORE_DATABASE_URL=sqlite+aiosqlite:///./opencode-a2a.db。
• 将此前误放到 opencode-a2a call 示例里的 database URL 移回服务端启动示例。
• 让用户在直接照抄 Quick Start 时，不会遗漏默认 durable store 配置，同时避免误解 outbound call 也依赖该变量。

模块二：upstream 并发保护与错误收敛

对应提交：3f63b9d

• 在 OpencodeUpstreamClient 中增加 fast-fail 并发预算：
  • OPENCODE_MAX_CONCURRENT_REQUESTS
  • OPENCODE_MAX_CONCURRENT_STREAMS
• 0 表示不限制，>0 表示启用快速失败式并发上限。
• 对 long-lived /event stream 与普通 unary/control upstream 请求分开建预算，避免二者混用同一资源边界。
• 超限时抛出稳定本地错误 UpstreamConcurrencyLimitError，不泄露底层 transport 细节。

模块三：协议层错误映射、文档与测试

对应提交：3f63b9d

• executor 将 upstream 超限收敛为稳定 task failure metadata：UPSTREAM_BACKPRESSURE。
• JSON-RPC extension methods 将 upstream 超限统一映射为稳定 UPSTREAM_UNREACHABLE 响应，并附带 detail。
• guide.md 补充新的并发配置项说明，并修正过时的 outbound auth 文案。
• 补齐 upstream client、executor、JSON-RPC query / discovery / control / interrupt 的回归测试。

验证

• 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%。

关联

Closes #276

[liujuanjuan1984]

本轮复审结论：未发现新的阻塞性问题。

判断依据：

• OpencodeUpstreamClient 的 fast-fail 并发保护收敛在 adapter 层，没有把调度复杂度扩散到上层调用方；
• /event stream 与 unary/control 请求分预算，方向合理，能避免长连接与普通请求抢占同一边界；
• executor 与 JSON-RPC extension 都补了稳定错误出口，协议层行为比直接透出底层异常更稳健；
• 文档与测试覆盖同步到位，./scripts/doctor.sh 已通过。

残余风险只有一项，且当前可接受：

• 当前策略是 fast-fail，不做排队；在突发高并发下会优先返回超限错误，而不是等待。这是本次设计的明确取舍，不是实现缺陷。

issue 关系复核：

• Closes #276 准确。
• 本 PR 里的 README 示例修正没有对应 tracking issue，当前无需额外补一个 related issue。

[liujuanjuan1984]

补充修正：README 里的 A2A_TASK_STORE_DATABASE_URL 已从 opencode-a2a call 示例移回 Quick Start 的服务端启动命令。

原因：这个变量描述的是当前服务实例的 durable task store 配置，不属于 outbound peer call 的 credential 示例。