switchyard_runner/

algorithm.rs

// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

//! Schema-neutral algorithm configuration and construction.

use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::error::Error;
use std::fmt::{Display, Formatter};
use std::path::PathBuf;
use std::sync::Arc;

use libsy::{
    AdvisorGate, AdvisorGateConfig, Algorithm, BreakerConfig, CapabilityJudgeConfig,
    ClassifierContractConfig, ClassifierResponseFormat, ClassifyTrigger, CompositeJudgeConfig,
    CompositeRouter, CustomClassifierConfig, CustomClassifierPolicy, DEFAULT_UNMATCHED_STEPS,
    DecisionChoice, DecisionJudgeConfig, DirectClassifierConfig, EscalationJudgeConfig,
    GateTrigger, HandoffNoteConfig, LlmCapabilityConfig, LlmClassifierConfig, LlmFallback,
    LlmTaskClassifier, Noop, Passthrough, PickerMode, Random, RuntimeModels, StageRouter,
    StageRouterConfig, SubagentRouter, SubagentRouterConfig, TaskClassifierConfig, ToolSemantics,
    Vgr, VgrConfig,
};
use serde::Deserialize;
use strum_macros::IntoStaticStr;
use switchyard_protocol::{Category, ModelId};

/// Error returned when an algorithm description cannot be constructed.
#[derive(Debug)]
pub struct AlgorithmConfigError {
    message: String,
    source: Option<Box<dyn Error + Send + Sync>>,
}

impl AlgorithmConfigError {
    fn new(message: impl Into<String>) -> Self {
        Self {
            message: message.into(),
            source: None,
        }
    }

    fn with_source(message: impl Into<String>, source: impl Error + Send + Sync + 'static) -> Self {
        Self {
            message: message.into(),
            source: Some(Box::new(source)),
        }
    }
}

impl Display for AlgorithmConfigError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(&self.message)
    }
}

impl Error for AlgorithmConfigError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        self.source.as_deref().map(|source| source as _)
    }
}

type AlgorithmResult<T> = Result<T, AlgorithmConfigError>;

/// How a custom classifier turns the judge's JSON verdict into a target.
#[derive(Clone, Debug, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum ClassifierPolicyConfig {
    /// Reads the target name straight out of the judge's verdict.
    TargetSelector {
        /// JSON Pointer to the name, such as `/decision/target`.
        selector: String,
    },
}

/// Which of the four `llm_classifier` behaviors a route uses.
#[derive(Clone, Copy, Debug, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ClassifierMode {
    /// Judges the request first, then serves the strong or weak target.
    Capability,
    /// Serves the weak target first and judges the finished turn, moving to the
    /// strong target once the session latches.
    Escalation,
    /// Judges against your own JSON schema and routes to any configured target.
    Custom,
    /// Asks a decision target to select one configured model group.
    Direct,
}

impl ClassifierPolicyConfig {
    fn into_libsy(self) -> CustomClassifierPolicy {
        match self {
            Self::TargetSelector { selector } => CustomClassifierPolicy::target_selector(selector),
        }
    }
}

#[derive(Clone, Debug)]
enum LlmClassifierModeConfig {
    Capability(CapabilityClassifierRouteConfig),
    Escalation(EscalationClassifierRouteConfig),
    Custom(CustomClassifierRouteConfig),
    Direct {
        models: CategoryModelConfig,
        default_target: Category,
        config: DirectClassifierConfig,
    },
}

#[derive(Clone, Debug)]
struct CapabilityClassifierRouteConfig {
    classifier_target: String,
    fail_open: bool,
    strong_target: String,
    weak_target: String,
    judge: CapabilityJudgeRouteConfig,
    classify_trigger: ClassifyTrigger,
    message_hash_fallback: bool,
    recent_turn_window: Option<usize>,
}

impl CapabilityClassifierRouteConfig {
    fn into_task_config(self) -> TaskClassifierConfig {
        let judge = match self.judge {
            CapabilityJudgeRouteConfig::Llm(judge) => CapabilityJudgeConfig::Llm(judge),
            CapabilityJudgeRouteConfig::Decision(judge) => {
                let defaults = DecisionJudgeConfig::default();
                CapabilityJudgeConfig::Decision(DecisionJudgeConfig {
                    cutoff: judge.cutoff,
                    instructions: judge.instructions,
                    choices: judge.choices.unwrap_or(defaults.choices),
                    apply_cutoff_to: judge.apply_cutoff_to.unwrap_or(defaults.apply_cutoff_to),
                })
            }
        };
        TaskClassifierConfig {
            judge,
            fail_open: self.fail_open,
            classify_trigger: self.classify_trigger,
            message_hash_fallback: self.message_hash_fallback,
            recent_turn_window: self.recent_turn_window,
        }
    }
}

#[derive(Clone, Debug)]
enum CapabilityJudgeRouteConfig {
    Llm(LlmCapabilityConfig),
    Decision(DecisionJudgeRouteConfig),
}

#[derive(Clone, Debug)]
struct EscalationClassifierRouteConfig {
    classifier_target: String,
    strong_target: String,
    weak_target: String,
    prompt: Option<String>,
    response_format_type: ClassifierResponseFormat,
    max_output_tokens: u64,
    judge_deadline_ms: Option<u64>,
    judge: EscalationJudgeConfig,
}

#[derive(Clone, Debug)]
struct CustomClassifierRouteConfig {
    models: CategoryModelConfig,
    default_target: Category,
    prompt: String,
    response_schema: String,
    policy: ClassifierPolicyConfig,
    classify_trigger: ClassifyTrigger,
    message_hash_fallback: bool,
    recent_turn_window: Option<usize>,
    max_output_tokens: u64,
    judge_deadline_ms: Option<u64>,
}

/// Runtime model groups for a custom classifier, keyed by group name.
///
/// `any` and `judge` are required; `capable` and `efficient` carry tier meaning
/// when present. Any other key is a deployment-defined group the policy may
/// select by name, which is what lets one route choose between more than two
/// models. Ordered so error messages and derived target lists do not depend on
/// hash iteration.
#[derive(Clone, Debug, Default, Deserialize)]
#[serde(transparent)]
pub struct CategoryModelConfig(BTreeMap<String, Vec<String>>);

impl CategoryModelConfig {
    fn restrict_to(&mut self, allowed: &BTreeSet<&str>) {
        for models in self.0.values_mut() {
            models.retain(|model| allowed.contains(model.as_str()));
        }
    }

    fn validate(&self, route_name: &str, default_target: &Category) -> AlgorithmResult<()> {
        for category in [Category::Any, Category::Judge] {
            if self.get(&category).is_empty() {
                return Err(AlgorithmConfigError::new(format!(
                    "llm_classifier route {route_name} models.{} must contain at least one target",
                    category.as_str()
                )));
            }
        }
        if self.get(default_target).is_empty() {
            return Err(AlgorithmConfigError::new(format!(
                "llm_classifier route {route_name} models.{} must contain at least one target because it is the default_target",
                default_target.as_str()
            )));
        }
        // Every group name parses, so a typo would otherwise build fine and then
        // abstain on every request. `any` is the fallback pool the router checks
        // the selected target against, so a group outside it can never be served.
        let any = self.get(&Category::Any);
        for (name, models) in &self.0 {
            if name == Category::Judge.as_str() || name == Category::Any.as_str() {
                continue;
            }
            if let Some(missing) = models.iter().find(|model| !any.contains(model)) {
                return Err(AlgorithmConfigError::new(format!(
                    "llm_classifier route {route_name} models.{name} lists target {missing}, which must also appear in models.any"
                )));
            }
        }
        Ok(())
    }

    fn get(&self, category: &Category) -> &[String] {
        self.0.get(category.as_str()).map_or(&[], Vec::as_slice)
    }

    /// Every configured target name, judge included.
    fn all_names(&self) -> Vec<&str> {
        Self::deduped(self.0.values().flatten())
    }

    /// The completion targets: every group except the judge's own candidates.
    ///
    /// `any` leads because it is the deployment's stated fallback order, and
    /// callers read this order to pick a route's representative target.
    fn routing_names(&self) -> Vec<&str> {
        let others = self
            .0
            .iter()
            .filter(|(name, _)| {
                *name != Category::Judge.as_str() && *name != Category::Any.as_str()
            })
            .flat_map(|(_, models)| models);
        Self::deduped(self.get(&Category::Any).iter().chain(others))
    }

    fn deduped<'a>(names: impl Iterator<Item = &'a String>) -> Vec<&'a str> {
        let mut seen = BTreeSet::new();
        names
            .map(String::as_str)
            .filter(|name| seen.insert(*name))
            .collect()
    }

    fn groups(&self) -> impl Iterator<Item = (Category, Vec<String>)> + '_ {
        self.0
            .iter()
            .filter_map(|(name, models)| Some((name.parse::<Category>().ok()?, models.clone())))
    }
}

/// Routing by a decision model's choice probability.
#[derive(Clone, Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DecisionJudgeRouteConfig {
    /// Route capable when the `apply_cutoff_to` probability is strictly above
    /// this cutoff. Uses the library default when omitted.
    pub cutoff: Option<f64>,
    /// Replaces the default decision instructions.
    pub instructions: Option<String>,
    /// Replaces the default `capable` and `efficient` choices.
    pub choices: Option<Vec<DecisionChoice>>,
    /// Choice ID whose probability is compared with the cutoff. Defaults to `capable`.
    pub apply_cutoff_to: Option<String>,
}

