fix: align sdk task-store and stream artifact flows

[liujuanjuan1984]

概览

本 PR 收敛两类边界：

• a2a-sdk task store / SDK-owned schema 的使用边界
• 流式 artifact 的传输边界与最终持久化边界

模块说明

服务与持久化

• src/opencode_a2a/server/rest_tasks.py
  • /v1/tasks 改为优先下推到 task_store.list()，不再先全量拉取再在进程内分页。
• src/opencode_a2a/server/application.py
  • 统一列表/消息路径的 call context 处理，让 owner scope 真正落到 SDK resolver。
• src/opencode_a2a/server/context_helpers.py
  • 收敛 ServerCallContext 规范化逻辑，补齐伪 context 的 user 兼容。
• src/opencode_a2a/server/task_store.py
  • SDK-owned tasks 表改为 fail-fast schema 校验后再委托 SDK initialize。
  • 读写前统一规范化 call context。
• src/opencode_a2a/server/migrations.py
  • 本地 migration 只继续管理 adapter-owned state tables，不再接管 SDK-owned tasks 表。

流式输出

• src/opencode_a2a/execution/stream_state.py
  • 流式状态从“整条流共用一个 artifact”收敛为“按逻辑 artifact 跟踪”。
• src/opencode_a2a/execution/stream_runtime.py
  • text / reasoning / tool_call 改为稳定逻辑 artifact 车道。
• src/opencode_a2a/execution/coordinator.py
  • streaming 完成时对 text artifact 补发完整 replace snapshot（append=false、lastChunk=true）。
• src/opencode_a2a/output_modes.py
  • 区分 transport event 与 persistence event；客户端继续收增量，task store 持久化 compact canonical snapshot。
• src/opencode_a2a/cli.py
  • 适配 final replace snapshot，避免 CLI 重复打印完整文本。

文档与测试

• docs/guide.md
  • 更新 SDK-owned schema 升级边界与 streaming contract 说明。
