[Priority: Med] [Feature] 设计 A2A 显式子 agent 编排与并行 subtask 契约

[liujuanjuan1984]

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

当前 opencode-a2a 没有给 A2A 客户端一个显式的“发起子 agent 编排 / 并行 subtask”契约。即使上游 opencode 本体已经支持 subtask part 和 task tool，这些能力目前仍然主要停留在 OpenCode 自身 prompt/runtime 里，A2A 消费方无法稳定、机器可发现地声明“请用某个 subagent 执行一个子任务”或“一次提交多个并行 subtasks”。这会限制更高阶的 agent orchestration 场景。

🛠️ 详细实施方案 (必须包含涉及的文件路径和核心逻辑/伪代码)

1. 设计显式 invocation contract，而不是依赖隐式 prompt engineering。
   涉及文件：

• src/opencode_a2a/contracts/extensions.py
• src/opencode_a2a/server/agent_card.py
• docs/guide.md

建议评估两种方案并选一条作为正式契约：

• 方案 A：新增 provider-private JSON-RPC 方法，例如 opencode.subtasks.run
• 方案 B：在主聊天请求中引入显式 metadata.shared.orchestration 或 provider-private part 映射

2. 为单个 subtask 定义稳定输入模型。
   涉及文件：

• src/opencode_a2a/jsonrpc/params.py
• src/opencode_a2a/jsonrpc/dispatch.py
• src/opencode_a2a/jsonrpc/handlers/subtask_invocation.py (new)
• src/opencode_a2a/opencode_upstream_client.py

建议输入字段：

• agent
• prompt
• description
• command (optional)
• model (optional)
• parallel_group (optional)
• metadata.opencode.directory / future workspace binding

伪代码：

validate params
resolve owner + directory/workspace boundary
convert request -> upstream subtask part or task tool input
submit to upstream session
return task/message handle + execution metadata

3. 显式支持“并行 subtask”批量提交，但要定义上限和结果模型。
   涉及文件：

• src/opencode_a2a/contracts/extensions.py
• src/opencode_a2a/jsonrpc/handlers/subtask_invocation.py (new)
• docs/guide.md

建议：

• 支持 items[] 批量提交
• 在 contract 中声明 max_parallel_subtasks
• 返回结果中显式区分 accepted / rejected / failed 子项

伪代码：

for subtask in items:
  validate each item
  submit in one upstream session or coordinated session set
collect accepted handles
return {
  items: [{client_id, status, handle, error?}],
  parallel: true
}

4. 明确与 a2a_call、普通 message/send、opencode.sessions.command 的边界。
   涉及文件：

• docs/guide.md
• src/opencode_a2a/contracts/extensions.py

需要明确：

• a2a_call 是跨 agent / 跨服务调用，不等同于本地 subagent orchestration
• 普通主聊天可以“自然触发” subtask，但不是稳定客户端 API
• 新契约面向“客户端显式请求编排”，应有单独的错误码、能力声明和安全限制

🧪 回归测试建议

• 为单 subtask / 批量并行 subtask 增加参数校验、目录边界、owner guard、上游失败映射测试。
• 为 Agent Card / extension params 增加契约测试，验证 invocation model、批量语义和限制声明。
• 增加端到端测试，验证客户端可显式触发一个 subagent 任务，并观察到稳定结果或流式状态。
• 运行 ./scripts/doctor.sh。

[liujuanjuan1984]

评估结论：该需求方向合理，但当前问题定义需要重写并拆阶段；以现在这个 issue body 直接开做，范围会过大，而且会和现有能力重复。

关键判断：当前仓库并不是“完全没有显式子任务入口”。

• 现有 opencode.sessions.prompt_async 已经支持 request.parts[].type = "subtask"，并且参数校验已覆盖 prompt / description / agent / model / command。
• 因此，A2A 客户端今天已经可以通过 provider-private JSON-RPC 方法显式提交单个 subtask，只是这个能力还没有在 contract / Agent Card / guide / OpenAPI 中被正式定义成“稳定 orchestration contract”。

这意味着 #339 不应该一上来就设计一个新的 opencode.subtasks.run，否则很可能和现有 prompt_async 路径重叠，增加冗余协议面。

建议把 #339 拆成 3 个步骤，并以后置依赖方式推进：

1. 第一步：先依赖 #338，把现有单 subtask 语义正式化。
   • 明确 prompt_async + subtask part 是否就是第一版显式 orchestration contract。
   • 如果这个问题不先收敛，后续新增专用方法就没有比较基线。
2. 第二步：只补“单 subtask 的稳定调用语义”，不做并行批量。
   • 如果现有 prompt_async 已足够，就只补 contract / 文档 / 示例 / 返回与流式观察说明。
   • 只有当现有形态无法表达所需字段时，才评估新增独立方法或 provider-private metadata 结构。
