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 / tool_input 新增片段
• turn：Turn 的 start / finish 生命周期
• compact：显式压缩的 start / finish 生命周期
• session：Session 自身状态变化，例如 title

Interaction Part 进入 pending 后携带完整请求；关联 Tool 同时进入 waiting-user。订阅保持为纯数据通道，用户决定通过 Session 命令 API 提交：

session.subscribe((mutation) => {
  if (
    mutation.variant === "part" &&
    mutation.type === "interaction" &&
    mutation.part.status === "pending"
  ) {
    render_interaction(mutation.part);
  }
});

await session.respond({
  interaction_id,
  response: { kind: "approval", decision: "approved" },
});

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