switchyard_runner/

config.rs

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

//! Version-1 TOML deployment loading for the shared runner.

use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::fs;
use std::path::Path;
use std::sync::Arc;
use std::time::Duration;

use serde::de::DeserializeOwned;
use serde::{Deserialize, Deserializer};
use serde_json::Value;
use switchyard_llm_client::{
    AuxiliaryOperation, Backend, ClientRouter, DEFAULT_MAX_RETRIES, HttpBackendConfig, ModelConfig,
    OpenAiDecisionClient, SystemOneClient, TranslatingLlmClient,
};
use switchyard_protocol::{ModelId, RoutedDecisionClient, RoutedLlmClient, WireFormat};

use crate::runner::ModelPropertiesProbe;
use crate::{
    AlgorithmSpec, AuxiliaryTarget, CallerAuthKind, DecisionTarget, ModelCapabilities, Route,
    Runner, RunnerError,
};

const SUPPORTED_SCHEMA_VERSION: u32 = 1;
const MAX_CONFIGURED_RETRIES: u32 = 10;

/// This function returns a deployment's declared credential variable names without reading their values.
/// It parses the deployment and checks its schema version before returning names from LLM and decision clients.
pub fn api_key_variables(source: &str) -> Result<BTreeSet<String>, RunnerError> {
    let config: DeploymentConfig = toml::from_str(source).map_err(|_| {
        RunnerError::configuration(
            "Could not parse the server config to read credential references.",
        )
    })?;
    if config.schema_version != SUPPORTED_SCHEMA_VERSION {
        return Err(RunnerError::configuration(
            "Unsupported server config schema version.",
        ));
    }
    let mut variables: BTreeSet<_> = config
        .llm_clients
        .values()
        .filter_map(|client| client.api_key_env.clone())
        .collect();
    for client in config.decision_clients.values() {
        variables.insert(client.api_key_env.clone());
    }
    if variables
        .iter()
        .any(|name| name.trim().is_empty() || name.contains(['\0', '=']))
    {
        return Err(RunnerError::configuration(
            "Invalid credential environment variable name.",
        ));
    }
    Ok(variables)
}

type RunnerResult<T> = Result<T, RunnerError>;

pub(crate) fn load_runner(path: impl AsRef<Path>) -> RunnerResult<Runner> {
    let path = path.as_ref();
    let source = fs::read_to_string(path).map_err(|error| {
        RunnerError::configuration_source(
            format!("failed to read server config {}: {error}", path.display()),
            error,
        )
    })?;
    runner_from_toml(&source).map_err(|error| {
        RunnerError::configuration_source(
            format!("invalid server config {}: {error}", path.display()),
            error,
        )
    })
}

pub(crate) fn runner_from_toml(source: &str) -> RunnerResult<Runner> {
    let config: DeploymentConfig = toml::from_str(source).map_err(|error| {
        RunnerError::configuration_source(format!("failed to parse TOML: {error}"), error)
    })?;
    config.build()
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct DeploymentConfig {
    schema_version: u32,
    fallback_client: Option<String>,
    #[serde(default)]
    llm_clients: BTreeMap<String, LlmClientConfig>,
    targets: BTreeMap<String, TargetConfig>,
    #[serde(default)]
    decision_clients: BTreeMap<String, DecisionClientConfig>,
    #[serde(default)]
    decision_targets: BTreeMap<String, DecisionTargetConfig>,
    routes: BTreeMap<String, RouteConfig>,
}

#[derive(Debug)]
struct RouteConfig {
    id: ModelId,
    context_window: Option<u32>,
    tool_calling: Option<bool>,
    reasoning: Option<bool>,
    vision: Option<bool>,
    algorithm: AlgorithmSpec,
    infra: Option<libsy::InfraPolicy>,
}

struct TargetPromptPolicy {
    prompts: HashMap<ModelId, String>,
    routing_answer_target: Option<ModelId>,
}

impl<'de> Deserialize<'de> for RouteConfig {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let mut table = toml::Table::deserialize(deserializer)?;
        let id = take_required(&mut table, "id")?;
        let context_window = take_optional(&mut table, "context_window")?;
        let tool_calling = take_optional(&mut table, "tool_calling")?;
        let reasoning = take_optional(&mut table, "reasoning")?;
        let vision = take_optional(&mut table, "vision")?;
        let infra = take_optional(&mut table, "infra")?;
        let algorithm = AlgorithmSpec::deserialize(toml::Value::Table(table))
            .map_err(serde::de::Error::custom)?;
        Ok(Self {
            id,
            context_window,
            tool_calling,
            reasoning,
            vision,
            algorithm,
            infra,
        })
    }
}

