feat(server): add database-backed persistence for task and runtime state

[liujuanjuan1984]

概要

实现 #304：为当前仓库引入可配置的 database-backed store，并将目前需要跨重启保留的核心业务状态接入同一持久化后端。

改动模块

1. 配置与依赖

• pyproject.toml
• uv.lock
• src/opencode_a2a/config.py

新增：

• A2A_TASK_STORE_BACKEND
• A2A_TASK_STORE_DATABASE_URL
• A2A_TASK_STORE_TABLE_NAME
• A2A_TASK_STORE_CREATE_TABLE

补充 sqlalchemy / aiosqlite 依赖，并在 database backend 下要求显式提供 database URL。

说明：

• A2A_TASK_STORE_CREATE_TABLE 现在统一控制 database backend 下 task store table 与 runtime state tables 的自动创建。

2. Task Store 装配

• src/opencode_a2a/server/task_store.py
• src/opencode_a2a/server/application.py

实现 task store builder，按配置选择：

• InMemoryTaskStore
• DatabaseTaskStore

在 app lifespan 中负责初始化和释放 database-backed store / engine。

3. Session / Interrupt 状态持久化

• src/opencode_a2a/runtime_state.py
• src/opencode_a2a/server/state_store.py
• src/opencode_a2a/execution/session_manager.py
• src/opencode_a2a/opencode_upstream_client.py
• src/opencode_a2a/execution/stream_runtime.py
• src/opencode_a2a/jsonrpc/application.py
• src/opencode_a2a/execution/executor.py

新增 repository 抽象与 memory/database 双后端，接入：

• task records
• session binding
• session ownership
• pending preferred session claims
• interrupt request bindings
• interrupt tombstones

4. 文档与测试

• docs/guide.md
• tests/server/test_task_store_factory.py
• tests/server/test_state_store.py
• tests/server/test_database_app_persistence.py
• 以及相关 transport / interrupt / upstream 测试更新

新增覆盖：

• database-backed task store 的最小 persistence 验证
• database-backed session / interrupt state persistence 验证
• A2A_TASK_STORE_CREATE_TABLE=false 时不自动创建 state tables
• app 重建后的端到端回归：task / session / interrupt 三类状态持续可用

当前边界

仍保持进程内状态，不进入数据库：

• session in-flight create tasks
• asyncio locks
• outbound A2A client cache
• stream-local aggregation state

验证

• uv sync --all-extras
• uv run pre-commit run --all-files
• uv run pytest
• 结果：357 passed

相关 commits

• 10573d5 feat(server): add database-backed task store backend (#304)
• e51bc97 feat(server): persist session and interrupt state in database backend (#304)
• 3328523 test(server): cover app restart persistence for database backend (#304)
• 8a5889d fix(server): align database state tables with create-table config (#304)

Closes #304
Relates to #264

[liujuanjuan1984]

本轮审查结论：实现方向合理，#304 的核心目标已经落地，且 task / session / interrupt 三类状态都补上了回归覆盖。

发现 1 个需要明确的风险和 1 个非阻塞清理点：

1. 中：A2A_TASK_STORE_CREATE_TABLE 当前只作用于 task table，不作用于 runtime state tables。

   • 位置：src/opencode_a2a/server/task_store.py:65-70、src/opencode_a2a/server/state_store.py:187-192、src/opencode_a2a/server/state_store.py:523-528
   • 说明：PR 新增了 database-backed session / interrupt state，但这两类 repository 在初始化时始终执行 create_all。如果部署方把 A2A_TASK_STORE_CREATE_TABLE=false 理解成“所有数据库表都不自动建表”，当前行为会超出预期。
   • 判断：这不影响当前功能正确性，但会影响数据库接入边界，尤其是依赖外部 migration / 受限权限数据库的部署。

2. 低：close_task_store() 目前只在测试里使用，主路径不再消费。

   • 位置：src/opencode_a2a/server/task_store.py:92-95
   • 说明：app lifespan 现在直接持有并释放共享 engine，这个 helper 已经不是主实现路径的一部分。
   • 判断：不阻塞合并，但后续可以继续收口，避免保留“看起来像生产路径、实际上只服务测试”的额外 helper。

除此之外，这个 PR 的 Closes #304 / Relates to #264 是准确的。

[liujuanjuan1984]

已基于当前分支修掉上一轮审查里的两个点：

1. A2A_TASK_STORE_CREATE_TABLE 现在同时约束 runtime state tables 的自动创建。

   • DatabaseSessionStateRepository / DatabaseInterruptRequestRepository 新增 create_tables 开关。
   • build_session_state_repository() / build_interrupt_request_repository() 现在会传入 settings.a2a_task_store_create_table。
   • 新增测试覆盖 A2A_TASK_STORE_CREATE_TABLE=false 时不自动创建 state tables。

2. 删除了只服务测试的生产 helper close_task_store()。

   • 测试改为直接释放 task store 持有的 engine。

补充验证：

• uv run pre-commit run --all-files
• uv run pytest
• 结果：357 passed

新增 commit：

• 8a5889d fix(server): align database state tables with create-table config (#304)