lean_ctx/core/config/

proxy.rs

//! API proxy upstream overrides (`config.toml`).

use lean_ctx_protocol::ProtocolReference;
use serde::{Deserialize, Serialize};

#[path = "proxy_upstream.rs"]
mod upstream;
use upstream::is_custom_upstream_host;
pub(super) use upstream::validate_upstream_url;
pub use upstream::{
    ProxyProvider, UpstreamDrift, Upstreams, diagnose_drift, env_upstream_override,
    is_local_proxy_url, normalize_url, normalize_url_opt,
};

/// API proxy upstream overrides. `None` = use provider default.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct ProxyConfig {
    pub anthropic_upstream: Option<String>,
    pub openai_upstream: Option<String>,
    pub chatgpt_upstream: Option<String>,
    pub gemini_upstream: Option<String>,
    /// Universal provider registry (`[[proxy.providers]]`): additional upstream
    /// providers beyond the four built-ins, declared as data — id + wire shape +
    /// base URL — so a new OpenAI/Anthropic/Gemini/Bedrock endpoint (Azure AI
    /// Foundry, OpenRouter, Groq, vLLM/Ollama, a corporate gateway…) is a pure
    /// config entry, never a code change. Reachable under
    /// `/providers/{id}/...` on the proxy and addressable by the router.
    /// The legacy `*_upstream` fields above stay authoritative for the four
    /// built-in provider routes (backwards compatible).
    pub providers: Vec<ProviderEntry>,
    /// History-pruning strategy for proxied chat requests.
    /// "cache-aware" (default) | "rolling" | "off". See [`HistoryMode`].
    pub history_mode: Option<String>,
    /// Allow a non-loopback plaintext `http://` upstream (trusted local network
    /// only). Opt-in; see [`ProxyConfig::allows_insecure_http_upstream`]. (#440)
    pub allow_insecure_http_upstream: Option<bool>,
    /// Allow a custom (non-allowlisted) **HTTPS** upstream host — e.g. a corporate
    /// gateway in front of the provider API. Opt-in; see
    /// [`ProxyConfig::allows_custom_upstream`]. Mirrors `allow_insecure_http_upstream`
    /// so the long-lived managed proxy (LaunchAgent / systemd), which only reads
    /// `config.toml` and never the shell's `LEAN_CTX_ALLOW_CUSTOM_UPSTREAM`, can
    /// honor a custom upstream too (#590).
    pub allow_custom_upstream: Option<bool>,
    /// mz14: allow a `[[proxy.providers]]` entry that points at a vendor's own
    /// China-hosted API (a `[[direct]]` host of the bundled model catalog:
    /// DeepSeek, Z.ai, MiniMax). Default `false`: such a request is refused
    /// with 403 `cn_direct_opt_in_required`. An org policy with
    /// `vendor_direct_cn = false` voids this opt-in. Config only, no env var.
    pub allow_vendor_direct_cn: Option<bool>,
    /// Absolute project root the proxy acts for; operator-set only, verified at
    /// use. Env `LEAN_CTX_PROXY_PROJECT_ROOT`. See `proxy::request_project`.
    pub project_root: Option<String>,
    /// Inject `stream_options.include_usage = true` into streamed OpenAI Chat
    /// Completions so the final chunk reports real token usage for the measured
    /// spend meter. Default on; set `false` for a client that mishandles the
    /// trailing usage chunk. Anthropic/Gemini/OpenAI-Responses report usage
    /// without any request change, so this only affects Chat Completions.
    pub meter_openai_usage: Option<bool>,
    /// Additional response header carrying the upstream gateway's billed USD
    /// for the turn (#1189). LiteLLM's `x-litellm-response-cost` is always
    /// recognized; set this for a corporate gateway that reports the charge
    /// under its own header name. Measured header costs beat table estimates
    /// (body-reported costs, e.g. OpenRouter `usage.cost`, beat headers).
    pub cost_response_header: Option<String>,
    /// Opt-in "big-gap cold-prefix repack" (#480). When the proxy can confidently
    /// predict (from idle time vs the provider cache TTL) that the client-cached
    /// prefix has already expired, it overrides the normal "never rewrite the
    /// cached prefix" rule for that one resume request and prunes the now-cold
    /// prefix too, re-seeding a leaner cache. `None`/`false` (the default) keeps
    /// the prefix always protected. See [`ProxyConfig::repacks_cold_prefix`].
    pub cold_prefix_repack: Option<bool>,
    /// Opt-in per-role prose compression for the proxy's frozen request region
    /// (#710). `None` for a role (the default) leaves that role untouched —
    /// today's behaviour. See [`RoleAggressiveness`].
    pub role_aggressiveness: RoleAggressiveness,
    /// Live tool-result compression on the wire (#481). `true` (the default)
    /// keeps today's behaviour: the proxy compresses non-protected `tool_result`
    /// content on every request. `false` turns it off so the proxy can run
    /// **meter-only** — real billed/cache token metering with zero request
    /// rewriting (combine with `history_mode = "off"`, `long_session_elide =
    /// false` — env `LEAN_CTX_PROXY_LONG_SESSION_ELIDE=off`, the default — and
    /// no `role_aggressiveness` for a fully byte-unchanged body).
    /// Env `LEAN_CTX_PROXY_LIVE_COMPRESS`.
    /// See [`ProxyConfig::live_compresses`].
    pub live_compress: Option<bool>,
    /// Per-tool exclusion list for live tool-result compression (#481). Tool
    /// names are matched case-insensitively as substrings (the same style as
    /// `proxy::tool_kind::classify_tool_name`); a match is treated as
    /// protected, exactly like a file read. `None` (the default) protects
    /// Serena's code-reading tools (`find_symbol`/`find_referencing_symbols`/
    /// `search_for_pattern` return source bodies the model edits, but are
    /// mis-bucketed as `Search` by name). Set an explicit list to narrow it, or
    /// `[]` to disable the exclusion. See [`ProxyConfig::is_tool_live_compress_excluded`].
    pub live_compress_exclude: Option<Vec<String>>,
    /// File-path globs whose reads are never compressed (#1150). A read whose path
    /// matches any of these is returned verbatim (`full`) by the read tools — for
    /// files where exact bytes matter more than token savings: golden snapshots,
    /// byte-asserted fixtures, security-sensitive configs. Globs (`*`/`**`/`?`,
    /// the `glob` crate) are matched against the path and its file name, so
    /// `*.snap`, `**/golden/**`, and `tests/fixtures/*` all work. `None`/empty (the
    /// default) protects nothing — the lossless crushers and beneficial gate
    /// already keep compression safe, so this is an explicit escape hatch, not a
    /// default. See [`ProxyConfig::is_path_compress_protected`].
    pub compress_protect: Option<Vec<String>>,
    /// Opt-in in-band CCR retrieval for a remote proxy with no shared filesystem
    /// (#493, follow-up to #482). When enabled, a lossy stub advertises a compact
    /// `<lc_expand:HASH>` marker (instead of a local tee path the remote agent
    /// can't read); when the model echoes that marker back, the proxy splices the
    /// verbatim original — recovered from its **local** tee store — inline on the
    /// next request, costing one turn of latency and needing no MCP/FS on the
    /// agent host. `None`/`false` (the default) keeps the path-handle stub. The
    /// splice is a strict no-op on marker-less turns, so it never perturbs the
    /// provider cache prefix unless the model explicitly asked to expand. See
    /// [`ProxyConfig::ccr_inband_enabled`].
    pub ccr_inband: Option<bool>,
    /// Opt-in active prompt-cache breakpoint injection for Anthropic (#939). When
    /// enabled and the client set no `cache_control` of its own, the proxy adds a
    /// single `cache_control: {type:"ephemeral"}` breakpoint to the `system`
    /// field so an otherwise-uncached, stable system prompt bills later turns at
    /// the cached rate. Anthropic-only: OpenAI/Gemini cache prefixes automatically
    /// and ignore the marker, so those paths stay byte-unchanged. The injection is
    /// deterministic, never adds a second breakpoint, and is skipped below
    /// Anthropic's minimum cacheable size. `None`/`false` (the default) leaves the
    /// request untouched. See [`ProxyConfig::cache_breakpoint_enabled`].
    pub cache_breakpoint: Option<bool>,
    /// Agent-loop cache lifetime for Anthropic. While the model works through
    /// tool calls (the request ends in tool results), the conversation's cache
    /// markers are written for 5 minutes instead of 1 hour; the person's last
    /// prompt keeps a 1 h marker of its own, so a long pause loses at most this
    /// turn's tool steps. A 1 h write costs 2x the input price, a 5 min write
    /// 1.25x. See [`ProxyConfig::cache_ttl_loop_enabled`].
    pub cache_ttl_loop: Option<bool>,
    /// Long-session elision for Anthropic. Once a conversation's messages pass
    /// 180 000 characters, tool output older than the live window and longer
    /// than 2 000 characters leaves as a one-line stub naming a private archive
    /// file with the full text. See [`ProxyConfig::long_session_elide_enabled`].
    pub long_session_elide: Option<bool>,
    /// Opt-in counterfactual savings metering (#701). When enabled, each
    /// *rewritten* Anthropic `/v1/messages` request additionally fires a **free**
    /// `count_tokens` probe with the original, uncompressed body, concurrently
    /// with the real forward. The provider-counted answer ("this request would
    /// have cost N input tokens without lean-ctx") is paired with the actually
    /// billed usage from the same response — provider-authoritative receipts
    /// instead of local tokenizer estimates. The probe never mutates or delays
    /// the forwarded request; probe failures degrade to the estimate. Off by
    /// default: it adds one extra HTTP call per compressed request (free at
    /// Anthropic, but latency/rate-limit surface). See
    /// [`ProxyConfig::counterfactual_metering_enabled`].
    pub counterfactual_metering: Option<bool>,
    /// Opt-in cache-aligner volatile-field telemetry (#940). When enabled, the
    /// proxy scans each *unanchored* Anthropic system prompt for volatile,
    /// cache-busting fields (ISO dates/datetimes, UUIDs, git SHAs) and records how
    /// many it found on `/status` `cache_safety` — purely to quantify how much
    /// prompt-cache the client is leaking. **Measurement only**: the request body
    /// is never mutated, so it is strictly cache-safe. `None` (the default) enables
    /// it — every proxy ships cache-leak visibility out of the box (#986 premium
    /// defaults); set `false` to opt out of the per-request scan. See
    /// [`ProxyConfig::cache_aligner_enabled`].
    pub cache_aligner: Option<bool>,
    /// Opt-in active cache-aligner relocate (#974). When enabled, the proxy
    /// rewrites an *unanchored* Anthropic `system` prompt into a stable block
    /// (volatile values — ISO dates/datetimes, UUIDs, git SHAs — replaced by
    /// constant placeholders) carrying the `cache_control` breakpoint, plus an
    /// *uncached* trailing block that re-states the relocated values. The cacheable
    /// prefix then stays byte-stable turn-to-turn and finally caches; only the
    /// small tail is reprocessed. Anthropic-only, Treatment-arm, gated on a client
    /// that anchored nothing and on Anthropic's minimum cacheable size.
    /// Deterministic (#498) and idempotent. `None`/`false` (the default) leaves the
    /// request untouched. The `cache_aligner` telemetry above is the precursor that
    /// quantifies how much this would save. See
    /// [`ProxyConfig::cache_align_relocate_enabled`].
    pub cache_align_relocate: Option<bool>,
    /// Cache-economics (#986), **on by default**. Bundles two strictly-safe halves
    /// behind one flag: (1) prompt-cache **miss attribution** telemetry — per turn,
    /// classify why the cache hit or missed (cold start / warm reuse / TTL lapse /
    /// prefix change) and expose cumulative gauges on `/status`
    /// (`proxy::cache_attribution`); and (2) a **net-cost gate** on the
    /// cold-prefix repack (`proxy::cache_policy::worth_repacking`) that
    /// skips re-seeding prefixes too small to be cached. The telemetry never
    /// touches the body and the gate only makes repacking *more* conservative, so
    /// it can never bust a cache that would otherwise have been kept. `None` (the
    /// default) enables both — every proxy gets the diagnosis and the safer repack
    /// out of the box (#986 premium defaults); set `false` to opt out. See
    /// [`ProxyConfig::cache_policy_enabled`].
    pub cache_policy: Option<bool>,
    /// Cache-safe, cross-provider reasoning-effort control (#834). One of
    /// `minimal|low|medium|high` pins the model's reasoning depth across every
    /// provider; `None`/`"off"` (the default) is a strict no-op. The value is a
    /// constant — identical on every request — so the provider prompt-cache
    /// prefix stays byte-stable (#448/#498) and only the model's reasoning depth
    /// changes. lean-ctx translates it to each provider's native parameter and
    /// only ever *fills* it (never overrides a client-set value), on models that
    /// accept it. Per-turn effort switching is deliberately unsupported — it
    /// would invalidate the prompt cache. Env `LEAN_CTX_PROXY_EFFORT`. See
    /// [`ProxyConfig::resolved_effort`].
    pub effort: Option<String>,
    /// How the proxy squeezes prose it must shrink (#895): `"auto"` (default) and
    /// `"extractive"` use embedding-based extractive ranking — keeping the most
    /// central sentences instead of just the prefix — when the local embedding
    /// engine is available, falling back to truncation otherwise; `"truncate"`
    /// keeps the original deterministic FIFO squeeze (and no engine). Wire
    /// rewrites are memoized per content so the engine's cold→warm transition
    /// never changes an already-emitted frozen-region rewrite (#448/#498). Env
    /// `LEAN_CTX_PROXY_PROSE_RANKER`. See [`ProxyConfig::resolved_prose_ranker`].
    pub prose_ranker: Option<String>,
    /// Fraction `0.0..=1.0` of conversations placed in the output-savings control
    /// arm (#895 Track B). `0` (default) = no holdout (every conversation is
    /// shaped). When `> 0`, a deterministic cohort = `blake3(system + first user
    /// msg)` puts ~this fraction of conversations in a control arm that skips
    /// output-shaping (effort control + verbosity steer) but is still metered —
    /// giving an honest measured output-token reduction. The cohort is a pure
    /// function of conversation identity, so a conversation stays in one arm
    /// across turns (cache-safe). Env `LEAN_CTX_PROXY_OUTPUT_HOLDOUT`. See
    /// [`ProxyConfig::output_holdout_fraction`].
    pub output_holdout: Option<f64>,
    /// Fraction `0.0..=1.0` of conversations placed in the input-compression
    /// control arm (#1905). `0` (default) = no holdout. When `> 0`, a
    /// deterministic cohort (salted separately from `output_holdout`) puts ~this
    /// fraction of conversations in a control arm whose requests are forwarded
    /// without any of the proxy's input compression (tool-output compression,
    /// history pruning, prose rewriting, cold-prefix repack) but still metered,
    /// so the input-token reduction is measured against a real uncompressed
    /// baseline. Env `LEAN_CTX_PROXY_COMPRESSION_HOLDOUT`. See
    /// [`ProxyConfig::compression_holdout_fraction`].
    pub compression_holdout: Option<f64>,
    /// Opt-in cache-safe wire verbosity steer (#895). When `true`, the proxy
    /// appends a single constant "be concise" instruction to the last user turn
    /// of each request (output-shaping for non-rules-aware API clients). The
    /// suffix is constant and appended strictly after the last `cache_control`
    /// breakpoint, so the provider prompt-cache prefix stays byte-stable. Default
    /// `false`. Env `LEAN_CTX_PROXY_VERBOSITY_STEER`. See
    /// [`ProxyConfig::verbosity_steer_enabled`].
    pub verbosity_steer: Option<bool>,
    /// Unified proxy operation mode (`[proxy] proxy_mode`). `"token"` (default)
    /// or `"token"`. Sets sensible defaults for all cache-related knobs; explicit
    /// per-knob overrides always win. Env `LEAN_CTX_PROXY_MODE`.
    pub proxy_mode: Option<String>,
    /// Headroom stacking compatibility (`[proxy] compat_stack`). When set to
    /// `"headroom"`, the proxy auto-configures for running behind Headroom:
    /// live compression off, breakpoint injection off, cache alignment on.
    /// Also auto-detected via the `X-Headroom-Compressed` request header.
    /// Env `LEAN_CTX_PROXY_COMPAT_STACK`.
    pub compat_stack: Option<String>,
    /// Opt-in: route a Codex *ChatGPT-subscription* login through the proxy for
    /// model-turn compression. Default `None`/`false` keeps Codex native (history
    /// visible, cloud/remote intact, no #597). When `true`, Codex setup pins the
    /// generated `leanctx-chatgpt` provider + `chatgpt_base_url`; that scopes Codex
    /// history to the provider (#597), so it stays opt-in. Toggle durably with
    /// `lean-ctx proxy codex-chatgpt on|off`; resolved via
    /// [`ProxyConfig::codex_chatgpt_proxy_enabled`].
    pub codex_chatgpt_proxy: Option<bool>,
    /// Active request routing (`[proxy.routing]`, enterprise#13): model aliases
    /// and intent-tier downgrades applied in the forward path. Off by default —
    /// an empty/absent table is a strict passthrough. See [`RoutingRules`].
    pub routing: RoutingRules,
    /// Counterfactual-baseline parameters (`[proxy.baseline]`, enterprise#15/#18)
    /// for the avoided-cost evidence chain. See [`BaselineConfig`].
    pub baseline: BaselineConfig,
    pub pipeline: PipelineConfig,
    /// Prompt-cache share guard (`[proxy.cache_share]`): rolling cache-read
    /// share per provider+model, its alarm threshold and the provider
    /// allowlist for open models. See [`CacheShareConfig`].
    pub cache_share: CacheShareConfig,
}

