[Priority: Med] [Feature] Client 侧自动轮询回退机制 (GetTask)

[liujuanjuan1984]

背景

当前 A2AClient 已不是“主要同步阻塞模式”。主干中的 facade 以 stream-first 为主：

• send_message() 直接流式消费 peer 返回的 A2A 事件；
• send() 只是对流式结果做最终事件收敛；
• 已提供 get_task() 与 resubscribe_task() 作为显式任务查询/重订阅入口。

但当前 client 构建仍显式关闭 SDK polling（ClientConfig(... polling=False)），因此当对端 server 采用“先返回 non-terminal Task，再要求 client 通过 tasks/get 轮询结果”的模式时，当前 facade 仍缺少自动回退能力。

当前问题

当 peer A2A server：

1. 不提供稳定 streaming；或
2. 对 message/send 返回 working / 其他 non-terminal Task；且
3. 需要 client 继续通过 tasks/get 才能拿到最终结果

则当前 A2AClient.send() / send_message() 不会自动接管后续 polling 流程，需要调用方自行组合 get_task() 或 resubscribe_task()。

期望方向

评估是否为 facade 增加一个可选的自动 polling fallback：

• 仅在收到 non-terminal Task 且未进入 streaming completion path 时触发；
• 采用有上限的退避与超时，而不是无限轮询；
• 保持当前显式 get_task() / resubscribe_task() API 不变；
• 不改变默认的 stream-first 模型。

非目标

• 不把 facade 改回同步阻塞优先。
• 不取代 resubscribe_task() 的显式订阅能力。
• 不在本 issue 内同时扩展 transport negotiation 或 peer capability discovery。

建议实施步骤

1. 盘点当前 send() / send_message() 对 non-terminal Task 的返回形态。
2. 明确触发 polling fallback 的边界条件。
3. 设计 polling 参数：间隔、退避、总超时、最大尝试次数。
4. 先补 façade 层测试，再决定是否实现。

验收标准

• 明确 non-terminal Task 的自动 polling 触发条件。
• 明确 fallback 与显式 get_task() / resubscribe_task() 的职责边界。
• 若进入实现阶段，补齐回归测试与超时/错误路径测试。

关联

• Related [Priority: Med] [Feature] Server 侧 SSE 流式心跳与空闲状态反馈 #311
• Related [Priority: Med] [Reliability] 收敛 durable task 的终态一致性与 task store 异常契约 #321

[liujuanjuan1984]

基于当前 main（2026-03-26）复核，#310 仍然是一个合理且仍有效的需求，且建议继续保留为 client facade 层议题。

复核结论：

1. 当前 facade 侧确实没有自动 polling fallback。

   • src/opencode_a2a/client/client.py 中，send_message() 只是透传 SDK client.send_message() 产生的事件；
   • send() 只是收敛并返回最后一个事件；
   • _build_client() 仍明确使用 ClientConfig(... polling=False)；
   • 现有测试 tests/client/test_client_facade.py 也显式断言 config.polling is False。

2. 这个问题不能通过“仅把 SDK polling=True 打开”来解决。

   • 已核对当前 a2a-sdk：ClientConfig.polling 的注释明确说明，caller 仍需要自行检查任务是否完成，并自行执行 polling loop；
   • BaseClient.send_message() 当前只是用该配置去设置 MessageSendConfiguration.blocking = not config.polling，并不会在收到 non-terminal task 后自动继续 tasks/get。
   • 因此，如果要补 fallback，最合理的位置仍是本仓 facade 层，而不是依赖 SDK 内建自动收敛。

3. 当前 issue 的实现方向需要比原描述再收窄一点，避免破坏现有 stream-first 边界。

   • send_message() 目前是“协议事件流”接口，最好继续保持薄封装；
   • send() 的语义更接近“拿到最终结果”，而当前实现实际上可能返回 non-terminal 最后事件，这里存在 contract/文档上的张力；
   • 因此更推荐优先把 fallback 设计为 send() 的可选能力，或至少做成显式 opt-in，而不是默认修改 send_message() 的事件语义。

4. 触发条件建议进一步明确，不应把所有 non-terminal state 都无差别纳入自动轮询。

   • 更适合自动轮询的是明显“仍在推进中”的状态，例如 submitted / working / unknown；
   • input_required / auth_required 更像等待调用方介入的边界，不应默认持续轮询；
   • 若后续实现 send_message() 级别 fallback，也需要明确它产出的是“轮询得到的 task snapshot”还是“模拟 streaming event”，否则容易与 resubscribe_task() 的职责重叠。

建议的最小实现方向：

• 先补 façade tests，覆盖：
  • send() 命中 non-terminal task 后进入 fallback 并最终收敛为 terminal task；
  • 超时 / 最大尝试次数 / transport error 路径；
  • input_required / auth_required 不进入自动轮询；
  • 仍保留显式 get_task() / resubscribe_task() 能力不变。
• 配置上采用显式 opt-in，并提供有限参数：初始间隔、退避倍率、最大间隔、总超时或最大尝试次数。
• 文档中明确：默认仍是 stream-first；自动 polling fallback 只是兼容 peer 侧 non-streaming/non-terminal task 模式的可选补充。

相关 issue 复核：

• #311 已关闭，且是 server SSE heartbeat，和本 issue 没有必要绑在同一分支实现。
• #321 已关闭，属于 server durable task contract 收口，也不需要与本 issue 一并开发。
• 当前 open issues 中暂无其它与 client polling fallback 高度耦合、建议强绑定并做的议题；本 issue 可以独立推进。

[liujuanjuan1984]

已按本轮评估方向完成实现，范围保持在 facade 层的最小收敛：

1. A2AClient.send() 新增可选自动 polling fallback。

   • 默认仍保持现有 stream-first 行为；
   • 只有在 send() 收到 (Task, None) 且 task state 属于 submitted / working / unknown 时才触发；
   • send_message() 继续保持薄封装事件流，不改变其 contract。

2. 新增 client 侧配置项：

   • A2A_CLIENT_POLLING_FALLBACK_ENABLED
   • A2A_CLIENT_POLLING_FALLBACK_INITIAL_INTERVAL_SECONDS
   • A2A_CLIENT_POLLING_FALLBACK_MAX_INTERVAL_SECONDS
   • A2A_CLIENT_POLLING_FALLBACK_BACKOFF_MULTIPLIER
   • A2A_CLIENT_POLLING_FALLBACK_TIMEOUT_SECONDS

3. fallback 行为边界：

   • 采用退避 + 总超时上限；
   • task 到达 terminal state 后返回；
   • 若轮询过程中进入 input_required / auth_required 等 caller-intervention state，则停止自动轮询并返回当前 task snapshot；
   • tasks/get 的错误映射继续复用现有 facade error mapping。

4. 已补回归测试：

   • terminal 收敛路径；
   • input_required 不进入自动轮询；
   • timeout 路径；
   • tasks/get 错误路径；
   • 新配置解析与参数校验。

5. 文档已补：

   • docs/guide.md 增加了 fallback 开关与行为说明。

验证结果：

• ./scripts/doctor.sh 已通过
• 本地结果：398 passed

如果后续要继续扩展到 send_message() 级别，需要先单独定义“轮询得到的 task snapshot 是否应继续伪装成 streaming event”的 contract；本轮没有把这层语义混入实现里。