Struct AgentChainState 

pub struct AgentChainState {

    pub agents: Arc<[String]>,
    pub current_agent_index: usize,
    pub models_per_agent: Arc<[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 current_drain: AgentDrain,
    pub current_mode: DrainMode,
    pub rate_limit_continuation_prompt: Option<RateLimitContinuationPrompt>,
    pub last_session_id: Option<String>,
    pub last_failure_reason: 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)

Memory Optimization

Uses Arc<[T]> for agents and models_per_agent collections to enable cheap cloning during state transitions. Since these collections are immutable after construction, Arc::clone only increments a reference count instead of deep copying the entire collection.

Fields

agents: Arc<[String]>

Agent names in fallback order. Arc<String> enables cheap cloning via reference counting instead of deep copying the collection.

current_agent_index: usize

models_per_agent: Arc<[Vec<String>]>

Models per agent. Arc for immutable outer collection with cheap cloning. Inner Vec is kept for runtime indexing during model selection.

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

Compatibility copy of the broad capability role.

Runtime code should treat current_drain as authoritative and derive the active role from it. This field is retained for checkpoint compatibility and diagnostics only.

current_drain: AgentDrain

current_mode: DrainMode

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.

last_failure_reason: Option<String>

Last failure reason from the most recent agent failure.

Used to provide context in CLI output when a fallback agent is invoked. Cleared on InvocationSucceeded or ChainInitialized.

Implementations

impl AgentChainState

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_drain(&self, drain: AgentDrain) -> Self

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 with_failure_reason(&self, reason: Option<String>) -> Self

Store last failure reason for CLI output context.

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

impl AgentChainState

pub fn initial() -> Self

pub fn matches_runtime_drain(&self, runtime_drain: AgentDrain) -> bool

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

pub const fn with_drain(self, drain: AgentDrain) -> Self

pub const fn with_mode(self, mode: DrainMode) -> Self

pub const fn active_role(&self) -> AgentRole

pub const 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 const 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 + drain).

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 const fn is_exhausted(&self) -> bool

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.