supercode_harness/

model_catalog.rs

//! §2 module 26 `model.catalog` (`docs/composable-harness/
//! COMPOSABLE-HARNESS-DESIGN.md` §3.1 `[capabilities.model_catalog]`) — P4
//! of the composable-harness migration (design §5.2 phase **P4**: "aliases +
//! fallback chains (userconfig.rs:386-411) promoted into core" + the
//! `small_model` knob).
//!
//! **What moved here.** The CLI's `alias_table`/`resolve_model_alias`
//! (`crates/cli/src/userconfig.rs`) were CLI-only (design §1.10: "CLI model
//! aliases ✓ … `resolve_model_alias`, userconfig.rs:386-411"). This module is
//! the single source of truth now — [`DEFAULT_ALIASES`] is the exact same
//! eleven built-in aliases, byte-identical, so moving them here changes no
//! resolved slug for any existing caller. The CLI crate re-exports through
//! `userconfig::alias_table`/`resolve_model_alias` (zero call-site churn,
//! zero behavior change — see that module).
//!
//! **What's NEW (P4).** [`resolve_alias`] additionally accepts an
//! `extra` table (`[capabilities.model_catalog].aliases`, §3.1/§3.2:
//! "`capabilities.model_catalog.*` | CLI `alias_table` … + NEW
//! small-model/fallback") so a user's own config can add or override an
//! alias without recompiling — `extra` is checked BEFORE
//! [`DEFAULT_ALIASES`], so a user override always wins. [`resolve_fallback_chain`]
//! resolves a `[capabilities.model_catalog].fallback` list of aliases/slugs
//! into a plain slug list the SAME way, for the D-9-adjacent "failure
//! fallback chain" knob (catalog §4a: "Model aliases + failure fallback
//! chain (resolution table before request build)").
//!
//! **Scope note (S-sized, per design §5.2 P4).** This module lands the
//! RESOLUTION TABLE only — `Config::small_model`/`Config::model_fallback`
//! are knobs a caller can read, not a retry/failover LOOP that automatically
//! re-sends a failed request against the next model in the chain. Building
//! that loop is a distinct, larger change (closer to §1.10's "mid-session
//! model switch," itself called out in design §5.2 as its own M-sized item,
//! separate from this S-sized catalog item) and is out of scope here.

/// The built-in alias → full-slug table (byte-identical to the CLI's
/// original `userconfig::alias_table`, moved here as the single source of
/// truth — see the module doc).
pub const DEFAULT_ALIASES: &[(&str, &str)] = &[
    ("opus", "anthropic/claude-opus-4-8"),
    ("sonnet", "anthropic/claude-sonnet-4-6"),
    ("gpt", "openai/gpt-5.5"),
    ("gpt-5.5", "openai/gpt-5.5"),
    ("gpt-5", "openai/gpt-5"),
    ("gemini", "google/gemini-2.5-pro"),
    ("flash", "deepseek/deepseek-v4-flash"),
    ("deepseek-flash", "deepseek/deepseek-v4-flash"),
    ("deepseek", "deepseek/deepseek-v4-pro"),
    ("llama", "meta-llama/llama-4-maverick"),
];

/// Expand a friendly model alias to its full slug through the built-in
/// table alone — the no-config path, for callers that have no resolved
/// [`Routing`] in hand (an imported foreign session's recorded model name, a
/// help listing). Unknown values pass through unchanged so any real slug
/// still works. A caller that DOES have a config resolves through
/// [`Routing::resolve_alias`] instead, which additionally honours the
/// config's own alias table, its patterns, and its provider/account scopes.
pub fn resolve_alias(model: &str) -> String {
    Routing::default().resolve_alias(model)
}