/// Settings for an `llm_classifier` route. Which fields are required depends on
/// the [`ClassifierMode`]; using a field from the wrong mode is an error.
#[derive(Clone, Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct LlmClassifierRouteConfig {
    /// Target the judge is called through. Never a routing destination itself.
    pub classifier_target: String,
    /// Mode to run. Defaults to escalation when `escalation` is set, otherwise capability.
    pub mode: Option<ClassifierMode>,
    /// Capability and escalation modes: the capable tier.
    pub strong_target: Option<String>,
    /// Capability and escalation modes: the efficient tier.
    pub weak_target: Option<String>,
    /// Capability mode: lowest solve probability that still routes to the weak
    /// target, from 0 to 1.
    pub base_threshold: Option<f64>,
    /// Capability mode: how much to raise the threshold when the judge is
    /// uncertain. Added once for an uncertain verdict and twice for unsupported.
    pub threshold_step: Option<f64>,
    /// Capability mode: threshold steps for an unmatched verdict (no capability rule
    /// applies). 1 by default, the same as uncertain; 2 treats it like unsupported.
    pub unmatched_steps: Option<u8>,
    /// Capability and direct modes: routes to the capable tier or `default_target` when
    /// the judge call fails. Defaults to true in these modes.
    pub fail_open: Option<bool>,
    /// How often the judge runs: every request, once per user turn, or once per session.
    pub classify_trigger: ClassifyTrigger,
    /// Reuses the session's target by hashing the first user message when no
    /// session ID is available. Needs `classify_trigger = "new_session"`.
    pub message_hash_fallback: bool,
    /// How many trailing turns the judge sees. Unset shows it the opening task
    /// and the latest user follow-up only.
    pub recent_turn_window: Option<usize>,
    /// Replaces the packaged judge prompt. Required in custom mode.
    pub prompt: Option<String>,
    /// How the judge is asked for structured output. Use `json_object` when the
    /// provider cannot do JSON Schema.
    pub response_format_type: ClassifierResponseFormat,
    /// Most completion tokens the judge verdict may use.
    #[serde(default = "default_classifier_max_output_tokens")]
    pub max_output_tokens: u64,
    /// Whole-consultation bound on the judge call in milliseconds; expiry follows the
    /// route's `fail_open` setting. Unset leaves the consultation unbounded.
    #[serde(default)]
    pub judge_deadline_ms: Option<u64>,
    /// Escalation mode: how many escalate verdicts latch the session, and how
    /// much of the transcript the judge sees.
    pub escalation: Option<EscalationJudgeConfig>,
    /// Capability mode: use a decision target as the judge, with a capable-or-efficient choice.
    pub decision: Option<DecisionJudgeRouteConfig>,
    /// Custom and direct modes: runtime model groups. In direct mode, every non-empty
    /// group except `judge` and `any` is an option the decision target may select.
    pub models: Option<CategoryModelConfig>,
    /// Custom and direct modes: category used when the judge fails or its verdict
    /// cannot be routed.
    pub default_target: Option<String>,
    /// Custom mode: JSON Schema the verdict must match, written as a string.
    pub response_schema: Option<String>,
    /// Custom mode: how to read the chosen target out of the verdict.
    pub policy: Option<ClassifierPolicyConfig>,
}

/// Routing policy applied only to delegated sub-agent work, nested inside a
/// `passthrough` or `stage_router` route.
#[derive(Clone, Debug, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum SubagentRouteConfig {
    /// Sends all sub-agent work to one target.
    Passthrough {
        /// Target that serves sub-agent requests.
        target: String,
    },
    /// Judges each sub-agent request. Only [`ClassifierMode::Custom`] is supported here.
    LlmClassifier(Box<LlmClassifierRouteConfig>),
}

impl SubagentRouteConfig {
    fn routing_target_names(&self) -> Vec<&str> {
        match self {
            Self::Passthrough { target } => vec![target],
            Self::LlmClassifier(classifier) => classifier
                .models
                .as_ref()
                .map(CategoryModelConfig::routing_names)
                .unwrap_or_default(),
        }
    }

    fn judge_target_names(&self) -> Vec<&str> {
        match self {
            Self::Passthrough { .. } => Vec::new(),
            Self::LlmClassifier(classifier) => classifier
                .models
                .as_ref()
                .map(|models| models.get(&Category::Judge))
                .unwrap_or_default()
                .iter()
                .map(String::as_str)
                .collect(),
        }
    }
}

/// A routing algorithm described by configured target names. Converting it to `&str` gives
/// the route's `type`, such as `stage_router`.
#[derive(Clone, Debug, Deserialize, IntoStaticStr)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
#[strum(serialize_all = "snake_case")]
pub enum AlgorithmSpec {
    /// Replies `OK` without calling any model. Useful for smoke tests.
    Noop {},
    /// Splits traffic across several targets.
    Random {
        /// Target names to choose from.
        targets: Vec<String>,
        /// Relative weights in `targets` order. Equal weights when unset.
        weights: Option<Vec<f64>>,
        /// Makes the sequence of choices repeatable.
        seed: Option<u64>,
    },
    /// Sends every request to one target.
    Passthrough {
        /// Target that serves the request.
        target: String,
        /// Separate policy for delegated sub-agent work.
        #[serde(default)]
        subagents: Option<SubagentRouteConfig>,
    },
    /// Asks a judge model which target should serve the request.
    LlmClassifier {
        /// Judge and tier settings, written directly in the route table.
        #[serde(flatten)]
        config: LlmClassifierRouteConfig,
    },
    /// Picks a tier per turn by scoring signals from recent tool results.
    StageRouter {
        capable_target: String,
        efficient_target: String,
        #[serde(default)]
        capable_first_threshold: f64,
        #[serde(flatten)]
        settings: StageSettingsConfig,
        /// Tier to use when the signals are not confident.
        picker: PickerMode,
        /// Judge consulted for turns the tool signals cannot decide.
        #[serde(default)]
        classifier: Option<StageClassifierConfig>,
        /// Separate policy for delegated sub-agent work.
        #[serde(default)]
        subagents: Option<SubagentRouteConfig>,
    },
    /// Picks a routing strategy automatically, preset with recommended knobs.
    /// Currently a `stage_router` with `picker = "efficient_first"` and
    /// `confidence_threshold = 0.5`; change `build_algorithm`'s `Auto` arm to
    /// repoint it at a different algorithm or preset.
    Auto {
        /// The capable tier.
        capable_target: String,
        /// The efficient tier.
        efficient_target: String,
    },
    /// A judge picks the tier at each user turn; a stage router runs the turns within it.
    Composite {
        /// Judge that picks the tier. Called through its own target.
        classifier: StageClassifierConfig,
        /// The stage router the judge hands off to.
        stage: StageTierConfig,
        /// Settings for the profile selected by an efficient verdict.
        #[serde(default)]
        efficient: Option<Box<StageProfileConfig>>,
        /// Settings for the profile selected by a capable verdict.
        #[serde(default)]
        capable: Option<Box<StageProfileConfig>>,
        /// Separate policy for delegated sub-agent work.
        #[serde(default)]
        subagents: Option<SubagentRouteConfig>,
    },
    /// Serves every turn from one target, and has a second model review some of
    /// those turns before the caller sees them.
    Advisor {
        /// Serves every client-visible turn.
        executor_target: String,
        /// Reviews gated turns. Never a routing destination.
        advisor_target: String,
        /// Replaces the built-in APPROVE/REDO reviewer prompt.
        #[serde(default)]
        reviewer_system_prompt: Option<String>,
        /// Replaces the built-in text put in front of a REDO plan.
        #[serde(default)]
        redo_feedback_prefix: Option<String>,
        /// What fires a review.
        #[serde(default)]
        gate_trigger: AdvisorTriggerConfig,
        /// Regular expression for the `pattern` trigger. Required by it, and unused otherwise.
        #[serde(default)]
        gate_trigger_pattern: Option<String>,
        /// How many reviews one session may spend.
        #[serde(default = "default_max_reviews")]
        max_reviews: u32,
        /// Reviews a turn after this many assistant turns, as a mid-task
        /// checkpoint. Zero turns the checkpoint off.
        #[serde(default)]
        gate_stall_turns: u32,
        /// Tool results a turn needs before it can be reviewed. Skips early chatty turns.
        #[serde(default)]
        gate_min_tool_results: u32,
        /// Most output tokens one review may use.
        #[serde(default = "default_advisor_max_tokens")]
        advisor_max_tokens: u64,
        /// Sampling temperature for reviews. Left off the request when unset.
        #[serde(default)]
        advisor_temperature: Option<f64>,
        /// Size cap on the transcript sent to the advisor. Longer transcripts
        /// are trimmed from the middle.
        #[serde(default = "default_transcript_max_chars")]
        transcript_max_chars: usize,
        /// Lets the turn through when the advisor fails, instead of erroring.
        #[serde(default = "default_fail_open")]
        fail_open: bool,
    },
    Vgr {
        #[serde(flatten)]
        config: VgrRouteConfig,
    },
    /// Routes using a checkpoint-backed prefill classifier.
    PrefillRouter {
        /// Target names in checkpoint output order.
        targets: Vec<String>,
        /// Tensor-only router checkpoint path.
        checkpoint: PathBuf,
        /// PyTorch device used for encoder inference, such as `cpu`, `cuda`, or
        /// `cuda:0`. Auto-detected when omitted.
        device: Option<String>,
        /// Directory where Hugging Face caches the downloaded encoder and tokenizer.
        cache_dir: Option<PathBuf>,
        /// Maximum tokenized encoder input length; longer prompts are truncated.
        max_length: Option<usize>,
        /// Maximum prompts per encoder forward pass.
        batch_size: Option<usize>,
    },
}

#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct VgrRouteConfig {
    pub efficient_target: String,
    pub capable_target: String,
    /// Defaults to `efficient_target`.
    #[serde(default)]
    pub judge_target: Option<String>,
    #[serde(default)]
    pub capable_judge_target: Option<String>,
    #[serde(default)]
    pub mode: VgrModeConfig,
    #[serde(default)]
    pub active_approval: Option<String>,
    #[serde(default = "default_vgr_deadline")]
    pub deadline_seconds: f64,
    /// Enforces VGR decision and efficient turn budgets. Defaults to true.
    #[serde(default = "default_true")]
    pub bounded_efficient: bool,
    #[serde(default = "default_true")]
    pub task_typing: bool,
    #[serde(default = "default_vgr_breaker_threshold")]
    pub breaker_threshold: u32,
    #[serde(default = "default_vgr_breaker_cooldown")]
    pub breaker_cooldown_seconds: f64,
    /// Clean trailing tool results that let a long run recover on the capable judge.
    #[serde(default)]
    pub confirmed_recovery_min_clean_tail: Option<u32>,
    /// Tells the capable tier it inherits unverified tool-using work.
    #[serde(default)]
    pub agentic_handoff: bool,
    /// Condenses history from the efficient tier at handoff. Requires `agentic_handoff`.
    #[serde(default)]
    pub compact_handoff: bool,
    /// Wall-clock budget for the efficient tier within one user turn.
    #[serde(default)]
    pub efficient_turn_budget_seconds: Option<f64>,
    /// Holds escalations across later user turns.
    #[serde(default)]
    pub latch_escalation: bool,
}

#[derive(Clone, Debug, Default, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum VgrModeConfig {
    #[default]
    Off,
    Evaluate,
    Shadow,
    Active,
}

/// What fires an advisor route's review.
#[derive(Clone, Debug, Default, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum AdvisorTriggerConfig {
    /// The executor's first turn without tool calls.
    #[default]
    NoToolCall,
    /// The first turn whose text matches `gate_trigger_pattern`.
    Pattern,
}

