[Priority: High] [Architecture] 评估并推进从 InMemory Store 到 Database Store 的迁移

[liujuanjuan1984]

背景

参考外部 issue：liujuanjuan1984/codex-a2a#134

当前仓库的需求同样成立，而且范围应比“只替换一个 InMemoryTaskStore”更明确：

• 目前 src/opencode_a2a/server/application.py 在 create_app() 中直接实例化 InMemoryTaskStore
• 这意味着 tasks/get、tasks/cancel、tasks/resubscribe 仍然只依赖单进程内存态
• 服务重启、滚动发布、横向扩容后，任务查询与重订阅无法稳定延续
• 除了 task store，仓库内还存在几类明确的业务状态目前仍放在内存字典/TTL cache 中，后续应评估是否统一进入数据库持久化

当前实现现状

Server 侧当前在内存中的业务状态

1. Task records

• 来源：InMemoryTaskStore
• 位置：src/opencode_a2a/server/application.py
• 影响接口：tasks/get、tasks/cancel、tasks/resubscribe、流式执行后的 task replay
• 这是最明确、最优先需要落库的数据

2. Session binding / ownership state

• 位置：src/opencode_a2a/execution/session_manager.py
• 当前内存态包含：
  • (identity, context_id) -> session_id 绑定关系
  • session_id -> identity owner 关系
  • pending preferred session claims
• 这些状态决定 session extension / session control 的行为，至少前两类属于业务态，不应永久依赖单进程内存

Client / upstream 协调侧当前在内存中的业务状态

3. Interrupt request bindings

• 位置：src/opencode_a2a/opencode_upstream_client.py
• 当前内存态包含：
  • request_id -> {session_id, interrupt_type, identity, task_id, context_id, expires_at}
  • interrupt tombstones
• 这部分直接影响 interrupt callback / reply 流程，若服务重启会丢失 request 关联关系

不建议作为首批落库对象的状态

以下更像运行时缓存或并发控制对象，不建议作为本 issue 的首批数据库目标：

• A2AClientManager 的 outbound client cache
• SessionManager 的 in-flight create tasks / asyncio locks
• streaming 过程中的临时聚合状态、事件队列、TTL 临时缓存

这些状态需要的是进程内协调，不是数据库持久化。

问题复现 / 现状缺陷

1. 启动服务并发起一个会生成 task 的请求
2. 通过 tasks/get 或 tasks/resubscribe 可以正常查询/重订阅
3. 重启服务进程后再次查询同一 task / interrupt / session 绑定相关状态
4. 当前结果：内存态丢失，行为退化为“查不到”或“无法继续原流程”

预期行为

• Task 状态在服务重启后仍可查询和重订阅
• Session binding / owner 关系至少具备明确的持久化抽象，不再硬编码为进程内 TTL cache
• Interrupt request binding 具备可持久化的 registry 抽象，避免 callback/reply 因重启而断链
• app 装配层不应直接硬编码某个 in-memory implementation

实施建议

第一阶段：最小可交付

1. 为 task store 引入 backend 配置，而不是在 create_app() 内硬编码 InMemoryTaskStore
2. 优先支持最小可运行 profile：SQLite
3. 保持 request handler 只依赖 task store 抽象，不感知具体实现
4. 保持现有 tasks/get、tasks/cancel、tasks/resubscribe 对外 contract 不变

第二阶段：业务态落库抽象继续收口

1. 为 session binding / owner state 抽象 repository
2. 为 interrupt request registry 抽象 repository
3. 明确哪些字段需要 TTL / expires_at，哪些是业务主记录
4. 允许开发环境继续使用 in-memory backend，但不要让业务逻辑直接绑定它

验收标准

• Settings 中存在显式 store backend 配置，app 装配层不再硬编码 InMemoryTaskStore
• 至少提供一个 database-backed task store profile（优先 SQLite）
• tasks/get、tasks/cancel、tasks/resubscribe 在内存与数据库后端下行为一致
• 补最小重启场景验证：重建 app 后仍可查询既有 task
• session binding / owner state 的持久化方案被明确设计（本 issue 可先实现抽象或首批落地）
• interrupt request binding / tombstone 的持久化方案被明确设计（本 issue 可先实现抽象或首批落地）
• 文档补充 backend 配置与本地 SQLite 示例

相关 issue

