Struct ProxyConfig 

pub struct ProxyConfig {

    pub anthropic_upstream: Option<String>,
    pub openai_upstream: Option<String>,
    pub chatgpt_upstream: Option<String>,
    pub gemini_upstream: Option<String>,
    pub providers: Vec<ProviderEntry>,
    pub history_mode: Option<String>,
    pub allow_insecure_http_upstream: Option<bool>,
    pub allow_custom_upstream: Option<bool>,
    pub meter_openai_usage: Option<bool>,
    pub cost_response_header: Option<String>,
    pub cold_prefix_repack: Option<bool>,
    pub role_aggressiveness: RoleAggressiveness,
    pub live_compress: Option<bool>,
    pub live_compress_exclude: Option<Vec<String>>,
    pub compress_protect: Option<Vec<String>>,
    pub ccr_inband: Option<bool>,
    pub cache_breakpoint: Option<bool>,
    pub counterfactual_metering: Option<bool>,
    pub cache_aligner: Option<bool>,
    pub cache_align_relocate: Option<bool>,
    pub cache_policy: Option<bool>,
    pub effort: Option<String>,
    pub prose_ranker: Option<String>,
    pub output_holdout: Option<f64>,
    pub verbosity_steer: Option<bool>,
    pub proxy_mode: Option<String>,
    pub compat_stack: Option<String>,
    pub codex_chatgpt_proxy: Option<bool>,
    pub routing: RoutingRules,
    pub baseline: BaselineConfig,
}

API proxy upstream overrides. None = use provider default.

Fields

anthropic_upstream: Option<String>

openai_upstream: Option<String>

chatgpt_upstream: Option<String>

gemini_upstream: Option<String>

providers: Vec<ProviderEntry>

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).

history_mode: Option<String>

History-pruning strategy for proxied chat requests. “cache-aware” (default) | “rolling” | “off”. See HistoryMode.

allow_insecure_http_upstream: Option<bool>

Allow a non-loopback plaintext http:// upstream (trusted local network only). Opt-in; see ProxyConfig::allows_insecure_http_upstream. (#440)

allow_custom_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).

meter_openai_usage: Option<bool>

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.

cost_response_header: Option<String>

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).

cold_prefix_repack: Option<bool>

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.

role_aggressiveness: RoleAggressiveness

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.

live_compress: Option<bool>

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" and no role_aggressiveness for a fully byte-unchanged body). Env LEAN_CTX_PROXY_LIVE_COMPRESS. See ProxyConfig::live_compresses.

live_compress_exclude: Option<Vec<String>>

Per-tool exclusion list for live tool-result compression (#481). Tool names are matched case-insensitively as substrings (the same style as crate::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.

compress_protect: 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.

ccr_inband: Option<bool>

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.

cache_breakpoint: 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.

counterfactual_metering: 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.

cache_aligner: 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.

cache_align_relocate: 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.

cache_policy: 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 (crate::proxy::cache_attribution); and (2) a net-cost gate on the cold-prefix repack (crate::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.

effort: Option<String>

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.

prose_ranker: 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.

output_holdout: Option<f64>

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.

verbosity_steer: Option<bool>

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.

proxy_mode: Option<String>

Unified proxy operation mode ([proxy] proxy_mode). "cache" (default) or "token". Sets sensible defaults for all cache-related knobs; explicit per-knob overrides always win. Env LEAN_CTX_PROXY_MODE.

compat_stack: 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.

codex_chatgpt_proxy: Option<bool>

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.

routing: RoutingRules

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.

baseline: BaselineConfig

Counterfactual-baseline parameters ([proxy.baseline], enterprise#15/#18) for the avoided-cost evidence chain. See BaselineConfig.

Implementations

impl ProxyConfig

pub fn resolved_proxy_mode(&self) -> ProxyMode

Resolved proxy mode. LEAN_CTX_PROXY_MODE env wins, then config, then Cache.

pub fn is_headroom_compat(&self) -> bool

Whether a Headroom-compatible stack is configured.

pub fn resolved_history_mode(&self) -> HistoryMode

Resolved history mode: LEAN_CTX_PROXY_HISTORY_MODE env var wins, then [proxy].history_mode in config.toml, then cache-aware. Unknown values fall back to the default so a typo can never silently re-enable the cache-hostile rolling mode.

pub fn meters_openai_usage(&self) -> bool

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 cost_response_header(&self) -> Option<String>

Operator-configured extra cost header (#1189), normalized to lowercase. None when unset/blank — LiteLLM’s standard header is always checked.

pub fn resolved_prose_ranker(&self) -> ProseRanker

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.

pub fn output_holdout_fraction(&self) -> f64

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.

pub fn verbosity_steer_enabled(&self) -> bool

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).

pub fn codex_chatgpt_proxy_enabled(&self) -> bool

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 repacks_cold_prefix(&self) -> bool

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 ccr_inband_enabled(&self) -> bool

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 cache_breakpoint_enabled(&self) -> bool

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 counterfactual_metering_enabled(&self) -> bool

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 cache_aligner_enabled(&self) -> bool

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_align_relocate_enabled(&self) -> bool

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_policy_enabled(&self) -> bool

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 resolved_effort(&self) -> Option<Effort>

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.

pub fn live_compresses(&self) -> bool

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_compress_exclude_patterns(&self) -> Vec<String>

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.

pub fn is_tool_live_compress_excluded(&self, tool_name: &str) -> bool

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.

pub fn compress_protect_globs(&self) -> Vec<Pattern>

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.

pub fn is_path_compress_protected(&self, path: &str) -> bool

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.

pub fn resolved_role_aggressiveness(&self, role: ProseRole) -> Option<f64>

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.

pub fn allows_insecure_http_upstream(&self) -> bool

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_custom_upstream(&self) -> bool

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 has_custom_host_upstream(&self) -> bool

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).

pub fn resolve_upstream(&self, provider: ProxyProvider) -> String

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_all(&self) -> Upstreams

Resolve all three upstreams at once (startup snapshot, env-aware).

pub fn resolve_providers(&self) -> Vec<ResolvedProvider>

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).

pub fn resolve_all_disk(&self) -> Upstreams

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 refresh_upstreams(&self, last: &Upstreams) -> Upstreams

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.

Trait Implementations

impl Clone for ProxyConfig

fn clone(&self) -> ProxyConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ProxyConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ProxyConfig

fn default() -> ProxyConfig

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ProxyConfig

where ProxyConfig: Default,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ProxyConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.