Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat: add lean-ctx context tool support
Gili Tzabari4b061792b29f
diff --git a/README.md b/README.mdindex 8ce942b85..a00bafb23 100644--- a/README.md+++ b/README.md@@ -83,7 +83,7 @@ OPENAI_BASE_URL=http://localhost:8787/v1 your-app- **Cross-agent memory and learning.** Claude Code saves a fact, Codex reads it back. `headroom learn` mines failed sessions and writes corrections straight to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` — reliability compounds over time.- **Reversible (CCR).** Compression is not deletion. The model can always call `headroom_retrieve` to pull the original bytes. Nothing is thrown away.-Bundles the [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — full [attribution below](#compared-to).+Bundles managed [RTK](https://github.com/rtk-ai/rtk) and [lean-ctx](https://github.com/yvgude/lean-ctx) binaries for local CLI context filtering — full [attribution below](#compared-to).---@@ -264,10 +264,11 @@ Headroom runs **locally**, covers **every** content type (not just CLI or text),|----------------------------------|-------------------------------------------------|-------------------------------------|:-----:|:----------:|| **Headroom** | All context — tools, RAG, logs, files, history | Proxy · library · middleware · MCP | Yes | Yes || [RTK](https://github.com/rtk-ai/rtk) | CLI command outputs | CLI wrapper | Yes | No |+| [lean-ctx](https://github.com/yvgude/lean-ctx) | CLI commands, MCP tools, editor rules | CLI wrapper · MCP | Yes | No || [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call | No | No || OpenAI Compaction | Conversation history | Provider-native | No | No |-> **Attribution.** Headroom ships with the excellent [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — `git show` → `git show --short`, noisy `ls` → scoped, chatty installers → summarized. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it.+> **Attribution.** Headroom ships with the excellent [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — `git show` → `git show --short`, noisy `ls` → scoped, chatty installers → summarized. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it. Headroom can also use [lean-ctx](https://github.com/yvgude/lean-ctx) as the selected CLI context tool; set `HEADROOM_CONTEXT_TOOL=lean-ctx` before running `headroom wrap ...`.---diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdxindex 2ee202482..8027c283c 100644--- a/docs/content/docs/configuration.mdx+++ b/docs/content/docs/configuration.mdx@@ -5,6 +5,20 @@ description: All configuration options for the Headroom Python and TypeScript SDHeadroom can be configured via the SDK constructor, proxy command line, environment variables, or per-request overrides.+## CLI Context Tool++`headroom wrap ...` uses RTK for local shell-output filtering by default.+Set `HEADROOM_CONTEXT_TOOL=lean-ctx` to have wrap commands install or reuse+`lean-ctx` and run `lean-ctx init --agent <tool>` instead of RTK setup.++```bash+export HEADROOM_CONTEXT_TOOL=lean-ctx+headroom wrap claude+headroom wrap codex --prepare-only+```++Supported values are `rtk` and `lean-ctx`; unset defaults to `rtk`.+## Modes| Mode | Behavior | Use Case |diff --git a/docs/content/docs/docker-install.mdx b/docs/content/docs/docker-install.mdxindex f61ca7761..b6f351263 100644--- a/docs/content/docs/docker-install.mdx+++ b/docs/content/docs/docker-install.mdx@@ -75,7 +75,7 @@ docker run --rm -it \`wrap` is host-oriented in Docker-native mode:- the wrapper starts the Headroom proxy in Docker-- container-side prep writes Headroom config, memory, and `rtk` guidance into mounted host files+- container-side prep writes Headroom config, memory, and selected CLI context-tool setup into mounted host files- the target CLI itself is launched on the host by the wrapperSupported host wrap flows:diff --git a/docs/content/docs/filesystem-contract.mdx b/docs/content/docs/filesystem-contract.mdxindex 64e90e11e..6aeda5451 100644--- a/docs/content/docs/filesystem-contract.mdx+++ b/docs/content/docs/filesystem-contract.mdx@@ -55,6 +55,7 @@ Examples:| Proxy log directory | `${WORKSPACE_DIR}/logs/` | — || HTTP 400 debug dumps | `${WORKSPACE_DIR}/logs/debug_400/` | — || Vendored `rtk` binary | `${WORKSPACE_DIR}/bin/rtk[.exe]` | — |+| Vendored `lean-ctx` binary | `${WORKSPACE_DIR}/bin/lean-ctx[.exe]` | — || Deployment profiles | `${WORKSPACE_DIR}/deploy/` | — || Beacon lock file | `${WORKSPACE_DIR}/.beacon_lock_<port>` | — |diff --git a/docs/spec/015-interfaces.md b/docs/spec/015-interfaces.mdindex 73b6a619c..20b7069ee 100644--- a/docs/spec/015-interfaces.md+++ b/docs/spec/015-interfaces.md@@ -100,7 +100,7 @@ headroom wrap [OPTIONS] -- <command> [args...]| Flag | Default | Description ||------|---------|-------------|| `--port` | `8787` | Proxy port |-| `--no-rtk` | `false` | Skip RTK hooks |+| `--no-context-tool` / `--no-rtk` | `false` | Skip CLI context-tool setup |**Supported Commands:**- `claude` — Wrap Claude Codediff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex afc473a58..8220aa048 100644--- a/headroom/cli/proxy.py+++ b/headroom/cli/proxy.py@@ -12,6 +12,11 @@ from headroom.proxy.modes import PROXY_MODE_TOKEN, normalize_proxy_modefrom .main import main+_CONTEXT_TOOL_ENV = "HEADROOM_CONTEXT_TOOL"+_CONTEXT_TOOL_RTK = "rtk"+_CONTEXT_TOOL_LEAN_CTX = "lean-ctx"+_VALID_CONTEXT_TOOLS = {_CONTEXT_TOOL_RTK, _CONTEXT_TOOL_LEAN_CTX}+def _get_env_bool(name: str, default: bool) -> bool:val = os.environ.get(name)@@ -20,6 +25,19 @@ def _get_env_bool(name: str, default: bool) -> bool:return val.lower() in ("true", "1", "yes", "on")+def _selected_context_tool() -> str:+ raw = os.environ.get(_CONTEXT_TOOL_ENV, "").strip().lower().replace("_", "-")+ if not raw:+ return _CONTEXT_TOOL_RTK+ if raw == "leanctx":+ raw = _CONTEXT_TOOL_LEAN_CTX+ if raw not in _VALID_CONTEXT_TOOLS:+ raise click.ClickException(+ f"{_CONTEXT_TOOL_ENV} must be one of: {', '.join(sorted(_VALID_CONTEXT_TOOLS))}"+ )+ return raw++@main.command()@click.option("--host",@@ -735,6 +753,7 @@ Memory (Multi-Provider):from headroom.proxy.server import _get_code_aware_banner_statuscode_aware_line = f" Code-Aware: {_get_code_aware_banner_status(config)}"+ context_tool_line = f" Context Tool: {_selected_context_tool()}"click.echo(f"""╔═══════════════════════════════════════════════════════════════════════╗@@ -752,6 +771,7 @@ Starting proxy server...Memory: {memory_status}License: {license_status}{code_aware_line}+{context_tool_line}{extensions_line}{stateless_line}{telemetry_line}{backend_section}diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 4be5c2976..9639ded25 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -1,13 +1,13 @@"""Wrap CLI commands to run through Headroom proxy.Usage:- headroom wrap claude # Start proxy + rtk + claude+ headroom wrap claude # Start proxy + context tool + claudeheadroom wrap copilot -- --model ... # Start proxy + launch GitHub Copilot CLIheadroom wrap codex # Start proxy + OpenAI Codex CLIheadroom wrap aider # Start proxy + aiderheadroom wrap cursor # Start proxy + print Cursor config instructionsheadroom wrap openclaw # Install + configure OpenClaw plugin- headroom wrap claude --no-rtk # Without rtk hooks+ headroom wrap claude --no-context-tool # Without CLI context-tool setupheadroom wrap claude --port 9999 # Custom proxy portheadroom wrap claude -- --model opus # Pass args to claude"""@@ -22,6 +22,7 @@ import signalimport socketimport subprocessimport sys+import tempfileimport timefrom pathlib import Pathfrom typing import Any, cast@@ -77,12 +78,37 @@ from headroom.providers.openclaw import (from .main import main+_CONTEXT_TOOL_ENV = "HEADROOM_CONTEXT_TOOL"+_CONTEXT_TOOL_RTK = "rtk"+_CONTEXT_TOOL_LEAN_CTX = "lean-ctx"+_VALID_CONTEXT_TOOLS = {_CONTEXT_TOOL_RTK, _CONTEXT_TOOL_LEAN_CTX}+def _live_wrap_module() -> Any:"""Return the current live wrap module instance."""return cast(Any, sys.modules[__name__])+def _selected_context_tool() -> str:+ """Return the configured CLI context tool.++ RTK remains the default for backward compatibility. Set+ ``HEADROOM_CONTEXT_TOOL=lean-ctx`` to let lean-ctx configure the supported+ coding agent instead.+ """++ raw = os.environ.get(_CONTEXT_TOOL_ENV, "").strip().lower().replace("_", "-")+ if not raw:+ return _CONTEXT_TOOL_RTK+ if raw == "leanctx":+ raw = _CONTEXT_TOOL_LEAN_CTX+ if raw not in _VALID_CONTEXT_TOOLS:+ raise click.ClickException(+ f"{_CONTEXT_TOOL_ENV} must be one of: {', '.join(sorted(_VALID_CONTEXT_TOOLS))}"+ )+ return raw++def _print_telemetry_notice() -> None:"""Print a telemetry notice when anonymous telemetry is enabled.@@ -244,6 +270,53 @@ def _setup_rtk(verbose: bool = False) -> Path | None:return rtk_path+def _setup_lean_ctx_agent(agent: str, verbose: bool = False) -> Path | None:+ """Run lean-ctx agent setup for the requested coding tool."""++ from headroom.lean_ctx import get_lean_ctx_path+ from headroom.lean_ctx.installer import ensure_lean_ctx++ lean_ctx = get_lean_ctx_path()+ if not lean_ctx:+ click.echo(" Downloading lean-ctx...")+ lean_ctx = ensure_lean_ctx()+ if not lean_ctx:+ click.echo(" lean-ctx download failed — continuing without it")+ return None++ try:+ with tempfile.TemporaryDirectory(prefix="headroom-lean-ctx-") as setup_cwd:+ # lean-ctx writes project-local files when initialized from a git+ # checkout. Run from a non-project directory so setup is limited to+ # home-scoped agent config such as ~/.codex or ~/.claude.+ result = subprocess.run(+ [str(lean_ctx), "init", "--agent", agent],+ capture_output=True,+ text=True,+ encoding="utf-8",+ errors="replace",+ timeout=30,+ cwd=setup_cwd,+ )+ except Exception as e:+ click.echo(f" lean-ctx setup failed — continuing without it: {e}")+ return None++ if result.returncode != 0:+ detail = (result.stderr or result.stdout).strip()+ suffix = f": {detail}" if detail else ""+ click.echo(f" lean-ctx setup failed — continuing without it{suffix}")+ return None++ if verbose:+ detail = result.stdout.strip()+ if detail:+ click.echo(f" lean-ctx configured for {agent}: {detail}")+ else:+ click.echo(f" lean-ctx configured for {agent}")+ return lean_ctx++def _remove_claude_rtk_hooks(settings_path: Path | None = None) -> bool:"""Remove Headroom/rtk-managed Claude hook entries from settings.json.@@ -1710,7 +1783,13 @@ def unwrap() -> None:@wrap.command(context_settings={"ignore_unknown_options": True})@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-rtk", is_flag=True, help="Skip rtk installation and hook registration")+ "--no-context-tool",+ "--no-rtk",+ "no_rtk",+ is_flag=True,+ help="Skip CLI context-tool setup",+)@click.option("--no-mcp",is_flag=True,@@ -1756,13 +1835,16 @@ def claude(headroom wrap claude --resume <id> # Resume a sessionheadroom wrap claude -- -p # Claude in print modeheadroom wrap claude --code-graph # With code graph intelligence- headroom wrap claude --no-rtk # Skip rtk (proxy only)+ headroom wrap claude --no-context-tool # Skip CLI context-tool setupheadroom wrap claude --no-mcp # Skip MCP retrieve tool registrationheadroom wrap claude --no-serena # Skip Serena MCP registration"""if prepare_only:if not no_rtk:- _prepare_wrap_rtk(verbose=verbose, label="Claude")+ if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:+ _setup_lean_ctx_agent("claude", verbose=verbose)+ else:+ _prepare_wrap_rtk(verbose=verbose, label="Claude")returnclaude_bin = shutil.which("claude")@@ -1831,10 +1913,14 @@ def claude()if not no_rtk:- click.echo(" Setting up rtk...")- _setup_rtk(verbose=verbose)+ if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:+ click.echo(" Setting up lean-ctx...")+ _setup_lean_ctx_agent("claude", verbose=verbose)+ else:+ click.echo(" Setting up rtk...")+ _setup_rtk(verbose=verbose)elif verbose:- click.echo(" Skipping rtk (--no-rtk)")+ click.echo(" Skipping CLI context tool (--no-context-tool)")if not no_mcp:from headroom.mcp_registry import ClaudeRegistrar@@ -1945,9 +2031,11 @@ def unwrap_claude(@wrap.command(context_settings={"ignore_unknown_options": True})@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")@click.option(+ "--no-context-tool","--no-rtk",+ "no_rtk",is_flag=True,- help="Skip rtk installation and Copilot instructions injection",+ help="Skip CLI context-tool setup",)@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")@click.option(@@ -2005,7 +2093,7 @@ def copilot(headroom wrap copilot -- --model claude-sonnet-4-20250514headroom wrap copilot --backend anyllm --anyllm-provider groq -- --model gpt-4oheadroom wrap copilot --provider-type openai --wire-api responses -- --model gpt-5.4- headroom wrap copilot --no-rtk -- --prompt "explain this file"+ headroom wrap copilot --no-context-tool -- --prompt "explain this file""""copilot_bin = shutil.which("copilot")if not copilot_bin:@@ -2034,11 +2122,15 @@ def copilot()if not no_rtk:- click.echo(" Setting up rtk for Copilot...")- rtk_path = _ensure_rtk_binary(verbose=verbose)- if rtk_path:- copilot_instructions = Path.cwd() / ".github" / "copilot-instructions.md"- _inject_rtk_instructions(copilot_instructions, verbose=verbose)+ if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:+ click.echo(" Setting up lean-ctx for Copilot...")+ _setup_lean_ctx_agent("copilot", verbose=verbose)+ else:+ click.echo(" Setting up rtk for Copilot...")+ rtk_path = _ensure_rtk_binary(verbose=verbose)+ if rtk_path:+ copilot_instructions = Path.cwd() / ".github" / "copilot-instructions.md"+ _inject_rtk_instructions(copilot_instructions, verbose=verbose)env = os.environ.copy()openai_api_url: str | None = None@@ -2118,7 +2210,13 @@ def copilot(@wrap.command(context_settings={"ignore_unknown_options": True})@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-rtk", is_flag=True, help="Skip rtk installation and AGENTS.md injection")+ "--no-context-tool",+ "--no-rtk",+ "no_rtk",+ is_flag=True,+ help="Skip CLI context-tool setup",+)@click.option("--no-mcp",is_flag=True,@@ -2171,16 +2269,16 @@ def codex(\bSets OPENAI_BASE_URL to route all OpenAI API calls through Headroom.- Installs rtk and injects instructions into AGENTS.md so Codex uses- token-optimized commands (60-90% savings on shell output). Also+ Sets up the selected CLI context tool so Codex uses token-optimized+ commands (60-90% savings on shell output). Alsoregisters the headroom MCP server in ~/.codex/config.toml so Codexcan call ``headroom_retrieve`` on compression markers.\bExamples:- headroom wrap codex # Start proxy + rtk + mcp + codex+ headroom wrap codex # Start proxy + context tool + mcp + codexheadroom wrap codex -- "fix the bug" # Pass prompt to codex- headroom wrap codex --no-rtk # Skip rtk setup+ headroom wrap codex --no-context-tool # Skip CLI context-tool setupheadroom wrap codex --no-mcp # Skip MCP retrieve tool registrationheadroom wrap codex --no-serena # Skip Serena MCP registrationheadroom wrap codex --port 9999 # Custom proxy port@@ -2195,18 +2293,22 @@ def codex(_codex_config_file, _codex_backup_file = _codex_config_paths()_snapshot_codex_config_if_unwrapped(_codex_config_file, _codex_backup_file)- # Setup rtk for Codex (binary + AGENTS.md instructions, no hooks)+ # Setup CLI context tool for Codex.if not no_rtk:- click.echo(" Setting up rtk for Codex...")- rtk_path = _ensure_rtk_binary(verbose=verbose)- if rtk_path:- # Inject into project AGENTS.md (Codex reads this automatically)- agents_md = Path.cwd() / "AGENTS.md"- _inject_rtk_instructions(agents_md, verbose=verbose)+ if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:+ click.echo(" Setting up lean-ctx for Codex...")+ _setup_lean_ctx_agent("codex", verbose=verbose)+ else:+ click.echo(" Setting up rtk for Codex...")+ rtk_path = _ensure_rtk_binary(verbose=verbose)+ if rtk_path:+ # Inject into project AGENTS.md (Codex reads this automatically)+ agents_md = Path.cwd() / "AGENTS.md"+ _inject_rtk_instructions(agents_md, verbose=verbose)- # Also inject into global ~/.codex/AGENTS.md- global_agents = Path.home() / ".codex" / "AGENTS.md"- _inject_rtk_instructions(global_agents, verbose=verbose)+ # Also inject into global ~/.codex/AGENTS.md+ global_agents = Path.home() / ".codex" / "AGENTS.md"+ _inject_rtk_instructions(global_agents, verbose=verbose)# Register headroom MCP server in ~/.codex/config.toml so Codex can# call headroom_retrieve on compression markers from the proxy.@@ -2320,7 +2422,13 @@ def codex(@wrap.command(context_settings={"ignore_unknown_options": True})@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-rtk", is_flag=True, help="Skip rtk installation and conventions injection")+ "--no-context-tool",+ "--no-rtk",+ "no_rtk",+ is_flag=True,+ help="Skip CLI context-tool setup",+)@click.option("--code-graph",is_flag=True,@@ -2355,25 +2463,28 @@ def aider(\bSets OPENAI_API_BASE to route all API calls through Headroom.- Installs rtk and injects instructions into .aider.conf.yml conventions- so aider uses token-optimized commands.+ Sets up the selected CLI context tool so aider uses token-optimized commands.\bExamples:- headroom wrap aider # Start proxy + rtk + aider+ headroom wrap aider # Start proxy + context tool + aiderheadroom wrap aider -- --model gpt-4o # Use GPT-4oheadroom wrap aider -- --model claude-sonnet-4 # Use Claude- headroom wrap aider --no-rtk # Skip rtk setup+ headroom wrap aider --no-context-tool # Skip CLI context-tool setupheadroom wrap aider --backend litellm-vertex --region us-central1"""- # Setup rtk for aider (binary + CONVENTIONS.md instructions)+ # Setup CLI context tool for aider.if not no_rtk:- click.echo(" Setting up rtk for aider...")- rtk_path = _ensure_rtk_binary(verbose=verbose)- if rtk_path:- # aider reads CONVENTIONS.md from project root- conventions = Path.cwd() / "CONVENTIONS.md"- _inject_rtk_instructions(conventions, verbose=verbose)+ if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:+ click.echo(" Setting up lean-ctx for aider...")+ _setup_lean_ctx_agent("aider", verbose=verbose)+ else:+ click.echo(" Setting up rtk for aider...")+ rtk_path = _ensure_rtk_binary(verbose=verbose)+ if rtk_path:+ # aider reads CONVENTIONS.md from project root+ conventions = Path.cwd() / "CONVENTIONS.md"+ _inject_rtk_instructions(conventions, verbose=verbose)if prepare_only:return@@ -2411,7 +2522,13 @@ def aider(@wrap.command(context_settings={"ignore_unknown_options": True})@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-rtk", is_flag=True, help="Skip rtk installation and .cursorrules injection")+ "--no-context-tool",+ "--no-rtk",+ "no_rtk",+ is_flag=True,+ help="Skip CLI context-tool setup",+)@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")@click.option("--learn", is_flag=True, help="Enable live traffic learning (patterns saved to .cursor/rules/)"@@ -2432,8 +2549,8 @@ def cursor(\bCursor reads its API configuration from its settings UI, not from- environment variables. This command starts the proxy, installs rtk- with .cursorrules instructions, and prints the Cursor settings.+ environment variables. This command starts the proxy, sets up the selected+ CLI context tool, and prints the Cursor settings.\bAfter running this command, open Cursor and configure:@@ -2441,16 +2558,20 @@ def cursor(\bExample:- headroom wrap cursor # Start proxy + rtk + instructions- headroom wrap cursor --no-rtk # Proxy only, no rtk+ headroom wrap cursor # Start proxy + context-tool instructions+ headroom wrap cursor --no-context-tool # Proxy only, no CLI context toolheadroom wrap cursor --port 9999 # Custom proxy port"""if not no_rtk:- click.echo(" Setting up rtk for Cursor...")- rtk_path = _ensure_rtk_binary(verbose=verbose)- if rtk_path:- cursorrules = Path.cwd() / ".cursorrules"- _inject_rtk_instructions(cursorrules, verbose=verbose)+ if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:+ click.echo(" Setting up lean-ctx for Cursor...")+ _setup_lean_ctx_agent("cursor", verbose=verbose)+ else:+ click.echo(" Setting up rtk for Cursor...")+ rtk_path = _ensure_rtk_binary(verbose=verbose)+ if rtk_path:+ cursorrules = Path.cwd() / ".cursorrules"+ _inject_rtk_instructions(cursorrules, verbose=verbose)if prepare_only:return@@ -2476,7 +2597,10 @@ def cursor(click.echo(line)if not no_rtk:click.echo()- click.echo(" rtk instructions injected into .cursorrules")+ if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:+ click.echo(" lean-ctx configured for Cursor")+ else:+ click.echo(" rtk instructions injected into .cursorrules")click.echo(" Cursor will use token-optimized commands automatically.")click.echo()click.echo(" Press Ctrl+C to stop the proxy.")diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.htmlindex 7d44b366a..8d017b1cb 100644--- a/headroom/dashboard/templates/dashboard.html+++ b/headroom/dashboard/templates/dashboard.html@@ -109,7 +109,7 @@</div><div class="mt-2 text-xs text-gray-500"><span x-show="stats.cost?.savings_usd > 0"- x-text="formatNumber(stats.tokens?.proxy_compression_saved || 0) + ' proxy tokens only; RTK excluded from $'"></span>+ x-text="formatNumber(stats.tokens?.proxy_compression_saved || 0) + ' proxy tokens only; ' + cliFilteringLabel + ' excluded from $'"></span><span x-show="!(stats.cost?.savings_usd > 0)"x-text="formatNumber(stats.requests?.total || 0) + ' requests processed'"></span></div>@@ -125,7 +125,7 @@<div class="mt-1 text-xs text-gray-500 leading-relaxed"><span x-text="'Proxy ' + formatNumber(stats.tokens?.proxy_compression_saved || 0) + ' (' + proxyShareOfTotal.toFixed(1) + '%)'"></span><span class="mx-1 text-gray-600">/</span>- <span x-text="'RTK ' + formatNumber(stats.tokens?.rtk_saved || 0) + ' (' + rtkShareOfTotal.toFixed(1) + '%)'"></span>+ <span x-text="cliFilteringLabel + ' ' + formatNumber(cliFilteringSaved) + ' (' + cliFilteringShareOfTotal.toFixed(1) + '%)'"></span></div><div class="mt-2 h-8"><svg class="w-full h-full" viewBox="0 0 100 32" preserveAspectRatio="none">@@ -698,8 +698,8 @@<span class="font-mono text-sm" x-text="formatNumber(stats.tokens?.total_before_compression || 0)"></span></div><div class="flex justify-between items-center">- <span class="text-sm text-gray-400">RTK Filtered</span>- <span class="font-mono text-sm text-emerald-400" x-text="formatNumber(stats.tokens?.rtk_saved || 0)"></span>+ <span class="text-sm text-gray-400" x-text="cliFilteringLabel + ' Filtered'"></span>+ <span class="font-mono text-sm text-emerald-400" x-text="formatNumber(cliFilteringSaved)"></span></div><div class="flex justify-between items-center"><span class="text-sm text-gray-400">Proxy Removed</span>@@ -1778,10 +1778,26 @@return (this.stats.tokens?.proxy_compression_saved || 0) / total * 100;},- get rtkShareOfTotal() {+ get cliFilteringLabel() {+ const raw = this.stats.savings?.by_layer?.cli_filtering?.label+ || this.stats.context_tool?.label+ || this.stats.context_tool?.configured+ || 'Context Tool';+ if (String(raw).toLowerCase() === 'lean-ctx') return 'Lean-ctx';+ return String(raw);+ },++ get cliFilteringSaved() {+ return this.stats.tokens?.cli_filtering_saved+ ?? this.stats.tokens?.cli_tokens_avoided+ ?? this.stats.tokens?.rtk_saved+ ?? 0;+ },++ get cliFilteringShareOfTotal() {const total = this.compressionTotalBefore;if (total <= 0) return 0;- return (this.stats.tokens?.rtk_saved || 0) / total * 100;+ return this.cliFilteringSaved / total * 100;},// --- Compression Confidence ---diff --git a/headroom/lean_ctx/__init__.py b/headroom/lean_ctx/__init__.pynew file mode 100644index 000000000..fcad548c3--- /dev/null+++ b/headroom/lean_ctx/__init__.py@@ -0,0 +1,46 @@+"""lean-ctx integration for Headroom.++lean-ctx configures supported coding agents to route tool output through its+context-filtering layer. Headroom downloads and manages the lean-ctx binary.+"""++from __future__ import annotations++import platform+import shutil+from pathlib import Path++from headroom import paths as _paths++LEAN_CTX_VERSION = "v3.4.7"+LEAN_CTX_BIN_DIR = _paths.bin_dir()+_LEAN_CTX_NAME = "lean-ctx.exe" if platform.system() == "Windows" else "lean-ctx"+LEAN_CTX_BIN_PATH = _paths.lean_ctx_path()+++def _managed_lean_ctx_candidates() -> list[Path]:+ """Return known Headroom-managed lean-ctx binary paths."""+ candidates = [LEAN_CTX_BIN_DIR / _LEAN_CTX_NAME]+ for name in ("lean-ctx", "lean-ctx.exe"):+ path = LEAN_CTX_BIN_DIR / name+ if path not in candidates:+ candidates.append(path)+ return candidates+++def get_lean_ctx_path() -> Path | None:+ """Get path to lean-ctx binary — check PATH first, then ~/.headroom/bin/."""+ system_lean_ctx = shutil.which("lean-ctx")+ if system_lean_ctx:+ return Path(system_lean_ctx)++ for candidate in _managed_lean_ctx_candidates():+ if candidate.exists() and candidate.is_file():+ return candidate++ return None+++def is_lean_ctx_installed() -> bool:+ """Check if lean-ctx is available."""+ return get_lean_ctx_path() is not Nonediff --git a/headroom/lean_ctx/installer.py b/headroom/lean_ctx/installer.pynew file mode 100644index 000000000..045e9f828--- /dev/null+++ b/headroom/lean_ctx/installer.py@@ -0,0 +1,179 @@+"""Download and install lean-ctx binary from GitHub releases."""++from __future__ import annotations++import io+import logging+import os+import platform+import stat+import subprocess+import tarfile+import zipfile+from pathlib import Path+from urllib.request import urlopen++from . import LEAN_CTX_BIN_DIR, LEAN_CTX_VERSION++logger = logging.getLogger(__name__)++GITHUB_RELEASE_URL = "https://github.com/yvgude/lean-ctx/releases/download"+++def _detect_runtime_target_triple() -> str:+ """Detect platform and return the lean-ctx release target triple."""+ system = platform.system()+ machine = platform.machine()++ if system == "Darwin":+ arch = "aarch64" if machine == "arm64" else "x86_64"+ return f"{arch}-apple-darwin"+ if system == "Linux":+ arch = "aarch64" if machine == "aarch64" else "x86_64"+ suffix = "unknown-linux-musl" if _is_musl() else "unknown-linux-gnu"+ return f"{arch}-{suffix}"+ if system == "Windows":+ return "x86_64-pc-windows-msvc"++ raise RuntimeError(f"Unsupported platform: {system} {machine}")+++def _is_musl() -> bool:+ try:+ result = subprocess.run(+ ["ldd", "--version"],+ capture_output=True,+ text=True,+ timeout=2,+ check=False,+ )+ return "musl" in (result.stdout + result.stderr).lower()+ except Exception:+ return False+++def _get_target_triple() -> str:+ """Return the requested lean-ctx target triple, honoring explicit overrides."""+ return _get_explicit_target_triple() or _detect_runtime_target_triple()+++def _get_explicit_target_triple() -> str:+ """Return the explicitly requested lean-ctx target triple, if any."""+ return (+ os.environ.get("HEADROOM_LEAN_CTX_TARGET", "").strip()+ or os.environ.get("LEAN_CTX_TARGET", "").strip()+ )+++def _binary_name_for_target(target: str) -> str:+ """Return the expected binary name for a target triple."""+ return "lean-ctx.exe" if "windows" in target else "lean-ctx"+++def _should_verify_target(target: str) -> bool:+ """Verify runtime-detected targets; explicit overrides may be cross-target."""+ if _get_explicit_target_triple():+ return False+ return target == _detect_runtime_target_triple()+++def _get_download_url(version: str) -> tuple[str, str]:+ """Get download URL and extension for this platform."""+ target = _get_target_triple()+ ext = "zip" if "windows" in target else "tar.gz"+ url = f"{GITHUB_RELEASE_URL}/{version}/lean-ctx-{target}.{ext}"+ return url, ext+++def download_lean_ctx(version: str | None = None) -> Path:+ """Download lean-ctx binary from GitHub releases."""+ version = version or LEAN_CTX_VERSION+ target = _get_target_triple()+ url, ext = _get_download_url(version)+ target_path = LEAN_CTX_BIN_DIR / _binary_name_for_target(target)++ LEAN_CTX_BIN_DIR.mkdir(parents=True, exist_ok=True)++ logger.info("Downloading lean-ctx %s from %s ...", version, url)++ try:+ if not url.startswith(("http://", "https://")):+ raise ValueError(f"Invalid URL scheme in {url}")+ try:+ with urlopen(url, timeout=30) as response:+ data = response.read()+ except Exception as download_err:+ if "CERTIFICATE_VERIFY_FAILED" in str(download_err):+ raise RuntimeError(+ "TLS verification failed downloading lean-ctx; "+ "fix the local trust store and retry."+ ) from download_err+ raise+ except Exception as e:+ raise RuntimeError(f"Failed to download lean-ctx from {url}: {e}") from e++ try:+ if ext == "tar.gz":+ with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:+ for member in tar.getmembers():+ if member.name.endswith("/lean-ctx") or member.name == "lean-ctx":+ member.name = target_path.name+ tar.extract(member, LEAN_CTX_BIN_DIR)+ break+ else:+ raise RuntimeError("lean-ctx binary not found in archive")+ elif ext == "zip":+ with zipfile.ZipFile(io.BytesIO(data)) as zf:+ for name in zf.namelist():+ if name.endswith("lean-ctx.exe") or name.endswith("/lean-ctx"):+ with zf.open(name) as src, open(target_path, "wb") as dst:+ dst.write(src.read())+ break+ else:+ raise RuntimeError("lean-ctx binary not found in archive")+ except (tarfile.TarError, zipfile.BadZipFile) as e:+ raise RuntimeError(f"Failed to extract lean-ctx archive: {e}") from e++ if "windows" not in target:+ target_path.chmod(target_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)++ if _should_verify_target(target):+ try:+ result = subprocess.run(+ [str(target_path), "--version"],+ capture_output=True,+ text=True,+ encoding="utf-8",+ errors="replace",+ timeout=5,+ )+ if result.returncode != 0:+ raise RuntimeError(f"lean-ctx verification failed: {result.stderr}")+ logger.info("lean-ctx installed: %s", result.stdout.strip())+ except FileNotFoundError as e:+ raise RuntimeError("lean-ctx binary not found after extraction") from e+ except subprocess.TimeoutExpired as e:+ raise RuntimeError("lean-ctx verification timed out") from e+ else:+ logger.info(+ "lean-ctx installed for target %s at %s (verification skipped)",+ target,+ target_path,+ )++ return target_path+++def ensure_lean_ctx(version: str | None = None) -> Path | None:+ """Ensure lean-ctx is installed — download if needed."""+ from . import get_lean_ctx_path++ existing = get_lean_ctx_path()+ if existing:+ return existing++ try:+ return download_lean_ctx(version)+ except RuntimeError as e:+ logger.warning("Could not install lean-ctx: %s", e)+ return Nonediff --git a/headroom/paths.py b/headroom/paths.pyindex dd24ab261..eb1633f8d 100644--- a/headroom/paths.py+++ b/headroom/paths.py@@ -75,6 +75,8 @@ _CODEX_WIRE_DEBUG_DIR = "codex_wire"_BIN_DIR = "bin"_RTK_UNIX = "rtk"_RTK_WIN = "rtk.exe"+_LEAN_CTX_UNIX = "lean-ctx"+_LEAN_CTX_WIN = "lean-ctx.exe"_DEPLOY_DIR = "deploy"_PLUGINS_DIR = "plugins"@@ -274,6 +276,13 @@ def rtk_path() -> Path:return bin_dir() / name+def lean_ctx_path() -> Path:+ """Return the path to the vendored ``lean-ctx`` binary."""++ name = _LEAN_CTX_WIN if os.name == "nt" else _LEAN_CTX_UNIX+ return bin_dir() / name++def deploy_root() -> Path:"""Return the root directory for persistent deployment profiles."""@@ -349,6 +358,7 @@ __all__ = ["codex_wire_debug_dir","bin_dir","rtk_path",+ "lean_ctx_path","deploy_root","beacon_lock_path","models_config_path",diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.pyindex 0eed221ef..8cc51378a 100644--- a/headroom/proxy/cost.py+++ b/headroom/proxy/cost.py@@ -300,12 +300,14 @@ def merge_cost_stats(Each savings layer is reported separately with its own scope:- savings_usd: compression savings at model list price (monotonic)- cache_savings_usd: prefix cache discount from provider (separate)- - cli_tokens_avoided: tokens filtered by rtk (token count only, no $ estimate)+ - cli_tokens_avoided: tokens filtered by the selected CLI context tool+ (token count only, no $ estimate)The dollar metric (savings_usd) remains ONLY proxy compression savings- priced at the model's published input rate. RTK is folded into the- dashboard's compression token total, but it has no reliable model-specific- dollar estimate because those tokens never reached the proxy request.+ priced at the model's published input rate. CLI filtering is folded into+ the dashboard's compression token total, but it has no reliable+ model-specific dollar estimate because those tokens never reached the+ proxy request.Prefix cache savings stay separate because they are a provider discount,not token removal. This avoids the non-monotonic moving-average repricingbug (#83).@@ -322,7 +324,9 @@ def merge_cost_stats("compression_savings_usd": round(compression_savings, 4),"cache_savings_usd": round(cache_net, 4),"cli_tokens_avoided": cli_tokens_avoided,+ "cli_filtering_tokens_avoided": cli_tokens_avoided,"cli_tokens_included_in_compression": True,+ "cli_filtering_tokens_included_in_compression": True,}@@ -388,8 +392,8 @@ def build_session_summary(best_detail = f"{best['original']:,} → {best['optimized']:,} tokens"# Cost summary — dollar savings are proxy-compression only at model list- # price. rtk tokens are counted in token savings but have no model-specific- # price because they never reached the proxy request.+ # price. CLI filtering tokens are counted in token savings but have no+ # model-specific price because they never reached the proxy request.cost_stats = proxy.cost_tracker.stats() if proxy.cost_tracker else {}cost_with = cost_stats.get("cost_with_headroom_usd", 0.0)compression_savings = cost_stats.get("savings_usd", 0.0)@@ -414,6 +418,11 @@ def build_session_summary("best_compression_pct": best_compression,"best_detail": best_detail,"total_tokens_removed": metrics.tokens_saved_total,+ "cli_filtering_tokens_avoided": cli_tokens_avoided,+ "total_tokens_saved_with_cli_filtering": (+ metrics.tokens_saved_total + cli_tokens_avoided+ ),+ "total_tokens_before_with_cli_filtering": total_tokens_before,"rtk_tokens_avoided": cli_tokens_avoided,"total_tokens_saved_with_rtk": metrics.tokens_saved_total + cli_tokens_avoided,"total_tokens_before_with_rtk": total_tokens_before,@@ -427,9 +436,14 @@ def build_session_summary("breakdown": {"cache_savings_usd": round(cache_net, 2),"compression_savings_usd": round(compression_savings, 2),+ "cli_filtering_savings_usd": None,+ "cli_filtering_savings_note": (+ "CLI filtering tokens are included in token savings only; "+ "dollar savings use proxy compression tokens at model list price."+ ),"rtk_savings_usd": None,"rtk_savings_note": (- "rtk tokens are included in token savings only; dollar savings "+ "CLI filtering tokens are included in token savings only; dollar savings ""use proxy compression tokens at model list price."),},diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex f346459a2..80c96c5aa 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -13,6 +13,7 @@ import jsonimport loggingimport osimport random+import subprocessimport threadingimport timefrom collections import OrderedDict@@ -566,18 +567,28 @@ def append_text_to_latest_user_input_item(return body_input, 0+_CONTEXT_TOOL_ENV = "HEADROOM_CONTEXT_TOOL"+_CONTEXT_TOOL_RTK = "rtk"+_CONTEXT_TOOL_LEAN_CTX = "lean-ctx"+RTK_STATS_CACHE_TTL_SECONDS = 5.0-_rtk_stats_cache_lock = threading.Lock()-_rtk_stats_cache: dict[str, Any] = {+CONTEXT_TOOL_STATS_CACHE_TTL_SECONDS = RTK_STATS_CACHE_TTL_SECONDS+_context_tool_stats_cache_lock = threading.Lock()+_context_tool_stats_cache: dict[str, Any] = {"expires_at": 0.0,"has_value": False,+ "tool": None,"value": None,}-_rtk_session_baseline: dict[str, Any] = {+_context_tool_session_baseline: dict[str, Any] = {"initialized": False,+ "tool": None,"total_commands": 0,"tokens_saved": 0,}+_rtk_stats_cache_lock = _context_tool_stats_cache_lock+_rtk_stats_cache = _context_tool_stats_cache+_rtk_session_baseline = _context_tool_session_baseline# Maximum request body size (100MB - increased to support image-heavy requests)MAX_REQUEST_BODY_SIZE = 100 * 1024 * 1024@@ -803,19 +814,59 @@ def _setup_file_logging() -> None:pass+def _selected_context_tool() -> str:+ raw = os.environ.get(_CONTEXT_TOOL_ENV, _CONTEXT_TOOL_RTK).strip().lower()+ normalized = raw.replace("_", "-")+ if normalized in ("leanctx", _CONTEXT_TOOL_LEAN_CTX):+ return _CONTEXT_TOOL_LEAN_CTX+ return _CONTEXT_TOOL_RTK+++def _context_tool_label(tool: str) -> str:+ if tool == _CONTEXT_TOOL_LEAN_CTX:+ return "lean-ctx"+ return "RTK"+++def _coerce_int(value: Any, default: int = 0) -> int:+ try:+ return int(value or 0)+ except (TypeError, ValueError):+ return default+++def _coerce_float(value: Any, default: float = 0.0) -> float:+ try:+ return float(value or 0.0)+ except (TypeError, ValueError):+ return default+++def _first_value(mapping: dict[str, Any], keys: tuple[str, ...], default: Any = 0) -> Any:+ for key in keys:+ if key in mapping and mapping[key] is not None:+ return mapping[key]+ return default++def _read_rtk_lifetime_stats() -> dict[str, Any] | None:"""Read rtk's current project-level lifetime stats."""- import subprocess as _sp-from headroom.rtk import get_rtk_pathrtk_path = get_rtk_path()if not rtk_path:- return None+ return {+ "tool": _CONTEXT_TOOL_RTK,+ "label": _context_tool_label(_CONTEXT_TOOL_RTK),+ "installed": False,+ "total_commands": 0,+ "tokens_saved": 0,+ "avg_savings_pct": 0.0,+ }try:- result = _sp.run(+ result = subprocess.run([str(rtk_path), "gain", "--project", "--format", "json"],capture_output=True,text=True,@@ -825,13 +876,17 @@ def _read_rtk_lifetime_stats() -> dict[str, Any] | None:data = json.loads(result.stdout)summary = data.get("summary", {})payload = {+ "tool": _CONTEXT_TOOL_RTK,+ "label": _context_tool_label(_CONTEXT_TOOL_RTK),"installed": True,- "total_commands": summary.get("total_commands", 0),- "tokens_saved": summary.get("total_saved", 0),- "avg_savings_pct": summary.get("avg_savings_pct", 0.0),+ "total_commands": _coerce_int(summary.get("total_commands", 0)),+ "tokens_saved": _coerce_int(summary.get("total_saved", 0)),+ "avg_savings_pct": _coerce_float(summary.get("avg_savings_pct", 0.0)),}else:return {+ "tool": _CONTEXT_TOOL_RTK,+ "label": _context_tool_label(_CONTEXT_TOOL_RTK),"installed": True,"total_commands": 0,"tokens_saved": 0,@@ -839,6 +894,8 @@ def _read_rtk_lifetime_stats() -> dict[str, Any] | None:}except Exception:return {+ "tool": _CONTEXT_TOOL_RTK,+ "label": _context_tool_label(_CONTEXT_TOOL_RTK),"installed": True,"total_commands": 0,"tokens_saved": 0,@@ -848,46 +905,153 @@ def _read_rtk_lifetime_stats() -> dict[str, Any] | None:return payload-def initialize_rtk_session_baseline() -> None:- """Pin the current rtk counters as the proxy-session baseline."""+def _read_lean_ctx_lifetime_stats() -> dict[str, Any] | None:+ """Read lean-ctx's current project-level lifetime stats."""- payload = _read_rtk_lifetime_stats()- with _rtk_stats_cache_lock:- _rtk_session_baseline.update(+ from headroom.lean_ctx import get_lean_ctx_path++ lean_ctx_path = get_lean_ctx_path()+ if not lean_ctx_path:+ return {+ "tool": _CONTEXT_TOOL_LEAN_CTX,+ "label": _context_tool_label(_CONTEXT_TOOL_LEAN_CTX),+ "installed": False,+ "total_commands": 0,+ "tokens_saved": 0,+ "avg_savings_pct": 0.0,+ }++ base_payload = {+ "tool": _CONTEXT_TOOL_LEAN_CTX,+ "label": _context_tool_label(_CONTEXT_TOOL_LEAN_CTX),+ "installed": True,+ "total_commands": 0,+ "tokens_saved": 0,+ "avg_savings_pct": 0.0,+ }++ try:+ result = subprocess.run(+ [str(lean_ctx_path), "gain", "--json"],+ capture_output=True,+ text=True,+ timeout=5,+ )+ if result.returncode != 0 or not result.stdout.strip():+ return dict(base_payload)++ data = json.loads(result.stdout)+ summary = data.get("summary", data) if isinstance(data, dict) else {}+ if not isinstance(summary, dict):+ return dict(base_payload)++ return {+ **base_payload,+ "total_commands": _coerce_int(+ _first_value(+ summary,+ (+ "total_commands",+ "commands",+ "command_count",+ "totalCommandCount",+ ),+ )+ ),+ "tokens_saved": _coerce_int(+ _first_value(+ summary,+ (+ "total_saved",+ "tokens_saved",+ "total_tokens_saved",+ "saved_tokens",+ "totalSaved",+ ),+ )+ ),+ "avg_savings_pct": _coerce_float(+ _first_value(+ summary,+ (+ "avg_savings_pct",+ "average_savings_pct",+ "avgSavingsPct",+ "savings_percent",+ ),+ 0.0,+ )+ ),+ }+ except Exception:+ return dict(base_payload)+++def _read_context_tool_lifetime_stats(tool: str) -> dict[str, Any] | None:+ if tool == _CONTEXT_TOOL_LEAN_CTX:+ return _read_lean_ctx_lifetime_stats()+ return _read_rtk_lifetime_stats()+++def initialize_context_tool_session_baseline() -> None:+ """Pin the current context-tool counters as the proxy-session baseline."""++ tool = _selected_context_tool()+ payload = _read_context_tool_lifetime_stats(tool)+ with _context_tool_stats_cache_lock:+ _context_tool_session_baseline.update({"initialized": True,+ "tool": tool,"total_commands": int((payload or {}).get("total_commands", 0) or 0),"tokens_saved": int((payload or {}).get("tokens_saved", 0) or 0),})- _rtk_stats_cache.update(+ _context_tool_stats_cache.update({"expires_at": 0.0,"has_value": False,+ "tool": None,"value": None,})-def _get_rtk_stats() -> dict[str, Any] | None:- """Get rtk savings for the current Headroom proxy session.+def initialize_rtk_session_baseline() -> None:+ """Pin the current context-tool counters as the proxy-session baseline."""++ initialize_context_tool_session_baseline()- rtk persists project-level lifetime counters. Dashboard stats should be- session-local, so we subtract the counter snapshot captured at proxy- startup instead of resetting rtk's own history.++def _get_context_tool_stats() -> dict[str, Any] | None:+ """Get context-tool savings for the current Headroom proxy session.++ RTK and lean-ctx persist project-level lifetime counters. Dashboard stats+ should be session-local, so we subtract the counter snapshot captured at+ proxy startup instead of resetting the tool's own history."""+ tool = _selected_context_tool()now = time.monotonic()- with _rtk_stats_cache_lock:- if _rtk_stats_cache["has_value"] and now < float(_rtk_stats_cache["expires_at"]):- return cast(dict[str, Any] | None, _rtk_stats_cache["value"])-- payload = _read_rtk_lifetime_stats()- with _rtk_stats_cache_lock:- if not _rtk_session_baseline["initialized"]:- _rtk_session_baseline.update(+ with _context_tool_stats_cache_lock:+ cached_value = cast(dict[str, Any] | None, _context_tool_stats_cache["value"])+ if (+ _context_tool_stats_cache["has_value"]+ and now < float(_context_tool_stats_cache["expires_at"])+ and _context_tool_stats_cache.get("tool") == tool+ ):+ return cached_value++ payload = _read_context_tool_lifetime_stats(tool)+ with _context_tool_stats_cache_lock:+ if (+ not _context_tool_session_baseline["initialized"]+ or _context_tool_session_baseline.get("tool") != tool+ ):+ _context_tool_session_baseline.update({"initialized": True,+ "tool": tool,"total_commands": int((payload or {}).get("total_commands", 0) or 0),"tokens_saved": int((payload or {}).get("tokens_saved", 0) or 0),}@@ -896,28 +1060,37 @@ def _get_rtk_stats() -> dict[str, Any] | None:if payload is not None:payload = {**payload,+ "tool": tool,+ "label": _context_tool_label(tool),"total_commands": max(int(payload.get("total_commands", 0) or 0)- - int(_rtk_session_baseline["total_commands"]),+ - int(_context_tool_session_baseline["total_commands"]),0,),"tokens_saved": max(int(payload.get("tokens_saved", 0) or 0)- - int(_rtk_session_baseline["tokens_saved"]),+ - int(_context_tool_session_baseline["tokens_saved"]),0,),}- _rtk_stats_cache.update(+ _context_tool_stats_cache.update({- "expires_at": time.monotonic() + RTK_STATS_CACHE_TTL_SECONDS,+ "expires_at": time.monotonic() + CONTEXT_TOOL_STATS_CACHE_TTL_SECONDS,"has_value": True,+ "tool": tool,"value": payload,})return payload+def _get_rtk_stats() -> dict[str, Any] | None:+ """Backward-compatible alias for selected context-tool stats."""++ return _get_context_tool_stats()++def is_anthropic_auth(headers: dict[str, str]) -> bool:"""Detect Anthropic auth signals in request headers."""if headers.get("x-api-key") or headers.get("anthropic-version"):diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 78fcdd958..30f66d1b0 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -116,11 +116,12 @@ from headroom.proxy.helpers import (MAX_MESSAGE_ARRAY_LENGTH, # noqa: F401MAX_REQUEST_BODY_SIZE, # noqa: F401MAX_SSE_BUFFER_SIZE, # noqa: F401+ _get_context_tool_stats,_get_image_compressor, # noqa: F401_get_rtk_stats, # noqa: F401_read_request_json, # noqa: F401_setup_file_logging, # noqa: F401- initialize_rtk_session_baseline,+ initialize_context_tool_session_baseline,is_anthropic_auth, # noqa: F401jitter_delay_ms,)@@ -1339,7 +1340,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:app.state.started_at = time.time()app.state.ready = Falseapp.state.startup_error = None- initialize_rtk_session_baseline()+ initialize_context_tool_session_baseline()try:try:@@ -1700,15 +1701,24 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# Build prefix cache stats once (used in both prefix_cache and cost)prefix_cache_stats = _build_prefix_cache_stats(m, proxy.cost_tracker)- # Fetch CLI filtering savings (rtk — tokens avoided before reaching context)- cli_filtering_stats = _get_rtk_stats()+ # Fetch CLI filtering savings from the selected context tool. These+ # tokens are avoided before they reach model context.+ cli_filtering_stats = _get_context_tool_stats()+ cli_filtering_tool = (+ str(cli_filtering_stats.get("tool", "rtk")) if cli_filtering_stats else "rtk"+ )+ cli_filtering_label = (+ str(cli_filtering_stats.get("label", "RTK")) if cli_filtering_stats else "RTK"+ )cli_tokens_avoided = (cli_filtering_stats.get("tokens_saved", 0) if cli_filtering_stats else 0)+ rtk_tokens_avoided = cli_tokens_avoided if cli_filtering_tool == "rtk" else 0+ lean_ctx_tokens_avoided = cli_tokens_avoided if cli_filtering_tool == "lean-ctx" else 0# Calculate total tokens before Headroom-side reduction. Proxy- # compression and rtk both remove tokens before they reach model- # context, so dashboard-facing compression savings combines them.+ # compression and the configured context tool both remove tokens before+ # they reach model context, so dashboard-facing savings combines them.proxy_compression_tokens = m.tokens_saved_totalall_layers_tokens_saved = proxy_compression_tokens + cli_tokens_avoidedtotal_tokens_before = m.tokens_input_total + all_layers_tokens_saved@@ -1767,21 +1777,27 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"total_tokens": total_tokens_all_layers,"by_layer": {"cli_filtering": {+ "tool": cli_filtering_tool,+ "label": cli_filtering_label,"tokens": cli_tokens_avoided,+ "tokens_saved": cli_tokens_avoided,"included_in": "tokens.saved","description": (- "Tokens avoided by CLI output filtering (rtk) before reaching context. "+ f"Tokens avoided by CLI output filtering ({cli_filtering_label}) "+ "before reaching context. ""Included in dashboard token savings, but not in dollar savings."),},"compression": {"tokens": proxy_compression_tokens,"proxy_tokens": proxy_compression_tokens,- "rtk_tokens": cli_tokens_avoided,+ "cli_filtering_tokens": cli_tokens_avoided,+ "rtk_tokens": rtk_tokens_avoided,+ "lean_ctx_tokens": lean_ctx_tokens_avoided,"all_layers_tokens": all_layers_tokens_saved,"description": ("Tokens removed by Headroom proxy compression. "- "Dashboard token savings also includes rtk CLI filtering."+ "Dashboard token savings also includes CLI context-tool filtering."),},"prefix_cache": {@@ -1808,7 +1824,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"output": m.tokens_output_total,"saved": all_layers_tokens_saved,"proxy_compression_saved": proxy_compression_tokens,- "rtk_saved": cli_tokens_avoided,+ "cli_filtering_saved": cli_tokens_avoided,+ "rtk_saved": rtk_tokens_avoided,+ "lean_ctx_saved": lean_ctx_tokens_avoided,"cli_tokens_avoided": cli_tokens_avoided,"proxy_total_before_compression": proxy_total_before_compression,"total_before_compression": total_tokens_before,@@ -1904,6 +1922,14 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:),},"toin": get_toin().get_stats(),+ "context_tool": {+ "configured": cli_filtering_tool,+ "label": cli_filtering_label,+ "available": bool(+ cli_filtering_stats and cli_filtering_stats.get("installed", False)+ ),+ "stats": cli_filtering_stats,+ },"cli_filtering": cli_filtering_stats,"cache": await proxy.cache.stats() if proxy.cache else None,"rate_limiter": await proxy.rate_limiter.stats() if proxy.rate_limiter else None,@@ -1956,7 +1982,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:await proxy.metrics.reset_runtime()if proxy.cost_tracker:proxy.cost_tracker.reset_runtime()- initialize_rtk_session_baseline()+ initialize_context_tool_session_baseline()async with _stats_snapshot_lock:_stats_snapshot["value"] = None_stats_snapshot["expires_at"] = 0.0diff --git a/headroom/subscription/models.py b/headroom/subscription/models.pyindex 45b17620b..df93996b7 100644--- a/headroom/subscription/models.py+++ b/headroom/subscription/models.py@@ -4,7 +4,7 @@ Mirrors the Anthropic OAuth usage API response exactly, including:- five_hour / seven_day rolling windows (utilization + reset times)- seven_day_opus / seven_day_sonnet per-model 7-day windows- extra_usage overage block (credits stored in cents by Anthropic)- - Headroom contribution: tokens conserved by compression, rtk, cache+ - Headroom contribution: tokens conserved by compression, CLI filtering, cache- Window discrepancy detection (surge pricing, cache-miss anomalies)"""@@ -383,8 +383,11 @@ class HeadroomContribution:tokens_saved_compression: int = 0"""Input tokens removed by proxy compression."""+ tokens_saved_cli_filtering: int = 0+ """Tokens avoided by the selected CLI context tool before reaching context."""+tokens_saved_rtk: int = 0- """Tokens avoided by CLI filtering (rtk) before reaching context."""+ """Deprecated alias for CLI filtering tokens from older persisted state."""tokens_saved_cache_reads: int = 0"""Input tokens served from Anthropic prefix-cache (discounted reads)."""@@ -392,19 +395,26 @@ class HeadroomContribution:compression_savings_usd: float = 0.0cache_savings_usd: float = 0.0+ def cli_filtering_saved(self) -> int:+ return max(self.tokens_saved_cli_filtering, self.tokens_saved_rtk)+def total_saved(self) -> int:- return self.tokens_saved_compression + self.tokens_saved_rtk + self.tokens_saved_cache_reads+ return (+ self.tokens_saved_compression+ + self.cli_filtering_saved()+ + self.tokens_saved_cache_reads+ )def compression_saved(self) -> int:- """Tokens removed before model context by compression plus rtk."""+ """Tokens removed before model context by compression plus CLI filtering."""- return self.tokens_saved_compression + self.tokens_saved_rtk+ return self.tokens_saved_compression + self.cli_filtering_saved()def total_savings_usd(self) -> float:return self.compression_savings_usd + self.cache_savings_usddef raw_without_headroom(self) -> int:- return self.tokens_submitted + self.tokens_saved_compression + self.tokens_saved_rtk+ return self.tokens_submitted + self.tokens_saved_compression + self.cli_filtering_saved()def efficiency_pct(self) -> float:raw = self.raw_without_headroom()@@ -418,7 +428,8 @@ class HeadroomContribution:"tokens_saved": {"compression": self.compression_saved(),"proxy_compression": self.tokens_saved_compression,- "rtk": self.tokens_saved_rtk,+ "cli_filtering": self.cli_filtering_saved(),+ "rtk": self.cli_filtering_saved(),"cache_reads": self.tokens_saved_cache_reads,"total": self.total_saved(),},diff --git a/headroom/subscription/tracker.py b/headroom/subscription/tracker.pyindex 95260646b..9b28d0a62 100644--- a/headroom/subscription/tracker.py+++ b/headroom/subscription/tracker.py@@ -193,6 +193,7 @@ class SubscriptionTracker(QuotaTracker):*,tokens_submitted: int = 0,tokens_saved_compression: int = 0,+ tokens_saved_cli_filtering: int | None = None,tokens_saved_rtk: int = 0,tokens_saved_cache_reads: int = 0,compression_savings_usd: float = 0.0,@@ -204,9 +205,15 @@ class SubscriptionTracker(QuotaTracker):"""with self._lock:c = self._state.contribution+ cli_filtering = (+ tokens_saved_rtk+ if tokens_saved_cli_filtering is None+ else tokens_saved_cli_filtering+ )c.tokens_submitted += max(tokens_submitted, 0)c.tokens_saved_compression += max(tokens_saved_compression, 0)- c.tokens_saved_rtk += max(tokens_saved_rtk, 0)+ c.tokens_saved_cli_filtering += max(cli_filtering, 0)+ c.tokens_saved_rtk += max(cli_filtering, 0)c.tokens_saved_cache_reads += max(tokens_saved_cache_reads, 0)c.compression_savings_usd += max(compression_savings_usd, 0.0)c.cache_savings_usd += max(cache_savings_usd, 0.0)@@ -479,12 +486,14 @@ class SubscriptionTracker(QuotaTracker):c.tokens_submitted = int(contrib.get("tokens_submitted", 0))saved = contrib.get("tokens_saved", {})# Newer state writes dashboard-facing ``compression`` as- # proxy-compression + rtk. Prefer the raw proxy field when present- # so loading does not double-count rtk into the internal counter.+ # proxy-compression + CLI filtering. Prefer the raw proxy field when+ # present so loading does not double-count CLI filtering.c.tokens_saved_compression = int(saved.get("proxy_compression", saved.get("compression", 0)))- c.tokens_saved_rtk = int(saved.get("rtk", 0))+ cli_filtering = int(saved.get("cli_filtering", saved.get("rtk", 0)))+ c.tokens_saved_cli_filtering = cli_filtering+ c.tokens_saved_rtk = cli_filteringc.tokens_saved_cache_reads = int(saved.get("cache_reads", 0))savings_usd = contrib.get("savings_usd", {})c.compression_savings_usd = float(savings_usd.get("compression", 0.0))diff --git a/scripts/install.ps1 b/scripts/install.ps1index 5c6c223ed..abe01875a 100644--- a/scripts/install.ps1+++ b/scripts/install.ps1@@ -839,6 +839,38 @@ function Invoke-ClaudeRtkInit {}}+function Get-ContextTool {+ $value = $env:HEADROOM_CONTEXT_TOOL+ if ([string]::IsNullOrWhiteSpace($value)) {+ return 'rtk'+ }++ $value = $value.Trim().ToLowerInvariant().Replace('_', '-')+ if ($value -eq 'leanctx') {+ return 'lean-ctx'+ }+ if ($value -ne 'rtk' -and $value -ne 'lean-ctx') {+ Fail 'HEADROOM_CONTEXT_TOOL must be one of: lean-ctx, rtk'+ }+ return $value+}++function Invoke-LeanCtxInit {+ param([string]$Agent)++ $cmd = Get-Command lean-ctx -ErrorAction SilentlyContinue+ if (-not $cmd) {+ Write-Warning "lean-ctx is not installed on PATH; $Agent lean-ctx setup was skipped"+ return+ }++ try {+ & $cmd.Source init --agent $Agent | Out-Null+ } catch {+ Write-Warning "Failed to initialize lean-ctx for $Agent; continuing without lean-ctx setup"+ }+}+function Invoke-WithTemporaryEnv {param([hashtable]$Environment,@@ -1614,6 +1646,7 @@ switch ($args[0]) {}$parsed = Parse-WrapArgs -Arguments $wrapArgs+ $contextTool = Get-ContextTool$proxyArgs = New-Object System.Collections.Generic.List[string]if ($parsed.Learn) { $proxyArgs.Add('--learn') }if ($parsed.Backend) { $proxyArgs.AddRange([string[]]@('--backend', $parsed.Backend)) }@@ -1633,11 +1666,20 @@ switch ($args[0]) {if (-not $parsed.NoProxy) {$prepareArgs.Add('--no-proxy')}+ if ((-not $parsed.NoRtk) -and $contextTool -eq 'lean-ctx') {+ $prepareArgs.Add('--no-rtk')+ }Invoke-PrepareOnly -Tool $tool -KnownArgs $prepareArgs.ToArray()+ if ((-not $parsed.NoRtk) -and $contextTool -eq 'lean-ctx') {+ Invoke-LeanCtxInit -Agent $tool+ }+switch ($tool) {'claude' {- if (-not $parsed.NoRtk) { Invoke-ClaudeRtkInit }+ if ((-not $parsed.NoRtk) -and $contextTool -eq 'rtk') {+ Invoke-ClaudeRtkInit+ }$exitCode = Invoke-WithTemporaryEnv -Environment @{ ANTHROPIC_BASE_URL = "http://127.0.0.1:$($parsed.Port)" } -Command 'claude' -Arguments $parsed.HostArgsexit $exitCode}diff --git a/scripts/install.sh b/scripts/install.shindex 3296d8fb6..64e0f33dd 100644--- a/scripts/install.sh+++ b/scripts/install.sh@@ -797,6 +797,38 @@ run_claude_rtk_init() {fi}+selected_context_tool() {+ local value="${HEADROOM_CONTEXT_TOOL:-rtk}"+ value="${value,,}"+ value="${value//_/-}"+ if [[ -z "${value}" ]]; then+ value="rtk"+ elif [[ "${value}" == "leanctx" ]]; then+ value="lean-ctx"+ fi++ case "${value}" in+ rtk|lean-ctx)+ printf '%s\n' "${value}"+ ;;+ *)+ die "HEADROOM_CONTEXT_TOOL must be one of: lean-ctx, rtk"+ ;;+ esac+}++run_lean_ctx_init() {+ local agent="$1"+ if ! command -v lean-ctx >/dev/null 2>&1; then+ warn "lean-ctx is not installed on PATH; ${agent} lean-ctx setup was skipped"+ return+ fi++ if ! lean-ctx init --agent "${agent}" >/dev/null 2>&1; then+ warn "Failed to initialize lean-ctx for ${agent}; continuing without lean-ctx setup"+ fi+}+parse_wrap_args() {local -n out_known=$1local -n out_host=$2@@ -1470,8 +1502,9 @@ main() {returnfi- local known_args host_args port no_rtk no_proxy learn backend anyllm region+ local known_args host_args port no_rtk no_proxy learn backend anyllm region context_toolparse_wrap_args known_args host_args port no_rtk no_proxy learn backend anyllm region "$@"+ context_tool="$(selected_context_tool)"local proxy_args=()if [[ "${learn}" -eq 1 ]]; then@@ -1497,11 +1530,18 @@ main() {if [[ "${no_proxy}" -eq 0 ]]; thenprep_args+=(--no-proxy)fi+ if [[ "${no_rtk}" -eq 0 && "${context_tool}" == "lean-ctx" ]]; then+ prep_args+=(--no-rtk)+ firun_prepare_only "${tool}" "${prep_args[@]}"+ if [[ "${no_rtk}" -eq 0 && "${context_tool}" == "lean-ctx" ]]; then+ run_lean_ctx_init "${tool}"+ fi+case "${tool}" inclaude)- if [[ "${no_rtk}" -eq 0 ]]; then+ if [[ "${no_rtk}" -eq 0 && "${context_tool}" == "rtk" ]]; thenrun_claude_rtk_initfiANTHROPIC_BASE_URL="http://127.0.0.1:${port}" run_host_tool claude "${host_args[@]}"diff --git a/tests/test_cli/test_wrap_bridge.py b/tests/test_cli/test_wrap_bridge.pyindex 48c475f38..2c7b6c674 100644--- a/tests/test_cli/test_wrap_bridge.py+++ b/tests/test_cli/test_wrap_bridge.py@@ -3,12 +3,22 @@from __future__ import annotationsimport json+import subprocessfrom pathlib import Pathfrom unittest.mock import patch+import pytestfrom click.testing import CliRunnerfrom headroom.cli.main import main+from headroom.cli.wrap import _setup_lean_ctx_agent++[email protected](autouse=True)+def _default_context_tool(monkeypatch) -> None:+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)+ monkeypatch.delenv("LEAN_CTX_AGENT", raising=False)+ monkeypatch.delenv("LEAN_CTX_DATA_DIR", raising=False)def _set_test_home(monkeypatch, tmp_path: Path) -> None:@@ -29,6 +39,46 @@ def test_wrap_claude_prepare_only_skips_host_binary_lookup() -> None:which_mock.assert_not_called()+def test_wrap_claude_prepare_only_uses_lean_ctx_when_configured(monkeypatch) -> None:+ runner = CliRunner()+ monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "lean-ctx")++ with patch("headroom.cli.wrap._prepare_wrap_rtk") as prepare_rtk:+ with patch(+ "headroom.cli.wrap._setup_lean_ctx_agent",+ return_value=Path("lean-ctx"),+ ) as setup:+ result = runner.invoke(main, ["wrap", "claude", "--prepare-only"])++ assert result.exit_code == 0, result.output+ prepare_rtk.assert_not_called()+ setup.assert_called_once_with("claude", verbose=False)+++def test_setup_lean_ctx_agent_runs_outside_project_root(monkeypatch, tmp_path: Path) -> None:+ project_root = tmp_path / "project"+ project_root.mkdir()+ (project_root / ".git").mkdir()+ lean_ctx = tmp_path / "lean-ctx"+ lean_ctx.write_text("#!/bin/sh\n", encoding="utf-8")+ calls: list[dict] = []++ def fake_run(*args, **kwargs):+ calls.append({"args": args, "kwargs": kwargs})+ return subprocess.CompletedProcess(args[0], 0, stdout="", stderr="")++ monkeypatch.chdir(project_root)+ monkeypatch.setattr("headroom.lean_ctx.get_lean_ctx_path", lambda: lean_ctx)+ monkeypatch.setattr("headroom.cli.wrap.subprocess.run", fake_run)++ assert _setup_lean_ctx_agent("codex") == lean_ctx++ assert calls+ cwd = Path(calls[0]["kwargs"]["cwd"])+ assert cwd != project_root+ assert project_root not in cwd.parents++def test_wrap_codex_prepare_only_updates_config(monkeypatch, tmp_path: Path) -> None:_set_test_home(monkeypatch, tmp_path)runner = CliRunner()@@ -43,6 +93,53 @@ def test_wrap_codex_prepare_only_updates_config(monkeypatch, tmp_path: Path) ->assert 'base_url = "http://127.0.0.1:8787/v1"' in config_file.read_text()+def test_wrap_codex_prepare_only_uses_lean_ctx_when_configured(monkeypatch, tmp_path: Path) -> None:+ _set_test_home(monkeypatch, tmp_path)+ monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "lean-ctx")+ runner = CliRunner()++ with runner.isolated_filesystem(temp_dir=str(tmp_path)):+ with patch("headroom.cli.wrap._ensure_rtk_binary") as ensure_rtk:+ with patch(+ "headroom.cli.wrap._setup_lean_ctx_agent",+ return_value=Path("lean-ctx"),+ ) as setup:+ result = runner.invoke(+ main,+ ["wrap", "codex", "--prepare-only", "--no-mcp", "--no-serena"],+ )++ assert result.exit_code == 0, result.output+ ensure_rtk.assert_not_called()+ setup.assert_called_once_with("codex", verbose=False)+ assert not Path("AGENTS.md").exists()+++def test_wrap_codex_prepare_only_accepts_no_context_tool_alias(monkeypatch, tmp_path: Path) -> None:+ _set_test_home(monkeypatch, tmp_path)+ monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "lean-ctx")+ runner = CliRunner()++ with runner.isolated_filesystem(temp_dir=str(tmp_path)):+ with patch("headroom.cli.wrap._ensure_rtk_binary") as ensure_rtk:+ with patch("headroom.cli.wrap._setup_lean_ctx_agent") as setup:+ result = runner.invoke(+ main,+ [+ "wrap",+ "codex",+ "--prepare-only",+ "--no-context-tool",+ "--no-mcp",+ "--no-serena",+ ],+ )++ assert result.exit_code == 0, result.output+ ensure_rtk.assert_not_called()+ setup.assert_not_called()++def test_wrap_aider_prepare_only_injects_conventions(monkeypatch, tmp_path: Path) -> None:_set_test_home(monkeypatch, tmp_path)runner = CliRunner()@@ -71,6 +168,27 @@ def test_wrap_cursor_prepare_only_injects_cursorrules(monkeypatch, tmp_path: Patassert "headroom:rtk-instructions" in cursorrules.read_text()+def test_wrap_cursor_prepare_only_uses_lean_ctx_when_configured(+ monkeypatch, tmp_path: Path+) -> None:+ _set_test_home(monkeypatch, tmp_path)+ monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "lean-ctx")+ runner = CliRunner()++ with runner.isolated_filesystem(temp_dir=str(tmp_path)):+ with patch("headroom.cli.wrap._ensure_rtk_binary") as ensure_rtk:+ with patch(+ "headroom.cli.wrap._setup_lean_ctx_agent",+ return_value=Path("lean-ctx"),+ ) as setup:+ result = runner.invoke(main, ["wrap", "cursor", "--prepare-only"])++ assert result.exit_code == 0, result.output+ ensure_rtk.assert_not_called()+ setup.assert_called_once_with("cursor", verbose=False)+ assert not Path(".cursorrules").exists()++def test_wrap_openclaw_prepare_only_emits_config_without_python_default() -> None:runner = CliRunner()diff --git a/tests/test_lean_ctx_installer.py b/tests/test_lean_ctx_installer.pynew file mode 100644index 000000000..1ba7734b6--- /dev/null+++ b/tests/test_lean_ctx_installer.py@@ -0,0 +1,176 @@+"""Tests for managed lean-ctx installation."""++from __future__ import annotations++import io+import tarfile+import zipfile+from pathlib import Path+from types import SimpleNamespace+from unittest.mock import patch++import pytest++from headroom.lean_ctx import get_lean_ctx_path, installer+++def test_get_lean_ctx_path_finds_windows_managed_binary(tmp_path: Path) -> None:+ managed_dir = tmp_path / ".headroom" / "bin"+ managed_dir.mkdir(parents=True)+ managed_path = managed_dir / "lean-ctx.exe"+ managed_path.write_bytes(b"binary")++ with patch("headroom.lean_ctx.LEAN_CTX_BIN_DIR", managed_dir):+ with patch("headroom.lean_ctx.LEAN_CTX_BIN_PATH", managed_dir / "lean-ctx"):+ with patch("headroom.lean_ctx.shutil.which", return_value=None):+ assert get_lean_ctx_path() == managed_path+++def test_get_target_triple_uses_override(monkeypatch) -> None:+ monkeypatch.setenv("HEADROOM_LEAN_CTX_TARGET", "x86_64-pc-windows-msvc")+ assert installer._get_target_triple() == "x86_64-pc-windows-msvc"+++def test_detect_runtime_target_triple_handles_linux_gnu() -> None:+ with patch.object(installer.platform, "system", return_value="Linux"):+ with patch.object(installer.platform, "machine", return_value="x86_64"):+ with patch.object(installer, "_is_musl", return_value=False):+ assert installer._detect_runtime_target_triple() == "x86_64-unknown-linux-gnu"+++def test_detect_runtime_target_triple_handles_linux_musl_arm() -> None:+ with patch.object(installer.platform, "system", return_value="Linux"):+ with patch.object(installer.platform, "machine", return_value="aarch64"):+ with patch.object(installer, "_is_musl", return_value=True):+ assert installer._detect_runtime_target_triple() == "aarch64-unknown-linux-musl"+++def test_get_download_url_uses_windows_zip(monkeypatch) -> None:+ monkeypatch.delenv("HEADROOM_LEAN_CTX_TARGET", raising=False)+ monkeypatch.setenv("LEAN_CTX_TARGET", "x86_64-pc-windows-msvc")++ url, ext = installer._get_download_url("v1.2.3")++ assert url == f"{installer.GITHUB_RELEASE_URL}/v1.2.3/lean-ctx-x86_64-pc-windows-msvc.zip"+ assert ext == "zip"+ assert installer._binary_name_for_target("x86_64-pc-windows-msvc") == "lean-ctx.exe"+++def test_download_lean_ctx_skips_verify_for_non_native_target(monkeypatch, tmp_path: Path) -> None:+ archive = io.BytesIO()+ with tarfile.open(fileobj=archive, mode="w:gz") as tf:+ info = tarfile.TarInfo(name="lean-ctx")+ payload = b"fake-binary"+ info.size = len(payload)+ tf.addfile(info, io.BytesIO(payload))+ archive_bytes = archive.getvalue()++ class _Response:+ def __enter__(self):+ return self++ def __exit__(self, exc_type, exc, tb):+ return False++ def read(self) -> bytes:+ return archive_bytes++ monkeypatch.setenv("HEADROOM_LEAN_CTX_TARGET", "x86_64-apple-darwin")++ with patch.object(installer, "LEAN_CTX_BIN_DIR", tmp_path):+ with patch.object(installer, "urlopen", return_value=_Response()):+ with patch.object(installer.subprocess, "run") as subprocess_run:+ installed_path = installer.download_lean_ctx("v3.4.7")++ assert installed_path == tmp_path / "lean-ctx"+ assert installed_path.exists()+ subprocess_run.assert_not_called()+++def test_download_lean_ctx_extracts_zip_binary(monkeypatch, tmp_path: Path) -> None:+ archive = io.BytesIO()+ with zipfile.ZipFile(archive, mode="w") as zf:+ zf.writestr("lean-ctx.exe", b"fake-windows-binary")++ class _Response:+ def __enter__(self):+ return self++ def __exit__(self, exc_type, exc, tb):+ return False++ def read(self) -> bytes:+ return archive.getvalue()++ monkeypatch.setenv("HEADROOM_LEAN_CTX_TARGET", "x86_64-pc-windows-msvc")++ with patch.object(installer, "LEAN_CTX_BIN_DIR", tmp_path):+ with patch.object(installer, "urlopen", return_value=_Response()):+ installed_path = installer.download_lean_ctx("v3.4.7")++ assert installed_path == tmp_path / "lean-ctx.exe"+ assert installed_path.read_bytes() == b"fake-windows-binary"+++def test_download_lean_ctx_verifies_native_target(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.delenv("HEADROOM_LEAN_CTX_TARGET", raising=False)+ monkeypatch.delenv("LEAN_CTX_TARGET", raising=False)++ archive = io.BytesIO()+ with tarfile.open(fileobj=archive, mode="w:gz") as tf:+ info = tarfile.TarInfo(name="dist/lean-ctx")+ payload = b"fake-native-binary"+ info.size = len(payload)+ tf.addfile(info, io.BytesIO(payload))++ class _Response:+ def __enter__(self):+ return self++ def __exit__(self, exc_type, exc, tb):+ return False++ def read(self) -> bytes:+ return archive.getvalue()++ run_result = SimpleNamespace(returncode=0, stdout="lean-ctx 3.4.7", stderr="")++ with patch.object(installer, "LEAN_CTX_BIN_DIR", tmp_path):+ with patch.object(+ installer, "_detect_runtime_target_triple", return_value="x86_64-unknown-linux-gnu"+ ):+ with patch.object(installer, "urlopen", return_value=_Response()):+ with patch.object(+ installer.subprocess, "run", return_value=run_result+ ) as subprocess_run:+ installed_path = installer.download_lean_ctx("v3.4.7")++ assert installed_path == tmp_path / "lean-ctx"+ subprocess_run.assert_called_once_with(+ [str(installed_path), "--version"],+ capture_output=True,+ text=True,+ encoding="utf-8",+ errors="replace",+ timeout=5,+ )+++def test_download_lean_ctx_rejects_invalid_download_url(tmp_path: Path) -> None:+ with patch.object(installer, "LEAN_CTX_BIN_DIR", tmp_path):+ with patch.object(installer, "_get_target_triple", return_value="x86_64-unknown-linux-gnu"):+ with patch.object(+ installer,+ "_get_download_url",+ return_value=("file:///tmp/lean-ctx.tar.gz", "tar.gz"),+ ):+ with pytest.raises(RuntimeError, match="Invalid URL scheme"):+ installer.download_lean_ctx("v3.4.7")+++def test_ensure_lean_ctx_returns_none_when_download_fails() -> None:+ with patch("headroom.lean_ctx.get_lean_ctx_path", return_value=None):+ with patch.object(+ installer, "download_lean_ctx", side_effect=RuntimeError("download failed")+ ):+ assert installer.ensure_lean_ctx() is Nonediff --git a/tests/test_paths.py b/tests/test_paths.pyindex 33013860a..6af26ef9c 100644--- a/tests/test_paths.py+++ b/tests/test_paths.py@@ -326,6 +326,12 @@ def test_rtk_path_suffix(fake_home: Path) -> None:assert paths.rtk_path().parent == paths.bin_dir()+def test_lean_ctx_path_suffix(fake_home: Path) -> None:+ expected_name = "lean-ctx.exe" if os.name == "nt" else "lean-ctx"+ assert paths.lean_ctx_path().name == expected_name+ assert paths.lean_ctx_path().parent == paths.bin_dir()++def test_deploy_root_default(fake_home: Path) -> None:assert paths.deploy_root() == fake_home / ".headroom" / "deploy"@@ -384,6 +390,15 @@ def test_rtk_path_follows_workspace_env(assert paths.rtk_path() == ws / "bin" / expected_name+def test_lean_ctx_path_follows_workspace_env(+ fake_home: Path, clean_env: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ ws = tmp_path / "state"+ clean_env.setenv(paths.HEADROOM_WORKSPACE_DIR_ENV, str(ws))+ expected_name = "lean-ctx.exe" if os.name == "nt" else "lean-ctx"+ assert paths.lean_ctx_path() == ws / "bin" / expected_name++def test_beacon_lock_path_follows_workspace_env(fake_home: Path, clean_env: pytest.MonkeyPatch, tmp_path: Path) -> None:diff --git a/tests/test_proxy_dashboard_stats_cache.py b/tests/test_proxy_dashboard_stats_cache.pyindex eea9521a3..d9d970615 100644--- a/tests/test_proxy_dashboard_stats_cache.py+++ b/tests/test_proxy_dashboard_stats_cache.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport jsonimport shutilimport subprocess+from pathlib import Pathfrom types import SimpleNamespaceimport pytest@@ -28,14 +29,19 @@ class _ToinStub:@pytest.fixture(autouse=True)-def _reset_rtk_stats_cache() -> None:- proxy_helpers._rtk_stats_cache.update({"expires_at": 0.0, "has_value": False, "value": None})+def _reset_rtk_stats_cache(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)+ monkeypatch.setenv("HEADROOM_REQUIRE_RUST_CORE", "false")+ proxy_helpers._rtk_stats_cache.update(+ {"expires_at": 0.0, "has_value": False, "tool": None, "value": None}+ )proxy_helpers._rtk_session_baseline.update(- {"initialized": False, "total_commands": 0, "tokens_saved": 0}+ {"initialized": False, "tool": None, "total_commands": 0, "tokens_saved": 0})def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)now = {"value": 100.0}calls = {"run": 0}totals = [@@ -60,6 +66,8 @@ def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatchassert first == secondassert first == {+ "tool": "rtk",+ "label": "RTK","installed": True,"total_commands": 0,"tokens_saved": 0,@@ -71,6 +79,8 @@ def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatchthird = proxy_helpers._get_rtk_stats()assert third == {+ "tool": "rtk",+ "label": "RTK","installed": True,"total_commands": 2,"tokens_saved": 266,@@ -79,6 +89,56 @@ def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatchassert calls["run"] == 2+def test_get_context_tool_stats_reads_lean_ctx_gain(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "lean-ctx")+ now = {"value": 100.0}+ calls = {"run": 0}+ totals = [+ {"total_commands": 3, "tokens_saved": 400, "avg_savings_pct": 12.5},+ {"total_commands": 5, "tokens_saved": 475, "avg_savings_pct": 15.0},+ ]++ def _fake_run(args, **kwargs):+ calls["run"] += 1+ assert args == ["/usr/bin/lean-ctx", "gain", "--json"]+ summary = totals[min(calls["run"] - 1, len(totals) - 1)]+ return SimpleNamespace(returncode=0, stdout=json.dumps({"summary": summary}))++ monkeypatch.setattr(proxy_helpers.time, "monotonic", lambda: now["value"])+ monkeypatch.setattr(+ "headroom.lean_ctx.get_lean_ctx_path",+ lambda: Path("/usr/bin/lean-ctx"),+ )+ monkeypatch.setattr(subprocess, "run", _fake_run)++ first = proxy_helpers._get_context_tool_stats()+ second = proxy_helpers._get_context_tool_stats()++ assert first == second+ assert first == {+ "tool": "lean-ctx",+ "label": "lean-ctx",+ "installed": True,+ "total_commands": 0,+ "tokens_saved": 0,+ "avg_savings_pct": 12.5,+ }+ assert calls["run"] == 1++ now["value"] += proxy_helpers.CONTEXT_TOOL_STATS_CACHE_TTL_SECONDS + 0.1+ third = proxy_helpers._get_context_tool_stats()++ assert third == {+ "tool": "lean-ctx",+ "label": "lean-ctx",+ "installed": True,+ "total_commands": 2,+ "tokens_saved": 75,+ "avg_savings_pct": 15.0,+ }+ assert calls["run"] == 2++def test_stats_cached_query_reuses_short_ttl_snapshot(monkeypatch: pytest.MonkeyPatch) -> None:pytest.importorskip("fastapi")from fastapi.testclient import TestClient@@ -86,7 +146,7 @@ def test_stats_cached_query_reuses_short_ttl_snapshot(monkeypatch: pytest.Monkeyimport headroom.proxy.server as serverfrom headroom.proxy.server import ProxyConfig, create_app- calls = {"store": 0, "telemetry": 0, "feedback": 0, "rtk": 0}+ calls = {"store": 0, "telemetry": 0, "feedback": 0, "context_tool": 0}now = {"value": 100.0}monkeypatch.setattr(server.time, "monotonic", lambda: now["value"])@@ -106,16 +166,18 @@ def test_stats_cached_query_reuses_short_ttl_snapshot(monkeypatch: pytest.Monkeylambda: _StatsStub(calls, "feedback", {}),)- def _fake_rtk_stats() -> dict[str, int | bool | float]:- calls["rtk"] += 1+ def _fake_context_tool_stats() -> dict[str, int | bool | float | str]:+ calls["context_tool"] += 1return {+ "tool": "rtk",+ "label": "RTK","installed": True,"total_commands": 1,"tokens_saved": 5,"avg_savings_pct": 10.0,}- monkeypatch.setattr(server, "_get_rtk_stats", _fake_rtk_stats)+ monkeypatch.setattr(server, "_get_context_tool_stats", _fake_context_tool_stats)monkeypatch.setattr(server, "get_toin", lambda: _ToinStub())app = create_app(@@ -143,21 +205,142 @@ def test_stats_cached_query_reuses_short_ttl_snapshot(monkeypatch: pytest.Monkeyassert third.status_code == 200assert uncached.status_code == 200- assert calls == {"store": 3, "telemetry": 3, "feedback": 3, "rtk": 3}+ assert calls == {"store": 3, "telemetry": 3, "feedback": 3, "context_tool": 3}+ assert first.json()["context_tool"]["configured"] == "rtk"+ assert first.json()["context_tool"]["label"] == "RTK"assert first.json()["cli_filtering"]["tokens_saved"] == 5assert first.json()["tokens"]["saved"] == 5assert first.json()["tokens"]["proxy_compression_saved"] == 0+ assert first.json()["tokens"]["cli_filtering_saved"] == 5assert first.json()["tokens"]["rtk_saved"] == 5+ assert first.json()["tokens"]["lean_ctx_saved"] == 0assert first.json()["tokens"]["all_layers_saved"] == 5assert (first.json()["tokens"]["savings_percent"]== first.json()["tokens"]["all_layers_savings_percent"])assert first.json()["savings"]["by_layer"]["compression"]["tokens"] == 0+ assert first.json()["savings"]["by_layer"]["compression"]["cli_filtering_tokens"] == 5assert first.json()["savings"]["by_layer"]["compression"]["rtk_tokens"] == 5+ assert first.json()["savings"]["by_layer"]["compression"]["lean_ctx_tokens"] == 0assert first.json()["savings"]["by_layer"]["compression"]["all_layers_tokens"] == 5+def test_stats_reports_lean_ctx_as_selected_cli_filter(monkeypatch: pytest.MonkeyPatch) -> None:+ pytest.importorskip("fastapi")+ from fastapi.testclient import TestClient++ import headroom.proxy.server as server+ from headroom.proxy.server import ProxyConfig, create_app++ monkeypatch.setattr(+ server,+ "get_compression_store",+ lambda: _StatsStub({"store": 0}, "store", {}),+ )+ monkeypatch.setattr(+ server,+ "get_telemetry_collector",+ lambda: _StatsStub({"telemetry": 0}, "telemetry", {}),+ )+ monkeypatch.setattr(+ server,+ "get_compression_feedback",+ lambda: _StatsStub({"feedback": 0}, "feedback", {}),+ )+ monkeypatch.setattr(+ server,+ "_get_context_tool_stats",+ lambda: {+ "tool": "lean-ctx",+ "label": "lean-ctx",+ "installed": True,+ "total_commands": 1,+ "tokens_saved": 9,+ "avg_savings_pct": 11.0,+ },+ )+ monkeypatch.setattr(server, "get_toin", lambda: _ToinStub())++ app = create_app(+ ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ ccr_inject_tool=False,+ ccr_handle_responses=False,+ ccr_context_tracking=False,+ )+ )++ with TestClient(app) as client:+ response = client.get("/stats")++ payload = response.json()+ assert response.status_code == 200+ assert payload["context_tool"]["configured"] == "lean-ctx"+ assert payload["savings"]["by_layer"]["cli_filtering"]["label"] == "lean-ctx"+ assert payload["tokens"]["cli_filtering_saved"] == 9+ assert payload["tokens"]["rtk_saved"] == 0+ assert payload["tokens"]["lean_ctx_saved"] == 9+ assert payload["savings"]["by_layer"]["compression"]["rtk_tokens"] == 0+ assert payload["savings"]["by_layer"]["compression"]["lean_ctx_tokens"] == 9+++def test_cost_merge_uses_generic_cli_filtering_name() -> None:+ from headroom.proxy.cost import merge_cost_stats++ payload = merge_cost_stats(+ {"savings_usd": 1.23456, "other": "kept"},+ {"totals": {"net_savings_usd": 0.25}},+ cli_tokens_avoided=12,+ )++ assert payload is not None+ assert payload["compression_savings_usd"] == 1.2346+ assert payload["cache_savings_usd"] == 0.25+ assert payload["cli_tokens_avoided"] == 12+ assert payload["cli_filtering_tokens_avoided"] == 12+ assert payload["cli_filtering_tokens_included_in_compression"] is True+ assert payload["cli_tokens_included_in_compression"] is True+++def test_session_summary_uses_generic_cli_filtering_keys() -> None:+ from headroom.proxy.cost import build_session_summary++ proxy = SimpleNamespace(+ config=SimpleNamespace(mode="token"),+ logger=SimpleNamespace(_logs=[]),+ cost_tracker=SimpleNamespace(+ stats=lambda: {+ "cost_with_headroom_usd": 2.0,+ "savings_usd": 0.5,+ }+ ),+ )+ metrics = SimpleNamespace(+ requests_by_model={"gpt-test": 1},+ tokens_saved_total=20,+ )++ payload = build_session_summary(+ proxy,+ metrics,+ {"totals": {"net_savings_usd": 0.2}},+ cli_tokens_avoided=7,+ total_tokens_before=100,+ )++ assert payload["compression"]["cli_filtering_tokens_avoided"] == 7+ assert payload["compression"]["total_tokens_saved_with_cli_filtering"] == 27+ assert payload["compression"]["total_tokens_before_with_cli_filtering"] == 100+ assert payload["compression"]["rtk_tokens_avoided"] == 7+ assert payload["cost"]["breakdown"]["cli_filtering_savings_usd"] is None+ assert payload["cost"]["breakdown"]["rtk_savings_usd"] is None++def test_stats_reset_clears_runtime_proxy_counters(monkeypatch: pytest.MonkeyPatch) -> None:pytest.importorskip("fastapi")from fastapi.testclient import TestClient@@ -181,7 +364,7 @@ def test_stats_reset_clears_runtime_proxy_counters(monkeypatch: pytest.MonkeyPat"get_compression_feedback",lambda: _StatsStub({"feedback": 0}, "feedback", {}),)- monkeypatch.setattr(server, "_get_rtk_stats", lambda: None)+ monkeypatch.setattr(server, "_get_context_tool_stats", lambda: None)monkeypatch.setattr(server, "get_toin", lambda: _ToinStub())app = create_app(@@ -224,3 +407,9 @@ def test_dashboard_uses_cached_stats_and_lazy_history_feed_polling() -> None:assert "this.viewMode === 'history'" in htmlassert "this.feedOpen" in htmlassert "CLI Filtering (rtk)" not in html+ assert "RTK Filtered" not in html+ assert "|| 'RTK'" not in html+ assert "rtkShareOfTotal" not in html+ assert "Lean-ctx" in html+ assert "Context Tool" in html+ assert "cliFilteringLabel + ' Filtered'" in htmldiff --git a/tests/test_subscription_tracker.py b/tests/test_subscription_tracker.pyindex b591283f0..00c069730 100644--- a/tests/test_subscription_tracker.py+++ b/tests/test_subscription_tracker.py@@ -56,7 +56,7 @@ def test_tracker_notify_active_update_and_basic_state(monkeypatch: pytest.Monkeytracker.update_contribution(tokens_submitted=10,tokens_saved_compression=5,- tokens_saved_rtk=-1,+ tokens_saved_cli_filtering=-1,tokens_saved_cache_reads=3,compression_savings_usd=1.25,cache_savings_usd=-2.0,@@ -64,10 +64,13 @@ def test_tracker_notify_active_update_and_basic_state(monkeypatch: pytest.Monkeycontribution = tracker._state.contributionassert contribution.tokens_submitted == 10assert contribution.tokens_saved_compression == 5+ assert contribution.tokens_saved_cli_filtering == 0assert contribution.tokens_saved_rtk == 0assert contribution.tokens_saved_cache_reads == 3assert contribution.to_dict()["tokens_saved"]["compression"] == 5assert contribution.to_dict()["tokens_saved"]["proxy_compression"] == 5+ assert contribution.to_dict()["tokens_saved"]["cli_filtering"] == 0+ assert contribution.to_dict()["tokens_saved"]["rtk"] == 0assert contribution.compression_savings_usd == 1.25assert contribution.cache_savings_usd == 0.0@@ -178,7 +181,7 @@ def test_persist_and_load_state_round_trip(tmp_path: Path) -> None:tracker.update_contribution(tokens_submitted=11,tokens_saved_compression=2,- tokens_saved_rtk=3,+ tokens_saved_cli_filtering=3,tokens_saved_cache_reads=4,compression_savings_usd=1.5,cache_savings_usd=2.5,@@ -189,10 +192,13 @@ def test_persist_and_load_state_round_trip(tmp_path: Path) -> None:loader = SubscriptionTracker(persist_path=persist_path)assert loader._state.contribution.tokens_submitted == 11assert loader._state.contribution.tokens_saved_compression == 2+ assert loader._state.contribution.tokens_saved_cli_filtering == 3assert loader._state.contribution.tokens_saved_rtk == 3assert loader._state.contribution.tokens_saved_cache_reads == 4assert loader._state.contribution.to_dict()["tokens_saved"]["compression"] == 5assert loader._state.contribution.to_dict()["tokens_saved"]["proxy_compression"] == 2+ assert loader._state.contribution.to_dict()["tokens_saved"]["cli_filtering"] == 3+ assert loader._state.contribution.to_dict()["tokens_saved"]["rtk"] == 3assert loader._state.contribution.compression_savings_usd == 1.5assert loader._state.contribution.cache_savings_usd == 2.5assert loader._state.poll_count == 7diff --git a/tests/test_telemetry_warning.py b/tests/test_telemetry_warning.pyindex 8c9755955..43186c4a4 100644--- a/tests/test_telemetry_warning.py+++ b/tests/test_telemetry_warning.py@@ -139,6 +139,17 @@ class TestProxyCLITelemetryBanner:assert "HEADROOM_TELEMETRY=off" in result.output or "--no-telemetry" in result.output+ def test_banner_shows_context_tool(self, runner, monkeypatch):+ monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "lean-ctx")++ from headroom.cli.main import main++ with patch("headroom.proxy.server.run_server", side_effect=SystemExit(0)):+ result = runner.invoke(main, ["proxy"])++ assert result.exit_code == 0+ assert "Context Tool: lean-ctx" in result.output+# ---------------------------------------------------------------------------# wrap CLI telemetry notice