[feat] 完善 peering 场景的 outbound A2A client 与工具调用链路

[liujuanjuan1984]

背景

当前分支的实际改动范围已经超出最初“新增最小 A2A client 骨架”的讨论范畴。

除了 src/opencode_a2a/client/ 初始化能力之外，本轮实现还实际引入并修正了 peering 场景下的 outbound A2A 调用链路，包括：

• CLI 侧 direct outbound call 入口
• server 内 a2a_call 工具执行链路
• outbound bearer auth
• streamed peer output 消费
• server 侧 outbound client 配置全量接线

因此本 issue 需要从“client 初始化骨架”更新为覆盖当前真实交付范围的跟踪项。

现状

• 当前仓库已经具备 A2A server 侧运行时能力。
• 当前分支已新增 src/opencode_a2a/client/，并将其接入 peering/runtime 执行链路。
• 当前变更不再只是静态骨架，而是已经形成可用的 outbound A2A client 支撑能力。

需求目标

在不破坏现有 server 主体能力的前提下，完成面向 peering 场景的 outbound A2A client 支撑：

1. 建立可复用的 client/ 模块边界与 facade。
2. 提供 CLI 侧 outbound A2A 调用能力。
3. 让 server 能执行 a2a_call 工具，并消费下游 peer 的真实输出。
4. 补齐 outbound 鉴权与配置接线，避免半接线与运行时偏差。
5. 同步文档与测试，保证行为可以被验证与维护。

实际改造范围

client facade

• 新增 src/opencode_a2a/client/ 下 facade、配置、错误模型与公开类型。
• 支持 agent card 获取、发送消息、查询任务、取消任务、重订阅任务。

peering / runtime integration

• 新增 CLI opencode-a2a call 子命令。
• executor 支持处理 OpenCode 返回的 a2a_call 工具调用。
• 引入 A2AClientManager 管理 server 生命周期内的 outbound client 复用。

reliability fixes

• 修正 outbound bearer auth 缺失问题。
• 修正 streamed peer output 仅返回占位文本的问题。
• 补齐 server 侧 outbound client 配置：
  • A2A_CLIENT_TIMEOUT_SECONDS
  • A2A_CLIENT_CARD_FETCH_TIMEOUT_SECONDS
  • A2A_CLIENT_USE_CLIENT_PREFERENCE
  • A2A_CLIENT_BEARER_TOKEN
  • A2A_CLIENT_SUPPORTED_TRANSPORTS

docs / tests

• 更新 README.md 与 docs/guide.md。
• 新增并补充 client / executor / server 相关测试。

验收标准

• 在 src/opencode_a2a/client/ 下建立清晰的 client 模块边界。
• 提供最小可用的 outbound A2A client facade。
• 提供 CLI 侧 outbound 调用入口。
• 让 a2a_call 工具链路可以消费下游 peer 真实输出。
• 补齐 outbound 鉴权与配置接线。
• 补充文档说明与测试覆盖。
• 完成基线验证：uv run pre-commit run --all-files、uv run pytest。

关联实现

• Draft PR: feat(a2a): add outbound A2A client facade, CLI call, and streamed a2a_call integration #286

代码仓库快照

• git rev-parse HEAD: d0e43d4cac272ba2cf7b7a4518eb71ae54864311

[liujuanjuan1984]

评估结论：不建议直接照搬 a2a-client-hub 全量。

建议先做 最小 client 通用层，保留现有包结构，在 下新增 子模块，不需要先重构包级目录。

照搬优先级（高->低）：

1. 可复用： 的 facade 思路、 的 SDK 适配实现、 的 endpoint/peer 归一化。
2. 可复用： 与部分错误映射（）逻辑。
3. 先暂不带： 这类依赖 hub 内部 auth/db/runtime 的服务层组织。

实施拆解建议：

• P1：搭建 client 骨架（, , , ），实现 。
• P2：补齐测试（），覆盖 1) 正常调用 2) jsonrpc/protocol 错误归一。
• P3：再补 级缓存和生命周期，再考虑 streaming 与多 transport 策略。

当前 issue 建议跟进该顺序执行，避免把 a2a-client-hub 的 hub 层能力误带入轻量库。

[liujuanjuan1984]

评估结论：不建议直接照搬 a2a-client-hub 全量。

建议先做「最小 client 通用层」，保留现有包结构，在现有 src/opencode_a2a/ 下新增 client/ 子模块，不需要先重构包级目录。

照搬优先级（高到低）：

1. 可复用：a2a-client-hub 中的 app/integrations/a2a_client/client.py 的 facade 思路、adapters/sdk.py 的 SDK 适配实现、selection.py 的 endpoint/peer 归一化。
2. 可复用：errors.py 与部分错误映射（a2a_error_contract.py）逻辑。
3. 先暂不带：registry/session_factory/invoke_session/resolution/metrics/validators 这类依赖 hub 内部 auth/db/runtime 的服务层组织。

实施拆解建议：

• P1：搭建 client 骨架（client/types.py, client/config.py, client/errors.py, client/client.py），实现 get_agent_card / send / get_task / cancel。
• P2：补齐测试（tests/client/test_*），覆盖 1) 正常调用 2) jsonrpc/protocol 错误归一。
• P3：再补 gateway/registry 级缓存和生命周期，再考虑 streaming 与多 transport 策略。

