[Priority: Med] [Enhancement] 对齐 session query 的过滤参数与 cursor 分页

[liujuanjuan1984]

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

当前 session query 契约只正式声明了 limit 分页，且 opencode.sessions.messages.list 没有暴露上游已有的 before cursor；opencode.sessions.list 也没有对齐 directory、roots、start、search 等过滤字段。结果是适配层虽然覆盖了“能列出来”，但与上游 OpenCode 的查询还原度仍有明显差距，客户端也无法稳定做增量加载与精确过滤。

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

1. 扩展 query 参数解析器与契约声明。
   涉及文件：

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

建议补齐字段：

• opencode.sessions.list: directory, roots, start, search, limit
• opencode.sessions.messages.list: limit, before

2. 为消息分页显式暴露 next_cursor，不要只把它吞在上游 HTTP Header 里。
   涉及文件：

• src/opencode_a2a/jsonrpc/handlers/session_queries.py
• src/opencode_a2a/opencode_upstream_client.py

伪代码：

raw_items, next_cursor = upstream.list_messages(session_id, limit, before)
return {
  items: mapped_messages,
  next_cursor: next_cursor,
}

3. 保持与现有 limit-only 客户端兼容。
   涉及文件：

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

建议把分页模型从“只有 limit”升级为“limit + optional cursor”，同时在 Agent Card 中说明 before 只适用于 message history，不适用于通用分页。

🧪 回归测试建议

• 为 params.py 增加字段组合校验测试，覆盖非法 before、非法 limit、旧客户端兼容。
• 为 opencode.sessions.messages.list 增加带 cursor 的 handler 测试，验证 next_cursor 透出。
• 为文档与 contract 一致性测试补齐新的参数/结果字段断言。
• 运行 ./scripts/doctor.sh。

[liujuanjuan1984]

当前已在分支 issue-334-session-query-pagination 上完成评估，结论如下：

1. 需求仍然合理且仍然有效。

• 当前主干仍是 limit-only 契约：src/opencode_a2a/jsonrpc/params.py 还在拒绝 cursor/page/size，src/opencode_a2a/jsonrpc/handlers/session_queries.py 也还只返回 result.items。
• 上游 opencode 最新 dev 仍支持该 issue 提到的能力：GET /session 支持 directory / roots / start / search / limit，GET /session/:sessionID/message 支持 limit + before，并通过 X-Next-Cursor / Link 暴露下一页 cursor。

2. 实施方案需要按当前代码最佳实践调整。

• directory 不能作为原样透传的 query 参数处理，必须走现有 directory resolver / workspace boundary 约束；否则会绕开当前 metadata.opencode.directory 同类路径已经遵循的边界检查。
• 除了 params.py / extensions.py / docs/guide.md / session_queries.py / opencode_upstream_client.py，还应同步更新 src/opencode_a2a/server/openapi.py、src/opencode_a2a/server/agent_card.py 以及对应 contract consistency / agent card / openapi 测试。
• next_cursor 不建议继续用裸 tuple 透传，最好在 upstream client 层引入显式 page result（例如带 items 和 next_cursor 的 typed envelope），这样 handler / contract / tests 会更稳。
• 不建议顺手对齐上游 limit=0 的“返回全部消息”语义；当前适配层已经明确采用有界 limit 策略，继续保持 1..100 更符合现有服务边界。

3. 相关 open issues 评估。

• #333 与 session 能力面高度相关，但范围明显更大，不建议与本 issue 同分支一并开发；更合适的顺序是先完成 #334 的 query parity，再在 #333 中复用 cursor/filter 的契约基础。
• #326 与 SessionManager idle lock 清理相关，不建议合并到本次分支。

如果后续直接实现，我建议本 issue 的落地范围收敛为：

• opencode.sessions.list：补 directory / roots / start / search
• opencode.sessions.messages.list：补 before
• 返回 result.next_cursor
• 保持现有默认/最大 limit 与旧客户端兼容

[liujuanjuan1984]

已在分支 issue-334-session-query-pagination 完成实现，当前结果如下：

• opencode.sessions.list 已补齐 directory / roots / start / search / limit 过滤字段，并且 directory 会经过现有 workspace boundary 解析，不做原样透传。
• opencode.sessions.messages.list 已补齐 before cursor，并返回 result.next_cursor。
• session query extension contract、Agent Card、OpenAPI、guide 文档与测试已同步更新。
• upstream client 已显式读取 X-Next-Cursor，消息分页不再把 cursor 丢在上游 header 里。

回归结果：

• ./scripts/doctor.sh
• 418 tests passed
• coverage 91.97%

[liujuanjuan1984]

当前实现已提交到 PR #341：

• feat: add session query filters and cursor pagination #341

本 PR 已实现 #334 的目标范围：session filters、message cursor pagination、next_cursor 暴露，以及对应 contract / docs / tests 对齐。