/// `[proxy.cache_share]` — guards the provider prompt-cache discount.
///
/// Without prompt caching a long agent session bills every prompt token at
/// the full input rate; with it most prompt tokens bill at the cache-read
/// rate. The proxy keeps a rolling window per provider+model and raises an
/// alarm when the cache-read share of the prompt tokens drops below
/// `alarm_threshold`.
///
/// Open-weight models (Llama, Qwen, DeepSeek, …) are served by many hosts,
/// and not all of them give a reliable cache discount. A provider not in
/// `open_model_providers` is flagged (`open_model_policy = "flag"`, the
/// default) or refused before the request leaves (`"refuse"`). Local
/// endpoints are exempt: nothing is bought there.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(default)]
pub struct CacheShareConfig {
    /// Minimum cache-read share (0–1) of the prompt tokens; default 0.90.
    pub alarm_threshold: Option<f64>,
    /// Rolling window in seconds; default 3600, capped at 7 days.
    pub window_secs: Option<u64>,
    /// Prompt tokens a window needs before the alarm may fire, so the cold
    /// first turn of a session (all cache writes) does not alarm; default 200 000.
    pub min_prompt_tokens: Option<u64>,
    /// Provider ids (registry id or built-in label, case-insensitive) with a
    /// reliable cache discount, allowed to serve open models.
    pub open_model_providers: Vec<String>,
    /// Extra model-name fragments (case-insensitive) counted as open models,
    /// added to the built-in list.
    pub open_model_patterns: Vec<String>,
    /// `"flag"` (default) or `"refuse"` for an open model on a provider
    /// outside `open_model_providers`.
    pub open_model_policy: Option<String>,
}