当前 issue 建议按该顺序执行，避免把 a2a-client-hub 的 hub 层能力误带入轻量库。

[liujuanjuan1984]

已更新：该分支以 issue #285 的 P1/P2 两阶段目标推进。

• P1（本轮）：实现 src/opencode_a2a/client/ 最小骨架（轻量通用 A2A client 初始化能力）：

  • types.py
  • errors.py
  • config.py
  • client.py
  • 支持 get_agent_card、send_message（非流式）/send、get_task、cancel_task
  • 统一错误映射（JSON-RPC error -> A2A peer protocol error），保持与现网上游语义一致。

• P2（本轮）：新增 client 基础测试（tests/client/）：

  • 正常初始化与依赖注入行为。
  • send / get_task / cancel 的最小成功用例。
  • 关键错误路径（协议错误映射、HTTP 错误等）
  • 生命周期关闭与资源清理。

后续阶段（P3）不在本轮范围内，暂不引入 hub 式 registry/session_factory/gateway/metrics。

[liujuanjuan1984]

已开始按 issue #285 执行: 1) 新建 client 侧初始化模块骨架（config/errors/client）；2) 增加最小初始化测试；3) 更新 guide 文档边界；4) 提交并创建 PR。当前已创建分支 feat/a2a-client-init，并已创建 issue 记录，下一步完成代码与测试后会同步进度与风险。

[liujuanjuan1984]

当前进展（更新到 1/2 目标）

已完成 issue #285 的 P1/P2 范围：

• P1：新增 src/opencode_a2a/client/ 最小 client 初始化骨架

  • types.py：定义对外导出的 client 事件/流/元数据类型
  • errors.py：定义 client 侧错误基类与分类（不可达、重试、协议、操作不支持等）
  • config.py：实现 client 专用设置加载与解析（超时、偏好、传输清单）
  • client.py：实现 A2AClient facade 与 get_agent_card/send/send_message/get_task/cancel_task/resubscribe_task

• P2：新增 client 最小测试集合

  • tests/client/test_client_config.py
  • tests/client/test_client_facade.py
  • 覆盖初始化、路径规范化、参数透传、异常映射、生命周期行为

附带文档更新：

• docs/guide.md 补充 client 与 server 边界说明与 client bootstrap 接口列表

验证结果：

• uv run pre-commit run --all-files
• uv run pytest（全量）
• uv run pytest --no-cov tests/client
• uv run python -m py_compile src/opencode_a2a/client/*.py tests/client/*.py

未引入服务端行为变更，仍为 client 侧初始化层的增量实现。
已创建/同步分支：feat/a2a-client-init，后续可按 P3 补充 gateway/session/cache 等更完整消费层。

[liujuanjuan1984]

补充更新：已完成到 1/2 目标后提交到 PR。

• PR：https://github.com/Intelligent-Internet/opencode-a2a/pull/286（Draft）
• Commit：b358213
• 覆盖范围：src/opencode_a2a/client/*、tests/client/*、docs/guide.md
• 关键结论：服务端行为未改动；client 侧初始化能力已就绪并通过全量测试。

可继续按 issue #285 的阶段划分推进 P3（gateway/session 缓存与更完整消费层）。

[liujuanjuan1984]

补充更新：已完成到 1/2 目标后提交到 PR。

• PR：https://github.com/Intelligent-Internet/opencode-a2a/pull/286（Draft）
• Commit：b358213
• 覆盖范围：src/opencode_a2a/client/*、tests/client/*、docs/guide.md
• 关键结论：服务端行为未改动；client 侧初始化能力已就绪并通过全量测试。

可继续按 issue #285 的阶段划分推进 P3（gateway/session 缓存与更完整消费层）。

[liujuanjuan1984]

已推进第一步：先补齐 outbound A2A bearer token 鉴权链路。

本次变更：

• 新增 A2A_CLIENT_BEARER_TOKEN 配置，并注入 outbound request metadata。
• 贯通 A2AClient / A2AClientManager / server 内 a2a_call 相关路径。
• README 与 docs/guide.md 同步补充 outbound bearer token 说明。
• 补充最小 client 配置与 metadata 注入测试。

提交：42e3b71 fix: forward bearer auth for outbound a2a calls #285

[liujuanjuan1984]

已推进第二步：修正 a2a_call 对下游 A2A 流式结果的消费方式。

本次变更：

• 为 A2AClient 增加统一文本提取 helper，用于从 Message / Task / TaskArtifactUpdateEvent / 映射负载中抽取可读文本。
• executor 内 a2a_call 不再只取最后一个事件占位，而是消费整条下游事件流，优先提取真实输出文本。
• 测试补充流式 artifact 与 task status message 的覆盖。

提交：682251e fix: consume streamed peer output for a2a tool calls #285

[liujuanjuan1984]

已推进第三步：补齐 server 侧 outbound A2A client 配置接线，去掉“半接线”状态。

本次变更：

• Settings 正式加入并解析 A2A_CLIENT_CARD_FETCH_TIMEOUT_SECONDS、A2A_CLIENT_SUPPORTED_TRANSPORTS。
• A2AClientManager 改为向 embedded outbound client 全量下发 timeout / card fetch timeout / transport preference / bearer token / use_client_preference。
• README 与 docs/guide.md 从预览/半接线表述调整为真实已支持配置。
• 新增 server 侧配置透传测试。

提交：8c1b984 refactor: wire full outbound a2a client settings #285