3. 第三步：再单独设计“批量/并行 subtasks”。
   • 这部分复杂度显著更高，涉及：并发上限、accepted/rejected/failed 结果模型、owner/session 保护、workspace/worktree 绑定、授权边界。
   • 更适合后续单独 issue，而不是和“单 subtask 显式契约”绑在一起。

与其它 open issues 的关系：

• #338 是本 issue 的直接前置，不建议同分支混做，但建议先完成它的第一阶段。
• #332 很重要，因为显式 orchestration 一旦走向并行 subtasks，workspace/worktree 绑定几乎一定会成为必要前提；不过不建议和本 issue 同分支并做。
• #166 也很关键，原因是更强的 orchestration API 会放大高风险方法的授权问题；但它属于约束前提，不建议并入本分支实现。
• #336 有辅助价值，但不是前置。

结论：

• 需要拆分，而且建议把“单 subtask 显式契约”和“并行/批量 subtask 契约”拆开。
• 不建议现在就把 #339 当成一个完整实现 issue 直接开发。
• 更合理的顺序是：#338 第一阶段 -> 收敛单 subtask 正式 contract -> 再决定 #339 第二阶段是否真的需要新增专用方法。

[liujuanjuan1984]

补充说明：我会在 #338 第一阶段完成后，继续收敛本 issue 的“第一版显式 orchestration contract”。当前预期是：

• 优先复用现有 opencode.sessions.prompt_async + request.parts[].type=subtask 作为单 subtask 的正式调用契约；
• 通过独立 extension params / Agent Card / guide 把调用模型显式化；
• 本阶段仍不引入批量/并行 subtask 新方法。

也就是说，本 issue 当前会先实现“单 subtask 显式契约收敛”，并把并行/批量部分继续后置。

[liujuanjuan1984]

第一阶段实现已完成，当前落地范围如下：

• 新增 provider-private subtask invocation extension；
• 正式声明“单 subtask 显式调用契约”当前通过 opencode.sessions.prompt_async + request.parts[].type=subtask 暴露；
• 在 Agent Card / OpenAPI / guide 中明确：当前声明稳定的 shape 是“request.parts 中恰好一个 subtask part”；
• 明确 mixed payload、多 subtask、批量/并行提交仍然不在当前声明契约内。

回归结果：

• ./scripts/doctor.sh ✅
• 419 tests passed
• coverage 91.99%

本 issue 仍保持 open，原因是：

• 批量/并行 subtasks 的输入/结果模型还没有定义；
• workspace/worktree 绑定和授权边界也还没有在本 issue 内落地。

因此，这次实现完成的是“第一版显式 orchestration contract 收敛”，不是整个 #339 的最终完成态。

[liujuanjuan1984]

补充评估：如果希望把本 issue 也视为“完整实施完成”，当前还缺的主要是以下几项，而不仅仅是文档/契约层声明。

1. 把“单 subtask 显式契约”从声明变成运行时强约束。

• 当前已经声明稳定 shape 是：opencode.sessions.prompt_async + request.parts 中恰好一个 subtask part。
• 但运行时尚未强制拒绝以下未声明形态：
  • 多个 subtask parts
  • mixed text/file/agent/subtask payload
  • 其它超出当前声明范围的组合
• 如果不补这层校验，契约与实现仍然存在松耦合差异。

2. 批量 / 并行 subtasks 仍未设计与实现。

• 这是本 issue 最大的未完成面。
• 需要明确定义：
  • 请求模型
  • 最大并行数
  • accepted / rejected / failed 的结果模型
  • 是否复用同一 session
  • 是否复用同一 workspace
  • 部分失败如何表达

3. workspace / worktree 绑定问题未解决。

• 一旦进入并行 subtasks，这几乎会成为必要前提；
• 否则 orchestration 仍然局限在当前 shared workspace 模型中。
• 这块与 #332 强相关。

4. 授权边界仍需收敛。

• 更强的 orchestration API 会放大高风险方法的授权问题。
• 至少还需要明确：
  • 谁可以发起子任务
  • 是否允许 shell-capable subagent
  • identity/session/subtask ownership 如何约束
• 这块与 #166 强相关。

5. 端到端验收测试仍缺失。

• 当前主要完成的是 contract / docs / unit 级回归；
• 如果本 issue 要算真正完成，仍应补至少以下 E2E 覆盖：
  • 显式发起单 subtask
  • 观察稳定流式结果
  • 并行 subtasks 的成功 / 部分失败 / 拒绝路径

当前判断：

• 本次实现完成的是“第一阶段显式 orchestration contract 收敛”；
• 距离本 issue 的完整完成态仍有明显差距；
• 暂不建议继续扩大本分支范围，后续可在明确产品方向后再决定是否继续推进这些缺口。