Session Mutations

session.subscribe() delivers one unified SessionMutation stream for Message data, streaming output, Turn lifecycle, and Session state.

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

The seven variants are message, part, delta, turn, file_diff, session, and warning. A warning / model_request Mutation reports a failed model call and whether another retry will follow. Delta types are text, reasoning, and tool_input; the last one also carries tool_call_id. All Mutations contain mutation_id, session_id, and created_at. Message-related Mutations also carry message_id and revision for safe snapshot updates.

A pending Interaction lives on its Tool Part and carries the complete request while that Tool is waiting-user. The subscription remains a data-only channel; submit a user response through the Session command 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" } },
});

Mutations are a live protocol, not the history format. Use messages() for Message state and get_info() for Session state. Reload snapshots and subscribe again after a disconnect. For the complete field table, state machine, and loss-free sync algorithm, see Live subscriptions and Reconnect and sync.