/// The judge a `stage_router` route falls through to, and how it routes.
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StageClassifierConfig {
    /// Target the judge is called through. Not a routing destination.
    pub target: String,
    /// Composite accepts custom-schema judges as well as capability judges.
    #[serde(default)]
    pub mode: Option<ClassifierMode>,
    #[serde(default)]
    pub response_schema: Option<String>,
    #[serde(default)]
    pub policy: Option<ClassifierPolicyConfig>,
    #[serde(default)]
    pub decision: Option<DecisionJudgeRouteConfig>,
    #[serde(default)]
    pub fail_open: Option<bool>,
    /// Lowest solve probability that still routes to the efficient tier, from 0 to 1.
    pub base_threshold: Option<f64>,
    /// How much to raise the threshold when the judge is uncertain. Added once
    /// for an uncertain verdict and twice for unsupported.
    #[serde(default)]
    pub threshold_step: Option<f64>,
    /// How often the judge runs. Composite honors it. A standalone stage route
    /// rejects any value other than `every_request`, because its fallback judge
    /// runs on every ambiguous turn and retains no verdict.
    #[serde(default)]
    pub classify_trigger: ClassifyTrigger,
    /// Reuses the session's target by hashing the first user message when no
    /// session ID is available.
    #[serde(default)]
    pub message_hash_fallback: bool,
    /// How many trailing turns the judge sees. Unset shows it the opening task
    /// and the latest user follow-up only.
    #[serde(default)]
    pub recent_turn_window: Option<usize>,
    /// Replaces the packaged judge prompt.
    #[serde(default)]
    pub prompt: Option<String>,
    /// How the judge is asked for structured output. Use `json_object` when the
    /// provider cannot do JSON Schema.
    #[serde(default)]
    pub response_format_type: ClassifierResponseFormat,
    /// Most completion tokens the judge verdict may use.
    #[serde(default = "default_classifier_max_output_tokens")]
    pub max_output_tokens: u64,
    /// Whole-consultation bound on the judge call in milliseconds; expiry follows the
    /// route's `fail_open` setting. Unset leaves the consultation unbounded.
    #[serde(default)]
    pub judge_deadline_ms: Option<u64>,
}

const COMPOSITE_PLANNING_PROMPT: &str = "You are in the planning phase. Inspect the task and the relevant code, then form a concrete implementation plan before modifying any files. Use read-only tools as needed. Do not make an edit until the plan is complete. After completing the plan, immediately make the first edit in the same task to hand execution off. Do not finish or return a final response with only the plan.";

/// The shared model pair and defaults for composite stage profiles.
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StageTierConfig {
    pub capable_target: String,
    pub efficient_target: String,
    #[serde(default)]
    pub capable_first_threshold: f64,
    #[serde(flatten)]
    pub settings: StageSettingsConfig,
}

/// Settings shared by standalone stage routes and composite profiles.
#[derive(Clone, Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct StageSettingsConfig {
    #[serde(alias = "efficient_first_threshold")]
    pub confidence_threshold: Option<f64>,
    pub recent_turn_window: Option<usize>,
    pub tool_semantics: Option<ToolSemantics>,
    pub capable_hold_turns: Option<i64>,
    pub efficient_hold_turns: Option<i64>,
    pub handoff_notes: Option<HandoffNoteConfig>,
    pub capable_system_prompt: Option<String>,
    pub efficient_system_prompt: Option<String>,
}

#[derive(Clone, Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StageProfileConfig {
    pub classifier: Option<StageClassifierConfig>,
    pub picker: Option<PickerMode>,
    #[serde(flatten)]
    pub settings: StageSettingsConfig,
}

impl StageSettingsConfig {
    fn stage_config(&self, shared: &Self, mode: PickerMode, threshold: f64) -> StageRouterConfig {
        let mut config =
            StageRouterConfig::new(mode, self.confidence_threshold.unwrap_or(threshold));
        config.recent_window = self.recent_turn_window.or(shared.recent_turn_window);
        config.tool_semantics = self
            .tool_semantics
            .as_ref()
            .or(shared.tool_semantics.as_ref())
            .cloned()
            .unwrap_or_default();
        config.capable_hold_turns = self
            .capable_hold_turns
            .or(shared.capable_hold_turns)
            .unwrap_or(2);
        config.efficient_hold_turns = self.efficient_hold_turns.or(shared.efficient_hold_turns);
        config.handoff_notes = self
            .handoff_notes
            .as_ref()
            .or(shared.handoff_notes.as_ref())
            .cloned();
        config.capable_system_prompt = self
            .capable_system_prompt
            .as_ref()
            .or(shared.capable_system_prompt.as_ref())
            .cloned();
        config.efficient_system_prompt = self
            .efficient_system_prompt
            .as_ref()
            .or(shared.efficient_system_prompt.as_ref())
            .cloned();
        config
    }
}

impl StageTierConfig {
    fn profile_config(
        &self,
        profile: &StageProfileConfig,
        picker: PickerMode,
    ) -> StageRouterConfig {
        let threshold = match picker {
            PickerMode::EfficientFirst => self.settings.confidence_threshold.unwrap_or(0.4),
            PickerMode::CapableFirst => self.capable_first_threshold,
        };
        let mode = profile.picker.unwrap_or(picker);
        let capable_first = mode == PickerMode::CapableFirst;
        let mut config = profile
            .settings
            .stage_config(&self.settings, mode, threshold);
        config.recent_window.get_or_insert(3);
        config.capable_hold_turns = profile
            .settings
            .capable_hold_turns
            .or(self.settings.capable_hold_turns)
            .unwrap_or(if capable_first { 0 } else { 2 });
        config
            .efficient_hold_turns
            .get_or_insert(if capable_first { -1 } else { 0 });
        if capable_first {
            config
                .capable_system_prompt
                .get_or_insert_with(|| COMPOSITE_PLANNING_PROMPT.into());
        }
        config
    }

    /// Warns when both tiers name one target; see [`warn_identical_tiers`].
    fn warn_identical_tiers(&self, route_name: &str) {
        warn_identical_tiers(route_name, &self.capable_target, &self.efficient_target);
    }
}

impl StageClassifierConfig {
    fn composite_judge_config(
        &self,
        route_name: &str,
        capable: &str,
        efficient: &str,
    ) -> AlgorithmResult<CompositeJudgeConfig> {
        if matches!(self.mode, Some(ClassifierMode::Custom)) {
            return Ok(CompositeJudgeConfig::Custom(
                self.custom_classifier_config(route_name)?,
            ));
        }
        let mut config = self.task_classifier_config(route_name, capable, efficient)?;
        if let CapabilityJudgeConfig::Decision(judge) = &mut config.judge {
            judge.cutoff.get_or_insert(0.92);
        }
        Ok(CompositeJudgeConfig::Capability(config))
    }

    fn task_classifier_config(
        &self,
        route_name: &str,
        capable_target: &str,
        efficient_target: &str,
    ) -> AlgorithmResult<TaskClassifierConfig> {
        if self
            .mode
            .is_some_and(|mode| !matches!(mode, ClassifierMode::Capability))
            || self.response_schema.is_some()
            || self.policy.is_some()
        {
            return Err(AlgorithmConfigError::new(
                "custom classifier settings require composite with mode = custom",
            ));
        }
        let config = LlmClassifierRouteConfig {
            classifier_target: self.target.clone(),
            strong_target: Some(capable_target.to_string()),
            weak_target: Some(efficient_target.to_string()),
            base_threshold: self.base_threshold,
            threshold_step: self.threshold_step,
            fail_open: self.fail_open,
            decision: self.decision.clone(),
            classify_trigger: self.classify_trigger,
            message_hash_fallback: self.message_hash_fallback,
            recent_turn_window: self.recent_turn_window,
            prompt: self.prompt.clone(),
            response_format_type: self.response_format_type,
            max_output_tokens: self.max_output_tokens,
            judge_deadline_ms: self.judge_deadline_ms,
            ..Default::default()
        };
        match config.validated_classifier_mode(route_name)? {
            LlmClassifierModeConfig::Capability(config) => Ok(config.into_task_config()),
            _ => Err(AlgorithmConfigError::new("expected a capability judge")),
        }
    }

    fn infer_decision(
        &mut self,
        infer: &mut impl FnMut(&str, &mut Option<DecisionJudgeRouteConfig>),
    ) {
        if matches!(self.mode, None | Some(ClassifierMode::Capability)) {
            infer(&self.target, &mut self.decision);
        }
    }

    fn stage_fallback(
        &self,
        route_name: &str,
        capable: &str,
        efficient: &str,
        targets: &BTreeMap<String, ModelId>,
    ) -> AlgorithmResult<LlmFallback> {
        Ok(LlmFallback {
            target: Some(resolve_target_model_id(route_name, &self.target, targets)?),
            config: self.task_classifier_config(route_name, capable, efficient)?,
        })
    }

    fn custom_classifier_config(
        &self,
        route_name: &str,
    ) -> AlgorithmResult<CustomClassifierConfig> {
        if self.fail_open == Some(false) {
            return Err(AlgorithmConfigError::new(
                "composite custom classifiers always fail open; remove fail_open = false",
            ));
        }
        if self.decision.is_some()
            || self.base_threshold.is_some()
            || self.threshold_step.is_some()
            || self.response_format_type != ClassifierResponseFormat::JsonSchema
        {
            return Err(AlgorithmConfigError::new(
                "composite custom classifier cannot use capability thresholds, decision settings, or response_format_type",
            ));
        }
        let schema =
            required_classifier_field(route_name, "response_schema", &self.response_schema)?;
        let schema = serde_json::from_str(&schema).map_err(|error| {
            AlgorithmConfigError::with_source(
                format!("composite route {route_name}: response_schema is invalid JSON"),
                error,
            )
        })?;
        let mut config = CustomClassifierConfig::new(
            required_classifier_field(route_name, "prompt", &self.prompt)?,
            schema,
            required_classifier_field(route_name, "policy", &self.policy)?.into_libsy(),
        );
        config.classify_trigger = self.classify_trigger;
        config.message_hash_fallback = self.message_hash_fallback;
        config.recent_turn_window = self.recent_turn_window;
        config.max_output_tokens = self.max_output_tokens;
        Ok(config)
    }
}

