[Agent Feature] Using Gorm to store the Session, Messages etc. entities in the DB

[robocanic]

What would you like to be added:
目前Agent 模块中的Session，Message等会话数据都放置在内存中，需要使用Gorm来支持持久化。

Why is this needed:
分布式场景下，需要用持久化存储来存储会话数据，支持多租户，多机器，HITL等场景

[beatenevo]

Implementation Plan

1. Define the SessionStore, MessageStore, and combined Store, basing #1502
2. Move the existing in-memory Session, Turn, and Message logic into MemoryStore while preserving the current behavior.
3. Unify Store dependency injection so that Session Manager, Agent, and Memory Tool use the same Store instance.
4. Add Gorm models for Session, Turn, and Message.
5. Implement GormStore to persist and retrieve Session, Turn, and Message data.
6. Add configurable Memory/Gorm backend selection and MySQL/PostgreSQL database connections.
7. Add schema migration, transaction handling, message ordering constraints, and cascading deletion of session-related data.
8. Add shared contract tests for MemoryStore and GormStore, restart recovery tests, and multi-instance data-sharing tests.

Expected Result

The existing in-memory storage mode will remain available, while Gorm-backed persistent storage can be enabled through configuration. Agent sessions, turns, and messages will survive service restarts and can be shared across multiple AI service instances connected to the same database.
But this does not implement tenant identity integration or HITL execution-state persistence because neither contract currently exists in the codebase,it provides the durable conversation storage foundation required for those scenarios.

实施方案

1. 基于 #1502 定义 SessionStore、MessageStore 和组合 Store
2. 将现有 Session、Turn、Message 的内存逻辑迁移为 MemoryStore，保持原有行为。
3. 统一 Store 依赖注入，确保 Session Manager、Agent 和 Memory Tool 使用同一个 Store 实例。
4. 增加 Session、Turn、Message 对应的 Gorm Model。
5. 实现 GormStore，完成 Session、Turn、Message 的持久化读写。
6. 增加 Memory/Gorm 后端配置切换，以及 MySQL、PostgreSQL 数据库连接。
7. 增加表迁移、事务处理、消息顺序约束和 Session 关联数据删除。
8. 增加 MemoryStore/GormStore Contract Test、重启恢复测试和多实例共享测试。

最终结果：

保留现有 MemoryStore 模式，同时支持通过 Gorm 将 Agent Session、Turn 和 Message 持久化到共享数据库，使会话数据能够在服务重启后恢复，并在多个 AI 服务实例之间共享。但是由于缺失Tenant 身份模型与来源和当前没有HITL状态机，对于这两个场景只能提供会话持久化基础。

[beatenevo]

Please assign it to me if possible. @robocanic

[robocanic]

可以的，方向上没问题，可以再细化成一个完整的spec

[beatenevo]

1. Store 抽象

基于 #1502，新增统一 Store 抽象：

type SessionStore interface {
    Create(ctx context.Context, session *Session) error
    Get(ctx context.Context, sessionID string) (*Session, error)
    List(ctx context.Context) ([]*Session, error)
    Touch(ctx context.Context, sessionID string, updatedAt time.Time) error
    Delete(ctx context.Context, sessionID string) error
    DeleteExpired(ctx context.Context, now time.Time) (int, error)
}

type MessageStore interface {
    AddHistory(ctx context.Context, sessionID string, messages ...*ai.Message) error
    IsEmpty(ctx context.Context, sessionID string) (bool, error)
    WindowMemory(ctx context.Context, sessionID string) ([]*ai.Message, error)
    AllMemory(ctx context.Context, sessionID string) ([]*ai.Message, error)
    NextTurn(ctx context.Context, sessionID string) error
}

type Store interface {
    SessionStore
    MessageStore
}

新增统一领域错误：

var (
    ErrSessionNotFound  = errors.New("session not found")
    ErrSessionExpired   = errors.New("session expired")
    ErrNoActiveTurn     = errors.New("no active turn")
    ErrTurnLimitReached = errors.New("conversation turn limit reached")
)

Store 接口只负责存储和读取，不负责模型调用、工具调用和 HTTP 逻辑。