/// Default cache-read share below which the cache-share alarm fires.
const DEFAULT_CACHE_SHARE_THRESHOLD: f64 = 0.90;
/// Default rolling window of the cache-share guard (one hour).
const DEFAULT_CACHE_SHARE_WINDOW_SECS: u64 = 3_600;
/// Longest rolling window the cache-share guard keeps (seven days).
const MAX_CACHE_SHARE_WINDOW_SECS: u64 = 7 * 24 * 3_600;
/// Default prompt tokens a window needs before the alarm may fire.
const DEFAULT_CACHE_SHARE_MIN_PROMPT_TOKENS: u64 = 200_000;

impl CacheShareConfig {
    /// Configured threshold clamped to 0–1, or the 0.90 default.
    #[must_use]
    pub fn effective_threshold(&self) -> f64 {
        match self.alarm_threshold {
            Some(t) if t.is_finite() => t.clamp(0.0, 1.0),
            _ => DEFAULT_CACHE_SHARE_THRESHOLD,
        }
    }

    /// Configured window clamped to 60 s – 7 days, or one hour.
    #[must_use]
    pub fn effective_window_secs(&self) -> u64 {
        self.window_secs
            .unwrap_or(DEFAULT_CACHE_SHARE_WINDOW_SECS)
            .clamp(60, MAX_CACHE_SHARE_WINDOW_SECS)
    }

    /// Configured minimum prompt tokens, or the default.
    #[must_use]
    pub fn effective_min_prompt_tokens(&self) -> u64 {
        self.min_prompt_tokens
            .unwrap_or(DEFAULT_CACHE_SHARE_MIN_PROMPT_TOKENS)
    }

    /// True when an unlisted provider must refuse an open model; any value
    /// other than `"refuse"` flags only.
    #[must_use]
    pub fn refuses_unlisted_open_models(&self) -> bool {
        self.open_model_policy
            .as_deref()
            .is_some_and(|p| p.trim().eq_ignore_ascii_case("refuse"))
    }
}

/// `[proxy.baseline]` — the contract-frozen counterfactual parameters that make
/// the success fee provable (enterprise#15, Doc 04 §6 / Doc 08 §2).
///
/// - `reference_model`: the model the customer *would have used* without
///   lean-ctx. Frozen per deployment/contract (calibration: enterprise#41);
///   every usage event stores `reference_cost_usd` = the request's
///   **uncompressed** input tokens priced at this model's input rate — the
///   counterfactual cost the avoided-cost ledger settles against.
/// - `local_shadow_rate_per_mtok`: USD per 1M tokens booked as the actual cost
///   of locally served (loopback) inference. Local compute is never free —
///   hardware and power are real — so the shadow rate keeps local-model savings
///   honest instead of infinite. Default: `0.25` USD/MTok, a conservative
///   self-hosting cost estimate; calibrate per deployment.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(default)]
pub struct BaselineConfig {
    /// Counterfactual reference model (`None` = baseline evidence off).
    pub reference_model: Option<String>,
    /// USD per 1M tokens for local/loopback inference (default 0.25, never 0).
    pub local_shadow_rate_per_mtok: Option<f64>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(default)]
pub struct PipelineConfig {
    pub enable_dedup: bool,
    pub enable_prose: bool,
    /// Use KnowledgeRouter references to protect relevant request context.
    pub enable_knowledge_routing: bool,
    pub min_savings_pct: f32,
}

impl Default for PipelineConfig {
    fn default() -> Self {
        Self {
            enable_dedup: true,
            enable_prose: true,
            enable_knowledge_routing: true,
            min_savings_pct: 5.0,
        }
    }
}

/// Default local shadow rate (USD per 1M tokens) when `[proxy.baseline]` sets
/// none: a conservative self-hosted inference cost so `is_local` usage is
/// never booked at $0 (Doc 04 §6 "local-free ≠ cost-free").
pub const DEFAULT_LOCAL_SHADOW_RATE_PER_MTOK: f64 = 0.25;

impl BaselineConfig {
    /// Effective shadow rate: configured value (clamped positive) or default.
    #[must_use]
    pub fn effective_local_shadow_rate(&self) -> f64 {
        match self.local_shadow_rate_per_mtok {
            Some(r) if r > 0.0 => r,
            _ => DEFAULT_LOCAL_SHADOW_RATE_PER_MTOK,
        }
    }
}

/// `[proxy.routing]` — explicit, operator-written model targets.
///
/// **Aliases** map an exact requested model to a fixed target, e.g. an org
/// name (`acme/fast`) onto an approved endpoint or a local model. LeanCTX never
/// chooses a model by itself: automatic, intent- or cost-based selection was
/// removed in v4 (the gateway decides *what* may leave, not *which* model).
///
/// A target is `"model"` (swap the model, keep the upstream) or
/// `"provider:model"` where `provider` is a `[[proxy.providers]]` registry id
/// or a built-in (`anthropic|openai|gemini`) — then the request is also
/// re-targeted to that provider's upstream.
///
/// **Fail-open by construction:** an unknown alias or unreachable target
/// forwards the request unchanged.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(default)]
pub struct RoutingRules {
    /// Master switch; `false`/absent = passthrough (no body rewrite at all).
    pub enabled: Option<bool>,
    /// Exact model-name aliases: requested model → `"provider:model"` | `"model"`.
    /// BTreeMap for deterministic iteration/serialization (#498).
    pub aliases: std::collections::BTreeMap<String, String>,
    /// Removed intent-tier table. Still parsed so `doctor` can tell an operator
    /// that it no longer routes anything; never read by the proxy.
    #[serde(skip_serializing)]
    pub tiers: std::collections::BTreeMap<String, String>,
}

impl RoutingRules {
    /// True when the router should run at all.
    #[must_use]
    pub fn is_active(&self) -> bool {
        self.enabled.unwrap_or(false) && !self.aliases.is_empty()
    }
}

/// A parsed routing target: optional provider id + model name.
/// `"foundry:gpt-4o-mini"` → provider `foundry`, model `gpt-4o-mini`;
/// `"claude-haiku-4-5"` → model only (upstream unchanged).
#[must_use]
pub fn parse_route_target(target: &str) -> Option<(Option<&str>, &str)> {
    let t = target.trim();
    if t.is_empty() {
        return None;
    }
    match t.split_once(':') {
        Some((provider, model)) => {
            let (provider, model) = (provider.trim(), model.trim());
            if provider.is_empty() || model.is_empty() {
                None
            } else {
                Some((Some(provider), model))
            }
        }
        None => Some((None, t)),
    }
}

/// The API dialect an upstream endpoint speaks — deliberately separate from the
/// provider's *identity*. lean-ctx understands four wire shapes; any number of
/// configured providers (Foundry, OpenRouter, Groq, a local vLLM…) map onto
/// them. New shape = code; new provider = config (universal-provider-framework).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum WireShape {
    /// Anthropic Messages API (`/v1/messages`).
    Anthropic,
    /// OpenAI Chat Completions / Responses API (also spoken by Azure AI
    /// Foundry, OpenRouter, Groq, vLLM, Ollama, LM Studio…).
    OpenAi,
    /// Google Gemini `generateContent` API.
    Gemini,
    /// Amazon Bedrock Runtime `InvokeModel` / event-stream API.
    Bedrock,
}

