# Session、Run 与 Trace 生命周期

**更新日期**：2026-07-22
**状态**：当前可运行架构

## 1. Identity

- `sessionId`：多轮对话目录，由客户端传入或应用生成。
- `runId`：一次 Chat 执行，由 Harness 生成并在 SSE metadata 首事件返回。
- 所有 Run、AgentStep、ToolInvocation 和 Trace 查询必须使用同一个 exact ID；禁止用“最新一条”替代。

## 2. 生命周期

```text
request accepted
  -> start RunContext
  -> persist diagnosis_run RUNNING
  -> metadata(session_id, run_id)
  -> route / execute / guard / release
  -> SUCCESS | FALLBACK | FAILED | CANCELLED
  -> persist terminal state and budget usage
```

disconnect、timeout 与 send failure 通过同一个 `ChatRunControl` 请求取消。正常 SSE complete 在 callback 前标记 terminal，避免误取消；late content 被 state machine 拒绝。

## 3. Trace 聚合

`GET /api/diagnosis/{sessionId}/trace?runId={runId}` 聚合：

- `chat_session` metadata。
- exact `diagnosis_run` 状态、intent、release outcome、安全 answer 与预算。
- `agent_step` metadata-only 模型步骤。
- `tool_invocation` metadata-only Tool durable audit。

Redis canonical invocation 不是 Trace API 的长期响应内容；它只供当前 Run EvidenceGuard 验真。

## 4. PreviousTurn

应用在创建当前 Run 前读取同 Session 最近安全发布结果。只允许结构化 PublishedResult 的固定字段进入 PreviousTurn，且执行字节上限；完整历史、失败、Fallback、Tool raw data 和 guard reason 均排除。