Session Manager 只依赖 SessionStore，Agent 和 Memory Tool 只依赖 MessageStore；三者使用同一个底层 Store 实例。

2. MemoryStore

将当前 Session Manager 和 HistoryMemory 的内存逻辑迁移到 MemoryStore。

• 保留现有 Session 字段、状态和 24 小时过期规则。
• 保留现有 Turn 生命周期。
• 每个Turn的读取顺序固定为 system->user->model。
• 同一 Role 内的消息保持sequence顺序。
• 保留 nil Message 和未知 Role 被忽略的行为。
• 使用 Store 锁保护 Session、Turn 和 Message 状态。
• Session 删除时清理 active history 和 completed history。
• 现有 HistoryMemory 不再由 Agent 或 Memory Tool 单独创建。

关于max_turn语义

MemorySpec.max_turns 是 Session 最大 Turn 数的唯一配置来源：

• 默认值为 100。
• 配置值必须同时传入 MemoryStore 和 GormStore。
• 两个后端必须使用完全一致的限制逻辑。
• 一个 Session 最多完成 max_turns 个 Turn。
• 最后一个合法 Turn 可以正常完成。
• 当下一次交互尝试创建第 max_turns + 1 个 Turn 时，AddHistory 返回 ErrTurnLimitReached。
• Agent 收到该错误后不得继续调用模型，SSE 返回错误事件。
• 新消息不得在达到上限后被静默追加到最后一个 Turn。
  生产 Store 不再使用独立的硬编码 TurnLimit = 10。

MemoryStore 和 GormStore 必须通过同一套 Contract Test 验证。

3. Store 依赖注入

Runtime 中只创建一个 Store 实例：

MemoryComponent
  -> MemoryStore 或 GormStore
      -> Session Manager 使用 SessionStore
      -> Agent 使用 MessageStore
      -> Memory Tool 使用 MessageStore

MemoryComponent 使用完整配置构造：

func NewMemoryComponent(spec MemorySpec) (runtime.Component, error)

• Session Manager 不再持有 Session map。
• Agent 不再创建 HistoryMemory。
• Agent 接收 MessageStore。
• Memory Tool 接收同一个 MessageStore。
• Router 接收 SessionStore。
• Handler 通过 Session Manager 调用 Touch。
• Handler 删除 Session 时直接调用 Store 的会话级删除，由 Store 在事务中显式删除 Message、Turn 和 Session，不依赖数据库外键或数据库级联。
• 移除 Agent.GetMemory()。
• 移除生产代码中创建 mock Session 的副作用。
• Store 错误不得只记录日志后忽略，必须返回到 Agent、Handler 或 SSE。
• Gin 请求的 context.Context 必须传递到 Agent。请求 Context 用于模型推理、工具调用、Store 读取以及 Session Get/Touch。模型结果、观察结果的 AddHistory 和最终 NextTurn 使用由context.WithoutCancel(requestCtx) 派生的 persistCtx，以保证客户端断开后已生成数据仍能完成持久化。

Context 规则

请求 Context 和持久化 Context 区分：

requestCtx:
  - 模型推理
  - 工具调用
  - Store 读取
  - Session Get/Touch

persistCtx = context.WithoutCancel(requestCtx):
  - 模型结果 AddHistory
  - 观察结果 AddHistory
  - 最终 NextTurn

客户端断开时：

• 模型推理和工具调用可以被取消。
• Store 读取可以被取消。
• 已生成的模型消息和观察消息仍应使用 persistCtx 完成持久化。
• 最终 NextTurn 使用 persistCtx 执行。
• 持久化 Context 保留 Context Value，但不继承请求取消和 deadline。

4. Gorm Model

新增三张表：

ai_sessions
ai_turns
ai_messages

Model 和 GormStore 放在 ai/store/gorm，package 名使用 gormstore。

Session Model：

type SessionModel struct {
    ID        string    `gorm:"primaryKey;size:64"`
    CreatedAt time.Time `gorm:"not null"`
    UpdatedAt time.Time `gorm:"not null;index"`
    Status    string    `gorm:"size:16;not null;index"`
}

func (SessionModel) TableName() string {
    return "ai_sessions"
}