impl WireShape {
    /// Stable lowercase name (serde representation) for logs and `/status`.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            WireShape::Anthropic => "anthropic",
            WireShape::OpenAi => "openai",
            WireShape::Gemini => "gemini",
            WireShape::Bedrock => "bedrock",
        }
    }
}

/// One `[[proxy.providers]]` registry entry (see [`ProxyConfig::providers`]).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderEntry {
    /// Registry id, used in the `/providers/{id}/...` route and in routing
    /// rules. Lowercase alphanumeric plus `-`/`_`; must not shadow a built-in
    /// provider name (`anthropic`, `openai`, `chatgpt`, `gemini`).
    pub id: String,
    /// Which API dialect the endpoint speaks (`anthropic|openai|gemini|bedrock`).
    pub shape: WireShape,
    /// Endpoint base URL. HTTPS for any non-loopback host; a declared registry
    /// entry is itself the custom-host opt-in (no separate allowlist flag).
    pub base_url: String,
    /// Name of the environment variable holding the upstream API key the
    /// gateway injects (replacing the caller's credential headers). `None` =
    /// forward the caller's own credentials verbatim (default, loopback mode).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub api_key_env: Option<String>,
    /// AWS region for Bedrock SigV4. Bedrock uses standard AWS credential
    /// environment variables and rejects `api_key_env`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub aws_region: Option<String>,
    /// Non-secret opaque account label for destination policy. This is an
    /// operator-configured route label, not a provider-verified account ID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub account_ref: Option<String>,
    /// Declared provider region. Bedrock uses its validated SigV4 `aws_region`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub region: Option<String>,
    /// Set `false` to keep the entry in config but take it out of service.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enabled: Option<bool>,
    /// Marks this endpoint as local inference (Ollama/vLLM/…): usage is booked
    /// at the transparent `local_shadow_rate` instead of provider list prices
    /// (enterprise#15/#18). Unset = derived from the URL (loopback hosts are
    /// local). Set it explicitly when the endpoint is local but not loopback —
    /// the containerized gateway reaching the host's Ollama
    /// (`host.docker.internal`) or an in-cluster server (`ollama.svc.cluster.local`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub local: Option<bool>,
}

/// A validated, ready-to-serve registry provider (runtime view of
/// [`ProviderEntry`], published inside [`Upstreams`]).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedProvider {
    pub id: String,
    pub shape: WireShape,
    pub base_url: String,
    pub api_key_env: Option<String>,
    /// Validated SigV4 region for Bedrock; absent for other shapes.
    pub aws_region: Option<String>,
    /// Non-secret operator label, only usable as an account binding with
    /// gateway-managed authentication and no caller scope override.
    pub account_ref: Option<String>,
    /// Validated destination region; Bedrock's value is its signing region.
    pub region: Option<String>,
    /// Billed as local inference (shadow rate). Explicit `local` flag when the
    /// entry declares one, otherwise loopback-URL derivation.
    pub local: bool,
    /// Where the upstream credential comes from. Never read from TOML:
    /// every `[[proxy.providers]]` entry is [`CredentialSource::Configured`].
    pub credential: CredentialSource,
}

/// The credential a provider sends upstream.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CredentialSource {
    /// The caller's own headers, or the key in `api_key_env`.
    Configured,
    /// The Hive instance's short-lived access token (`hive_i_…`), only for
    /// the built-in `leanctx` provider and only to the Hive models origin
    /// (`core::hive_models`, mz6).
    HiveInstance,
}

/// Built-in provider route names a registry entry must not shadow
/// (`leanctx`: the Hive subscription models, `core::hive_models`).
const BUILTIN_PROVIDER_IDS: &[&str] = &[
    "anthropic",
    "openai",
    "chatgpt",
    "gemini",
    crate::core::hive_models::PROVIDER_ID,
];

/// True when `id` is usable as a registry id: non-empty, lowercase alnum plus
/// `-`/`_` (it becomes a URL path segment), and not a built-in provider name.
fn is_valid_provider_id(id: &str) -> bool {
    !id.is_empty()
        && !BUILTIN_PROVIDER_IDS.contains(&id)
        && id
            .chars()
            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-' || c == '_')
}

fn valid_aws_region(region: &str) -> bool {
    !region.is_empty()
        && region.len() <= 32
        && region
            .bytes()
            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
}

fn valid_bedrock_endpoint(base_url: &str, region: &str) -> bool {
    let Ok(url) = reqwest::Url::parse(base_url) else {
        return false;
    };
    if !matches!(url.path(), "" | "/") || url.query().is_some() || url.fragment().is_some() {
        return false;
    }
    let Some(host) = url.host_str().map(str::to_ascii_lowercase) else {
        return false;
    };
    let loopback = host == "localhost"
        || host
            .parse::<std::net::IpAddr>()
            .is_ok_and(|address| address.is_loopback());
    if loopback {
        return true;
    }
    let accepted = [
        format!("bedrock-runtime.{region}.amazonaws.com"),
        format!("bedrock-runtime.{region}.amazonaws.com.cn"),
        format!("bedrock-runtime.{region}.api.aws"),
        format!("bedrock-runtime-fips.{region}.amazonaws.com"),
        format!("bedrock-runtime-fips.{region}.api.aws"),
    ];
    accepted.iter().any(|candidate| candidate == &host)
        || host.ends_with(&format!(".bedrock-runtime.{region}.vpce.amazonaws.com"))
}

impl ResolvedProvider {
    #[must_use]
    pub fn injects_gateway_credential(&self) -> bool {
        self.api_key_env.is_some() || self.shape == WireShape::Bedrock
    }

    #[must_use]
    pub fn gateway_credential_present(&self) -> bool {
        if self.shape == WireShape::Bedrock {
            return ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
                .into_iter()
                .all(|name| std::env::var(name).is_ok_and(|value| !value.trim().is_empty()));
        }
        self.api_key_env
            .as_deref()
            .is_some_and(|name| std::env::var(name).is_ok_and(|value| !value.trim().is_empty()))
    }
}

/// Per-role prose-compression intensity for the proxy's frozen request region.
///
/// Each value is a `0.0–1.0` aggressiveness level reusing the same mapping as
/// the `ctx_read` knob (#708): `0.0` keeps everything, `1.0` is most aggressive.
/// `None` (the default) means "do not compress this role's prose" so the proxy
/// stays byte-for-byte unchanged until an operator opts in. The `assistant`
/// role is never represented here — model turns are always passed through
/// verbatim (the #710 passthrough guarantee).
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(default)]
pub struct RoleAggressiveness {
    /// Aggressiveness for system prompts (Anthropic `system` / OpenAI `system`
    /// messages / Gemini `systemInstruction`). `None` = leave untouched.
    pub system: Option<f64>,
    /// Aggressiveness for user prose (free-text user turns, never tool results).
    /// `None` = leave untouched.
    pub user: Option<f64>,
}

/// The conversation roles whose prose the proxy may compress in the frozen
/// region. Deliberately excludes `assistant` — model turns are never rewritten.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProseRole {
    System,
    User,
}

/// Unified proxy operation mode that sets cache-optimal defaults for all knobs.
///
/// Instead of configuring 8+ individual booleans, operators pick a single mode
/// that resolves sensible defaults. Explicit per-knob overrides always win.
///
/// - `Cache`: maximise provider prompt-cache hit rate. History is
///   frozen at staircase boundaries, breakpoints are injected, volatile fields
///   are detected, and the live tail is compressed — but the prefix is never
///   rewritten.
/// - `Token` (default for the knob presets): maximise raw token reduction.
///   Cold prefixes may be repacked and volatile fields relocated. History is
///   only rewritten (rolling) when `token` is chosen explicitly; an unset mode
///   keeps cache-aware history pruning (#1895). Best for short one-shot
///   requests where cache reuse is unlikely.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProxyMode {
    Cache,
    Token,
}

impl ProxyMode {
    fn parse(s: &str) -> Option<Self> {
        match s.trim().to_ascii_lowercase().as_str() {
            "cache" | "cache_mode" | "cost_savings" => Some(Self::Cache),
            "token" | "token_mode" | "token_savings" => Some(Self::Token),
            _ => None,
        }
    }

    /// Default value for a cache-related knob under this mode.
    pub fn preset_for(self, knob: &str) -> Option<bool> {
        match (self, knob) {
            (Self::Cache | Self::Token, "cache_aligner" | "cache_policy")
            | (Self::Token, "cache_align_relocate" | "cold_prefix_repack" | "verbosity_steer") => {
                Some(true)
            }

            (Self::Cache | Self::Token, "cache_breakpoint")
            | (Self::Cache, "cache_align_relocate" | "cold_prefix_repack" | "verbosity_steer") => {
                Some(false)
            }

            _ => None,
        }
    }
}