impl AlgorithmSpec {
    /// Filters configured pools without replacing required targets or changing their roles.
    pub(crate) fn restricted_to(&self, allowed: &BTreeSet<&str>) -> AlgorithmResult<Self> {
        let mut restricted = self.clone();
        match &mut restricted {
            Self::Random {
                targets, weights, ..
            } => {
                if let Some(weights) = weights {
                    if weights.len() != targets.len() {
                        return Err(AlgorithmConfigError::new(format!(
                            "random expected {} weights, got {}",
                            targets.len(),
                            weights.len()
                        )));
                    }
                    // Keep weight positions paired with the original target order.
                    let mut index = 0;
                    weights.retain(|_| {
                        let keep = allowed.contains(targets[index].as_str());
                        index += 1;
                        keep
                    });
                }
                targets.retain(|target| allowed.contains(target.as_str()));
                if targets.is_empty() {
                    return Err(AlgorithmConfigError::new(
                        "target requirements leave random without an eligible target".to_string(),
                    ));
                }
            }
            Self::LlmClassifier { config } => {
                if let Some(models) = &mut config.models {
                    models.restrict_to(allowed);
                }
            }
            _ => {}
        }
        let subagents = match &mut restricted {
            Self::Passthrough { subagents, .. }
            | Self::StageRouter { subagents, .. }
            | Self::Composite { subagents, .. } => subagents.as_mut(),
            _ => None,
        };
        if let Some(SubagentRouteConfig::LlmClassifier(config)) = subagents
            && let Some(models) = &mut config.models
        {
            models.restrict_to(allowed);
        }
        if let Some(target) = restricted
            .callable_target_names()
            .into_iter()
            .find(|target| !allowed.contains(target))
        {
            return Err(AlgorithmConfigError::new(format!(
                "required target {target} does not satisfy target requirements"
            )));
        }
        Ok(restricted)
    }

    pub(crate) const fn supports_target_restrictions(&self) -> bool {
        !matches!(self, Self::PrefillRouter { .. })
    }

    /// This iterator yields tier classifier targets and their optional decision settings.
    /// It includes classifiers in nested Composite profiles.
    /// Standalone custom and direct modes use model groups and are excluded.
    pub(crate) fn classifier_targets(
        &self,
    ) -> impl Iterator<Item = (&str, Option<&DecisionJudgeRouteConfig>)> {
        let (primary, profiles) = match self {
            Self::LlmClassifier { config, .. }
                if !matches!(
                    config.classifier_mode(),
                    ClassifierMode::Custom | ClassifierMode::Direct
                ) =>
            {
                (
                    Some((config.classifier_target.as_str(), config.decision.as_ref())),
                    [None, None],
                )
            }
            Self::Composite {
                classifier,
                efficient,
                capable,
                ..
            } => (
                Some((classifier.target.as_str(), classifier.decision.as_ref())),
                [efficient.as_deref(), capable.as_deref()],
            ),
            Self::StageRouter { classifier, .. } => (
                classifier
                    .as_ref()
                    .map(|c| (c.target.as_str(), c.decision.as_ref())),
                [None, None],
            ),
            _ => (None, [None, None]),
        };
        primary.into_iter().chain(
            profiles
                .into_iter()
                .flatten()
                .filter_map(|profile| profile.classifier.as_ref())
                .map(|c| (c.target.as_str(), c.decision.as_ref())),
        )
    }

    /// Gives capability judges default decision settings when their target is a decision target.
    pub(crate) fn infer_decision_judges(&mut self, is_decision_target: impl Fn(&str) -> bool) {
        let mut infer = |target: &str, decision: &mut Option<DecisionJudgeRouteConfig>| {
            if is_decision_target(target) {
                decision.get_or_insert_with(Default::default);
            }
        };
        match self {
            Self::LlmClassifier { config }
                if matches!(config.classifier_mode(), ClassifierMode::Capability) =>
            {
                infer(&config.classifier_target, &mut config.decision);
            }
            Self::StageRouter {
                classifier: Some(classifier),
                ..
            } => classifier.infer_decision(&mut infer),
            Self::Composite {
                classifier,
                efficient,
                capable,
                ..
            } => {
                classifier.infer_decision(&mut infer);
                for profile in [efficient, capable].into_iter().flatten() {
                    if let Some(classifier) = &mut profile.classifier {
                        classifier.infer_decision(&mut infer);
                    }
                }
            }
            _ => {}
        }
    }

    /// Judge targets that must be decision targets.
    pub(crate) fn decision_target_names(&self) -> Vec<&str> {
        let mut names: Vec<&str> = self
            .classifier_targets()
            .filter(|(_, decision)| decision.is_some())
            .map(|(target, _)| target)
            .collect();
        if let Self::LlmClassifier { config, .. } = self
            && matches!(config.classifier_mode(), ClassifierMode::Direct)
            && let Some(models) = &config.models
        {
            names.extend(models.get(&Category::Judge).iter().map(String::as_str));
        }
        names
    }

    /// Completion targets in algorithm order; judge-only targets are excluded.
    pub fn routing_target_names(&self) -> Vec<&str> {
        match self {
            Self::Noop { .. } => Vec::new(),
            Self::Random { targets, .. } => targets.iter().map(String::as_str).collect(),
            Self::Passthrough {
                target, subagents, ..
            } => {
                let mut names = vec![target.as_str()];
                if let Some(subagents) = subagents {
                    names.extend(subagents.routing_target_names());
                }
                names
            }
            Self::LlmClassifier { config, .. } => match config.classifier_mode() {
                ClassifierMode::Capability => config
                    .weak_target
                    .iter()
                    .chain(&config.strong_target)
                    .map(String::as_str)
                    .collect(),
                ClassifierMode::Escalation => config
                    .strong_target
                    .iter()
                    .chain(&config.weak_target)
                    .map(String::as_str)
                    .collect(),
                ClassifierMode::Custom | ClassifierMode::Direct => config
                    .models
                    .as_ref()
                    .map(CategoryModelConfig::routing_names)
                    .unwrap_or_default(),
            },
            Self::StageRouter {
                capable_target,
                efficient_target,
                subagents,
                ..
            } => {
                let mut names = vec![capable_target.as_str(), efficient_target.as_str()];
                if let Some(subagents) = subagents {
                    names.extend(subagents.routing_target_names());
                }
                names
            }
            Self::Auto {
                capable_target,
                efficient_target,
            } => vec![capable_target.as_str(), efficient_target.as_str()],
            Self::Composite {
                stage, subagents, ..
            } => {
                let mut names = vec![
                    stage.capable_target.as_str(),
                    stage.efficient_target.as_str(),
                ];
                if let Some(subagents) = subagents {
                    names.extend(subagents.routing_target_names());
                }
                names
            }
            // The advisor is judge-only: reviews go through its own client,
            // so it is not a completion (or count_tokens) destination.
            Self::Advisor {
                executor_target, ..
            } => vec![executor_target],
            Self::Vgr { config } => {
                vec![
                    config.efficient_target.as_str(),
                    config.capable_target.as_str(),
                ]
            }
            Self::PrefillRouter { targets, .. } => targets.iter().map(String::as_str).collect(),
        }
    }

    /// Every target the algorithm may call, including judge-only targets.
    ///
    /// [`routing_target_names`](Self::routing_target_names) covers completion destinations;
    /// a classifier also calls its judge, and that call needs a client too.
    pub fn callable_target_names(&self) -> Vec<&str> {
        let mut names = self.routing_target_names();
        names.extend(self.judge_target_names());
        names
    }

    /// Targets the algorithm calls only to decide, such as a judge or an advisor. A target
    /// that also answers requests appears in [`routing_target_names`](Self::routing_target_names) too.
    pub fn judge_target_names(&self) -> Vec<&str> {
        let mut names = Vec::new();
        match self {
            // Custom and direct modes name their judge in `models.judge`; the other
            // two modes use the top-level `classifier_target`.
            Self::LlmClassifier { config, .. } => {
                if matches!(
                    config.classifier_mode(),
                    ClassifierMode::Custom | ClassifierMode::Direct
                ) {
                    names.extend(
                        config
                            .models
                            .as_ref()
                            .map(|models| models.get(&Category::Judge))
                            .unwrap_or_default()
                            .iter()
                            .map(String::as_str),
                    );
                } else {
                    names.push(config.classifier_target.as_str());
                }
            }
            Self::StageRouter { .. } | Self::Composite { .. } => {
                names.extend(self.classifier_targets().map(|(target, _)| target));
            }
            Self::Advisor { advisor_target, .. } => names.push(advisor_target),
            Self::Vgr { config } => {
                names.extend(config.judge_target.as_deref());
                names.extend(config.capable_judge_target.as_deref());
            }
            _ => {}
        }
        // A sub-agent classifier calls its own judge, which is never a completion target.
        if let Self::Passthrough {
            subagents: Some(subagents),
            ..
        }
        | Self::StageRouter {
            subagents: Some(subagents),
            ..
        }
        | Self::Composite {
            subagents: Some(subagents),
            ..
        } = self
        {
            names.extend(subagents.judge_target_names());
        }
        names
    }

    /// Target names grouped as the runtime [`Driver`](libsy::Driver) expects them.
    fn runtime_model_names(&self, route_name: &str) -> AlgorithmResult<RuntimeModelNames> {
        let parent = match self {
            Self::Noop { .. } => HashMap::new(),
            Self::Random { targets, .. } | Self::PrefillRouter { targets, .. } => {
                category_models([(Category::Any, targets.clone())])
            }
            Self::Passthrough { target, .. } => {
                category_models([(Category::Any, vec![target.clone()])])
            }
            Self::LlmClassifier { config } => {
                classifier_runtime_model_names(config.validated_classifier_mode(route_name)?)
            }
            Self::StageRouter {
                capable_target,
                efficient_target,
                classifier,
                ..
            } => {
                let mut models = category_models([
                    (Category::Capable, vec![capable_target.clone()]),
                    (Category::Efficient, vec![efficient_target.clone()]),
                    (
                        Category::Any,
                        vec![capable_target.clone(), efficient_target.clone()],
                    ),
                ]);
                if let Some(classifier) = classifier {
                    models.insert(Category::Judge, vec![classifier.target.clone()]);
                }
                models
            }
            Self::Auto {
                capable_target,
                efficient_target,
            } => category_models([
                (Category::Capable, vec![capable_target.clone()]),
                (Category::Efficient, vec![efficient_target.clone()]),
                (
                    Category::Any,
                    vec![capable_target.clone(), efficient_target.clone()],
                ),
            ]),
            Self::Composite { stage, .. } => category_models([
                (
                    Category::Judge,
                    self.judge_target_names()
                        .into_iter()
                        .map(str::to_string)
                        .collect(),
                ),
                (Category::Capable, vec![stage.capable_target.clone()]),
                (Category::Efficient, vec![stage.efficient_target.clone()]),
                (
                    Category::Any,
                    vec![stage.capable_target.clone(), stage.efficient_target.clone()],
                ),
            ]),
            Self::Advisor {
                executor_target,
                advisor_target,
                ..
            } => category_models([
                (Category::Efficient, vec![executor_target.clone()]),
                (Category::Any, vec![executor_target.clone()]),
                (Category::Judge, vec![advisor_target.clone()]),
            ]),
            Self::Vgr { config } => {
                let judge = config
                    .judge_target
                    .as_ref()
                    .unwrap_or(&config.efficient_target);
                let judges = std::iter::once(judge)
                    .chain(&config.capable_judge_target)
                    .cloned()
                    .collect();
                category_models([
                    (Category::Efficient, vec![config.efficient_target.clone()]),
                    (Category::Capable, vec![config.capable_target.clone()]),
                    (
                        Category::Any,
                        vec![
                            config.efficient_target.clone(),
                            config.capable_target.clone(),
                        ],
                    ),
                    (Category::Judge, judges),
                ])
            }
        };

        let subagents = match self {
            Self::Passthrough { subagents, .. }
            | Self::StageRouter { subagents, .. }
            | Self::Composite { subagents, .. } => subagents.as_ref(),
            _ => None,
        };
        // Sub-agent groups stay separate from the parent's. Merging them would let a
        // sub-agent's `capable` resolve to the parent's, and would put models only the
        // sub-agents were given into the parent's `Any` fallback list.
        let subagent = subagents
            .map(|subagents| subagent_runtime_model_names(subagents, route_name))
            .transpose()?;
        Ok(RuntimeModelNames { parent, subagent })
    }