• tests/execution/*、tests/server/*
  • 补齐 task store schema fail-fast、伪 context 兼容、stream artifact canonical persistence 等回归测试。

验证

• bash ./scripts/doctor.sh
• uv run python ./scripts/find_thin_wrappers.py --thin-only src/opencode_a2a

关联 Issue

Closes #441
Closes #442
Closes #447
Closes #448
Refs #445
Refs #446

[liujuanjuan1984]

补充说明：本轮已移除 SDK-owned tasks 表的运行时兼容迁移，改为启动期显式 schema 校验并在 legacy schema 上 fail-fast，提示先执行 upstream a2a-db。这一步是为了把 SDK-owned schema 的升级责任收回到 upstream 推荐路径，同时保留本仓库对 adapter-owned state tables 的独立迁移管理。

[liujuanjuan1984]

补充说明：本轮已收掉 task store 对伪 ServerCallContext 的兼容缺口。新增共享 context 规范化层，并把测试辅助从脆弱的 mock call context 切回真实 ServerCallContext，避免 owner resolver 因缺失 user 而在 save/get/delete/list 路径上包装成 TaskStoreOperationError。验证已通过 bash ./scripts/doctor.sh。

[liujuanjuan1984]

本轮基于当前分支对 PR #443 做了独立审查，结论如下。

审查结论

未发现阻塞性问题。当前变更能够较稳健地覆盖 #441、#442、#447 想要解决的主问题，方向与当前 a2a-sdk 最佳实践一致。

主要判断

1. /v1/tasks 列表路径收敛方向合理

• rest_tasks.py 现在通过 context_builder(request) 构造请求级 ServerCallContext，并在 rest_tasks.py 开始使用 task_store.list() 分页下推过滤条件。
• 这比此前“先全量拉取再在进程内分页”的方案更贴近 SDK 原生能力，也更能利用底层 store 的 owner scope 与分页语义。

2. SDK-owned task schema 改为 fail-fast，符合当前更优的升级边界

• task_store.py 在初始化前先做 schema compatibility 校验，并在 task_store.py 起对 legacy tasks 表给出显式报错与 a2a-db 提示。
• 这比运行时偷偷补列/补索引更符合 SDK-owned schema 由 upstream migration tool 管理的边界约束。

3. ServerCallContext 兼容缺口修复是到位的

• context_helpers.py 把伪 ServerCallContext 的兼容逻辑集中到一处，避免 task_store 和测试辅助各自散落补丁。
• task_store.py 统一接入该规范化逻辑后，owner resolver 不再因 mock context 缺失 user 而退化成 TaskStoreOperationError。
• helpers.py 与 test_task_store_factory.py / test_task_store_factory.py 也把测试辅助和回归测试一起收敛到了真实语义。

issue 关联审查

• Closes #441：准确。PR 最终确实覆盖了原始 TaskStoreOperationError 诊断后的修复落地，不再只是分析。
• Closes #442：准确。PR 已把 db/list/init/context 这几处最关键的 SDK 对齐点收回到当前最佳实践。
• Closes #447：准确。伪 ServerCallContext 的兼容缺口及测试辅助脆弱用法都已在本分支修复。
• Refs #445：准确。当前 PR 虽然已经去掉 SDK-owned tasks 表的 runtime auto-migrate，但 #445 还包含更宽的 upstream 扩展边界与长期 migration 策略讨论，保留 Refs 更稳妥。
• Refs #446：准确。终态原子保护对 DatabaseTaskStore 私有实现的依赖仍未在本 PR 中消除。

残余风险

• 非阻塞残余仍在 task_store.py 到 task_store.py：终态原子保护仍依赖 DatabaseTaskStore._ensure_initialized()、task_model、async_session_maker、_from_orm() 等 SDK 私有/内部实现细节。这次 PR 没有扩大该耦合，但也还没有消除它；继续由 #446 跟踪是合适的。

标题与描述审查

• PR 标题已调整为 fix: align task store boundaries with a2a-sdk，比原先带 db 的表述更贴近本 PR 实际覆盖范围。
• PR 描述按模块分组后与最终代码状态一致，issue 关联关系当前也准确。

[liujuanjuan1984]

本轮独立审查结论：未发现新的阻塞性问题，当前实现比之前的临时方案更贴近 a2a-sdk 的 artifact 语义与长期维护边界。

重点判断：

• 合理性：流式 transport 与 task-store persistence 现在已经分离。客户端仍接收增量，持久层改为 compact canonical snapshot，这正是本仓库此前缺失的边界。
• 稳健性：final text snapshot 改为同一逻辑 text artifact 上的 append=false replace 事件，避免最终 Task 快照残留 token 级碎片；CLI 也已补上 replace 去重，不会在本仓库自带客户端上重复打印完整内容。
• 优雅性：stream artifact 不再把 text / reasoning / tool_call 混在一个 artifactId 下，而是收敛为逻辑输出车道；这让 SDK 现有的 append/replace 语义终于和我们的 artifact 设计对齐。
• 回归面：doctor.sh 已通过，612 passed，coverage 91.25%。

当前剩余的非阻塞风险没有变化，仍是 #446：terminal-state 原子保护对 a2a-sdk 私有实现存在少量耦合。这次改动没有扩大该耦合。

[liujuanjuan1984]

补充本轮收尾审查结论：

1. 维护脚本审查

• 当前仓库只有明确的“套壳”脚本 scripts/find_thin_wrappers.py；没有单独命名的“死代码”脚本入口，也未安装 vulture 一类现成检查器，所以这里没有擅自发明一条仓库外流程。
• uv run python ./scripts/find_thin_wrappers.py --thin-only src/opencode_a2a 已执行。
• 输出里与本 PR 相关的命中，主要是有意保留的 override / facade / route callback / decorator forwarding，例如 NegotiatingResultAggregator.consume_all、TaskStoreDecorator.*、路由闭包与健康检查入口；未发现需要在本 PR 继续删除或重构的新增死包装。

2. PR 代码变动独立审查

• 未发现新的阻塞性问题。
• 本 PR 现在同时收敛了 SDK task-store 边界和 streaming artifact 边界，方向合理。
• 流式实现相较之前更稳：逻辑 artifact 车道、final replace snapshot、transport/persistence 分离三件事是配套的，没有只修表面碎片问题。
• task-store 侧的 /v1/tasks 下推、call context 规范化、SDK-owned schema fail-fast 也都与前述 issues 对齐，没有看到新的偏差或冗余扩散。
• 当前剩余非阻塞风险仍是 #446：terminal-state 原子保护对 a2a-sdk 私有实现有少量耦合，这次没有扩大该风险。

3. PR 与 issues 关系

• Closes #441、Closes #442、Closes #447、Closes #448 目前是准确的。
• Refs #445、Refs #446 也合理：这两个议题仍有后续设计/收敛空间，不应在本 PR 提前关闭。