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 生命周期
• file_diff：当前 Turn 的文件改动实时摘要
• session：Session 自身状态变化，例如 title
• warning：不写入历史的运行期警告，例如模型请求失败与重试

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

session.subscribe((mutation) => {
  if (mutation.variant !== "part" || mutation.part.type !== "tool") return;
  const interaction = (mutation.part.interactions ?? []).find(
    (item) => item.status === "pending",
  );
  if (interaction) render_interaction(interaction);
});

await session.respond({
  interaction_id,
  response: { type: "approval", outcome: "resolved", payload: { decision: "approved" } },
});

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