/// Everything `[capabilities.model_catalog]` resolves into, alias-resolved:
/// the effective `core.model`, the `small_model` (if set), and the
/// `fallback` chain (if set). Shared by both resolution paths that carry a
/// `capabilities.<name>` table shaped like [`crate::configfile::CapabilityConfig`]
/// — the SDK's [`crate::configfile::HarnessConfig`] resolver
/// (`materialize_config`) and the CLI's own `FileConfig`-driven
/// `build_config` — so the alias/small-model/fallback resolution logic
/// lives in exactly one place.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Resolution {
    /// `base_model`, alias-resolved.
    pub model: String,
    /// `capabilities.model_catalog.small_model`, alias-resolved, if set to
    /// a non-empty string.
    pub small_model: Option<String>,
    /// `capabilities.model_catalog.fallback`, alias-resolved in order, if
    /// non-empty.
    pub fallback: Vec<String>,
    /// BP-5 (`capabilities.model_catalog.base_prompts`, catalog D2
    /// "Per-model-family base-prompt selection"): model-id glob → that
    /// family's base system prompt. Empty unless the config sets the table.
    pub base_prompts: std::collections::BTreeMap<String, String>,
    /// BP-13: the whole routing table (aliases, per-model rules, allow/deny
    /// lists) — carried forward onto [`crate::Config::model_routing`] so
    /// every later routing decision asks THIS value rather than re-reading
    /// the capability table behind this module's back.
    pub routing: Routing,
    /// BP-13: why `model` is refused by the config-layer allow/deny lists,
    /// or `None`. Reported by the resolver, never silently applied.
    pub refusal: Option<String>,
}

/// Resolve `[capabilities.model_catalog]` against `base_model` (typically
/// the already-computed `core.model` / CLI `--model`/config value).
/// Consulted regardless of `capabilities.model_catalog.enabled` — matching
/// the resolver's existing D-9 check (`configfile::validate_modules`),
/// which already reads `model_catalog.small_model` unconditionally: these
/// are data a caller resolves against, not an activation switch.
pub fn resolve(
    capabilities: &std::collections::BTreeMap<String, crate::configfile::CapabilityConfig>,
    base_model: &str,
) -> Resolution {
    let routing = Routing::from_capabilities(capabilities);

    let mut out = Resolution {
        model: if base_model.is_empty() {
            String::new()
        } else {
            routing.resolve_alias(base_model)
        },
        small_model: None,
        fallback: Vec::new(),
        base_prompts: std::collections::BTreeMap::new(),
        refusal: None,
        routing,
    };

    if let Some(cap) = capabilities.get("model_catalog") {
        if let Some(sm) = cap.settings.get("small_model").and_then(|v| v.as_str()) {
            if !sm.is_empty() {
                out.small_model = Some(out.routing.resolve_alias(sm));
            }
        }
        // BP-5: the per-family base-prompt table. Read here, next to
        // `small_model`/`fallback`, for the same reason those are: it is
        // DATA a caller resolves against, not an activation switch.
        if let Some(table) = cap.settings.get("base_prompts").and_then(|v| v.as_object()) {
            out.base_prompts = table
                .iter()
                .filter_map(|(pattern, body)| {
                    body.as_str()
                        .filter(|text| !text.is_empty())
                        .map(|text| (pattern.clone(), text.to_string()))
                })
                .collect();
        }
        if let Some(fb) = cap.settings.get("fallback").and_then(|v| v.as_array()) {
            out.fallback = fb
                .iter()
                .filter_map(|v| v.as_str())
                .map(|m| out.routing.resolve_alias(m))
                .collect();
        }
    }
    // The allow/deny lists bind every model this table hands out, not just
    // `core.model` — a fallback entry or a small model the org forbids is
    // exactly as forbidden as a main model it forbids.
    out.refusal = [Some(&out.model)]
        .into_iter()
        .flatten()
        .chain(out.small_model.iter())
        .chain(out.fallback.iter())
        .filter(|m| !m.is_empty())
        .find_map(|m| out.routing.refusal(m));
    out
}

