Struct AgentChainState 

pub struct AgentChainState {

    pub agents: Vec<String>,
    pub current_agent_index: usize,
    pub models_per_agent: Vec<Vec<String>>,
    pub current_model_index: usize,
    pub retry_cycle: u32,
    pub max_cycles: u32,
    pub retry_delay_ms: u64,
    pub backoff_multiplier: f64,
    pub max_backoff_ms: u64,
    pub backoff_pending_ms: Option<u64>,
    pub current_role: AgentRole,
    pub rate_limit_continuation_prompt: Option<RateLimitContinuationPrompt>,
    pub last_session_id: Option<String>,
}

Agent fallback chain state (explicit, not loop indices).

Tracks position in the multi-level fallback chain:

• Agent level (primary → fallback1 → fallback2)
• Model level (within each agent, try different models)
• Retry cycle (exhaust all agents, start over with exponential backoff)

Fields

agents: Vec<String>

current_agent_index: usize

models_per_agent: Vec<Vec<String>>

current_model_index: usize

retry_cycle: u32

max_cycles: u32

retry_delay_ms: u64

Base delay between retry cycles in milliseconds.

backoff_multiplier: f64

Multiplier for exponential backoff.

max_backoff_ms: u64

Maximum backoff delay in milliseconds.

backoff_pending_ms: Option<u64>

Pending backoff delay (milliseconds) that must be waited before continuing.

current_role: AgentRole

rate_limit_continuation_prompt: Option<RateLimitContinuationPrompt>

Prompt context preserved from a rate-limited agent for continuation.

When an agent hits 429, we save the prompt here so the next agent can continue the SAME role/task instead of starting from scratch.

IMPORTANT: This must be role-scoped to prevent cross-task contamination (e.g., a developer continuation prompt overriding an analysis prompt).

last_session_id: Option<String>

Session ID from the last agent response.

Used for XSD retry to continue with the same session when possible. Agents that support sessions (e.g., Claude Code) emit session IDs that can be passed back for continuation.

Implementations

impl AgentChainState

pub fn initial() -> Self

pub fn with_agents( self, agents: Vec<String>, models_per_agent: Vec<Vec<String>>, role: AgentRole, ) -> Self

pub fn with_max_cycles(self, max_cycles: u32) -> Self

Builder method to set the maximum number of retry cycles.

A retry cycle is when all agents have been exhausted and we start over with exponential backoff.

pub fn with_backoff_policy( self, retry_delay_ms: u64, backoff_multiplier: f64, max_backoff_ms: u64, ) -> Self

pub fn current_agent(&self) -> Option<&String>

pub fn consumer_signature_sha256(&self) -> String

Stable signature of the current consumer set (agents + configured models + role).

This is used to dedupe oversize materialization decisions across reducer retries. The signature is stable under:

• switching the current agent/model index
• retry cycles

It changes only when the configured consumer set changes.

pub fn current_model(&self) -> Option<&String>

Get the currently selected model for the current agent.

Returns None if:

• No models are configured
• The current agent index is out of bounds
• The current model index is out of bounds

pub fn is_exhausted(&self) -> bool

pub fn advance_to_next_model(&self) -> Self

pub fn switch_to_next_agent(&self) -> Self

pub fn switch_to_agent_named(&self, to_agent: &str) -> Self

Switch to a specific agent by name.

If to_agent is unknown, falls back to switch_to_next_agent() to keep the reducer deterministic.

pub fn switch_to_next_agent_with_prompt(&self, prompt: Option<String>) -> Self

Switch to next agent after rate limit, preserving prompt for continuation.

This is used when an agent hits a 429 rate limit error. Instead of retrying with the same agent (which would likely hit rate limits again), we switch to the next agent and preserve the prompt so the new agent can continue the same work.

pub fn switch_to_next_agent_with_prompt_for_role( &self, role: AgentRole, prompt: Option<String>, ) -> Self

Switch to next agent after rate limit, preserving prompt for continuation (role-scoped).

pub fn clear_continuation_prompt(&self) -> Self

Clear continuation prompt after successful execution.

Called when an agent successfully completes its task, clearing any saved prompt context from previous rate-limited agents.

pub fn reset_for_role(&self, role: AgentRole) -> Self

pub fn reset(&self) -> Self

pub fn with_session_id(&self, session_id: Option<String>) -> Self

Store session ID from agent response for potential reuse.

pub fn clear_session_id(&self) -> Self

Clear session ID (e.g., when switching agents or starting new work).

pub fn start_retry_cycle(&self) -> Self

pub fn clear_backoff_pending(&self) -> Self

Trait Implementations

impl Clone for AgentChainState

fn clone(&self) -> AgentChainState

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentChainState

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentChainState

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentChainState

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

where __S: Serializer,

Serialize this value into the given Serde serializer.