# H2 Continuity Envelope

## 1. 目标

把 `Conversation.agent_state` 从“当前 runtime 顺手写进去的状态桶”升级成 **runtime-neutral continuity envelope**。

## 2. 当前问题

当前状态里：
- Jarvis continuity 已较丰富
- Hermes runtime metadata 仍较浅
- 两边并没有统一的 envelope

风险是：
- Hermes session state 覆盖 Jarvis continuity
- 回滚时状态结构混乱
- 后端重启后难以恢复 runtime continuity

## 3. 目标结构

建议方向：

```json
{
  "version": 2,
  "active_runtime": "hermes",
  "runtime_state": {
    "jarvis": { "...": "fallback/runtime snapshot" },
    "hermes": {
      "session_id": "...",
      "status": "warm|resumed|cold|error",
      "last_used_at": "...",
      "restart_count": 0,
      "health": { "...": "..." }
    }
  },
  "product_continuity": {
    "turn_context": {},
    "pending_action": {},
    "task_state": {},
    "memory_checkpoint": {}
  },
  "migration": {
    "source": "jarvis-legacy",
    "updated_at": "..."
  }
}
```

## 4. 核心原则

1. Jarvis 拥有产品 continuity。
2. Hermes 拥有 runtime continuity。
3. envelope 负责把两者挂在一起。
4. 不能让 Hermes session id 替代产品 continuity。

## 5. 影响范围

- `backend/app/models/conversation.py`
- `backend/app/services/agent_service.py`
- `backend/app/agents/state.py`
- `backend/app/services/agent_runtime/hermes_session_manager.py`

## 6. 历史兼容

本阶段必须考虑：
- 兼容旧 `agent_state`
- 兼容 Jarvis-only 历史 conversation
- 允许逐步迁移，不要求一次性重写所有旧数据

## 7. 完成标准

- [ ] `agent_state` 有统一 envelope 结构
- [ ] Jarvis continuity 与 Hermes runtime state 不再互相覆盖
- [ ] 老 conversation 可兼容读取
- [ ] 为 H3 durable lifecycle 提供恢复所需元数据