Turn Model：

type TurnModel struct {
    ID          uint64       `gorm:"primaryKey;autoIncrement"`
    SessionID   string       `gorm:"size:64;not null;index"`
    CreatedAt   time.Time    `gorm:"not null;index"`
    CompletedAt *time.Time   `gorm:"index"`
}

func (TurnModel) TableName() string {
    return "ai_turns"
}

Message Model：

type MessageModel struct {
    ID        uint64    `gorm:"primaryKey;autoIncrement"`
    TurnID    uint64    `gorm:"not null;uniqueIndex:uidx_ai_message_turn_sequence"`
    Sequence  uint64    `gorm:"not null;uniqueIndex:uidx_ai_message_turn_sequence"`
    Payload   []byte    `gorm:"not null"`
    CreatedAt time.Time `gorm:"not null"`
}

func (MessageModel) TableName() string {
    return "ai_messages"
}

数据库约束

必须存在：

PRIMARY KEY(ai_sessions.id)
INDEX(ai_sessions.updated_at)
INDEX(ai_sessions.status)
INDEX(ai_turns.session_id)
INDEX(ai_turns.created_at)
INDEX(ai_turns.completed_at)
UNIQUE(ai_messages.turn_id, ai_messages.sequence)

session_id 和 turn_id 仅作为普通关联字段，由 Store 在应用层校验。

删除 Session 时，Store 必须在事务中按Message - Turn - Session顺序显式删除，这样可以避免依赖数据库外键和数据库级联行为，并保持 MySQL、PostgreSQL、SQLite 行为一致。

Payload 保存完整的 Genkit ai.Message JSON，不拆分为多个业务字段。

JSON 编解码必须完整保留 Role、Content、Message Metadata，以及 Part 中的 ToolRequest、ToolResponse、Resource、Custom 和 Metadata。解码失败时返回包含 Message ID 的错误，不返回部分解码结果。

5. GormStore

实现 SessionStore、MessageStore 和组合 Store。

GormStore 提供接收已打开 *gorm.DB 的构造函数，用于 Contract Test、重启恢复和多实例测试；生产环境由 MemoryComponent 根据配置创建数据库连接。

AddHistory

在一个短事务中执行：

1. 锁定 Session 行。
2. 校验 Session 存在、状态为 active 且未过期。
3. 查找 active Turn。
4. 如果没有 active Turn，检查已完成 Turn 数：
   • 已达到 max_turns 时返回 ErrTurnLimitReached；
   • 未达到时创建新的 active Turn。
5. 过滤 nil 和未知 Role。
6. 查询该 Turn 的最新 sequence。
7. 按输入顺序编码并插入支持的 Message。
8. 提交事务。

即使过滤后没有可写入的 Message，也必须创建 active Turn。
任何编码或插入失败都必须回滚整个事务，包括 Turn 创建。
事务不能跨越模型推理、工具调用或 SSE 流式输出。
MySQL/PostgreSQL 使用 Session 行锁串行化同一 Session 的 Store 写操作。SQLite 不支持 SELECT ... FOR UPDATE，不作为同一 Session 并发写入保证的依据。

WindowMemory

• 读取 active Turn。
• 按 sequence ASC 查询 Message。
• JSON 解码为 ai.Message。
• 按 system -> user -> model 分组返回。
• 每个 Role 内保持 sequence 顺序。
• 没有 active Turn 时返回空切片。

AllMemory

• 读取 active Turn 和 completed Turn。
• active Turn 始终排在最前。
• completed Turn 按 Turn.ID ASC 排序。
• 每个 Turn 内按 system -> user -> model 分组。
• 每个 Role 内保持 sequence 顺序。
  该顺序用于兼容现有 HistoryMemory 行为，不定义新的全局时间顺序。

NextTurn

在一个短事务中执行：

1. 锁定 Session 行。
2. 查找 active Turn。
3. 校验完成该 Turn 不会超过 max_turns。
4. 最后一个合法 Turn 必须正常完成。
5. 设置 completed_at。
6. 提交事务。
   没有 active Turn 时返回 ErrNoActiveTurn。
   后续创建第 max_turns + 1 个 Turn 时，由 AddHistory 返回 ErrTurnLimitReached。
   发生错误时不得改变 Turn 状态。

