Enum RunEvent 

pub enum RunEvent {
    SessionStarted {
        protocol_version: u32,
        cli_version: String,
        model: String,
        task_id: Option<String>,
        session_id: String,
    },
    Text {
        delta: String,
    },
    Reasoning {
        delta: String,
    },
    ToolStarted {
        call_id: String,
    },
    ToolFinished {
        call_id: String,
        name: String,
        status: String,
        summary: String,
        error: Option<String>,
        plan: Option<PlanApproved>,
        web: Option<Box<WebEventDetails>>,
    },
    ApprovalRequired {
        call_id: String,
        tool: String,
        risk: String,
        prompt: String,
    },
    TasksUpdated {
        tasks: Vec<TaskLine>,
        completed: u32,
        total: u32,
    },
    Error {
        message: String,
    },
    TurnDone {
        total_tokens: Option<u64>,
        stop_reason: Option<String>,
    },
    Result {
        response: String,
        reasoning: Option<String>,
        total_tokens: u64,
        errors: Vec<String>,
        session_id: String,
        structured_output: Option<Value>,
    },
}

One line of the mermaid run --format ndjson stream. Internally tagged on type (snake_case), matching the house style for stable wire unions (ToolMetadata).

Variants

SessionStarted

First line of every stream: protocol version + run identity.

Fields

protocol_version: u32

RUN_EVENT_PROTOCOL_VERSION at the time of emission.

cli_version: String

Mermaid version that produced the stream.

model: String

Resolved model id driving the run.

task_id: Option<String>

Durable runtime task id, when the run is task-backed.

session_id: String

Conversation/session id owning this run — pass it to mermaid run --resume <id> to continue the session. Additive (defaulted) so pre-existing recordings still deserialize.

Text

A chunk of assistant answer text.

Fields

delta: String

The appended text.

Reasoning

A chunk of model reasoning / thinking.

Fields

delta: String

The appended reasoning text.

ToolStarted

A tool began executing (bracketed by a later RunEvent::ToolFinished with the same call_id).

Fields

call_id: String

Stable per-run tool-call id.

ToolFinished

A tool finished. name is derived from the run metadata; status is success / error / cancelled.

Fields

call_id: String

Stable per-run tool-call id (matches the tool_started line).

name: String

Tool name, e.g. execute_command, read_file, <server>/<tool>.

status: String

success, error, or cancelled.

summary: String

One-line human summary of the outcome.

error: Option<String>

Error detail, when the tool failed.

plan: Option<PlanApproved>

Present when this call is exit_plan_mode resolving with an APPROVED plan — first-class plan visibility for SDK/daemon subscribers without breaking the started/finished pairing. Additive: absent for every other tool, and omitted from the wire when None.

web: Option<Box<WebEventDetails>>

Structured, secret-safe web transport details for web tools.

ApprovalRequired

A gated tool is waiting for approval. Headless runs surface this so a supervising process can decide.

Fields

call_id: String

Stable per-run tool-call id.

tool: String

Tool name being gated.

risk: String

Risk classification (e.g. network, mutation).

prompt: String

Human-readable approval prompt.

TasksUpdated

The session task checklist changed (task_create / task_update / a user /tasks edit). Full snapshot of the visible list, so consumers never need to correlate diffs. Additive — protocol stays v1.

Fields

tasks: Vec<TaskLine>

Every non-deleted task, in creation order.

completed: u32

Count of completed tasks (numerator of “Tasks m/n”).

total: u32

Count of visible tasks (denominator of “Tasks m/n”).

Error

The turn hit a recoverable or terminal upstream error.

Fields

message: String

Human-readable error message.

TurnDone

A model turn completed (token usage + why it stopped, when known).

Fields

total_tokens: Option<u64>

Total tokens for the turn, when the provider reported them.

stop_reason: Option<String>

Why the turn stopped (stop, length, tool_use, …), when known.

Result

Terminal line of the stream: the aggregated run result.

Fields

response: String

Final assistant response text.

reasoning: Option<String>

Final reasoning text, when the model exposed any.

total_tokens: u64

Cumulative token usage for the whole run.

errors: Vec<String>

Errors encountered during the run (empty on success).

session_id: String

Conversation/session id owning this run (same as the session_started line; repeated here so a consumer that only reads the terminal line still gets it). Additive (defaulted).

structured_output: Option<Value>

--output-schema runs: the response parsed as JSON, present only when it parsed AND validated against the schema. Additive (defaulted) — protocol_version stays 1.

Implementations

impl RunEvent

pub fn from_msg(msg: &Msg) -> Option<RunEvent>

Project a lifecycle Msg into a public RunEvent, or None for the many messages that have no place in the SDK stream.

Pure and stateless: tool identity is read from the finished outcome’s metadata rather than correlated across messages, so no projector state is required. The wildcard arm is intentional here (this is a lossy projection, not the reducer — most Msgs are deliberately dropped).

Trait Implementations

impl Clone for RunEvent

fn clone(&self) -> RunEvent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RunEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RunEvent

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for RunEvent

fn eq(&self, other: &RunEvent) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for RunEvent

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for RunEvent