/// BP-5 (catalog D2 "Per-model-family base-prompt selection", cx§2
/// "Per-model base instructions": "the system prompt is selected per model
/// family from bundled markdown"): the base prompt `model` should run
/// under, or `None` when no family pattern matches.
///
/// `prompts` is keyed by a [`crate::config::glob_match`] pattern over the
/// model id (`"*codex*"`, `"openai/gpt-5.*"`). The MOST SPECIFIC match wins,
/// specificity being the pattern's own length — a TOML table has no order to
/// rely on, so selection must not depend on one. Ties (equal-length patterns
/// both matching) break lexicographically, so the answer is total and
/// reproducible.
pub fn base_prompt_for<'a>(
    prompts: &'a std::collections::BTreeMap<String, String>,
    model: &str,
) -> Option<&'a str> {
    prompts
        .iter()
        .filter(|(pattern, _)| crate::config::glob_match(pattern, model))
        .max_by(|(a, _), (b, _)| a.len().cmp(&b.len()).then_with(|| b.cmp(a)))
        .map(|(_, body)| body.as_str())
}

// ---------------------------------------------------------------------------
// BP-13 — the ONE model-resolution path.
// ---------------------------------------------------------------------------
//
// Everything routing decides about a model — which slug a friendly name means,
// which reasoning effort and thinking budget the request carries, which service
// tier it asks for, which tool-shape capability bits the registry reads, and
// whether the model is allowed at all — resolves HERE, out of the same
// `[capabilities.model_catalog]` table the presets already set. There is no
// second table, no parallel registry, and no consumer that reads a raw setting
// behind this module's back: `configfile::materialize_config` folds this into
// `Config::model_routing`, and every consumer (`Agent`'s request build, its
// fallback pass, `ToolRegistry::from_config`, the CLI's `--model`/`/model`)
// asks the SAME `Routing` value.

/// The reasoning-effort ladder, weakest first. Spans both harnesses' own
/// vocabularies: Claude Code's `low|medium|high` and Codex's `none…ultra`
/// (cc§9, cx§6/§9). A level outside the ladder is not an error — it is
/// forwarded verbatim to the provider — but it cannot be RANKED, so an
/// effort cap can neither clamp it nor be fooled by it (see [`cap_effort`]).
pub const EFFORT_LADDER: &[&str] = &["none", "minimal", "low", "medium", "high", "xhigh", "ultra"];

/// Position of `level` on [`EFFORT_LADDER`], or `None` for a level this
/// build does not rank.
pub fn effort_rank(level: &str) -> Option<usize> {
    EFFORT_LADDER.iter().position(|l| *l == level)
}

/// Clamp `level` down to `cap`. Returns `level` unchanged when there is no
/// cap, when the cap does not bind, or when EITHER side is unrankable (an
/// unknown spelling must not be silently rewritten into a ladder value the
/// user never asked for).
pub fn cap_effort(level: Option<&str>, cap: Option<&str>) -> Option<String> {
    let level = level?;
    let Some(cap) = cap else {
        return Some(level.to_string());
    };
    match (effort_rank(level), effort_rank(cap)) {
        (Some(l), Some(c)) if l > c => Some(cap.to_string()),
        _ => Some(level.to_string()),
    }
}

/// Match `value` against a model PATTERN and return what the wildcard
/// captured.
///
/// A pattern is either an exact slug (matches by equality; the capture is
/// the whole value) or a single-`*` glob (`opus*`, `*[1m]`, `openai/gpt-5*`),
/// where `*` stands for any run of characters including the empty one. A
/// second `*` is not a pattern this build understands and never matches, so
/// a typo fails closed rather than matching everything.
pub fn pattern_capture(pattern: &str, value: &str) -> Option<String> {
    match pattern.split_once('*') {
        None => (pattern == value).then(|| value.to_string()),
        Some((prefix, suffix)) => {
            if suffix.contains('*') {
                return None;
            }
            if value.len() < prefix.len() + suffix.len() {
                return None;
            }
            if !value.starts_with(prefix) || !value.ends_with(suffix) {
                return None;
            }
            Some(value[prefix.len()..value.len() - suffix.len()].to_string())
        }
    }
}

