Enum AgentEvent 

pub enum AgentEvent {
    InvocationStarted {
        role: AgentRole,
        agent: AgentName,
        model: Option<ModelName>,
    },
    InvocationSucceeded {
        role: AgentRole,
        agent: AgentName,
    },
    InvocationFailed {
        role: AgentRole,
        agent: AgentName,
        exit_code: i32,
        error_kind: AgentErrorKind,
        retriable: bool,
    },
    FallbackTriggered {
        role: AgentRole,
        from_agent: AgentName,
        to_agent: AgentName,
    },
    ModelFallbackTriggered {
        role: AgentRole,
        agent: AgentName,
        from_model: ModelName,
        to_model: ModelName,
    },
    RetryCycleStarted {
        role: AgentRole,
        cycle: u32,
    },
    ChainExhausted {
        role: AgentRole,
    },
    ChainInitialized {
        drain: AgentDrain,
        agents: Vec<AgentName>,
        models_per_agent: Vec<Vec<String>>,
        max_cycles: u32,
        retry_delay_ms: u64,
        backoff_multiplier: f64,
        max_backoff_ms: u64,
    },
    RateLimited {
        role: AgentRole,
        agent: AgentName,
        prompt_context: Option<String>,
    },
    AuthFailed {
        role: AgentRole,
        agent: AgentName,
    },
    TimedOut {
        role: AgentRole,
        agent: AgentName,
        output_kind: TimeoutOutputKind,
        logfile_path: Option<String>,
        child_status_at_timeout: Option<ChildProcessInfo>,
    },
    SessionEstablished {
        role: AgentRole,
        agent: AgentName,
        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,
    },
    ConnectivityCheckSucceeded,
    ConnectivityCheckFailed,
}

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

Compatibility role metadata for the active drain.

Runtime routing is drain-owned; reducers use explicit drain state as the authoritative consumer identity.

agent: AgentName

The agent being invoked.

model: Option<ModelName>

The model being used, if specified.

InvocationSucceeded

Agent invocation succeeded.

Fields

role: AgentRole

Compatibility role metadata for the active drain.

agent: AgentName

The agent that succeeded.

InvocationFailed

Agent invocation failed.

Fields

role: AgentRole

Compatibility role metadata for the active drain.

agent: AgentName

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: AgentName

The agent being switched from.

to_agent: AgentName

The agent being switched to.

ModelFallbackTriggered

Model fallback triggered within the same agent.

Fields

role: AgentRole

The role being fulfilled.

agent: AgentName

The agent whose model is changing.

from_model: ModelName

The model being switched from.

to_model: ModelName

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

drain: AgentDrain

The explicit runtime drain this chain is for.

agents: Vec<AgentName>

The agents available in this chain.

models_per_agent: Vec<Vec<String>>

Per-agent model flag lists, parallel to agents.

Each inner Vec contains model flags (e.g. ["-m opencode/glm-4.7-free"]) for the corresponding agent. An empty inner Vec means no model-level fallback for that agent (treated as a single-model agent).

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: AgentName

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: AgentName

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. NoResult triggers immediate agent switch; PartialResult uses the same-agent retry budget (same semantics as before this feature).

Fields

role: AgentRole

The role being fulfilled.

agent: AgentName

The agent that timed out.

output_kind: TimeoutOutputKind

Whether the agent produced a result file before timing out.

logfile_path: Option<String>

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

When output_kind is PartialResult 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: AgentName

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.

ConnectivityCheckSucceeded

Connectivity probe succeeded (network is reachable).

Emitted when a connectivity probe succeeds. The reducer processes this to update ConnectivityState accordingly. If the pipeline was waiting for connectivity verification, this clears that pending flag.

ConnectivityCheckFailed

Connectivity probe failed (network is unreachable).

Emitted when a connectivity probe fails. The reducer processes this to update ConnectivityState. If the failure threshold is reached, the pipeline enters offline mode.

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 PartialEq for AgentEvent

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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.

impl StructuralPartialEq for AgentEvent