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 six variants are message, part, delta, turn, compact, and session. 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 Part carries the complete request while its related 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.type === "interaction" &&
    mutation.part.status === "pending"
  ) {
    render_interaction(mutation.part);
  }
});

await session.respond({
  interaction_id,
  response: { kind: "approval", 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.