Delete

在同一个事务中执行：

锁定 ai_sessions 行
删除该 Session 的 ai_messages
删除该 Session 的 ai_turns
删除 ai_sessions 行

删除不存在的 Session 返回 ErrSessionNotFound。

DeleteExpired

删除超过 24 小时未更新的 Session，并同时删除关联 Turn 和 Message。
要求：

• 每个实例都可以每小时执行清理。
• 不选举单独的 cleanup leader。
• 重复执行必须幂等。
• Gorm 必须在同一个事务中查询并复核过期 Session。
• MySQL/PostgreSQL 在支持时使用行锁。
• 如果其他实例已经刷新 Session，则不得根据旧查询结果删除该 Session。
• 返回值是删除的 Session 数量，不是子数据数量。
• 清理失败只记录日志，并在下一次周期重试。

6. 后端配置和数据库连接

在现有 memory Component 中增加 backend 配置：

type: memory
spec:
  backend: memory
  history_key: chat_history
  max_turns: 100

Gorm 配置示例：

type: memory
spec:
  backend: gorm
  history_key: chat_history
  max_turns: 100
  database:
    driver: mysql
    dsn: ${AI_DB_DSN}
    max_open_conns: 50
    max_idle_conns: 10

配置要求：

• backend 支持 memory 和 gorm，默认值为 memory。
• max_turns 默认值为 100。
• max_turns 是两个 Store 后端共同执行的最大 Turn 数。
• Runtime Gorm backend 支持 MySQL 和 PostgreSQL。
• SQLite 仅由测试构造函数使用。
• Gorm backend 必须配置 database.driver 和 database.dsn。
• 连接池支持 max_open_conns 和 max_idle_conns。
• 默认值为 max_open_conns=100、max_idle_conns=10。
• 连接池参数必须为正。
• max_idle_conns 不得大于 max_open_conns。
• max_turns 必须为正数。
• 初始化时打开数据库连接并执行 AutoMigrate。
• Component 停止时关闭数据库连接。
• Memory backend 不得创建数据库连接。
• 更新 JSON Schema 和配置字段说明文档。

AI 是独立 Go Module，gorm.io/gorm、MySQL、PostgreSQL 和测试用 SQLite driver 必须添加到 ai/go.mod。AI 模块不直接依赖根模块的 pkg/store/dbcommon。

7. Migration、事务、顺序和删除

• ai_sessions、ai_turns、ai_messages 表迁移。
• Session、Turn、Message 写入事务。
• Message 在同一 Turn 内的 sequence 唯一约束。
• Store 应用层维护 Session、Turn、Message 关联关系。
• 不创建数据库外键。
• Session 删除时由 Store 显式删除 Message、Turn、Session。
• Gorm 错误转换为统一 Store 错误。
• MySQL/PostgreSQL 使用事务和行锁保证单次 Store 操作的数据一致性。
• 事务只包含 Store 读写，不跨越模型推理、工具调用或 SSE。
• SQLite 不支持 SELECT ... FOR UPDATE，因此 SQLite 测试不作为同一 Session 并发保证。

8. 测试

Contract Test

MemoryStore 和 GormStore 共用一套测试，覆盖：

• Session 创建、读取、列表、Touch、删除。
• Session 过期判断。
• system、user、model、nil、未知 Role。
• Role 分组顺序。
• WindowMemory 和 AllMemory 顺序。
• 配置的 max_turns 限制。
• 最后一个合法 Turn 可以完成。
• 下一次 AddHistory 返回 ErrTurnLimitReached。
• 超限后不得修改之前的 Turn。
• 无 active Turn 错误。
• Session 删除后的历史清理。
• 返回值为快照，外部修改不能影响 Store 内部数据。

重启恢复测试

使用文件 SQLite：

1. 创建 Store 并执行迁移。
2. 创建 Session。
3. 写入多个 Turn 和 Message。
4. 关闭 Store。
5. 使用同一个数据库文件重新创建 Store。
6. 验证 Session 和完整历史仍然存在且顺序一致。
7. 验证读取非法 Payload 时返回包含 Message ID 的错误。
8. 验证删除逻辑不依赖 SQLite 外键。