    /// Response target and routing-only dependency for routers that answer while routing.
    #[cfg(not(target_os = "wasi"))]
    pub(crate) fn routing_response_and_dependency(&self) -> Option<(&str, &str)> {
        match self {
            Self::LlmClassifier { config, .. }
                if matches!(config.classifier_mode(), ClassifierMode::Escalation) =>
            {
                Some((
                    config.weak_target.as_deref()?,
                    config.classifier_target.as_str(),
                ))
            }
            Self::Advisor {
                executor_target,
                advisor_target,
                ..
            } => Some((executor_target, advisor_target)),
            Self::Vgr { config } => Some((
                &config.efficient_target,
                config
                    .judge_target
                    .as_deref()
                    .unwrap_or(&config.efficient_target),
            )),
            Self::Noop { .. }
            | Self::Random { .. }
            | Self::Passthrough { .. }
            | Self::LlmClassifier { .. }
            | Self::StageRouter { .. }
            | Self::Auto { .. }
            | Self::Composite { .. }
            | Self::PrefillRouter { .. } => None,
        }
    }

    /// Builds this algorithm after resolving configured target names.
    pub fn build(
        &self,
        route_name: &str,
        targets: &BTreeMap<String, ModelId>,
    ) -> AlgorithmResult<Arc<dyn Algorithm>> {
        build_algorithm(route_name, self, targets)
    }

    /// Resolves target names to host model IDs and builds the algorithm and runtime groups.
    pub fn build_with_runtime_models(
        &self,
        route_name: &str,
        targets: &BTreeMap<String, ModelId>,
    ) -> AlgorithmResult<(Arc<dyn Algorithm>, RuntimeModels)> {
        let algorithm = self.build(route_name, targets)?;
        let names = self.runtime_model_names(route_name)?;
        let mut models =
            RuntimeModels::new(resolve_runtime_models(route_name, names.parent, targets)?);
        if let Some(subagent) = names.subagent {
            models = models.with_subagent(resolve_runtime_models(route_name, subagent, targets)?);
        }
        Ok((algorithm, models))
    }
}

/// One route's target names, grouped by category and by routing scope.
struct RuntimeModelNames {
    /// Groups the algorithm itself routes over.
    parent: HashMap<Category, Vec<String>>,
    /// Groups delegated sub-agent work routes over, when the route has a `subagents` table.
    subagent: Option<HashMap<Category, Vec<String>>>,
}

fn category_models(
    entries: impl IntoIterator<Item = (Category, Vec<String>)>,
) -> HashMap<Category, Vec<String>> {
    entries.into_iter().collect()
}

fn custom_runtime_model_names(config: &CategoryModelConfig) -> HashMap<Category, Vec<String>> {
    config.groups().collect()
}

fn classifier_runtime_model_names(
    config: LlmClassifierModeConfig,
) -> HashMap<Category, Vec<String>> {
    match config {
        LlmClassifierModeConfig::Capability(config) => category_models([
            (Category::Judge, vec![config.classifier_target]),
            (Category::Efficient, vec![config.weak_target.clone()]),
            (Category::Capable, vec![config.strong_target.clone()]),
            (
                Category::Any,
                vec![config.weak_target, config.strong_target],
            ),
        ]),
        LlmClassifierModeConfig::Escalation(config) => category_models([
            (Category::Judge, vec![config.classifier_target]),
            (Category::Efficient, vec![config.weak_target.clone()]),
            (Category::Capable, vec![config.strong_target.clone()]),
            (
                Category::Any,
                vec![config.strong_target, config.weak_target],
            ),
        ]),
        LlmClassifierModeConfig::Custom(config) => custom_runtime_model_names(&config.models),
        LlmClassifierModeConfig::Direct { models, .. } => custom_runtime_model_names(&models),
    }
}

fn subagent_runtime_model_names(
    config: &SubagentRouteConfig,
    route_name: &str,
) -> AlgorithmResult<HashMap<Category, Vec<String>>> {
    match config {
        SubagentRouteConfig::Passthrough { target } => {
            Ok(category_models([(Category::Any, vec![target.clone()])]))
        }
        SubagentRouteConfig::LlmClassifier(config) => {
            let LlmClassifierModeConfig::Custom(config) =
                config.validated_classifier_mode(route_name)?
            else {
                return Err(AlgorithmConfigError::new(format!(
                    "route {route_name}: subagents llm_classifier only supports mode custom"
                )));
            };
            Ok(custom_runtime_model_names(&config.models))
        }
    }
}
impl LlmClassifierRouteConfig {
    fn classifier_mode(&self) -> ClassifierMode {
        let default = if self.escalation.is_some() {
            ClassifierMode::Escalation
        } else {
            ClassifierMode::Capability
        };
        self.mode.unwrap_or(default)
    }

    fn validated_classifier_mode(
        &self,
        route_name: &str,
    ) -> AlgorithmResult<LlmClassifierModeConfig> {
        let Self {
            classifier_target,
            mode,
            strong_target,
            weak_target,
            base_threshold,
            threshold_step,
            unmatched_steps,
            fail_open,
            classify_trigger,
            message_hash_fallback,
            recent_turn_window,
            prompt,
            response_format_type,
            max_output_tokens,
            judge_deadline_ms,
            escalation,
            decision,
            models,
            default_target,
            response_schema,
            policy,
        } = self;

        let selected_mode = match (mode, escalation.is_some()) {
            (Some(mode), _) => *mode,
            (None, true) => ClassifierMode::Escalation,
            (None, false) => ClassifierMode::Capability,
        };

        if decision.is_some() && !matches!(selected_mode, ClassifierMode::Capability) {
            return Err(AlgorithmConfigError::new(format!(
                "llm_classifier route {route_name}: decision requires capability mode"
            )));
        }

        if !matches!(
            selected_mode,
            ClassifierMode::Capability | ClassifierMode::Direct
        ) && *fail_open == Some(true)
        {
            return Err(AlgorithmConfigError::new(format!(
                "llm_classifier route {route_name}: fail_open = true requires capability or direct mode"
            )));
        }

        match selected_mode {
            ClassifierMode::Capability => {
                if escalation.is_some() {
                    return Err(classifier_field_error(
                        route_name,
                        "escalation",
                        "capability",
                    ));
                }
                reject_custom_fields(
                    route_name,
                    "capability",
                    models,
                    default_target,
                    response_schema,
                    policy,
                )?;
                let judge = if let Some(decision) = decision {
                    if base_threshold.is_some()
                        || threshold_step.is_some()
                        || unmatched_steps.is_some()
                        || prompt.is_some()
                        || *response_format_type != ClassifierResponseFormat::JsonSchema
                        || *max_output_tokens != default_classifier_max_output_tokens()
                        || judge_deadline_ms.is_some()
                    {
                        return Err(AlgorithmConfigError::new(format!(
                            "llm_classifier route {route_name}: decision cannot use LLM judge settings; use decision.cutoff and decision.instructions"
                        )));
                    }
                    CapabilityJudgeRouteConfig::Decision(decision.clone())
                } else {
                    CapabilityJudgeRouteConfig::Llm(LlmCapabilityConfig {
                        base_threshold: required_classifier_field(
                            route_name,
                            "base_threshold",
                            base_threshold,
                        )?,
                        threshold_step: threshold_step.unwrap_or_default(),
                        unmatched_steps: unmatched_steps.unwrap_or(DEFAULT_UNMATCHED_STEPS),
                        contract: classifier_contract(prompt.as_deref())
                            .with_response_format_type(*response_format_type),
                        max_output_tokens: *max_output_tokens,
                        judge_deadline_ms: *judge_deadline_ms,
                    })
                };
                Ok(LlmClassifierModeConfig::Capability(
                    CapabilityClassifierRouteConfig {
                        classifier_target: classifier_target.clone(),
                        fail_open: fail_open.unwrap_or(true),
                        strong_target: required_classifier_field(
                            route_name,
                            "strong_target",
                            strong_target,
                        )?,
                        weak_target: required_classifier_field(
                            route_name,
                            "weak_target",
                            weak_target,
                        )?,
                        judge,
                        classify_trigger: *classify_trigger,
                        message_hash_fallback: *message_hash_fallback,
                        recent_turn_window: *recent_turn_window,
                    },
                ))
            }
            ClassifierMode::Escalation => {
                reject_custom_fields(
                    route_name,
                    "escalation",
                    models,
                    default_target,
                    response_schema,
                    policy,
                )?;
                if *classify_trigger != ClassifyTrigger::EveryRequest {
                    return Err(AlgorithmConfigError::new(format!(
                        "llm_classifier route {route_name} mode escalation cannot use classify_trigger"
                    )));
                }
                let has_capability_settings = base_threshold.is_some()
                    || threshold_step.is_some()
                    || fail_open.is_some()
                    || *message_hash_fallback
                    || recent_turn_window.is_some();
                // `unmatched_steps` is new, so no existing escalation configuration carries it:
                // reject it even when the mode is implied by `escalation`. The older capability
                // keys stay tolerated in that implicit form for compatibility.
                if unmatched_steps.is_some() || (mode.is_some() && has_capability_settings) {
                    return Err(AlgorithmConfigError::new(format!(
                        "llm_classifier route {route_name} mode escalation cannot use capability routing settings"
                    )));
                }
                if has_capability_settings {
                    // Existing files that select escalation through the `escalation` table alone
                    // keep loading, but their capability keys do nothing in this mode.
                    tracing::warn!(
                        "llm_classifier route {route_name} runs in escalation mode because it has an escalation table; base_threshold, threshold_step, fail_open, recent_turn_window and message_hash_fallback are ignored in this mode. Set mode = \"escalation\" and remove them."
                    );
                }
                Ok(LlmClassifierModeConfig::Escalation(
                    EscalationClassifierRouteConfig {
                        classifier_target: classifier_target.clone(),
                        strong_target: required_classifier_field(
                            route_name,
                            "strong_target",
                            strong_target,
                        )?,
                        weak_target: required_classifier_field(
                            route_name,
                            "weak_target",
                            weak_target,
                        )?,
                        prompt: prompt.clone(),
                        response_format_type: *response_format_type,
                        max_output_tokens: *max_output_tokens,
                        judge_deadline_ms: *judge_deadline_ms,
                        judge: required_classifier_field(route_name, "escalation", escalation)?,
                    },
                ))
            }
            ClassifierMode::Custom => {
                if !classifier_target.is_empty()
                    || strong_target.is_some()
                    || weak_target.is_some()
                    || base_threshold.is_some()
                    || threshold_step.is_some()
                    || unmatched_steps.is_some()
                    || escalation.is_some()
                    || *response_format_type != ClassifierResponseFormat::JsonSchema
                {
                    return Err(AlgorithmConfigError::new(format!(
                        "llm_classifier route {route_name} mode custom cannot use capability or escalation fields and response_format_type must be 'json_schema'"
                    )));
                }
                let (models, default_target) =
                    validated_models(route_name, models, default_target)?;
                Ok(LlmClassifierModeConfig::Custom(
                    CustomClassifierRouteConfig {
                        models,
                        default_target,
                        prompt: required_classifier_field(route_name, "prompt", prompt)?,
                        response_schema: required_classifier_field(
                            route_name,
                            "response_schema",
                            response_schema,
                        )?,
                        policy: required_classifier_field(route_name, "policy", policy)?,
                        classify_trigger: *classify_trigger,
                        message_hash_fallback: *message_hash_fallback,
                        recent_turn_window: *recent_turn_window,
                        max_output_tokens: *max_output_tokens,
                        judge_deadline_ms: *judge_deadline_ms,
                    },
                ))
            }
            ClassifierMode::Direct => {
                if !classifier_target.is_empty()
                    || strong_target.is_some()
                    || weak_target.is_some()
                    || base_threshold.is_some()
                    || threshold_step.is_some()
                    || unmatched_steps.is_some()
                    || escalation.is_some()
                    || prompt.is_some()
                    || response_schema.is_some()
                    || policy.is_some()
                    || *response_format_type != ClassifierResponseFormat::JsonSchema
                    || *max_output_tokens != default_classifier_max_output_tokens()
                    || judge_deadline_ms.is_some()
                {
                    return Err(AlgorithmConfigError::new(format!(
                        "llm_classifier route {route_name} mode direct cannot use capability, escalation, or LLM judge fields"
                    )));
                }
                let (models, default_target) =
                    validated_models(route_name, models, default_target)?;
                let options = models
                    .groups()
                    .filter(|(category, targets)| {
                        !targets.is_empty() && !matches!(category, Category::Judge | Category::Any)
                    })
                    .map(|(category, _)| category)
                    .collect();
                Ok(LlmClassifierModeConfig::Direct {
                    models,
                    default_target,
                    config: DirectClassifierConfig {
                        options,
                        fail_open: fail_open.unwrap_or(true),
                        classify_trigger: *classify_trigger,
                        message_hash_fallback: *message_hash_fallback,
                        recent_turn_window: *recent_turn_window,
                    },
                })
            }
        }
    }
}

