car_server_core/coder/

router.rs

//! Engine selection: native CAR loop vs. delegation to an external CLI.
//!
//! Resolution order: an explicit choice always wins; `Auto` assesses the
//! intent with `car-inference`'s [`TaskComplexity`] heuristics and delegates
//! to the preferred ready external CLI only for `Complex` work, keeping
//! routine tasks on the native loop. Detection is injected as plain data so
//! resolution is unit-testable without binaries on `$PATH`.

use car_inference::adaptive_router::TaskComplexity;
use serde::{Deserialize, Serialize};

/// Which engine performs the coding work.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EngineChoice {
    /// Decide per task: complexity assessment + detected external CLIs.
    Auto,
    /// CAR's own inference + tool loop.
    Native,
    /// One session of a detected external agentic CLI (`claude-code`,
    /// `codex`, `gemini`).
    External(String),
    /// Foreman (#274): decompose the intent, farm subtasks to the external
    /// CLI in parallel worktrees, gate each patch + the integrated union,
    /// then land the verified union in the session worktree. Declines to
    /// single-session/native when the plan has no parallelism.
    Foreman(String),
}

impl EngineChoice {
    /// Parse the RPC/CLI form: `auto` | `native` | `external[:agent_id]` |
    /// `foreman[:agent_id]`.
    pub fn parse(s: &str) -> Result<Self, String> {
        match s.trim() {
            "auto" | "" => Ok(Self::Auto),
            "native" => Ok(Self::Native),
            "external" => Ok(Self::External(String::new())),
            "foreman" => Ok(Self::Foreman(String::new())),
            other => {
                if let Some(id) = other.strip_prefix("external:") {
                    if !id.is_empty() {
                        return Ok(Self::External(id.to_string()));
                    }
                }
                if let Some(id) = other.strip_prefix("foreman:") {
                    if !id.is_empty() {
                        return Ok(Self::Foreman(id.to_string()));
                    }
                }
                Err(format!(
                    "unknown engine '{other}' (expected auto | native | external[:agent_id] | foreman[:agent_id])"
                ))
            }
        }
    }

    pub fn label(&self) -> String {
        match self {
            Self::Auto => "auto".to_string(),
            Self::Native => "native".to_string(),
            Self::External(id) if id.is_empty() => "external".to_string(),
            Self::External(id) => format!("external:{id}"),
            Self::Foreman(id) if id.is_empty() => "foreman".to_string(),
            Self::Foreman(id) => format!("foreman:{id}"),
        }
    }
}

/// What resolution needs to know about one detected external CLI.
#[derive(Debug, Clone)]
pub struct DetectedAgent {
    pub id: String,
    /// Health bucket is `Ready` (authenticated, status command succeeded).
    pub ready: bool,
    /// Set when detection proved the binary cannot be executed at all —
    /// carries the diagnosis. Kept separate from `ready` because the two
    /// answer different questions, and collapsing them is what made a
    /// quarantined binary indistinguishable from a signed-out one. Sending
    /// a user to `codex login` when the login command is itself
    /// unrunnable is a dead end.
    pub unusable_reason: Option<String>,
}

impl DetectedAgent {
    /// The user-facing explanation for why this agent can't be used, or
    /// `None` when it is ready. Prefers the executability diagnosis over
    /// the auth guess.
    fn unavailable_reason(&self, kind: &str) -> Option<String> {
        if let Some(why) = &self.unusable_reason {
            return Some(format!(
                "{kind} '{}' is installed but cannot be executed: {why}",
                self.id
            ));
        }
        if !self.ready {
            return Some(format!(
                "{kind} '{}' is installed but not ready (not authenticated?)",
                self.id
            ));
        }
        None
    }
}

/// Default delegation preference when several CLIs are ready.
pub const DEFAULT_PREFERENCE: [&str; 3] = ["claude-code", "codex", "gemini"];

/// A resolved engine (never `Auto`) plus the reason, for the event stream.
#[derive(Debug, Clone, PartialEq)]
pub struct ResolvedEngine {
    pub engine: EngineChoice,
    pub reason: String,
}

/// Snapshot the currently-detected external CLIs (with health) into the
/// plain shape [`resolve_engine`] consumes.
pub async fn detect_ready_agents() -> Vec<DetectedAgent> {
    car_external_agents::detect_with_health(false)
        .await
        .into_iter()
        .map(|spec| DetectedAgent {
            ready: matches!(
                &spec.health,
                Some(h) if h.status == car_external_agents::HealthStatus::Ready
            ),
            unusable_reason: spec.unusable_reason().map(str::to_string),
            id: spec.id,
        })
        .collect()
}

