Session Mutation

session.subscribe() 返回统一的 SessionMutation。Message 数据、流式增量、Turn 生命周期和 Session 状态都通过同一个订阅入口传递。

所有 Mutation 都有 mutation_id、session_id 与 created_at。Message 相关 Mutation 还包含 message_id 与 revision，客户端用它们定位目标消息并防止旧快照覆盖新状态。

最常见的是文本 delta

如果你只是做实时文本输出，通常只需要先处理：

if (mutation.variant === "delta" && mutation.type === "text") {
  process.stdout.write(mutation.delta);
}

五种 variant 的职责是：

• message：完整顶层 Message 快照
• part：完整 Assistant Part 快照，例如 Tool 状态
• delta：text / reasoning 新增片段
• turn：Turn 的 start / finish 生命周期
• session：Session 自身状态变化，例如 title

Tool Part 进入 approval-required 后会携带完整审批请求。订阅保持为纯数据通道，用户决定通过 Session 命令 API 提交：

session.subscribe((mutation) => {
  if (
    mutation.variant === "part" &&
    mutation.type === "tool" &&
    mutation.part.state === "approval-required" &&
    mutation.part.approval
  ) {
    show_approval_request(mutation.part.approval);
  }
});

await session.resolve_approval({
  approval_id,
  decision: "approved",
});

Mutation 是实时协议，不是历史格式。加载已有历史使用 messages()；网络重连后重新读取 Message 与 Session 快照并重新订阅。完整的字段表、状态机和无丢事件同步方案见 实时订阅 与 重连与同步。