fn validated_models(
    route_name: &str,
    models: &Option<CategoryModelConfig>,
    default_target: &Option<String>,
) -> AlgorithmResult<(CategoryModelConfig, Category)> {
    let models = required_classifier_field(route_name, "models", models)?;
    let default_target: Category =
        required_classifier_field(route_name, "default_target", default_target)?
            .parse()
            .map_err(|error| {
                AlgorithmConfigError::new(format!(
                    "llm_classifier route {route_name} has invalid default_target: {error}"
                ))
            })?;
    if default_target == Category::Judge {
        return Err(AlgorithmConfigError::new(format!(
            "llm_classifier route {route_name} default_target cannot be judge"
        )));
    }
    models.validate(route_name, &default_target)?;
    Ok((models, default_target))
}

fn reject_custom_fields(
    route_name: &str,
    mode: &str,
    models: &Option<CategoryModelConfig>,
    default_target: &Option<String>,
    response_schema: &Option<String>,
    policy: &Option<ClassifierPolicyConfig>,
) -> AlgorithmResult<()> {
    if models.is_some() || default_target.is_some() || response_schema.is_some() || policy.is_some()
    {
        return Err(AlgorithmConfigError::new(format!(
            "llm_classifier route {route_name} mode {mode} cannot use custom classifier fields"
        )));
    }
    Ok(())
}

fn classifier_field_error(route_name: &str, field: &str, mode: &str) -> AlgorithmConfigError {
    AlgorithmConfigError::new(format!(
        "llm_classifier route {route_name} mode {mode} cannot use {field}"
    ))
}

fn required_classifier_field<T: Clone>(
    route_name: &str,
    field: &str,
    value: &Option<T>,
) -> AlgorithmResult<T> {
    value.clone().ok_or_else(|| {
        AlgorithmConfigError::new(format!(
            "llm_classifier route {route_name} requires {field}"
        ))
    })
}

fn build_subagent_router_config(
    route_name: &str,
    config: &SubagentRouteConfig,
    targets: &BTreeMap<String, ModelId>,
) -> AlgorithmResult<SubagentRouterConfig> {
    match config {
        SubagentRouteConfig::Passthrough { target } => {
            resolve_target_model_id(route_name, target, targets)?;
            Ok(SubagentRouterConfig::fixed_target())
        }
        SubagentRouteConfig::LlmClassifier(config) => {
            let LlmClassifierModeConfig::Custom(config) =
                config.validated_classifier_mode(route_name)?
            else {
                return Err(AlgorithmConfigError::new(format!(
                    "route {route_name}: subagents llm_classifier only supports mode custom"
                )));
            };
            for name in config.models.all_names() {
                resolve_target_model_id(route_name, name, targets)?;
            }
            if config.models.get(&config.default_target).is_empty() {
                return Err(AlgorithmConfigError::new(format!(
                    "route {route_name}: subagents llm_classifier has no model for default category {}",
                    config.default_target.as_str()
                )));
            }
            let response_schema =
                serde_json::from_str(&config.response_schema).map_err(|error| {
                    AlgorithmConfigError::with_source(
                        format!(
                            "route {route_name}: subagents llm_classifier response_schema is invalid JSON: {error}"
                        ),
                        error,
                    )
                })?;
            warn_single_target_classifier(route_name, &config.models);
            let mut classifier_config = CustomClassifierConfig::new(
                config.prompt,
                response_schema,
                config.policy.into_libsy(),
            );
            classifier_config.recent_turn_window = config.recent_turn_window;
            classifier_config.max_output_tokens = config.max_output_tokens;
            classifier_config.judge_deadline_ms = config.judge_deadline_ms;
            let classifier = Arc::new(
                LlmTaskClassifier::new(LlmClassifierConfig::Custom {
                    default_target: config.default_target.clone(),
                    config: classifier_config,
                })
                .map_err(|error| {
                    AlgorithmConfigError::with_source(
                        format!("route {route_name}: subagents llm_classifier: {error}"),
                        error,
                    )
                })?,
            );
            Ok(SubagentRouterConfig {
                classifier,
                default_target: config.default_target,
                classify_trigger: config.classify_trigger,
                message_hash_fallback: config.message_hash_fallback,
            })
        }
    }
}

fn attach_subagent_router(
    route_name: &str,
    parent: Arc<dyn Algorithm>,
    config: Option<&SubagentRouteConfig>,
    targets: &BTreeMap<String, ModelId>,
) -> AlgorithmResult<Arc<dyn Algorithm>> {
    let Some(config) = config else {
        return Ok(parent);
    };
    let config = build_subagent_router_config(route_name, config, targets)?;
    let algorithm = SubagentRouter::new(parent, config).map_err(|error| {
        AlgorithmConfigError::with_source(
            format!("route {route_name}: subagent routing: {error}"),
            error,
        )
    })?;
    Ok(Arc::new(algorithm))
}

