Enum AgentEvent 

pub enum AgentEvent {
    RunStarted {
        agent: String,
        task: String,
    },
    TurnStarted {
        agent: String,
        turn: usize,
        max_turns: usize,
    },
    LlmResponse {
        agent: String,
        turn: usize,
        usage: TokenUsage,
        stop_reason: StopReason,
        tool_call_count: usize,
        text: String,
        latency_ms: u64,
        model: Option<String>,
        time_to_first_token_ms: u64,
    },
    Reasoning {
        agent: String,
        turn: usize,
        text: String,
    },
    ToolCallStarted {
        agent: String,
        tool_name: String,
        tool_call_id: String,
        input: String,
    },
    ToolCallCompleted {
        agent: String,
        tool_name: String,
        tool_call_id: String,
        is_error: bool,
        duration_ms: u64,
        output: String,
    },
    ApprovalRequested {
        agent: String,
        turn: usize,
        tool_names: Vec<String>,
    },
    ApprovalDecision {
        agent: String,
        turn: usize,
        approved: bool,
    },
    SubAgentsDispatched {
        agent: String,
        agents: Vec<String>,
    },
    SubAgentCompleted {
        agent: String,
        success: bool,
        usage: TokenUsage,
    },
    ContextSummarized {
        agent: String,
        turn: usize,
        usage: TokenUsage,
    },
    RunCompleted {
        agent: String,
        total_usage: TokenUsage,
        tool_calls_made: usize,
    },
    GuardrailDenied {
        agent: String,
        hook: String,
        reason: String,
        tool_name: Option<String>,
    },
    GuardrailWarned {
        agent: String,
        hook: String,
        reason: String,
        tool_name: Option<String>,
    },
    RunFailed {
        agent: String,
        error: String,
        partial_usage: TokenUsage,
    },
    RequestRouted {
        agent: String,
        mode: String,
        source: String,
        confidence: f32,
    },
    GateFired {
        agent: String,
        gate: String,
        reason: String,
    },
    RetryAttempt {
        agent: String,
        attempt: u32,
        max_retries: u32,
        delay_ms: u64,
        error_class: String,
    },
    DoomLoopDetected {
        agent: String,
        turn: usize,
        consecutive_count: u32,
        tool_names: Vec<String>,
    },
    FuzzyDoomLoopDetected {
        agent: String,
        turn: usize,
        consecutive_count: u32,
        tool_names: Vec<String>,
    },
    KillSwitchActivated {
        agent: String,
        reason: String,
        guardrail_name: String,
    },
    SessionPruned {
        agent: String,
        turn: usize,
        tool_results_pruned: usize,
        bytes_saved: usize,
        tool_results_total: usize,
    },
    AutoCompactionTriggered {
        agent: String,
        turn: usize,
        success: bool,
        usage: TokenUsage,
    },
    SensorEventProcessed {
        sensor_name: String,
        decision: String,
        priority: Option<String>,
        story_id: Option<String>,
    },
    StoryUpdated {
        story_id: String,
        subject: String,
        event_count: usize,
        priority: Option<String>,
    },
    ModelEscalated {
        agent: String,
        from_tier: String,
        to_tier: String,
        reason: String,
    },
    BudgetExceeded {
        agent: String,
        used: u64,
        limit: u64,
        partial_usage: TokenUsage,
    },
    AgentSpawned {
        agent: String,
        spawned_name: String,
        tools: Vec<String>,
        task: String,
    },
    TaskRouted {
        decision: String,
        reason: String,
        selected_agent: Option<String>,
        complexity_score: f32,
        escalated: bool,
    },
    WorkflowNodeStarted {
        node: String,
    },
    WorkflowNodeCompleted {
        node: String,
    },
    WorkflowNodeFailed {
        node: String,
    },
    ToolNameRepaired {
        agent: String,
        original: String,
        repaired: String,
    },
}

Structured events emitted during agent and orchestrator execution.

All events carry the agent name for identification in multi-agent runs. Events are emitted synchronously via the OnEvent callback — keep handlers fast to avoid blocking the agent loop.

Variants

RunStarted

Agent loop started.

Fields

agent: String

task: String

TurnStarted

A new turn in the agent loop.

Fields

agent: String

turn: usize

max_turns: usize

LlmResponse

LLM call completed.

Fields

agent: String

turn: usize

usage: TokenUsage

stop_reason: StopReason

tool_call_count: usize

text: String

Truncated LLM response text.

latency_ms: u64

Wall-clock milliseconds for the LLM call.

model: Option<String>

Model name from the provider, if available.

time_to_first_token_ms: u64

Time-to-first-token in milliseconds (streaming only). 0 for non-streaming.

Reasoning

The model emitted chain-of-thought before its answer (reasoning models only — qwen3-thinking, deepseek-r1). Carried separately from the answer text so a UI can render it distinctly (dimmed/collapsible).

Fields

agent: String

turn: usize

text: String

Truncated reasoning text.

ToolCallStarted

Tool execution started.

Fields

agent: String

tool_name: String

tool_call_id: String

input: String

Truncated JSON string of tool input.

ToolCallCompleted

Tool execution completed.

Fields

agent: String

tool_name: String

tool_call_id: String

is_error: bool

duration_ms: u64

output: String

Truncated tool output content.

ApprovalRequested

Human approval requested.

Fields

agent: String

turn: usize

tool_names: Vec<String>

ApprovalDecision

Human approval decision received.

Fields

agent: String

turn: usize

approved: bool

SubAgentsDispatched

Orchestrator dispatched sub-agents.

Fields

agent: String

agents: Vec<String>

SubAgentCompleted

