# H5 Event Mapper 与 SSE 契约

## 1. 目标

建立一层稳定的 **Hermes event -> Jarvis SSE** 映射边界，让前端无需理解 Hermes 内部事件模型。

## 2. 当前约束

前端当前主要依赖：
- `frontend/src/api/conversation.ts`
- `frontend/src/pages/chat/composables/useChatView.ts`

并假设 SSE 事件名为：
- `metadata`
- `progress`
- `chunk`
- `error`
- `done`

Hermes-first 改造不能让 UI 直接去消费 Hermes-native event。

## 3. 推荐映射原则

### 3.1 保持外部契约稳定

对前端继续输出：
- `metadata`
- `progress`
- `chunk`
- `error`
- `done`

### 3.2 Hermes richer event 不直接外泄

更细的 runtime 细节：
- tool trace
- retry/restart details
- health transitions
- session diagnostics

应该进入：
- runtime observability
- attachments
- agent_state metadata

而不是直接让 UI 依赖这些字段。

## 4. 推荐映射关系

- session prepare / hydrate / warm reuse -> `progress`
- assistant content delta -> `chunk`
- execution failure -> `error`
- finish signal -> `done`
- conversation/message identity -> `metadata`

## 5. 推荐文件变更

- 新增：`backend/app/services/agent_runtime/hermes_event_mapper.py`
- 修改：
  - `backend/app/services/agent_runtime/hermes_runtime.py`
  - `backend/app/services/agent_service.py`
  - `frontend/src/api/conversation.ts`（如需轻量兼容字段扩展）

## 6. 设计约束

1. SSE 事件名不破坏。
2. 前端 parser 不因 Hermes-first 被重写。
3. 缺失字段允许降级，但事件序列必须稳定。
4. 错误事件不能导致 assistant message 持久化乱序。

## 7. 完成标准

- [ ] Hermes runtime 有明确的 event mapping 边界
- [ ] 前端现有 SSE parser 继续可用
- [ ] richer diagnostics 有单独落点，不污染 UI 契约