/// How the proxy squeezes prose it must shrink (#895).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProseRanker {
    /// Extractive embedding ranking when the engine is available, else truncate.
    /// The default — strictly better than truncation, and cache-safe via the
    /// per-content memo in `proxy::prose_ranker`.
    Auto,
    /// Same engine path as `Auto` (kept distinct so an operator can express
    /// intent / so a future "require engine" semantic has a name).
    Extractive,
    /// Original deterministic FIFO squeeze; never touches the embedding engine.
    Truncate,
}

/// How the proxy prunes old tool results from conversation history.
///
/// Provider prompt caches (Anthropic `cache_control`, OpenAI automatic prompt
/// caching) bill cached prefix tokens at a fraction of the base rate but only
/// match *exact* prefixes. Any mutation whose position depends on the current
/// conversation length (a rolling window) rewrites a previously-stable message
/// every turn, invalidating the cache from that point — turning cheap cache
/// reads into full-price writes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HistoryMode {
    /// Prune only at frozen generation boundaries that advance in large,
    /// deterministic steps. Between jumps the request prefix is byte-stable,
    /// so provider prompt caches keep hitting. Content the client has marked
    /// with a `cache_control` breakpoint is never rewritten, so an advancing
    /// boundary can no longer invalidate the already-cached prefix (#448).
    /// Default.
    CacheAware,
    /// Legacy behaviour: summarize everything older than the last N messages.
    /// Maximum raw-token reduction, but defeats provider prompt caching.
    Rolling,
    /// Never prune history (tool-result compression still applies — it is
    /// content-deterministic and therefore prefix-stable).
    Off,
}

impl ProxyConfig {
    /// Resolved proxy mode. `LEAN_CTX_PROXY_MODE` env wins, then config, then `Token`.
    #[must_use]
    pub fn resolved_proxy_mode(&self) -> ProxyMode {
        let raw = std::env::var("LEAN_CTX_PROXY_MODE")
            .ok()
            .or_else(|| self.proxy_mode.clone());
        raw.as_deref()
            .and_then(ProxyMode::parse)
            .unwrap_or(ProxyMode::Token)
    }

    /// Whether a Headroom-compatible stack is configured.
    #[must_use]
    pub fn is_headroom_compat(&self) -> bool {
        let raw = std::env::var("LEAN_CTX_PROXY_COMPAT_STACK")
            .ok()
            .or_else(|| self.compat_stack.clone());
        raw.as_deref()
            .is_some_and(|s| s.trim().eq_ignore_ascii_case("headroom"))
    }

    /// Resolved history mode: `LEAN_CTX_PROXY_HISTORY_MODE` env var wins,
    /// then `[proxy].history_mode` in config.toml, then the preset of an
    /// *explicitly chosen* `proxy_mode` (`token` → rolling, `cache` →
    /// cache-aware), then cache-aware.
    /// Unknown values fall back to the default so a typo can never silently
    /// re-enable the cache-hostile rolling mode — and neither can the implicit
    /// `Token` default of [`Self::resolved_proxy_mode`] (#1895).
    pub fn resolved_history_mode(&self) -> HistoryMode {
        let raw = std::env::var("LEAN_CTX_PROXY_HISTORY_MODE")
            .ok()
            .or_else(|| self.history_mode.clone());
        if let Some(mode) = raw.as_deref().map(str::trim) {
            if mode.eq_ignore_ascii_case("rolling") {
                return HistoryMode::Rolling;
            }
            if mode.eq_ignore_ascii_case("off") {
                return HistoryMode::Off;
            }
        }
        let explicit_mode = std::env::var("LEAN_CTX_PROXY_MODE")
            .ok()
            .or_else(|| self.proxy_mode.clone());
        match explicit_mode.as_deref().and_then(ProxyMode::parse) {
            Some(ProxyMode::Token) => HistoryMode::Rolling,
            Some(ProxyMode::Cache) | None => HistoryMode::CacheAware,
        }
    }

    /// Whether the proxy injects `stream_options.include_usage` into streamed
    /// OpenAI Chat Completions to meter real spend. `[proxy] meter_openai_usage`
    /// in config.toml, default `true`.
    pub fn meters_openai_usage(&self) -> bool {
        self.meter_openai_usage.unwrap_or(true)
    }

    /// Operator-configured extra cost header (#1189), normalized to lowercase.
    /// `None` when unset/blank — LiteLLM's standard header is always checked.
    pub fn cost_response_header(&self) -> Option<String> {
        self.cost_response_header
            .as_deref()
            .map(str::trim)
            .filter(|h| !h.is_empty())
            .map(str::to_lowercase)
    }

    /// Resolved prose-ranker strategy (#895). Precedence: the
    /// `LEAN_CTX_PROXY_PROSE_RANKER` env var, then `[proxy] prose_ranker` in
    /// config.toml, then `Auto`. Unknown values resolve to `Auto` so a typo can
    /// never silently disable the premium path; `"truncate"`/`"off"` selects the
    /// legacy squeeze.
    #[must_use]
    pub fn resolved_prose_ranker(&self) -> ProseRanker {
        let raw = std::env::var("LEAN_CTX_PROXY_PROSE_RANKER")
            .ok()
            .or_else(|| self.prose_ranker.clone());
        match raw.as_deref().map(str::trim) {
            Some(s) if s.eq_ignore_ascii_case("truncate") || s.eq_ignore_ascii_case("off") => {
                ProseRanker::Truncate
            }
            Some(s) if s.eq_ignore_ascii_case("extractive") => ProseRanker::Extractive,
            _ => ProseRanker::Auto,
        }
    }

    /// Resolved output-savings holdout fraction (#895 Track B), clamped to
    /// `[0,1]`. Precedence: `LEAN_CTX_PROXY_OUTPUT_HOLDOUT` env > `[proxy]
    /// output_holdout` > `0.0` (no holdout). An unparseable/blank env value is
    /// ignored so a typo can never silently change the experiment fraction.
    #[must_use]
    pub fn output_holdout_fraction(&self) -> f64 {
        let from_env = std::env::var("LEAN_CTX_PROXY_OUTPUT_HOLDOUT")
            .ok()
            .and_then(|v| v.trim().parse::<f64>().ok());
        from_env
            .or(self.output_holdout)
            .unwrap_or(0.0)
            .clamp(0.0, 1.0)
    }

    /// Resolved input-compression holdout fraction (#1905), clamped to `[0,1]`.
    /// Precedence: `LEAN_CTX_PROXY_COMPRESSION_HOLDOUT` env > `[proxy]
    /// compression_holdout` > `0.0` (no holdout). An unparseable/blank env value
    /// is ignored, as for [`ProxyConfig::output_holdout_fraction`].
    #[must_use]
    pub fn compression_holdout_fraction(&self) -> f64 {
        let from_env = std::env::var("LEAN_CTX_PROXY_COMPRESSION_HOLDOUT")
            .ok()
            .and_then(|v| v.trim().parse::<f64>().ok());
        from_env
            .or(self.compression_holdout)
            .unwrap_or(0.0)
            .clamp(0.0, 1.0)
    }

    /// Whether the cache-safe wire verbosity steer (#895) is enabled. Precedence:
    /// `LEAN_CTX_PROXY_VERBOSITY_STEER` env (`1`/`true`/`on`) > `[proxy]
    /// verbosity_steer` > `false` (off).
    #[must_use]
    pub fn verbosity_steer_enabled(&self) -> bool {
        if let Ok(raw) = std::env::var("LEAN_CTX_PROXY_VERBOSITY_STEER") {
            let v = raw.trim();
            return v.eq_ignore_ascii_case("1")
                || v.eq_ignore_ascii_case("true")
                || v.eq_ignore_ascii_case("on")
                || v.eq_ignore_ascii_case("yes");
        }
        if let Some(v) = self.verbosity_steer {
            return v;
        }
        self.resolved_proxy_mode()
            .preset_for("verbosity_steer")
            .unwrap_or(false)
    }

    /// Resolved Codex ChatGPT-subscription proxy opt-in (default off).
    /// `LEAN_CTX_CODEX_CHATGPT_PROXY` (any value) forces it on for the current
    /// process, then `[proxy] codex_chatgpt_proxy` in config.toml, else `false`.
    pub fn codex_chatgpt_proxy_enabled(&self) -> bool {
        std::env::var("LEAN_CTX_CODEX_CHATGPT_PROXY").is_ok()
            || self.codex_chatgpt_proxy.unwrap_or(false)
    }