/// Pick an agent for a request that named none.
///
/// Both branches skip anything [`car_external_agents::auto_selectable`] holds
/// back. Today that is `mini-swe-agent`, which exists as the `coder-ab`
/// measurement baseline: without the filter the `or_else` fallback below would
/// hand a user's real coding task to a control arm on any machine where it is
/// the only signed-in CLI. An explicitly named agent is unaffected — that path
/// does not come through here.
fn first_ready(preference: &[&str], detected: &[DetectedAgent]) -> Option<String> {
    let usable = |d: &DetectedAgent| d.ready && car_external_agents::auto_selectable(d.id.as_str());
    preference
        .iter()
        .find(|p| detected.iter().any(|d| usable(d) && d.id == **p))
        .map(|p| p.to_string())
        // A ready agent outside the preference list still beats nothing.
        .or_else(|| detected.iter().find(|d| usable(d)).map(|d| d.id.clone()))
}

/// Resolve the requested engine against the detected CLIs and the intent's
/// assessed complexity. Errors only when an *explicit* external request can't
/// be satisfied — `Auto` always resolves (falling back to native).
pub fn resolve_engine(
    requested: &EngineChoice,
    intent: &str,
    detected: &[DetectedAgent],
    preference: &[&str],
) -> Result<ResolvedEngine, String> {
    match requested {
        EngineChoice::Native => Ok(ResolvedEngine {
            engine: EngineChoice::Native,
            reason: "explicitly requested".into(),
        }),
        EngineChoice::External(id) if !id.is_empty() => {
            let agent = detected
                .iter()
                .find(|d| d.id == *id)
                .ok_or_else(|| format!("external agent '{id}' is not installed"))?;
            if let Some(why) = agent.unavailable_reason("external agent") {
                return Err(why);
            }
            Ok(ResolvedEngine {
                engine: EngineChoice::External(id.clone()),
                reason: "explicitly requested".into(),
            })
        }
        EngineChoice::External(_) => {
            let id = first_ready(preference, detected).ok_or(
                "external engine requested but no external agent CLI is installed and ready",
            )?;
            Ok(ResolvedEngine {
                engine: EngineChoice::External(id),
                reason: "first ready external agent".into(),
            })
        }
        EngineChoice::Foreman(id) if !id.is_empty() => {
            let agent = detected
                .iter()
                .find(|d| d.id == *id)
                .ok_or_else(|| format!("foreman adapter '{id}' is not installed"))?;
            if let Some(why) = agent.unavailable_reason("foreman adapter") {
                return Err(why);
            }
            // Naming a measurement baseline outright is meaningful for
            // `external` — that IS how `coder-ab` runs its control arm — and
            // meaningless for `foreman`, which decomposes the goal and farms
            // subtasks through CAR's own orchestration. A baseline run through
            // that measures CAR's orchestrator, not the baseline, so it is
            // refused rather than quietly producing a number nobody can read.
            if !car_external_agents::auto_selectable(id.as_str()) {
                return Err(format!(
                    "'{id}' is a measurement baseline, not a Foreman adapter — run it as \
                     `external:{id}` (see docs/coder-ab-guide.md)"
                ));
            }
            Ok(ResolvedEngine {
                engine: EngineChoice::Foreman(id.clone()),
                reason: "explicitly requested".into(),
            })
        }
        EngineChoice::Foreman(_) => {
            let id = first_ready(preference, detected).ok_or(
                "foreman engine requested but no external agent CLI is installed and ready",
            )?;
            Ok(ResolvedEngine {
                engine: EngineChoice::Foreman(id),
                reason: "first ready external agent".into(),
            })
        }
        EngineChoice::Auto => {
            // `assess` buckets almost any coding intent as `Code` (repair
            // markers like "fix"/"refactor" dominate), so `Code` alone can't
            // mean "delegate". Frontier-worthy = genuinely Complex, or a Code
            // task whose intent is long/multi-step enough that a frontier CLI
            // is likely to outperform the native loop. The explicit engine
            // override is the real control; this is a default, not a promise.
            let complexity = TaskComplexity::assess(intent);
            let broad_scope = intent.split_whitespace().count() > 120;
            let frontier_worthy = complexity == TaskComplexity::Complex
                || (complexity == TaskComplexity::Code && broad_scope);
            if frontier_worthy {
                if let Some(id) = first_ready(preference, detected) {
                    // Foreman-first: its planner self-selects — a plan with
                    // no parallelism declines to single-session, so trivial
                    // tasks never pay the farm-out cost.
                    return Ok(ResolvedEngine {
                        engine: EngineChoice::Foreman(id),
                        reason: format!(
                            "task assessed as {complexity:?} with broad scope and a frontier CLI is ready; \
                             foreman gates the parallel farm-out"
                        ),
                    });
                }
            }
            Ok(ResolvedEngine {
                engine: EngineChoice::Native,
                reason: if frontier_worthy {
                    "task is complex but no external CLI is ready; using native loop".into()
                } else {
                    format!("task assessed as {complexity:?}; native loop suffices")
                },
            })
        }
    }
}

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

    fn agents(ready: &[&str], installed_not_ready: &[&str]) -> Vec<DetectedAgent> {
        ready
            .iter()
            .map(|id| DetectedAgent {
                id: id.to_string(),
                ready: true,
                unusable_reason: None,
            })
            .chain(installed_not_ready.iter().map(|id| DetectedAgent {
                id: id.to_string(),
                ready: false,
                unusable_reason: None,
            }))
            .collect()
    }

    /// An installed-but-unrunnable CLI must be reported as unrunnable,
    /// not as an auth problem. Sending the user to `codex login` when
    /// the login command is itself SIGKILLed is a dead end, and this is
    /// the path `coder.start --engine codex` takes — the one the
    /// original Gatekeeper report came from.
    #[test]
    fn explicit_engine_reports_unrunnable_over_auth() {
        let detected = vec![DetectedAgent {
            id: "codex".to_string(),
            ready: false,
            unusable_reason: Some("killed by signal 9".to_string()),
        }];
        let err = resolve_engine(
            &EngineChoice::External("codex".to_string()),
            "add a test",
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap_err();
        assert!(
            err.contains("cannot be executed") && err.contains("signal 9"),
            "want the executability diagnosis, got {err:?}"
        );
        assert!(
            !err.contains("not authenticated"),
            "must not blame auth for an unrunnable binary, got {err:?}"
        );
    }

    // A prompt TaskComplexity::assess reliably buckets as Complex: long,
    // multi-step, architecture-flavored.
    fn complex_intent() -> String {
        format!(
            "Refactor the authentication architecture across the whole system, design and \
             implement the migration step by step, then analyze the tradeoffs. {}",
            "Consider every module and integration in depth. ".repeat(30)
        )
    }

    #[test]
    fn explicit_choice_always_wins() {
        let detected = agents(&["claude-code"], &[]);
        let r = resolve_engine(
            &EngineChoice::Native,
            &complex_intent(),
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(r.engine, EngineChoice::Native);

        let r = resolve_engine(
            &EngineChoice::External("claude-code".into()),
            "tiny task",
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(r.engine, EngineChoice::External("claude-code".into()));
    }

    #[test]
    fn explicit_external_fails_clearly_when_unavailable() {
        let err = resolve_engine(
            &EngineChoice::External("codex".into()),
            "x",
            &agents(&[], &["codex"]),
            &DEFAULT_PREFERENCE,
        )
        .unwrap_err();
        assert!(err.contains("not ready"), "{err}");

        let err = resolve_engine(
            &EngineChoice::External("codex".into()),
            "x",
            &agents(&[], &[]),
            &DEFAULT_PREFERENCE,
        )
        .unwrap_err();
        assert!(err.contains("not installed"), "{err}");
    }

    #[test]
    fn auto_with_no_clis_is_native() {
        let r = resolve_engine(
            &EngineChoice::Auto,
            &complex_intent(),
            &[],
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(r.engine, EngineChoice::Native);
        assert!(r.reason.contains("no external CLI"), "{}", r.reason);
    }

    /// The `coder-ab` baseline must never be picked by a request that named
    /// no agent — not by `auto`, and not by a bare `external`. It is a control
    /// arm; routing a user's real task to it would be shipping the control.
    #[test]
    fn an_unnamed_request_never_resolves_to_the_measurement_baseline() {
        let detected = agents(&["mini-swe-agent"], &[]);

        let bare = resolve_engine(
            &EngineChoice::External(String::new()),
            &complex_intent(),
            &detected,
            &DEFAULT_PREFERENCE,
        );
        assert!(
            bare.is_err(),
            "bare `external` must not fall back to the baseline: {bare:?}"
        );

        // `auto` has to resolve *something*, and the honest something is the
        // native loop — not the control arm.
        let auto = resolve_engine(
            &EngineChoice::Auto,
            &complex_intent(),
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(auto.engine, EngineChoice::Native, "{}", auto.reason);
    }

    /// The other half: holding it back from *unnamed* resolution must not make
    /// it unreachable. `car coder-ab --external mini-swe-agent` is the whole
    /// reason the adapter exists.
    #[test]
    fn naming_the_baseline_outright_still_resolves() {
        let detected = agents(&["mini-swe-agent"], &[]);
        let r = resolve_engine(
            &EngineChoice::External("mini-swe-agent".into()),
            "fix the failing test",
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(
            r.engine,
            EngineChoice::External("mini-swe-agent".into()),
            "{}",
            r.reason
        );
    }

    /// `docs/websocket-protocol.md` asserts the baseline is not a Foreman
    /// adapter. The `first_ready` filter alone does not enforce that — the
    /// explicit-Foreman branch never consults it — so the claim needs its own
    /// check or the docs describe a rule the code does not have.
    #[test]
    fn the_measurement_baseline_is_refused_as_a_foreman_adapter() {
        let detected = agents(&["mini-swe-agent"], &[]);
        let err = resolve_engine(
            &EngineChoice::Foreman("mini-swe-agent".into()),
            &complex_intent(),
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .expect_err("a control arm run through CAR's orchestrator measures the orchestrator");
        assert!(err.contains("measurement baseline"), "{err}");
        // The error has to name the thing that DOES work, or it is a dead end.
        assert!(err.contains("external:mini-swe-agent"), "{err}");
    }

    /// Positive control on the two above: the same fixture shape with a
    /// production adapter DOES resolve through the fallback, so the assertions
    /// are testing the exclusion and not a broken fixture.
    #[test]
    fn an_unnamed_request_still_resolves_to_a_production_agent() {
        // `codex` is in DEFAULT_PREFERENCE; use an id that is not, so this
        // exercises the same `or_else` fallback the baseline is held out of.
        let detected = agents(&["some-future-cli"], &[]);
        let r = resolve_engine(
            &EngineChoice::External(String::new()),
            &complex_intent(),
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(r.engine, EngineChoice::External("some-future-cli".into()));
    }

    #[test]
    fn auto_simple_task_stays_native_even_with_clis() {
        let detected = agents(&["claude-code"], &[]);
        let r = resolve_engine(
            &EngineChoice::Auto,
            "fix typo in README",
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(r.engine, EngineChoice::Native, "{}", r.reason);
    }

    #[test]
    fn auto_complex_task_delegates_foreman_first_in_preference_order() {
        let detected = agents(&["gemini", "claude-code"], &["codex"]);
        let r = resolve_engine(
            &EngineChoice::Auto,
            &complex_intent(),
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(
            r.engine,
            EngineChoice::Foreman("claude-code".into()),
            "foreman-first with preference order: {}",
            r.reason
        );
    }

    #[test]
    fn explicit_foreman_resolves_and_fails_clearly() {
        let detected = agents(&["codex"], &["claude-code"]);
        let r = resolve_engine(
            &EngineChoice::Foreman(String::new()),
            "x",
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(r.engine, EngineChoice::Foreman("codex".into()));

        let err = resolve_engine(
            &EngineChoice::Foreman("claude-code".into()),
            "x",
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap_err();
        assert!(err.contains("not ready"), "{err}");

        let err = resolve_engine(
            &EngineChoice::Foreman(String::new()),
            "x",
            &agents(&[], &[]),
            &DEFAULT_PREFERENCE,
        )
        .unwrap_err();
        assert!(err.contains("no external agent"), "{err}");
    }

    #[test]
    fn ready_agent_outside_preference_still_selected() {
        let detected = agents(&["future-cli"], &[]);
        let r = resolve_engine(
            &EngineChoice::External(String::new()),
            "x",
            &detected,
            &DEFAULT_PREFERENCE,
        )
        .unwrap();
        assert_eq!(r.engine, EngineChoice::External("future-cli".into()));
    }

    #[test]
    fn parse_round_trips() {
        for (input, expect) in [
            ("auto", EngineChoice::Auto),
            ("", EngineChoice::Auto),
            ("native", EngineChoice::Native),
            ("external", EngineChoice::External(String::new())),
            (
                "external:claude-code",
                EngineChoice::External("claude-code".into()),
            ),
            ("foreman", EngineChoice::Foreman(String::new())),
            ("foreman:codex", EngineChoice::Foreman("codex".into())),
        ] {
            assert_eq!(EngineChoice::parse(input).unwrap(), expect);
        }
        assert!(EngineChoice::parse("warp-drive").is_err());
        assert!(EngineChoice::parse("external:").is_err());
        assert!(EngineChoice::parse("foreman:").is_err());
    }
}