/// `build_algorithm` builds the configured algorithm and attaches supported subagent routing.
/// It returns errors for invalid settings or failed target lookups during construction.
/// `AlgorithmSpec::build_with_runtime_models` also resolves the runtime model groups.
fn build_algorithm(
    route_name: &str,
    config: &AlgorithmSpec,
    targets: &BTreeMap<String, ModelId>,
) -> AlgorithmResult<Arc<dyn Algorithm>> {
    match config {
        AlgorithmSpec::Noop { .. } => Ok(Arc::new(Noop {})),
        AlgorithmSpec::Random {
            targets: names,
            weights,
            seed,
        } => {
            // The algorithm only sees its targets at request time, so a bad pairing
            // would otherwise fail every request instead of failing to start.
            if let Some(weights) = weights
                && weights.len() != names.len()
            {
                return Err(AlgorithmConfigError::new(format!(
                    "random route {route_name}: expected {} weights, got {}",
                    names.len(),
                    weights.len()
                )));
            }
            let mut seen = BTreeSet::new();
            if let Some(duplicate) = names.iter().find(|name| !seen.insert(*name)) {
                return Err(AlgorithmConfigError::new(format!(
                    "random route {route_name}: targets must be unique, {duplicate} is repeated"
                )));
            }
            let algorithm = Random::new(weights.clone(), *seed).map_err(|error| {
                AlgorithmConfigError::with_source(
                    format!("random route {route_name}: {error}"),
                    error,
                )
            })?;
            Ok(Arc::new(algorithm))
        }
        AlgorithmSpec::Passthrough { subagents, .. } => {
            let algorithm = Passthrough;
            let parent: Arc<dyn Algorithm> = Arc::new(algorithm);
            attach_subagent_router(route_name, parent, subagents.as_ref(), targets)
        }
        AlgorithmSpec::LlmClassifier {
            config: classifier_config,
            ..
        } => {
            let mode = classifier_config.validated_classifier_mode(route_name)?;
            let algorithm = match mode {
                LlmClassifierModeConfig::Capability(config) => {
                    let classifier_config = config.into_task_config();
                    LlmTaskClassifier::new(LlmClassifierConfig::Capability {
                        config: classifier_config,
                    })
                }
                LlmClassifierModeConfig::Escalation(config) => {
                    LlmTaskClassifier::new(LlmClassifierConfig::Escalation {
                        contract: classifier_contract(config.prompt.as_deref())
                            .with_response_format_type(config.response_format_type),
                        config: config.judge,
                        max_output_tokens: config.max_output_tokens,
                        judge_deadline_ms: config.judge_deadline_ms,
                    })
                }
                LlmClassifierModeConfig::Custom(config) => {
                    let response_schema = serde_json::from_str(&config.response_schema).map_err(
                        |error| {
                            AlgorithmConfigError::with_source(
                                format!(
                                    "llm_classifier route {route_name}: response_schema is invalid JSON: {error}"
                                ),
                                error,
                            )
                        },
                    )?;
                    warn_single_target_classifier(route_name, &config.models);
                    let mut classifier_config = CustomClassifierConfig::new(
                        config.prompt,
                        response_schema,
                        config.policy.into_libsy(),
                    );
                    classifier_config.classify_trigger = config.classify_trigger;
                    classifier_config.message_hash_fallback = config.message_hash_fallback;
                    classifier_config.recent_turn_window = config.recent_turn_window;
                    classifier_config.max_output_tokens = config.max_output_tokens;
                    classifier_config.judge_deadline_ms = config.judge_deadline_ms;
                    LlmTaskClassifier::new(LlmClassifierConfig::Custom {
                        default_target: config.default_target,
                        config: classifier_config,
                    })
                }
                LlmClassifierModeConfig::Direct {
                    default_target,
                    config,
                    ..
                } => LlmTaskClassifier::new(LlmClassifierConfig::Direct {
                    default_target,
                    config,
                }),
            }
            .map_err(|error| {
                AlgorithmConfigError::with_source(
                    format!("llm_classifier route {route_name}: {error}"),
                    error,
                )
            })?;
            Ok(Arc::new(algorithm))
        }
        AlgorithmSpec::StageRouter {
            capable_target,
            efficient_target,
            capable_first_threshold,
            settings,
            picker,
            classifier,
            subagents,
            ..
        } => {
            if matches!(picker, PickerMode::CapableFirst) {
                tracing::warn!(
                    "stage_router route {route_name} uses picker \"capable_first\", which is experimental: published thresholds and routing results all come from \"efficient_first\", so there is no calibrated confidence_threshold for it and no measured accuracy or cost. Use \"efficient_first\" unless you are running your own calibration."
                );
            }
            warn_identical_tiers(route_name, capable_target, efficient_target);
            let threshold = settings.confidence_threshold.ok_or_else(|| {
                AlgorithmConfigError::new(format!(
                    "stage_router route {route_name}: confidence_threshold is required"
                ))
            })?;
            let mut config = settings.stage_config(settings, *picker, threshold);
            config.capable_first_threshold = *capable_first_threshold;
            // The judge is called through its own target, so it is not a routing
            // destination and stays out of the tier pair.
            config.llm_fallback = classifier
                .as_ref()
                .map(|classifier| {
                    classifier.stage_fallback(route_name, capable_target, efficient_target, targets)
                })
                .transpose()?;
            let algorithm = StageRouter::new(config).map_err(|error| {
                AlgorithmConfigError::with_source(
                    format!("stage_router route {route_name}: {error}"),
                    error,
                )
            })?;
            let parent: Arc<dyn Algorithm> = Arc::new(algorithm);
            attach_subagent_router(route_name, parent, subagents.as_ref(), targets)
        }
        AlgorithmSpec::Auto {
            capable_target,
            efficient_target,
        } => {
            warn_identical_tiers(route_name, capable_target, efficient_target);
            let config = StageRouterConfig::new(PickerMode::EfficientFirst, 0.5);
            let algorithm = StageRouter::new(config).map_err(|error| {
                AlgorithmConfigError::with_source(
                    format!("auto route {route_name}: {error}"),
                    error,
                )
            })?;
            Ok(Arc::new(algorithm))
        }
        AlgorithmSpec::Composite {
            classifier,
            stage,
            efficient,
            capable,
            subagents,
        } => {
            stage.warn_identical_tiers(route_name);
            let judge = classifier.composite_judge_config(
                route_name,
                &stage.capable_target,
                &stage.efficient_target,
            )?;
            let defaults = StageProfileConfig::default();
            let profiles = [
                (efficient, PickerMode::EfficientFirst),
                (capable, PickerMode::CapableFirst),
            ]
            .map(|(profile, picker)| -> AlgorithmResult<_> {
                let profile = profile.as_deref().unwrap_or(&defaults);
                let mut config = stage.profile_config(profile, picker);
                config.llm_fallback = profile
                    .classifier
                    .as_ref()
                    .map(|classifier| {
                        classifier.stage_fallback(
                            route_name,
                            &stage.capable_target,
                            &stage.efficient_target,
                            targets,
                        )
                    })
                    .transpose()?;
                Ok(config)
            });
            let [profile_0, profile_1] = profiles;
            let algorithm = CompositeRouter::new_with_profiles(judge, profile_0?, profile_1?)
                .map_err(|error| {
                    AlgorithmConfigError::with_source(
                        format!("composite route {route_name}: {error}"),
                        error,
                    )
                })?;
            let parent: Arc<dyn Algorithm> = Arc::new(algorithm);
            attach_subagent_router(route_name, parent, subagents.as_ref(), targets)
        }
        AlgorithmSpec::Advisor {
            reviewer_system_prompt,
            redo_feedback_prefix,
            gate_trigger,
            gate_trigger_pattern,
            max_reviews,
            gate_stall_turns,
            gate_min_tool_results,
            advisor_max_tokens,
            advisor_temperature,
            transcript_max_chars,
            fail_open,
            ..
        } => {
            // A pattern set under the default trigger would be silently
            // ignored; reject the misconfiguration instead.
            if *gate_trigger == AdvisorTriggerConfig::NoToolCall && gate_trigger_pattern.is_some() {
                return Err(AlgorithmConfigError::new(format!(
                    "advisor route {route_name}: gate_trigger_pattern requires \
                     gate_trigger = \"pattern\""
                )));
            }
            let mut config = AdvisorGateConfig::default();
            if let Some(prompt) = reviewer_system_prompt {
                config.reviewer_system_prompt = prompt.clone();
            }
            if let Some(prefix) = redo_feedback_prefix {
                config.redo_feedback_prefix = prefix.clone();
            }
            config.gate_trigger = match gate_trigger {
                AdvisorTriggerConfig::NoToolCall => GateTrigger::NoToolCall,
                AdvisorTriggerConfig::Pattern => {
                    GateTrigger::Pattern(gate_trigger_pattern.clone().unwrap_or_default())
                }
            };
            config.max_reviews = *max_reviews;
            config.gate_stall_turns = *gate_stall_turns;
            config.gate_min_tool_results = *gate_min_tool_results;
            config.advisor_max_tokens = *advisor_max_tokens;
            config.advisor_temperature = *advisor_temperature;
            config.transcript_max_chars = *transcript_max_chars;
            config.fail_open = *fail_open;
            let algorithm = AdvisorGate::new(config).map_err(|error| {
                AlgorithmConfigError::with_source(
                    format!("advisor route {route_name}: {error}"),
                    error,
                )
            })?;
            Ok(Arc::new(algorithm))
        }
        AlgorithmSpec::Vgr { config } => build_vgr(route_name, config, targets),
        AlgorithmSpec::PrefillRouter {
            targets: names,
            checkpoint,
            device,
            cache_dir,
            max_length,
            batch_size,
        } => {
            #[cfg(feature = "prefill-router")]
            {
                let targets = names
                    .iter()
                    .map(|name| resolve_target_model_id(route_name, name, targets))
                    .collect::<AlgorithmResult<Vec<_>>>()?;
                let mut config = prefill_router::PrefillRouterConfig::new(targets, checkpoint);
                config.device.clone_from(device);
                config.cache_dir.clone_from(cache_dir);
                if let Some(max_length) = max_length {
                    config.max_length = *max_length;
                }
                if let Some(batch_size) = batch_size {
                    config.batch_size = *batch_size;
                }
                let algorithm = config.build().map_err(|error| {
                    AlgorithmConfigError::with_source(
                        format!("prefill_router route {route_name}: {error}"),
                        error,
                    )
                })?;
                Ok(Arc::new(algorithm))
            }

            #[cfg(not(feature = "prefill-router"))]
            {
                let _ = (
                    names, checkpoint, device, cache_dir, max_length, batch_size, targets,
                );
                Err(AlgorithmConfigError::new(format!(
                    "prefill_router route {route_name} requires the `prefill-router` Cargo feature"
                )))
            }
        }
    }
}

fn build_vgr(
    route_name: &str,
    config: &VgrRouteConfig,
    targets: &BTreeMap<String, ModelId>,
) -> AlgorithmResult<Arc<dyn Algorithm>> {
    let efficient = resolve_target_model_id(route_name, &config.efficient_target, targets)?;
    let capable = resolve_target_model_id(route_name, &config.capable_target, targets)?;
    let optional = |name: &Option<String>| {
        name.as_deref()
            .map(|name| resolve_target_model_id(route_name, name, targets))
            .transpose()
    };
    let mut runtime = VgrConfig::new(efficient, capable);
    runtime.targets.judge = optional(&config.judge_target)?;
    runtime.targets.capable_judge = optional(&config.capable_judge_target)?;
    runtime.mode = match config.mode {
        VgrModeConfig::Off => libsy::ServingMode::Off,
        VgrModeConfig::Evaluate => libsy::ServingMode::Evaluate,
        VgrModeConfig::Shadow => libsy::ServingMode::Shadow,
        VgrModeConfig::Active => libsy::ServingMode::Active {
            approval: config.active_approval.clone().unwrap_or_default(),
        },
    };
    runtime.deadline = vgr_duration(route_name, "deadline_seconds", config.deadline_seconds)?;
    runtime.bounded_efficient = config.bounded_efficient;
    runtime.task_typing = config.task_typing;
    runtime.confirmed_recovery_min_clean_tail = config.confirmed_recovery_min_clean_tail;
    runtime.agentic_handoff = config.agentic_handoff;
    runtime.compact_handoff = config.compact_handoff;
    runtime.latch_escalation = config.latch_escalation;
    runtime.efficient_turn_budget = config
        .efficient_turn_budget_seconds
        .map(|seconds| vgr_duration(route_name, "efficient_turn_budget_seconds", seconds))
        .transpose()?;
    runtime.breaker = BreakerConfig {
        threshold: config.breaker_threshold,
        cooldown: vgr_duration(
            route_name,
            "breaker_cooldown_seconds",
            config.breaker_cooldown_seconds,
        )?,
    };
    Vgr::new(runtime)
        .map(|algorithm| Arc::new(algorithm) as Arc<dyn Algorithm>)
        .map_err(|error| {
            AlgorithmConfigError::with_source(format!("vgr route {route_name}: {error}"), error)
        })
}