• Relates to [chore] 参考外部 issue #132 汇总本仓协议层与服务层值得继续演进的点 #264

Git snapshot

• git rev-parse HEAD: e2eaf3922ea3d50d17fc8eb3d7a4985105a2a7cc

[liujuanjuan1984]

已完成 #304 第一阶段最小落地，当前提交：10573d5

本次实现范围：

1. task store backend 配置化

• 在 Settings 中新增：
  • A2A_TASK_STORE_BACKEND
  • A2A_TASK_STORE_DATABASE_URL
  • A2A_TASK_STORE_TABLE_NAME
  • A2A_TASK_STORE_CREATE_TABLE
• 当 backend=database 时，强制要求 A2A_TASK_STORE_DATABASE_URL

2. app 装配层不再硬编码 InMemoryTaskStore

• 新增 src/opencode_a2a/server/task_store.py
• create_app() 现在通过 builder 按配置选择 InMemoryTaskStore 或 DatabaseTaskStore
• lifespan 启动阶段会初始化 task store；关闭阶段会释放 database engine

3. 最小 SQLite profile 已可运行

• 直接复用 a2a-sdk 的 DatabaseTaskStore
• 项目已补充 sqlalchemy + aiosqlite 依赖
• 文档已补充 SQLite 启动示例与限制说明

4. 回归测试

• 新增最小 persistence 验证：重建 store 后仍可读取既有 task
• 新增 create_app 对 task-store 配置的装配测试

当前明确边界：

• 本次只把 task records 落到了 database-backed backend
• session binding / ownership state 以及 interrupt request binding 仍然是内存态，后续应继续按 issue 设计推进
• 另外，a2a-sdk 的 custom table_name 路径本身存在动态 model 构造副作用；本仓已在 builder 层做最小兼容处理，避免同进程重复构造时直接失败

验证：

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

[liujuanjuan1984]

已继续完成 #304 第二阶段，当前新增提交：e51bc97

本次新增内容：

1. session binding / ownership state 持久化抽象

• 新增 src/opencode_a2a/server/state_store.py
• SessionManager 现在通过 SessionStateRepository 读写：
  • (identity, context_id) -> session_id
  • session_id -> identity
  • pending preferred session claims
• memory backend 继续保留现有行为
• database backend 下，这三类状态会落到数据库表中

2. interrupt request registry 持久化抽象

• 新增 InterruptRequestRepository
• OpencodeUpstreamClient 不再直接操作内存字典，而是走 repository
• database backend 下会持久化：
  • active interrupt request bindings
  • interrupt tombstones
• jsonrpc callback 路径和 streaming interrupt 路径已同步接到新的 async repository 调用

3. app 装配层统一接线

• create_app() 现在会基于 backend 构造：
  • task store
  • session state repository
  • interrupt request repository
• database backend 下三者共享同一个 database URL
• 为了不打断现有 monkeypatch/stub 测试，create_app 内增加了对旧签名构造器的兼容回退

4. 文档与回归测试

• docs/guide.md 已更新：database backend 不再只持久化 task records
• 新增 tests/server/test_state_store.py
• 覆盖 database-backed session / interrupt state 的最小持久化验证

当前边界：

• 已持久化：task records、session binding / ownership / pending claims、interrupt request bindings / tombstones
• 仍然不落库：
  • session in-flight create tasks
  • asyncio locks
  • outbound A2A client cache
  • stream-local aggregation state

验证：

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

[liujuanjuan1984]

已补完 #304 的 app 级跨重启集成验证，当前新增提交：3328523

补充内容：

• 新增 tests/server/test_database_app_persistence.py
• 覆盖同一 SQLite backend 下，app 重建前后：
  • task records 可继续读取
  • session binding 可继续复用，不会重复创建 upstream session
  • interrupt request binding 可继续通过 JSON-RPC callback 正常消费
• create_app() 现在把 task_store / agent_executor / upstream_client 显式挂到 app.state，避免测试和诊断继续依赖框架内部属性名

验证：

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

当前判断：#304 已具备关闭条件。

[liujuanjuan1984]

补充收口：

• 已修正 A2A_TASK_STORE_CREATE_TABLE 的边界，当前会统一控制 database backend 下 task store table 与 runtime state tables 的自动创建。
• 已删除只服务测试的生产 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)