[bug] a2a_call 工具失败返回应统一错误码而非裸露 str(exc)

[liujuanjuan1984]

背景

PR #286 在 OpencodeAgentExecutor._handle_a2a_call_tool 中捕获异常后直接返回 str(exc)。
该路径会把底层异常文本直接透出给上层工具执行结果。

问题现象

在 a2a_call 失败场景（如鉴权错误、超时、解析失败）中，返回的 tool output error 内容可能包含过细的实现细节。

重现步骤

1. 在上游工具触发 a2a_call 且目标 peer 返回异常（如 401、超时、协议解析错误）。
2. 查看工具返回的 error 字段。

预期

• a2a_call 的错误应返回可归类、可追踪但不泄露过细底层细节的稳定结构（例如统一错误码+可读短语）。
• 兼容当前错误消费方对 error 字段存在性的判断。

实际

• 直接返回 str(exc)，字段内容与底层 SDK/网络实现耦合，缺少稳定结构。

验收标准

• 引入统一错误映射（如鉴权、网络、超时、协议类区分）。
• a2a_call 返回结果中错误消息稳定、可用于上游识别。
• 补充最少一条失败分支测试（覆盖典型异常类型）。

相关提交与快照

• 关联 PR：feat(a2a): add outbound A2A client facade, CLI call, and streamed a2a_call integration #286
• 当前提交：2bd888e5684dadab3bd3e8f9e7bfcdf957774376

[liujuanjuan1984]

基于当前 main 重新评估，#288 的需求仍然合理且有效，但不建议只在 OpencodeAgentExecutor._handle_a2a_call_tool 内把 str(exc) 替换成另一段分支判断后结束。

当前仓库已经有两层可复用的错误归类基础：

• src/opencode_a2a/client/errors.py 已定义 A2AAgentUnavailableError、A2AClientResetRequiredError、A2AUnsupportedOperationError、A2APeerProtocolError 等稳定错误类型。
• src/opencode_a2a/execution/upstream_errors.py 已承担服务端执行链路的稳定错误映射。

因此，#288 更合理的实施方式应当是：

1. 为 a2a_call 工具结果引入一个薄的统一错误映射层，而不是继续在 _handle_a2a_call_tool 里堆叠 except 细节。
2. 该映射层优先消费 A2AClientError 及其子类，输出稳定的错误码与短语，避免把底层 SDK / HTTP / JSON-RPC 原始文本直接暴露到 error 字段。
3. 对调用方兼容上，保留 error 字段存在性语义；如果需要补充机器可读信息，建议以附加字段承载，而不是让 error 继续承载底层异常全文。
4. 实施范围应与全局错误收敛方向保持一致，避免在 executor.py 新增另一套分散映射逻辑。

高度相关的 open issues：

• #274：中心化错误映射机制，和本 issue 是最直接的上位关系，建议至少按同一错误分类口径实现。
• #292：A2AClient facade 职责收敛，其中已经包含“调用集中化 error mapping”的方向。若本次修改会新增 client 侧错误映射 helper，建议与该 issue 协调设计，避免后续重复搬迁。

当前建议是：

• 本分支聚焦完成 #288 的可交付修复；
• 但实现方式要显式对齐 #274 / #292 的方向，抽成可复用 helper，而不是做单点字符串替换。

[liujuanjuan1984]

本次实现已推送到分支 eval/issue-288。

• commit: 2c5c54f
• branch: eval/issue-288

本次落地内容：

1. a2a_call 工具失败不再直接暴露 str(exc)，而是统一返回稳定 error + error_code，并按需附带非敏感 error_meta。
2. 新增 src/opencode_a2a/execution/tool_error_mapping.py，集中处理 tool result error payload 映射。
3. 新增 src/opencode_a2a/client/error_mapping.py，将 outbound client 的 HTTP / JSON-RPC / transport error 归类为稳定异常类型。
4. 同步拆出 agent_card.py、request_context.py、payload_text.py，避免继续把 helper 堆在 client.py 中。
5. 已补充回归测试，覆盖 a2a_call 的 auth / protocol / unavailable / invalid input 等典型失败分支。

验证结果：

• uv run pre-commit run --all-files
• uv run pytest
• 338 tests passed
• coverage: 90.62%

与其它 issue 的关系：

• 本次直接解决 #288
• 实现方式显式对齐 #274 的中心化错误映射方向
• 同时吸收了 #292 中 client helper 拆分与 error mapping 收敛的设计