[Priority: Med] [Enhancement] 引入中心化错误映射机制 (ErrorTranslator)

[liujuanjuan1984]

🔍 发现的问题 / 原始需求描述

目前错误转换逻辑散落在 upstream_errors.py、executor.py 和 jsonrpc/application.py 中，导致不同报错链路（上游 API、A2A 协议校验、沙箱策略）的错误返回行为缺乏统一标准。

🛠️ 详细实施方案

• 涉及文件: src/opencode_a2a_server/execution/errors.py
• 核心逻辑:
  1. 定义 ErrorTranslator 类，将各类异常统一映射为 A2A 标准的 event_queue 失败事件或符合 A2A 规范的 JSON-RPC 错误码。
  2. 使用 Python 枚举定义标准错误类型，确保 type=METHOD_NOT_SUPPORTED 等字段在各处调用一致。
• 伪代码:

  class ErrorTranslator:
      @staticmethod
      def to_a2a_event(exc: Exception) -> dict[str, Any]: ...
      
      @staticmethod
      def to_jsonrpc_error(exc: Exception) -> JsonRpcError: ...

🧪 回归测试建议

• 使用不同的测试用例模拟 HTTP 500、404、权限不足等上游报错。
• 验证返回的 A2A 事件格式（failed 状态）在各接口下完全对齐。

[liujuanjuan1984]

基于 eval/issue-288 / 2c5c54f，本次已先落一段可复用的中心化错误映射切片：

• src/opencode_a2a/client/error_mapping.py
• src/opencode_a2a/execution/tool_error_mapping.py

这次主要统一了两段链路：

1. outbound A2A client 的 HTTP / JSON-RPC / transport error 归类；
2. a2a_call synthetic tool result 的稳定错误输出。

说明：这与 #274 的方向一致，但当前还没有把 jsonrpc/application.py 与 execution/upstream_errors.py 一并并入同一个全局 ErrorTranslator。因此我建议本次对 #274 保持 related/in progress，不直接关闭。

[liujuanjuan1984]

基于当前主干（5395342）重新评估，结论如下。

1. 该需求依然合理且有效。

• 当前错误映射仍然分散在多处：
  • src/opencode_a2a/client/error_mapping.py
  • src/opencode_a2a/execution/tool_error_mapping.py
  • src/opencode_a2a/execution/upstream_errors.py
  • src/opencode_a2a/jsonrpc/application.py
• 其中前两处已经完成了一部分中心化；jsonrpc/application.py 仍保留较多分散的 JSONRPCError(...) / InvalidParamsError(...) / InternalError(...) 组装逻辑，upstream_errors.py 也仍维护一套独立 profile。

2. issue 原始实施方案已经过时。

• 旧路径 src/opencode_a2a_server/execution/errors.py 不再适用。
• 更重要的是，当前代码并不是只有两类输出面；至少有四类：
  • outbound client exception mapping
  • synthetic tool result error payload
  • JSON-RPC error response
  • streaming terminal / in-band upstream error
• 因此不建议现在再引入一个过于粗粒度、所有场景都强行塞进去的单体 ErrorTranslator 类。

3. 当前更符合主干最佳实践的方案应是“共享 taxonomy + 分出口 translator”，而不是“单一巨型 translator”。

• 建议保留并继续复用现有的：
  • client/error_mapping.py
  • execution/tool_error_mapping.py
• 新增一个更底层的共享错误画像/分类模块，用于沉淀：
  • upstream HTTP status -> canonical profile
  • auth / permission / timeout / unavailable / protocol / invalid params 等 canonical code
• 然后让不同出口各自消费这套共享画像：
  • jsonrpc/application.py 负责 JSON-RPC error response translator
  • execution/upstream_errors.py 负责 stream terminal / in-band translator
  • execution/tool_error_mapping.py 继续负责 tool payload translator

4. 本次分支如果继续开发，建议按以下顺序推进：

• 第一步：抽共享 upstream / protocol error profile，避免 jsonrpc/application.py 与 upstream_errors.py 各自维护状态码与 message 规则
• 第二步：把 jsonrpc/application.py 中分散的错误组装收敛到明确 helper
• 第三步：对齐 metrics / logging 所使用的稳定 error_code / error_type 字段
• 第四步：补回归测试，覆盖 HTTP 401/403/404/429/5xx、invalid params、upstream payload / contract error

5. 相关 open issues 判断。

• #276：相关但不建议本次一并实现。它关注并发控制与背压；本次最多在错误 taxonomy 上预留可复用 code，不要捆绑到同一分支。
• #279：相关但不建议本次一并实现。metrics 标签最终应复用统一 error taxonomy，但 issue 本身是生产/消费逻辑对齐，不应在本分支扩大范围。
• 当前没有其它必须与 #274 同分支关闭的 open issue。

结论：#274 应继续保留并推进，但实施方案需要从“单一 ErrorTranslator 类”调整为“共享错误画像 + 分出口 translator”。

[liujuanjuan1984]

本次已在分支 eval/issue-274 上完成第一轮完整实现，方向与前述重评估一致：不是引入一个单体 ErrorTranslator，而是落地“共享 taxonomy + 分出口 translator”。

已完成：

1. 共享 upstream taxonomy

• 新增 src/opencode_a2a/error_taxonomy.py
• 将 upstream HTTP status -> canonical profile、response detail 提取逻辑抽到共享模块
• execution/upstream_errors.py 改为复用该共享 taxonomy，不再单独维护状态码画像

2. JSON-RPC error translator

• 新增 src/opencode_a2a/jsonrpc/error_mapping.py
• 将以下错误出口的组装收敛到专门 translator：
  • unsupported method
  • session forbidden / not found
  • interrupt not found / expired
  • invalid params / internal error
  • upstream http / unreachable / payload mismatch

3. application.py 收口

• src/opencode_a2a/jsonrpc/application.py 中原先分散的 JSONRPCError(...) / InvalidParamsError(...) / InternalError(...) 组装已接入 translator
• 保持现有 business code 与对外契约不变；重点是减少分散逻辑和重复规则

4. 回归测试

• 新增 tests/jsonrpc/test_error_mapping.py
• 现有集成测试继续覆盖 session query / prompt_async / command / interrupt 等 JSON-RPC 链路

验证：

• uv run pre-commit run --all-files
• uv run pytest
• 结果：348 passed，coverage 91.07%

下一步建议：

• 继续在本分支补一轮 PR 级审查，确认是否还存在冗余 helper、是否需要进一步把 metrics/logging 直接接到统一 taxonomy。