fn take_required<T, E>(table: &mut toml::Table, name: &'static str) -> Result<T, E>
where
    T: DeserializeOwned,
    E: serde::de::Error,
{
    let value = table.remove(name).ok_or_else(|| E::missing_field(name))?;
    T::deserialize(value).map_err(E::custom)
}

fn take_optional<T, E>(table: &mut toml::Table, name: &'static str) -> Result<Option<T>, E>
where
    T: DeserializeOwned,
    E: serde::de::Error,
{
    table
        .remove(name)
        .map(|value| T::deserialize(value).map_err(E::custom))
        .transpose()
}

impl RouteConfig {
    fn capabilities(&self) -> ModelCapabilities {
        ModelCapabilities {
            context_window: self.context_window,
            tool_calling: self.tool_calling,
            reasoning: self.reasoning,
            vision: self.vision,
        }
    }

    fn routing_target_names(&self) -> Vec<&str> {
        self.algorithm.routing_target_names()
    }

    fn callable_target_names(&self) -> Vec<&str> {
        self.algorithm.callable_target_names()
    }
}

impl DeploymentConfig {
    fn decision_target(&self, name: &str) -> Option<DecisionTarget> {
        let target = self.targets.get(name)?;
        let client = self.llm_clients.get(&target.llm_client)?;
        Some(DecisionTarget {
            target: name.to_string(),
            model: target.id.clone(),
            format: client.format.wire_format(),
            base_url: client.base_url.as_str().to_string(),
            extra_body: target.extra_body.clone(),
        })
    }

    fn build(self) -> RunnerResult<Runner> {
        if self.schema_version != SUPPORTED_SCHEMA_VERSION {
            return Err(RunnerError::configuration(format!(
                "unsupported schema_version {}; expected {SUPPORTED_SCHEMA_VERSION}",
                self.schema_version
            )));
        }

        let mut route_names_by_id = HashMap::new();
        for (route_name, config) in &self.routes {
            validate_value("route name", route_name)?;
            validate_value(&format!("route {route_name} id"), &config.id)?;
            if let Some(first_route_name) =
                route_names_by_id.insert(config.id.as_str(), route_name.as_str())
            {
                return Err(RunnerError::configuration(format!(
                    "routes {first_route_name} and {route_name} both use id {}; route ids must be unique",
                    config.id
                )));
            }
        }

        // The LLM client keeps one backend per model id, so two targets naming the same model on
        // the same client share it. That is harmless when their request settings agree (an alias
        // for a different system prompt, say) and silently wrong when they do not: the second
        // target's reasoning_effort or extra_body would never reach the wire.
        let mut seen_client_model_ids: HashMap<(&str, &str), (&String, &TargetConfig)> =
            HashMap::new();
        for (target_name, target) in &self.targets {
            validate_value("target name", target_name)?;
            validate_value(&format!("target {target_name} id"), &target.id)?;
            match seen_client_model_ids.entry((target.llm_client.as_str(), target.id.as_str())) {
                std::collections::hash_map::Entry::Vacant(slot) => {
                    slot.insert((target_name, target));
                }
                std::collections::hash_map::Entry::Occupied(slot) => {
                    let (first_name, first) = slot.get();
                    if first.reasoning_effort != target.reasoning_effort
                        || first.extra_body != target.extra_body
                        || first.omit_body_fields != target.omit_body_fields
                    {
                        return Err(RunnerError::configuration(format!(
                            "targets {first_name} and {target_name} both name model {} on llm client {} but with different reasoning_effort, extra_body, or omit_body_fields; one target per model id is kept, so give each its own model id or llm client",
                            target.id, target.llm_client
                        )));
                    }
                    tracing::warn!(
                        "target {target_name} reuses model id {} on llm client {}; only one target per id is kept and the other is dropped. Give each target a unique model id, or point both routes at one target.",
                        target.id,
                        target.llm_client
                    );
                }
            }
        }

        let mut provider_api_keys = Vec::new();
        let clients = self.build_clients(&mut provider_api_keys)?;
        let decision_clients = self.build_decision_clients(&mut provider_api_keys)?;
        for (name, target) in &self.decision_targets {
            validate_value("decision target name", name)?;
            validate_value(&format!("decision target {name} id"), &target.id)?;
            if self.targets.contains_key(name) {
                return Err(RunnerError::configuration(format!(
                    "target {name} is defined as both an LLM and decision target"
                )));
            }
            if !decision_clients.contains_key(&target.decision_client) {
                return Err(RunnerError::configuration(format!(
                    "decision target {name} references unknown decision client {}",
                    target.decision_client
                )));
            }
        }
        let targets = self.build_targets();
        let fallback_base_url = self.fallback_base_url()?;
        let mut routes = Vec::with_capacity(self.routes.len());
        let mut model_properties_probes = BTreeMap::new();
        for (route_name, config) in &self.routes {
            let decision_judge = config.algorithm.decision_judge();
            for name in config.callable_target_names() {
                let (exists, kind) = if decision_judge.is_some_and(|(judge, _)| judge == name) {
                    (self.decision_targets.contains_key(name), "decision")
                } else {
                    (self.targets.contains_key(name), "LLM")
                };
                if !exists {
                    return Err(RunnerError::configuration(format!(
                        "route references unknown target {name}; route {route_name} requires target kind {kind}"
                    )));
                }
            }
            for name in config.routing_target_names().into_iter().chain(
                decision_judge
                    .into_iter()
                    .flat_map(|(_, judge)| judge.candidates.values().map(String::as_str)),
            ) {
                if !self.targets.contains_key(name) {
                    return Err(RunnerError::configuration(format!(
                        "route {route_name} completion and candidate target {name} must be an LLM target"
                    )));
                }
            }
            let capabilities = config.capabilities();
            if capabilities.context_window == Some(0) {
                return Err(RunnerError::configuration(format!(
                    "route {route_name} context_window must be greater than zero"
                )));
            }
            let (algorithm, models) = config
                .algorithm
                .build_with_runtime_models(route_name, &targets)
                .map_err(|error| RunnerError::configuration_source(error.to_string(), error))?;
            if let Some(infra) = &config.infra {
                if !matches!(&config.algorithm, AlgorithmSpec::LlmClassifier { config }
                    if matches!(config.mode, None | Some(crate::ClassifierMode::Capability))
                        && config.escalation.is_none())
                {
                    return Err(RunnerError::configuration(format!(
                        "route {route_name}: infra requires capability llm_classifier without escalation"
                    )));
                }
                infra.validate().map_err(|error| {
                    RunnerError::configuration_source(format!("route {route_name}: {error}"), error)
                })?;
            }
            if let AlgorithmSpec::Vgr { config: vgr } = &config.algorithm
                && let Some(probe) =
                    self.build_model_properties_probe(&vgr.efficient_target, &clients)
            {
                model_properties_probes.insert(config.id.clone(), probe);
            }
            let (route_clients, caller_auth) =
                self.build_route_clients(route_name, config, &clients, &decision_clients)?;
            let anthropic_auxiliary_target =
                self.build_anthropic_auxiliary_target(config, &clients);
            let responses_auxiliary_target =
                self.build_responses_auxiliary_target(config, &clients);
            let decision_targets = config
                .routing_target_names()
                .into_iter()
                .filter_map(|name| self.decision_target(name))
                .collect();
            let route = Route::new(
                algorithm,
                route_clients,
                caller_auth,
                capabilities,
                anthropic_auxiliary_target,
                responses_auxiliary_target,
                decision_targets,
                models,
            )
            .with_infra(config.infra.clone());
            routes.push((config.id.clone(), route));
        }
        let runner = Runner::new(routes)
            .with_fallback_url(fallback_base_url)
            .with_provider_api_keys(provider_api_keys)
            .with_model_properties_probes(model_properties_probes);
        Ok(runner)
    }

    fn build_clients(
        &self,
        provider_api_keys: &mut Vec<String>,
    ) -> RunnerResult<BTreeMap<String, Arc<TranslatingLlmClient>>> {
        let mut models_by_client = self
            .llm_clients
            .keys()
            .map(|name| (name.clone(), Vec::new()))
            .collect::<BTreeMap<String, Vec<ModelConfig>>>();

        for (name, client_config) in &self.llm_clients {
            validate_value("llm client name", name)?;
            let backend = build_backend(
                name,
                client_config,
                &BTreeMap::new(),
                &BTreeSet::new(),
                None,
            )?;
            let (Backend::OpenAiChat(config)
            | Backend::OpenAiResponses(config)
            | Backend::Anthropic(config)) = backend;
            if let Some(key) = config.api_key {
                provider_api_keys.push(key);
            }
        }
        for (target_name, target) in &self.targets {
            let client_config = self.llm_clients.get(&target.llm_client).ok_or_else(|| {
                RunnerError::configuration(format!(
                    "target {target_name} references unknown llm client {}",
                    target.llm_client
                ))
            })?;
            let model_configs = models_by_client
                .get_mut(&target.llm_client)
                .ok_or_else(|| {
                    RunnerError::configuration("validated llm client was not initialized")
                })?;
            if let Some(effort) = &target.reasoning_effort {
                if effort.trim().is_empty() {
                    return Err(RunnerError::configuration(format!(
                        "target {target_name} reasoning_effort must not be empty"
                    )));
                }
                if matches!(client_config.format, ClientFormat::AnthropicMessages) {
                    return Err(RunnerError::configuration(format!(
                        "target {target_name} reasoning_effort is only supported on openai_chat and openai_responses clients"
                    )));
                }
            }
            model_configs.push(ModelConfig::new(
                target.id.clone(),
                build_backend(
                    &target.llm_client,
                    client_config,
                    &target.extra_body,
                    &target.omit_body_fields,
                    target.reasoning_effort.clone(),
                )?,
                None,
            ));
        }

        let mut clients = BTreeMap::new();
        for (name, model_configs) in models_by_client {
            let mut client = TranslatingLlmClient::new(&model_configs)
                .map_err(|error| RunnerError::configuration(error.to_string()))?;
            if !self.llm_clients[&name].fallback_on_rate_limit {
                client = client.without_rate_limit_cooldown();
            }
            clients.insert(name, Arc::new(client));
        }
        Ok(clients)
    }

    fn build_decision_clients(
        &self,
        provider_api_keys: &mut Vec<String>,
    ) -> RunnerResult<BTreeMap<String, Arc<dyn RoutedDecisionClient>>> {
        self.decision_clients
            .iter()
            .map(|(name, config)| {
                validate_value("decision client name", name)?;
                let DecisionClientConfig {
                    format,
                    endpoint,
                    api_key_env,
                    timeout_ms,
                } = config;
                if *timeout_ms == 0 {
                    return Err(RunnerError::configuration(format!(
                        "decision client {name} timeout_ms must be at least 1"
                    )));
                }
                let api_key = read_api_key(&format!("decision client {name}"), api_key_env)?;
                let timeout = Duration::from_millis(*timeout_ms);
                let client = match format {
                    DecisionFormat::SystemOne => {
                        SystemOneClient::new(endpoint.0.clone(), api_key.clone(), timeout)
                            .map(|client| Arc::new(client) as Arc<dyn RoutedDecisionClient>)
                    }
                    DecisionFormat::OpenaiDecisions => {
                        OpenAiDecisionClient::new(endpoint.0.clone(), api_key.clone(), timeout)
                            .map(|client| Arc::new(client) as Arc<dyn RoutedDecisionClient>)
                    }
                }
                .map_err(|error| RunnerError::configuration(error.to_string()))?;
                provider_api_keys.push(api_key);
                Ok((name.clone(), client))
            })
            .collect()
    }

    fn build_targets(&self) -> BTreeMap<String, ModelId> {
        self.targets
            .iter()
            .map(|(name, config)| (name.clone(), config.id.clone()))
            .chain(
                self.decision_targets
                    .iter()
                    .map(|(name, config)| (name.clone(), config.id.clone())),
            )
            .collect()
    }

    /// Builds the client router for one route. The second value is the caller credential family
    /// that the route's forwarding clients need, or `None` when no client forwards the caller's
    /// credential. A request through the other family's APIs fails before any upstream call.
    fn build_route_clients(
        &self,
        route_name: &str,
        route: &RouteConfig,
        clients: &BTreeMap<String, Arc<TranslatingLlmClient>>,
        decision_clients: &BTreeMap<String, Arc<dyn RoutedDecisionClient>>,
    ) -> RunnerResult<(ClientRouter, Option<CallerAuthKind>)> {
        let TargetPromptPolicy {
            prompts,
            routing_answer_target,
        } = self.build_route_target_prompts(route_name, route)?;
        let mut by_model = HashMap::new();
        let mut targets_by_model: HashMap<&str, (&str, &TargetConfig)> = HashMap::new();
        let mut caller_auth = None;
        let mut has_mixed_families = false;
        let mut forwarding_origins = BTreeSet::new();
        let mut decisions_by_model = HashMap::new();
        for name in route.callable_target_names() {
            if route
                .algorithm
                .decision_judge()
                .is_some_and(|(judge, _)| judge == name)
            {
                let target = &self.decision_targets[name];
                decisions_by_model.insert(
                    target.id.clone(),
                    decision_clients[&target.decision_client].clone(),
                );
                continue;
            }
            let target = self.targets.get(name).ok_or_else(|| {
                RunnerError::configuration(format!("route references unknown target {name}"))
            })?;
            if let Some((first_name, first)) = targets_by_model.insert(&target.id, (name, target))
                && first.llm_client != target.llm_client
            {
                return Err(RunnerError::configuration(format!(
                    "route {route_name} targets {first_name} and {name} use model {} on different llm clients; execution is keyed by model id, so use distinct model ids within this route or put these targets in separate routes",
                    target.id
                )));
            }
            let client = clients.get(&target.llm_client).ok_or_else(|| {
                RunnerError::configuration(format!("target {name} has no constructed llm client"))
            })?;
            let client_config = self.llm_clients.get(&target.llm_client).ok_or_else(|| {
                RunnerError::configuration(format!(
                    "target {name} references unknown llm client {}",
                    target.llm_client
                ))
            })?;
            if client_config.forward_auth {
                let target_auth = client_config.format.caller_auth_kind();
                has_mixed_families |= caller_auth.is_some_and(|kind| kind != target_auth);
                caller_auth = Some(target_auth);
                forwarding_origins.insert(client_config.base_url.0.origin().ascii_serialization());
            }
            let client: Arc<dyn RoutedLlmClient> = client.clone();
            by_model.insert(target.id.clone(), client);
        }
        // Only forwarding clients count: an api_key_env client sends the server's own key.
        // Forwarding clients must share one credential family unless they all use the same
        // scheme, host, and port, such as one LLM gateway that accepts the caller's gateway key
        // on every endpoint. Such a route serves Chat Completions and Responses callers because
        // Anthropic clients forward the caller's `authorization` header unchanged.
        if has_mixed_families {
            if forwarding_origins.len() > 1 {
                let origins = Vec::from_iter(forwarding_origins).join(", ");
                return Err(RunnerError::configuration(format!(
                    "route {route_name} cannot forward both Anthropic and OpenAI caller credentials to different origins ({origins}); point all of its forwarding clients at one origin (same scheme, host, and port), such as an LLM gateway, or set api_key_env instead of forward_auth on one provider's clients"
                )));
            }
            caller_auth = Some(CallerAuthKind::OpenAi);
        }
        let completion_targets = route
            .routing_target_names()
            .into_iter()
            .map(|name| self.targets[name].id.clone())
            .collect::<Vec<_>>();
        let router = ClientRouter::new_with_decision_clients(
            by_model,
            decisions_by_model,
            prompts,
            routing_answer_target,
            &completion_targets,
        )
        .without_rate_limit_fallback(
            route
                .routing_target_names()
                .into_iter()
                .filter_map(|name| {
                    let target = &self.targets[name];
                    (!self.llm_clients[&target.llm_client].fallback_on_rate_limit)
                        .then(|| target.id.clone())
                })
                .collect(),
        );
        Ok((router, caller_auth))
    }

    /// Builds the effective prompt policy for this route's completion targets.
    fn build_route_target_prompts(
        &self,
        route_name: &str,
        route: &RouteConfig,
    ) -> RunnerResult<TargetPromptPolicy> {
        let mut prompts = HashMap::new();
        let mut aliases = HashMap::<&ModelId, Option<&str>>::new();
        for name in route.algorithm.routing_target_names() {
            let target = self.targets.get(name).ok_or_else(|| {
                RunnerError::configuration(format!("route references unknown target {name}"))
            })?;
            let prompt = target.system_prompt.as_deref();
            if aliases
                .insert(&target.id, prompt)
                .is_some_and(|configured| configured != prompt)
            {
                return Err(RunnerError::configuration(format!(
                    "route {route_name} maps completion target aliases to model {} with different system_prompt values",
                    target.id
                )));
            }
            if let Some(prompt) = prompt {
                prompts.insert(target.id.clone(), prompt.to_string());
            }
        }
        let mut policy = TargetPromptPolicy {
            prompts,
            routing_answer_target: None,
        };
        let Some((response_name, dependency_name)) =
            route.algorithm.routing_response_and_dependency()
        else {
            return Ok(policy);
        };
        let response = self.targets.get(response_name).ok_or_else(|| {
            RunnerError::configuration(format!("route references unknown target {response_name}"))
        })?;
        if !policy.prompts.contains_key(&response.id) {
            return Ok(policy);
        }
        let dependency = self.targets.get(dependency_name).ok_or_else(|| {
            RunnerError::configuration(format!("route references unknown target {dependency_name}"))
        })?;
        if response.id == dependency.id {
            return Err(RunnerError::configuration(format!(
                "route {route_name} cannot apply system_prompt to target {response_name}: model {} is also used by routing-only target {dependency_name}",
                response.id,
            )));
        }
        policy.routing_answer_target = Some(response.id.clone());
        Ok(policy)
    }

    fn fallback_base_url(&self) -> RunnerResult<Option<String>> {
        let Some(name) = &self.fallback_client else {
            return Ok(None);
        };
        let config = self.llm_clients.get(name).ok_or_else(|| {
            RunnerError::configuration(format!(
                "fallback_client references unknown llm client {name}"
            ))
        })?;
        Ok(Some(config.base_url.as_str().to_string()))
    }

    fn build_model_properties_probe(
        &self,
        efficient_target_name: &str,
        clients: &BTreeMap<String, Arc<TranslatingLlmClient>>,
    ) -> Option<ModelPropertiesProbe> {
        let efficient_target = self.targets.get(efficient_target_name)?;
        let client_config = self.llm_clients.get(&efficient_target.llm_client)?;
        if !matches!(
            client_config.context_discovery,
            Some(ContextDiscovery::LlamaCpp)
        ) {
            return None;
        }
        let client = clients.get(&efficient_target.llm_client)?;
        Some(ModelPropertiesProbe {
            model: efficient_target.id.clone(),
            format: client_config.format.wire_format(),
            client: Arc::clone(client),
        })
    }

    fn build_anthropic_auxiliary_target(
        &self,
        route: &RouteConfig,
        clients: &BTreeMap<String, Arc<TranslatingLlmClient>>,
    ) -> Option<AuxiliaryTarget> {
        route
            .routing_target_names()
            .into_iter()
            .enumerate()
            .filter_map(|(index, name)| {
                let target = self.build_auxiliary_target(
                    name,
                    clients,
                    AuxiliaryOperation::AnthropicCountTokens,
                )?;
                Some((count_tokens_priority(name, &target.model), index, target))
            })
            .min_by_key(|(priority, index, _)| (*priority, *index))
            .map(|(_, _, target)| target)
    }

    fn build_responses_auxiliary_target(
        &self,
        route: &RouteConfig,
        clients: &BTreeMap<String, Arc<TranslatingLlmClient>>,
    ) -> Option<AuxiliaryTarget> {
        route.routing_target_names().into_iter().find_map(|name| {
            self.build_auxiliary_target(name, clients, AuxiliaryOperation::ResponsesInputTokens)
        })
    }

    fn build_auxiliary_target(
        &self,
        name: &str,
        clients: &BTreeMap<String, Arc<TranslatingLlmClient>>,
        operation: AuxiliaryOperation,
    ) -> Option<AuxiliaryTarget> {
        let target = self.targets.get(name)?;
        let client = clients.get(&target.llm_client)?;
        client
            .supports_auxiliary(&target.id, operation)
            .then(|| AuxiliaryTarget {
                model: target.id.clone(),
                client: client.clone(),
            })
    }
}

fn count_tokens_priority(target_name: &str, model_id: &ModelId) -> usize {
    let target_name = target_name.to_ascii_lowercase();
    let model_id = model_id.to_ascii_lowercase();
    ["opus", "sonnet", "haiku"]
        .iter()
        .position(|hint| target_name.contains(hint) || model_id.contains(hint))
        .unwrap_or(3)
}

/// A client endpoint, parsed when the config loads rather than checked afterwards.
///
/// Holding a `HttpBaseUrl` is proof the value is an absolute HTTP(S) URL, so no
/// later stage has to re-check it or can forget to.
#[derive(Clone, Debug)]
struct HttpBaseUrl(reqwest::Url);

impl HttpBaseUrl {
    fn as_str(&self) -> &str {
        self.0.as_str()
    }
}

impl<'de> Deserialize<'de> for HttpBaseUrl {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let raw = String::deserialize(deserializer)?;
        let url = reqwest::Url::parse(raw.trim()).map_err(|error| {
            serde::de::Error::custom(format!("base_url must be an absolute HTTP(S) URL: {error}"))
        })?;
        if !matches!(url.scheme(), "http" | "https") || url.host_str().is_none() {
            return Err(serde::de::Error::custom(
                "base_url must be an absolute HTTP(S) URL",
            ));
        }
        Ok(Self(url))
    }
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct LlmClientConfig {
    format: ClientFormat,
    base_url: HttpBaseUrl,
    /// Opt-in context discovery for VGR's efficient target. Unset disables discovery.
    context_discovery: Option<ContextDiscovery>,
    api_key_env: Option<String>,
    #[serde(default)]
    forward_auth: bool,
    #[serde(default)]
    extra_headers: BTreeMap<String, String>,
    #[serde(default = "default_max_retries")]
    max_retries: u32,
    #[serde(default = "default_fallback_on_rate_limit")]
    fallback_on_rate_limit: bool,
    /// Cooldown after an exhausted transient completion failure. Defaults to 5 seconds; zero disables it.
    #[serde(default = "default_failure_cooldown_ms")]
    failure_cooldown_ms: u64,
    /// Deadline in milliseconds for all attempts and the complete response. Unset is unbounded.
    timeout_ms: Option<u64>,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "snake_case")]
enum ContextDiscovery {
    LlamaCpp,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct DecisionClientConfig {
    format: DecisionFormat,
    endpoint: HttpBaseUrl,
    api_key_env: String,
    timeout_ms: u64,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "snake_case")]
enum DecisionFormat {
    SystemOne,
    OpenaiDecisions,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct DecisionTargetConfig {
    id: ModelId,
    decision_client: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct TargetConfig {
    id: ModelId,
    llm_client: String,
    #[serde(default)]
    extra_body: BTreeMap<String, Value>,
    /// Top-level request fields dropped from the outbound body before `extra_body` is merged.
    /// For providers that reject an otherwise standard field.
    #[serde(default)]
    omit_body_fields: BTreeSet<String>,
    system_prompt: Option<String>,
    /// Reasoning effort forced on every request to this target, replacing the caller's value.
    /// Only meaningful on `openai_chat` and `openai_responses` clients.
    reasoning_effort: Option<String>,
}

#[derive(Clone, Copy, Debug, Deserialize)]
enum ClientFormat {
    #[serde(rename = "openai_chat")]
    OpenAiChat,
    #[serde(rename = "openai_responses")]
    OpenAiResponses,
    #[serde(rename = "anthropic_messages")]
    AnthropicMessages,
}

impl ClientFormat {
    const fn wire_format(self) -> WireFormat {
        match self {
            Self::OpenAiChat => WireFormat::OpenAiChat,
            Self::OpenAiResponses => WireFormat::OpenAiResponses,
            Self::AnthropicMessages => WireFormat::AnthropicMessages,
        }
    }

    const fn caller_auth_kind(self) -> CallerAuthKind {
        match self {
            Self::AnthropicMessages => CallerAuthKind::Anthropic,
            Self::OpenAiChat | Self::OpenAiResponses => CallerAuthKind::OpenAi,
        }
    }
}

fn build_backend(
    client_name: &str,
    config: &LlmClientConfig,
    extra_body: &BTreeMap<String, Value>,
    omit_body_fields: &BTreeSet<String>,
    reasoning_effort: Option<String>,
) -> RunnerResult<Backend> {
    if config.max_retries > MAX_CONFIGURED_RETRIES {
        return Err(RunnerError::configuration(format!(
            "llm client {client_name} max_retries must be at most {MAX_CONFIGURED_RETRIES}"
        )));
    }
    if config.timeout_ms == Some(0) {
        return Err(RunnerError::configuration(format!(
            "llm client {client_name} timeout_ms must be at least 1"
        )));
    }
    if config.forward_auth && config.api_key_env.is_some() {
        return Err(RunnerError::configuration(format!(
            "llm client {client_name} cannot set both forward_auth and api_key_env"
        )));
    }
    let api_key = config
        .api_key_env
        .as_deref()
        .map(|variable| read_api_key(&format!("llm client {client_name}"), variable))
        .transpose()?;
    let http = HttpBackendConfig {
        base_url: config.base_url.as_str().to_string(),
        api_key,
        forward_auth: config.forward_auth,
        extra_headers: config.extra_headers.clone(),
        extra_body: extra_body.clone(),
        omit_body_fields: omit_body_fields.clone(),
        reasoning_effort,
        max_retries: config.max_retries,
        failure_cooldown: Duration::from_millis(config.failure_cooldown_ms),
        timeout: config.timeout_ms.map(Duration::from_millis),
    };
    let backend = match config.format {
        ClientFormat::OpenAiChat => Backend::OpenAiChat(http),
        ClientFormat::OpenAiResponses => Backend::OpenAiResponses(http),
        ClientFormat::AnthropicMessages => Backend::Anthropic(http),
    };
    Ok(backend)
}

fn read_api_key(client: &str, variable: &str) -> RunnerResult<String> {
    if variable.trim().is_empty() {
        return Err(RunnerError::configuration(format!(
            "{client} api_key_env must not be empty"
        )));
    }
    // A name with `=` is often a pasted `NAME=key` line, so this error omits the name.
    if variable.contains(['\0', '=']) {
        return Err(RunnerError::configuration(format!(
            "{client} api_key_env must not contain '=' or NUL"
        )));
    }
    let api_key = std::env::var(variable).map_err(|error| {
        // VarError can contain the raw credential, so errors report only its category.
        let reason = match error {
            std::env::VarError::NotPresent => "environment variable not found",
            std::env::VarError::NotUnicode(_) => "environment variable is not valid Unicode",
        };
        RunnerError::configuration(format!(
            "{client} could not read api_key_env {variable}: {reason}"
        ))
    })?;
    if api_key.trim().is_empty() {
        return Err(RunnerError::configuration(format!(
            "{client} api_key_env {variable} is empty"
        )));
    }
    Ok(api_key)
}

// A function so that serde default can use it.
const fn default_max_retries() -> u32 {
    DEFAULT_MAX_RETRIES
}

const fn default_fallback_on_rate_limit() -> bool {
    true
}

const fn default_failure_cooldown_ms() -> u64 {
    5000
}

fn validate_value(label: &str, value: &str) -> RunnerResult<()> {
    if value.trim().is_empty() || value.trim() != value {
        return Err(RunnerError::configuration(format!(
            "{label} must be non-empty and have no surrounding whitespace"
        )));
    }
    Ok(())
}

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

    #[test]
    fn route_presentation_fields_are_split_from_the_algorithm() {
        let route: RouteConfig = toml::from_str(
            r#"
type = "random"
id = "switchyard/random"
context_window = 128000
tool_calling = true
reasoning = false
targets = ["fast", "strong"]
weights = [1.0, 2.0]
seed = 7
"#,
        )
        .expect("route should deserialize");

        assert_eq!(route.id, "switchyard/random");
        assert_eq!(route.context_window, Some(128_000));
        assert_eq!(route.tool_calling, Some(true));
        assert_eq!(route.reasoning, Some(false));
        assert_eq!(route.algorithm.routing_target_names(), ["fast", "strong"]);
    }

    #[test]
    fn route_algorithm_unknown_fields_are_rejected() {
        let error = toml::from_str::<RouteConfig>(
            r#"
type = "passthrough"
id = "switchyard/fast"
target = "fast"
bogus = true
"#,
        )
        .expect_err("unknown route keys must be rejected");

        assert!(error.to_string().contains("bogus"), "{error}");
    }

    #[test]
    fn deployment_errors_keep_one_path_context() {
        let path = Path::new("/definitely/missing/switchyard-routes.toml");
        let error = match load_runner(path) {
            Ok(_) => panic!("missing config should fail"),
            Err(error) => error,
        };
        let message = error.to_string();

        assert_eq!(message.matches(&path.display().to_string()).count(), 1);
        assert!(message.starts_with("failed to read server config"));
    }
}
#[cfg(test)]
mod deployment_tests {
    use super::*;
    use serde_json::json;
    use switchyard_protocol::Category;

    const VALID_CONFIG: &str = r#"
schema_version = 1

[llm_clients.primary]
format = "openai_chat"
base_url = "https://example.test/v1"

[llm_clients.responses]
format = "openai_responses"
base_url = "https://example.test/v1"

[llm_clients.anthropic]
format = "anthropic_messages"
base_url = "https://example.test"

[targets.classifier]
id = "classifier/model"
llm_client = "primary"

[targets.strong]
id = "strong/model"
llm_client = "responses"

[targets.weak]
id = "weak/model"
llm_client = "anthropic"

[routes.noop]
id = "switchyard/noop"
type = "noop"

[routes.random]
id = "switchyard/random"
type = "random"
targets = ["strong", "weak"]

[routes.classifier]
id = "switchyard/classifier"
type = "llm_classifier"
classifier_target = "classifier"
strong_target = "strong"
weak_target = "weak"
base_threshold = 0.5

[routes.passthrough]
id = "switchyard/passthrough"
type = "passthrough"
target = "weak"

[routes.plan_execute]
id = "switchyard/plan-execute"
type = "plan_execute"
capable_target = "strong"
efficient_target = "weak"
"#;

    #[test]
    fn public_runner_from_toml_builds_a_deployment() -> RunnerResult<()> {
        let config = format!(
            "{VALID_CONFIG}\n[routes.classifier.infra]\n\
             max_signal_age_ms = 1000\nmin_waiting_requests = 4\nmax_capable_inflight = 2"
        );
        let runner = Runner::from_toml(&config)?;
        assert!(
            Runner::from_toml(
                &config.replace("min_waiting_requests = 4", "min_waiting_requests = 0")
            )
            .is_err()
        );

        let classifier = runner
            .route("switchyard/classifier")
            .expect("classifier route should exist");
        let models = classifier.models();
        assert_eq!(
            models.models_for(&Category::Judge),
            [ModelId::from("classifier/model")]
        );
        assert_eq!(
            models.models_for(&Category::Efficient),
            [ModelId::from("weak/model")]
        );
        assert_eq!(
            models.models_for(&Category::Capable),
            [ModelId::from("strong/model")]
        );
        assert_eq!(
            models.models_for(&Category::Any),
            [ModelId::from("weak/model"), ModelId::from("strong/model")]
        );
        let plan_execute = runner
            .route("switchyard/plan-execute")
            .expect("plan-execute route should exist");
        assert_eq!(
            plan_execute.models().models_for(&Category::Capable),
            [ModelId::from("strong/model")]
        );
        assert_eq!(
            plan_execute.models().models_for(&Category::Efficient),
            [ModelId::from("weak/model")]
        );
        assert!(runner.route("switchyard/passthrough").is_some());
        Ok(())
    }

    #[test]
    fn duplicate_route_ids_are_rejected() {
        let config = format!(
            r#"{VALID_CONFIG}

[routes.duplicate]
id = "switchyard/passthrough"
type = "passthrough"
target = "strong"
"#
        );

        let error = error_message(&config);

        assert!(
            error.contains(
                "routes duplicate and passthrough both use id switchyard/passthrough; route ids must be unique"
            ),
            "{error}"
        );
    }

    #[tokio::test]
    async fn plan_execute_applies_custom_tool_semantics() -> RunnerResult<()> {
        use switchyard_protocol::{ContentBlock, Message, Request, Role, ToolCall};

        let configured = format!(
            "{VALID_CONFIG}\n[routes.plan_execute.tool_semantics]\nmutate = [\"persist_source_file\"]"
        );
        let mut request = Request::default();
        request.llm_request.messages.push(Message {
            role: Role::Assistant,
            content: vec![ContentBlock::ToolCall(ToolCall {
                id: "write-1".to_string(),
                name: "mcp__files__Persist_Source_File".to_string(),
                arguments: json!({"path": "task.py", "content": "print('hello')"}),
            })],
        });

        for (config, expected) in [
            (VALID_CONFIG, "strong/model"),
            (configured.as_str(), "weak/model"),
        ] {
            let runner = Runner::from_toml(config)?;
            let route = runner.route("switchyard/plan-execute").unwrap();
            let outcome = route.decide(request.clone()).await?;
            assert_eq!(outcome.selected_model_ids[0], expected);
        }
        Ok(())
    }

    fn error_message(toml: &str) -> String {
        match runner_from_toml(toml) {
            Ok(_) => "configuration unexpectedly succeeded".to_string(),
            Err(error) => error.to_string(),
        }
    }

    fn vgr_config() -> String {
        format!(
            r#"{VALID_CONFIG}

[routes.vgr]
id = "switchyard/vgr"
type = "vgr"
efficient_target = "weak"
capable_target = "strong"
judge_target = "classifier"
mode = "active"
active_approval = "prospective-validation-and-canary-approved"
task_typing = false
"#
        )
    }

    #[test]
    fn vgr_compaction_is_opt_in_from_toml() -> RunnerResult<()> {
        for setting in ["", "compact_handoff = false", "compact_handoff = true"] {
            let source = format!("{}\nagentic_handoff = true\n{setting}\n", vgr_config());
            let parsed: DeploymentConfig = toml::from_str(&source).expect("valid VGR config");
            let AlgorithmSpec::Vgr { config } = &parsed.routes["vgr"].algorithm else {
                panic!("expected VGR route");
            };
            assert_eq!(config.compact_handoff, setting.ends_with("= true"));
            assert!(runner_from_toml(&source)?.route("switchyard/vgr").is_some());
        }
        Ok(())
    }

    #[test]
    fn vgr_route_builds_and_rejects_unsafe_configuration() -> RunnerResult<()> {
        let runner = runner_from_toml(&vgr_config())?;
        assert!(runner.route("switchyard/vgr").is_some());

        let compact = format!("{}\ncompact_handoff = true\n", vgr_config());
        assert!(error_message(&compact).contains("compact_handoff requires agentic_handoff"));
        let compact = format!("{compact}\nagentic_handoff = true\n");
        assert!(
            runner_from_toml(&compact)?
                .route("switchyard/vgr")
                .is_some()
        );

        let identical_ids = vgr_config().replace(
            "efficient_target = \"weak\"",
            "efficient_target = \"strong\"",
        );
        assert!(error_message(&identical_ids).contains("distinct efficient and capable model IDs"));

        let bad_approval =
            vgr_config().replace("prospective-validation-and-canary-approved", "approved");
        assert!(error_message(&bad_approval).contains("approval attestation"));

        let missing_target = vgr_config().replace(
            "efficient_target = \"weak\"",
            "efficient_target = \"missing\"",
        );
        assert!(error_message(&missing_target).contains("unknown target missing"));

        let zero_cooldown = format!("{}breaker_cooldown_seconds = 0\n", vgr_config());
        assert!(
            error_message(&zero_cooldown).contains("breaker_cooldown_seconds must be a positive")
        );
        Ok(())
    }

    #[test]
    fn vgr_local_server_example_builds_and_rejects_unknown_discovery() -> RunnerResult<()> {
        let example = include_str!("../../../examples/vgr-local-servers.toml");
        let runner = runner_from_toml(example)?;
        assert!(runner.route("switchyard/vgr").is_some());
        let invalid = example.replace(
            "context_discovery = \"llama_cpp\"",
            "context_discovery = \"guess\"",
        );
        assert!(error_message(&invalid).contains("unknown variant `guess`"));
        Ok(())
    }

    fn with_subagent_llm_classifier(config: &str, route: &str, extra: &str) -> String {
        let mut configured = config.to_string();
        configured.push_str(&format!("\n[routes.{route}.subagents]\n"));
        configured.push_str(
            r#"type = "llm_classifier"
mode = "custom"
models = { judge = ["classifier"], capable = ["strong"], efficient = ["weak"], any = ["strong", "weak"] }
default_target = "efficient"
prompt = "Select a target for this delegated task."
response_schema = '{"type":"object","properties":{"target":{"type":"string","enum":["capable","efficient"]}},"required":["target"],"additionalProperties":false}'
policy = { type = "target_selector", selector = "/target" }
classify_trigger = "new_session""#,
        );
        configured.push_str(extra);
        configured
    }

    #[test]
    fn subagent_models_stay_separate_from_the_parent_tiers() -> RunnerResult<()> {
        // The sub-agent target is also the parent's capable tier. Merged into one group it
        // would be indistinguishable from that tier, and delegated work would follow the
        // parent's ordering instead of its own configured target.
        let runner = runner_from_toml(&with_subagent_passthrough(&stage_config(), "stage"))?;
        let models = runner
            .route("switchyard/stage")
            .expect("stage route should exist")
            .models();

        assert_eq!(
            models.subagent_models_for(&Category::Any),
            [ModelId::from("strong/model")]
        );
        assert_eq!(
            models.models_for(&Category::Any),
            [ModelId::from("strong/model"), ModelId::from("weak/model")]
        );
        Ok(())
    }

    fn with_subagent_passthrough(config: &str, route: &str) -> String {
        format!("{config}\n[routes.{route}.subagents]\ntype = \"passthrough\"\ntarget = \"strong\"")
    }

    fn stage_config() -> String {
        format!(
            r#"{VALID_CONFIG}
[targets.stage_judge]
id = "stage-judge/model"
llm_client = "primary"

[routes.stage]
id = "switchyard/stage"
type = "stage_router"
capable_target = "strong"
efficient_target = "weak"
picker = "efficient_first"
confidence_threshold = 1.0
capable_hold_turns = 2

[routes.stage.tool_semantics]
observe = ["lookup_customer"]
mutate = ["send_payment"]
plan = ["create_workflow"]
new = ["send_message"]

[routes.stage.classifier]
target = "stage_judge"
base_threshold = 0.5
"#
        )
    }

    fn composite_config() -> String {
        format!(
            r#"{VALID_CONFIG}
[targets.tier_judge]
id = "tier-judge/model"
llm_client = "primary"

[routes.composed]
id = "switchyard/hier"
type = "composite"

[routes.composed.classifier]
target = "tier_judge"
base_threshold = 0.5
classify_trigger = "user_turn"

[routes.composed.stage]
capable_target = "strong"
efficient_target = "weak"
confidence_threshold = 0.5
capable_hold_turns = 2

[routes.composed.stage.tool_semantics]
new = ["send_message"]
"#
        )
    }

    #[test]
    fn stage_and_composite_validate_hold_turns() {
        for source in [
            stage_config(),
            stage_config().replace("efficient_first", "capable_first"),
            composite_config(),
        ] {
            for field in ["capable_hold_turns", "efficient_hold_turns"] {
                for (turns, valid) in [
                    (-2_i64, false),
                    (-1, true),
                    (0, true),
                    (3, true),
                    (i64::from(u32::MAX), true),
                    (i64::from(u32::MAX) + 1, false),
                ] {
                    let configured =
                        source.replace("capable_hold_turns = 2", &format!("{field} = {turns}"));
                    let result = runner_from_toml(&configured);
                    assert_eq!(result.is_ok(), valid, "{field} = {turns}");
                    if let Err(error) = result {
                        assert!(error.to_string().contains(field), "{error}");
                    }
                }
            }
        }
    }

    #[test]
    fn composite_decision_judge_reuses_capability_validation() {
        let source = composite_config().replace(
            "[routes.composed.classifier]\ntarget = \"tier_judge\"\nbase_threshold = 0.5",
            "[routes.composed.classifier]\ntarget = \"tier_judge\"",
        ) + r#"
[routes.composed.classifier.decision]
cutoff = 0.4
candidates = { a = "strong", b = "weak" }
evidence = { description = "candidate comparison" }
"#;
        for (source, valid) in [
            (source.clone(), true),
            (
                source.replace(
                    "target = \"tier_judge\"",
                    "target = \"tier_judge\"\nbase_threshold = 0.5",
                ),
                false,
            ),
            (source.replace("b = \"weak\"", "b = \"strong\""), false),
        ] {
            let deployment: DeploymentConfig = toml::from_str(&source).unwrap();
            let spec = &deployment.routes["composed"].algorithm;
            assert_eq!(spec.decision_judge().unwrap().0, "tier_judge");
            assert_eq!(
                spec.build_with_runtime_models("composed", &deployment.build_targets())
                    .is_ok(),
                valid
            );
        }
    }

    #[test]
    fn composite_custom_judge_builds_and_rejects_capability_settings() -> RunnerResult<()> {
        let source = composite_config().replace(
            "base_threshold = 0.5\nclassify_trigger",
            r#"mode = "custom"
prompt = 'Select efficient or capable.'
response_schema = '{"type":"object","properties":{"decision":{"type":"object","properties":{"target":{"type":"string","enum":["efficient","capable"]}},"required":["target"],"additionalProperties":false}},"required":["decision"],"additionalProperties":false}'
policy = { type = "target_selector", selector = "/decision/target" }
classify_trigger"#,
        );
        runner_from_toml(&source)?;
        runner_from_toml(
            &source.replace("mode = \"custom\"", "mode = \"custom\"\nfail_open = true"),
        )?;
        for (setting, expected) in [
            (
                "base_threshold = 0.5",
                "composite custom classifier cannot use capability thresholds",
            ),
            (
                "fail_open = false",
                "composite custom classifiers always fail open",
            ),
        ] {
            let invalid = source.replace(
                "mode = \"custom\"",
                &format!("mode = \"custom\"\n{setting}"),
            );
            assert!(error_message(&invalid).contains(expected));
        }
        Ok(())
    }

    #[test]
    fn composite_route_builds_and_claims_both_tiers_and_its_judge() -> RunnerResult<()> {
        let runner = runner_from_toml(&composite_config())?;
        assert!(
            runner
                .models()
                .any(|model| model.id.as_str() == "switchyard/hier")
        );
        Ok(())
    }

    #[test]
    fn builds_all_supported_algorithm_types() -> RunnerResult<()> {
        let state = runner_from_toml(VALID_CONFIG)?;
        // The model id array is sorted alphabetically
        assert_eq!(
            state
                .models()
                .map(|model| model.id.as_str())
                .collect::<Vec<_>>(),
            [
                "switchyard/classifier",
                "switchyard/noop",
                "switchyard/passthrough",
                "switchyard/plan-execute",
                "switchyard/random",
            ]
        );
        Ok(())
    }

    #[test]
    fn stage_rejects_ambiguous_or_non_additive_tool_semantics() {
        for (configured, expected) in [
            (
                stage_config().replace(
                    "mutate = [\"send_payment\"]",
                    "mutate = [\"LOOKUP_CUSTOMER\"]",
                ),
                "appears in both tool_semantics.observe and tool_semantics.mutate",
            ),
            (
                stage_config().replace("new = [\"send_message\"]", "new = [\"Read\"]"),
                "already has built-in semantics and cannot be reclassified",
            ),
            (
                stage_config().replace("observe = [\"lookup_customer\"]", "observe = [\" \"]"),
                "contains an empty tool name",
            ),
        ] {
            let message = error_message(&configured);
            assert!(
                message.contains(expected),
                "expected {expected:?} in error, got: {message}"
            );
        }
    }

    #[test]
    fn passthrough_and_stage_accept_subagent_routing() -> RunnerResult<()> {
        let stage = stage_config();
        let stage_with_classifier = with_subagent_llm_classifier(&stage, "stage", "");
        let parsed: DeploymentConfig = toml::from_str(&stage_with_classifier).map_err(|error| {
            RunnerError::configuration(format!("failed to parse stage config: {error}"))
        })?;
        let Some(stage_route) = parsed.routes.get("stage") else {
            return Err(RunnerError::configuration("stage route is missing"));
        };
        let callable_targets = stage_route.callable_target_names();
        for expected in ["strong", "weak", "stage_judge", "classifier"] {
            assert!(callable_targets.contains(&expected));
        }

        for configured in [
            with_subagent_llm_classifier(VALID_CONFIG, "passthrough", ""),
            with_subagent_passthrough(VALID_CONFIG, "passthrough"),
            stage_with_classifier,
            with_subagent_passthrough(&stage, "stage"),
        ] {
            runner_from_toml(&configured)?;
        }
        Ok(())
    }

    #[test]
    fn aliased_completion_targets_reject_prompt_conflicts() {
        let configured = stage_config()
            .replace(
                "id = \"strong/model\"\nllm_client = \"responses\"",
                "id = \"strong/model\"\nllm_client = \"responses\"\nsystem_prompt = \"capable\"",
            )
            .replace(
                "[routes.stage]",
                "[targets.strong_alias]\nid = \"strong/model\"\nllm_client = \"responses\"\n\n[routes.stage]",
            )
            .replace("efficient_target = \"weak\"", "efficient_target = \"strong_alias\"");
        let message = error_message(&configured);
        assert!(
            message.contains("completion target aliases to model strong/model with different system_prompt values"),
            "unexpected error: {message}"
        );
    }

    #[test]
    fn prompted_routing_response_cannot_share_a_model_with_a_dependency() {
        let configured = VALID_CONFIG
            .replace(
                "id = \"classifier/model\"\nllm_client = \"primary\"",
                "id = \"weak/model\"\nllm_client = \"primary\"",
            )
            .replace(
                "id = \"weak/model\"\nllm_client = \"anthropic\"",
                "id = \"weak/model\"\nllm_client = \"anthropic\"\nsystem_prompt = \"answer prompt\"",
            )
            .replace(
                "base_threshold = 0.5",
                "base_threshold = 0.5\nescalation = { confirmations = 1 }",
            );

        let message = error_message(&configured);

        assert!(
            message.contains("cannot apply system_prompt to target weak: model weak/model is also used by routing-only target classifier"),
            "unexpected error: {message}"
        );
    }

    #[test]
    fn rejects_invalid_unreferenced_llm_client() {
        for (settings, expected) in [
            (
                "base_url = \"not a url\"",
                "base_url must be an absolute HTTP(S) URL",
            ),
            (
                "base_url = \"https://example.test\"\ntimeout_ms = 0",
                "timeout_ms must be at least 1",
            ),
        ] {
            let invalid = format!(
                "{VALID_CONFIG}\n[llm_clients.unused]\nformat = \"openai_chat\"\n{settings}"
            );
            let message = error_message(&invalid);
            assert!(message.contains(expected), "unexpected error: {message}");
        }
    }

    #[test]
    fn an_escalation_table_switches_the_classifier_route_to_escalation() -> RunnerResult<()> {
        // Present: the classifier target judges the weak tier's reply each turn instead of
        // picking a tier ahead of it. The route builds either way, so the assertion is that
        // the knob parses and its settings reach the algorithm's validation.
        let escalating = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nescalation = { confirmations = 2 }",
        );
        runner_from_toml(&escalating)?;

        let reversible = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nescalation = { confirmations = 2, deescalation = { strong_min_calls = 3, confirmations = 2, strong_max_calls = 6, weak_cooldown_calls = 8 } }",
        );
        runner_from_toml(&reversible)?;

        // A setting that would starve the judge is rejected here rather than on the first
        // request, the same as any other unusable route configuration.
        let starved = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nescalation = { confirmations = 0 }",
        );
        assert!(error_message(&starved).contains("confirmations must be at least 1"));

        Ok(())
    }

    #[test]
    fn a_target_reasoning_effort_parses_and_is_rejected_where_unsupported() -> RunnerResult<()> {
        let strong = "[targets.strong]\nid = \"strong/model\"\nllm_client = \"responses\"";
        let weak = "[targets.weak]\nid = \"weak/model\"\nllm_client = \"anthropic\"";
        assert!(VALID_CONFIG.contains(strong) && VALID_CONFIG.contains(weak));

        let forced = VALID_CONFIG.replace(strong, &format!("{strong}\nreasoning_effort = \"max\""));
        runner_from_toml(&forced)?;

        let blank = VALID_CONFIG.replace(strong, &format!("{strong}\nreasoning_effort = \" \""));
        assert!(error_message(&blank).contains("reasoning_effort must not be empty"));

        let anthropic = VALID_CONFIG.replace(weak, &format!("{weak}\nreasoning_effort = \"high\""));
        assert!(
            error_message(&anthropic)
                .contains("only supported on openai_chat and openai_responses")
        );
        Ok(())
    }

    #[test]
    fn duplicate_targets_with_conflicting_settings_are_rejected() -> RunnerResult<()> {
        let strong = "[targets.strong]\nid = \"strong/model\"\nllm_client = \"responses\"";
        assert!(VALID_CONFIG.contains(strong));
        // Same model, same client, different effort: the second target could never take effect.
        let conflicting = VALID_CONFIG.replace(
            strong,
            &format!(
                "{strong}\n\n[targets.strong_max]\nid = \"strong/model\"\nllm_client = \"responses\"\nreasoning_effort = \"max\""
            ),
        );
        assert!(
            error_message(&conflicting)
                .contains("different reasoning_effort, extra_body, or omit_body_fields"),
            "{}",
            error_message(&conflicting)
        );
        // An alias with identical settings is still allowed (it only warns).
        let alias = VALID_CONFIG.replace(
            strong,
            &format!("{strong}\n\n[targets.strong_alias]\nid = \"strong/model\"\nllm_client = \"responses\""),
        );
        runner_from_toml(&alias)?;
        Ok(())
    }

    #[test]
    fn classifier_judge_completion_caps_are_configurable() -> RunnerResult<()> {
        let capability = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nmax_output_tokens = 512",
        );
        runner_from_toml(&capability)?;

        let escalation = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nmax_output_tokens = 256\nescalation = { confirmations = 2 }",
        );
        runner_from_toml(&escalation)?;
        Ok(())
    }

    #[test]
    fn classifier_prompts_are_configurable_in_both_modes() -> RunnerResult<()> {
        let capability = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nprompt = \"custom capability rubric\"",
        );
        runner_from_toml(&capability)?;

        let escalation = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nprompt = \"custom trajectory rubric\"\nescalation = { confirmations = 2 }",
        );
        runner_from_toml(&escalation)?;

        let empty = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nprompt = \"   \"",
        );
        assert!(error_message(&empty).contains("classifier prompt must not be empty"));

        let schema_placeholder = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nprompt = \"{{RESPONSE_SCHEMA}}\"",
        );
        assert!(
            error_message(&schema_placeholder)
                .contains("Switchyard supplies the schema automatically")
        );
        Ok(())
    }

    #[test]
    fn mode_custom_rejects_capability_fields() {
        let mixed = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "mode = \"custom\"\nbase_threshold = 0.5",
        );

        assert!(
            error_message(&mixed)
                .contains("mode custom cannot use capability or escalation fields")
        );
    }

    #[test]
    fn stage_router_rejects_an_unknown_field() {
        let config = stage_config().replace(
            "picker = \"efficient_first\"",
            "picker = \"efficient_first\"\nmagic = true",
        );
        assert!(error_message(&config).contains("unknown field"));
    }

    #[test]
    fn auto_route_builds_a_stage_router_with_no_extra_fields() -> RunnerResult<()> {
        let config = format!(
            r#"{VALID_CONFIG}
[routes.auto]
id = "switchyard/auto"
type = "auto"
capable_target = "strong"
efficient_target = "weak"
"#
        );
        let runner = runner_from_toml(&config)?;
        assert!(runner.route("switchyard/auto").is_some());
        Ok(())
    }

    #[test]
    fn composite_stage_block_rejects_an_unknown_field() {
        let config = composite_config().replace(
            "confidence_threshold = 0.5",
            "confidence_threshold = 0.5\nmagic = true",
        );
        assert!(error_message(&config).contains("unknown field"));
    }

    #[test]
    fn rejects_unknown_fields_and_algorithm_types() {
        let unknown_field =
            VALID_CONFIG.replace("schema_version = 1", "schema_version = 1\nmagic = true");
        assert!(error_message(&unknown_field).contains("unknown field"));

        let nested_completion_cap = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nescalation = { max_output_tokens = 256 }",
        );
        assert!(error_message(&nested_completion_cap).contains("unknown field"));

        let unknown_classifier_field = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.5\nclassifier_magic = true",
        );
        assert!(error_message(&unknown_classifier_field).contains("unknown field"));

        let target_capability = VALID_CONFIG.replace(
            "llm_client = \"responses\"",
            "llm_client = \"responses\"\ncontext_window = 1000000",
        );
        assert!(error_message(&target_capability).contains("unknown field `context_window`"));

        let unknown_algorithm = VALID_CONFIG.replace("type = \"noop\"", "type = \"imaginary\"");
        assert!(error_message(&unknown_algorithm).contains("unknown variant"));
    }

    #[test]
    fn rejects_unknown_stage_classifier_fields() {
        // Nested classifier typos must fail instead of silently using a default.
        let config = format!(
            r#"{VALID_CONFIG}

[routes.stage]
id = "switchyard/stage"
type = "stage_router"
capable_target = "strong"
efficient_target = "weak"
picker = "efficient_first"
confidence_threshold = 1.0

[routes.stage.classifier]
target = "classifier"
base_threshold = 0.5
classifier_magic = true
"#
        );

        let error = error_message(&config);
        assert!(
            error.contains("unknown field `classifier_magic`"),
            "{error}"
        );
    }

    #[test]
    fn rejects_invalid_references_and_parameters() {
        let cases = [
            (
                VALID_CONFIG.replace("llm_client = \"primary\"", "llm_client = \"missing\""),
                "unknown llm client missing",
            ),
            (
                VALID_CONFIG.replace(
                    "targets = [\"strong\", \"weak\"]",
                    "targets = [\"strong\", \"missing\"]",
                ),
                "unknown target missing",
            ),
            (
                VALID_CONFIG.replace(
                    "targets = [\"strong\", \"weak\"]",
                    "targets = [\"strong\", \"weak\"]\nweights = [0, 0]",
                ),
                "at least one weight must be positive",
            ),
            (
                VALID_CONFIG.replace(
                    "targets = [\"strong\", \"weak\"]",
                    "targets = [\"strong\", \"strong\"]",
                ),
                "targets must be unique, strong is repeated",
            ),
            (
                VALID_CONFIG.replace(
                    "targets = [\"strong\", \"weak\"]",
                    "targets = [\"strong\", \"weak\"]\nweights = [1]",
                ),
                "expected 2 weights, got 1",
            ),
            (
                VALID_CONFIG.replace("base_threshold = 0.5", "base_threshold = 1.5"),
                "base_threshold must be between 0 and 1",
            ),
            (
                VALID_CONFIG.replace("classifier_target = \"classifier\"\n", ""),
                "route references unknown target",
            ),
            (
                VALID_CONFIG.replace(
                    "classifier_target = \"classifier\"",
                    "classifier_target = \"\"",
                ),
                "route references unknown target",
            ),
            (
                VALID_CONFIG.replace(
                    "classifier_target = \"classifier\"",
                    "classifier_target = \"   \"",
                ),
                "route references unknown target",
            ),
            (
                VALID_CONFIG.replace(
                    "base_threshold = 0.5",
                    "base_threshold = 0.5\nthreshold_step = -0.1",
                ),
                "threshold_step must be finite and greater than or equal to 0",
            ),
            (
                VALID_CONFIG.replace(
                    "base_threshold = 0.5",
                    "base_threshold = 0.8\nthreshold_step = 0.11",
                ),
                "base_threshold + 2 * threshold_step must be at most 1",
            ),
            (
                VALID_CONFIG.replace(
                    "base_threshold = 0.5",
                    "base_threshold = 0.5\nmax_output_tokens = 0\nescalation = { confirmations = 2 }",
                ),
                "max_output_tokens must be at least 1",
            ),
            (
                VALID_CONFIG.replace(
                    "base_threshold = 0.5",
                    "base_threshold = 0.5\nmessage_hash_fallback = true",
                ),
                "message_hash_fallback requires classify_trigger = new_session",
            ),
            (
                with_subagent_llm_classifier(
                    VALID_CONFIG,
                    "passthrough",
                    "\nmessage_hash_fallback = true",
                ),
                "cannot use message_hash_fallback",
            ),
            (
                with_subagent_llm_classifier(VALID_CONFIG, "passthrough", "")
                    .replace("mode = \"custom\"", "mode = \"capability\""),
                "mode capability cannot use custom classifier fields",
            ),
            (
                VALID_CONFIG.replace(
                    "base_threshold = 0.5",
                    "escalation = { confirmations = 2 }\nclassify_trigger = \"user_turn\"",
                ),
                "mode escalation cannot use classify_trigger",
            ),
            (
                VALID_CONFIG.replace("schema_version = 1", "schema_version = 2"),
                "unsupported schema_version 2",
            ),
            (
                VALID_CONFIG.replace("[targets.strong]", "[targets.\" strong \"]"),
                "target name must be non-empty and have no surrounding whitespace",
            ),
            (
                VALID_CONFIG.replace(
                    "targets = [\"strong\", \"weak\"]",
                    "targets = [\"strong\", \"weak\"]\ncontext_window = 0",
                ),
                "route random context_window must be greater than zero",
            ),
        ];

        for (toml, expected) in cases {
            let error = error_message(&toml);
            assert!(
                error.contains(expected),
                "expected error containing {expected}, got {error}"
            );
        }
    }

    #[test]
    fn accepts_duplicate_target_model_ids_on_one_client() -> RunnerResult<()> {
        // Two targets share one model id on one client. The client keeps one and drops the
        // other, so the build warns and still succeeds, and both routes resolve. Serving one
        // model under two route names this way is allowed; pointing both routes at one target
        // is the tidier form.
        const SAME_MODEL_TWO_ROUTES: &str = r#"
schema_version = 1

[llm_clients.primary]
format = "openai_chat"
base_url = "https://example.test/v1"

[targets.fast]
id = "gpt-4o"
llm_client = "primary"

[targets.smart]
id = "gpt-4o"
llm_client = "primary"

[routes.fast]
id = "switchyard/fast"
type = "passthrough"
target = "fast"

[routes.smart]
id = "switchyard/smart"
type = "passthrough"
target = "smart"
"#;
        let state = runner_from_toml(SAME_MODEL_TWO_ROUTES)?;
        assert_eq!(
            state
                .models()
                .map(|model| model.id.as_str())
                .collect::<Vec<_>>(),
            ["switchyard/fast", "switchyard/smart"]
        );
        Ok(())
    }

    #[test]
    fn accepts_same_model_id_on_different_llm_clients() -> RunnerResult<()> {
        // Separate routes may serve the same model through different clients.
        const CROSS_PROVIDER: &str = r#"
schema_version = 1

[llm_clients.openai]
format = "openai_chat"
base_url = "https://example.test/v1"

[llm_clients.azure]
format = "openai_chat"
base_url = "https://azure.test/v1"

[targets.openai]
id = "gpt-4o"
llm_client = "openai"

[targets.azure]
id = "gpt-4o"
llm_client = "azure"

[routes.openai]
id = "switchyard/openai-gpt4o"
type = "passthrough"
target = "openai"

[routes.azure]
id = "switchyard/azure-gpt4o"
type = "passthrough"
target = "azure"
"#;
        runner_from_toml(CROSS_PROVIDER)?;
        let shared_route = format!(
            r#"{CROSS_PROVIDER}

[routes.shared]
id = "switchyard/shared"
type = "stage_router"
capable_target = "openai"
efficient_target = "azure"
picker = "efficient_first"
confidence_threshold = 0.5
"#
        );
        let message = error_message(&shared_route);
        assert!(
            message.contains("route shared")
                && message.contains("openai")
                && message.contains("azure")
                && message.contains("gpt-4o")
                && message.contains("different llm clients"),
            "{message}"
        );
        Ok(())
    }

    #[test]
    fn accepts_relative_weights_and_seed() -> RunnerResult<()> {
        let weighted = VALID_CONFIG.replace(
            "targets = [\"strong\", \"weak\"]",
            "targets = [\"strong\", \"weak\"]\nweights = [1, 3]\nseed = 42",
        );
        runner_from_toml(&weighted)?;
        Ok(())
    }

    #[test]
    fn accepts_new_session_trigger_with_message_hash_fallback() -> RunnerResult<()> {
        let configured = VALID_CONFIG.replace(
            "base_threshold = 0.5",
            "base_threshold = 0.25\nthreshold_step = 0.1\nclassify_trigger = \"new_session\"\nmessage_hash_fallback = true",
        );
        runner_from_toml(&configured)?;
        Ok(())
    }

    #[test]
    fn target_extra_body_is_parsed_and_applied_to_its_backend() -> RunnerResult<()> {
        let configured = VALID_CONFIG.replacen(
            "llm_client = \"primary\"",
            "llm_client = \"primary\"\n\
             extra_body = { service_tier = \"priority\", \
             chat_template_kwargs = { enable_thinking = false } }",
            1,
        );
        let config: DeploymentConfig = toml::from_str(&configured).map_err(|error| {
            RunnerError::configuration(format!("failed to parse config: {error}"))
        })?;
        let Some(target) = config.targets.get("classifier") else {
            return Err(RunnerError::configuration("classifier target is missing"));
        };
        let Some(client) = config.llm_clients.get("primary") else {
            return Err(RunnerError::configuration("primary llm client is missing"));
        };
        let backend = build_backend(
            "primary",
            client,
            &target.extra_body,
            &target.omit_body_fields,
            None,
        )?;

        assert_eq!(
            backend.extra_body().get("service_tier"),
            Some(&json!("priority"))
        );
        assert_eq!(
            backend
                .extra_body()
                .get("chat_template_kwargs")
                .and_then(|value| value.get("enable_thinking")),
            Some(&json!(false))
        );
        Ok(())
    }

    #[test]
    fn target_omit_body_fields_is_parsed_and_applied_to_its_backend() -> RunnerResult<()> {
        let configured = VALID_CONFIG.replacen(
            "llm_client = \"primary\"",
            "llm_client = \"primary\"\n\
             omit_body_fields = [\"max_output_tokens\"]",
            1,
        );
        let config: DeploymentConfig = toml::from_str(&configured).map_err(|error| {
            RunnerError::configuration(format!("failed to parse config: {error}"))
        })?;
        let Some(target) = config.targets.get("classifier") else {
            return Err(RunnerError::configuration("classifier target is missing"));
        };
        let Some(client) = config.llm_clients.get("primary") else {
            return Err(RunnerError::configuration("primary llm client is missing"));
        };
        let backend = build_backend(
            "primary",
            client,
            &target.extra_body,
            &target.omit_body_fields,
            None,
        )?;

        assert!(backend.omit_body_fields().contains("max_output_tokens"));
        Ok(())
    }

    #[test]
    fn client_deadline_defaults_and_rejects_zero() -> RunnerResult<()> {
        for (setting, expected) in [
            ("", None),
            ("timeout_ms = 1500", Some(1500)),
            ("timeout_ms = 0", Some(0)),
        ] {
            let source = format!(
                "format = \"openai_chat\"\nbase_url = \"https://example.test/v1\"\n{setting}"
            );
            let config: LlmClientConfig = toml::from_str(&source).expect("valid deadline config");
            let backend = build_backend("test", &config, &BTreeMap::new(), &BTreeSet::new(), None);
            if expected == Some(0) {
                assert!(backend.is_err());
            } else {
                assert_eq!(backend?.timeout(), expected.map(Duration::from_millis));
            }
        }
        Ok(())
    }

    #[test]
    fn retry_budget_defaults_and_accepts_an_override() -> RunnerResult<()> {
        let default: DeploymentConfig = toml::from_str(VALID_CONFIG).map_err(|error| {
            RunnerError::configuration(format!("failed to parse default config: {error}"))
        })?;
        let Some(primary) = default.llm_clients.get("primary") else {
            return Err(RunnerError::configuration("primary llm client is missing"));
        };
        assert_eq!(primary.max_retries, DEFAULT_MAX_RETRIES);

        let explicit = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            "base_url = \"https://example.test/v1\"\nmax_retries = 0",
            1,
        );
        let config: DeploymentConfig = toml::from_str(&explicit).map_err(|error| {
            RunnerError::configuration(format!("failed to parse explicit retry config: {error}"))
        })?;
        let Some(primary) = config.llm_clients.get("primary") else {
            return Err(RunnerError::configuration("primary llm client is missing"));
        };
        assert_eq!(primary.max_retries, 0);

        let maximum = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            &format!(
                "base_url = \"https://example.test/v1\"\nmax_retries = {MAX_CONFIGURED_RETRIES}"
            ),
            1,
        );
        let config: DeploymentConfig = toml::from_str(&maximum).map_err(|error| {
            RunnerError::configuration(format!("failed to parse maximum retry config: {error}"))
        })?;
        let Some(primary) = config.llm_clients.get("primary") else {
            return Err(RunnerError::configuration("primary llm client is missing"));
        };
        assert_eq!(primary.max_retries, MAX_CONFIGURED_RETRIES);
        Ok(())
    }

    #[test]
    fn rejects_headers_that_switchyard_sets() {
        let cases = [
            (
                "base_url = \"https://example.test/v1\"",
                "base_url = \"https://example.test/v1\"\n\
                 extra_headers = { AUTHORIZATION = \"Bearer custom-key\" }",
                "AUTHORIZATION",
            ),
            (
                "base_url = \"https://example.test\"",
                "base_url = \"https://example.test\"\n\
                 extra_headers = { \"X-Api-Key\" = \"custom-key\" }",
                "X-Api-Key",
            ),
            (
                "base_url = \"https://example.test\"",
                "base_url = \"https://example.test\"\n\
                 extra_headers = { \"ANTHROPIC-VERSION\" = \"custom-version\" }",
                "ANTHROPIC-VERSION",
            ),
        ];

        for (original, replacement, header) in cases {
            let configured = VALID_CONFIG.replacen(original, replacement, 1);
            let error = error_message(&configured);
            assert!(
                error.contains(&format!("extra_headers cannot set {header:?}")),
                "expected {header} to be rejected, got: {error}"
            );
        }
    }

    #[test]
    fn accepts_additional_headers() -> RunnerResult<()> {
        let configured = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            "base_url = \"https://example.test/v1\"\n\
             extra_headers = { X-Inference-Priority = \"batch\" }",
            1,
        );

        runner_from_toml(&configured)?;
        Ok(())
    }

    #[test]
    fn retry_budget_rejects_negative_values() {
        let invalid = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            "base_url = \"https://example.test/v1\"\nmax_retries = -1",
            1,
        );
        assert!(error_message(&invalid).contains("max_retries"));
    }

    #[test]
    fn retry_budget_rejects_excessive_values() {
        let invalid = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            "base_url = \"https://example.test/v1\"\nmax_retries = 11",
            1,
        );
        assert!(
            error_message(&invalid).contains("llm client primary max_retries must be at most 10")
        );
    }

    #[test]
    fn api_key_environment_reference_is_validated() {
        let missing = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            "base_url = \"https://example.test/v1\"\napi_key_env = \"SWITCHYARD_CONFIG_TEST_KEY_THAT_IS_NOT_SET\"",
            1,
        );
        assert!(error_message(&missing).contains("SWITCHYARD_CONFIG_TEST_KEY_THAT_IS_NOT_SET"));

        const EMPTY_KEY_ENV: &str = "SWITCHYARD_CONFIG_TEST_EMPTY_KEY";
        unsafe {
            // "unsafe" is for concurrent reads and writes, very rare
            std::env::set_var(EMPTY_KEY_ENV, "");
        }
        let empty = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            &format!("base_url = \"https://example.test/v1\"\napi_key_env = \"{EMPTY_KEY_ENV}\""),
            1,
        );
        let message = error_message(&empty);
        unsafe {
            std::env::remove_var(EMPTY_KEY_ENV);
        }
        assert!(message.contains("is empty"));

        // macOS reads `FOO` for the name `FOO=x`, so the config would use another variable. A
        // name with `=` is often a pasted `NAME=key` line, so the error leaves it out.
        let with_equals = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            "base_url = \"https://example.test/v1\"\napi_key_env = \"NVIDIA_API_KEY=DUMMY_SECRET_DO_NOT_LOG\"",
            1,
        );
        let message = error_message(&with_equals);
        assert!(message.contains("llm client primary api_key_env must not contain '=' or NUL"));
        assert!(!message.contains("DUMMY_SECRET_DO_NOT_LOG"), "{message}");
    }

    // `VarError::NotUnicode` holds the variable's value, so printing that error prints the key.
    #[cfg(any(unix, windows))]
    #[test]
    fn invalid_unicode_api_key_is_not_printed() {
        const RAW_KEY_ENV: &str = "SWITCHYARD_CONFIG_TEST_RAW_KEY";
        #[cfg(unix)]
        let raw = {
            use std::os::unix::ffi::OsStringExt;
            let mut bytes = b"DUMMY_SECRET_DO_NOT_LOG".to_vec();
            bytes.push(0xff);
            std::ffi::OsString::from_vec(bytes)
        };
        #[cfg(windows)]
        let raw = {
            use std::os::windows::ffi::OsStringExt;
            let mut words: Vec<_> = "DUMMY_SECRET_DO_NOT_LOG".encode_utf16().collect();
            words.push(0xd800);
            std::ffi::OsString::from_wide(&words)
        };
        unsafe {
            // "unsafe" is for concurrent reads and writes, very rare
            std::env::set_var(RAW_KEY_ENV, raw);
        }
        let result = read_api_key("llm client fixture", RAW_KEY_ENV);
        unsafe {
            std::env::remove_var(RAW_KEY_ENV);
        }
        let error = result.expect_err("invalid Unicode credential").to_string();
        assert!(error.contains("not valid Unicode"), "{error}");
        assert!(!error.contains("DUMMY_SECRET_DO_NOT_LOG"), "{error}");
    }

    #[test]
    fn forward_auth_rejects_conflicting_credentials() {
        let competing_auth = VALID_CONFIG.replacen(
            "base_url = \"https://example.test/v1\"",
            "base_url = \"https://example.test/v1\"\n\
                 forward_auth = true\n\
                 api_key_env = \"UNUSED_TEST_KEY\"",
            1,
        );
        assert!(
            error_message(&competing_auth).contains("cannot set both forward_auth and api_key_env")
        );

        let static_auth = VALID_CONFIG.replacen(
            "base_url = \"https://example.test\"",
            "base_url = \"https://example.test\"\n\
                 forward_auth = true\n\
                 extra_headers = { Authorization = \"static-value\" }",
            1,
        );
        assert!(error_message(&static_auth).contains("extra_headers cannot set \"Authorization\""));

        let static_beta = static_auth.replace("Authorization", "anthropic-beta");
        assert!(
            error_message(&static_beta).contains("extra_headers cannot set \"anthropic-beta\"")
        );

        for header in ["chatgpt-account-id", "x-openai-fedramp"] {
            let static_context = VALID_CONFIG.replacen(
                "base_url = \"https://example.test/v1\"",
                &format!(
                    "base_url = \"https://example.test/v1\"\n\
                     forward_auth = true\n\
                     extra_headers = {{ \"{header}\" = \"static-value\" }}"
                ),
                1,
            );
            assert!(
                error_message(&static_context)
                    .contains(&format!("extra_headers cannot set \"{header}\""))
            );
        }
    }

    /// Returns a config whose `mixed` route has a GPT target on a Responses client and a Claude
    /// target on a Messages client at `messages_url`. Its `claude` route uses Claude only.
    fn mixed_forwarding_config(messages_url: &str) -> String {
        format!(
            r#"
schema_version = 1

[llm_clients.responses]
format = "openai_responses"
base_url = "https://gateway.example.test/v1"
forward_auth = true

[llm_clients.messages]
format = "anthropic_messages"
base_url = "{messages_url}"
forward_auth = true

[targets]
gpt = {{ id = "gpt/model", llm_client = "responses" }}
claude = {{ id = "claude/model", llm_client = "messages" }}

[routes.mixed]
id = "switchyard/mixed"
type = "random"
targets = ["gpt", "claude"]

[routes.claude]
id = "switchyard/claude"
type = "passthrough"
target = "claude"
"#
        )
    }

    /// A forwarding route can mix OpenAI and Anthropic clients only when they all use the same
    /// scheme, host, and port.
    #[test]
    fn forwarding_route_mixes_formats_only_on_one_host() -> RunnerResult<()> {
        // Same host, different paths: the mixed route serves OpenAI callers, and the route that
        // uses only the Messages client keeps serving Messages callers.
        let runner = runner_from_toml(&mixed_forwarding_config("https://gateway.example.test"))?;
        let caller_auth = |id| runner.route(id).and_then(Route::caller_auth);
        assert_eq!(
            caller_auth("switchyard/mixed"),
            Some(CallerAuthKind::OpenAi)
        );
        assert_eq!(
            caller_auth("switchyard/claude"),
            Some(CallerAuthKind::Anthropic)
        );

        // A different host, port, or scheme fails, and the error names it.
        for other in [
            "https://api.anthropic.test",
            "https://gateway.example.test:8443",
            "http://gateway.example.test",
        ] {
            let error = error_message(&mixed_forwarding_config(other));
            assert!(
                error.contains("different origins") && error.contains(other),
                "{error}"
            );
        }
        Ok(())
    }

    const ADVISOR_CONFIG: &str = r#"