多实例共享测试

创建两个连接同一 SQLite 文件的 GormStore：

• 实例 A 写入 Session、Turn 和 Message。
• 实例 B 读取实例 A 写入的数据。
• 验证多个 Turn 的 (turn_id, sequence) 独立。
• 实例 B 删除 Session 后，实例 A 不再能够读取相关数据。

其他测试

• Gorm JSON 编解码测试。
• 事务回滚测试。
• (turn_id, sequence) 唯一约束测试。
• MySQL/PostgreSQL 驱动编译和可选集成测试。
• Agent 和 Memory Tool 共享同一个 Store 实例测试。
• Agent、Handler、Memory Tool、SSE 回归测试。
• 请求取消可以中止模型和工具执行。
• 脱离取消的持久化 Context 可以完成已生成 Message 写入和最终 Turn 收尾。
• MemoryStore go test -race 测试。
• Gorm Component Stop 关闭数据库连接测试。

[robocanic]

方案整体我这边看下来没问题，数据库设计有一个点需要注意，不要在表中使用外键，会拖慢数据库操作的效率。 @larry-zy 再帮忙看看这个设计是否有问题

[larry-zy]

方案整体方向没问题，Store 抽象 + 单实例注入 + MemoryStore/GormStore 共用 Contract Test 的拆分是对的，尤其统一 Store实例正好修掉了现在 Agent 和 Memory Tool 各持一个 HistoryMemory、历史对不上的问题。补充几个小点，结合现有代码核实过，分三档。

一、需要先定的硬问题

1. max_turns 与 TurnLimit=10 必须先对齐
   现状 max_turns（默认 100）一路传到 Component 后并没有下传给 HistoryMemory，真实上限是 history.go 里硬编码的 const TurnLimit =
   10——配置项目前是死代码。第 6 节又把 max_turns 写进配置。请在 spec 里定死：是启用 max_turns（废掉硬编码 10），还是迁移期两边都锁死
   10。否则 GormStore 和 MemoryStore 很容易在这个值上分叉，共用 Contract Test 就失去意义。

2.「保持现有行为」不够——现有的轮次上限行为本身是坏的
NextTurn 在第 10 轮会因窗口满返回 "context is full, please create a new session"，但调用点 react.go 是
history.NextTurn(sessionID)，直接丢弃了返回值。结果：第 10 轮后不再 pop，后续所有对话被静默合并进同一个
turn，「上限」对用户不可见、也没真正拦住。所以第 2/5 节请用文字把目标语义写清楚（一个 session 最多 N
轮、到顶后对用户如何表现），而不是「保持现有行为」——因为现有行为是个 bug。

二、spec 内部需要澄清

3. role 分组顺序 vs 单一 sequence
   第 2 节要保留 system/user/model 分组和读取顺序，但第 4 节 Message 只有单个 sequence、role 埋在 Payload 里，ORDER BY sequence
   只能还原插入顺序。当前生产链路每次只写单条、且只有 user/model（没有 system 写历史），插入序恰好等于分组序，撞不到；但第 8
   节「AddHistory 的 Role 分组和顺序」测试一旦传混合 role，MemoryStore（按 role 重排）和 GormStore（按
   sequence）就会分叉。建议二选一并写进 spec：放弃分组统一按插入序（更简单，不影响现链路），或加 role/group 列按 (role_group,
   sequence) 排。顺带一提，AllMemory 现有顺序是「当前 turn 在最前、再接旧历史」，反直觉，spec
   别只写「保持兼容顺序」，把顺序显式定义并进契约测试。

三、设计建议（非 bug）

4. request ctx 与持久化
   现在 agent goroutine 跑在 context.Background() 派生的 ctx 上，和 gin 请求刻意解耦——客户端断连（handler 在
   c.Request.Context().Done() 直接 return）后，生成和落库仍会在后台跑完。第 3 节要把 gin ctx 传进 Agent/Store
   支持取消，等于反转这个解耦。取消推理本身合理（省 token），但把存储写入也挂上去有副作用：断连时
   NextTurn/收尾写入会被取消，可能留下未 finalize 的半截 turn；或某次写入正好在事务中被取消回滚。建议区分：推理/工具调用挂请求
   ctx，生成后的 AddHistory/NextTurn 用脱离取消的 ctx。

