Module context_overhead 

Honest accounting of the fixed per-turn context lean-ctx injects (GitHub #361).

Three components ride every request and — on a provider WITHOUT prompt caching — are re-billed on every turn:

• the exposed MCP tool schemas (description + input schema of each tool),
• the MCP server instructions block, and
• the rules block lean-ctx writes into the host’s instruction file (CLAUDE.md / AGENTS.md).

lean-ctx gain measures compression on lean-ctx-touched reads — its denominator is lean-ctx traffic, not the provider bill. On a phase-isolated / non-caching workload (separate process per phase, no provider cache) the cached-re-read lever has no surface, so the headline can read net-positive while the bill moved net-negative. Surfacing this overhead — and stating the denominator — keeps the meter honest.

Net bill impact ≈ gross_saved_tokens − total_tokens() × turns.

Structs

ContextOverhead

A measured breakdown, in tokens, of the per-turn context lean-ctx adds.

Functions

net_of_injection

Net-of-injection reconciliation with baseline + cache corrections (#1104).

observed_turns

Provider turns (requests) the proxy actually observed carrying the injected prefix. The proxy is the only component that sees every provider turn, so its persisted request count is the honest multiplier for the per-turn injection tax. 0 when the proxy is not in the request path — we never guess turns we did not see, so net_of_injection then collapses to the gross savings.

proactive_injected_tokens

Total proactive context tokens appended by this process.

record_proactive_injection

Record tokens appended as proactive context so savings reports can account for the dynamic response-side injection separately from fixed overhead.

set_no_cache_adjust

tool_tokens

Description + input-schema tokens for one tool definition — exactly the two fields a client re-sends in every request’s tool list.