schema_version = 1

[llm_clients.anthropic]
format = "anthropic_messages"
base_url = "https://example.test"

[targets.executor]
id = "executor/model"
llm_client = "anthropic"

[targets.advisor]
id = "advisor/model"
llm_client = "anthropic"

[routes.gated]
id = "switchyard/advisor"
type = "advisor"
executor_target = "executor"
advisor_target = "advisor"
"#;

    #[test]
    fn advisor_route_parses_with_defaults_and_builds() -> RunnerResult<()> {
        let state = runner_from_toml(ADVISOR_CONFIG)?;
        let route = state
            .route("switchyard/advisor")
            .expect("advisor route should exist");
        let models = route.models();
        // The gate calls the executor through `efficient`; `any` keeps it in the
        // route's last-resort pool.
        assert_eq!(
            models.models_for(&Category::Efficient),
            [ModelId::from("executor/model")]
        );
        assert_eq!(
            models.models_for(&Category::Any),
            [ModelId::from("executor/model")]
        );
        assert_eq!(
            models.models_for(&Category::Judge),
            [ModelId::from("advisor/model")]
        );
        assert_eq!(
            state
                .models()
                .map(|model| model.id.as_str())
                .collect::<Vec<_>>(),
            ["switchyard/advisor"]
        );
        Ok(())
    }

    #[test]
    fn advisor_route_accepts_every_gate_knob() -> RunnerResult<()> {
        let tuned = ADVISOR_CONFIG.replace(
            "advisor_target = \"advisor\"",
            concat!(
                "advisor_target = \"advisor\"\n",
                "reviewer_system_prompt = \"review it\"\n",
                "redo_feedback_prefix = \"REVIEWER SAYS: \"\n",
                "gate_trigger = \"pattern\"\n",
                "gate_trigger_pattern = 'task_complete[\"\\s>:]*true'\n",
                "max_reviews = 2\n",
                "gate_stall_turns = 40\n",
                "gate_min_tool_results = 1\n",
                "advisor_max_tokens = 1024\n",
                "advisor_temperature = 0.0\n",
                "transcript_max_chars = 100000\n",
                "fail_open = false\n",
                "context_window = 200000\n",
                "tool_calling = true\n",
                "reasoning = true",
            ),
        );
        runner_from_toml(&tuned)?;
        Ok(())
    }

    #[test]
    fn advisor_route_rejects_unknown_keys() {
        let invalid = ADVISOR_CONFIG.replace(
            "advisor_target = \"advisor\"",
            "advisor_target = \"advisor\"\nbogus_field = 1",
        );
        assert!(error_message(&invalid).contains("bogus_field"));
    }

    #[test]
    fn advisor_route_requires_both_targets() {
        let missing = ADVISOR_CONFIG.replace("advisor_target = \"advisor\"\n", "");
        assert!(error_message(&missing).contains("advisor_target"));
    }

    #[test]
    fn advisor_route_rejects_unknown_target() {
        let invalid = ADVISOR_CONFIG.replace(
            "advisor_target = \"advisor\"",
            "advisor_target = \"missing\"",
        );
        assert!(error_message(&invalid).contains("missing"));
    }

    #[test]
    fn advisor_route_rejects_invalid_pattern() {
        let invalid = ADVISOR_CONFIG.replace(
            "advisor_target = \"advisor\"",
            "advisor_target = \"advisor\"\ngate_trigger = \"pattern\"\ngate_trigger_pattern = \"(unclosed\"",
        );
        assert!(error_message(&invalid).contains("not a valid regex"));
    }

    #[test]
    fn advisor_route_rejects_pattern_without_pattern_trigger() {
        let invalid = ADVISOR_CONFIG.replace(
            "advisor_target = \"advisor\"",
            "advisor_target = \"advisor\"\ngate_trigger_pattern = \"done\"",
        );
        assert!(
            error_message(&invalid)
                .contains("gate_trigger_pattern requires gate_trigger = \"pattern\"")
        );
    }

    #[test]
    fn advisor_route_pattern_trigger_requires_pattern() {
        let invalid = ADVISOR_CONFIG.replace(
            "advisor_target = \"advisor\"",
            "advisor_target = \"advisor\"\ngate_trigger = \"pattern\"",
        );
        assert!(error_message(&invalid).contains("non-empty gate_trigger_pattern"));
    }

    #[test]
    fn advisor_route_rejects_zero_max_reviews() {
        let invalid = ADVISOR_CONFIG.replace(
            "advisor_target = \"advisor\"",
            "advisor_target = \"advisor\"\nmax_reviews = 0",
        );
        assert!(error_message(&invalid).contains("max_reviews must be at least 1"));
    }
}