/// How specific a pattern is: its literal (non-wildcard) length, with an
/// exact pattern always beating a glob of the same literal length. Used to
/// order overlays so the most specific rule wins.
fn pattern_specificity(pattern: &str) -> (usize, u8) {
    let literal = pattern.chars().filter(|c| *c != '*').count();
    (literal, u8::from(!pattern.contains('*')))
}

/// Per-model routing rules: what `[capabilities.model_catalog.models.<pattern>]`
/// (and the table's own top-level defaults) say about one model.
///
/// Every field is `Option` so "unset" and "set to the default value" stay
/// distinguishable — an unset field inherits, a set one overrides.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ModelRules {
    /// Reasoning-effort level for this model — the per-model override of
    /// `[core] effort` (cc§9 effort levels, cx§9 tiers).
    pub effort: Option<String>,
    /// Ceiling on the effort level for this model. Applied AFTER `effort`
    /// and after `[core] effort`, so a cap binds whatever the level came
    /// from — the per-model half of the org effort cap.
    pub max_effort: Option<String>,
    /// Thinking-token budget (Claude Code's `MAX_THINKING_TOKENS`).
    pub thinking_budget: Option<u32>,
    /// Service tier / fast-mode variant asked for on the request
    /// (cc `/fast`, cx `model_service_tier`).
    pub service_tier: Option<String>,
    /// Capability bit: this model takes the freeform `apply_patch`
    /// envelope. `Some(false)` swaps the write surface to `edit_file` /
    /// `write_file` instead (cx§9 `apply_patch_tool_type`).
    pub apply_patch: Option<bool>,
    /// Capability bit: this model takes the dedicated search tool
    /// (cx§9 `supports_search_tool`).
    pub search_tool: Option<bool>,
}

impl ModelRules {
    /// Overlay `other`'s SET fields onto `self`; unset fields inherit.
    pub fn overlay(&mut self, other: &ModelRules) {
        if other.effort.is_some() {
            self.effort.clone_from(&other.effort);
        }
        if other.max_effort.is_some() {
            self.max_effort.clone_from(&other.max_effort);
        }
        if other.thinking_budget.is_some() {
            self.thinking_budget = other.thinking_budget;
        }
        if other.service_tier.is_some() {
            self.service_tier.clone_from(&other.service_tier);
        }
        if other.apply_patch.is_some() {
            self.apply_patch = other.apply_patch;
        }
        if other.search_tool.is_some() {
            self.search_tool = other.search_tool;
        }
    }

    fn from_settings(obj: &serde_json::Map<String, serde_json::Value>) -> ModelRules {
        let text = |key: &str| {
            obj.get(key)
                .and_then(|v| v.as_str())
                .filter(|s| !s.is_empty())
                .map(str::to_string)
        };
        ModelRules {
            effort: text("effort"),
            max_effort: text("max_effort"),
            thinking_budget: obj
                .get("thinking_budget")
                .and_then(|v| v.as_u64())
                .filter(|n| *n > 0)
                .map(|n| n as u32),
            service_tier: text("service_tier"),
            apply_patch: obj.get("apply_patch").and_then(|v| v.as_bool()),
            search_tool: obj.get("search_tool").and_then(|v| v.as_bool()),
        }
    }
}