fn vgr_duration(route: &str, field: &str, seconds: f64) -> AlgorithmResult<std::time::Duration> {
    let message = || format!("vgr route {route}: {field} must be a positive number");
    let duration = std::time::Duration::try_from_secs_f64(seconds)
        .map_err(|error| AlgorithmConfigError::with_source(message(), error))?;
    if duration.is_zero() {
        return Err(AlgorithmConfigError::new(message()));
    }
    Ok(duration)
}

const fn default_max_reviews() -> u32 {
    1
}

const fn default_advisor_max_tokens() -> u64 {
    2048
}

const fn default_transcript_max_chars() -> usize {
    200_000
}

const fn default_fail_open() -> bool {
    true
}

fn classifier_contract(prompt: Option<&str>) -> ClassifierContractConfig {
    prompt.map_or_else(ClassifierContractConfig::default, |prompt| {
        ClassifierContractConfig::default().with_prompt(prompt)
    })
}

fn default_classifier_max_output_tokens() -> u64 {
    LlmCapabilityConfig::default().max_output_tokens
}

/// Both tiers on one target leave the route nothing to choose between; every decision
/// lands on the same model. The file still loads, since a single-model deployment can
/// be a deliberate overhead measurement.
fn warn_identical_tiers(route_name: &str, capable_target: &str, efficient_target: &str) {
    if capable_target == efficient_target {
        tracing::warn!(
            route = route_name,
            target = capable_target,
            "capable_target and efficient_target name the same target, so every request goes to one model; use passthrough for a single model, or point the tiers at two targets"
        );
    }
}

fn warn_single_target_classifier(route_name: &str, models: &CategoryModelConfig) {
    if models.routing_names().len() < 2 {
        tracing::warn!(
            route = route_name,
            "custom classifier has only one routing target; judge calls add cost without a routing choice. Use passthrough or add another completion target in routes.<name>, or in routes.<name>.subagents for a subagent classifier."
        );
    }
}

const fn default_vgr_deadline() -> f64 {
    30.0
}

const fn default_true() -> bool {
    true
}

const fn default_vgr_breaker_threshold() -> u32 {
    5
}

const fn default_vgr_breaker_cooldown() -> f64 {
    30.0
}

fn resolve_target_model_id(
    route_name: &str,
    name: &str,
    targets: &BTreeMap<String, ModelId>,
) -> AlgorithmResult<ModelId> {
    targets.get(name).cloned().ok_or_else(|| {
        AlgorithmConfigError::new(format!(
            "route {route_name} references unknown target {name}"
        ))
    })
}

fn resolve_runtime_models(
    route_name: &str,
    names: HashMap<Category, Vec<String>>,
    targets: &BTreeMap<String, ModelId>,
) -> AlgorithmResult<HashMap<Category, Vec<ModelId>>> {
    names
        .into_iter()
        .map(|(category, names)| {
            let models = names
                .into_iter()
                .map(|name| resolve_target_model_id(route_name, &name, targets))
                .collect::<AlgorithmResult<Vec<_>>>()?;
            Ok((category, models))
        })
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn composite_profile_defaults() -> AlgorithmResult<()> {
        let stage: StageTierConfig =
            toml::from_str("capable_target = 'strong'\nefficient_target = 'weak'").unwrap();
        for (picker, threshold, capable_hold, efficient_hold, prompt) in [
            (PickerMode::EfficientFirst, 0.4, 2, 0, None),
            (
                PickerMode::CapableFirst,
                0.0,
                0,
                -1,
                Some(COMPOSITE_PLANNING_PROMPT),
            ),
        ] {
            let config = stage.profile_config(&StageProfileConfig::default(), picker);
            assert_eq!(config.mode, picker);
            assert_eq!(config.confidence_threshold, threshold);
            assert_eq!(config.recent_window, Some(3));
            assert_eq!(config.capable_hold_turns, capable_hold);
            assert_eq!(config.efficient_hold_turns, Some(efficient_hold));
            assert_eq!(config.capable_system_prompt.as_deref(), prompt);
            assert!(config.llm_fallback.is_none());
            assert!(config.handoff_notes.is_none());
        }
        let standalone = StageSettingsConfig::default().stage_config(
            &StageSettingsConfig::default(),
            PickerMode::CapableFirst,
            0.5,
        );
        assert_eq!(standalone.capable_hold_turns, 2);
        assert!(standalone.capable_system_prompt.is_none());
        Ok(())
    }

    #[test]
    fn composite_profile_overrides() {
        let stage: StageTierConfig = toml::from_str(
            r#"
capable_target = "strong"
efficient_target = "weak"
efficient_first_threshold = 0.7
capable_first_threshold = 0.2
recent_turn_window = 5
capable_hold_turns = 4
efficient_hold_turns = 1
capable_system_prompt = "Shared plan"
"#,
        )
        .unwrap();
        let shared = stage.profile_config(&StageProfileConfig::default(), PickerMode::CapableFirst);
        assert_eq!(shared.confidence_threshold, 0.2);
        assert_eq!(shared.recent_window, Some(5));
        assert_eq!(shared.capable_hold_turns, 4);
        assert_eq!(shared.efficient_hold_turns, Some(1));
        assert_eq!(shared.capable_system_prompt.as_deref(), Some("Shared plan"));
        assert_eq!(
            stage
                .profile_config(&StageProfileConfig::default(), PickerMode::EfficientFirst)
                .confidence_threshold,
            0.7
        );
        let profile: StageProfileConfig = toml::from_str(
            r#"
confidence_threshold = 0.0
recent_turn_window = 2
capable_hold_turns = 0
efficient_hold_turns = 0
capable_system_prompt = ""
"#,
        )
        .unwrap();
        let config = stage.profile_config(&profile, PickerMode::CapableFirst);
        assert_eq!(config.confidence_threshold, 0.0);
        assert_eq!(config.recent_window, Some(2));
        assert_eq!(config.capable_hold_turns, 0);
        assert_eq!(config.efficient_hold_turns, Some(0));
        assert_eq!(config.capable_system_prompt.as_deref(), Some(""));
    }

    #[test]
    fn composite_decision_defaults_and_overrides() -> AlgorithmResult<()> {
        for (settings, cutoff, fail_open) in [
            ("[decision]", 0.92, true),
            ("fail_open = false\n[decision]\ncutoff = 0.7", 0.7, false),
        ] {
            let classifier: StageClassifierConfig = toml::from_str(&format!(
                "target = 'judge'\nclassify_trigger = 'new_session'\n{settings}"
            ))
            .unwrap();
            let CompositeJudgeConfig::Capability(config) =
                classifier.composite_judge_config("route", "strong", "weak")?
            else {
                panic!()
            };
            assert_eq!(config.classify_trigger, ClassifyTrigger::NewSession);
            assert_eq!(config.fail_open, fail_open);
            let CapabilityJudgeConfig::Decision(judge) = config.judge else {
                panic!()
            };
            assert_eq!(judge.cutoff, Some(cutoff));
        }
        Ok(())
    }

    #[test]
    fn restricted_random_preserves_weight_positions() -> AlgorithmResult<()> {
        let allowed = BTreeSet::from(["private_a", "private_b"]);
        let mut algorithm = AlgorithmSpec::Random {
            targets: ["public_a", "private_a", "public_b", "private_b"]
                .map(String::from)
                .to_vec(),
            weights: Some(vec![1.0, 2.0, 3.0, 4.0]),
            seed: Some(42),
        };
        let AlgorithmSpec::Random {
            targets,
            weights,
            seed,
        } = algorithm.restricted_to(&allowed)?
        else {
            unreachable!();
        };
        assert_eq!(targets, ["private_a", "private_b"]);
        assert_eq!(weights, Some(vec![2.0, 4.0]));
        assert_eq!(seed, Some(42));
        if let AlgorithmSpec::Random { weights, .. } = &mut algorithm {
            *weights = Some(vec![1.0]);
        }
        assert!(algorithm.restricted_to(&allowed).is_err());
        Ok(())
    }

    fn custom_classifier() -> LlmClassifierRouteConfig {
        LlmClassifierRouteConfig {
            mode: Some(ClassifierMode::Custom),
            models: Some(CategoryModelConfig(BTreeMap::from([
                ("any".into(), vec!["public".into(), "private".into()]),
                ("efficient".into(), vec!["public".into(), "private".into()]),
                ("judge".into(), vec!["judge".into()]),
                ("research".into(), vec!["public".into()]),
            ]))),
            default_target: Some("efficient".into()),
            prompt: Some("Select an available target.".into()),
            response_schema: Some(r#"{"type":"object"}"#.into()),
            max_output_tokens: default_classifier_max_output_tokens(),
            policy: Some(ClassifierPolicyConfig::TargetSelector {
                selector: "/target".into(),
            }),
            ..LlmClassifierRouteConfig::default()
        }
    }

    #[test]
    fn restricted_custom_pools_cover_parent_and_subagents() -> AlgorithmResult<()> {
        let allowed = BTreeSet::from(["private", "judge"]);
        let targets = BTreeMap::from([
            ("private".into(), ModelId::from("private")),
            ("judge".into(), ModelId::from("judge")),
        ]);
        let parent = AlgorithmSpec::LlmClassifier {
            config: custom_classifier(),
        };
        let child = AlgorithmSpec::Passthrough {
            target: "private".into(),
            subagents: Some(SubagentRouteConfig::LlmClassifier(Box::new(
                custom_classifier(),
            ))),
        };
        for algorithm in [parent, child] {
            let restricted = algorithm.restricted_to(&allowed)?;
            let groups = restricted.runtime_model_names("test")?;
            let groups = groups.subagent.unwrap_or(groups.parent);
            assert_eq!(groups[&Category::Any], ["private"]);
            assert_eq!(groups[&Category::Efficient], ["private"]);
            assert_eq!(groups[&Category::Judge], ["judge"]);
            restricted.build("test", &targets)?;
            let missing_judge = algorithm.restricted_to(&BTreeSet::from(["private"]))?;
            assert!(missing_judge.build("test", &targets).is_err());
        }
        Ok(())
    }

    #[test]
    fn restricted_roles_are_not_replaced() {
        let stage = AlgorithmSpec::Auto {
            capable_target: "private".into(),
            efficient_target: "public".into(),
        };
        assert!(stage.restricted_to(&BTreeSet::from(["private"])).is_err());
    }
}