sessions：构建 Session / Memory / Summary 多后端回放一致性框架

[shsaihdsaiudh]

背景

生产环境可能从 InMemory 切换到 SQL 或 Redis。不同后端若在事件顺序、state、memory 或 summary 语义上不一致，会导致上下文回放、长期记忆和摘要更新异常。本 PR 完成 issue #89 要求的可复用回放一致性框架，并修复框架通过真实后端测试发现的两个问题。

做了什么

1. 新增 tests/sessions/replay_harness.py，使用同一组标准操作驱动 Session 与 Memory 后端，生成规范化快照并递归比较字段。
2. 新增 10 条公开 JSONL replay case，覆盖单轮、多轮、工具调用、state 覆盖、memory 写入/读取、summary 创建/更新/截断，以及失败和重复写入恢复。
3. 差异结果包含 session id、event index 或 summary id、字段路径、后端名称和两端值；allowed_diff 必须逐项声明路径及原因。
4. 时间字段统一归一化，memory 搜索结果按规范化 JSON 排序；事件顺序、state、工具参数、summary 版本、归属和覆盖关系保持严格比较。
5. 增加 10 类人为差异注入测试，并单独验证 summary 丢失、旧版覆盖新版、归属错误三类问题均能检出。
6. 提供 session_memory_summary_diff_report.json 和 150–300 字设计说明。

同时修复的问题

• SQL Session 按时间戳恢复事件时，生成时间较新的 summary event 会落到保留事件之后。现在 summary event 使用首个保留事件之前的时间锚点，确保数据库往返后仍位于活动窗口首位。
• Redis HGETALL 返回 bytes，原实现直接拼接字符串 state 前缀会触发 TypeError。现在在服务边界解码键，并用 JSON 编解码 state 值，保留布尔、数字、对象等类型。
• 每条 replay case 使用独立 app 命名空间，避免失败重跑后 app/user state 污染后续用例。

运行模式

• 轻量模式：TRPC_REPLAY_LIGHTWEIGHT=1 pytest -q tests/sessions/test_replay_consistency.py
• 默认模式：比较 InMemory 与临时 SQLite。
• Redis 集成：设置 TRPC_REPLAY_REDIS_URL 后加入 Redis；本 PR 使用 Docker redis:7-alpine 实测。

测试结果

• InMemory / SQLite / Docker Redis 三后端 replay 连续运行两次，均为 8/8 通过。
• replay、Redis Session、SQL Session、Session Summarizer 相关测试共 117 项通过。
• 三后端 replay 约 1.7 秒，低于 30 秒要求。

Fixes #89

RELEASE NOTES: NONE

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[shsaihdsaiudh]

I have read the CLA Document and I hereby sign the CLA

[shsaihdsaiudh]

Docker Redis 三后端回放实测日志

以下日志对应 PR 最新提交 3e049fc5fabc259da37dc2d7930755257e0a95aa，包含 Docker/Redis 身份、健康检查、逐项 pytest 输出及退出码。

同时在本地执行了与 CI 相同的检查：

.venv/bin/yapf --diff trpc_agent_sdk/sessions/_redis_session_service.py trpc_agent_sdk/sessions/_session_summarizer.py
.venv/bin/flake8 trpc_agent_sdk/sessions/_redis_session_service.py trpc_agent_sdk/sessions/_session_summarizer.py
# 两条命令均无输出，退出码 0

展开完整 Docker Redis 测试日志

测试时间: 2026-07-12 13:05:11 CST
Git commit: 3e049fc5fabc259da37dc2d7930755257e0a95aa
Docker: client=29.2.0 server=29.2.0
Redis image: redis@sha256:6ab0b6e7381779332f97b8ca76193e45b0756f38d4c0dcda72dbb3c32061ab99
77c1a0cb0169c2e805f1479582fbed5ae8983c569734d2125e3c359f3781c5a9
Container: name=/trpc-agent-replay-89 status=running health=healthy image=sha256:6ab0b6e7381779332f97b8ca76193e45b0756f38d4c0dcda72dbb3c32061ab99
Redis PING: PONG
Command: TRPC_REPLAY_REDIS_URL=redis://127.0.0.1:16379/0 .venv/bin/pytest -vv tests/sessions/test_replay_consistency.py
============================= test session starts ==============================
platform darwin -- Python 3.12.13, pytest-9.1.1, pluggy-1.6.0 -- /Users/yangyeyuan/Desktop/trpc-agent-python/.venv/bin/python
cachedir: .pytest_cache
rootdir: /Users/yangyeyuan/Desktop/trpc-agent-python
configfile: pyproject.toml
plugins: langsmith-0.10.2, anyio-4.14.1, asyncio-1.4.0
asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
collecting ... collected 8 items

tests/sessions/test_replay_consistency.py::test_public_fixture_contains_ten_required_cases PASSED [ 12%]
tests/sessions/test_replay_consistency.py::test_normal_replays_have_no_unexpected_differences PASSED [ 25%]
tests/sessions/test_replay_consistency.py::test_diff_report_is_machine_readable_and_locatable PASSED [ 37%]
tests/sessions/test_replay_consistency.py::test_allowed_diff_only_exempts_declared_metadata PASSED [ 50%]
tests/sessions/test_replay_consistency.py::test_all_ten_injected_inconsistencies_are_detected PASSED [ 62%]
tests/sessions/test_replay_consistency.py::test_summary_integrity_faults_are_detected[summary_create-missing] PASSED [ 75%]
tests/sessions/test_replay_consistency.py::test_summary_integrity_faults_are_detected[summary_update-overwrite] PASSED [ 87%]
tests/sessions/test_replay_consistency.py::test_summary_integrity_faults_are_detected[summary_truncation-ownership] PASSED [100%]

============================== 8 passed in 1.14s ===============================
pytest exit code: 0
1:C 12 Jul 2026 05:05:11.480 * oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
1:C 12 Jul 2026 05:05:11.480 * Redis version=7.4.9, bits=64, commit=00000000, modified=0, pid=1, just started
1:C 12 Jul 2026 05:05:11.480 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
1:M 12 Jul 2026 05:05:11.480 * monotonic clock: POSIX clock_gettime
1:M 12 Jul 2026 05:05:11.480 * Running mode=standalone, port=6379.
1:M 12 Jul 2026 05:05:11.481 * Server initialized
1:M 12 Jul 2026 05:05:11.481 * Ready to accept connections tcp

[codecov]

Codecov Report

❌ Patch coverage is 91.66667% with 2 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@e113610). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
trpc_agent_sdk/sessions/_redis_session_service.py	90.47619%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main        #163   +/-   ##
==========================================
  Coverage        ?   87.55921%           
==========================================
  Files           ?         467           
  Lines           ?       44121           
  Branches        ?           0           
==========================================
  Hits            ?       38632           
  Misses          ?        5489           
  Partials        ?           0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.