    /// Whether the opt-in cold-prefix repack (#480) is enabled. A wrong "cold"
    /// guess re-bills cache reads as writes (~12x), so this is off by default and
    /// must be explicitly enabled. `LEAN_CTX_PROXY_COLD_PREFIX_REPACK` (any
    /// value) wins, then `[proxy] cold_prefix_repack` in config.toml, else
    /// `false`.
    pub fn repacks_cold_prefix(&self) -> bool {
        if std::env::var("LEAN_CTX_PROXY_COLD_PREFIX_REPACK").is_ok() {
            return true;
        }
        if let Some(v) = self.cold_prefix_repack {
            return v;
        }
        self.resolved_proxy_mode()
            .preset_for("cold_prefix_repack")
            .unwrap_or(false)
    }

    /// Whether opt-in in-band CCR retrieval (#493) is enabled. Off by default:
    /// the splice mutates provider-visible conversation content for the one turn
    /// the model asks to expand, so it must be an explicit opt-in.
    /// `LEAN_CTX_PROXY_CCR_INBAND` (any value) wins, then `[proxy] ccr_inband` in
    /// config.toml, else `false`.
    pub fn ccr_inband_enabled(&self) -> bool {
        std::env::var("LEAN_CTX_PROXY_CCR_INBAND").is_ok() || self.ccr_inband.unwrap_or(false)
    }

    /// Whether opt-in Anthropic prompt-cache breakpoint injection (#939) is
    /// enabled. Off by default: it mutates the provider-visible `system` shape
    /// (string → cache-marked block array), so it must be an explicit opt-in.
    /// `LEAN_CTX_PROXY_CACHE_BREAKPOINT` (any value) wins, then `[proxy]
    /// cache_breakpoint` in config.toml, else `false`.
    pub fn cache_breakpoint_enabled(&self) -> bool {
        if std::env::var("LEAN_CTX_PROXY_CACHE_BREAKPOINT").is_ok() {
            return true;
        }
        if let Some(v) = self.cache_breakpoint {
            return v;
        }
        if self.is_headroom_compat() {
            return false;
        }
        self.resolved_proxy_mode()
            .preset_for("cache_breakpoint")
            .unwrap_or(false)
    }

    /// Whether the agent-loop cache lifetime (5 min inside the loop, 1 h on the
    /// person's last prompt) is applied to Anthropic requests.
    /// `LEAN_CTX_PROXY_CACHE_TTL_LOOP=on|off` wins, then `[proxy]
    /// cache_ttl_loop` in config.toml, else `true` (measured on Claude Code
    /// `-p`, Haiku 5.5, Context Mode short tasks: -17.9 % cost, 79/80 vs 80/80
    /// solved; only `cache_control` lifetimes change).
    pub fn cache_ttl_loop_enabled(&self) -> bool {
        env_bool_or("LEAN_CTX_PROXY_CACHE_TTL_LOOP", self.cache_ttl_loop, true)
    }

    /// Whether long-session elision applies to Anthropic requests
    /// (every turn of a session past the threshold). `LEAN_CTX_PROXY_LONG_SESSION_ELIDE=on|off` wins,
    /// then `[proxy] long_session_elide` in config.toml, else `false`: on
    /// Claude Code with Haiku 5.5 (three runs, 44 long tasks per arm) it cut
    /// cost to x0.67-0.92 but solved 37/44 vs 42/44 natively, because the
    /// model did not always read back an elided early output.
    pub fn long_session_elide_enabled(&self) -> bool {
        env_bool_or(
            "LEAN_CTX_PROXY_LONG_SESSION_ELIDE",
            self.long_session_elide,
            false,
        )
    }

    /// Whether opt-in counterfactual savings metering (#701) is enabled. Off by
    /// default: it fires one extra (free) Anthropic `count_tokens` call per
    /// rewritten request — pure telemetry, but extra latency budget and
    /// rate-limit surface, so it must be an explicit opt-in.
    /// `LEAN_CTX_PROXY_COUNTERFACTUAL` (any value) wins, then `[proxy]
    /// counterfactual_metering` in config.toml, else `false`.
    pub fn counterfactual_metering_enabled(&self) -> bool {
        std::env::var("LEAN_CTX_PROXY_COUNTERFACTUAL").is_ok()
            || self.counterfactual_metering.unwrap_or(false)
    }

    /// Whether opt-in cache-aligner volatile-field telemetry (#940) is enabled.
    /// On by default (#986 premium defaults): the scan is pure measurement and
    /// never mutates the body, so every proxy ships cache-leak visibility out of
    /// the box. Strictly cache-safe. `LEAN_CTX_PROXY_CACHE_ALIGNER=on|off` wins,
    /// then `[proxy] cache_aligner` in config.toml, else `true`. Opt **out** only
    /// to drop the per-request system-prompt scan.
    pub fn cache_aligner_enabled(&self) -> bool {
        env_bool_or("LEAN_CTX_PROXY_CACHE_ALIGNER", self.cache_aligner, true)
    }

    /// Whether opt-in active cache-aligner relocate (#974) is enabled. Off by
    /// default: it reshapes the provider-visible `system` field (moving volatile
    /// values to an uncached tail block), so it must be an explicit opt-in.
    /// `LEAN_CTX_PROXY_CACHE_ALIGN_RELOCATE` (any value) wins, then `[proxy]
    /// cache_align_relocate` in config.toml, else `false`.
    pub fn cache_align_relocate_enabled(&self) -> bool {
        if std::env::var("LEAN_CTX_PROXY_CACHE_ALIGN_RELOCATE").is_ok() {
            return true;
        }
        if let Some(v) = self.cache_align_relocate {
            return v;
        }
        if self.is_headroom_compat() {
            return false;
        }
        self.resolved_proxy_mode()
            .preset_for("cache_align_relocate")
            .unwrap_or(false)
    }

    /// Whether cache-economics (#986) is enabled: prompt-cache miss attribution
    /// telemetry plus the net-cost repack gate. Both are strictly safe
    /// (measurement + a more-conservative repack that never busts a cache the
    /// default kept), so this is **on by default** — every proxy gets the
    /// diagnosis and the safer repack out of the box.
    /// `LEAN_CTX_PROXY_CACHE_POLICY=on|off` wins, then `[proxy] cache_policy` in
    /// config.toml, else `true`. Opt out to keep `/status` free of the attribution
    /// gauges and skip the per-request prefix hash.
    pub fn cache_policy_enabled(&self) -> bool {
        env_bool_or("LEAN_CTX_PROXY_CACHE_POLICY", self.cache_policy, true)
    }

    /// Resolved cross-provider reasoning effort (#834), or `None` when the
    /// feature is off (the default — a strict no-op that preserves the
    /// byte-unchanged meter-only path). Precedence: `LEAN_CTX_PROXY_EFFORT` env
    /// (`off` disables, a valid level wins, an unparseable/blank value is
    /// ignored) > `[proxy] effort` in config.toml. Any unknown value resolves to
    /// `None` so a typo can never silently enable reasoning steering.
    #[must_use]
    pub fn resolved_effort(&self) -> Option<super::Effort> {
        if let Ok(raw) = std::env::var("LEAN_CTX_PROXY_EFFORT") {
            let trimmed = raw.trim();
            if trimmed.eq_ignore_ascii_case("off") {
                return None;
            }
            if let Some(effort) = super::Effort::parse(trimmed) {
                return Some(effort);
            }
            // Blank/unknown env → ignore and fall through to config, mirroring
            // `live_compresses` so a typo never flips the configured behaviour.
        }
        self.effort.as_deref().and_then(super::Effort::parse)
    }

    /// The proxy's project root as written, unverified: env
    /// `LEAN_CTX_PROXY_PROJECT_ROOT` wins over `[proxy] project_root`; blank = unset.
    pub fn configured_project_root(&self) -> Option<String> {
        let set = |root: &String| !root.trim().is_empty();
        let env = std::env::var("LEAN_CTX_PROXY_PROJECT_ROOT")
            .ok()
            .filter(set);
        env.or_else(|| self.project_root.clone()).filter(set)
    }

    /// Whether the proxy live-compresses non-protected `tool_result` content
    /// (#481). `LEAN_CTX_PROXY_LIVE_COMPRESS` (`0`/`false`/`off`/`no` → off,
    /// `1`/`true`/`on`/`yes` → on) wins, then `[proxy] live_compress` in
    /// config.toml, else `true`. An unparseable/blank env value is ignored so a
    /// typo can never silently flip the mode.
    pub fn live_compresses(&self) -> bool {
        if let Ok(raw) = std::env::var("LEAN_CTX_PROXY_LIVE_COMPRESS") {
            match raw.trim().to_ascii_lowercase().as_str() {
                "0" | "false" | "off" | "no" => return false,
                "1" | "true" | "on" | "yes" => return true,
                _ => {}
            }
        }
        if let Some(v) = self.live_compress {
            return v;
        }
        if self.is_headroom_compat() {
            return false;
        }
        match self.resolved_proxy_mode() {
            ProxyMode::Cache | ProxyMode::Token => true,
        }
    }

