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 history_mode: Option<String>,
    pub allow_insecure_http_upstream: Option<bool>,
    pub meter_openai_usage: Option<bool>,
    pub cold_prefix_repack: Option<bool>,
    pub role_aggressiveness: RoleAggressiveness,
    pub live_compress: Option<bool>,
    pub live_compress_exclude: Option<Vec<String>>,
    pub ccr_inband: Option<bool>,
    pub effort: Option<String>,
    pub prose_ranker: Option<String>,
    pub output_holdout: Option<f64>,
    pub verbosity_steer: Option<bool>,
}

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>

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)

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.

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.

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.

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.

Implementations

impl ProxyConfig

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