/// The whole resolved routing table, carried on
/// [`crate::Config::model_routing`] and consulted by every routing decision.
///
/// It keeps the PATTERNS rather than one pre-resolved answer on purpose: a
/// mid-session model switch has to re-decide effort, budget, tier and tool
/// bits for the NEW model, and it does that by asking this same value again
/// ([`Routing::rules_for`]) rather than by re-reading config elsewhere.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Routing {
    /// Alias → slug entries from the config, in precedence order: the
    /// declared account's scope, then the declared provider's, then the flat
    /// table. Consulted before [`DEFAULT_ALIASES`]. A key may be a `*`
    /// pattern, in which case the value may contain `{}` — replaced by the
    /// captured stem after that stem is itself alias-resolved (Claude Code's
    /// `sonnet[1m]` shape).
    pub aliases: Vec<(String, String)>,
    /// `[capabilities.model_catalog.models.<pattern>]`, least specific
    /// first, so overlaying in order leaves the most specific rule winning.
    pub models: Vec<(String, ModelRules)>,
    /// The table's own top-level rules — the baseline every model inherits.
    pub defaults: ModelRules,
    /// `allowed_models`: when non-empty, a model matching NO entry is
    /// refused outright.
    pub allowed: Vec<String>,
    /// `denied_models`: a model matching any entry is refused outright.
    pub denied: Vec<String>,
    /// The declared provider whose alias scope is in force (`provider`).
    pub provider: Option<String>,
    /// The declared account/plan tier whose alias scope is in force
    /// (`account`) — Claude Code's account-type defaults (cc§9).
    pub account: Option<String>,
}

impl Routing {
    /// Expand a friendly model name to a full slug through this table, then
    /// [`DEFAULT_ALIASES`], then unchanged pass-through.
    ///
    /// Exact entries always beat patterns, and among patterns the most
    /// specific wins. A pattern's `{}` placeholder receives the captured
    /// stem RE-RESOLVED through this same function (depth-capped), which is
    /// what makes `sonnet[1m]` land on `anthropic/claude-sonnet-4-6[1m]`
    /// rather than on the literal text `sonnet[1m]`.
    pub fn resolve_alias(&self, model: &str) -> String {
        self.resolve_alias_depth(model, 0)
    }

    fn resolve_alias_depth(&self, model: &str, depth: usize) -> String {
        if depth > 4 {
            return model.to_string();
        }
        for (alias, slug) in &self.aliases {
            if !alias.contains('*') && alias == model {
                return slug.clone();
            }
        }
        if let Some((_, slug)) = DEFAULT_ALIASES.iter().find(|(a, _)| *a == model) {
            return (*slug).to_string();
        }
        let mut best: Option<(usize, u8, &str, String)> = None;
        for (alias, slug) in &self.aliases {
            if !alias.contains('*') {
                continue;
            }
            let Some(stem) = pattern_capture(alias, model) else {
                continue;
            };
            let (literal, exact) = pattern_specificity(alias);
            if best
                .as_ref()
                .is_none_or(|(l, e, _, _)| (literal, exact) > (*l, *e))
            {
                best = Some((literal, exact, slug.as_str(), stem));
            }
        }
        match best {
            Some((_, _, template, stem)) => {
                let expanded = self.resolve_alias_depth(&stem, depth + 1);
                template.replace("{}", &expanded)
            }
            None => model.to_string(),
        }
    }

    /// The rules in force for `model`: the table defaults with every
    /// matching `models.<pattern>` overlaid, least specific first.
    pub fn rules_for(&self, model: &str) -> ModelRules {
        let mut rules = self.defaults.clone();
        for (pattern, r) in &self.models {
            if pattern_capture(pattern, model).is_some() {
                rules.overlay(r);
            }
        }
        rules
    }

    /// The effort level to send for `model`, given the session's
    /// `[core] effort`: the per-model level if one is set, else the session
    /// level, clamped by whichever effort cap applies.
    pub fn effective_effort(&self, model: &str, session_effort: Option<&str>) -> Option<String> {
        let rules = self.rules_for(model);
        let level = rules.effort.as_deref().or(session_effort);
        cap_effort(level, rules.max_effort.as_deref())
    }

