Enum AgentEvent 

pub enum AgentEvent {
    AgentStart,
    RunIdentified {
        identity: RunIdentity,
    },
    AgentEnd {
        messages: Vec<AgentMessage>,
    },
    TurnStart,
    TurnEnd {
        message: AgentMessage,
        tool_results: Vec<AgentMessage>,
    },
    MessageStart {
        message: AgentMessage,
    },
    MessageUpdate {
        partial: AgentMessage,
        chunk: AssistantStreamChunk,
    },
    MessageEnd {
        message: AgentMessage,
    },
    ToolExecutionStart {
        tool_call_id: String,
        tool_name: String,
        args: Value,
    },
    ToolExecutionUpdate {
        tool_call_id: String,
        tool_name: String,
        partial: ToolResult,
    },
    ToolExecutionEnd {
        tool_call_id: String,
        tool_name: String,
        result: ToolResult,
        is_error: bool,
    },
    OutputTokensEscalation {
        attempt: u8,
        prev_cap: u32,
        new_cap: u32,
    },
    ContextTransformApplied {
        iteration: usize,
        plugin: &'static str,
        before: Vec<AgentMessage>,
        after: Vec<AgentMessage>,
    },
    ToolGateApplied {
        iteration: usize,
        plugin: &'static str,
        allow: Option<Vec<String>>,
    },
    ToolGateConflictResolved {
        iteration: usize,
        plugins: Vec<String>,
        chosen_plugin: Option<String>,
        allow: Vec<String>,
        reason: String,
    },
    ProviderRequestPrepared {
        iteration: usize,
        model_id: Option<String>,
        system_prompt: String,
        messages: Vec<AgentMessage>,
        tools: Vec<ToolSchema>,
        temperature: Option<f32>,
        max_output_tokens: Option<u32>,
    },
}

All events the loop emits.

Lifecycle events (AgentStart, AgentEnd, TurnStart, TurnEnd) bracket the run. Message events (MessageStart, MessageUpdate, MessageEnd) bracket each individual message. Tool events (ToolExecutionStart, ToolExecutionUpdate, ToolExecutionEnd) bracket each tool call.

Variants

AgentStart

First event in a run. Emitted once.

RunIdentified

Run identity, emitted immediately after AgentEvent::AgentStart when the context carries a RunIdentity. Trajectory sinks key every subsequent event of the same run on identity.run_id; child runs surface their parent_run_id so the spawn tree rebuilds without external bookkeeping.

Existing observers that don’t care about identity ignore this variant (every match arm in the tree already has a wildcard fallback). Plugins and sinks that want identity pattern-match directly.

Fields

identity: RunIdentity

AgentEnd

Last event in a run. Carries the messages produced during this run (not the full transcript). Listeners that want the full transcript should fold prior messages into a state of their own.

Fields

messages: Vec<AgentMessage>

TurnStart

Bracket: a new turn begins. A turn is one assistant response plus any tool calls/results it spawned.

TurnEnd

Bracket: a turn ends. Carries the assistant message and the tool results for that turn (empty if the model didn’t call any tools).

Fields

message: AgentMessage

tool_results: Vec<AgentMessage>

MessageStart

A message has been added to the transcript (user, assistant, or tool result). For assistant messages, this fires before streaming begins; subsequent MessageUpdate events carry deltas.

Fields

message: AgentMessage

MessageUpdate

Streaming delta for the in-progress assistant message.

Fields

partial: AgentMessage

chunk: AssistantStreamChunk

MessageEnd

The message has been fully assembled (final content, stop reason).

Fields

message: AgentMessage

ToolExecutionStart

A tool execution has begun.

Fields

tool_call_id: String

tool_name: String

args: Value

ToolExecutionUpdate

Partial progress from a long-running tool. The tool calls update.send(...) to surface intermediate state without ending.

Fields

tool_call_id: String

tool_name: String

partial: ToolResult

ToolExecutionEnd

A tool execution has finished.

Fields

tool_call_id: String

tool_name: String

result: ToolResult

is_error: bool

OutputTokensEscalation

The loop discarded a truncated assistant turn and re-streamed with a higher max_output_tokens cap. Emitted once per retry attempt; multiple events for the same turn signal the recovery walked the configured ladder. See crate::config::MaxTokensRecovery.

Fields

attempt: u8

1-indexed retry counter within the current turn.

prev_cap: u32

Cap that produced the truncated turn we’re discarding.

new_cap: u32

Cap we’re re-streaming with.

ContextTransformApplied

A ContextTransform plugin ran on this turn’s transcript. Emitted once per active transform per turn, in registration order. Carries the full before/after message slices so observers can reconstruct exactly which messages each transform removed, added, or rewrote — the canonical answer to “which compaction stripped that tool result we expected the model to still see?”.

Fields

iteration: usize

Zero-indexed turn within the current run. Same semantics as crate::plugin::TransformContext::iteration.

plugin: &'static str

Plugin::name of the transform that just ran.

before: Vec<AgentMessage>

Transcript handed to the transform.

after: Vec<AgentMessage>

Transcript the transform returned.

ToolGateApplied

A ToolGate plugin contributed to this turn’s allowlist. Emitted once per gate per turn. Multiple gates compose by intersection downstream; this event records the gate’s own decision before composition so observers can attribute the final allowlist to specific plugins.

Fields

iteration: usize

Zero-indexed turn within the current run.

plugin: &'static str

Plugin::name of the gate.

allow: Option<Vec<String>>

None when the gate declined to constrain; Some(names) when it returned an allowlist (sorted for stable diffing).

ToolGateConflictResolved

Multiple ToolGate plugins narrowed the same turn to disjoint non-empty allowlists. The loop repaired the composition to avoid advertising an empty tool catalog to the model.

Fields

iteration: usize

Zero-indexed turn within the current run.

plugins: Vec<String>

Gate names that returned a non-empty allowlist.

chosen_plugin: Option<String>

Gate whose allowlist won the deterministic repair policy.

allow: Vec<String>

Final repaired allowlist, sorted for stable diffing.

reason: String

Human-readable policy reason for trajectory/debug inspection.

ProviderRequestPrepared

Snapshot of the request the loop is about to send to the provider on this turn, taken after every ContextTransform has run and every ToolGate has filtered. This is the typed view of “what the model sees” — wire-format conversion (provider-specific shapes) happens downstream inside the StreamFn. Emitted once per turn, just before the stream call.

Fields

iteration: usize

Zero-indexed turn within the current run.

model_id: Option<String>

Model identifier the host associated with this loop, when known. Provider transports still own their wire conversion, so this is observability metadata only.

system_prompt: String

System prompt for this turn. May include ephemeral system reminders injected by ContextTransform plugins.

messages: Vec<AgentMessage>

Full message history the loop is about to send.

tools: Vec<ToolSchema>

Tool schemas advertised this turn, post-ToolGate filtering.

temperature: Option<f32>

Sampling temperature forwarded to the provider stream, when configured.

max_output_tokens: Option<u32>

Resolved per-turn output cap.

Trait Implementations

impl Clone for AgentEvent

fn clone(&self) -> AgentEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentEvent

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

Formats the value using the given formatter.

impl Deserialize<'static> for AgentEvent

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

where __D: Deserializer<'static>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentEvent

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

where __S: Serializer,

Serialize this value into the given Serde serializer.