    /// Resolved per-tool live-compress exclusion patterns (#481). `None` in
    /// config falls back to the built-in default (protect Serena); an explicit
    /// list — including the empty list — is used verbatim so operators can narrow
    /// or fully clear it.
    #[must_use]
    pub fn live_compress_exclude_patterns(&self) -> Vec<String> {
        self.live_compress_exclude
            .clone()
            .unwrap_or_else(default_live_compress_exclude)
    }

    /// Whether `tool_name` is on the live-compress exclusion list (#481) and must
    /// therefore reach the model intact, like a protected file read. Matching is
    /// case-insensitive substring, mirroring `tool_kind::classify_tool_name`.
    #[must_use]
    pub fn is_tool_live_compress_excluded(&self, tool_name: &str) -> bool {
        let name = tool_name.to_ascii_lowercase();
        self.live_compress_exclude_patterns().iter().any(|p| {
            let p = p.trim().to_ascii_lowercase();
            !p.is_empty() && name.contains(p.as_str())
        })
    }

    /// Compiled `compress_protect` globs (#1150), skipping any that fail to parse
    /// so one malformed entry never disables the rest. Empty when unset — the
    /// default — which makes [`Self::is_path_compress_protected`] a fast no-op.
    #[must_use]
    pub fn compress_protect_globs(&self) -> Vec<glob::Pattern> {
        self.compress_protect
            .as_deref()
            .unwrap_or_default()
            .iter()
            .filter_map(|p| glob::Pattern::new(p.trim()).ok())
            .collect()
    }

    /// Whether `path` is on the never-compress list (#1150) and must be returned
    /// verbatim. Each glob is tried against both the full path (with backslashes
    /// normalised to `/`) and the bare file name, so `*.snap` matches anywhere
    /// while `**/golden/**` can still target a directory. Empty list → always
    /// `false` (today's behaviour), so a default proxy pays nothing.
    #[must_use]
    pub fn is_path_compress_protected(&self, path: &str) -> bool {
        let patterns = self.compress_protect_globs();
        if patterns.is_empty() {
            return false;
        }
        let norm = path.replace('\\', "/");
        let base = norm.rsplit('/').next().unwrap_or(norm.as_str());
        patterns.iter().any(|p| p.matches(&norm) || p.matches(base))
    }

    /// Resolved prose-compression aggressiveness for `role`, clamped to `[0,1]`,
    /// or `None` when prose compression is off for that role (the default).
    ///
    /// Precedence: the role's env override (`LEAN_CTX_PROXY_SYSTEM_AGGR` /
    /// `LEAN_CTX_PROXY_USER_AGGR`) wins, then `[proxy.role_aggressiveness]` in
    /// config.toml. An unparseable or blank env value is ignored so a typo can
    /// never silently disable the configured behaviour.
    #[must_use]
    pub fn resolved_role_aggressiveness(&self, role: ProseRole) -> Option<f64> {
        let (env_var, configured) = match role {
            ProseRole::System => (
                "LEAN_CTX_PROXY_SYSTEM_AGGR",
                self.role_aggressiveness.system,
            ),
            ProseRole::User => ("LEAN_CTX_PROXY_USER_AGGR", self.role_aggressiveness.user),
        };
        let from_env = std::env::var(env_var)
            .ok()
            .and_then(|v| v.trim().parse::<f64>().ok());
        let resolved = from_env.or(configured);
        if resolved.is_some() {
            return resolved.map(|a| a.clamp(0.0, 1.0));
        }
        if self.resolved_proxy_mode() == ProxyMode::Token && role == ProseRole::System {
            return Some(0.5);
        }
        None
    }

    /// Whether a non-loopback plaintext `http://` upstream is allowed. Opt-in
    /// only — a deliberate downgrade for a trusted local-network service such as
    /// `http://host.docker.internal:2455` in front of codex-lb (#440).
    /// `LEAN_CTX_ALLOW_INSECURE_HTTP_UPSTREAM` (any value) wins, then
    /// `[proxy] allow_insecure_http_upstream` in config.toml, default `false`.
    pub fn allows_insecure_http_upstream(&self) -> bool {
        std::env::var("LEAN_CTX_ALLOW_INSECURE_HTTP_UPSTREAM").is_ok()
            || self.allow_insecure_http_upstream.unwrap_or(false)
    }

    /// Whether a custom (non-allowlisted) HTTPS upstream host is allowed. Opt-in
    /// only — lifting the built-in host allowlist points the proxy at a host you
    /// control (e.g. a corporate gateway), so it must be deliberate.
    /// `LEAN_CTX_ALLOW_CUSTOM_UPSTREAM` (any value) wins, then
    /// `[proxy] allow_custom_upstream` in config.toml, default `false`.
    ///
    /// Unlike the env var, the **config flag reaches the managed (service-spawned)
    /// proxy**, which only reads `config.toml` — that is the whole point of #590:
    /// `proxy enable`/`restart` start the proxy via launchd/systemd, which never
    /// inherits the shell's `LEAN_CTX_ALLOW_CUSTOM_UPSTREAM`.
    pub fn allows_custom_upstream(&self) -> bool {
        std::env::var("LEAN_CTX_ALLOW_CUSTOM_UPSTREAM").is_ok()
            || self.allow_custom_upstream.unwrap_or(false)
    }

    /// `[proxy] allow_vendor_direct_cn` (default `false`). The org policy can
    /// still void it (`routing.vendor_direct_cn = false`).
    #[must_use]
    pub fn allows_vendor_direct_cn(&self) -> bool {
        self.allow_vendor_direct_cn.unwrap_or(false)
    }

    /// True when any `*_upstream` configured in `config.toml` (env-independent) is a
    /// custom HTTPS host outside the built-in allowlist — i.e. one that resolves
    /// only with the [`Self::allows_custom_upstream`] opt-in. Plaintext-HTTP custom
    /// hosts are governed by `allow_insecure_http_upstream` instead, so they are
    /// excluded here. Lets `proxy enable`/`restart` persist the opt-in (so the
    /// managed proxy honors it) and `proxy status` explain a blocked upstream,
    /// without touching the allowlisted-host case (#590).
    #[must_use]
    pub fn has_custom_host_upstream(&self) -> bool {
        [
            self.anthropic_upstream.as_deref(),
            self.openai_upstream.as_deref(),
            self.chatgpt_upstream.as_deref(),
            self.gemini_upstream.as_deref(),
        ]
        .into_iter()
        .flatten()
        .filter_map(normalize_url_opt)
        .any(|u| is_custom_upstream_host(&u))
    }

    /// `(env var, configured value, provider default)` for one provider.
    fn provider_spec(&self, provider: ProxyProvider) -> (&'static str, Option<&str>, &'static str) {
        match provider {
            ProxyProvider::Anthropic => (
                "LEAN_CTX_ANTHROPIC_UPSTREAM",
                self.anthropic_upstream.as_deref(),
                "https://api.anthropic.com",
            ),
            ProxyProvider::OpenAi => (
                "LEAN_CTX_OPENAI_UPSTREAM",
                self.openai_upstream.as_deref(),
                "https://api.openai.com",
            ),
            ProxyProvider::ChatGpt => (
                "LEAN_CTX_CHATGPT_UPSTREAM",
                self.chatgpt_upstream.as_deref(),
                "https://chatgpt.com",
            ),
            ProxyProvider::Gemini => (
                "LEAN_CTX_GEMINI_UPSTREAM",
                self.gemini_upstream.as_deref(),
                "https://generativelanguage.googleapis.com",
            ),
        }
    }

    /// Resolve one upstream with precedence `LEAN_CTX_*_UPSTREAM` env var >
    /// `[proxy].*_upstream` (config.toml) > provider default.
    ///
    /// Returns `Err` when a value is *present but invalid* so a live reload can
    /// keep the last good value instead of silently rerouting to the default; an
    /// *absent* value resolves to the provider default (`Ok`).
    fn resolve_upstream_checked(&self, provider: ProxyProvider) -> Result<String, String> {
        self.resolve_upstream_inner(provider, true)
    }

    /// Shared resolver for [`resolve_upstream_checked`] and the disk-only view.
    /// `use_env = false` ignores the `LEAN_CTX_*_UPSTREAM` override and yields
    /// the config.toml truth a freshly (re)started managed proxy would serve.
    fn resolve_upstream_inner(
        &self,
        provider: ProxyProvider,
        use_env: bool,
    ) -> Result<String, String> {
        let (env_var, config_val, default) = self.provider_spec(provider);
        let env_val = if use_env {
            std::env::var(env_var)
                .ok()
                .and_then(|v| normalize_url_opt(&v))
        } else {
            None
        };
        let candidate = env_val.or_else(|| config_val.and_then(normalize_url_opt));
        match candidate {
            None => Ok(normalize_url(default)),
            Some(url) => validate_upstream_url(
                &url,
                self.allows_insecure_http_upstream(),
                self.allows_custom_upstream(),
            ),
        }
    }