    /// Why `model` is refused, or `None` when it is allowed — the
    /// CONFIG-layer half of the org model allowlist. A denied model can
    /// never be selected, and with an allowlist set nothing outside it can.
    pub fn refusal(&self, model: &str) -> Option<String> {
        if let Some(pattern) = self
            .denied
            .iter()
            .find(|p| pattern_capture(p, model).is_some())
        {
            return Some(format!(
                "model `{model}` matches capabilities.model_catalog.denied_models entry `{pattern}`"
            ));
        }
        if !self.allowed.is_empty()
            && !self
                .allowed
                .iter()
                .any(|p| pattern_capture(p, model).is_some())
        {
            return Some(format!(
                "model `{model}` is not in capabilities.model_catalog.allowed_models ({})",
                self.allowed.join(", ")
            ));
        }
        None
    }

    /// Whether anything in this table restricts model choice at all.
    pub fn restricts_models(&self) -> bool {
        !self.allowed.is_empty() || !self.denied.is_empty()
    }

    /// Build the routing table from `[capabilities.model_catalog]`.
    ///
    /// Consulted regardless of the module's `enabled` flag, for the same
    /// reason [`resolve`] is: these are data a caller resolves against, not
    /// an activation switch (and the D-9 resolver check already reads
    /// `small_model` unconditionally).
    pub fn from_capabilities(
        capabilities: &std::collections::BTreeMap<String, crate::configfile::CapabilityConfig>,
    ) -> Routing {
        let Some(cap) = capabilities.get("model_catalog") else {
            return Routing::default();
        };
        let s = &cap.settings;
        let scope = |key: &str| {
            s.get(key)
                .and_then(|v| v.as_str())
                .filter(|p| !p.is_empty())
                .map(str::to_string)
        };
        let provider = scope("provider");
        let account = scope("account");

        // Alias scopes, most specific first: the declared account's table,
        // then the declared provider's, then the flat table.
        let mut aliases: Vec<(String, String)> = Vec::new();
        let provider_table = provider
            .as_deref()
            .and_then(|p| s.get("providers")?.as_object()?.get(p))
            .and_then(|v| v.as_object());
        if let (Some(pt), Some(account)) = (provider_table, account.as_deref()) {
            if let Some(at) = pt
                .get("accounts")
                .and_then(|v| v.as_object())
                .and_then(|a| a.get(account))
                .and_then(|v| v.as_object())
            {
                push_alias_table(at.get("aliases"), &mut aliases);
            }
        }
        if let Some(pt) = provider_table {
            push_alias_table(pt.get("aliases"), &mut aliases);
        }
        push_alias_table(s.get("aliases"), &mut aliases);

        let mut models: Vec<(String, ModelRules)> = s
            .get("models")
            .and_then(|v| v.as_object())
            .map(|o| {
                o.iter()
                    .filter_map(|(pattern, v)| {
                        Some((pattern.clone(), ModelRules::from_settings(v.as_object()?)))
                    })
                    .collect()
            })
            .unwrap_or_default();
        models.sort_by_key(|(pattern, _)| pattern_specificity(pattern));

        Routing {
            aliases,
            models,
            defaults: ModelRules::from_settings(s),
            allowed: string_list(s.get("allowed_models")),
            denied: string_list(s.get("denied_models")),
            provider,
            account,
        }
    }
}

fn push_alias_table(value: Option<&serde_json::Value>, out: &mut Vec<(String, String)>) {
    let Some(obj) = value.and_then(|v| v.as_object()) else {
        return;
    };
    let mut entries: Vec<(String, String)> = obj
        .iter()
        .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
        .collect();
    entries.sort();
    out.extend(entries);
}

fn string_list(value: Option<&serde_json::Value>) -> Vec<String> {
    value
        .and_then(|v| v.as_array())
        .map(|a| {
            a.iter()
                .filter_map(|v| v.as_str().map(str::to_string))
                .collect()
        })
        .unwrap_or_default()
}