Enum AgentEvent 

pub enum AgentEvent {
    InvocationStarted {
        role: AgentRole,
        agent: String,
        model: Option<String>,
    },
    InvocationSucceeded {
        role: AgentRole,
        agent: String,
    },
    InvocationFailed {
        role: AgentRole,
        agent: String,
        exit_code: i32,
        error_kind: AgentErrorKind,
        retriable: bool,
    },
    FallbackTriggered {
        role: AgentRole,
        from_agent: String,
        to_agent: String,
    },
    ModelFallbackTriggered {
        role: AgentRole,
        agent: String,
        from_model: String,
        to_model: String,
    },
    RetryCycleStarted {
        role: AgentRole,
        cycle: u32,
    },
    ChainExhausted {
        role: AgentRole,
    },
    ChainInitialized {
        role: AgentRole,
        agents: Vec<String>,
        max_cycles: u32,
        retry_delay_ms: u64,
        backoff_multiplier: f64,
        max_backoff_ms: u64,
    },
    RateLimited {
        role: AgentRole,
        agent: String,
        prompt_context: Option<String>,
    },
    AuthFailed {
        role: AgentRole,
        agent: String,
    },
    TimedOut {
        role: AgentRole,
        agent: String,
        output_kind: TimeoutOutputKind,
        logfile_path: Option<String>,
        child_status_at_timeout: Option<ChildProcessInfo>,
    },
    SessionEstablished {
        role: AgentRole,
        agent: String,
        session_id: String,
    },
    XsdValidationFailed {
        role: AgentRole,
        artifact: ArtifactType,
        error: String,
        retry_count: u32,
    },
    TemplateVariablesInvalid {
        role: AgentRole,
        template_name: String,
        missing_variables: Vec<String>,
        unresolved_placeholders: Vec<String>,
    },
    TimeoutContextWritten {
        role: AgentRole,
        logfile_path: String,
        context_path: String,
    },
}

Agent invocation and chain management events.

Events related to agent execution, fallback chains, model switching, rate limiting, and retry cycles. The agent chain provides fault tolerance through multiple fallback levels:

1. Model level: Try different models for the same agent
2. Agent level: Switch to a fallback agent
3. Retry cycle: Start over with exponential backoff

State Transitions

• InvocationFailed(retriable=true): Advances to next model
• InvocationFailed(retriable=false): Typically switches to next agent (policy may vary by kind)
• RateLimited: Typically immediate agent switch with prompt preservation
• ChainExhausted: Starts new retry cycle
• InvocationSucceeded: Clears continuation prompt

Variants

InvocationStarted

Agent invocation started.

Fields

role: AgentRole

The role this agent is fulfilling.

agent: String

The agent being invoked.

model: Option<String>

The model being used, if specified.

InvocationSucceeded

Agent invocation succeeded.

Fields

role: AgentRole

The role this agent fulfilled.

agent: String

The agent that succeeded.

InvocationFailed

Agent invocation failed.

Fields

role: AgentRole

The role this agent was fulfilling.

agent: String

The agent that failed.

exit_code: i32

The exit code from the agent process.

error_kind: AgentErrorKind

The kind of error that occurred.

retriable: bool

Whether this error is retriable with the same agent.

FallbackTriggered

Fallback triggered to switch to a different agent.

Fields

role: AgentRole

The role being fulfilled.

from_agent: String

The agent being switched from.

to_agent: String

The agent being switched to.

ModelFallbackTriggered

Model fallback triggered within the same agent.

Fields

role: AgentRole

The role being fulfilled.

agent: String

The agent whose model is changing.

from_model: String

The model being switched from.

to_model: String

The model being switched to.

RetryCycleStarted

Retry cycle started (all agents exhausted, starting over).

Fields

role: AgentRole

The role being retried.

cycle: u32

The cycle number starting.

ChainExhausted

Agent chain exhausted (no more agents/models to try).

Fields

role: AgentRole

The role whose chain is exhausted.

ChainInitialized

Agent chain initialized with available agents.

Fields

role: AgentRole

The role this chain is for.

agents: Vec<String>

The agents available in this chain.

max_cycles: u32

Maximum number of retry cycles allowed for this chain.

retry_delay_ms: u64

Base retry-cycle delay in milliseconds.

backoff_multiplier: f64

Exponential backoff multiplier.

max_backoff_ms: u64

Maximum backoff delay in milliseconds.

RateLimited

Agent hit rate limit (429).

Effects/executors emit this as a fact event. The reducer decides whether/when to switch agents.

Fields

role: AgentRole

The role being fulfilled.

agent: String

The agent that hit the rate limit.

prompt_context: Option<String>

The prompt that was being executed when rate limit was hit. This allows the next agent to continue the same work.

AuthFailed

Agent hit authentication failure (401/403).

Effects/executors emit this as a fact event. The reducer decides whether/when to switch agents.

Fields

role: AgentRole

The role being fulfilled.

agent: String

The agent that failed authentication.

TimedOut

Agent hit an idle timeout.

Emitted as a fact; the reducer decides retry vs fallback based on output_kind. NoOutput triggers immediate agent switch; PartialOutput uses the same-agent retry budget (same semantics as before this feature).

Fields

role: AgentRole

The role being fulfilled.

agent: String

The agent that timed out.

output_kind: TimeoutOutputKind

Whether the agent produced any output before timing out.

logfile_path: Option<String>

Path to the agent’s logfile (for context extraction on PartialOutput retry).

When output_kind is PartialOutput and the agent has no session ID, this path is used to extract context for the retry prompt.

child_status_at_timeout: Option<ChildProcessInfo>

Child process status when the timeout was enforced.

None if no children existed or child checking was disabled. When Some, contains the child count and cumulative CPU time at timeout.

SessionEstablished

Session established with agent.

Emitted when an agent response includes a session ID that can be used for XSD retry continuation. This enables reusing the same session when retrying due to validation failures.

Fields

role: AgentRole

The role this agent is fulfilling.

agent: String

The agent name.

session_id: String

The session ID returned by the agent.

XsdValidationFailed

XSD validation failed for agent output.

Emitted when agent output cannot be parsed or fails XSD validation. Distinct from OutputValidationFailed events in phase-specific enums, this is the canonical XSD retry trigger that the reducer uses to decide whether to retry with the same agent/session or advance the chain.

Fields

role: AgentRole

The role whose output failed validation.

artifact: ArtifactType

The artifact type that failed validation.

error: String

Error message from validation.

retry_count: u32

Current XSD retry count for this artifact.

TemplateVariablesInvalid

Template rendering failed due to missing required variables or unresolved placeholders.

Emitted when a prompt template cannot be rendered because required variables are missing or unresolved placeholders (e.g., {{VAR}}) remain in the output. The reducer decides fallback policy, typically switching to the next agent.

Fields

role: AgentRole

The role whose template failed to render.

template_name: String

The name of the template that failed.

missing_variables: Vec<String>

Variables that were required but not provided.

unresolved_placeholders: Vec<String>

Placeholder patterns that remain unresolved in the rendered output.

TimeoutContextWritten

Timeout context written to temp file for session-less agent retry.

Emitted when a timeout with meaningful output occurs but the agent doesn’t support session IDs. The prior context is extracted from the logfile and written to a temp file for the retry prompt to reference.

Fields

role: AgentRole

The role this agent is fulfilling.

logfile_path: String

Source logfile path the context was extracted from.

context_path: String

Target temp file path where context was written.

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.