Struct FallbackConfig 

pub struct FallbackConfig {
    pub developer: Vec<String>,
    pub reviewer: Vec<String>,
    pub commit: Vec<String>,
    pub provider_fallback: HashMap<String, Vec<String>>,
    pub max_retries: u32,
    pub retry_delay_ms: u64,
    pub backoff_multiplier: f64,
    pub max_backoff_ms: u64,
    pub max_cycles: u32,
}

Agent chain configuration for preferred agents and fallback switching.

The agent chain defines both:

1. The preferred agent (first in the list) for each role
2. The fallback agents (remaining in the list) to try if the preferred fails

This provides a unified way to configure which agents to use and in what order. Ralph automatically switches to the next agent in the chain when encountering errors like rate limits or auth failures.

Provider-Level Fallback

In addition to agent-level fallback, you can configure provider-level fallback within a single agent using the provider_fallback field. This is useful for agents like opencode that support multiple providers/models via the -m flag.

Example:

[agent_chain]
provider_fallback.opencode = ["-m opencode/glm-4.7-free", "-m opencode/claude-sonnet-4"]

Exponential Backoff and Cycling

When all fallbacks are exhausted, Ralph uses exponential backoff and cycles back to the first agent in the chain:

• Base delay starts at retry_delay_ms (default: 1000ms)
• Each cycle multiplies by backoff_multiplier (default: 2.0)
• Capped at max_backoff_ms (default: 60000ms = 1 minute)
• Maximum cycles controlled by max_cycles (default: 3)

Fields

developer: Vec<String>

Ordered list of agents for developer role (first = preferred, rest = fallbacks).

reviewer: Vec<String>

Ordered list of agents for reviewer role (first = preferred, rest = fallbacks).

commit: Vec<String>

Ordered list of agents for commit role (first = preferred, rest = fallbacks).

provider_fallback: HashMap<String, Vec<String>>

Provider-level fallback: maps agent name to list of model flags to try. Example: opencode = ["-m opencode/glm-4.7-free", "-m opencode/claude-sonnet-4"]

max_retries: u32

Maximum number of retries per agent before moving to next.

retry_delay_ms: u64

Base delay between retries in milliseconds.

backoff_multiplier: f64

Multiplier for exponential backoff (default: 2.0).

max_backoff_ms: u64

Maximum backoff delay in milliseconds (default: 60000 = 1 minute).

max_cycles: u32

Maximum number of cycles through all agents before giving up (default: 3).

Implementations

impl FallbackConfig

pub fn calculate_backoff(&self, cycle: u32) -> u64

Calculate exponential backoff delay for a given cycle.

Uses the formula: min(base * multiplier^cycle, max_backoff)

Uses integer arithmetic to avoid floating-point casting issues.

pub fn get_fallbacks(&self, role: AgentRole) -> &[String]

Get fallback agents for a role.

pub fn has_fallbacks(&self, role: AgentRole) -> bool

Check if fallback is configured for a role.

pub fn get_provider_fallbacks(&self, agent_name: &str) -> &[String]

Get provider-level fallback model flags for an agent.

Returns the list of model flags to try for the given agent name. Empty slice if no provider fallback is configured for this agent.

pub fn has_provider_fallbacks(&self, agent_name: &str) -> bool

Check if provider-level fallback is configured for an agent.

Trait Implementations

impl Clone for FallbackConfig

fn clone(&self) -> FallbackConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FallbackConfig

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

Formats the value using the given formatter.

impl Default for FallbackConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for FallbackConfig

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.