5. 共享库下的 List/DeleteExpired
   List(ctx) 无过滤/分页，在多实例共享库下会全表扫，建议签名带 status/updatedAt 过滤 + 分页（也为将来 tenant 留口）。另外
   cleanupExpiredSessions 每个实例都会周期性打 DeleteExpired，spec 说明清由谁清理即可。

[beatenevo]

方案整体方向没问题，Store 抽象 + 单实例注入 + MemoryStore/GormStore 共用 Contract Test 的拆分是对的，尤其统一 Store实例正好修掉了现在 Agent 和 Memory Tool 各持一个 HistoryMemory、历史对不上的问题。补充几个小点，结合现有代码核实过，分三档。

一、需要先定的硬问题

1. max_turns 与 TurnLimit=10 必须先对齐
   现状 max_turns（默认 100）一路传到 Component 后并没有下传给 HistoryMemory，真实上限是 history.go 里硬编码的 const TurnLimit =
   10——配置项目前是死代码。第 6 节又把 max_turns 写进配置。请在 spec 里定死：是启用 max_turns（废掉硬编码 10），还是迁移期两边都锁死
   10。否则 GormStore 和 MemoryStore 很容易在这个值上分叉，共用 Contract Test 就失去意义。

2.「保持现有行为」不够——现有的轮次上限行为本身是坏的 NextTurn 在第 10 轮会因窗口满返回 "context is full, please create a new session"，但调用点 react.go 是 history.NextTurn(sessionID)，直接丢弃了返回值。结果：第 10 轮后不再 pop，后续所有对话被静默合并进同一个 turn，「上限」对用户不可见、也没真正拦住。所以第 2/5 节请用文字把目标语义写清楚（一个 session 最多 N 轮、到顶后对用户如何表现），而不是「保持现有行为」——因为现有行为是个 bug。

二、spec 内部需要澄清

3. role 分组顺序 vs 单一 sequence
   第 2 节要保留 system/user/model 分组和读取顺序，但第 4 节 Message 只有单个 sequence、role 埋在 Payload 里，ORDER BY sequence
   只能还原插入顺序。当前生产链路每次只写单条、且只有 user/model（没有 system 写历史），插入序恰好等于分组序，撞不到；但第 8
   节「AddHistory 的 Role 分组和顺序」测试一旦传混合 role，MemoryStore（按 role 重排）和 GormStore（按
   sequence）就会分叉。建议二选一并写进 spec：放弃分组统一按插入序（更简单，不影响现链路），或加 role/group 列按 (role_group,
   sequence) 排。顺带一提，AllMemory 现有顺序是「当前 turn 在最前、再接旧历史」，反直觉，spec
   别只写「保持兼容顺序」，把顺序显式定义并进契约测试。

三、设计建议（非 bug）

4. request ctx 与持久化
   现在 agent goroutine 跑在 context.Background() 派生的 ctx 上，和 gin 请求刻意解耦——客户端断连（handler 在
   c.Request.Context().Done() 直接 return）后，生成和落库仍会在后台跑完。第 3 节要把 gin ctx 传进 Agent/Store
   支持取消，等于反转这个解耦。取消推理本身合理（省 token），但把存储写入也挂上去有副作用：断连时
   NextTurn/收尾写入会被取消，可能留下未 finalize 的半截 turn；或某次写入正好在事务中被取消回滚。建议区分：推理/工具调用挂请求
   ctx，生成后的 AddHistory/NextTurn 用脱离取消的 ctx。
5. 共享库下的 List/DeleteExpired
   List(ctx) 无过滤/分页，在多实例共享库下会全表扫，建议签名带 status/updatedAt 过滤 + 分页（也为将来 tenant 留口）。另外
   cleanupExpiredSessions 每个实例都会周期性打 DeleteExpired，spec 说明清由谁清理即可。

thx，I have updated my spec according your comment,for the list, I`d like to address it during future extensions.