    /// Effective upstream for a provider (env > config > default). An invalid
    /// configured/env value falls back to the provider default (logged) — the
    /// safe choice at startup.
    pub fn resolve_upstream(&self, provider: ProxyProvider) -> String {
        match self.resolve_upstream_checked(provider) {
            Ok(url) => url,
            Err(e) => {
                tracing::warn!("upstream validation failed, using default: {e}");
                normalize_url(self.provider_spec(provider).2)
            }
        }
    }

    /// Resolve all three upstreams at once (startup snapshot, env-aware).
    pub fn resolve_all(&self) -> Upstreams {
        Upstreams {
            anthropic: self.resolve_upstream(ProxyProvider::Anthropic),
            openai: self.resolve_upstream(ProxyProvider::OpenAi),
            chatgpt: self.resolve_upstream(ProxyProvider::ChatGpt),
            gemini: self.resolve_upstream(ProxyProvider::Gemini),
            providers: self.resolve_providers(),
        }
    }

    /// Validate + resolve the `[[proxy.providers]]` registry. Invalid entries
    /// are logged and skipped (one typo must never take the proxy down or
    /// disable the remaining registry); duplicates keep the first occurrence.
    /// A declared registry entry is itself the deliberate custom-host opt-in,
    /// so any HTTPS host is accepted; plaintext HTTP still requires loopback or
    /// the explicit insecure-HTTP opt-in (same rule as the built-ins).
    #[must_use]
    pub fn resolve_providers(&self) -> Vec<ResolvedProvider> {
        let mut seen: std::collections::BTreeSet<&str> = std::collections::BTreeSet::new();
        let mut out = Vec::new();
        for entry in &self.providers {
            if !entry.enabled.unwrap_or(true) {
                continue;
            }
            let id = entry.id.trim();
            if !is_valid_provider_id(id) {
                tracing::warn!(
                    "[proxy.providers] invalid id '{id}' (lowercase alnum/-/_ only, \
                     must not shadow a built-in provider) — entry skipped"
                );
                continue;
            }
            if !seen.insert(id) {
                tracing::warn!("[proxy.providers] duplicate id '{id}' — keeping first entry");
                continue;
            }
            match validate_upstream_url(&entry.base_url, self.allows_insecure_http_upstream(), true)
            {
                Ok(base_url) => {
                    let account_ref = entry
                        .account_ref
                        .as_deref()
                        .map(str::trim)
                        .filter(|value| !value.is_empty());
                    // Check raw controls before normalization can remove them.
                    if entry
                        .account_ref
                        .as_deref()
                        .is_some_and(|value| value.chars().any(char::is_control))
                        || account_ref
                            .is_some_and(|value| ProtocolReference::new(value.to_owned()).is_err())
                    {
                        tracing::warn!(
                            "[proxy.providers] provider '{id}' has invalid account_ref — skipped"
                        );
                        continue;
                    }
                    let configured_region = entry
                        .region
                        .as_deref()
                        .map(str::trim)
                        .filter(|value| !value.is_empty());
                    if entry
                        .region
                        .as_deref()
                        .is_some_and(|value| value.chars().any(char::is_control))
                        || configured_region
                            .is_some_and(|value| ProtocolReference::new(value.to_owned()).is_err())
                    {
                        tracing::warn!(
                            "[proxy.providers] provider '{id}' has invalid region — skipped"
                        );
                        continue;
                    }
                    let aws_region = entry
                        .aws_region
                        .as_deref()
                        .map(str::trim)
                        .filter(|value| !value.is_empty());
                    if entry.shape == WireShape::Bedrock {
                        let Some(region) = aws_region.filter(|value| valid_aws_region(value))
                        else {
                            tracing::warn!(
                                "[proxy.providers] Bedrock provider '{id}' requires valid aws_region — skipped"
                            );
                            continue;
                        };
                        if entry.api_key_env.is_some() || !valid_bedrock_endpoint(&base_url, region)
                        {
                            tracing::warn!(
                                "[proxy.providers] Bedrock provider '{id}' has invalid credential mode or endpoint — skipped"
                            );
                            continue;
                        }
                        if configured_region.is_some_and(|configured| configured != region) {
                            tracing::warn!(
                                "[proxy.providers] Bedrock provider '{id}' region must match aws_region — skipped"
                            );
                            continue;
                        }
                    } else if aws_region.is_some() {
                        tracing::warn!(
                            "[proxy.providers] non-Bedrock provider '{id}' cannot set aws_region — skipped"
                        );
                        continue;
                    }
                    // Explicit `local` flag wins; otherwise loopback URLs are
                    // local (host.docker.internal etc. need the explicit flag).
                    let local = entry.local.unwrap_or_else(|| is_local_proxy_url(&base_url));
                    out.push(ResolvedProvider {
                        id: id.to_string(),
                        shape: entry.shape,
                        base_url,
                        api_key_env: entry
                            .api_key_env
                            .as_deref()
                            .map(str::trim)
                            .filter(|v| !v.is_empty())
                            .map(str::to_string),
                        aws_region: aws_region.map(str::to_string),
                        account_ref: account_ref.map(str::to_string),
                        region: if entry.shape == WireShape::Bedrock {
                            aws_region.map(str::to_string)
                        } else {
                            configured_region.map(str::to_string)
                        },
                        local,
                        credential: CredentialSource::Configured,
                    });
                }
                Err(e) => {
                    tracing::warn!("[proxy.providers] '{id}' has invalid base_url — skipped: {e}");
                }
            }
        }
        out
    }

    /// Resolve all upstreams from config.toml only (ignoring `LEAN_CTX_*` env) —
    /// the values a freshly (re)started managed proxy would serve. Used by
    /// status/doctor to detect drift from a running proxy's live upstream (#449).
    pub fn resolve_all_disk(&self) -> Upstreams {
        let pick = |provider: ProxyProvider| {
            self.resolve_upstream_inner(provider, false)
                .unwrap_or_else(|_| normalize_url(self.provider_spec(provider).2))
        };
        Upstreams {
            anthropic: pick(ProxyProvider::Anthropic),
            openai: pick(ProxyProvider::OpenAi),
            chatgpt: pick(ProxyProvider::ChatGpt),
            gemini: pick(ProxyProvider::Gemini),
            providers: self.resolve_providers(),
        }
    }

    /// Re-resolve upstreams for a *running* proxy (#449). For any provider whose
    /// currently configured/env value fails validation, the last good value is
    /// kept instead of rerouting live traffic to the provider default — so a typo
    /// in config.toml can never silently redirect in-flight requests.
    pub fn refresh_upstreams(&self, last: &Upstreams) -> Upstreams {
        let keep = |provider: ProxyProvider, prev: &str| {
            self.resolve_upstream_checked(provider).unwrap_or_else(|e| {
                tracing::warn!("upstream invalid, keeping {prev}: {e}");
                prev.to_string()
            })
        };
        Upstreams {
            anthropic: keep(ProxyProvider::Anthropic, &last.anthropic),
            openai: keep(ProxyProvider::OpenAi, &last.openai),
            chatgpt: keep(ProxyProvider::ChatGpt, &last.chatgpt),
            gemini: keep(ProxyProvider::Gemini, &last.gemini),
            // Registry re-resolution is deterministic from config; an entry
            // that turned invalid is dropped with a warning (see
            // `resolve_providers`), the rest keep serving.
            providers: self.resolve_providers(),
        }
    }
}

/// Resolve a tri-state boolean toggle for the default-**on** proxy features: an
/// explicit `on`/`off`-style environment variable wins, then the config
/// `Option<bool>`, else `default`. Lets an operator force a feature on **or** off
/// from the shell; an unparseable value is ignored so a typo can never silently
/// flip it (mirrors [`ProxyConfig::live_compresses`]).
fn env_bool_or(env_key: &str, configured: Option<bool>, default: bool) -> bool {
    if let Ok(raw) = std::env::var(env_key) {
        match raw.trim().to_ascii_lowercase().as_str() {
            "1" | "true" | "yes" | "on" => return true,
            "0" | "false" | "no" | "off" => return false,
            _ => {}
        }
    }
    configured.unwrap_or(default)
}

/// Built-in default live-compress exclusion (#481). Serena's code-reading tools
/// (`find_symbol`/`find_referencing_symbols`/`search_for_pattern`) return source
/// bodies the model edits, yet are mis-bucketed as `Search` by name, so the proxy
/// would otherwise gut them. Protect anything namespaced `serena` by default.
fn default_live_compress_exclude() -> Vec<String> {
    vec!["serena".to_string()]
}

#[cfg(test)]
#[path = "proxy_tests.rs"]
mod tests;