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(proxy): per-project savings breakdown on the dashboard (claude, codex, aider, copilot, cursor) (#803)
Focused Instability914a60a2b07c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c284fb3ba..46cf18156 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).+## Unreleased++### Features++* **proxy:** per-project savings breakdown on the dashboard for all wrapped agents — Claude Code, Codex, aider, Copilot, and Cursor ([#802](https://github.com/chopratejas/headroom/issues/802)). `headroom wrap claude`/`codex` tag requests with an `X-Headroom-Project` header (launch-directory name); `wrap aider`/`copilot`/`cursor` — whose clients cannot send custom headers — use a `/p/<name>` base-URL prefix the proxy strips. Savings are aggregated per project (persisted, schema v3 with transparent v2 migration), exposed as `savings.per_project` in `/stats` and `projects` in `/stats-history`, and shown in a Per-Project Savings dashboard table.++## [0.24.0](https://github.com/chopratejas/headroom/compare/v0.23.0...v0.24.0) (2026-06-08)diff --git a/e2e/wrap/run.py b/e2e/wrap/run.pyindex 4597f68d9..38e57a870 100644--- a/e2e/wrap/run.py+++ b/e2e/wrap/run.py@@ -14,6 +14,7 @@ import timefrom http.server import BaseHTTPRequestHandler, ThreadingHTTPServerfrom pathlib import Pathfrom typing import Any+from urllib.parse import quoteimport httpx@@ -654,19 +655,23 @@ def verify_aider_wrap(base_env: dict[str, str], project_dir: Path, log_dir: Pathentries = read_jsonl(log_dir / "aider.jsonl")assert_true(len(entries) > 0, "Aider shim should have been invoked")env_vars = entries[-1]["env"]+ # Aider cannot send custom headers, so its wrap embeds the launch+ # directory as a /p/<name> base-URL prefix for per-project savings;+ # the proxy strips it before routing, so the probes still succeed.+ project_prefix = f"/p/{quote(project_dir.name, safe='')}"assert_true(- env_vars.get("OPENAI_API_BASE") == f"http://127.0.0.1:{port}/v1",+ env_vars.get("OPENAI_API_BASE") == f"http://127.0.0.1:{port}{project_prefix}/v1","Aider wrap should set OPENAI_API_BASE",)assert_true(- env_vars.get("ANTHROPIC_BASE_URL") == f"http://127.0.0.1:{port}",+ env_vars.get("ANTHROPIC_BASE_URL") == f"http://127.0.0.1:{port}{project_prefix}","Aider wrap should set ANTHROPIC_BASE_URL",)assert_true(entries[-1]["probes"]== [- {"url": f"http://127.0.0.1:{port}/v1/models", "status": 200},- {"url": f"http://127.0.0.1:{port}/health", "status": 200},+ {"url": f"http://127.0.0.1:{port}{project_prefix}/v1/models", "status": 200},+ {"url": f"http://127.0.0.1:{port}{project_prefix}/health", "status": 200},],"Aider shim should prove both configured base URLs point at a live proxy",)@@ -686,8 +691,10 @@ def verify_cursor_wrap(base_env: dict[str, str], project_dir: Path) -> None:)try:output = wait_for_output(proc, "Press Ctrl+C to stop the proxy.", timeout=30)+ # Cursor setup lines embed the /p/<name> per-project prefix.+ cursor_prefix = f"/p/{quote(project_dir.name, safe='')}"assert_true(- f"http://127.0.0.1:{port}/v1" in output,+ f"http://127.0.0.1:{port}{cursor_prefix}/v1" in output,"Cursor wrap should print the OpenAI base URL override",)assert_true(diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 353383d95..da00b4064 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -87,6 +87,7 @@ from headroom.providers.openclaw import (from headroom.providers.openclaw import (normalize_gateway_provider_ids as _normalize_openclaw_gateway_provider_ids_impl,)+from headroom.proxy.project_context import with_project_prefix as _with_project_prefixfrom .main import main@@ -944,6 +945,47 @@ def _prepare_wrap_rtk(verbose: bool = False, *, label: str | None = None) -> Patreturn _ensure_rtk_binary(verbose=verbose)+# Canonical casing for the proxy's per-project savings header (matched+# case-insensitively by headroom.proxy.project_context.PROJECT_HEADER).+_PROJECT_HEADER_NAME = "X-Headroom-Project"+++def _project_name_from_cwd() -> str | None:+ """Project label for X-Headroom-Project: basename of the launch directory.++ The proxy sanitizes and caps the value server-side+ (headroom.proxy.savings_tracker.sanitize_project_name), so the raw+ directory name is safe to send as-is.+ """+ name = Path.cwd().name.strip()+ return name or None+++def _apply_project_header_env(env: dict[str, str]) -> None:+ """Inject X-Headroom-Project into ``ANTHROPIC_CUSTOM_HEADERS``.++ Claude Code reads ``ANTHROPIC_CUSTOM_HEADERS`` as newline-separated+ ``Name: value`` lines and attaches them to every API request; the+ Headroom proxy uses the X-Headroom-Project header for per-project+ savings attribution. An existing user-supplied x-headroom-project+ header (any casing) always wins — we never duplicate or overwrite it,+ and any other user headers are preserved by appending.+ """+ project = _project_name_from_cwd()+ if not project:+ return+ header_line = f"{_PROJECT_HEADER_NAME}: {project}"+ existing = env.get("ANTHROPIC_CUSTOM_HEADERS")+ if existing:+ for line in existing.splitlines():+ name = line.split(":", 1)[0].strip()+ if name.lower() == _PROJECT_HEADER_NAME.lower():+ return # user override wins+ env["ANTHROPIC_CUSTOM_HEADERS"] = f"{existing}\n{header_line}"+ else:+ env["ANTHROPIC_CUSTOM_HEADERS"] = header_line++def _inject_codex_provider_config(port: int) -> None:"""Inject a Headroom model provider into Codex's config.toml.@@ -985,6 +1027,11 @@ def _inject_codex_provider_config(port: int) -> None:'name = "OpenAI via Headroom proxy"\n'f'base_url = "http://127.0.0.1:{port}/v1"\n'f"supports_websockets = true\n"+ # Per-project savings: Codex sends the header only when the mapped+ # env var (HEADROOM_PROJECT, set by `headroom wrap codex`) exists at+ # Codex runtime. Inline table keeps the key inside this section so+ # _strip_codex_headroom_blocks removes it with the rest of the block.+ f'env_http_headers = {{ "{_PROJECT_HEADER_NAME}" = "HEADROOM_PROJECT" }}\n'f"{_CODEX_END_MARKER}\n")@@ -2494,6 +2541,10 @@ def claude(else:env["ANTHROPIC_BASE_URL"] = proxy_url+ # Per-project savings attribution: tag every request with the launch+ # directory's name via X-Headroom-Project (user override wins).+ _apply_project_header_env(env)+# Issue #746: keep Claude Code's on-demand tool loading on through the# proxy so tool schemas are not eagerly materialized into local context._tool_search_value = _configure_tool_search_env(env, tool_search)@@ -2743,7 +2794,11 @@ def copilot(_copilot_default_wire_api_for_model(selected_model) if subscription else "completions")env["COPILOT_PROVIDER_TYPE"] = "openai"- env["COPILOT_PROVIDER_BASE_URL"] = f"http://127.0.0.1:{port}/v1"+ # Per-project savings: the Copilot CLI cannot send custom headers, so+ # the project rides as a /p/<name> base-URL prefix the proxy strips.+ env["COPILOT_PROVIDER_BASE_URL"] = _with_project_prefix(+ f"http://127.0.0.1:{port}/v1", _project_name_from_cwd()+ )env["COPILOT_PROVIDER_WIRE_API"] = effective_wire_apienv["COPILOT_PROVIDER_BEARER_TOKEN"] = client_bearerenv["GITHUB_COPILOT_USE_TOKEN_EXCHANGE"] = "false"@@ -2760,7 +2815,7 @@ def copilot(copilot_proxy_token = client_bearerenv_vars_display = ["COPILOT_PROVIDER_TYPE=openai",- f"COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:{port}/v1",+ f"COPILOT_PROVIDER_BASE_URL={env['COPILOT_PROVIDER_BASE_URL']}",f"COPILOT_PROVIDER_WIRE_API={effective_wire_api}",("COPILOT_AUTH_MODE=github-subscription-experimental"@@ -2787,6 +2842,7 @@ def copilot(provider_type=effective_provider_type,wire_api=wire_api,environ=env,+ project=_project_name_from_cwd(),)if not env.get("COPILOT_PROVIDER_API_KEY"):@@ -3008,6 +3064,13 @@ def codex(env, env_vars_display = _build_codex_launch_env(port, os.environ)+ # Per-project savings attribution: the injected provider config maps the+ # X-Headroom-Project header to HEADROOM_PROJECT via env_http_headers, so+ # Codex sends it only when this var is set. A user-set value wins.+ _codex_project = _project_name_from_cwd()+ if _codex_project and "HEADROOM_PROJECT" not in env:+ env["HEADROOM_PROJECT"] = _codex_project+# Inject Headroom provider into Codex config so WebSocket traffic also# routes through the proxy. Codex ignores OPENAI_BASE_URL for its WS# transport unless a custom provider declares supports_websockets = true.@@ -3119,7 +3182,9 @@ def aider(click.echo("Install aider: pip install aider-chat")raise SystemExit(1)- env, env_vars_display = _build_aider_launch_env(port, os.environ)+ env, env_vars_display = _build_aider_launch_env(+ port, os.environ, project=_project_name_from_cwd()+ )_launch_tool(binary=aider_bin,@@ -3202,7 +3267,7 @@ def cursor(returndef _print_cursor_setup() -> None:- for line in _render_cursor_setup_lines(port):+ for line in _render_cursor_setup_lines(port, project=_project_name_from_cwd()):click.echo(line)if not no_rtk:click.echo()diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.htmlindex 58a72988a..a2efe9369 100644--- a/headroom/dashboard/templates/dashboard.html+++ b/headroom/dashboard/templates/dashboard.html@@ -886,6 +886,44 @@</div></template>+ <!-- Per-Project Savings Breakdown -->+ <template x-if="Object.keys(stats.savings?.per_project || {}).length > 0">+ <div class="bg-surface rounded-lg border border-border overflow-hidden mb-6">+ <div class="px-4 py-3 border-b border-border flex justify-between items-center">+ <span class="text-sm font-medium text-gray-300">Per-Project Savings</span>+ <span class="text-xs text-gray-500">Lifetime totals — all time</span>+ </div>+ <div class="overflow-x-auto">+ <table class="w-full text-sm">+ <thead>+ <tr class="text-left text-xs text-gray-500 uppercase tracking-wide">+ <th class="px-4 py-3 font-medium">Project</th>+ <th class="px-4 py-3 font-medium text-right">Requests</th>+ <th class="px-4 py-3 font-medium text-right">Tokens Saved</th>+ <th class="px-4 py-3 font-medium text-right">Saved $</th>+ <th class="px-4 py-3 font-medium text-right">Savings %</th>+ </tr>+ </thead>+ <tbody class="divide-y divide-border">+ <template x-for="[project, info] in Object.entries(stats.savings?.per_project || {})" :key="project">+ <tr class="hover:bg-border/30 transition-colors">+ <td class="px-4 py-3">+ <span class="px-2 py-0.5 bg-border rounded text-xs" x-text="project"></span>+ </td>+ <td class="px-4 py-3 text-right font-mono" x-text="info.requests"></td>+ <td class="px-4 py-3 text-right font-mono text-accent" x-text="formatNumber(info.tokens_saved)"></td>+ <td class="px-4 py-3 text-right font-mono text-emerald-400" x-text="'$' + formatCurrency(info.compression_savings_usd || 0)"></td>+ <td class="px-4 py-3 text-right">+ <span class="text-accent font-mono" x-text="(info.savings_percent || 0).toFixed(1) + '%'"></span>+ </td>+ </tr>+ </template>+ </tbody>+ </table>+ </div>+ </div>+ </template>+<!-- Recent Requests Table (with expandable rows) --><div class="bg-surface rounded-lg border border-border overflow-hidden"><div class="px-4 py-3 border-b border-border flex justify-between items-center">diff --git a/headroom/providers/aider/runtime.py b/headroom/providers/aider/runtime.pyindex e382b282a..8ced698b4 100644--- a/headroom/providers/aider/runtime.py+++ b/headroom/providers/aider/runtime.py@@ -7,15 +7,23 @@ from collections.abc import Mappingfrom headroom.providers.claude import proxy_base_url as claude_proxy_base_urlfrom headroom.providers.codex import proxy_base_url as codex_proxy_base_url+from headroom.proxy.project_context import with_project_prefixdef build_launch_env(- port: int, environ: Mapping[str, str] | None = None+ port: int,+ environ: Mapping[str, str] | None = None,+ project: str | None = None,) -> tuple[dict[str, str], list[str]]:- """Build environment variables for Aider through the local proxy."""+ """Build environment variables for Aider through the local proxy.++ ``project`` (the wrap launch directory) is encoded as a ``/p/<name>``+ base-URL prefix because aider cannot send custom headers; the proxy+ strips it and attributes savings per project.+ """env = dict(environ or os.environ)- openai_base_url = codex_proxy_base_url(port)- anthropic_base_url = claude_proxy_base_url(port)+ openai_base_url = with_project_prefix(codex_proxy_base_url(port), project)+ anthropic_base_url = with_project_prefix(claude_proxy_base_url(port), project)env["OPENAI_API_BASE"] = openai_base_urlenv["ANTHROPIC_BASE_URL"] = anthropic_base_urlreturn env, [diff --git a/headroom/providers/copilot/wrap.py b/headroom/providers/copilot/wrap.pyindex cd5cfe313..672e50954 100644--- a/headroom/providers/copilot/wrap.py+++ b/headroom/providers/copilot/wrap.py@@ -11,6 +11,8 @@ from typing import Anyimport click+from headroom.proxy.project_context import with_project_prefix+def resolve_provider_type(backend: str | None, provider_type: str, environ: Mapping[str, str] | None = None@@ -113,8 +115,14 @@ def build_launch_env(provider_type: str,wire_api: str | None,environ: Mapping[str, str] | None = None,+ project: str | None = None,) -> tuple[dict[str, str], list[str]]:- """Build the Copilot BYOK environment for the selected provider type."""+ """Build the Copilot BYOK environment for the selected provider type.++ ``project`` (the wrap launch directory) is encoded as a ``/p/<name>``+ base-URL prefix because the Copilot CLI cannot send custom headers; the+ proxy strips it and attributes savings per project.+ """# Distinguish "caller passed nothing" (use os.environ) from "caller# explicitly passed an empty dict" (start fresh — the test/CLI is in# charge of which keys to seed). The previous `environ or os.environ`@@ -129,7 +137,7 @@ def build_launch_env(env["COPILOT_PROVIDER_API_KEY"] = keyif provider_type == "anthropic":- base_url = f"http://127.0.0.1:{port}"+ base_url = with_project_prefix(f"http://127.0.0.1:{port}", project)env["COPILOT_PROVIDER_BASE_URL"] = base_urlreturn env, ["COPILOT_PROVIDER_TYPE=anthropic",@@ -137,7 +145,7 @@ def build_launch_env(]effective_wire_api = wire_api or "completions"- base_url = f"http://127.0.0.1:{port}/v1"+ base_url = with_project_prefix(f"http://127.0.0.1:{port}/v1", project)env["COPILOT_PROVIDER_BASE_URL"] = base_urlenv["COPILOT_PROVIDER_WIRE_API"] = effective_wire_apireturn env, [diff --git a/headroom/providers/cursor/runtime.py b/headroom/providers/cursor/runtime.pyindex 7a2f33135..b67f36456 100644--- a/headroom/providers/cursor/runtime.py+++ b/headroom/providers/cursor/runtime.py@@ -6,6 +6,7 @@ from dataclasses import dataclassfrom headroom.providers.claude import proxy_base_url as claude_proxy_base_urlfrom headroom.providers.codex import proxy_base_url as codex_proxy_base_url+from headroom.proxy.project_context import with_project_prefix@dataclass(frozen=True)@@ -16,18 +17,23 @@ class CursorProxyTargets:anthropic_base_url: str-def build_proxy_targets(port: int) -> CursorProxyTargets:- """Build the local proxy URLs shown to Cursor users."""+def build_proxy_targets(port: int, project: str | None = None) -> CursorProxyTargets:+ """Build the local proxy URLs shown to Cursor users.++ ``project`` (the wrap launch directory) is encoded as a ``/p/<name>``+ base-URL prefix because Cursor cannot send custom headers; the proxy+ strips it and attributes savings per project.+ """return CursorProxyTargets(- openai_base_url=codex_proxy_base_url(port),- anthropic_base_url=claude_proxy_base_url(port),+ openai_base_url=with_project_prefix(codex_proxy_base_url(port), project),+ anthropic_base_url=with_project_prefix(claude_proxy_base_url(port), project),)-def render_setup_lines(port: int) -> list[str]:+def render_setup_lines(port: int, project: str | None = None) -> list[str]:"""Render the Cursor setup instructions for the local proxy."""- targets = build_proxy_targets(port)- return [+ targets = build_proxy_targets(port, project)+ lines = [" Headroom proxy is running. Configure Cursor:",""," For OpenAI models:",@@ -42,3 +48,11 @@ def render_setup_lines(port: int) -> list[str]:" Settings > Models > OpenAI API Key > Override OpenAI Base URL",f" Set to: {targets.openai_base_url}",]+ if project:+ lines += [+ "",+ f" Dashboard savings will be attributed to project '{project}'",+ " (the directory this command was run from). Re-run from another",+ " project directory to get that project's URL.",+ ]+ return linesdiff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 80802a2b8..be9b0a85a 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -47,6 +47,7 @@ from headroom.proxy.auth_mode import classify_auth_mode, classify_clientfrom headroom.proxy.compression_decision import CompressionDecisionfrom headroom.proxy.cost import _summarize_transformsfrom headroom.proxy.outcome import RequestOutcome+from headroom.proxy.project_context import classify_project, set_current_projectlogger = logging.getLogger("headroom.proxy")@@ -3381,6 +3382,9 @@ class OpenAIHandlerMixin:# Identify the WS harness before downstream auth/header rewrites.# Captured in closure so per-turn RequestOutcome can stamp it.client = classify_client(ws_headers)+ # WS sessions bypass the HTTP middleware, so bind the project here;+ # per-turn outcome emission inside this task inherits the context.+ set_current_project(classify_project(ws_headers))_ws_url_obj = getattr(websocket, "url", None)_ws_url = str(_ws_url_obj) if _ws_url_obj is not None else ""_ws_path = getattr(_ws_url_obj, "path", "") if _ws_url_obj is not None else ""diff --git a/headroom/proxy/outcome.py b/headroom/proxy/outcome.pyindex 37f5d2643..ebd17516d 100644--- a/headroom/proxy/outcome.py+++ b/headroom/proxy/outcome.py@@ -129,6 +129,7 @@ class RequestOutcome:request_messages: list[dict[str, Any]] | None = Nonetags: dict[str, str] = field(default_factory=dict)client: str | None = None+ project: str | None = None# ── Derived (computed once, no caching needed — properties are cheap) ─@@ -303,6 +304,11 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:"""from headroom.proxy.cost import _summarize_transformsfrom headroom.proxy.models import RequestLog+ from headroom.proxy.project_context import get_current_project++ # Project attribution: explicit outcome field wins, else the value the+ # HTTP middleware / WS accept captured from ``X-Headroom-Project``.+ project = outcome.project or get_current_project()# 1. Prometheus / SavingsTracker.await handler.metrics.record_request(@@ -323,6 +329,7 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:cache_write_1h_tokens=outcome.cache_write_1h_tokens,uncached_input_tokens=outcome.uncached_input_tokens,attempted_input_tokens=outcome.attempted_input_tokens,+ project=project,)# 2. Cost tracker (optional).@@ -349,6 +356,8 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:log_tags = dict(outcome.tags)if outcome.client:log_tags["client"] = outcome.client+ if project:+ log_tags["project"] = projectrequest_logger.log(RequestLog(request_id=outcome.request_id,diff --git a/headroom/proxy/project_context.py b/headroom/proxy/project_context.pynew file mode 100644index 000000000..fe48a7163--- /dev/null+++ b/headroom/proxy/project_context.py@@ -0,0 +1,106 @@+"""Per-request project attribution for the proxy.++``headroom wrap`` launches agents with an ``X-Headroom-Project`` header+(via ``ANTHROPIC_CUSTOM_HEADERS`` for Claude Code and ``env_http_headers``+for Codex) naming the project directory the agent is working in. The proxy+captures that header once per request — in the HTTP middleware for regular+requests and at the WebSocket accept for Codex responses-WS sessions —+into a :mod:`contextvars` variable, so the outcome funnel can attribute+savings to a project without threading a parameter through every handler.++The value is sanitized (printable characters only, length-capped) before it+is stored; an absent or unusable header simply leaves attribution off for+that request, matching pre-feature behavior.+"""++from __future__ import annotations++from collections.abc import Mapping, MutableMapping+from contextvars import ContextVar+from typing import Any+from urllib.parse import quote, unquote, urlsplit, urlunsplit++from headroom.proxy.savings_tracker import sanitize_project_name++PROJECT_HEADER = "x-headroom-project"+PROJECT_PATH_PREFIX = "/p/"++_current_project: ContextVar[str | None] = ContextVar("headroom_current_project", default=None)+++def classify_project(headers: Mapping[str, Any] | Any) -> str | None:+ """Extract a sanitized project name from request headers, if present."""+ get = getattr(headers, "get", None)+ if get is None:+ return None+ value = get(PROJECT_HEADER) or get("X-Headroom-Project")+ return sanitize_project_name(value)+++def set_current_project(project: str | None) -> None:+ """Bind the active request's project for downstream outcome recording."""+ _current_project.set(sanitize_project_name(project))+++def get_current_project() -> str | None:+ """Project bound to the current request context, or ``None``."""+ return _current_project.get()+++def split_project_path(path: str) -> tuple[str | None, str]:+ """Split ``/p/<name>/rest`` into ``(name, /rest)``.++ Clients that cannot send custom headers (aider, Copilot BYOK, Cursor)+ are pointed at a project-prefixed base URL instead; the first path+ segment after ``/p/`` is the URL-encoded project name. Returns+ ``(None, path)`` unchanged when the prefix is absent or unusable.+ """+ if not path.startswith(PROJECT_PATH_PREFIX):+ return None, path+ remainder = path[len(PROJECT_PATH_PREFIX) :]+ segment, sep, rest = remainder.partition("/")+ project = sanitize_project_name(unquote(segment)) if segment else None+ if project is None:+ return None, path+ return project, ("/" + rest) if sep else "/"+++def strip_project_path_prefix(scope: MutableMapping[str, Any]) -> str | None:+ """Strip a ``/p/<name>`` prefix from an ASGI scope, returning the name.++ Mutates ``scope["path"]`` (and ``raw_path``) so routing sees the+ canonical path. Must run before anything caches the request URL.+ """+ project, stripped = split_project_path(scope.get("path", ""))+ if project is not None:+ scope["path"] = stripped+ if "raw_path" in scope:+ scope["raw_path"] = quote(stripped).encode("ascii")+ return project+++def with_project_prefix(base_url: str, project: str | None) -> str:+ """Insert ``/p/<name>`` ahead of the path of a local proxy base URL.++ Producer-side counterpart of :func:`split_project_path`, used by+ ``headroom wrap`` for clients that cannot send custom headers.+ Returns ``base_url`` unchanged when the project name is unusable.+ """+ name = sanitize_project_name(project)+ if name is None:+ return base_url+ parts = urlsplit(base_url)+ prefixed = f"{PROJECT_PATH_PREFIX}{quote(name, safe='')}{parts.path}"+ return urlunsplit(parts._replace(path=prefixed.rstrip("/")))+++__all__ = [+ "PROJECT_HEADER",+ "PROJECT_PATH_PREFIX",+ "classify_project",+ "get_current_project",+ "set_current_project",+ "split_project_path",+ "strip_project_path_prefix",+ "with_project_prefix",+]diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.pyindex edfce23c9..a1bf43019 100644--- a/headroom/proxy/prometheus_metrics.py+++ b/headroom/proxy/prometheus_metrics.py@@ -562,6 +562,7 @@ class PrometheusMetrics:cache_write_1h_tokens: int = 0,uncached_input_tokens: int = 0,attempted_input_tokens: int = 0,+ project: str | None = None,):"""Record metrics for a request."""async with self._lock:@@ -649,6 +650,7 @@ class PrometheusMetrics:input_tokens=input_tokens,tokens_saved=tokens_saved,provider=provider,+ project=project,cache_read_tokens=cache_read_tokens,cache_write_tokens=cache_write_tokens,uncached_input_tokens=uncached_input_tokens,diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.pyindex 30e6deb8f..6a7ebfba2 100644--- a/headroom/proxy/savings_tracker.py+++ b/headroom/proxy/savings_tracker.py@@ -26,8 +26,10 @@ logger = logging.getLogger(__name__)HEADROOM_SAVINGS_PATH_ENV_VAR = _paths.HEADROOM_SAVINGS_PATH_ENVDEFAULT_SAVINGS_DIR = ".headroom"DEFAULT_SAVINGS_FILE = "proxy_savings.json"-SCHEMA_VERSION = 2+SCHEMA_VERSION = 3DEFAULT_MAX_HISTORY_POINTS = 5000+DEFAULT_MAX_PROJECTS = 50+PROJECT_NAME_MAX_LENGTH = 128DEFAULT_MAX_HISTORY_AGE_DAYS = 365DEFAULT_MAX_RESPONSE_HISTORY_POINTS = 500DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES = 60@@ -287,6 +289,64 @@ def _empty_display_session() -> dict[str, Any]:}+def sanitize_project_name(value: Any) -> str | None:+ """Normalize a client-supplied project name; ``None`` when unusable.++ Strips control characters, trims whitespace, and caps length so a+ misbehaving client cannot bloat the persisted state or the dashboard.+ """+ if not isinstance(value, str):+ return None+ cleaned = "".join(ch for ch in value if ch.isprintable()).strip()+ if not cleaned:+ return None+ return cleaned[:PROJECT_NAME_MAX_LENGTH]+++def _empty_project_entry() -> dict[str, Any]:+ return {+ "requests": 0,+ "tokens_saved": 0,+ "compression_savings_usd": 0.0,+ "total_input_tokens": 0,+ "total_input_cost_usd": 0.0,+ "last_activity_at": None,+ }+++def _normalize_projects(raw: Any) -> dict[str, dict[str, Any]]:+ if not isinstance(raw, dict):+ return {}+ projects: dict[str, dict[str, Any]] = {}+ for name, entry in raw.items():+ cleaned_name = sanitize_project_name(name)+ if cleaned_name is None or not isinstance(entry, dict):+ continue+ normalized = _empty_project_entry()+ normalized["requests"] = _coerce_int(entry.get("requests"))+ normalized["tokens_saved"] = _coerce_int(entry.get("tokens_saved"))+ normalized["compression_savings_usd"] = round(+ _coerce_float(entry.get("compression_savings_usd")), 6+ )+ normalized["total_input_tokens"] = _coerce_int(entry.get("total_input_tokens"))+ normalized["total_input_cost_usd"] = round(+ _coerce_float(entry.get("total_input_cost_usd")), 6+ )+ last_activity = _parse_timestamp(entry.get("last_activity_at"))+ normalized["last_activity_at"] = _to_utc_iso(last_activity) if last_activity else None+ projects[cleaned_name] = normalized+ if len(projects) > DEFAULT_MAX_PROJECTS:+ # Oversized persisted maps (hand-edited or future versions) would+ # otherwise shrink only one entry per recorded request.+ kept = sorted(+ projects.items(),+ key=lambda item: (item[1]["tokens_saved"], item[1]["last_activity_at"] or ""),+ reverse=True,+ )[:DEFAULT_MAX_PROJECTS]+ projects = dict(kept)+ return projects++def _normalize_display_session(entry: Any) -> dict[str, Any]:if not isinstance(entry, dict):return _empty_display_session()@@ -427,6 +487,7 @@ class SavingsTracker:input_tokens: int,tokens_saved: int,provider: str | None = None,+ project: str | None = None,cache_read_tokens: int = 0,cache_write_tokens: int = 0,uncached_input_tokens: int = 0,@@ -526,6 +587,16 @@ class SavingsTracker:if session.get("started_at") is None:session["started_at"] = session["last_activity_at"]+ self._record_project_locked(+ project,+ timestamp_dt=timestamp_dt,+ requests_delta=1,+ tokens_saved_delta=delta_tokens_saved,+ savings_usd_delta=delta_savings_usd,+ input_tokens_delta=delta_input_tokens,+ input_cost_usd_delta=delta_input_cost_usd,+ )+if delta_tokens_saved > 0:self._state["history"].append({@@ -542,6 +613,67 @@ class SavingsTracker:self._save_locked()return True+ def _record_project_locked(+ self,+ project: str | None,+ *,+ timestamp_dt: datetime,+ requests_delta: int = 0,+ tokens_saved_delta: int = 0,+ savings_usd_delta: float = 0.0,+ input_tokens_delta: int = 0,+ input_cost_usd_delta: float = 0.0,+ ) -> None:+ """Accumulate per-project savings. Caller must hold ``self._lock``.++ Unattributed traffic (``project`` missing or unusable) is skipped so+ existing aggregate behavior is unchanged. The map is capped at+ ``DEFAULT_MAX_PROJECTS`` entries, evicting the smallest/oldest bucket.+ """+ name = sanitize_project_name(project)+ if name is None:+ return+ projects: dict[str, dict[str, Any]] = self._state.setdefault("projects", {})+ entry = projects.setdefault(name, _empty_project_entry())+ entry["requests"] += max(requests_delta, 0)+ entry["tokens_saved"] += max(tokens_saved_delta, 0)+ entry["compression_savings_usd"] = round(+ entry["compression_savings_usd"] + max(savings_usd_delta, 0.0), 6+ )+ entry["total_input_tokens"] += max(input_tokens_delta, 0)+ entry["total_input_cost_usd"] = round(+ entry["total_input_cost_usd"] + max(input_cost_usd_delta, 0.0), 6+ )+ entry["last_activity_at"] = _to_utc_iso(timestamp_dt)+ if len(projects) > DEFAULT_MAX_PROJECTS:+ evict = min(+ (key for key in projects if key != name),+ key=lambda key: (+ projects[key]["tokens_saved"],+ projects[key]["last_activity_at"] or "",+ ),+ )+ del projects[evict]++ def _projects_snapshot_locked(self) -> dict[str, dict[str, Any]]:+ """Per-project stats with a derived ``savings_percent``, sorted by savings."""+ projects = self._state.get("projects", {})+ ranked = sorted(+ projects.items(),+ key=lambda item: item[1]["tokens_saved"],+ reverse=True,+ )+ result: dict[str, dict[str, Any]] = {}+ for name, entry in ranked:+ view = dict(entry)+ total_before = entry["tokens_saved"] + entry["total_input_tokens"]+ view["savings_percent"] = round(+ (entry["tokens_saved"] / total_before * 100) if total_before > 0 else 0.0,+ 2,+ )+ result[name] = view+ return result+def stats_preview(self, recent_points: int = 20) -> dict[str, Any]:"""Return a compact preview for `/stats`."""snapshot = self.snapshot()@@ -554,6 +686,8 @@ class SavingsTracker:"history_points": len(snapshot["history"]),"recent_history": snapshot["history"][-recent_points:],"retention": snapshot["retention"],+ "projects": snapshot["projects"],+ "projects_limit": DEFAULT_MAX_PROJECTS,}def history_response(self, history_mode: str = "compact") -> dict[str, Any]:@@ -582,6 +716,7 @@ class SavingsTracker:"available_series": ["history", *series.keys()],},"retention": snapshot["retention"],+ "projects": snapshot["projects"],"history_summary": {"mode": history_mode,"stored_points": len(raw_history),@@ -645,6 +780,7 @@ class SavingsTracker:"max_history_age_days": self._max_history_age_days,"max_response_history_points": self._max_response_history_points,},+ "projects": self._projects_snapshot_locked(),}def _default_state(self) -> dict[str, Any]:@@ -659,6 +795,7 @@ class SavingsTracker:},"display_session": _empty_display_session(),"history": [],+ "projects": {},}def _load_state(self) -> dict[str, Any]:@@ -731,6 +868,7 @@ class SavingsTracker:},"display_session": _normalize_display_session(raw.get("display_session")),"history": normalized_history,+ "projects": _normalize_projects(raw.get("projects")),}if normalized_history:@@ -822,6 +960,7 @@ class SavingsTracker:"lifetime": self._state["lifetime"],"display_session": self._state["display_session"],"history": self._state["history"],+ "projects": self._state.get("projects", {}),}json_data = json.dumps(payload, indent=2)diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 613fe6fb6..afac7fa9d 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -139,6 +139,11 @@ from headroom.proxy.modes import (is_token_mode,normalize_proxy_mode,)+from headroom.proxy.project_context import (+ classify_project,+ set_current_project,+ strip_project_path_prefix,+)from headroom.proxy.prometheus_metrics import PrometheusMetrics # noqa: F401from headroom.proxy.rate_limiter import TokenBucketRateLimiter # noqa: F401from headroom.proxy.request_logger import RequestLogger # noqa: F401@@ -1709,10 +1714,17 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:async def _record_headroom_stack(request, call_next):started = time.perf_counter()inbound_id = f"inbound-{time.time_ns()}"+ # Project attribution: an explicit X-Headroom-Project header wins+ # (claude/codex wraps); otherwise a /p/<name> base-URL prefix (aider,+ # Copilot BYOK, Cursor — clients that cannot send custom headers).+ # The prefix strip mutates the scope, so it must happen before+ # request.url is first accessed (Starlette caches the URL).+ prefix_project = strip_project_path_prefix(request.scope)path = request.url.pathmethod = request.methodquery = request.url.queryheaders = dict(request.headers.items())+ set_current_project(classify_project(headers) or prefix_project)client = getattr(request, "client", None)client_addr = ""if client is not None:@@ -2024,6 +2036,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"summary": summary,"savings": {"total_tokens": total_tokens_all_layers,+ "per_project": persistent_savings.get("projects", {}),"by_layer": {"cli_filtering": {"tool": cli_filtering_tool,diff --git a/tests/test_cli/test_wrap_aider.py b/tests/test_cli/test_wrap_aider.pyindex 83a6486bb..9ac91fdfe 100644--- a/tests/test_cli/test_wrap_aider.py+++ b/tests/test_cli/test_wrap_aider.py@@ -4,6 +4,7 @@ from __future__ import annotationsfrom pathlib import Pathfrom unittest.mock import patch+from urllib.parse import quoteimport pytestfrom click.testing import CliRunner@@ -11,6 +12,11 @@ from click.testing import CliRunnerfrom headroom.cli.main import main+def _expected_project_prefix() -> str:+ """The /p/<name> prefix the wrap now embeds (launch-directory basename)."""+ return f"/p/{quote(Path.cwd().name, safe='')}"++@pytest.fixturedef runner() -> CliRunner:return CliRunner()@@ -32,8 +38,8 @@ def test_wrap_aider_sets_provider_envs(assert result.exit_code == 0, result.outputenv = captured["env"]assert isinstance(env, dict)- assert env["OPENAI_API_BASE"] == "http://127.0.0.1:8787/v1"- assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:8787"+ assert env["OPENAI_API_BASE"] == f"http://127.0.0.1:8787{_expected_project_prefix()}/v1"+ assert env["ANTHROPIC_BASE_URL"] == f"http://127.0.0.1:8787{_expected_project_prefix()}"assert captured["tool_label"] == "AIDER"assert captured["agent_type"] == "aider"assert captured["args"] == ("--model", "gpt-4o")diff --git a/tests/test_cli/test_wrap_codex.py b/tests/test_cli/test_wrap_codex.pyindex f6aedefd2..a0f3f813e 100644--- a/tests/test_cli/test_wrap_codex.py+++ b/tests/test_cli/test_wrap_codex.py@@ -741,3 +741,64 @@ def test_unwrap_codex_preserves_unrelated_sections(assert result.exit_code == 0, result.outputrestored = config_file.read_text()assert restored == original+++# ---------------------------------------------------------------------------+# Per-project savings: env_http_headers in the injected provider block+# ---------------------------------------------------------------------------+++class TestCodexProjectHeaderConfig:+ """The injected provider maps X-Headroom-Project to HEADROOM_PROJECT.++ Codex's ``env_http_headers`` sends a header only when the mapped env var+ is set at Codex runtime, so `headroom wrap codex` exports+ ``HEADROOM_PROJECT`` and the proxy attributes savings per project.+ """++ def test_inject_writes_env_http_headers_mapping(+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+ ) -> None:+ _set_test_home(monkeypatch, tmp_path)++ wrap_mod._inject_codex_provider_config(8787)++ content = (tmp_path / ".codex" / "config.toml").read_text()+ assert 'env_http_headers = { "X-Headroom-Project" = "HEADROOM_PROJECT" }' in content++ def test_env_http_headers_inside_provider_section(+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+ ) -> None:+ """The mapping must live inside [model_providers.headroom], before+ the closing marker, so it applies to the Headroom provider."""+ _set_test_home(monkeypatch, tmp_path)++ wrap_mod._inject_codex_provider_config(8787)++ content = (tmp_path / ".codex" / "config.toml").read_text()+ section_start = content.index("[model_providers.headroom]")+ mapping_pos = content.index("env_http_headers")+ end_marker_pos = content.index(wrap_mod._CODEX_END_MARKER, section_start)+ assert section_start < mapping_pos < end_marker_pos++ def test_strip_removes_block_with_env_http_headers(+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+ ) -> None:+ """_strip_codex_headroom_blocks removes the whole injected block,+ including the new env_http_headers line, leaving user content."""+ _set_test_home(monkeypatch, tmp_path)+ config_dir = tmp_path / ".codex"+ config_dir.mkdir()+ config_file = config_dir / "config.toml"+ original = '[profiles.default]\nmodel = "gpt-4o"\n'+ config_file.write_text(original)++ wrap_mod._inject_codex_provider_config(8787)+ wrapped = config_file.read_text()+ assert "env_http_headers" in wrapped++ cleaned = wrap_mod._strip_codex_headroom_blocks(wrapped)+ assert "env_http_headers" not in cleaned+ assert "X-Headroom-Project" not in cleaned+ assert "[model_providers.headroom]" not in cleaned+ assert 'model = "gpt-4o"' in cleaneddiff --git a/tests/test_cli/test_wrap_copilot.py b/tests/test_cli/test_wrap_copilot.pyindex 0e44977b7..cc2f0c173 100644--- a/tests/test_cli/test_wrap_copilot.py+++ b/tests/test_cli/test_wrap_copilot.py@@ -8,6 +8,7 @@ import sysimport typesfrom pathlib import Pathfrom unittest.mock import patch+from urllib.parse import quoteimport clickimport pytest@@ -16,6 +17,11 @@ from click.testing import CliRunnerfrom headroom.copilot_auth import DEFAULT_API_URL+def _expected_project_prefix() -> str:+ """The /p/<name> prefix the wrap now embeds (launch-directory basename)."""+ return f"/p/{quote(Path.cwd().name, safe='')}"++@pytest.fixturedef runner() -> CliRunner:return CliRunner()@@ -98,7 +104,7 @@ def test_wrap_copilot_auto_anthropic_injects_instructions(env = captured["env"]assert isinstance(env, dict)assert env["COPILOT_PROVIDER_TYPE"] == "anthropic"- assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787"+ assert env["COPILOT_PROVIDER_BASE_URL"] == f"http://127.0.0.1:8787{_expected_project_prefix()}"assert "COPILOT_PROVIDER_WIRE_API" not in envassert captured["agent_type"] == "copilot"assert captured["tool_label"] == "COPILOT"@@ -145,7 +151,9 @@ def test_wrap_copilot_openai_backend_sets_completions_env(env = captured["env"]assert isinstance(env, dict)assert env["COPILOT_PROVIDER_TYPE"] == "openai"- assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"+ assert env["COPILOT_PROVIDER_BASE_URL"] == (+ f"http://127.0.0.1:8787{_expected_project_prefix()}/v1"+ )assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"assert captured["backend"] == "anyllm"assert captured["anyllm_provider"] == "groq"@@ -181,7 +189,9 @@ def test_wrap_copilot_auto_detects_running_proxy_backend(env = captured["env"]assert isinstance(env, dict)assert env["COPILOT_PROVIDER_TYPE"] == "openai"- assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"+ assert env["COPILOT_PROVIDER_BASE_URL"] == (+ f"http://127.0.0.1:8787{_expected_project_prefix()}/v1"+ )assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"@@ -210,7 +220,9 @@ def test_wrap_copilot_prefers_existing_oauth_session(env = captured["env"]assert isinstance(env, dict)assert env["COPILOT_PROVIDER_TYPE"] == "openai"- assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"+ assert env["COPILOT_PROVIDER_BASE_URL"] == (+ f"http://127.0.0.1:8787{_expected_project_prefix()}/v1"+ )assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"assert env["COPILOT_PROVIDER_BEARER_TOKEN"] == "gho-existing"assert env["GITHUB_COPILOT_API_URL"] == DEFAULT_API_URL@@ -249,7 +261,9 @@ def test_wrap_copilot_subscription_uses_github_auth_without_provider_key(env = captured["env"]assert isinstance(env, dict)assert env["COPILOT_PROVIDER_TYPE"] == "openai"- assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"+ assert env["COPILOT_PROVIDER_BASE_URL"] == (+ f"http://127.0.0.1:8787{_expected_project_prefix()}/v1"+ )assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"assert env["COPILOT_PROVIDER_BEARER_TOKEN"] == "gho-existing"assert "COPILOT_PROVIDER_API_KEY" not in envdiff --git a/tests/test_cli/test_wrap_helpers.py b/tests/test_cli/test_wrap_helpers.pyindex cc3b9b12f..fbb56460d 100644--- a/tests/test_cli/test_wrap_helpers.py+++ b/tests/test_cli/test_wrap_helpers.py@@ -405,3 +405,114 @@ def test_run_proxy_only_watcher_calls_cleanup_on_finally(inv = runner.invoke(_cmd)assert inv.exit_code == 1assert cleanup_calls["n"] >= 1, "cleanup must run via the finally block"+++# ---------------------------------------------------------------------------+# _project_name_from_cwd / _apply_project_header_env — per-project savings+# header injection for `headroom wrap claude` (issue: per-project savings).+# ---------------------------------------------------------------------------+++class TestApplyProjectHeaderEnv:+ """X-Headroom-Project injection into ANTHROPIC_CUSTOM_HEADERS."""++ def test_sets_header_from_cwd_basename(+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+ ) -> None:+ project_dir = tmp_path / "my-project"+ project_dir.mkdir()+ monkeypatch.chdir(project_dir)++ env: dict[str, str] = {}+ wrap_mod._apply_project_header_env(env)++ assert env["ANTHROPIC_CUSTOM_HEADERS"] == "X-Headroom-Project: my-project"++ def test_appends_to_existing_custom_headers(+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+ ) -> None:+ project_dir = tmp_path / "proj"+ project_dir.mkdir()+ monkeypatch.chdir(project_dir)++ env = {"ANTHROPIC_CUSTOM_HEADERS": "X-Custom-Trace: abc123"}+ wrap_mod._apply_project_header_env(env)++ # User header preserved verbatim, ours appended on a new line.+ assert env["ANTHROPIC_CUSTOM_HEADERS"] == (+ "X-Custom-Trace: abc123\nX-Headroom-Project: proj"+ )++ @pytest.mark.parametrize(+ "user_value",+ [+ "X-Headroom-Project: their-name",+ "x-headroom-project: their-name",+ "X-HEADROOM-PROJECT: their-name",+ "X-Other: 1\nx-Headroom-Project: their-name",+ ],+ )+ def test_existing_project_header_wins_case_insensitive(+ self,+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+ user_value: str,+ ) -> None:+ project_dir = tmp_path / "proj"+ project_dir.mkdir()+ monkeypatch.chdir(project_dir)++ env = {"ANTHROPIC_CUSTOM_HEADERS": user_value}+ wrap_mod._apply_project_header_env(env)++ # Untouched: no duplicate header, user override wins.+ assert env["ANTHROPIC_CUSTOM_HEADERS"] == user_value++ @pytest.mark.parametrize(+ "user_value",+ [+ "X-Headroom-Project-Id: other",+ "X-Trace: mentions x-headroom-project in the value",+ ],+ )+ def test_similar_header_names_do_not_suppress_injection(+ self,+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+ user_value: str,+ ) -> None:+ project_dir = tmp_path / "proj"+ project_dir.mkdir()+ monkeypatch.chdir(project_dir)++ env = {"ANTHROPIC_CUSTOM_HEADERS": user_value}+ wrap_mod._apply_project_header_env(env)++ # Only an exact header-name match counts as a user override.+ assert env["ANTHROPIC_CUSTOM_HEADERS"] == (f"{user_value}\nX-Headroom-Project: proj")++ def test_empty_cwd_name_sets_nothing(self, monkeypatch: pytest.MonkeyPatch) -> None:+ """A degenerate cwd (e.g. filesystem root → empty basename) is a no-op."""+ monkeypatch.setattr(wrap_mod.Path, "cwd", classmethod(lambda cls: Path("/")))++ env: dict[str, str] = {}+ wrap_mod._apply_project_header_env(env)++ assert "ANTHROPIC_CUSTOM_HEADERS" not in env++ def test_whitespace_only_cwd_name_sets_nothing(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(wrap_mod.Path, "cwd", classmethod(lambda cls: Path("/tmp/ ")))++ env: dict[str, str] = {}+ wrap_mod._apply_project_header_env(env)++ assert "ANTHROPIC_CUSTOM_HEADERS" not in env++ def test_project_name_from_cwd_returns_basename(+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+ ) -> None:+ project_dir = tmp_path / "vibe-headroom"+ project_dir.mkdir()+ monkeypatch.chdir(project_dir)++ assert wrap_mod._project_name_from_cwd() == "vibe-headroom"diff --git a/tests/test_provider_aider.py b/tests/test_provider_aider.pyindex 542edab62..08a0d1d22 100644--- a/tests/test_provider_aider.py+++ b/tests/test_provider_aider.py@@ -31,3 +31,21 @@ def test_aider_build_install_env_returns_only_persistent_proxy_variables() -> No"OPENAI_API_BASE": "http://127.0.0.1:8787/v1","ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",}+++def test_aider_build_launch_env_applies_project_path_prefix() -> None:+ env, lines = build_launch_env(port=9999, environ={}, project="my repo")++ assert env["OPENAI_API_BASE"] == "http://127.0.0.1:9999/p/my%20repo/v1"+ assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999/p/my%20repo"+ assert lines == [+ "OPENAI_API_BASE=http://127.0.0.1:9999/p/my%20repo/v1",+ "ANTHROPIC_BASE_URL=http://127.0.0.1:9999/p/my%20repo",+ ]+++def test_aider_build_launch_env_ignores_unusable_project() -> None:+ env, _lines = build_launch_env(port=9999, environ={}, project=" ")++ assert env["OPENAI_API_BASE"] == "http://127.0.0.1:9999/v1"+ assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999"diff --git a/tests/test_provider_copilot_wrap.py b/tests/test_provider_copilot_wrap.pyindex 720386070..3defacfa4 100644--- a/tests/test_provider_copilot_wrap.py+++ b/tests/test_provider_copilot_wrap.py@@ -164,3 +164,32 @@ def test_model_configured_detects_env_and_cli_variants() -> None:assert model_configured(("--model", "gpt-4o"), {}) is Trueassert model_configured(("--model=gpt-4o",), {}) is Trueassert model_configured(("--other", "value"), {}) is False+++def test_build_launch_env_applies_project_path_prefix() -> None:+ anthropic_env, _ = build_launch_env(+ port=8787,+ provider_type="anthropic",+ wire_api=None,+ environ={"ANTHROPIC_API_KEY": "sk-ant-test"},+ project="api server",+ )+ openai_env, openai_lines = build_launch_env(+ port=8787,+ provider_type="openai",+ wire_api=None,+ environ={"OPENAI_API_KEY": "sk-proj-test"},+ project="api server",+ )++ assert anthropic_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/p/api%20server"+ assert openai_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/p/api%20server/v1"+ assert "COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:8787/p/api%20server/v1" in openai_lines++ plain_env, _ = build_launch_env(+ port=8787,+ provider_type="openai",+ wire_api=None,+ environ={"OPENAI_API_KEY": "sk-proj-test"},+ )+ assert plain_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"diff --git a/tests/test_provider_cursor.py b/tests/test_provider_cursor.pyindex b16671524..3652e21dd 100644--- a/tests/test_provider_cursor.py+++ b/tests/test_provider_cursor.py@@ -28,3 +28,21 @@ def test_cursor_build_install_env_returns_both_proxy_urls() -> None:"OPENAI_BASE_URL": "http://127.0.0.1:7654/v1","ANTHROPIC_BASE_URL": "http://127.0.0.1:7654",}+++def test_cursor_proxy_targets_apply_project_path_prefix() -> None:+ targets = build_proxy_targets(9999, project="frontend")++ assert targets.openai_base_url == "http://127.0.0.1:9999/p/frontend/v1"+ assert targets.anthropic_base_url == "http://127.0.0.1:9999/p/frontend"+++def test_cursor_setup_lines_mention_project_attribution() -> None:+ lines = render_setup_lines(8787, project="frontend")+ joined = "\n".join(lines)++ assert "http://127.0.0.1:8787/p/frontend/v1" in joined+ assert "attributed to project 'frontend'" in joined++ plain = "\n".join(render_setup_lines(8787))+ assert "attributed" not in plaindiff --git a/tests/test_proxy_project_savings.py b/tests/test_proxy_project_savings.pynew file mode 100644index 000000000..086819f59--- /dev/null+++ b/tests/test_proxy_project_savings.py@@ -0,0 +1,341 @@+"""Tests for per-project savings attribution (X-Headroom-Project)."""++import asyncio+import json++import pytest++pytest.importorskip("fastapi")+from fastapi.testclient import TestClient # noqa: E402++from headroom.proxy.outcome import RequestOutcome, emit_request_outcome # noqa: E402+from headroom.proxy.project_context import ( # noqa: E402+ classify_project,+ get_current_project,+ set_current_project,+ split_project_path,+ with_project_prefix,+)+from headroom.proxy.savings_tracker import ( # noqa: E402+ DEFAULT_MAX_PROJECTS,+ SavingsTracker,+ sanitize_project_name,+)+from headroom.proxy.server import ProxyConfig, create_app # noqa: E402++# ---------------------------------------------------------------------------+# sanitize_project_name / classify_project+# ---------------------------------------------------------------------------+++def test_sanitize_project_name_normalizes_and_caps():+ assert sanitize_project_name(" api-server ") == "api-server"+ assert sanitize_project_name("a" * 300) == "a" * 128+ assert sanitize_project_name("x\x00\x1by") == "xy"+ assert sanitize_project_name("") is None+ assert sanitize_project_name(" ") is None+ assert sanitize_project_name(None) is None+ assert sanitize_project_name(42) is None+++def test_classify_project_reads_header_case_insensitively():+ assert classify_project({"x-headroom-project": "frontend"}) == "frontend"+ assert classify_project({"X-Headroom-Project": " frontend "}) == "frontend"+ assert classify_project({"user-agent": "claude-code/1.0"}) is None+ assert classify_project(object()) is None+++def test_split_project_path_extracts_and_strips():+ assert split_project_path("/p/frontend/v1/messages") == ("frontend", "/v1/messages")+ assert split_project_path("/p/my%20repo/v1/chat/completions") == (+ "my repo",+ "/v1/chat/completions",+ )+ assert split_project_path("/p/frontend") == ("frontend", "/")+ # No prefix / unusable name: path passes through untouched.+ assert split_project_path("/v1/messages") == (None, "/v1/messages")+ assert split_project_path("/p//v1/messages") == (None, "/p//v1/messages")+ assert split_project_path("/p/%20%20/v1") == (None, "/p/%20%20/v1")+++def test_with_project_prefix_round_trips_through_split():+ url = with_project_prefix("http://127.0.0.1:8787/v1", "my repo")+ assert url == "http://127.0.0.1:8787/p/my%20repo/v1"+ path = url.removeprefix("http://127.0.0.1:8787")+ assert split_project_path(path) == ("my repo", "/v1")++ # Bare host (anthropic-style base) and unusable names.+ assert with_project_prefix("http://127.0.0.1:8787", "api") == "http://127.0.0.1:8787/p/api"+ assert with_project_prefix("http://127.0.0.1:8787/v1", " ") == "http://127.0.0.1:8787/v1"+ assert with_project_prefix("http://127.0.0.1:8787/v1", None) == "http://127.0.0.1:8787/v1"+++def test_project_contextvar_roundtrip():+ set_current_project(" demo ")+ assert get_current_project() == "demo"+ set_current_project(None)+ assert get_current_project() is None+++# ---------------------------------------------------------------------------+# SavingsTracker per-project aggregation+# ---------------------------------------------------------------------------+++def test_tracker_accumulates_per_project_and_persists(tmp_path):+ path = tmp_path / "savings.json"+ tracker = SavingsTracker(path=str(path))++ tracker.record_request(model="gpt-4o", input_tokens=1000, tokens_saved=400, project="api")+ tracker.record_request(model="gpt-4o", input_tokens=500, tokens_saved=100, project="api")+ tracker.record_request(model="gpt-4o", input_tokens=200, tokens_saved=50, project="web")+ tracker.record_request(model="gpt-4o", input_tokens=99, tokens_saved=9) # unattributed++ projects = tracker.stats_preview()["projects"]+ assert list(projects) == ["api", "web"] # sorted by tokens saved desc+ assert projects["api"]["requests"] == 2+ assert projects["api"]["tokens_saved"] == 500+ assert projects["api"]["total_input_tokens"] == 1500+ assert projects["api"]["savings_percent"] == pytest.approx(25.0)+ assert projects["web"]["requests"] == 1+ assert projects["api"]["last_activity_at"] is not None++ # Unattributed traffic still lands in the lifetime totals.+ assert tracker.stats_preview()["lifetime"]["requests"] == 4++ # Survives a restart via the persisted JSON state.+ reloaded = SavingsTracker(path=str(path))+ assert reloaded.stats_preview()["projects"]["api"]["tokens_saved"] == 500+++def test_tracker_migrates_v2_state_without_projects(tmp_path):+ path = tmp_path / "savings.json"+ path.write_text(+ json.dumps(+ {+ "schema_version": 2,+ "lifetime": {+ "requests": 3,+ "tokens_saved": 77,+ "compression_savings_usd": 0.1,+ "total_input_tokens": 500,+ "total_input_cost_usd": 0.2,+ },+ "display_session": None,+ "history": [],+ }+ )+ )+ tracker = SavingsTracker(path=str(path))+ preview = tracker.stats_preview()+ assert preview["projects"] == {}+ assert preview["lifetime"]["tokens_saved"] == 77+++def test_tracker_caps_project_cardinality(tmp_path):+ tracker = SavingsTracker(path=str(tmp_path / "savings.json"))+ for i in range(DEFAULT_MAX_PROJECTS + 5):+ tracker.record_request(+ model="gpt-4o",+ input_tokens=10,+ tokens_saved=i + 1,+ project=f"proj-{i:03d}",+ )+ projects = tracker.stats_preview()["projects"]+ assert len(projects) == DEFAULT_MAX_PROJECTS+ # The smallest buckets were evicted; the biggest savers survive.+ assert "proj-000" not in projects+ assert f"proj-{DEFAULT_MAX_PROJECTS + 4:03d}" in projects+++def test_tracker_sanitizes_persisted_project_state(tmp_path):+ path = tmp_path / "savings.json"+ path.write_text(+ json.dumps(+ {+ "schema_version": 3,+ "lifetime": {},+ "display_session": None,+ "history": [],+ "projects": {+ "ok": {"requests": "2", "tokens_saved": 10},+ "": {"requests": 1},+ "bad-entry": "not-a-dict",+ },+ }+ )+ )+ projects = SavingsTracker(path=str(path)).stats_preview()["projects"]+ assert set(projects) == {"ok"}+ assert projects["ok"]["requests"] == 2+ assert projects["ok"]["tokens_saved"] == 10+ assert projects["ok"]["compression_savings_usd"] == 0.0+++def test_tracker_caps_persisted_projects_on_load(tmp_path):+ path = tmp_path / "savings.json"+ oversized = {+ f"proj-{i:03d}": {"requests": 1, "tokens_saved": i}+ for i in range(DEFAULT_MAX_PROJECTS + 10)+ }+ path.write_text(+ json.dumps(+ {+ "schema_version": 3,+ "lifetime": {},+ "display_session": None,+ "history": [],+ "projects": oversized,+ }+ )+ )+ projects = SavingsTracker(path=str(path)).stats_preview()["projects"]+ assert len(projects) == DEFAULT_MAX_PROJECTS+ # Lowest tokens_saved entries are dropped, highest kept.+ assert "proj-000" not in projects+ assert f"proj-{DEFAULT_MAX_PROJECTS + 9:03d}" in projects+++# ---------------------------------------------------------------------------+# End-to-end: outcome funnel -> tracker -> /stats payload+# ---------------------------------------------------------------------------+++def _emit_outcome(proxy, *, project_field=None):+ outcome = RequestOutcome(+ request_id="req-1",+ provider="openai",+ model="gpt-4o",+ original_tokens=1000,+ optimized_tokens=600,+ output_tokens=20,+ tokens_saved=400,+ attempted_input_tokens=1000,+ project=project_field,+ )+ asyncio.run(emit_request_outcome(proxy, outcome))+++def test_funnel_attributes_savings_from_context_and_stats_exposes_them(tmp_path, monkeypatch):+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))+ config = ProxyConfig(cache_enabled=False, rate_limit_enabled=False, log_requests=False)++ with TestClient(create_app(config)) as client:+ proxy = client.app.state.proxy++ set_current_project("ctx-project")+ try:+ _emit_outcome(proxy)+ finally:+ set_current_project(None)++ # Explicit outcome.project wins over the bound context.+ _emit_outcome(proxy, project_field="field-project")++ stats = client.get("/stats").json()+ per_project = stats["savings"]["per_project"]+ assert per_project["ctx-project"]["tokens_saved"] == 400+ assert per_project["field-project"]["tokens_saved"] == 400+ assert stats["persistent_savings"]["projects"] == per_project+ assert stats["persistent_savings"]["projects_limit"] == DEFAULT_MAX_PROJECTS++ history = client.get("/stats-history").json()+ assert history["schema_version"] == 3+ assert history["projects"]["ctx-project"]["requests"] == 1+++# ---------------------------------------------------------------------------+# Regression: pre-feature behavior must be unchanged+# ---------------------------------------------------------------------------+++def test_record_request_without_project_matches_legacy_totals(tmp_path):+ """No-header traffic produces exactly the pre-v3 aggregates."""+ path = tmp_path / "savings.json"+ tracker = SavingsTracker(path=str(path))+ tracker.record_request(model="gpt-4o", input_tokens=100, tokens_saved=40)+ tracker.record_request(model="gpt-4o", input_tokens=200, tokens_saved=60)++ preview = tracker.stats_preview()+ assert preview["projects"] == {}+ assert preview["lifetime"]["requests"] == 2+ assert preview["lifetime"]["tokens_saved"] == 100+ assert preview["display_session"]["tokens_saved"] == 100++ persisted = json.loads(path.read_text())+ # Every legacy top-level key survives alongside the new projects map.+ assert set(persisted) >= {"schema_version", "lifetime", "display_session", "history"}+ assert persisted["projects"] == {}+++def test_stats_payload_keeps_legacy_shape(tmp_path, monkeypatch):+ """Dashboard consumers of the old /stats keys must not break."""+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))+ config = ProxyConfig(cache_enabled=False, rate_limit_enabled=False, log_requests=False)++ with TestClient(create_app(config)) as client:+ proxy = client.app.state.proxy+ _emit_outcome(proxy) # unattributed: no header, no context, no field++ stats = client.get("/stats").json()+ assert stats["savings"]["per_project"] == {}+ for legacy_key in ("requests", "savings", "persistent_savings", "cost"):+ assert legacy_key in stats, f"legacy /stats key {legacy_key!r} disappeared"+ assert stats["persistent_savings"]["lifetime"]["requests"] == 1++ history = client.get("/stats-history").json()+ for legacy_key in ("schema_version", "lifetime", "display_session", "retention"):+ assert legacy_key in history, f"legacy /stats-history key {legacy_key!r} disappeared"+++def test_metrics_record_request_works_without_project_kwarg(tmp_path, monkeypatch):+ """Existing callers that never pass ``project=`` keep working."""+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))+ config = ProxyConfig(cache_enabled=False, rate_limit_enabled=False, log_requests=False)++ with TestClient(create_app(config)) as client:+ proxy = client.app.state.proxy+ asyncio.run(+ proxy.metrics.record_request(+ provider="openai",+ model="gpt-4o",+ input_tokens=120,+ output_tokens=24,+ tokens_saved=30,+ latency_ms=15.0,+ )+ )+ preview = proxy.metrics.savings_tracker.stats_preview()+ assert preview["lifetime"]["tokens_saved"] == 30+ assert preview["projects"] == {}+++def test_middleware_binds_project_header_to_context(tmp_path, monkeypatch):+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))+ config = ProxyConfig(cache_enabled=False, rate_limit_enabled=False, log_requests=False)++ captured: list[str | None] = []++ import headroom.proxy.server as server_module++ def _capture(project: str | None) -> None:+ captured.append(project)+ set_current_project(project)++ monkeypatch.setattr(server_module, "set_current_project", _capture)++ with TestClient(create_app(config)) as client:+ assert client.get("/health", headers={"X-Headroom-Project": " my repo "}).status_code == 200+ assert client.get("/health").status_code == 200+ # /p/<name> base-URL prefix (aider/copilot/cursor wraps): stripped+ # before routing, so the request still reaches /health.+ assert client.get("/p/my%20repo/health").status_code == 200+ # An explicit header wins over the path prefix.+ assert (+ client.get(+ "/p/prefix-project/health", headers={"X-Headroom-Project": "header-project"}+ ).status_code+ == 200+ )++ assert captured == ["my repo", None, "my repo", "header-project"]diff --git a/tests/test_proxy_savings_history.py b/tests/test_proxy_savings_history.pyindex ba9391f81..421505d8c 100644--- a/tests/test_proxy_savings_history.py+++ b/tests/test_proxy_savings_history.py@@ -111,7 +111,7 @@ def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):)snapshot = tracker.snapshot()- assert snapshot["schema_version"] == 2+ assert snapshot["schema_version"] == 3assert snapshot["lifetime"] == {"requests": 0,"tokens_saved": 30,@@ -686,7 +686,7 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_phistory = client.get("/stats-history")assert history.status_code == 200history_data = history.json()- assert history_data["schema_version"] == 2+ assert history_data["schema_version"] == 3assert history_data["storage_path"] == str(savings_path)assert history_data["lifetime"]["tokens_saved"] == 40assert history_data["lifetime"]["total_input_tokens"] == 120