Skip to main content

switchyard_libsy/algorithms/
stage.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Signal-driven stage routing for coding agents.
5//!
6//! [`StageRouter`] is the assembled algorithm: a [`FallThrough`] pre-wired with
7//! the tool-signal processor that reads each turn's tool results and the
8//! [`StageClassifier`] that scores them onto the capable/efficient tiers. The cascade
9//! is an internal detail — callers drive the algorithm, not its parts.
10//!
11//! Signals do not decide every turn. An under-threshold turn abstains and falls
12//! through to the optional [`LlmTaskClassifier`] — the capability route's judge,
13//! joined in unchanged — and then to the picker's default tier, or to an
14//! override a decider ahead of stage set in its place.
15//!
16use std::sync::Arc;
17
18use async_trait::async_trait;
19
20use super::fall_through::FallThrough;
21use super::llm_class::{LlmClassifierConfig, LlmTaskClassifier, TaskClassifierConfig};
22use super::util::affinity::{ClassifyTrigger, has_new_user_turn};
23use super::util::stage::{
24    DecisionSource, HandoffNoteConfig, PickerMode, StageClassifier, Tier, fall_open_tier,
25    record_routing_decision,
26};
27use super::util::tool_signals::{DEFAULT_RECENT_WINDOW, ToolSemantics, ToolSignalProcessor};
28use crate::core::algorithm::{Algorithm, Driver};
29use crate::core::classifier::{Classification, Classifier, Score};
30use crate::core::processor::{Event, Processor};
31use crate::core::state::State;
32use crate::{LibsyError, Result};
33use switchyard_protocol::{Category, Request, Response};
34
35/// Telemetry name for a router this module assembles.
36const STAGE_ROUTER: &str = "stage_router";
37
38struct TierPromptProcessor {
39    capable: Option<String>,
40    efficient: Option<String>,
41}
42
43#[async_trait]
44impl Processor for TierPromptProcessor {
45    async fn process(&self, state: &mut State, event: Event<'_>) -> Result<()> {
46        if let Event::Decision {
47            driver,
48            category,
49            selected_model_id,
50            ..
51        } = event
52        {
53            state.target_prompts.clear();
54            for (tier, prompt) in [
55                (Category::Capable, &self.capable),
56                (Category::Efficient, &self.efficient),
57            ] {
58                if let Some(prompt) = prompt {
59                    for target in driver.models_for(&tier) {
60                        if target != selected_model_id || category.as_ref() == Some(&tier) {
61                            state.target_prompts.insert(target.clone(), prompt.clone());
62                        }
63                    }
64                }
65            }
66        }
67        Ok(())
68    }
69}
70
71/// Attributes a turn to the classifier it wraps, when that classifier decides it.
72///
73/// The classifiers themselves are composition-agnostic and write no state; only
74/// this router knows where each sits in its cascade.
75struct SourceStamp {
76    inner: Arc<dyn Classifier>,
77    source: DecisionSource,
78    judge: Option<switchyard_protocol::ModelId>,
79    skip_user_turn: bool,
80}
81
82#[async_trait]
83impl Classifier for SourceStamp {
84    async fn score(
85        &self,
86        state: &mut State,
87        request: &mut Request,
88        driver: &Driver,
89    ) -> Result<(Classification, Option<Response>)> {
90        if self.skip_user_turn && has_new_user_turn(&request.llm_request.messages) {
91            return Ok((Classification::Ambiguous(Vec::new()), None));
92        }
93        let scoped = self
94            .judge
95            .as_ref()
96            .map(|judge| driver.for_judge(judge.clone()));
97        let driver = scoped.as_ref().unwrap_or(driver);
98        let (classification, served) = self.inner.score(state, request, driver).await?;
99        // An abstaining classifier passes the turn on, so it is not its to claim.
100        if let Some(winner) = classification.argmax(false)? {
101            record_routing_decision(self.source, driver.provider_model(&winner.target));
102            driver.set_evidence_if_empty(serde_json::json!({
103                "source": self.source.as_str(),
104            }));
105        }
106        Ok((classification, served))
107    }
108}
109
110/// Closes the cascade at zero confidence: a fallback, not a judgement.
111struct FallOpen {
112    default_tier: Tier,
113}
114
115#[async_trait]
116impl Classifier for FallOpen {
117    async fn score(
118        &self,
119        state: &mut State,
120        _request: &mut Request,
121        driver: &Driver,
122    ) -> Result<(Classification, Option<Response>)> {
123        let tier = fall_open_tier(state).unwrap_or(self.default_tier);
124        let category = match tier {
125            Tier::Capable => Category::Capable,
126            Tier::Efficient => Category::Efficient,
127        };
128        let target = driver.first_model_for(&category)?.clone();
129        Ok((
130            Classification::Scores(vec![Score {
131                target,
132                confidence: 0.0,
133                category: Some(category),
134            }]),
135            None,
136        ))
137    }
138}
139
140/// The capability judge a stage router falls through to.
141pub struct LlmFallback {
142    /// Overrides the runtime judge for this stage configuration.
143    pub target: Option<switchyard_protocol::ModelId>,
144    /// Judge configuration. Its `recent_turn_window` counts trailing messages, while
145    /// this router's `recent_window` counts tool results.
146    /// Note: `classify_trigger` and `message_hash_fallback` have no effect here. The judge
147    /// runs as a cascade classifier on every ambiguous turn, not as a standalone algorithm,
148    /// so no verdict is retained.
149    pub config: TaskClassifierConfig,
150}
151
152/// How a stage router scores turns, and what it hands the model it picks.
153pub struct StageRouterConfig {
154    /// Tier a turn falls open to when the scorer is not confident.
155    pub mode: PickerMode,
156    /// How much corroboration a decisive pick needs, in `[0.0, 1.0]`.
157    pub confidence_threshold: f64,
158    /// Threshold after an outer classifier selects capable-first. Defaults to `0.0`.
159    pub capable_first_threshold: f64,
160    /// Trailing tool results the signals are computed over. `None` uses
161    /// [`DEFAULT_RECENT_WINDOW`].
162    pub recent_window: Option<usize>,
163    /// Exact tool-name semantics added to the built-in coding vocabulary.
164    pub tool_semantics: ToolSemantics,
165    /// Escalate on context compaction. Enabled by default.
166    pub compaction_override: bool,
167    /// Requests to keep on capable after an escalation. `0` disables the hold;
168    /// `-1` pins after switching to this tier.
169    pub capable_hold_turns: i64,
170    /// Requests to keep on efficient after a switch. `None` defaults to `-1`
171    /// under composite's capable-first policy, otherwise `0`. `Some(0)` disables
172    /// the hold; `Some(-1)` pins until the session state is cleared.
173    pub efficient_hold_turns: Option<i64>,
174    /// Note handed to the model on a signal-driven escalation, and on a
175    /// hand-back to the efficient tier when a de-escalation note is configured.
176    pub handoff_notes: Option<HandoffNoteConfig>,
177    /// System prompt handed to the runtime capable model.
178    pub capable_system_prompt: Option<String>,
179    /// System prompt handed to the runtime efficient model.
180    pub efficient_system_prompt: Option<String>,
181    /// Capability judge consulted on turns the signals leave undecided. It uses
182    /// the runtime judge model and the standalone capability route's settings.
183    pub llm_fallback: Option<LlmFallback>,
184}
185
186impl StageRouterConfig {
187    /// The signal-only configuration: no notes, no per-tier prompts, no judge.
188    /// Set the optional fields to add them.
189    pub fn new(mode: PickerMode, confidence_threshold: f64) -> Self {
190        Self {
191            mode,
192            confidence_threshold,
193            capable_first_threshold: 0.0,
194            recent_window: None,
195            tool_semantics: ToolSemantics::default(),
196            compaction_override: true,
197            capable_hold_turns: 2,
198            efficient_hold_turns: None,
199            handoff_notes: None,
200            capable_system_prompt: None,
201            efficient_system_prompt: None,
202            llm_fallback: None,
203        }
204    }
205}
206
207/// Routes coding-agent turns between a capable and an efficient tier: tool signals
208/// decide first, an optional capability judge takes the turns they cannot, and
209/// the picker's default tier closes the cascade so a turn is never left unrouted.
210pub struct StageRouter {
211    route: FallThrough,
212}
213
214impl StageRouter {
215    /// Routes between the runtime `capable` and `efficient` models. The judge,
216    /// when configured, is called through the runtime `judge` model.
217    ///
218    /// Errors if either threshold in `config` is outside `[0.0, 1.0]`, or if the
219    /// hold counts are outside `-1..=u32::MAX`. Also rejects a
220    /// fallback judge configured to retain verdicts: it runs on every ambiguous
221    /// turn, so `classify_trigger` and `message_hash_fallback` would do nothing.
222    pub fn new(config: StageRouterConfig) -> Result<Self> {
223        Ok(Self {
224            route: build_stage_route(config, false)?,
225        })
226    }
227}
228
229#[async_trait]
230impl Algorithm for StageRouter {
231    fn name(&self) -> &str {
232        STAGE_ROUTER
233    }
234
235    async fn route(
236        self: Arc<Self>,
237        driver: Driver,
238        request: Request,
239    ) -> Result<crate::RoutingOutcome> {
240        self.route.execute(driver, request).await
241    }
242}
243
244/// Wires the cascade the wrapper drives. Exposed so a composition above can
245/// stack a prelude onto it.
246pub(crate) fn build_stage_route(
247    config: StageRouterConfig,
248    reset_on_user_turn: bool,
249) -> Result<FallThrough> {
250    if let Some(fallback) = &config.llm_fallback
251        && (fallback.config.classify_trigger != ClassifyTrigger::EveryRequest
252            || fallback.config.message_hash_fallback)
253    {
254        return Err(LibsyError::AlgorithmError {
255            message: "classify_trigger and message_hash_fallback have no effect on the \
256                          stage fallback judge, which runs on every ambiguous turn. Remove \
257                          them, or use a composite route to judge once per user turn"
258                .to_string(),
259        });
260    }
261    for (name, threshold) in [
262        ("confidence_threshold", config.confidence_threshold),
263        ("capable_first_threshold", config.capable_first_threshold),
264    ] {
265        if !(0.0..=1.0).contains(&threshold) {
266            return Err(LibsyError::AlgorithmError {
267                message: format!("{name} must be between 0 and 1, got {threshold}"),
268            });
269        }
270    }
271    config.tool_semantics.validate()?;
272    for (name, turns) in [
273        ("capable_hold_turns", Some(config.capable_hold_turns)),
274        ("efficient_hold_turns", config.efficient_hold_turns),
275    ] {
276        let Some(turns) = turns else { continue };
277        if !(-1..=i64::from(u32::MAX)).contains(&turns) {
278            return Err(LibsyError::AlgorithmError {
279                message: format!(
280                    "{name} must be -1 or between 0 and {}, got {turns}",
281                    u32::MAX
282                ),
283            });
284        }
285    }
286    let default_tier = config.mode.default_tier();
287    let fall_open = FallOpen { default_tier };
288
289    let mut classifier = StageClassifier::new(config.mode, config.confidence_threshold)
290        .with_capable_first_threshold(config.capable_first_threshold)
291        .with_compaction_override(config.compaction_override)
292        .with_capable_hold_turns(config.capable_hold_turns);
293    classifier.reset_on_user_turn = reset_on_user_turn;
294    if let Some(turns) = config.efficient_hold_turns {
295        classifier = classifier.with_efficient_hold_turns(turns);
296    }
297    if let Some(notes) = config.handoff_notes {
298        classifier = classifier.with_handoff_notes(notes);
299    }
300    let signals = ToolSignalProcessor {
301        recent_window: config.recent_window.unwrap_or(DEFAULT_RECENT_WINDOW),
302        tool_semantics: config.tool_semantics,
303    };
304    let classifier = Arc::new(classifier.with_signals(signals));
305    let mut router = FallThrough::new_with_state()
306        .with_name(STAGE_ROUTER)
307        .with_processor(classifier.clone())
308        .with_classifier(classifier);
309    if let Some(fallback) = config.llm_fallback {
310        router = router.with_classifier(Arc::new(SourceStamp {
311            inner: Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {
312                config: fallback.config,
313            })?),
314            source: DecisionSource::LlmClassifier,
315            judge: fallback.target,
316            skip_user_turn: reset_on_user_turn,
317        }));
318    }
319    // Nothing behind this, so no turn is left unrouted.
320    router = router.with_classifier(Arc::new(SourceStamp {
321        inner: Arc::new(fall_open),
322        source: DecisionSource::FallOpen,
323        judge: None,
324        skip_user_turn: false,
325    }));
326    if config.capable_system_prompt.is_some() || config.efficient_system_prompt.is_some() {
327        router = router.with_processor(Arc::new(TierPromptProcessor {
328            capable: config.capable_system_prompt,
329            efficient: config.efficient_system_prompt,
330        }));
331    }
332    Ok(router)
333}
334
335#[cfg(test)]
336mod tests {
337    use crate::{CapabilityJudgeConfig, LlmCapabilityConfig};
338    use std::collections::HashMap;
339    use std::sync::Arc;
340
341    use async_trait::async_trait;
342    use parking_lot::Mutex;
343
344    use super::*;
345    use crate::algorithms::util::stage::{clear_fall_open, set_fall_open};
346    use crate::algorithms::util::tier_fixtures::{JUDGE, Recorder, turn_request};
347    use crate::core::testing::test_drive_with_models;
348    use switchyard_protocol::{Category, ModelId};
349
350    /// A classifier that always picks `target`, standing in for a cascade member.
351    struct Fixed(&'static str);
352
353    #[async_trait]
354    impl Classifier for Fixed {
355        async fn score(
356            &self,
357            _state: &mut State,
358            _request: &mut Request,
359            _driver: &Driver,
360        ) -> Result<(Classification, Option<Response>)> {
361            Ok((
362                Classification::Scores(vec![Score {
363                    target: ModelId::from(self.0),
364                    confidence: 1.0,
365                    category: None,
366                }]),
367                None,
368            ))
369        }
370    }
371
372    /// A classifier that never decides.
373    struct Abstains;
374
375    #[async_trait]
376    impl Classifier for Abstains {
377        async fn score(
378            &self,
379            _state: &mut State,
380            _request: &mut Request,
381            _driver: &Driver,
382        ) -> Result<(Classification, Option<Response>)> {
383            Ok((Classification::Ambiguous(vec![]), None))
384        }
385    }
386
387    async fn stamped(inner: Arc<dyn Classifier>) -> Result<Option<String>> {
388        let stamp = SourceStamp {
389            inner,
390            source: DecisionSource::LlmClassifier,
391            judge: None,
392            skip_user_turn: false,
393        };
394        let (driver, mut rx) = Driver::new("test", Arc::new(crate::RuntimeModels::default()));
395        stamp
396            .score(&mut State::default(), &mut Request::default(), &driver)
397            .await?;
398        driver
399            .finish(Ok(crate::RoutingOutcome::route_to(
400                "strong".into(),
401                Vec::new(),
402                Request::default(),
403            )))
404            .await?;
405        let Some(Ok(crate::Step::Done(outcome))) = rx.recv().await else {
406            panic!("expected Done step");
407        };
408        Ok(outcome
409            .metadata
410            .and_then(|metadata| metadata.evidence)
411            .and_then(|evidence| evidence.get("source")?.as_str().map(str::to_string)))
412    }
413
414    #[tokio::test]
415    async fn a_deciding_classifier_is_credited_with_the_turn() -> Result<()> {
416        assert_eq!(
417            stamped(Arc::new(Fixed("strong"))).await?.as_deref(),
418            Some("llm-classifier")
419        );
420        Ok(())
421    }
422
423    #[tokio::test]
424    async fn an_abstaining_classifier_claims_nothing() -> Result<()> {
425        // It passed the turn on, so the next classifier is the one that decided.
426        assert_eq!(stamped(Arc::new(Abstains)).await?, None);
427        Ok(())
428    }
429
430    fn config() -> StageRouterConfig {
431        StageRouterConfig::new(PickerMode::EfficientFirst, 0.5)
432    }
433
434    fn runtime_models() -> HashMap<Category, Vec<ModelId>> {
435        runtime_models_for("strong", "weak")
436    }
437
438    fn runtime_models_for(capable: &str, efficient: &str) -> HashMap<Category, Vec<ModelId>> {
439        [
440            (Category::Judge, vec![ModelId::from(JUDGE)]),
441            (Category::Efficient, vec![ModelId::from(efficient)]),
442            (Category::Capable, vec![ModelId::from(capable)]),
443            (
444                Category::Any,
445                vec![ModelId::from(capable), ModelId::from(efficient)],
446            ),
447        ]
448        .into()
449    }
450
451    #[test]
452    fn rejects_an_out_of_range_confidence_threshold() {
453        let mut config = config();
454        config.confidence_threshold = 1.5;
455        assert!(matches!(
456            StageRouter::new(config),
457            Err(LibsyError::AlgorithmError { .. })
458        ));
459    }
460
461    #[test]
462    fn rejects_an_out_of_range_judge_threshold() {
463        let mut config = config();
464        config.llm_fallback = Some(LlmFallback {
465            target: None,
466            config: TaskClassifierConfig {
467                judge: CapabilityJudgeConfig::Llm(LlmCapabilityConfig {
468                    base_threshold: -0.1,
469                    ..LlmCapabilityConfig::default()
470                }),
471                ..Default::default()
472            },
473        });
474        assert!(matches!(
475            StageRouter::new(config),
476            Err(LibsyError::AlgorithmError { .. })
477        ));
478    }
479
480    #[test]
481    fn rejects_retaining_triggers_on_the_fallback_judge() {
482        for (trigger, message_hash_fallback) in [
483            (ClassifyTrigger::UserTurn, false),
484            (ClassifyTrigger::NewSession, false),
485            (ClassifyTrigger::UserTurn, true),
486        ] {
487            let mut config = config();
488            config.llm_fallback = Some(LlmFallback {
489                target: None,
490                config: TaskClassifierConfig {
491                    classify_trigger: trigger,
492                    message_hash_fallback,
493                    ..Default::default()
494                },
495            });
496            assert!(
497                matches!(
498                    StageRouter::new(config),
499                    Err(LibsyError::AlgorithmError { .. })
500                ),
501                "{trigger:?} with message_hash_fallback = {message_hash_fallback}"
502            );
503        }
504    }
505
506    #[test]
507    fn builds() -> Result<()> {
508        let router = StageRouter::new(config())?;
509        assert_eq!(router.name(), STAGE_ROUTER);
510        Ok(())
511    }
512
513    #[test]
514    fn hold_turns_accept_pins_and_reject_invalid_counts() {
515        for capable in [true, false] {
516            for turns in [-2, -1, 0, 1, i64::from(u32::MAX), i64::from(u32::MAX) + 1] {
517                let mut config = config();
518                if capable {
519                    config.capable_hold_turns = turns;
520                } else {
521                    config.efficient_hold_turns = Some(turns);
522                }
523                assert_eq!(
524                    StageRouter::new(config).is_ok(),
525                    (-1..=i64::from(u32::MAX)).contains(&turns)
526                );
527            }
528        }
529    }
530
531    /// A clean write selects efficient without ending finite capable holds early.
532    fn production_request() -> Request {
533        let mut request = turn_request(false);
534        if let switchyard_protocol::ContentBlock::ToolCall(call) =
535            &mut request.llm_request.messages[1].content[0]
536        {
537            call.name = "Write".to_string();
538        }
539        request
540    }
541
542    /// Disabling compaction escalation preserves normal signals in both pickers.
543    #[tokio::test]
544    async fn compaction_override_can_be_disabled() -> Result<()> {
545        for mode in [PickerMode::EfficientFirst, PickerMode::CapableFirst] {
546            for enabled in [true, false] {
547                let mut config = StageRouterConfig::new(mode, 0.5);
548                assert!(config.compaction_override);
549                config.compaction_override = enabled;
550                config.capable_hold_turns = 0;
551                let router = recording_router(config)?;
552                let recorder = Arc::new(Recorder::default());
553                for mut request in [production_request(), turn_request(true)] {
554                    request.llm_request.has_compaction = true;
555                    test_drive_with_models(
556                        router.clone(),
557                        request,
558                        runtime_models(),
559                        recorder.serve(),
560                    )
561                    .await?;
562                }
563                let actual: Vec<_> = recorder
564                    .routed()
565                    .into_iter()
566                    .map(|call| call.target)
567                    .collect();
568                assert_eq!(actual, [if enabled { "strong" } else { "weak" }, "strong"]);
569            }
570        }
571        Ok(())
572    }
573
574    #[tokio::test]
575    async fn standalone_pickers_default_to_no_efficient_hold() -> Result<()> {
576        for mode in [PickerMode::EfficientFirst, PickerMode::CapableFirst] {
577            let mut config = StageRouterConfig::new(mode, 0.5);
578            config.capable_hold_turns = 0;
579            let router = recording_router(config)?;
580            let recorder = Arc::new(Recorder::default());
581            for request in [turn_request(true), production_request(), turn_request(true)] {
582                test_drive_with_models(router.clone(), request, runtime_models(), recorder.serve())
583                    .await?;
584            }
585            let actual: Vec<_> = recorder
586                .routed()
587                .into_iter()
588                .map(|call| call.target)
589                .collect();
590            assert_eq!(actual, ["strong", "weak", "strong"]);
591        }
592        Ok(())
593    }
594
595    /// Both pickers honor both holds; the switch request is not one of the held turns.
596    #[tokio::test]
597    async fn holds_expire_or_pin_after_switching_in_both_pickers() -> Result<()> {
598        for mode in [PickerMode::EfficientFirst, PickerMode::CapableFirst] {
599            for capable in [true, false] {
600                for turns in [0, 1, 2, -1] {
601                    let mut config = StageRouterConfig::new(mode, 0.5);
602                    config.capable_hold_turns = if capable { turns } else { 0 };
603                    config.efficient_hold_turns = Some(if capable { 0 } else { turns });
604                    let router = recording_router(config)?;
605                    let recorder = Arc::new(Recorder::default());
606                    let (switch, opposing, held_target, other_target) = if capable {
607                        (turn_request(true), production_request(), "strong", "weak")
608                    } else {
609                        (production_request(), turn_request(true), "weak", "strong")
610                    };
611                    let mut requests = vec![opposing.clone(), switch];
612                    requests.extend(std::iter::repeat_n(opposing, 4));
613                    for request in requests {
614                        test_drive_with_models(
615                            router.clone(),
616                            request,
617                            runtime_models(),
618                            recorder.serve(),
619                        )
620                        .await?;
621                    }
622                    let actual: Vec<_> = recorder
623                        .routed()
624                        .into_iter()
625                        .map(|call| call.target)
626                        .collect();
627                    let mut expected = vec![other_target, held_target];
628                    expected.extend((0..4).map(|i| {
629                        if turns == -1 || i < turns {
630                            held_target
631                        } else {
632                            other_target
633                        }
634                    }));
635                    assert_eq!(
636                        actual, expected,
637                        "{mode:?}, capable={capable}, turns={turns}"
638                    );
639                }
640            }
641        }
642        Ok(())
643    }
644
645    /// Initial selection does not pin. Once switched, pins survive missing signals,
646    /// passing tests, and critical errors, and remain scoped to one session/agent.
647    #[tokio::test]
648    async fn pins_survive_signals_and_remain_isolated() -> Result<()> {
649        for mode in [PickerMode::EfficientFirst, PickerMode::CapableFirst] {
650            for capable in [true, false] {
651                let mut config = StageRouterConfig::new(mode, 0.5);
652                config.capable_hold_turns = -1;
653                config.efficient_hold_turns = Some(-1);
654                let router = recording_router(config)?;
655                let recorder = Arc::new(Recorder::default());
656                let (initial, switch, held, other) = if capable {
657                    (production_request(), turn_request(true), "strong", "weak")
658                } else {
659                    (turn_request(true), production_request(), "weak", "strong")
660                };
661                let mut no_signals = turn_request(false);
662                no_signals.llm_request.messages.truncate(1);
663                let mut passing = turn_request(false);
664                if let switchyard_protocol::ContentBlock::ToolResult(result) =
665                    &mut passing.llm_request.messages[2].content[0]
666                {
667                    result.content = vec![switchyard_protocol::ContentBlock::Text {
668                        text: "test result: ok. 1 passed; 0 failed".into(),
669                    }];
670                }
671                let mut child = initial.clone();
672                child.metadata.as_mut().unwrap().agent_id = Some("child".into());
673                let mut other_session = initial.clone();
674                other_session.metadata.as_mut().unwrap().session_id = Some("other".into());
675                let mut final_request = initial.clone();
676                final_request.metadata.as_mut().unwrap().session_final = Some(true);
677                let requests = [
678                    initial.clone(),
679                    switch,
680                    no_signals,
681                    passing,
682                    initial.clone(),
683                    child,
684                    other_session,
685                    final_request,
686                    initial,
687                ];
688                for request in requests {
689                    test_drive_with_models(
690                        router.clone(),
691                        request,
692                        runtime_models(),
693                        recorder.serve(),
694                    )
695                    .await?;
696                }
697                let actual: Vec<_> = recorder
698                    .routed()
699                    .into_iter()
700                    .map(|call| call.target)
701                    .collect();
702                assert_eq!(
703                    actual,
704                    [other, held, held, held, held, other, other, held, other]
705                );
706            }
707        }
708        Ok(())
709    }
710
711    /// Judge-driven switches must arm the same pin as signal-driven switches.
712    #[tokio::test]
713    async fn judge_switches_arm_pins_and_held_turns_skip_the_judge() -> Result<()> {
714        for capable in [true, false] {
715            let recorder = Arc::new(Recorder::default());
716            let mut config = config_with_judge(&recorder, if capable { 1.0 } else { 0.0 });
717            config.capable_hold_turns = -1;
718            config.efficient_hold_turns = Some(-1);
719            let router = recording_router(config)?;
720            for p_solve in [
721                if capable { 1.0 } else { 0.0 },
722                if capable { 0.0 } else { 1.0 },
723                if capable { 1.0 } else { 0.0 },
724            ] {
725                *recorder.judge_p_solve.lock() = p_solve;
726                test_drive_with_models(
727                    router.clone(),
728                    turn_request(false),
729                    runtime_models(),
730                    recorder.serve(),
731                )
732                .await?;
733            }
734            let actual: Vec<_> = recorder
735                .routed()
736                .into_iter()
737                .map(|call| call.target)
738                .collect();
739            assert_eq!(
740                actual,
741                if capable {
742                    ["weak", "strong", "strong"]
743                } else {
744                    ["strong", "weak", "weak"]
745                }
746            );
747            assert_eq!(recorder.judge_calls(), 2);
748        }
749        Ok(())
750    }
751
752    // ── routing integration tests ────────────────────────────────────────────
753
754    const ESCALATION: &str = "the previous model was stalling; pick up the diagnosis";
755    fn recording_router(config: StageRouterConfig) -> Result<Arc<StageRouter>> {
756        Ok(Arc::new(StageRouter::new(config)?))
757    }
758
759    fn config_with_notes() -> StageRouterConfig {
760        let mut c = config();
761        c.handoff_notes = Some(HandoffNoteConfig::new(ESCALATION, None, true));
762        c
763    }
764
765    fn config_with_judge(recorder: &Arc<Recorder>, p_solve: f64) -> StageRouterConfig {
766        *recorder.judge_p_solve.lock() = p_solve;
767        let mut c = config();
768        c.llm_fallback = Some(LlmFallback {
769            target: None,
770            config: TaskClassifierConfig {
771                judge: CapabilityJudgeConfig::Llm(LlmCapabilityConfig {
772                    base_threshold: 0.5,
773                    ..LlmCapabilityConfig::default()
774                }),
775                recent_turn_window: Some(3),
776                ..Default::default()
777            },
778        });
779        c
780    }
781
782    /// Stands in for a decider ahead of stage: sets the override once, clears it
783    /// once, and leaves the turns between alone.
784    #[derive(Default)]
785    struct TierDecider {
786        requests: Mutex<u32>,
787    }
788
789    #[async_trait]
790    impl Processor for TierDecider {
791        async fn process(&self, state: &mut State, event: Event<'_>) -> Result<()> {
792            if matches!(event, Event::Request { .. }) {
793                let mut requests = self.requests.lock();
794                *requests += 1;
795                match *requests {
796                    1 => set_fall_open(state, Tier::Efficient),
797                    4 => clear_fall_open(state),
798                    _ => {}
799                }
800            }
801            Ok(())
802        }
803    }
804
805    #[tokio::test]
806    async fn an_override_replaces_the_picker_default_and_leaves_the_signals_alone() -> Result<()> {
807        let recorder = Arc::new(Recorder::default());
808        // The picker would fall open to "strong"; the override says "weak".
809        let config = StageRouterConfig::new(PickerMode::CapableFirst, 0.5);
810        let route: Arc<dyn Algorithm> = Arc::new(
811            build_stage_route(config, false)?.with_processor(Arc::new(TierDecider::default())),
812        );
813
814        let models = runtime_models();
815        for is_turn_failed in [false, false, true, false] {
816            test_drive_with_models(
817                route.clone(),
818                turn_request(is_turn_failed),
819                models.clone(),
820                recorder.serve(),
821            )
822            .await?;
823        }
824
825        let routed = recorder.routed();
826        assert_eq!(
827            routed[0].target, "weak",
828            "an undecided turn takes the override"
829        );
830        assert_eq!(
831            routed[1].target, "weak",
832            "which outlives the turn that set it"
833        );
834        assert_eq!(
835            routed[2].target, "strong",
836            "a critical failure still reaches the signals"
837        );
838        assert_eq!(
839            routed[3].target, "strong",
840            "clearing restores the picker default"
841        );
842        Ok(())
843    }
844
845    #[tokio::test]
846    async fn a_signal_driven_escalation_hands_the_note_to_the_model() -> Result<()> {
847        let recorder = Arc::new(Recorder::default());
848        let router = recording_router(config_with_notes())?;
849
850        test_drive_with_models(
851            router.clone(),
852            turn_request(false),
853            runtime_models(),
854            recorder.serve(),
855        )
856        .await?;
857        test_drive_with_models(
858            router.clone(),
859            turn_request(true),
860            runtime_models_for("runtime-strong", "runtime-weak"),
861            recorder.serve(),
862        )
863        .await?;
864
865        let calls = recorder.routed();
866        assert_eq!(calls[0].target, "weak");
867        assert_eq!(calls[1].target, "runtime-strong");
868        assert!(
869            !calls[0].messages.iter().any(|t| t.contains(ESCALATION)),
870            "steady-state turn should carry no note: {:?}",
871            calls[0].messages
872        );
873        assert!(
874            calls[1]
875                .messages
876                .last()
877                .is_some_and(|t| t.ends_with(ESCALATION)),
878            "escalating turn should carry the note last: {:?}",
879            calls[1].messages
880        );
881        Ok(())
882    }
883
884    #[tokio::test]
885    async fn the_judge_decides_a_turn_the_signals_leave_undecided() -> Result<()> {
886        let recorder = Arc::new(Recorder::default());
887        let router = recording_router(config_with_judge(&recorder, 0.1))?;
888
889        let (selected_model, _) = test_drive_with_models(
890            router.clone(),
891            turn_request(false),
892            runtime_models(),
893            recorder.serve(),
894        )
895        .await?;
896
897        let calls = recorder.calls.lock();
898        assert!(
899            calls.iter().any(|call| call.target == JUDGE),
900            "the judge should be recorded as a routing side call"
901        );
902        assert!(
903            calls.iter().any(|call| call.target == "strong"),
904            "the selected target should be recorded as an answer call"
905        );
906        drop(calls);
907        assert_eq!(selected_model, "strong");
908        Ok(())
909    }
910
911    #[tokio::test]
912    async fn a_decisive_signal_never_reaches_the_judge() -> Result<()> {
913        let recorder = Arc::new(Recorder::default());
914        let router = recording_router(config_with_judge(&recorder, 0.9))?;
915
916        test_drive_with_models(
917            router.clone(),
918            turn_request(true),
919            runtime_models(),
920            recorder.serve(),
921        )
922        .await?;
923
924        assert!(
925            !recorder.calls.lock().iter().any(|c| c.target == JUDGE),
926            "a resolved turn should not pay for a judge call"
927        );
928        assert_eq!(recorder.routed()[0].target, "strong");
929        Ok(())
930    }
931
932    #[tokio::test]
933    async fn the_judges_verdict_is_not_pinned_to_the_session() -> Result<()> {
934        let recorder = Arc::new(Recorder::default());
935        let router = recording_router(config_with_judge(&recorder, 0.1))?;
936
937        test_drive_with_models(
938            router.clone(),
939            turn_request(false),
940            runtime_models(),
941            recorder.serve(),
942        )
943        .await?;
944        *recorder.judge_p_solve.lock() = 0.9;
945        test_drive_with_models(
946            router.clone(),
947            turn_request(false),
948            runtime_models(),
949            recorder.serve(),
950        )
951        .await?;
952
953        let routed = recorder.routed();
954        assert_eq!(routed[0].target, "strong");
955        assert_eq!(routed[1].target, "weak");
956        assert_eq!(
957            recorder
958                .calls
959                .lock()
960                .iter()
961                .filter(|c| c.target == JUDGE)
962                .count(),
963            2,
964            "each undecided turn is its own question"
965        );
966        Ok(())
967    }
968
969    #[tokio::test]
970    async fn a_judge_that_cannot_tell_lands_on_the_picker_default() -> Result<()> {
971        let recorder = Arc::new(Recorder::default());
972        let router = recording_router(config_with_judge(&recorder, 42.0))?;
973
974        test_drive_with_models(
975            router.clone(),
976            turn_request(false),
977            runtime_models(),
978            recorder.serve(),
979        )
980        .await?;
981
982        assert_eq!(recorder.routed()[0].target, "weak");
983        Ok(())
984    }
985
986    #[tokio::test]
987    async fn the_judge_reads_the_window_it_was_configured_with() -> Result<()> {
988        let recorder = Arc::new(Recorder::default());
989        let router = recording_router(config_with_judge(&recorder, 0.9))?;
990
991        test_drive_with_models(
992            router.clone(),
993            turn_request(false),
994            runtime_models(),
995            recorder.serve(),
996        )
997        .await?;
998
999        let judged = recorder
1000            .calls
1001            .lock()
1002            .iter()
1003            .find(|c| c.target == JUDGE)
1004            .map(|c| c.messages.join("|"));
1005        let Some(judged) = judged else {
1006            panic!("the judge was never called");
1007        };
1008        assert!(
1009            judged.contains("fix the build"),
1010            "the judge should see the opening task: {judged}"
1011        );
1012        Ok(())
1013    }
1014}