A sub-agent completed.

Fields

agent: String

success: bool

usage: TokenUsage

ContextSummarized

Context was summarized due to threshold.

Fields

agent: String

turn: usize

usage: TokenUsage

RunCompleted

Agent run completed successfully.

Fields

agent: String

total_usage: TokenUsage

tool_calls_made: usize

GuardrailDenied

A guardrail denied an LLM response or tool call.

Fields

agent: String

hook: String

Which hook triggered the denial: "post_llm", "pre_tool", or "post_tool".

reason: String

tool_name: Option<String>

Set for pre_tool and post_tool denials, None for post_llm.

GuardrailWarned

A guardrail issued a warning but allowed the operation to proceed.

Fields

agent: String

hook: String

Which hook triggered the warning: "post_llm" or "pre_tool".

reason: String

tool_name: Option<String>

Set for pre_tool warnings, None for post_llm.

RunFailed

Agent run failed.

Fields

agent: String

error: String

partial_usage: TokenUsage

RequestRouted

An LLM retry attempt is about to happen (before the sleep). A fresh request was routed to a response mode (request-intent router).

Fields

agent: String

Agent name.

mode: String

The chosen mode label (“answer”/“execute”/“study”/“clarify”).

source: String

Which layer decided (“markers”/“classifier”/“safe_default”/“pinned”/“affirmation”).

confidence: f32

Classifier confidence (1.0 for deterministic sources).

GateFired

A deterministic harness gate fired (ask/act/plan/mode-contract/study/ repair-hint/escalation/delegation-nudge). These inject guidance into the agent’s context; this event makes them visible in the trace so a session can be audited (previously invisible — they were user messages).

Fields

agent: String

Agent name.

gate: String

Gate identifier (“plan_gate”, “ask_gate”, “act_gate”, “mode_contract”, “study_contract”, “repair_hint”, “deps_hint”, “escalation”, “delegation_nudge”, “same_agent_fanout”, “same_agent_fanout_dispatched”).

reason: String

Short reason / context (e.g. the failure class, the routed mode).

RetryAttempt

Fields

agent: String

attempt: u32

Current attempt number (1-indexed).

max_retries: u32

Maximum retries configured.

delay_ms: u64

Delay in milliseconds before the retry.

error_class: String

Classified error that triggered the retry.

DoomLoopDetected

Doom loop detected: the agent repeated identical tool calls too many times.

Fields

agent: String

turn: usize

consecutive_count: u32

Number of consecutive identical turns.

tool_names: Vec<String>

Tool names in the repeated batch.

FuzzyDoomLoopDetected

Fuzzy doom loop detected: the agent repeated the same tools with different inputs.

Fields

agent: String

turn: usize

consecutive_count: u32

Number of consecutive fuzzy-identical turns.

tool_names: Vec<String>

Tool names in the repeated batch.

KillSwitchActivated

Kill switch activated: a guardrail triggered an immediate agent termination.

Fields

agent: String

reason: String

guardrail_name: String

SessionPruned

Session pruning truncated old tool results before an LLM call.

Fields

agent: String

turn: usize

tool_results_pruned: usize

Number of tool results that were truncated.

bytes_saved: usize

Total bytes removed across all truncated tool results.

tool_results_total: usize

Total tool results inspected (pruned + skipped).

AutoCompactionTriggered

Auto-compaction was triggered due to context overflow.

Fields

agent: String

turn: usize

success: bool

Whether compaction succeeded.

usage: TokenUsage

Token usage from the compaction LLM call.

SensorEventProcessed

A sensor event was processed through the triage pipeline.

Fields

sensor_name: String

decision: String

“promote”, “drop”, or “dead_letter”

priority: Option<String>

story_id: Option<String>

StoryUpdated

A story was created or updated with new correlated events.

Fields

story_id: String

subject: String

event_count: usize

priority: Option<String>

ModelEscalated

Model cascade escalated from a cheaper tier.

Fields

agent: String

from_tier: String

to_tier: String

reason: String

“gate_rejected” or “tier_error”

BudgetExceeded

Token budget exceeded: the agent consumed more tokens than the configured limit.

Fields

agent: String

used: u64

Total tokens consumed (input + output) across all turns.

limit: u64

The configured token budget limit.

partial_usage: TokenUsage

Partial token usage accumulated before the budget was exceeded.

AgentSpawned

A dynamic agent was spawned at runtime by the orchestrator.

Fields

agent: String

spawned_name: String

tools: Vec<String>

task: String

TaskRouted

Task was routed to single-agent or orchestrator by the complexity analyzer.

Fields

decision: String

“single_agent” or “orchestrate”

reason: String

selected_agent: Option<String>

complexity_score: f32

escalated: bool

WorkflowNodeStarted

A workflow node agent has started executing (emitted by the workflow executor).

Fields

node: String

WorkflowNodeCompleted

A workflow node agent has completed executing (emitted by the workflow executor).

Fields

node: String

WorkflowNodeFailed

A workflow node agent has failed (emitted by the workflow executor).

Fields

node: String

ToolNameRepaired

LLM emitted an unknown tool name that was repaired via Levenshtein distance. The repair happens before permission/guardrail evaluation so the policy applies to the repaired name, not the typo.

Fields

agent: String

original: String

repaired: String

Implementations

impl AgentEvent

pub fn type_name(&self) -> &'static str

Returns the serde tag name for this event variant (e.g. "run_started").

Matches the #[serde(tag = "type", rename_all = "snake_case")] tags without requiring JSON serialization.

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<'de> Deserialize<'de> for AgentEvent

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

where __D: Deserializer<'de>,

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.