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
chore: renormalize line endings to LF
Garmefd2ac1ca4d8
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex a315e336e..fe8c697cb 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -1,2327 +1,2327 @@-"""Wrap CLI commands to run through Headroom proxy.--Usage:- headroom wrap claude # Start proxy + rtk + claude- headroom wrap copilot -- --model ... # Start proxy + launch GitHub Copilot CLI- headroom wrap codex # Start proxy + OpenAI Codex CLI- headroom wrap aider # Start proxy + aider- headroom wrap cursor # Start proxy + print Cursor config instructions- headroom wrap openclaw # Install + configure OpenClaw plugin- headroom wrap claude --no-rtk # Without rtk hooks- headroom wrap claude --port 9999 # Custom proxy port- headroom wrap claude -- --model opus # Pass args to claude-"""--from __future__ import annotations--import io-import json-import os-import shutil-import signal-import socket-import subprocess-import sys-import time-from pathlib import Path-from typing import Any, cast--# Fix Windows cp1252 encoding — box-drawing characters require UTF-8-if sys.platform == "win32" and hasattr(sys.stdout, "buffer"):- if sys.stdout.encoding and sys.stdout.encoding.lower().replace("-", "") != "utf8":- sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")- sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")--import click--from headroom.copilot_auth import DEFAULT_API_URL as COPILOT_API_URL-from headroom.copilot_auth import has_oauth_auth, resolve_client_bearer_token-from headroom.providers.aider import build_launch_env as _build_aider_launch_env-from headroom.providers.claude import proxy_base_url as _claude_proxy_base_url-from headroom.providers.codex import build_launch_env as _build_codex_launch_env-from headroom.providers.copilot import (- build_launch_env as _build_copilot_launch_env,-)-from headroom.providers.copilot import (- detect_running_proxy_backend as _copilot_detect_running_proxy_backend,-)-from headroom.providers.copilot import (- model_configured as _copilot_model_configured_impl,-)-from headroom.providers.copilot import (- provider_key_source as _copilot_provider_key_source,-)-from headroom.providers.copilot import (- query_proxy_config as _copilot_query_proxy_config,-)-from headroom.providers.copilot import (- resolve_provider_type as _copilot_resolve_provider_type,-)-from headroom.providers.copilot import (- validate_configuration as _validate_copilot_configuration,-)-from headroom.providers.cursor import render_setup_lines as _render_cursor_setup_lines-from headroom.providers.openclaw import (- build_plugin_entry as _build_openclaw_plugin_entry_impl,-)-from headroom.providers.openclaw import (- build_unwrap_entry as _build_openclaw_unwrap_entry_impl,-)-from headroom.providers.openclaw import (- decode_entry_json as _decode_openclaw_entry_json_impl,-)-from headroom.providers.openclaw import (- normalize_gateway_provider_ids as _normalize_openclaw_gateway_provider_ids_impl,-)--from .main import main---def _live_wrap_module() -> Any:- """Return the current live wrap module instance."""- return cast(Any, sys.modules[__name__])---def _print_telemetry_notice() -> None:- """Print a telemetry notice when anonymous telemetry is enabled.-- Respects the HEADROOM_TELEMETRY and HEADROOM_TELEMETRY_WARN feature flags.- Does nothing when telemetry or warnings are disabled.- """- from headroom.telemetry.beacon import format_telemetry_notice-- notice = format_telemetry_notice(prefix=" ")- if notice:- click.echo(notice)---# Proxy health check (reused from evals/suite_runner.py pattern)---def _check_proxy(port: int) -> bool:- """Check if Headroom proxy is running on given port."""- try:- with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:- s.settimeout(1)- s.connect(("127.0.0.1", port))- return True- except (TimeoutError, ConnectionRefusedError, OSError):- return False---def _get_log_path() -> Path:- """Get path for proxy log file."""- from headroom import paths as _paths-- log_dir = _paths.log_dir()- log_dir.mkdir(parents=True, exist_ok=True)- return log_dir / "proxy.log"---def _start_proxy(- port: int,- *,- learn: bool = False,- memory: bool = False,- agent_type: str = "unknown",- code_graph: bool = False,- backend: str | None = None,- anyllm_provider: str | None = None,- region: str | None = None,- openai_api_url: str | None = None,-) -> subprocess.Popen:- """Start Headroom proxy as a background subprocess.-- Logs are written to ~/.headroom/logs/proxy.log to avoid pipe buffer- deadlocks (macOS pipe buffer is ~64KB — a busy proxy fills it quickly,- blocking the process).- """- cmd = [sys.executable, "-m", "headroom.cli", "proxy", "--port", str(port)]-- # Forward HEADROOM_MODE env var so the proxy respects the user's mode choice- headroom_mode = os.environ.get("HEADROOM_MODE")- if headroom_mode:- cmd.extend(["--mode", headroom_mode])-- # Forward --learn flag to proxy subprocess- if learn:- cmd.append("--learn")-- # Forward --memory flag to proxy subprocess- if memory:- cmd.append("--memory")-- # Forward --code-graph flag to proxy subprocess (live file watcher)- if code_graph:- cmd.append("--code-graph")-- # Forward backend configuration to proxy subprocess- _backend = backend or os.environ.get("HEADROOM_BACKEND")- if _backend:- cmd.extend(["--backend", _backend])-- _anyllm = anyllm_provider or os.environ.get("HEADROOM_ANYLLM_PROVIDER")- if _anyllm:- cmd.extend(["--anyllm-provider", _anyllm])-- _region = region or os.environ.get("HEADROOM_REGION")- if _region:- cmd.extend(["--region", _region])-- if openai_api_url:- cmd.extend(["--openai-api-url", openai_api_url])-- log_path = _get_log_path()- log_file = open(log_path, "a") # noqa: SIM115-- # Ensure proxy subprocess uses UTF-8 (Windows defaults to cp1252)- proxy_env = os.environ.copy()- proxy_env["PYTHONIOENCODING"] = "utf-8"-- # Tell the proxy which agent is being wrapped (for traffic learning output)- if agent_type != "unknown":- proxy_env["HEADROOM_AGENT_TYPE"] = agent_type- proxy_env.setdefault("HEADROOM_STACK", f"wrap_{agent_type}")-- proc = subprocess.Popen(- cmd,- stdout=log_file,- stderr=log_file,- env=proxy_env,- )-- # Wait for proxy to be ready (up to 45 seconds).- # ML components (Kompress, Magika, Tree-sitter) load synchronously before- # uvicorn binds the port. On slower machines this can take 20-30 seconds.- for _i in range(45):- time.sleep(1)- if _check_proxy(port):- click.echo(f" Logs: {log_path}")- return proc- # Check if process died- if proc.poll() is not None:- log_file.close()- # Read last few lines of log for error context- try:- tail = log_path.read_text()[-500:]- except Exception:- tail = "(no log output)"- raise RuntimeError(f"Proxy exited with code {proc.returncode}: {tail}")-- proc.kill()- log_file.close()- raise RuntimeError(f"Proxy failed to start on port {port} within 45 seconds")---def _setup_rtk(verbose: bool = False) -> Path | None:- """Ensure rtk is installed and hooks are registered."""- from headroom.rtk import get_rtk_path- from headroom.rtk.installer import ensure_rtk, register_claude_hooks-- rtk_path = get_rtk_path()-- if rtk_path:- if verbose:- click.echo(f" rtk found at {rtk_path}")- else:- click.echo(" Downloading rtk (Rust Token Killer)...")- rtk_path = ensure_rtk()- if rtk_path:- click.echo(f" rtk installed at {rtk_path}")- else:- click.echo(" rtk download failed — continuing without it")- return None-- # Register hooks (idempotent)- if register_claude_hooks(rtk_path):- if verbose:- click.echo(" rtk hooks registered in Claude Code")- else:- click.echo(" rtk hook registration failed — continuing without it")-- return rtk_path---_CBM_MCP_SERVER_NAME = "codebase-memory-mcp"---def _register_cbm_mcp_server(cbm_bin: str) -> None:- """Register codebase-memory-mcp as an MCP server in Claude Code.-- Uses ``claude mcp add`` so the tools appear in ``/mcp`` automatically.- Idempotent — skips if already registered.- """- claude_cli = shutil.which("claude")- if not claude_cli:- return-- # Check if already registered- check = subprocess.run(- [claude_cli, "mcp", "get", _CBM_MCP_SERVER_NAME],- capture_output=True,- text=True,- )- if check.returncode == 0:- return # Already registered-- result = subprocess.run(- [claude_cli, "mcp", "add", _CBM_MCP_SERVER_NAME, "-s", "user", "--", cbm_bin],- capture_output=True,- text=True,- )- if result.returncode == 0:- click.echo(f" Code graph: registered {_CBM_MCP_SERVER_NAME} MCP server")- else:- pass # Non-critical — tools won't appear in /mcp but graph still works---def _setup_code_graph(verbose: bool = False) -> bool:- """Ensure codebase-memory-mcp is installed, registered as MCP server, and project is indexed.-- codebase-memory-mcp builds a knowledge graph of the codebase using- tree-sitter, enabling the LLM to query code structure (call chains,- function definitions, impact analysis) instead of reading entire files.-- Steps:- 1. Download the binary if not already present.- 2. Register as an MCP server in Claude Code (``claude mcp add``).- 3. Index the current project (fast, idempotent).-- With Claude Code's MCP Tool Search, the 14 graph tools add ~200 tokens- overhead per request (not the full ~1,915) — they're lazy-loaded.-- Returns True if graph is ready, False if setup failed.- """- from headroom.graph.installer import ensure_cbm, get_cbm_path-- cbm_path = get_cbm_path()- if not cbm_path:- click.echo(" Code graph: downloading codebase-memory-mcp...")- cbm_path = ensure_cbm()- if cbm_path:- click.echo(f" Code graph: installed at {cbm_path}")- else:- click.echo(" Code graph: download failed — skipping")- return False-- cbm_bin = str(cbm_path)-- # Register as MCP server so tools appear in /mcp- _register_cbm_mcp_server(cbm_bin)-- # Index current project (fast — ~1s for most repos, idempotent)- project_dir = str(Path.cwd())- try:- result = subprocess.run(- [- cbm_bin,- "cli",- "index_repository",- json.dumps({"repo_path": project_dir, "mode": "fast"}),- ],- capture_output=True,- text=True,- timeout=30,- )- if result.returncode == 0:- # Parse node/edge counts from output- for line in result.stdout.splitlines():- if '"nodes"' in line:- try:- # Parse the JSON response to extract node/edge counts- import re-- m_nodes = re.search(r'"nodes":(\d+)', line)- m_edges = re.search(r'"edges":(\d+)', line)- if m_nodes and m_edges:- nodes = int(m_nodes.group(1))- edges = int(m_edges.group(1))- click.echo(- f" Code graph: indexed ({nodes:,} symbols, "- f"{edges:,} relationships)"- )- else:- click.echo(" Code graph: indexed")- except (ValueError, AttributeError):- click.echo(" Code graph: indexed")- return True- click.echo(" Code graph: indexed")- return True- else:- if verbose:- click.echo(f" Code graph: indexing failed ({result.stderr[:100]})")- return False- except subprocess.TimeoutExpired:- click.echo(" Code graph: indexing timed out (will complete in background)")- return False- except Exception as e:- if verbose:- click.echo(f" Code graph: setup failed ({e})")- return False---# rtk instructions for tools without hook support (Codex, Cursor, Aider).-# These get injected into AGENTS.md / .cursorrules so the LLM voluntarily-# uses rtk-prefixed commands. Kept concise to minimize instruction overhead.-RTK_INSTRUCTIONS_BLOCK = """\-<!-- headroom:rtk-instructions -->-# RTK (Rust Token Killer) - Token-Optimized Commands--When running shell commands, **always prefix with `rtk`**. This reduces context-usage by 60-90% with zero behavior change. If rtk has no filter for a command,-it passes through unchanged — so it is always safe to use.--## Key Commands-```bash-# Git (59-80% savings)-rtk git status rtk git diff rtk git log--# Files & Search (60-75% savings)-rtk ls <path> rtk read <file> rtk grep <pattern>-rtk find <pattern> rtk diff <file>--# Test (90-99% savings) — shows failures only-rtk pytest tests/ rtk cargo test rtk test <cmd>--# Build & Lint (80-90% savings) — shows errors only-rtk tsc rtk lint rtk cargo build-rtk prettier --check rtk mypy rtk ruff check--# Analysis (70-90% savings)-rtk err <cmd> rtk log <file> rtk json <file>-rtk summary <cmd> rtk deps rtk env--# GitHub (26-87% savings)-rtk gh pr view <n> rtk gh run list rtk gh issue list--# Infrastructure (85% savings)-rtk docker ps rtk kubectl get rtk docker logs <c>--# Package managers (70-90% savings)-rtk pip list rtk pnpm install rtk npm run <script>-```--## Rules-- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`-- For debugging, use raw command without rtk prefix-- `rtk proxy <cmd>` runs command without filtering but tracks usage-<!-- /headroom:rtk-instructions -->-"""--# Marker used to detect if instructions are already injected-_RTK_MARKER = "<!-- headroom:rtk-instructions -->"--# Memory MCP markers-_MEMORY_MCP_MARKER = "# --- Headroom memory MCP (auto-injected) ---"-_MEMORY_MCP_END = "# --- end Headroom memory ---"-_MEMORY_AGENTS_MARKER = "<!-- headroom:memory-instructions -->"--# Codex config injection markers-_CODEX_TOP_LEVEL_MARKER = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"-_CODEX_END_MARKER = "# --- end Headroom ---"-# File name used for the pre-wrap snapshot of ~/.codex/config.toml. The-# snapshot lets `headroom unwrap codex` restore the exact prior state, even-# if the user had their own `model_provider` / `[model_providers.*]` config-# before running wrap.-_CODEX_CONFIG_BACKUP_SUFFIX = ".headroom-backup"---def _codex_config_paths() -> tuple[Path, Path]:- """Return ``(config_file, backup_file)`` paths for the Codex TOML config."""- config_dir = Path.home() / ".codex"- config_file = config_dir / "config.toml"- backup_file = config_dir / f"config.toml{_CODEX_CONFIG_BACKUP_SUFFIX}"- return config_file, backup_file---def _strip_codex_headroom_blocks(content: str) -> str:- """Remove all Headroom-managed blocks from a Codex ``config.toml`` string.-- Returns the cleaned content. Safe to call on content that never contained- any markers — it will be returned effectively unchanged (only trailing- whitespace is normalized).- """- import re-- # Remove any top-level-marker → end-marker span, possibly repeated.- while _CODEX_TOP_LEVEL_MARKER in content and _CODEX_END_MARKER in content:- start = content.index(_CODEX_TOP_LEVEL_MARKER)- end_idx = content.index(_CODEX_END_MARKER, start)- if end_idx < start:- break- end = end_idx + len(_CODEX_END_MARKER)- content = content[:start].rstrip("\n") + "\n" + content[end:].lstrip("\n")-- # Remove any stale top-level marker or end marker that lost its partner- # (e.g. a crashed prior wrap).- content = content.replace(_CODEX_TOP_LEVEL_MARKER + "\n", "")- content = content.replace(_CODEX_END_MARKER + "\n", "")-- # Strip any leftover top-level `model_provider = "headroom"` line, which- # older versions of `wrap codex` wrote outside the marker block.- content = re.sub(r'(?m)^[ \t]*model_provider[ \t]*=[ \t]*"headroom"[ \t]*\r?\n', "", content)-- # Strip any orphaned `[model_providers.headroom]` table with the fields we- # write. We only remove it if the table is recognisably ours (base_url- # mentions localhost and a Headroom proxy port). This protects users who- # happen to have a differently configured `headroom` provider.- orphan_headroom_table = re.compile(- r"(?ms)^\[model_providers\.headroom\][^\[]*?"- r'base_url[ \t]*=[ \t]*"http://127\.0\.0\.1:\d+/v1"[^\[]*?'- r"(?=^\[|\Z)"- )- content = orphan_headroom_table.sub("", content)-- return content.lstrip("\n").rstrip() + "\n" if content.strip() else ""---def _snapshot_codex_config_if_unwrapped(config_file: Path, backup_file: Path) -> None:- """Snapshot ``config.toml`` to ``backup_file`` before the first injection.-- Called as the first step of every Headroom injection into Codex's- ``config.toml``. Guarantees that ``headroom unwrap codex`` can restore the- user's original file byte-for-byte.-- Rules:-- * If the backup already exists, leave it alone — we only snapshot the- *pre-wrap* state, so running wrap repeatedly must not clobber it.- * If the config file doesn't exist yet, there's nothing to back up; unwrap- will remove the file entirely instead of restoring a snapshot.- * If the config already contains a Headroom marker, a wrap run is already- active: do not snapshot the injected state.- """- if backup_file.exists():- return- if not config_file.exists():- return- try:- content = config_file.read_text()- except OSError:- return- if _CODEX_TOP_LEVEL_MARKER in content or _CODEX_END_MARKER in content:- return- backup_file.parent.mkdir(parents=True, exist_ok=True)- shutil.copy2(config_file, backup_file)---def _ensure_rtk_binary(verbose: bool = False) -> Path | None:- """Ensure rtk binary is installed (download if needed). No hook registration."""- from headroom.rtk import get_rtk_path- from headroom.rtk.installer import ensure_rtk-- rtk_path = get_rtk_path()-- if rtk_path:- if verbose:- click.echo(f" rtk found at {rtk_path}")- return rtk_path-- click.echo(" Downloading rtk (Rust Token Killer)...")- rtk_path = ensure_rtk()- if rtk_path:- click.echo(f" rtk installed at {rtk_path}")- return rtk_path-- click.echo(" rtk download failed — continuing without it")- return None---def _prepare_wrap_rtk(verbose: bool = False, *, label: str | None = None) -> Path | None:- """Ensure rtk is present for host-bridged wrap flows without host-specific setup."""- if label:- click.echo(f" Preparing rtk for {label}...")- return _ensure_rtk_binary(verbose=verbose)---def _inject_codex_provider_config(port: int) -> None:- """Inject a Headroom model provider into Codex's config.toml.-- Codex ignores OPENAI_BASE_URL for WebSocket transport unless a custom- provider declares ``supports_websockets = true``. This writes a- ``[model_providers.headroom]`` section that routes both HTTP and WS- through the proxy, and sets ``model_provider = "headroom"``.-- Safe to call multiple times — the injected block is fully replaced on- each call, so re-running with a different ``port`` updates the config.- Before the first injection, the pre-wrap file is snapshotted to- ``~/.codex/config.toml.headroom-backup`` so ``headroom unwrap codex``- can restore it byte-for-byte.- """- config_file, backup_file = _codex_config_paths()- config_dir = config_file.parent-- # The injected content is split into two self-contained, marker-delimited- # blocks: a top-level key block (at the start of the file, because bare- # TOML keys must precede any [section]) and a provider-table block (at- # the end). Each block has its own matching begin/end marker pair so- # stripping them is unambiguous and never consumes user content that- # happens to sit between the two.- top_level_block = (- f'{_CODEX_TOP_LEVEL_MARKER}\nmodel_provider = "headroom"\n{_CODEX_END_MARKER}\n'- )- provider_section = (- f"{_CODEX_TOP_LEVEL_MARKER}\n"- "[model_providers.headroom]\n"- 'name = "OpenAI via Headroom proxy"\n'- f'base_url = "http://127.0.0.1:{port}/v1"\n'- f'env_key = "OPENAI_API_KEY"\n'- f"requires_openai_auth = true\n"- f"supports_websockets = true\n"- f"{_CODEX_END_MARKER}\n"- )-- try:- config_dir.mkdir(parents=True, exist_ok=True)-- # Snapshot the pre-wrap state before touching anything. No-op if the- # config is already wrapped, is missing, or we've already snapshotted.- _snapshot_codex_config_if_unwrapped(config_file, backup_file)-- if config_file.exists():- content = config_file.read_text()- # Remove any prior Headroom-managed blocks before re-injecting so- # the operation is idempotent and supports port changes.- content = _strip_codex_headroom_blocks(content)-- # Place the top-level key block at the very beginning of the file- # (bare TOML keys must precede any [section]) and the provider- # table at the end. User content, if any, sits between them.- user_content = content.strip()- if user_content:- content = top_level_block + "\n" + user_content + "\n\n" + provider_section- else:- content = top_level_block + "\n" + provider_section- else:- content = top_level_block + "\n" + provider_section-- config_file.write_text(content)- click.echo(f" Codex config: injected Headroom provider (WS + HTTP) into {config_file}")- except Exception as e:- click.echo(f" Warning: could not update Codex config: {e}")---def _restore_codex_provider_config() -> tuple[str, Path]:- """Undo ``_inject_codex_provider_config`` for ``~/.codex/config.toml``.-- Returns a tuple of ``(status, config_file)`` where status is one of:-- * ``"restored"`` — a pre-wrap backup existed and was restored; backup- file has been removed.- * ``"cleaned"`` — no backup existed, but the Headroom-managed block was- found and stripped out (preserving surrounding user content).- * ``"removed"`` — the config file only contained Headroom-managed- content (created by wrap) and has been deleted.- * ``"noop"`` — nothing to undo; no Headroom marker and no backup.- """- config_file, backup_file = _codex_config_paths()-- # Case 1: pre-wrap snapshot exists — restore it exactly.- if backup_file.exists():- shutil.copy2(backup_file, config_file)- backup_file.unlink()- return "restored", config_file-- # Case 2: no backup, but config file exists and has markers — strip them.- if config_file.exists():- original = config_file.read_text()- if _CODEX_TOP_LEVEL_MARKER in original or _CODEX_END_MARKER in original:- cleaned = _strip_codex_headroom_blocks(original)- if not cleaned.strip():- # Nothing left but Headroom content — remove the file entirely- # so Codex falls back to its default config.- config_file.unlink()- return "removed", config_file- config_file.write_text(cleaned)- return "cleaned", config_file-- # Nothing to undo.- return "noop", config_file---def _inject_rtk_instructions(file_path: Path, verbose: bool = False) -> bool:- """Inject rtk instructions into a file (AGENTS.md, .cursorrules, etc.).-- Idempotent — skips if marker already present. Appends to existing content.- Returns True if instructions were written.- """- if file_path.exists():- existing = file_path.read_text()- if _RTK_MARKER in existing:- if verbose:- click.echo(f" rtk instructions already in {file_path.name}")- return True- # Append to existing file- with open(file_path, "a") as f:- f.write("\n\n" + RTK_INSTRUCTIONS_BLOCK)- else:- file_path.parent.mkdir(parents=True, exist_ok=True)- file_path.write_text(RTK_INSTRUCTIONS_BLOCK)-- click.echo(f" rtk instructions injected into {file_path}")- return True---def _inject_memory_mcp_config(db_path: str, user_id: str) -> None:- """Register headroom memory as an MCP server in Codex's config.toml.-- Idempotent — replaces existing section if present.- """- import sys-- config_dir = Path.home() / ".codex"- config_file = config_dir / "config.toml"-- # Use forward slashes in TOML paths (works on all platforms, avoids- # backslash escaping issues on Windows)- python_bin = sys.executable.replace("\\", "/")- db_path_toml = db_path.replace("\\", "/")- mcp_section = (- f"\n{_MEMORY_MCP_MARKER}\n"- f"[mcp_servers.headroom_memory]\n"- f'command = "{python_bin}"\n'- f'args = ["-m", "headroom.memory.mcp_server", "--db", "{db_path_toml}", "--user", "{user_id}"]\n'- f"startup_timeout_sec = 30\n"- f"tool_timeout_sec = 30\n"- f"{_MEMORY_MCP_END}\n"- )-- try:- config_dir.mkdir(parents=True, exist_ok=True)-- # Snapshot pre-wrap state before touching config.toml so `unwrap codex`- # can fully restore it even when only `--memory` (not a full provider- # injection) was used.- _, backup_file = _codex_config_paths()- _snapshot_codex_config_if_unwrapped(config_file, backup_file)-- if config_file.exists():- content = config_file.read_text()- if _MEMORY_MCP_MARKER in content:- start = content.index(_MEMORY_MCP_MARKER)- end = content.index(_MEMORY_MCP_END) + len(_MEMORY_MCP_END)- content = content[:start].rstrip("\n") + mcp_section + content[end:].lstrip("\n")- else:- content = content.rstrip() + "\n" + mcp_section- else:- content = mcp_section-- config_file.write_text(content)- click.echo(f" Memory MCP: registered in {config_file}")- except Exception as e:- click.echo(f" Warning: could not register memory MCP: {e}")---def _inject_memory_agents_md(file_path: Path) -> bool:- """Inject memory usage guidance into AGENTS.md.-- Idempotent — skips if marker already present.- """- memory_block = (- f"{_MEMORY_AGENTS_MARKER}\n"- "## Memory\n\n"- "Use the `headroom_memory` MCP server for persistent cross-session knowledge.\n\n"- "**Before** answering questions about prior decisions, conventions, project context,\n"- "architecture, user preferences, org info, codenames, debugging history, or anything\n"- "from past sessions — call `memory_search` first.\n\n"- "**After** making durable decisions, discovering conventions, or learning important\n"- "facts — call `memory_save` to persist them for future sessions.\n\n"- "Memory is your first source of truth for anything not visible in the current conversation.\n"- )-- if file_path.exists():- existing = file_path.read_text()- if _MEMORY_AGENTS_MARKER in existing:- return True # Already injected- with open(file_path, "a") as f:- f.write("\n\n" + memory_block)- else:- file_path.parent.mkdir(parents=True, exist_ok=True)- file_path.write_text(memory_block)-- click.echo(f" Memory guidance injected into {file_path.name}")- return True---def _resolve_copilot_provider_type(backend: str | None, provider_type: str) -> str:- """Resolve Copilot BYOK provider type for the current proxy backend."""- return _copilot_resolve_provider_type(backend, provider_type)---def _query_proxy_config(port: int) -> dict[str, Any] | None:- """Query the running proxy's feature configuration via /health.-- Returns a dict with keys like backend, optimize, cache, rate_limit,- memory, learn, code_graph, pid. Returns None if unreachable or the- response lacks a config block.- """- return _copilot_query_proxy_config(port)---def _detect_running_proxy_backend(port: int) -> str | None:- """Read the backend of an already-running proxy from its health endpoint."""- return _copilot_detect_running_proxy_backend(port)---def _kill_proxy_by_pid(pid: int, port: int) -> bool:- """Terminate a proxy process by PID and wait for the port to free up.-- Sends SIGTERM first, falls back to SIGKILL after 5 seconds.- Returns True if the port is free afterwards, False otherwise.- """- try:- os.kill(pid, signal.SIGTERM)- except ProcessLookupError:- pass # Already gone- except PermissionError:- click.echo(f" Warning: No permission to kill proxy PID {pid}")- return False-- # Wait for port to free (up to 5 seconds)- for _ in range(50):- time.sleep(0.1)- if not _check_proxy(port):- return True-- # SIGTERM didn't work — escalate to SIGKILL (Unix) or terminate (Windows)- try:- _kill_signal = getattr(signal, "SIGKILL", signal.SIGTERM)- os.kill(pid, _kill_signal)- except (ProcessLookupError, PermissionError):- pass-- for _ in range(20):- time.sleep(0.1)- if not _check_proxy(port):- return True-- return False---def _find_persistent_manifest(port: int) -> Any:- """Return a matching persistent deployment manifest for the requested port."""- from headroom.install.state import list_manifests-- manifests = [manifest for manifest in list_manifests() if manifest.port == port]- manifests.sort(key=lambda manifest: (manifest.profile != "default", manifest.profile))- return manifests[0] if manifests else None---def _recover_persistent_proxy(port: int) -> bool:- """Start or recover a matching persistent deployment for the requested port."""- from headroom.install.health import probe_ready- from headroom.install.models import InstallPreset, SupervisorKind- from headroom.install.runtime import start_detached_agent, start_persistent_docker, wait_ready- from headroom.install.supervisors import start_supervisor-- manifest = _find_persistent_manifest(port)- if manifest is None:- return False-- if probe_ready(manifest.health_url):- click.echo(f" Reusing persistent deployment '{manifest.profile}' on port {port}")- return True-- if manifest.supervisor_kind == SupervisorKind.TASK.value:- click.echo(- f" Warning: task-based deployment '{manifest.profile}' cannot be auto-recovered via wrap"- )- return False-- click.echo(f" Recovering persistent deployment '{manifest.profile}' on port {port}...")- try:- if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:- start_persistent_docker(manifest)- elif manifest.supervisor_kind == SupervisorKind.SERVICE.value:- start_supervisor(manifest)- else:- start_detached_agent(manifest.profile)- except Exception as exc:- click.echo(- f" Warning: could not recover persistent deployment '{manifest.profile}': {exc}"- )- return False-- if wait_ready(manifest, timeout_seconds=45):- click.echo(f" Recovered persistent deployment '{manifest.profile}' on port {port}")- return True-- click.echo(f" Warning: persistent deployment '{manifest.profile}' did not become ready")- return False---def _copilot_model_configured(copilot_args: tuple[str, ...], env: dict[str, str]) -> bool:- """Return True when Copilot BYOK model selection is configured."""- return _copilot_model_configured_impl(copilot_args, env)---def _should_use_copilot_oauth(- *,- backend: str | None,- provider_type: str,- env: dict[str, str],-) -> bool:- """Prefer a reusable Copilot OAuth session when the requested routing supports it."""- if env.get("COPILOT_PROVIDER_API_KEY") or env.get("COPILOT_PROVIDER_BEARER_TOKEN"):- return False- if provider_type == "anthropic":- return False-- effective_backend = backend or os.environ.get("HEADROOM_BACKEND")- if effective_backend not in (None, "", "anthropic"):- return False-- return has_oauth_auth()---def _ensure_proxy(- port: int,- no_proxy: bool,- *,- learn: bool = False,- memory: bool = False,- agent_type: str = "unknown",- code_graph: bool = False,- backend: str | None = None,- anyllm_provider: str | None = None,- region: str | None = None,- openai_api_url: str | None = None,-) -> subprocess.Popen | None:- """Start or verify proxy. Returns process handle if we started it."""- helpers = _live_wrap_module()- if not no_proxy:- manifest = helpers._find_persistent_manifest(port)- if manifest is not None:- from headroom.install.health import probe_ready-- if probe_ready(manifest.health_url):- click.echo(f" Proxy already running on port {port}")- return None- if helpers._recover_persistent_proxy(port):- return None- if helpers._check_proxy(port):- raise click.ClickException(- f"Persistent deployment '{manifest.profile}' on port {port} is not healthy."- )- click.echo(- f" Warning: persistent deployment '{manifest.profile}' on port {port} "- "is stale; starting a fresh proxy instead."- )-- if helpers._check_proxy(port):- # Proxy is running — check if it has the features we need- needs_restart = False- running_config = helpers._query_proxy_config(port)-- if running_config is not None:- missing = []- if memory and not running_config.get("memory"):- missing.append("memory")- if learn and not running_config.get("learn"):- missing.append("learn")- if code_graph and not running_config.get("code_graph"):- missing.append("code_graph")-- if missing:- needs_restart = True- flags_str = ", ".join(f"--{f.replace('_', '-')}" for f in missing)- click.echo(f" Proxy on port {port} is missing: {flags_str}")- click.echo(" Restarting proxy with upgraded configuration...")-- # Merge: keep features the running proxy already has- memory = memory or bool(running_config.get("memory"))- learn = learn or bool(running_config.get("learn"))- code_graph = code_graph or bool(running_config.get("code_graph"))-- proxy_pid = running_config.get("pid")- if proxy_pid is not None:- if not helpers._kill_proxy_by_pid(int(proxy_pid), port):- raise click.ClickException(- f"Failed to stop existing proxy (PID {proxy_pid}) on port {port}. "- "Stop it manually and retry."- )- else:- click.echo(- " Warning: Running proxy does not expose PID. "- "Cannot restart automatically."- )- click.echo(- f" Please stop the proxy on port {port} manually "- f"and rerun with {flags_str}."- )- return None-- if not needs_restart:- click.echo(f" Proxy already running on port {port}")- return None-- # Start (or restart) the proxy with the requested flags- click.echo(f" Starting Headroom proxy on port {port}...")- try:- proc = cast(- subprocess.Popen[Any],- _live_wrap_module()._start_proxy(- port,- learn=learn,- memory=memory,- agent_type=agent_type,- code_graph=code_graph,- backend=backend,- anyllm_provider=anyllm_provider,- region=region,- openai_api_url=openai_api_url,- ),- )- click.echo(f" Proxy ready on http://127.0.0.1:{port}")- return proc- except RuntimeError as e:- click.echo(f" Error: {e}")- raise SystemExit(1) from e- else:- if not helpers._check_proxy(port):- click.echo(f" Warning: No proxy detected on port {port}")- return None---def _make_cleanup(proxy_proc_holder: list, port: int = 8787) -> Any:- """Create a cleanup function that terminates the proxy on exit.-- Only kills the proxy if no other headroom-wrapped clients are using it.- Checks by looking for other processes with ANTHROPIC_BASE_URL or- OPENAI_BASE_URL pointing at our port.- """-- def _other_clients_exist() -> bool:- """Check if other processes are using this proxy."""- try:- # Count headroom wrap processes (excluding ourselves)- result = subprocess.run(- ["pgrep", "-f", f"127.0.0.1:{port}"],- capture_output=True,- text=True,- )- pids = [p.strip() for p in result.stdout.strip().split("\n") if p.strip()]- my_pid = str(os.getpid())- other_pids = [p for p in pids if p != my_pid]- return len(other_pids) > 0- except Exception:- return False # If we can't check, assume no others-- def cleanup(signum: int | None = None, frame: Any = None) -> None:- proc = proxy_proc_holder[0] if proxy_proc_holder else None- if proc and proc.poll() is None:- if _other_clients_exist():- # Other clients still using the proxy — leave it running- return- proc.terminate()- try:- proc.wait(timeout=5)- except subprocess.TimeoutExpired:- proc.kill()-- return cleanup---def _launch_tool(- binary: str,- args: tuple,- env: dict[str, str],- port: int,- no_proxy: bool,- tool_label: str,- env_vars_display: list[str],- *,- learn: bool = False,- memory: bool = False,- agent_type: str = "unknown",- code_graph: bool = False,- backend: str | None = None,- anyllm_provider: str | None = None,- region: str | None = None,- openai_api_url: str | None = None,-) -> None:- """Common logic: start proxy, launch tool, clean up."""- proxy_holder: list[subprocess.Popen | None] = [None]- cleanup = _make_cleanup(proxy_holder, port)- signal.signal(signal.SIGINT, cleanup)- signal.signal(signal.SIGTERM, cleanup)-- try:- click.echo()- padded = f"HEADROOM WRAP: {tool_label}".center(47)- click.echo(" ╔═══════════════════════════════════════════════╗")- click.echo(f" ║{padded}║")- click.echo(" ╚═══════════════════════════════════════════════╝")- click.echo()-- proxy_holder[0] = _ensure_proxy(- port,- no_proxy,- learn=learn,- memory=memory,- agent_type=agent_type,- code_graph=code_graph,- backend=backend,- anyllm_provider=anyllm_provider,- region=region,- openai_api_url=openai_api_url,- )-- if code_graph:- _setup_code_graph(verbose=False)-- click.echo()- click.echo(f" Launching {tool_label} (API routed through Headroom)...")- for var in env_vars_display:- click.echo(f" {var}")- if args:- click.echo(f" Extra args: {' '.join(args)}")- _print_telemetry_notice()- click.echo()-- result = subprocess.run([binary, *args], env=env)- raise SystemExit(result.returncode)-- except SystemExit:- raise- except Exception as e:- click.echo(f" Error: {e}")- raise SystemExit(1) from e- finally:- cleanup()---def _run_checked(- cmd: list[str],- *,- cwd: Path | None = None,- action: str,-) -> subprocess.CompletedProcess[str]:- """Run subprocess and raise a ClickException with actionable context on failure."""- try:- return subprocess.run(- cmd,- cwd=str(cwd) if cwd else None,- check=True,- capture_output=True,- text=True,- encoding="utf-8",- errors="replace",- )- except FileNotFoundError as e:- raise click.ClickException(f"{action} failed: command not found: {cmd[0]}") from e- except subprocess.CalledProcessError as e:- stderr = (e.stderr or "").strip()- stdout = (e.stdout or "").strip()- details = stderr or stdout or f"exit code {e.returncode}"- raise click.ClickException(f"{action} failed: {details}") from e---def _resolve_openclaw_extensions_dir(openclaw_bin: str) -> Path:- """Resolve OpenClaw extension root from active config file path."""- result = _run_checked([openclaw_bin, "config", "file"], action="openclaw config file")- lines = result.stdout.strip().splitlines()- config_path_str = lines[-1].strip() if lines else ""- if not config_path_str:- raise click.ClickException(- "Unable to resolve OpenClaw config path from `openclaw config file`."- )- config_path = Path(config_path_str).expanduser()- return config_path.parent / "extensions"---def _normalize_openclaw_gateway_provider_ids(provider_ids: tuple[str, ...] | None) -> list[str]:- """Normalize configured OpenClaw provider ids, defaulting to openai-codex."""- return _normalize_openclaw_gateway_provider_ids_impl(provider_ids)---def _read_openclaw_config_value(openclaw_bin: str, path: str) -> Any | None:- """Read an OpenClaw config value when present, returning None on missing paths."""- result = subprocess.run(- [openclaw_bin, "config", "get", path],- capture_output=True,- text=True,- encoding="utf-8",- errors="replace",- )- if result.returncode != 0:- return None-- output = result.stdout.strip()- if not output:- return None-- try:- return json.loads(output)- except json.JSONDecodeError:- return output---def _decode_openclaw_entry_json(raw_value: str | None) -> Any | None:- """Decode a JSON payload captured from `openclaw config get` when available."""- return _decode_openclaw_entry_json_impl(raw_value)---def _build_openclaw_plugin_entry(- *,- existing_entry: Any,- proxy_port: int,- startup_timeout_ms: int,- python_path: str | None,- no_auto_start: bool,- gateway_provider_ids: tuple[str, ...] | None,- enabled: bool,-) -> dict[str, object]:- """Merge managed Headroom plugin settings with any existing entry payload."""- return _build_openclaw_plugin_entry_impl(- existing_entry=existing_entry,- proxy_port=proxy_port,- startup_timeout_ms=startup_timeout_ms,- python_path=python_path,- no_auto_start=no_auto_start,- gateway_provider_ids=gateway_provider_ids,- enabled=enabled,- )---def _build_openclaw_unwrap_entry(existing_entry: Any) -> dict[str, object]:- """Disable the managed plugin while preserving unrelated user config."""- return _build_openclaw_unwrap_entry_impl(existing_entry)---def _write_openclaw_plugin_entry(openclaw_bin: str, entry: dict[str, object]) -> None:- """Persist the Headroom plugin config entry."""- _run_checked(- [- openclaw_bin,- "config",- "set",- "plugins.entries.headroom",- json.dumps(entry, separators=(",", ":")),- "--strict-json",- ],- action="openclaw config set plugins.entries.headroom",- )---def _set_openclaw_context_engine_slot(openclaw_bin: str, engine_id: str) -> None:- """Persist the selected OpenClaw context engine slot."""- _run_checked(- [- openclaw_bin,- "config",- "set",- "plugins.slots.contextEngine",- json.dumps(engine_id),- "--strict-json",- ],- action="openclaw config set plugins.slots.contextEngine",- )---def _restart_or_start_openclaw_gateway(openclaw_bin: str) -> tuple[str, str]:- """Restart the gateway when running, otherwise start it."""- restart_result = subprocess.run(- [openclaw_bin, "gateway", "restart"],- capture_output=True,- text=True,- encoding="utf-8",- errors="replace",- )- if restart_result.returncode == 0:- output = restart_result.stdout.strip() or restart_result.stderr.strip()- return "restarted", output-- start_result = _run_checked(- [openclaw_bin, "gateway", "start"],- action="openclaw gateway start",- )- output = start_result.stdout.strip() or start_result.stderr.strip()- return "started", output---def _copy_openclaw_plugin_into_extensions(- *,- plugin_dir: Path,- openclaw_bin: str,-) -> Path:- """Fallback install path when `openclaw plugins install` is blocked on linked source."""- dist_dir = plugin_dir / "dist"- if not dist_dir.exists():- raise click.ClickException(- f"Plugin dist folder missing at {dist_dir}. Build the plugin first."- )- hook_shim_dir = plugin_dir / "hook-shim"- if not hook_shim_dir.exists():- raise click.ClickException(- f"Plugin hook-shim folder missing at {hook_shim_dir}. Build the plugin first."- )-- extensions_dir = _resolve_openclaw_extensions_dir(openclaw_bin)- target_dir = extensions_dir / "headroom"- target_dist = target_dir / "dist"- target_hook_shim = target_dir / "hook-shim"- target_dir.mkdir(parents=True, exist_ok=True)- if target_dist.exists():- shutil.rmtree(target_dist)- if target_hook_shim.exists():- shutil.rmtree(target_hook_shim)- shutil.copytree(dist_dir, target_dist)- shutil.copytree(hook_shim_dir, target_hook_shim)-- for filename in ("openclaw.plugin.json", "package.json", "README.md"):- source = plugin_dir / filename- if source.exists():- shutil.copy2(source, target_dir / filename)-- return target_dir---def wrap() -> None:- """Wrap CLI tools to run through Headroom.-- \b- Starts a Headroom proxy, configures the environment, and launches- the target tool so all API calls route through Headroom automatically.-- \b- Supported tools:- headroom wrap claude # Claude Code (Anthropic)- headroom wrap copilot -- --model claude-sonnet-4-20250514- headroom wrap codex # OpenAI Codex CLI- headroom wrap aider # Aider- headroom wrap cursor # Cursor (prints config instructions)- headroom wrap openclaw # OpenClaw plugin bootstrap- """---def unwrap() -> None:- """Undo durable Headroom wrapping for supported tools."""---# =============================================================================-# Claude Code-# =============================================================================--[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--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")- "--code-graph",- is_flag=True,- help="Enable code graph indexing via codebase-memory-mcp (optional)",-)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")- "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to MEMORY.md)"-)[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("claude_args", nargs=-1, type=click.UNPROCESSED)-def claude(- port: int,- no_rtk: bool,- code_graph: bool,- no_proxy: bool,- learn: bool,- memory: bool,- verbose: bool,- prepare_only: bool,- claude_args: tuple,-) -> None:- """Launch Claude Code through Headroom proxy.-- \b- Sets ANTHROPIC_BASE_URL to route all Anthropic API calls through Headroom.- All unknown flags are passed through to claude (e.g. --resume, --model).-- \b- Examples:- headroom wrap claude # Start everything- headroom wrap claude --memory # With persistent memory- headroom wrap claude --resume <id> # Resume a session- headroom wrap claude -- -p # Claude in print mode- headroom wrap claude --code-graph # With code graph intelligence- headroom wrap claude --no-rtk # Skip rtk (proxy only)- """- if prepare_only:- if not no_rtk:- _prepare_wrap_rtk(verbose=verbose, label="Claude")- return-- claude_bin = shutil.which("claude")- if not claude_bin:- click.echo("Error: 'claude' not found in PATH.")- click.echo("Install Claude Code: https://docs.anthropic.com/en/docs/claude-code")- raise SystemExit(1)-- # Setup rtk before launching (Claude-specific)- proxy_holder: list[subprocess.Popen | None] = [None]- cleanup = _make_cleanup(proxy_holder, port)- signal.signal(signal.SIGINT, cleanup)- signal.signal(signal.SIGTERM, cleanup)-- # Memory sync BEFORE proxy startup — sync headroom DB ↔ Claude's files- if memory:- try:- import subprocess as _sp-- mem_dir = Path.cwd() / ".headroom"- mem_dir.mkdir(parents=True, exist_ok=True)- _sync_db = str(mem_dir / "memory.db")- _sync_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))-- click.echo(f" Syncing memory (user={_sync_user})...")- sync_result = _sp.run(- [- sys.executable,- "-m",- "headroom.memory.sync",- "--db",- _sync_db,- "--user",- _sync_user,- "--agent",- "claude",- "--force",- ],- capture_output=True,- text=True,- timeout=30,- )- if sync_result.returncode == 0 and sync_result.stdout.strip():- import json as _json-- stats = _json.loads(sync_result.stdout.strip().split("\n")[-1])- imp, exp, ms = stats["imported"], stats["exported"], stats["ms"]- if imp or exp:- click.echo(f" Memory synced: {imp} imported, {exp} exported ({ms}ms)")- else:- click.echo(f" Memory: up to date ({ms}ms)")- elif sync_result.returncode != 0:- click.echo(f" Warning: memory sync error: {sync_result.stderr[-200:]}")- except Exception as e:- click.echo(f" Warning: memory sync failed: {e}")-- try:- click.echo()- click.echo(" ╔═══════════════════════════════════════════════╗")- click.echo(" ║ HEADROOM WRAP: CLAUDE ║")- click.echo(" ╚═══════════════════════════════════════════════╝")- click.echo()-- proxy_holder[0] = _ensure_proxy(- port, no_proxy, learn=learn, memory=memory, agent_type="claude", code_graph=code_graph- )-- if not no_rtk:- click.echo(" Setting up rtk...")- _setup_rtk(verbose=verbose)- elif verbose:- click.echo(" Skipping rtk (--no-rtk)")-- if code_graph:- _setup_code_graph(verbose=verbose)-- click.echo()- click.echo(" Launching Claude Code (API routed through Headroom)...")- click.echo(f" ANTHROPIC_BASE_URL={_claude_proxy_base_url(port)}")- if claude_args:- click.echo(f" Extra args: {' '.join(claude_args)}")- _print_telemetry_notice()- click.echo()-- env = os.environ.copy()- env["ANTHROPIC_BASE_URL"] = _claude_proxy_base_url(port)-- result = subprocess.run([claude_bin, *claude_args], env=env)- raise SystemExit(result.returncode)-- except SystemExit:- raise- except Exception as e:- click.echo(f" Error: {e}")- raise SystemExit(1) from e- finally:- cleanup()---# =============================================================================-# GitHub Copilot CLI-# =============================================================================--[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")- "--no-rtk",- is_flag=True,- help="Skip rtk installation and Copilot instructions injection",-)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")- "--backend",- default=None,- help="API backend for the proxy: 'anthropic', 'anyllm', 'litellm-vertex', etc. (env: HEADROOM_BACKEND)",-)- "--anyllm-provider",- default=None,- help="Provider for any-llm backend: openai, mistral, groq, etc. (env: HEADROOM_ANYLLM_PROVIDER)",-)- "--region", default=None, help="Cloud region for Bedrock/Vertex (env: HEADROOM_REGION)"-)- "--provider-type",- type=click.Choice(["auto", "anthropic", "openai"]),- default="auto",- show_default=True,- help="Copilot BYOK provider mode. 'auto' uses anthropic for the default proxy backend and openai for translated backends.",-)- "--wire-api",- type=click.Choice(["completions", "responses"]),- default=None,- help="OpenAI-compatible Copilot wire API. Defaults to 'completions' when provider-type resolves to openai.",-)[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("copilot_args", nargs=-1, type=click.UNPROCESSED)-def copilot(- port: int,- no_rtk: bool,- no_proxy: bool,- backend: str | None,- anyllm_provider: str | None,- region: str | None,- provider_type: str,- wire_api: str | None,- memory: bool,- verbose: bool,- copilot_args: tuple[str, ...],-) -> None:- """Launch GitHub Copilot CLI through Headroom proxy.-- \b- Configures Copilot CLI BYOK provider variables so Copilot routes through- the local Headroom proxy. In auto mode, the wrapper uses Anthropic-style- routing for the stock proxy backend and OpenAI-compatible routing for- translated backends such as any-llm and LiteLLM.-- \b- Examples:- headroom wrap copilot -- --model claude-sonnet-4-20250514- headroom wrap copilot --backend anyllm --anyllm-provider groq -- --model gpt-4o- headroom wrap copilot --provider-type openai --wire-api responses -- --model gpt-5.4- headroom wrap copilot --no-rtk -- --prompt "explain this file"- """- copilot_bin = shutil.which("copilot")- if not copilot_bin:- click.echo("Error: 'copilot' not found in PATH.")- click.echo(- "Install GitHub Copilot CLI: "- "https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli"- )- raise SystemExit(1)-- effective_backend = backend or os.environ.get("HEADROOM_BACKEND")- if _check_proxy(port):- running_backend = _detect_running_proxy_backend(port)- if effective_backend and running_backend and effective_backend != running_backend:- raise click.ClickException(- f"Proxy already running on port {port} with backend '{running_backend}'. "- f"Stop it or rerun with --backend {running_backend}."- )- effective_backend = running_backend or effective_backend-- effective_provider_type = _resolve_copilot_provider_type(effective_backend, provider_type)- _validate_copilot_configuration(- provider_type=effective_provider_type,- wire_api=wire_api,- backend=effective_backend,- )-- 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)-- env = os.environ.copy()- openai_api_url: str | None = None- if _should_use_copilot_oauth(- backend=effective_backend,- provider_type=provider_type,- env=env,- ):- client_bearer = resolve_client_bearer_token()- if not client_bearer:- raise click.ClickException(- "GitHub Copilot auth was detected but no reusable bearer token could be resolved."- )-- effective_wire_api = wire_api or "completions"- env["COPILOT_PROVIDER_TYPE"] = "openai"- env["COPILOT_PROVIDER_BASE_URL"] = f"http://127.0.0.1:{port}/v1"- env["COPILOT_PROVIDER_WIRE_API"] = effective_wire_api- env["COPILOT_PROVIDER_BEARER_TOKEN"] = client_bearer- env.pop("COPILOT_PROVIDER_API_KEY", None)- env_vars_display = [- "COPILOT_PROVIDER_TYPE=openai",- f"COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:{port}/v1",- f"COPILOT_PROVIDER_WIRE_API={effective_wire_api}",- "COPILOT_AUTH_MODE=github-oauth",- ]- openai_api_url = COPILOT_API_URL- else:- env, env_vars_display = _build_copilot_launch_env(- port=port,- provider_type=effective_provider_type,- wire_api=wire_api,- environ=env,- )-- if not env.get("COPILOT_PROVIDER_API_KEY"):- src = _copilot_provider_key_source(effective_provider_type)- click.echo(- f"\n Error: Copilot BYOK mode requires a provider API key.\n"- f" `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's\n"- f" Copilot API and routes requests directly to the model provider through the\n"- f" Headroom proxy. A GitHub Copilot subscription alone is not sufficient.\n\n"- f" Set one of:\n"- f" export {src}=sk-... # recommended\n"- f" export COPILOT_PROVIDER_API_KEY=sk-... # also works\n"- )- raise SystemExit(1)-- if not _copilot_model_configured(copilot_args, env):- click.echo(- " Note: Copilot BYOK requires a model. Pass `--model <name>` "- "or set `COPILOT_MODEL` / `COPILOT_PROVIDER_MODEL_ID`."- )-- _launch_tool(- binary=copilot_bin,- args=copilot_args,- env=env,- port=port,- no_proxy=no_proxy,- tool_label="COPILOT",- env_vars_display=env_vars_display,- learn=False,- memory=memory,- agent_type="copilot",- backend=backend,- anyllm_provider=anyllm_provider,- region=region,- openai_api_url=openai_api_url,- )---# =============================================================================-# OpenAI Codex CLI-# =============================================================================--[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--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")- "--code-graph",- is_flag=True,- help="Enable code graph indexing via codebase-memory-mcp (optional)",-)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")- "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to AGENTS.md)"-)- "--backend",- default=None,- help="API backend for the proxy: 'anthropic', 'anyllm', 'litellm-vertex', etc. (env: HEADROOM_BACKEND)",-)- "--anyllm-provider",- default=None,- help="Provider for any-llm backend: openai, mistral, groq, etc. (env: HEADROOM_ANYLLM_PROVIDER)",-)- "--region", default=None, help="Cloud region for Bedrock/Vertex (env: HEADROOM_REGION)"-)[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("codex_args", nargs=-1, type=click.UNPROCESSED)-def codex(- port: int,- no_rtk: bool,- code_graph: bool,- no_proxy: bool,- learn: bool,- memory: bool,- backend: str | None,- anyllm_provider: str | None,- region: str | None,- verbose: bool,- prepare_only: bool,- codex_args: tuple,-) -> None:- """Launch OpenAI Codex CLI through Headroom proxy.-- \b- Sets 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).-- \b- Examples:- headroom wrap codex # Start proxy + rtk + codex- headroom wrap codex -- "fix the bug" # Pass prompt to codex- headroom wrap codex --no-rtk # Skip rtk setup- headroom wrap codex --port 9999 # Custom proxy port- headroom wrap codex --backend anyllm --anyllm-provider groq- """- # Setup rtk for Codex (binary + AGENTS.md instructions, no hooks)- 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)-- # Also inject into global ~/.codex/AGENTS.md- global_agents = Path.home() / ".codex" / "AGENTS.md"- _inject_rtk_instructions(global_agents, verbose=verbose)-- # Setup memory MCP server for Codex (native tool integration)- if memory:- click.echo(" Setting up memory for Codex...")- mem_dir = Path.cwd() / ".headroom"- mem_dir.mkdir(parents=True, exist_ok=True)- db_path = str(mem_dir / "memory.db")- mem_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))-- # Register MCP server in Codex config- _inject_memory_mcp_config(db_path, mem_user)-- # Inject memory guidance into project AGENTS.md- agents_md = Path.cwd() / "AGENTS.md"- _inject_memory_agents_md(agents_md)-- # Sync Claude's memories → DB so MCP search finds them- try:- import asyncio-- from headroom.memory.backends.local import LocalBackend, LocalBackendConfig- from headroom.memory.sync import sync_import- from headroom.memory.sync_adapters.claude_code import (- ClaudeCodeAdapter,- get_claude_memory_dir,- )-- claude_memory_dir = get_claude_memory_dir()-- async def _import_claude_memories() -> int:- config = LocalBackendConfig(db_path=db_path)- backend = LocalBackend(config)- await backend._ensure_initialized()- adapter = ClaudeCodeAdapter(claude_memory_dir)- count = await sync_import(backend, adapter, mem_user)- await backend.close()- return count-- imported = asyncio.run(_import_claude_memories())- if imported:- click.echo(f" Memory: imported {imported} memories from Claude")- except Exception as e:- click.echo(f" Warning: Claude memory import failed: {e}")-- if prepare_only:- _inject_codex_provider_config(port)- return-- codex_bin = shutil.which("codex")- if not codex_bin:- click.echo("Error: 'codex' not found in PATH.")- click.echo("Install Codex CLI: npm install -g @openai/codex")- raise SystemExit(1)-- env, env_vars_display = _build_codex_launch_env(port, os.environ)-- # 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.- # NOTE: this must run BEFORE _inject_memory_mcp_config because it rewrites- # the config file. Re-inject MCP config after if memory is enabled.- _inject_codex_provider_config(port)- if memory:- mem_dir = Path.cwd() / ".headroom"- _inject_memory_mcp_config(- str(mem_dir / "memory.db"),- os.environ.get("USER", os.environ.get("USERNAME", "default")),- )-- _launch_tool(- binary=codex_bin,- args=codex_args,- env=env,- port=port,- no_proxy=no_proxy,- tool_label="CODEX",- env_vars_display=env_vars_display,- learn=learn,- memory=memory,- agent_type="codex",- code_graph=code_graph,- backend=backend,- anyllm_provider=anyllm_provider,- region=region,- )---# =============================================================================-# Aider-# =============================================================================--[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--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")- "--code-graph",- is_flag=True,- help="Enable code graph indexing via codebase-memory-mcp (optional)",-)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")[email protected]("--learn", is_flag=True, help="Enable live traffic learning")[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")- "--backend", default=None, help="API backend: 'anthropic', 'anyllm', 'litellm-vertex', etc."-)[email protected]("--anyllm-provider", default=None, help="Provider for any-llm backend")[email protected]("--region", default=None, help="Cloud region for Bedrock/Vertex")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("aider_args", nargs=-1, type=click.UNPROCESSED)-def aider(- port: int,- no_rtk: bool,- code_graph: bool,- no_proxy: bool,- learn: bool,- memory: bool,- backend: str | None,- anyllm_provider: str | None,- region: str | None,- verbose: bool,- prepare_only: bool,- aider_args: tuple,-) -> None:- """Launch aider through Headroom proxy.-- \b- Sets 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.-- \b- Examples:- headroom wrap aider # Start proxy + rtk + aider- headroom wrap aider -- --model gpt-4o # Use GPT-4o- headroom wrap aider -- --model claude-sonnet-4 # Use Claude- headroom wrap aider --no-rtk # Skip rtk setup- headroom wrap aider --backend litellm-vertex --region us-central1- """- # Setup rtk for aider (binary + CONVENTIONS.md instructions)- 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 prepare_only:- return-- aider_bin = shutil.which("aider")- if not aider_bin:- click.echo("Error: 'aider' not found in PATH.")- click.echo("Install aider: pip install aider-chat")- raise SystemExit(1)-- env, env_vars_display = _build_aider_launch_env(port, os.environ)-- _launch_tool(- binary=aider_bin,- args=aider_args,- env=env,- port=port,- no_proxy=no_proxy,- tool_label="AIDER",- env_vars_display=env_vars_display,- learn=learn,- memory=memory,- agent_type="aider",- code_graph=code_graph,- backend=backend,- anyllm_provider=anyllm_provider,- region=region,- )---# =============================================================================-# Cursor-# =============================================================================--[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--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")[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")- "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to .cursor/rules/)"-)[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)-def cursor(- port: int,- no_rtk: bool,- no_proxy: bool,- learn: bool,- memory: bool,- verbose: bool,- prepare_only: bool,-) -> None:- """Start Headroom proxy for use with Cursor.-- \b- Cursor 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.-- \b- After running this command, open Cursor and configure:- Settings > Models > OpenAI API Key > Advanced > Override Base URL-- \b- Example:- headroom wrap cursor # Start proxy + rtk + instructions- headroom wrap cursor --no-rtk # Proxy only, no rtk- headroom 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 prepare_only:- return-- proxy_holder: list[subprocess.Popen | None] = [None]- cleanup = _make_cleanup(proxy_holder, port)- signal.signal(signal.SIGINT, cleanup)- signal.signal(signal.SIGTERM, cleanup)-- try:- click.echo()- click.echo(" ╔═══════════════════════════════════════════════╗")- click.echo(" ║ HEADROOM WRAP: CURSOR ║")- click.echo(" ╚═══════════════════════════════════════════════╝")- click.echo()-- proxy_holder[0] = _ensure_proxy(- port, no_proxy, learn=learn, memory=memory, agent_type="cursor"- )-- click.echo()- for line in _render_cursor_setup_lines(port):- click.echo(line)- if not no_rtk:- click.echo()- 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.")- click.echo()-- # Block until Ctrl+C- try:- while True:- time.sleep(1)- proc = proxy_holder[0]- if proc and proc.poll() is not None:- click.echo(" Proxy process exited unexpectedly.")- raise SystemExit(1)- except KeyboardInterrupt:- click.echo("\n Shutting down...")-- except SystemExit:- raise- except Exception as e:- click.echo(f" Error: {e}")- raise SystemExit(1) from e- finally:- cleanup()---# =============================================================================-# OpenClaw-# =============================================================================--[email protected]("openclaw")- "--plugin-path",- type=click.Path(path_type=Path, file_okay=False, dir_okay=True),- default=None,- help="Path to local OpenClaw plugin source directory (advanced/dev override)",-)- "--plugin-spec",- default="headroom-ai/openclaw",- show_default=True,- help="NPM plugin spec for OpenClaw install (used when --plugin-path is omitted)",-)- "--skip-build",- is_flag=True,- help="Skip npm install/build in local source mode (--plugin-path)",-)- "--copy",- is_flag=True,- help="Install by copying plugin path instead of using --link",-)[email protected]("--proxy-port", default=8787, type=int, help="Headroom proxy port")[email protected]("--startup-timeout-ms", default=20000, type=int, help="Proxy startup timeout")- "--gateway-provider-id",- "gateway_provider_ids",- multiple=True,- help="OpenClaw provider id to route through Headroom (repeatable; default: openai-codex)",-)- "--python-path",- default=None,- help="Optional Python executable for proxy launcher fallback",-)- "--no-auto-start",- is_flag=True,- help="Disable plugin auto-start of local headroom proxy",-)- "--no-restart",- is_flag=True,- help="Do not restart OpenClaw gateway at the end",-)[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("--existing-entry-json", default=None, hidden=True)-def openclaw(- plugin_path: Path | None,- plugin_spec: str,- skip_build: bool,- copy: bool,- proxy_port: int,- startup_timeout_ms: int,- gateway_provider_ids: tuple[str, ...],- python_path: str | None,- no_auto_start: bool,- no_restart: bool,- verbose: bool,- prepare_only: bool,- existing_entry_json: str | None,-) -> None:- """Install and configure Headroom OpenClaw plugin in one command.-- \b- What this command does:- 1. Installs OpenClaw plugin from npm (or local --plugin-path)- 2. Builds plugin source if --plugin-path is used- 3. Writes minimal plugin config and sets contextEngine slot- 4. Validates config- 5. Restarts OpenClaw gateway (unless --no-restart)-- \b- Example:- headroom wrap openclaw- headroom wrap openclaw --plugin-path C:\\git\\headroom\\plugins\\openclaw- """- if prepare_only:- entry = _build_openclaw_plugin_entry(- existing_entry=_decode_openclaw_entry_json(existing_entry_json),- proxy_port=proxy_port,- startup_timeout_ms=startup_timeout_ms,- python_path=python_path,- no_auto_start=no_auto_start,- gateway_provider_ids=gateway_provider_ids,- enabled=True,- )- click.echo(json.dumps(entry, separators=(",", ":")))- return-- openclaw_bin = shutil.which("openclaw")- if not openclaw_bin:- raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")-- plugin_dir = plugin_path.resolve() if plugin_path else None- local_source_mode = plugin_dir is not None- if plugin_dir:- if not plugin_dir.exists():- raise click.ClickException(f"Plugin path not found: {plugin_dir}.")- if not (plugin_dir / "package.json").exists():- raise click.ClickException(f"Invalid plugin path (missing package.json): {plugin_dir}")- if not (plugin_dir / "openclaw.plugin.json").exists():- raise click.ClickException(- f"Invalid plugin path (missing openclaw.plugin.json): {plugin_dir}"- )-- npm_bin = shutil.which("npm")- if local_source_mode and not skip_build and not npm_bin:- raise click.ClickException(- "'npm' not found in PATH. Install Node/npm or rerun with --skip-build."- )-- click.echo()- click.echo(" ╔═══════════════════════════════════════════════╗")- click.echo(" ║ HEADROOM WRAP: OPENCLAW ║")- click.echo(" ╚═══════════════════════════════════════════════╝")- click.echo()- if local_source_mode:- click.echo(f" Plugin source: local ({plugin_dir})")- else:- click.echo(f" Plugin source: npm ({plugin_spec})")-- if local_source_mode and not skip_build:- click.echo(" Building OpenClaw plugin (npm install + npm run build)...")- _run_checked([npm_bin or "npm", "install"], cwd=plugin_dir, action="npm install")- _run_checked([npm_bin or "npm", "run", "build"], cwd=plugin_dir, action="npm run build")- elif not local_source_mode and skip_build:- click.echo(" Skipping build: npm install mode does not build local source.")-- effective_python_path = python_path- if effective_python_path is None and not no_auto_start and sys.executable:- effective_python_path = sys.executable-- existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")- entry = _build_openclaw_plugin_entry(- existing_entry=existing_entry,- proxy_port=proxy_port,- startup_timeout_ms=startup_timeout_ms,- python_path=effective_python_path,- no_auto_start=no_auto_start,- gateway_provider_ids=gateway_provider_ids,- enabled=True,- )-- click.echo(" Writing plugin configuration...")- _write_openclaw_plugin_entry(openclaw_bin, entry)-- install_cmd = [- openclaw_bin,- "plugins",- "install",- "--dangerously-force-unsafe-install",- ]- if local_source_mode:- if copy:- install_cmd.append(str(plugin_dir))- install_cwd = None- else:- install_cmd.extend(["--link", "."])- install_cwd = plugin_dir- else:- install_cmd.append(plugin_spec)- install_cwd = None-- click.echo(" Installing OpenClaw plugin with required unsafe-install flag...")- install_result = subprocess.run(- install_cmd,- cwd=str(install_cwd) if install_cwd else None,- capture_output=True,- text=True,- encoding="utf-8",- errors="replace",- )- if install_result.returncode != 0:- combined_error = "\n".join(- x for x in [install_result.stderr.strip(), install_result.stdout.strip()] if x- )- plugin_already_exists = "plugin already exists" in combined_error.lower()- linked_install_bug = (- "also not a valid hook pack" in combined_error.lower()- and "--dangerously-force-unsafe-install" in " ".join(install_cmd)- )- if plugin_already_exists:- click.echo(" Plugin already installed; continuing with configuration/update steps.")- elif linked_install_bug and local_source_mode and plugin_dir is not None:- click.echo(- " OpenClaw linked-path install bug detected; applying extension-path fallback..."- )- target_dir = _copy_openclaw_plugin_into_extensions(- plugin_dir=plugin_dir,- openclaw_bin=openclaw_bin,- )- click.echo(f" Fallback plugin copy completed: {target_dir}")- else:- details = combined_error or f"exit code {install_result.returncode}"- raise click.ClickException(f"openclaw plugins install failed: {details}")- elif verbose and install_result.stdout.strip():- click.echo(install_result.stdout.strip())-- _set_openclaw_context_engine_slot(openclaw_bin, "headroom")- _run_checked(- [openclaw_bin, "config", "validate"],- action="openclaw config validate",- )-- if no_restart:- click.echo(" Skipping gateway restart (--no-restart).")- click.echo(- " Run `openclaw gateway restart` (or `openclaw gateway start`) to apply plugin changes."- )- else:- click.echo(" Applying plugin changes to OpenClaw gateway...")- gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)- click.echo(f" Gateway {gateway_action}.")- if verbose and gateway_output:- click.echo(gateway_output)-- inspect_result = _run_checked(- [openclaw_bin, "plugins", "inspect", "headroom"],- action="openclaw plugins inspect headroom",- )- if verbose and inspect_result.stdout.strip():- click.echo(inspect_result.stdout.strip())-- click.echo()- click.echo("✓ OpenClaw is configured to use Headroom context compression.")- click.echo(" Plugin: headroom")- click.echo(" Slot: plugins.slots.contextEngine = headroom")- click.echo()--[email protected]("openclaw")[email protected]("--no-restart", is_flag=True, help="Do not restart OpenClaw gateway at the end")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("--existing-entry-json", default=None, hidden=True)-def unwrap_openclaw(- no_restart: bool,- verbose: bool,- prepare_only: bool,- existing_entry_json: str | None,-) -> None:- """Disable the Headroom OpenClaw plugin and restore the legacy engine slot."""- if prepare_only:- click.echo(- json.dumps(- _build_openclaw_unwrap_entry(_decode_openclaw_entry_json(existing_entry_json)),- separators=(",", ":"),- )- )- return-- openclaw_bin = shutil.which("openclaw")- if not openclaw_bin:- raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")-- click.echo()- click.echo(" ╔═══════════════════════════════════════════════╗")- click.echo(" ║ HEADROOM UNWRAP: OPENCLAW ║")- click.echo(" ╚═══════════════════════════════════════════════╝")- click.echo()- click.echo(" Disabling Headroom plugin and removing engine mapping...")-- existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")- entry = _build_openclaw_unwrap_entry(existing_entry)- _write_openclaw_plugin_entry(openclaw_bin, entry)- _set_openclaw_context_engine_slot(openclaw_bin, "legacy")- _run_checked(- [openclaw_bin, "config", "validate"],- action="openclaw config validate",- )-- if no_restart:- click.echo(" Skipping gateway restart (--no-restart).")- click.echo(- " Run `openclaw gateway restart` (or `openclaw gateway start`) to apply unwrap changes."- )- else:- click.echo(" Applying unwrap changes to OpenClaw gateway...")- gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)- click.echo(f" Gateway {gateway_action}.")- if verbose and gateway_output:- click.echo(gateway_output)-- if verbose:- inspect_result = _run_checked(- [openclaw_bin, "plugins", "inspect", "headroom"],- action="openclaw plugins inspect headroom",- )- if inspect_result.stdout.strip():- click.echo(inspect_result.stdout.strip())-- click.echo()- click.echo("✓ OpenClaw Headroom wrap removed.")- click.echo(" Plugin: headroom (installed, disabled)")- click.echo(" Slot: plugins.slots.contextEngine = legacy")- click.echo()---# =============================================================================-# OpenAI Codex CLI (unwrap)-# =============================================================================--[email protected]("codex")-def unwrap_codex() -> None:- """Undo ``headroom wrap codex`` edits to ``~/.codex/config.toml``.-- Behaviour:-- * If a pre-wrap backup (``config.toml.headroom-backup``) exists, the- original file is restored byte-for-byte and the backup is removed.- * Otherwise, if the config file still contains the Headroom-managed- block, that block is stripped out and the rest of the file is- preserved.- * If the config only ever contained Headroom-written content, the file- is removed entirely so Codex falls back to its defaults.- * If neither a backup nor a Headroom block is present, this is a safe- no-op (the user either never wrapped, or already unwrapped).- """- click.echo()- click.echo(" ╔═══════════════════════════════════════════════╗")- click.echo(" ║ HEADROOM UNWRAP: CODEX ║")- click.echo(" ╚═══════════════════════════════════════════════╝")- click.echo()-- try:- status, config_file = _restore_codex_provider_config()- except Exception as e: # pragma: no cover - filesystem-level errors- raise click.ClickException(f"could not unwrap Codex config: {e}") from e-- if status == "restored":- click.echo(f" Restored prior {config_file} from pre-wrap backup.")- elif status == "cleaned":- click.echo(f" Removed Headroom block from {config_file}; other content preserved.")- elif status == "removed":- click.echo(f" Removed {config_file} (contained only Headroom-written config).")- else:- click.echo(f" Nothing to undo: {config_file} has no Headroom wrap markers.")-- click.echo()- click.echo("✓ Codex is no longer routed through the Headroom proxy.")- click.echo()+"""Wrap CLI commands to run through Headroom proxy.++Usage:+ headroom wrap claude # Start proxy + rtk + claude+ headroom wrap copilot -- --model ... # Start proxy + launch GitHub Copilot CLI+ headroom wrap codex # Start proxy + OpenAI Codex CLI+ headroom wrap aider # Start proxy + aider+ headroom wrap cursor # Start proxy + print Cursor config instructions+ headroom wrap openclaw # Install + configure OpenClaw plugin+ headroom wrap claude --no-rtk # Without rtk hooks+ headroom wrap claude --port 9999 # Custom proxy port+ headroom wrap claude -- --model opus # Pass args to claude+"""++from __future__ import annotations++import io+import json+import os+import shutil+import signal+import socket+import subprocess+import sys+import time+from pathlib import Path+from typing import Any, cast++# Fix Windows cp1252 encoding — box-drawing characters require UTF-8+if sys.platform == "win32" and hasattr(sys.stdout, "buffer"):+ if sys.stdout.encoding and sys.stdout.encoding.lower().replace("-", "") != "utf8":+ sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")+ sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")++import click++from headroom.copilot_auth import DEFAULT_API_URL as COPILOT_API_URL+from headroom.copilot_auth import has_oauth_auth, resolve_client_bearer_token+from headroom.providers.aider import build_launch_env as _build_aider_launch_env+from headroom.providers.claude import proxy_base_url as _claude_proxy_base_url+from headroom.providers.codex import build_launch_env as _build_codex_launch_env+from headroom.providers.copilot import (+ build_launch_env as _build_copilot_launch_env,+)+from headroom.providers.copilot import (+ detect_running_proxy_backend as _copilot_detect_running_proxy_backend,+)+from headroom.providers.copilot import (+ model_configured as _copilot_model_configured_impl,+)+from headroom.providers.copilot import (+ provider_key_source as _copilot_provider_key_source,+)+from headroom.providers.copilot import (+ query_proxy_config as _copilot_query_proxy_config,+)+from headroom.providers.copilot import (+ resolve_provider_type as _copilot_resolve_provider_type,+)+from headroom.providers.copilot import (+ validate_configuration as _validate_copilot_configuration,+)+from headroom.providers.cursor import render_setup_lines as _render_cursor_setup_lines+from headroom.providers.openclaw import (+ build_plugin_entry as _build_openclaw_plugin_entry_impl,+)+from headroom.providers.openclaw import (+ build_unwrap_entry as _build_openclaw_unwrap_entry_impl,+)+from headroom.providers.openclaw import (+ decode_entry_json as _decode_openclaw_entry_json_impl,+)+from headroom.providers.openclaw import (+ normalize_gateway_provider_ids as _normalize_openclaw_gateway_provider_ids_impl,+)++from .main import main+++def _live_wrap_module() -> Any:+ """Return the current live wrap module instance."""+ return cast(Any, sys.modules[__name__])+++def _print_telemetry_notice() -> None:+ """Print a telemetry notice when anonymous telemetry is enabled.++ Respects the HEADROOM_TELEMETRY and HEADROOM_TELEMETRY_WARN feature flags.+ Does nothing when telemetry or warnings are disabled.+ """+ from headroom.telemetry.beacon import format_telemetry_notice++ notice = format_telemetry_notice(prefix=" ")+ if notice:+ click.echo(notice)+++# Proxy health check (reused from evals/suite_runner.py pattern)+++def _check_proxy(port: int) -> bool:+ """Check if Headroom proxy is running on given port."""+ try:+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:+ s.settimeout(1)+ s.connect(("127.0.0.1", port))+ return True+ except (TimeoutError, ConnectionRefusedError, OSError):+ return False+++def _get_log_path() -> Path:+ """Get path for proxy log file."""+ from headroom import paths as _paths++ log_dir = _paths.log_dir()+ log_dir.mkdir(parents=True, exist_ok=True)+ return log_dir / "proxy.log"+++def _start_proxy(+ port: int,+ *,+ learn: bool = False,+ memory: bool = False,+ agent_type: str = "unknown",+ code_graph: bool = False,+ backend: str | None = None,+ anyllm_provider: str | None = None,+ region: str | None = None,+ openai_api_url: str | None = None,+) -> subprocess.Popen:+ """Start Headroom proxy as a background subprocess.++ Logs are written to ~/.headroom/logs/proxy.log to avoid pipe buffer+ deadlocks (macOS pipe buffer is ~64KB — a busy proxy fills it quickly,+ blocking the process).+ """+ cmd = [sys.executable, "-m", "headroom.cli", "proxy", "--port", str(port)]++ # Forward HEADROOM_MODE env var so the proxy respects the user's mode choice+ headroom_mode = os.environ.get("HEADROOM_MODE")+ if headroom_mode:+ cmd.extend(["--mode", headroom_mode])++ # Forward --learn flag to proxy subprocess+ if learn:+ cmd.append("--learn")++ # Forward --memory flag to proxy subprocess+ if memory:+ cmd.append("--memory")++ # Forward --code-graph flag to proxy subprocess (live file watcher)+ if code_graph:+ cmd.append("--code-graph")++ # Forward backend configuration to proxy subprocess+ _backend = backend or os.environ.get("HEADROOM_BACKEND")+ if _backend:+ cmd.extend(["--backend", _backend])++ _anyllm = anyllm_provider or os.environ.get("HEADROOM_ANYLLM_PROVIDER")+ if _anyllm:+ cmd.extend(["--anyllm-provider", _anyllm])++ _region = region or os.environ.get("HEADROOM_REGION")+ if _region:+ cmd.extend(["--region", _region])++ if openai_api_url:+ cmd.extend(["--openai-api-url", openai_api_url])++ log_path = _get_log_path()+ log_file = open(log_path, "a") # noqa: SIM115++ # Ensure proxy subprocess uses UTF-8 (Windows defaults to cp1252)+ proxy_env = os.environ.copy()+ proxy_env["PYTHONIOENCODING"] = "utf-8"++ # Tell the proxy which agent is being wrapped (for traffic learning output)+ if agent_type != "unknown":+ proxy_env["HEADROOM_AGENT_TYPE"] = agent_type+ proxy_env.setdefault("HEADROOM_STACK", f"wrap_{agent_type}")++ proc = subprocess.Popen(+ cmd,+ stdout=log_file,+ stderr=log_file,+ env=proxy_env,+ )++ # Wait for proxy to be ready (up to 45 seconds).+ # ML components (Kompress, Magika, Tree-sitter) load synchronously before+ # uvicorn binds the port. On slower machines this can take 20-30 seconds.+ for _i in range(45):+ time.sleep(1)+ if _check_proxy(port):+ click.echo(f" Logs: {log_path}")+ return proc+ # Check if process died+ if proc.poll() is not None:+ log_file.close()+ # Read last few lines of log for error context+ try:+ tail = log_path.read_text()[-500:]+ except Exception:+ tail = "(no log output)"+ raise RuntimeError(f"Proxy exited with code {proc.returncode}: {tail}")++ proc.kill()+ log_file.close()+ raise RuntimeError(f"Proxy failed to start on port {port} within 45 seconds")+++def _setup_rtk(verbose: bool = False) -> Path | None:+ """Ensure rtk is installed and hooks are registered."""+ from headroom.rtk import get_rtk_path+ from headroom.rtk.installer import ensure_rtk, register_claude_hooks++ rtk_path = get_rtk_path()++ if rtk_path:+ if verbose:+ click.echo(f" rtk found at {rtk_path}")+ else:+ click.echo(" Downloading rtk (Rust Token Killer)...")+ rtk_path = ensure_rtk()+ if rtk_path:+ click.echo(f" rtk installed at {rtk_path}")+ else:+ click.echo(" rtk download failed — continuing without it")+ return None++ # Register hooks (idempotent)+ if register_claude_hooks(rtk_path):+ if verbose:+ click.echo(" rtk hooks registered in Claude Code")+ else:+ click.echo(" rtk hook registration failed — continuing without it")++ return rtk_path+++_CBM_MCP_SERVER_NAME = "codebase-memory-mcp"+++def _register_cbm_mcp_server(cbm_bin: str) -> None:+ """Register codebase-memory-mcp as an MCP server in Claude Code.++ Uses ``claude mcp add`` so the tools appear in ``/mcp`` automatically.+ Idempotent — skips if already registered.+ """+ claude_cli = shutil.which("claude")+ if not claude_cli:+ return++ # Check if already registered+ check = subprocess.run(+ [claude_cli, "mcp", "get", _CBM_MCP_SERVER_NAME],+ capture_output=True,+ text=True,+ )+ if check.returncode == 0:+ return # Already registered++ result = subprocess.run(+ [claude_cli, "mcp", "add", _CBM_MCP_SERVER_NAME, "-s", "user", "--", cbm_bin],+ capture_output=True,+ text=True,+ )+ if result.returncode == 0:+ click.echo(f" Code graph: registered {_CBM_MCP_SERVER_NAME} MCP server")+ else:+ pass # Non-critical — tools won't appear in /mcp but graph still works+++def _setup_code_graph(verbose: bool = False) -> bool:+ """Ensure codebase-memory-mcp is installed, registered as MCP server, and project is indexed.++ codebase-memory-mcp builds a knowledge graph of the codebase using+ tree-sitter, enabling the LLM to query code structure (call chains,+ function definitions, impact analysis) instead of reading entire files.++ Steps:+ 1. Download the binary if not already present.+ 2. Register as an MCP server in Claude Code (``claude mcp add``).+ 3. Index the current project (fast, idempotent).++ With Claude Code's MCP Tool Search, the 14 graph tools add ~200 tokens+ overhead per request (not the full ~1,915) — they're lazy-loaded.++ Returns True if graph is ready, False if setup failed.+ """+ from headroom.graph.installer import ensure_cbm, get_cbm_path++ cbm_path = get_cbm_path()+ if not cbm_path:+ click.echo(" Code graph: downloading codebase-memory-mcp...")+ cbm_path = ensure_cbm()+ if cbm_path:+ click.echo(f" Code graph: installed at {cbm_path}")+ else:+ click.echo(" Code graph: download failed — skipping")+ return False++ cbm_bin = str(cbm_path)++ # Register as MCP server so tools appear in /mcp+ _register_cbm_mcp_server(cbm_bin)++ # Index current project (fast — ~1s for most repos, idempotent)+ project_dir = str(Path.cwd())+ try:+ result = subprocess.run(+ [+ cbm_bin,+ "cli",+ "index_repository",+ json.dumps({"repo_path": project_dir, "mode": "fast"}),+ ],+ capture_output=True,+ text=True,+ timeout=30,+ )+ if result.returncode == 0:+ # Parse node/edge counts from output+ for line in result.stdout.splitlines():+ if '"nodes"' in line:+ try:+ # Parse the JSON response to extract node/edge counts+ import re++ m_nodes = re.search(r'"nodes":(\d+)', line)+ m_edges = re.search(r'"edges":(\d+)', line)+ if m_nodes and m_edges:+ nodes = int(m_nodes.group(1))+ edges = int(m_edges.group(1))+ click.echo(+ f" Code graph: indexed ({nodes:,} symbols, "+ f"{edges:,} relationships)"+ )+ else:+ click.echo(" Code graph: indexed")+ except (ValueError, AttributeError):+ click.echo(" Code graph: indexed")+ return True+ click.echo(" Code graph: indexed")+ return True+ else:+ if verbose:+ click.echo(f" Code graph: indexing failed ({result.stderr[:100]})")+ return False+ except subprocess.TimeoutExpired:+ click.echo(" Code graph: indexing timed out (will complete in background)")+ return False+ except Exception as e:+ if verbose:+ click.echo(f" Code graph: setup failed ({e})")+ return False+++# rtk instructions for tools without hook support (Codex, Cursor, Aider).+# These get injected into AGENTS.md / .cursorrules so the LLM voluntarily+# uses rtk-prefixed commands. Kept concise to minimize instruction overhead.+RTK_INSTRUCTIONS_BLOCK = """\+<!-- headroom:rtk-instructions -->+# RTK (Rust Token Killer) - Token-Optimized Commands++When running shell commands, **always prefix with `rtk`**. This reduces context+usage by 60-90% with zero behavior change. If rtk has no filter for a command,+it passes through unchanged — so it is always safe to use.++## Key Commands+```bash+# Git (59-80% savings)+rtk git status rtk git diff rtk git log++# Files & Search (60-75% savings)+rtk ls <path> rtk read <file> rtk grep <pattern>+rtk find <pattern> rtk diff <file>++# Test (90-99% savings) — shows failures only+rtk pytest tests/ rtk cargo test rtk test <cmd>++# Build & Lint (80-90% savings) — shows errors only+rtk tsc rtk lint rtk cargo build+rtk prettier --check rtk mypy rtk ruff check++# Analysis (70-90% savings)+rtk err <cmd> rtk log <file> rtk json <file>+rtk summary <cmd> rtk deps rtk env++# GitHub (26-87% savings)+rtk gh pr view <n> rtk gh run list rtk gh issue list++# Infrastructure (85% savings)+rtk docker ps rtk kubectl get rtk docker logs <c>++# Package managers (70-90% savings)+rtk pip list rtk pnpm install rtk npm run <script>+```++## Rules+- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`+- For debugging, use raw command without rtk prefix+- `rtk proxy <cmd>` runs command without filtering but tracks usage+<!-- /headroom:rtk-instructions -->+"""++# Marker used to detect if instructions are already injected+_RTK_MARKER = "<!-- headroom:rtk-instructions -->"++# Memory MCP markers+_MEMORY_MCP_MARKER = "# --- Headroom memory MCP (auto-injected) ---"+_MEMORY_MCP_END = "# --- end Headroom memory ---"+_MEMORY_AGENTS_MARKER = "<!-- headroom:memory-instructions -->"++# Codex config injection markers+_CODEX_TOP_LEVEL_MARKER = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"+_CODEX_END_MARKER = "# --- end Headroom ---"+# File name used for the pre-wrap snapshot of ~/.codex/config.toml. The+# snapshot lets `headroom unwrap codex` restore the exact prior state, even+# if the user had their own `model_provider` / `[model_providers.*]` config+# before running wrap.+_CODEX_CONFIG_BACKUP_SUFFIX = ".headroom-backup"+++def _codex_config_paths() -> tuple[Path, Path]:+ """Return ``(config_file, backup_file)`` paths for the Codex TOML config."""+ config_dir = Path.home() / ".codex"+ config_file = config_dir / "config.toml"+ backup_file = config_dir / f"config.toml{_CODEX_CONFIG_BACKUP_SUFFIX}"+ return config_file, backup_file+++def _strip_codex_headroom_blocks(content: str) -> str:+ """Remove all Headroom-managed blocks from a Codex ``config.toml`` string.++ Returns the cleaned content. Safe to call on content that never contained+ any markers — it will be returned effectively unchanged (only trailing+ whitespace is normalized).+ """+ import re++ # Remove any top-level-marker → end-marker span, possibly repeated.+ while _CODEX_TOP_LEVEL_MARKER in content and _CODEX_END_MARKER in content:+ start = content.index(_CODEX_TOP_LEVEL_MARKER)+ end_idx = content.index(_CODEX_END_MARKER, start)+ if end_idx < start:+ break+ end = end_idx + len(_CODEX_END_MARKER)+ content = content[:start].rstrip("\n") + "\n" + content[end:].lstrip("\n")++ # Remove any stale top-level marker or end marker that lost its partner+ # (e.g. a crashed prior wrap).+ content = content.replace(_CODEX_TOP_LEVEL_MARKER + "\n", "")+ content = content.replace(_CODEX_END_MARKER + "\n", "")++ # Strip any leftover top-level `model_provider = "headroom"` line, which+ # older versions of `wrap codex` wrote outside the marker block.+ content = re.sub(r'(?m)^[ \t]*model_provider[ \t]*=[ \t]*"headroom"[ \t]*\r?\n', "", content)++ # Strip any orphaned `[model_providers.headroom]` table with the fields we+ # write. We only remove it if the table is recognisably ours (base_url+ # mentions localhost and a Headroom proxy port). This protects users who+ # happen to have a differently configured `headroom` provider.+ orphan_headroom_table = re.compile(+ r"(?ms)^\[model_providers\.headroom\][^\[]*?"+ r'base_url[ \t]*=[ \t]*"http://127\.0\.0\.1:\d+/v1"[^\[]*?'+ r"(?=^\[|\Z)"+ )+ content = orphan_headroom_table.sub("", content)++ return content.lstrip("\n").rstrip() + "\n" if content.strip() else ""+++def _snapshot_codex_config_if_unwrapped(config_file: Path, backup_file: Path) -> None:+ """Snapshot ``config.toml`` to ``backup_file`` before the first injection.++ Called as the first step of every Headroom injection into Codex's+ ``config.toml``. Guarantees that ``headroom unwrap codex`` can restore the+ user's original file byte-for-byte.++ Rules:++ * If the backup already exists, leave it alone — we only snapshot the+ *pre-wrap* state, so running wrap repeatedly must not clobber it.+ * If the config file doesn't exist yet, there's nothing to back up; unwrap+ will remove the file entirely instead of restoring a snapshot.+ * If the config already contains a Headroom marker, a wrap run is already+ active: do not snapshot the injected state.+ """+ if backup_file.exists():+ return+ if not config_file.exists():+ return+ try:+ content = config_file.read_text()+ except OSError:+ return+ if _CODEX_TOP_LEVEL_MARKER in content or _CODEX_END_MARKER in content:+ return+ backup_file.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(config_file, backup_file)+++def _ensure_rtk_binary(verbose: bool = False) -> Path | None:+ """Ensure rtk binary is installed (download if needed). No hook registration."""+ from headroom.rtk import get_rtk_path+ from headroom.rtk.installer import ensure_rtk++ rtk_path = get_rtk_path()++ if rtk_path:+ if verbose:+ click.echo(f" rtk found at {rtk_path}")+ return rtk_path++ click.echo(" Downloading rtk (Rust Token Killer)...")+ rtk_path = ensure_rtk()+ if rtk_path:+ click.echo(f" rtk installed at {rtk_path}")+ return rtk_path++ click.echo(" rtk download failed — continuing without it")+ return None+++def _prepare_wrap_rtk(verbose: bool = False, *, label: str | None = None) -> Path | None:+ """Ensure rtk is present for host-bridged wrap flows without host-specific setup."""+ if label:+ click.echo(f" Preparing rtk for {label}...")+ return _ensure_rtk_binary(verbose=verbose)+++def _inject_codex_provider_config(port: int) -> None:+ """Inject a Headroom model provider into Codex's config.toml.++ Codex ignores OPENAI_BASE_URL for WebSocket transport unless a custom+ provider declares ``supports_websockets = true``. This writes a+ ``[model_providers.headroom]`` section that routes both HTTP and WS+ through the proxy, and sets ``model_provider = "headroom"``.++ Safe to call multiple times — the injected block is fully replaced on+ each call, so re-running with a different ``port`` updates the config.+ Before the first injection, the pre-wrap file is snapshotted to+ ``~/.codex/config.toml.headroom-backup`` so ``headroom unwrap codex``+ can restore it byte-for-byte.+ """+ config_file, backup_file = _codex_config_paths()+ config_dir = config_file.parent++ # The injected content is split into two self-contained, marker-delimited+ # blocks: a top-level key block (at the start of the file, because bare+ # TOML keys must precede any [section]) and a provider-table block (at+ # the end). Each block has its own matching begin/end marker pair so+ # stripping them is unambiguous and never consumes user content that+ # happens to sit between the two.+ top_level_block = (+ f'{_CODEX_TOP_LEVEL_MARKER}\nmodel_provider = "headroom"\n{_CODEX_END_MARKER}\n'+ )+ provider_section = (+ f"{_CODEX_TOP_LEVEL_MARKER}\n"+ "[model_providers.headroom]\n"+ 'name = "OpenAI via Headroom proxy"\n'+ f'base_url = "http://127.0.0.1:{port}/v1"\n'+ f'env_key = "OPENAI_API_KEY"\n'+ f"requires_openai_auth = true\n"+ f"supports_websockets = true\n"+ f"{_CODEX_END_MARKER}\n"+ )++ try:+ config_dir.mkdir(parents=True, exist_ok=True)++ # Snapshot the pre-wrap state before touching anything. No-op if the+ # config is already wrapped, is missing, or we've already snapshotted.+ _snapshot_codex_config_if_unwrapped(config_file, backup_file)++ if config_file.exists():+ content = config_file.read_text()+ # Remove any prior Headroom-managed blocks before re-injecting so+ # the operation is idempotent and supports port changes.+ content = _strip_codex_headroom_blocks(content)++ # Place the top-level key block at the very beginning of the file+ # (bare TOML keys must precede any [section]) and the provider+ # table at the end. User content, if any, sits between them.+ user_content = content.strip()+ if user_content:+ content = top_level_block + "\n" + user_content + "\n\n" + provider_section+ else:+ content = top_level_block + "\n" + provider_section+ else:+ content = top_level_block + "\n" + provider_section++ config_file.write_text(content)+ click.echo(f" Codex config: injected Headroom provider (WS + HTTP) into {config_file}")+ except Exception as e:+ click.echo(f" Warning: could not update Codex config: {e}")+++def _restore_codex_provider_config() -> tuple[str, Path]:+ """Undo ``_inject_codex_provider_config`` for ``~/.codex/config.toml``.++ Returns a tuple of ``(status, config_file)`` where status is one of:++ * ``"restored"`` — a pre-wrap backup existed and was restored; backup+ file has been removed.+ * ``"cleaned"`` — no backup existed, but the Headroom-managed block was+ found and stripped out (preserving surrounding user content).+ * ``"removed"`` — the config file only contained Headroom-managed+ content (created by wrap) and has been deleted.+ * ``"noop"`` — nothing to undo; no Headroom marker and no backup.+ """+ config_file, backup_file = _codex_config_paths()++ # Case 1: pre-wrap snapshot exists — restore it exactly.+ if backup_file.exists():+ shutil.copy2(backup_file, config_file)+ backup_file.unlink()+ return "restored", config_file++ # Case 2: no backup, but config file exists and has markers — strip them.+ if config_file.exists():+ original = config_file.read_text()+ if _CODEX_TOP_LEVEL_MARKER in original or _CODEX_END_MARKER in original:+ cleaned = _strip_codex_headroom_blocks(original)+ if not cleaned.strip():+ # Nothing left but Headroom content — remove the file entirely+ # so Codex falls back to its default config.+ config_file.unlink()+ return "removed", config_file+ config_file.write_text(cleaned)+ return "cleaned", config_file++ # Nothing to undo.+ return "noop", config_file+++def _inject_rtk_instructions(file_path: Path, verbose: bool = False) -> bool:+ """Inject rtk instructions into a file (AGENTS.md, .cursorrules, etc.).++ Idempotent — skips if marker already present. Appends to existing content.+ Returns True if instructions were written.+ """+ if file_path.exists():+ existing = file_path.read_text()+ if _RTK_MARKER in existing:+ if verbose:+ click.echo(f" rtk instructions already in {file_path.name}")+ return True+ # Append to existing file+ with open(file_path, "a") as f:+ f.write("\n\n" + RTK_INSTRUCTIONS_BLOCK)+ else:+ file_path.parent.mkdir(parents=True, exist_ok=True)+ file_path.write_text(RTK_INSTRUCTIONS_BLOCK)++ click.echo(f" rtk instructions injected into {file_path}")+ return True+++def _inject_memory_mcp_config(db_path: str, user_id: str) -> None:+ """Register headroom memory as an MCP server in Codex's config.toml.++ Idempotent — replaces existing section if present.+ """+ import sys++ config_dir = Path.home() / ".codex"+ config_file = config_dir / "config.toml"++ # Use forward slashes in TOML paths (works on all platforms, avoids+ # backslash escaping issues on Windows)+ python_bin = sys.executable.replace("\\", "/")+ db_path_toml = db_path.replace("\\", "/")+ mcp_section = (+ f"\n{_MEMORY_MCP_MARKER}\n"+ f"[mcp_servers.headroom_memory]\n"+ f'command = "{python_bin}"\n'+ f'args = ["-m", "headroom.memory.mcp_server", "--db", "{db_path_toml}", "--user", "{user_id}"]\n'+ f"startup_timeout_sec = 30\n"+ f"tool_timeout_sec = 30\n"+ f"{_MEMORY_MCP_END}\n"+ )++ try:+ config_dir.mkdir(parents=True, exist_ok=True)++ # Snapshot pre-wrap state before touching config.toml so `unwrap codex`+ # can fully restore it even when only `--memory` (not a full provider+ # injection) was used.+ _, backup_file = _codex_config_paths()+ _snapshot_codex_config_if_unwrapped(config_file, backup_file)++ if config_file.exists():+ content = config_file.read_text()+ if _MEMORY_MCP_MARKER in content:+ start = content.index(_MEMORY_MCP_MARKER)+ end = content.index(_MEMORY_MCP_END) + len(_MEMORY_MCP_END)+ content = content[:start].rstrip("\n") + mcp_section + content[end:].lstrip("\n")+ else:+ content = content.rstrip() + "\n" + mcp_section+ else:+ content = mcp_section++ config_file.write_text(content)+ click.echo(f" Memory MCP: registered in {config_file}")+ except Exception as e:+ click.echo(f" Warning: could not register memory MCP: {e}")+++def _inject_memory_agents_md(file_path: Path) -> bool:+ """Inject memory usage guidance into AGENTS.md.++ Idempotent — skips if marker already present.+ """+ memory_block = (+ f"{_MEMORY_AGENTS_MARKER}\n"+ "## Memory\n\n"+ "Use the `headroom_memory` MCP server for persistent cross-session knowledge.\n\n"+ "**Before** answering questions about prior decisions, conventions, project context,\n"+ "architecture, user preferences, org info, codenames, debugging history, or anything\n"+ "from past sessions — call `memory_search` first.\n\n"+ "**After** making durable decisions, discovering conventions, or learning important\n"+ "facts — call `memory_save` to persist them for future sessions.\n\n"+ "Memory is your first source of truth for anything not visible in the current conversation.\n"+ )++ if file_path.exists():+ existing = file_path.read_text()+ if _MEMORY_AGENTS_MARKER in existing:+ return True # Already injected+ with open(file_path, "a") as f:+ f.write("\n\n" + memory_block)+ else:+ file_path.parent.mkdir(parents=True, exist_ok=True)+ file_path.write_text(memory_block)++ click.echo(f" Memory guidance injected into {file_path.name}")+ return True+++def _resolve_copilot_provider_type(backend: str | None, provider_type: str) -> str:+ """Resolve Copilot BYOK provider type for the current proxy backend."""+ return _copilot_resolve_provider_type(backend, provider_type)+++def _query_proxy_config(port: int) -> dict[str, Any] | None:+ """Query the running proxy's feature configuration via /health.++ Returns a dict with keys like backend, optimize, cache, rate_limit,+ memory, learn, code_graph, pid. Returns None if unreachable or the+ response lacks a config block.+ """+ return _copilot_query_proxy_config(port)+++def _detect_running_proxy_backend(port: int) -> str | None:+ """Read the backend of an already-running proxy from its health endpoint."""+ return _copilot_detect_running_proxy_backend(port)+++def _kill_proxy_by_pid(pid: int, port: int) -> bool:+ """Terminate a proxy process by PID and wait for the port to free up.++ Sends SIGTERM first, falls back to SIGKILL after 5 seconds.+ Returns True if the port is free afterwards, False otherwise.+ """+ try:+ os.kill(pid, signal.SIGTERM)+ except ProcessLookupError:+ pass # Already gone+ except PermissionError:+ click.echo(f" Warning: No permission to kill proxy PID {pid}")+ return False++ # Wait for port to free (up to 5 seconds)+ for _ in range(50):+ time.sleep(0.1)+ if not _check_proxy(port):+ return True++ # SIGTERM didn't work — escalate to SIGKILL (Unix) or terminate (Windows)+ try:+ _kill_signal = getattr(signal, "SIGKILL", signal.SIGTERM)+ os.kill(pid, _kill_signal)+ except (ProcessLookupError, PermissionError):+ pass++ for _ in range(20):+ time.sleep(0.1)+ if not _check_proxy(port):+ return True++ return False+++def _find_persistent_manifest(port: int) -> Any:+ """Return a matching persistent deployment manifest for the requested port."""+ from headroom.install.state import list_manifests++ manifests = [manifest for manifest in list_manifests() if manifest.port == port]+ manifests.sort(key=lambda manifest: (manifest.profile != "default", manifest.profile))+ return manifests[0] if manifests else None+++def _recover_persistent_proxy(port: int) -> bool:+ """Start or recover a matching persistent deployment for the requested port."""+ from headroom.install.health import probe_ready+ from headroom.install.models import InstallPreset, SupervisorKind+ from headroom.install.runtime import start_detached_agent, start_persistent_docker, wait_ready+ from headroom.install.supervisors import start_supervisor++ manifest = _find_persistent_manifest(port)+ if manifest is None:+ return False++ if probe_ready(manifest.health_url):+ click.echo(f" Reusing persistent deployment '{manifest.profile}' on port {port}")+ return True++ if manifest.supervisor_kind == SupervisorKind.TASK.value:+ click.echo(+ f" Warning: task-based deployment '{manifest.profile}' cannot be auto-recovered via wrap"+ )+ return False++ click.echo(f" Recovering persistent deployment '{manifest.profile}' on port {port}...")+ try:+ if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:+ start_persistent_docker(manifest)+ elif manifest.supervisor_kind == SupervisorKind.SERVICE.value:+ start_supervisor(manifest)+ else:+ start_detached_agent(manifest.profile)+ except Exception as exc:+ click.echo(+ f" Warning: could not recover persistent deployment '{manifest.profile}': {exc}"+ )+ return False++ if wait_ready(manifest, timeout_seconds=45):+ click.echo(f" Recovered persistent deployment '{manifest.profile}' on port {port}")+ return True++ click.echo(f" Warning: persistent deployment '{manifest.profile}' did not become ready")+ return False+++def _copilot_model_configured(copilot_args: tuple[str, ...], env: dict[str, str]) -> bool:+ """Return True when Copilot BYOK model selection is configured."""+ return _copilot_model_configured_impl(copilot_args, env)+++def _should_use_copilot_oauth(+ *,+ backend: str | None,+ provider_type: str,+ env: dict[str, str],+) -> bool:+ """Prefer a reusable Copilot OAuth session when the requested routing supports it."""+ if env.get("COPILOT_PROVIDER_API_KEY") or env.get("COPILOT_PROVIDER_BEARER_TOKEN"):+ return False+ if provider_type == "anthropic":+ return False++ effective_backend = backend or os.environ.get("HEADROOM_BACKEND")+ if effective_backend not in (None, "", "anthropic"):+ return False++ return has_oauth_auth()+++def _ensure_proxy(+ port: int,+ no_proxy: bool,+ *,+ learn: bool = False,+ memory: bool = False,+ agent_type: str = "unknown",+ code_graph: bool = False,+ backend: str | None = None,+ anyllm_provider: str | None = None,+ region: str | None = None,+ openai_api_url: str | None = None,+) -> subprocess.Popen | None:+ """Start or verify proxy. Returns process handle if we started it."""+ helpers = _live_wrap_module()+ if not no_proxy:+ manifest = helpers._find_persistent_manifest(port)+ if manifest is not None:+ from headroom.install.health import probe_ready++ if probe_ready(manifest.health_url):+ click.echo(f" Proxy already running on port {port}")+ return None+ if helpers._recover_persistent_proxy(port):+ return None+ if helpers._check_proxy(port):+ raise click.ClickException(+ f"Persistent deployment '{manifest.profile}' on port {port} is not healthy."+ )+ click.echo(+ f" Warning: persistent deployment '{manifest.profile}' on port {port} "+ "is stale; starting a fresh proxy instead."+ )++ if helpers._check_proxy(port):+ # Proxy is running — check if it has the features we need+ needs_restart = False+ running_config = helpers._query_proxy_config(port)++ if running_config is not None:+ missing = []+ if memory and not running_config.get("memory"):+ missing.append("memory")+ if learn and not running_config.get("learn"):+ missing.append("learn")+ if code_graph and not running_config.get("code_graph"):+ missing.append("code_graph")++ if missing:+ needs_restart = True+ flags_str = ", ".join(f"--{f.replace('_', '-')}" for f in missing)+ click.echo(f" Proxy on port {port} is missing: {flags_str}")+ click.echo(" Restarting proxy with upgraded configuration...")++ # Merge: keep features the running proxy already has+ memory = memory or bool(running_config.get("memory"))+ learn = learn or bool(running_config.get("learn"))+ code_graph = code_graph or bool(running_config.get("code_graph"))++ proxy_pid = running_config.get("pid")+ if proxy_pid is not None:+ if not helpers._kill_proxy_by_pid(int(proxy_pid), port):+ raise click.ClickException(+ f"Failed to stop existing proxy (PID {proxy_pid}) on port {port}. "+ "Stop it manually and retry."+ )+ else:+ click.echo(+ " Warning: Running proxy does not expose PID. "+ "Cannot restart automatically."+ )+ click.echo(+ f" Please stop the proxy on port {port} manually "+ f"and rerun with {flags_str}."+ )+ return None++ if not needs_restart:+ click.echo(f" Proxy already running on port {port}")+ return None++ # Start (or restart) the proxy with the requested flags+ click.echo(f" Starting Headroom proxy on port {port}...")+ try:+ proc = cast(+ subprocess.Popen[Any],+ _live_wrap_module()._start_proxy(+ port,+ learn=learn,+ memory=memory,+ agent_type=agent_type,+ code_graph=code_graph,+ backend=backend,+ anyllm_provider=anyllm_provider,+ region=region,+ openai_api_url=openai_api_url,+ ),+ )+ click.echo(f" Proxy ready on http://127.0.0.1:{port}")+ return proc+ except RuntimeError as e:+ click.echo(f" Error: {e}")+ raise SystemExit(1) from e+ else:+ if not helpers._check_proxy(port):+ click.echo(f" Warning: No proxy detected on port {port}")+ return None+++def _make_cleanup(proxy_proc_holder: list, port: int = 8787) -> Any:+ """Create a cleanup function that terminates the proxy on exit.++ Only kills the proxy if no other headroom-wrapped clients are using it.+ Checks by looking for other processes with ANTHROPIC_BASE_URL or+ OPENAI_BASE_URL pointing at our port.+ """++ def _other_clients_exist() -> bool:+ """Check if other processes are using this proxy."""+ try:+ # Count headroom wrap processes (excluding ourselves)+ result = subprocess.run(+ ["pgrep", "-f", f"127.0.0.1:{port}"],+ capture_output=True,+ text=True,+ )+ pids = [p.strip() for p in result.stdout.strip().split("\n") if p.strip()]+ my_pid = str(os.getpid())+ other_pids = [p for p in pids if p != my_pid]+ return len(other_pids) > 0+ except Exception:+ return False # If we can't check, assume no others++ def cleanup(signum: int | None = None, frame: Any = None) -> None:+ proc = proxy_proc_holder[0] if proxy_proc_holder else None+ if proc and proc.poll() is None:+ if _other_clients_exist():+ # Other clients still using the proxy — leave it running+ return+ proc.terminate()+ try:+ proc.wait(timeout=5)+ except subprocess.TimeoutExpired:+ proc.kill()++ return cleanup+++def _launch_tool(+ binary: str,+ args: tuple,+ env: dict[str, str],+ port: int,+ no_proxy: bool,+ tool_label: str,+ env_vars_display: list[str],+ *,+ learn: bool = False,+ memory: bool = False,+ agent_type: str = "unknown",+ code_graph: bool = False,+ backend: str | None = None,+ anyllm_provider: str | None = None,+ region: str | None = None,+ openai_api_url: str | None = None,+) -> None:+ """Common logic: start proxy, launch tool, clean up."""+ proxy_holder: list[subprocess.Popen | None] = [None]+ cleanup = _make_cleanup(proxy_holder, port)+ signal.signal(signal.SIGINT, cleanup)+ signal.signal(signal.SIGTERM, cleanup)++ try:+ click.echo()+ padded = f"HEADROOM WRAP: {tool_label}".center(47)+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(f" ║{padded}║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()++ proxy_holder[0] = _ensure_proxy(+ port,+ no_proxy,+ learn=learn,+ memory=memory,+ agent_type=agent_type,+ code_graph=code_graph,+ backend=backend,+ anyllm_provider=anyllm_provider,+ region=region,+ openai_api_url=openai_api_url,+ )++ if code_graph:+ _setup_code_graph(verbose=False)++ click.echo()+ click.echo(f" Launching {tool_label} (API routed through Headroom)...")+ for var in env_vars_display:+ click.echo(f" {var}")+ if args:+ click.echo(f" Extra args: {' '.join(args)}")+ _print_telemetry_notice()+ click.echo()++ result = subprocess.run([binary, *args], env=env)+ raise SystemExit(result.returncode)++ except SystemExit:+ raise+ except Exception as e:+ click.echo(f" Error: {e}")+ raise SystemExit(1) from e+ finally:+ cleanup()+++def _run_checked(+ cmd: list[str],+ *,+ cwd: Path | None = None,+ action: str,+) -> subprocess.CompletedProcess[str]:+ """Run subprocess and raise a ClickException with actionable context on failure."""+ try:+ return subprocess.run(+ cmd,+ cwd=str(cwd) if cwd else None,+ check=True,+ capture_output=True,+ text=True,+ encoding="utf-8",+ errors="replace",+ )+ except FileNotFoundError as e:+ raise click.ClickException(f"{action} failed: command not found: {cmd[0]}") from e+ except subprocess.CalledProcessError as e:+ stderr = (e.stderr or "").strip()+ stdout = (e.stdout or "").strip()+ details = stderr or stdout or f"exit code {e.returncode}"+ raise click.ClickException(f"{action} failed: {details}") from e+++def _resolve_openclaw_extensions_dir(openclaw_bin: str) -> Path:+ """Resolve OpenClaw extension root from active config file path."""+ result = _run_checked([openclaw_bin, "config", "file"], action="openclaw config file")+ lines = result.stdout.strip().splitlines()+ config_path_str = lines[-1].strip() if lines else ""+ if not config_path_str:+ raise click.ClickException(+ "Unable to resolve OpenClaw config path from `openclaw config file`."+ )+ config_path = Path(config_path_str).expanduser()+ return config_path.parent / "extensions"+++def _normalize_openclaw_gateway_provider_ids(provider_ids: tuple[str, ...] | None) -> list[str]:+ """Normalize configured OpenClaw provider ids, defaulting to openai-codex."""+ return _normalize_openclaw_gateway_provider_ids_impl(provider_ids)+++def _read_openclaw_config_value(openclaw_bin: str, path: str) -> Any | None:+ """Read an OpenClaw config value when present, returning None on missing paths."""+ result = subprocess.run(+ [openclaw_bin, "config", "get", path],+ capture_output=True,+ text=True,+ encoding="utf-8",+ errors="replace",+ )+ if result.returncode != 0:+ return None++ output = result.stdout.strip()+ if not output:+ return None++ try:+ return json.loads(output)+ except json.JSONDecodeError:+ return output+++def _decode_openclaw_entry_json(raw_value: str | None) -> Any | None:+ """Decode a JSON payload captured from `openclaw config get` when available."""+ return _decode_openclaw_entry_json_impl(raw_value)+++def _build_openclaw_plugin_entry(+ *,+ existing_entry: Any,+ proxy_port: int,+ startup_timeout_ms: int,+ python_path: str | None,+ no_auto_start: bool,+ gateway_provider_ids: tuple[str, ...] | None,+ enabled: bool,+) -> dict[str, object]:+ """Merge managed Headroom plugin settings with any existing entry payload."""+ return _build_openclaw_plugin_entry_impl(+ existing_entry=existing_entry,+ proxy_port=proxy_port,+ startup_timeout_ms=startup_timeout_ms,+ python_path=python_path,+ no_auto_start=no_auto_start,+ gateway_provider_ids=gateway_provider_ids,+ enabled=enabled,+ )+++def _build_openclaw_unwrap_entry(existing_entry: Any) -> dict[str, object]:+ """Disable the managed plugin while preserving unrelated user config."""+ return _build_openclaw_unwrap_entry_impl(existing_entry)+++def _write_openclaw_plugin_entry(openclaw_bin: str, entry: dict[str, object]) -> None:+ """Persist the Headroom plugin config entry."""+ _run_checked(+ [+ openclaw_bin,+ "config",+ "set",+ "plugins.entries.headroom",+ json.dumps(entry, separators=(",", ":")),+ "--strict-json",+ ],+ action="openclaw config set plugins.entries.headroom",+ )+++def _set_openclaw_context_engine_slot(openclaw_bin: str, engine_id: str) -> None:+ """Persist the selected OpenClaw context engine slot."""+ _run_checked(+ [+ openclaw_bin,+ "config",+ "set",+ "plugins.slots.contextEngine",+ json.dumps(engine_id),+ "--strict-json",+ ],+ action="openclaw config set plugins.slots.contextEngine",+ )+++def _restart_or_start_openclaw_gateway(openclaw_bin: str) -> tuple[str, str]:+ """Restart the gateway when running, otherwise start it."""+ restart_result = subprocess.run(+ [openclaw_bin, "gateway", "restart"],+ capture_output=True,+ text=True,+ encoding="utf-8",+ errors="replace",+ )+ if restart_result.returncode == 0:+ output = restart_result.stdout.strip() or restart_result.stderr.strip()+ return "restarted", output++ start_result = _run_checked(+ [openclaw_bin, "gateway", "start"],+ action="openclaw gateway start",+ )+ output = start_result.stdout.strip() or start_result.stderr.strip()+ return "started", output+++def _copy_openclaw_plugin_into_extensions(+ *,+ plugin_dir: Path,+ openclaw_bin: str,+) -> Path:+ """Fallback install path when `openclaw plugins install` is blocked on linked source."""+ dist_dir = plugin_dir / "dist"+ if not dist_dir.exists():+ raise click.ClickException(+ f"Plugin dist folder missing at {dist_dir}. Build the plugin first."+ )+ hook_shim_dir = plugin_dir / "hook-shim"+ if not hook_shim_dir.exists():+ raise click.ClickException(+ f"Plugin hook-shim folder missing at {hook_shim_dir}. Build the plugin first."+ )++ extensions_dir = _resolve_openclaw_extensions_dir(openclaw_bin)+ target_dir = extensions_dir / "headroom"+ target_dist = target_dir / "dist"+ target_hook_shim = target_dir / "hook-shim"+ target_dir.mkdir(parents=True, exist_ok=True)+ if target_dist.exists():+ shutil.rmtree(target_dist)+ if target_hook_shim.exists():+ shutil.rmtree(target_hook_shim)+ shutil.copytree(dist_dir, target_dist)+ shutil.copytree(hook_shim_dir, target_hook_shim)++ for filename in ("openclaw.plugin.json", "package.json", "README.md"):+ source = plugin_dir / filename+ if source.exists():+ shutil.copy2(source, target_dir / filename)++ return target_dir+++def wrap() -> None:+ """Wrap CLI tools to run through Headroom.++ \b+ Starts a Headroom proxy, configures the environment, and launches+ the target tool so all API calls route through Headroom automatically.++ \b+ Supported tools:+ headroom wrap claude # Claude Code (Anthropic)+ headroom wrap copilot -- --model claude-sonnet-4-20250514+ headroom wrap codex # OpenAI Codex CLI+ headroom wrap aider # Aider+ headroom wrap cursor # Cursor (prints config instructions)+ headroom wrap openclaw # OpenClaw plugin bootstrap+ """+++def unwrap() -> None:+ """Undo durable Headroom wrapping for supported tools."""+++# =============================================================================+# Claude Code+# =============================================================================++[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--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")+ "--code-graph",+ is_flag=True,+ help="Enable code graph indexing via codebase-memory-mcp (optional)",+)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")+ "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to MEMORY.md)"+)[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("claude_args", nargs=-1, type=click.UNPROCESSED)+def claude(+ port: int,+ no_rtk: bool,+ code_graph: bool,+ no_proxy: bool,+ learn: bool,+ memory: bool,+ verbose: bool,+ prepare_only: bool,+ claude_args: tuple,+) -> None:+ """Launch Claude Code through Headroom proxy.++ \b+ Sets ANTHROPIC_BASE_URL to route all Anthropic API calls through Headroom.+ All unknown flags are passed through to claude (e.g. --resume, --model).++ \b+ Examples:+ headroom wrap claude # Start everything+ headroom wrap claude --memory # With persistent memory+ headroom wrap claude --resume <id> # Resume a session+ headroom wrap claude -- -p # Claude in print mode+ headroom wrap claude --code-graph # With code graph intelligence+ headroom wrap claude --no-rtk # Skip rtk (proxy only)+ """+ if prepare_only:+ if not no_rtk:+ _prepare_wrap_rtk(verbose=verbose, label="Claude")+ return++ claude_bin = shutil.which("claude")+ if not claude_bin:+ click.echo("Error: 'claude' not found in PATH.")+ click.echo("Install Claude Code: https://docs.anthropic.com/en/docs/claude-code")+ raise SystemExit(1)++ # Setup rtk before launching (Claude-specific)+ proxy_holder: list[subprocess.Popen | None] = [None]+ cleanup = _make_cleanup(proxy_holder, port)+ signal.signal(signal.SIGINT, cleanup)+ signal.signal(signal.SIGTERM, cleanup)++ # Memory sync BEFORE proxy startup — sync headroom DB ↔ Claude's files+ if memory:+ try:+ import subprocess as _sp++ mem_dir = Path.cwd() / ".headroom"+ mem_dir.mkdir(parents=True, exist_ok=True)+ _sync_db = str(mem_dir / "memory.db")+ _sync_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))++ click.echo(f" Syncing memory (user={_sync_user})...")+ sync_result = _sp.run(+ [+ sys.executable,+ "-m",+ "headroom.memory.sync",+ "--db",+ _sync_db,+ "--user",+ _sync_user,+ "--agent",+ "claude",+ "--force",+ ],+ capture_output=True,+ text=True,+ timeout=30,+ )+ if sync_result.returncode == 0 and sync_result.stdout.strip():+ import json as _json++ stats = _json.loads(sync_result.stdout.strip().split("\n")[-1])+ imp, exp, ms = stats["imported"], stats["exported"], stats["ms"]+ if imp or exp:+ click.echo(f" Memory synced: {imp} imported, {exp} exported ({ms}ms)")+ else:+ click.echo(f" Memory: up to date ({ms}ms)")+ elif sync_result.returncode != 0:+ click.echo(f" Warning: memory sync error: {sync_result.stderr[-200:]}")+ except Exception as e:+ click.echo(f" Warning: memory sync failed: {e}")++ try:+ click.echo()+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(" ║ HEADROOM WRAP: CLAUDE ║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()++ proxy_holder[0] = _ensure_proxy(+ port, no_proxy, learn=learn, memory=memory, agent_type="claude", code_graph=code_graph+ )++ if not no_rtk:+ click.echo(" Setting up rtk...")+ _setup_rtk(verbose=verbose)+ elif verbose:+ click.echo(" Skipping rtk (--no-rtk)")++ if code_graph:+ _setup_code_graph(verbose=verbose)++ click.echo()+ click.echo(" Launching Claude Code (API routed through Headroom)...")+ click.echo(f" ANTHROPIC_BASE_URL={_claude_proxy_base_url(port)}")+ if claude_args:+ click.echo(f" Extra args: {' '.join(claude_args)}")+ _print_telemetry_notice()+ click.echo()++ env = os.environ.copy()+ env["ANTHROPIC_BASE_URL"] = _claude_proxy_base_url(port)++ result = subprocess.run([claude_bin, *claude_args], env=env)+ raise SystemExit(result.returncode)++ except SystemExit:+ raise+ except Exception as e:+ click.echo(f" Error: {e}")+ raise SystemExit(1) from e+ finally:+ cleanup()+++# =============================================================================+# GitHub Copilot CLI+# =============================================================================++[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")+ "--no-rtk",+ is_flag=True,+ help="Skip rtk installation and Copilot instructions injection",+)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")+ "--backend",+ default=None,+ help="API backend for the proxy: 'anthropic', 'anyllm', 'litellm-vertex', etc. (env: HEADROOM_BACKEND)",+)+ "--anyllm-provider",+ default=None,+ help="Provider for any-llm backend: openai, mistral, groq, etc. (env: HEADROOM_ANYLLM_PROVIDER)",+)+ "--region", default=None, help="Cloud region for Bedrock/Vertex (env: HEADROOM_REGION)"+)+ "--provider-type",+ type=click.Choice(["auto", "anthropic", "openai"]),+ default="auto",+ show_default=True,+ help="Copilot BYOK provider mode. 'auto' uses anthropic for the default proxy backend and openai for translated backends.",+)+ "--wire-api",+ type=click.Choice(["completions", "responses"]),+ default=None,+ help="OpenAI-compatible Copilot wire API. Defaults to 'completions' when provider-type resolves to openai.",+)[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("copilot_args", nargs=-1, type=click.UNPROCESSED)+def copilot(+ port: int,+ no_rtk: bool,+ no_proxy: bool,+ backend: str | None,+ anyllm_provider: str | None,+ region: str | None,+ provider_type: str,+ wire_api: str | None,+ memory: bool,+ verbose: bool,+ copilot_args: tuple[str, ...],+) -> None:+ """Launch GitHub Copilot CLI through Headroom proxy.++ \b+ Configures Copilot CLI BYOK provider variables so Copilot routes through+ the local Headroom proxy. In auto mode, the wrapper uses Anthropic-style+ routing for the stock proxy backend and OpenAI-compatible routing for+ translated backends such as any-llm and LiteLLM.++ \b+ Examples:+ headroom wrap copilot -- --model claude-sonnet-4-20250514+ headroom wrap copilot --backend anyllm --anyllm-provider groq -- --model gpt-4o+ headroom wrap copilot --provider-type openai --wire-api responses -- --model gpt-5.4+ headroom wrap copilot --no-rtk -- --prompt "explain this file"+ """+ copilot_bin = shutil.which("copilot")+ if not copilot_bin:+ click.echo("Error: 'copilot' not found in PATH.")+ click.echo(+ "Install GitHub Copilot CLI: "+ "https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli"+ )+ raise SystemExit(1)++ effective_backend = backend or os.environ.get("HEADROOM_BACKEND")+ if _check_proxy(port):+ running_backend = _detect_running_proxy_backend(port)+ if effective_backend and running_backend and effective_backend != running_backend:+ raise click.ClickException(+ f"Proxy already running on port {port} with backend '{running_backend}'. "+ f"Stop it or rerun with --backend {running_backend}."+ )+ effective_backend = running_backend or effective_backend++ effective_provider_type = _resolve_copilot_provider_type(effective_backend, provider_type)+ _validate_copilot_configuration(+ provider_type=effective_provider_type,+ wire_api=wire_api,+ backend=effective_backend,+ )++ 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)++ env = os.environ.copy()+ openai_api_url: str | None = None+ if _should_use_copilot_oauth(+ backend=effective_backend,+ provider_type=provider_type,+ env=env,+ ):+ client_bearer = resolve_client_bearer_token()+ if not client_bearer:+ raise click.ClickException(+ "GitHub Copilot auth was detected but no reusable bearer token could be resolved."+ )++ effective_wire_api = wire_api or "completions"+ env["COPILOT_PROVIDER_TYPE"] = "openai"+ env["COPILOT_PROVIDER_BASE_URL"] = f"http://127.0.0.1:{port}/v1"+ env["COPILOT_PROVIDER_WIRE_API"] = effective_wire_api+ env["COPILOT_PROVIDER_BEARER_TOKEN"] = client_bearer+ env.pop("COPILOT_PROVIDER_API_KEY", None)+ env_vars_display = [+ "COPILOT_PROVIDER_TYPE=openai",+ f"COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:{port}/v1",+ f"COPILOT_PROVIDER_WIRE_API={effective_wire_api}",+ "COPILOT_AUTH_MODE=github-oauth",+ ]+ openai_api_url = COPILOT_API_URL+ else:+ env, env_vars_display = _build_copilot_launch_env(+ port=port,+ provider_type=effective_provider_type,+ wire_api=wire_api,+ environ=env,+ )++ if not env.get("COPILOT_PROVIDER_API_KEY"):+ src = _copilot_provider_key_source(effective_provider_type)+ click.echo(+ f"\n Error: Copilot BYOK mode requires a provider API key.\n"+ f" `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's\n"+ f" Copilot API and routes requests directly to the model provider through the\n"+ f" Headroom proxy. A GitHub Copilot subscription alone is not sufficient.\n\n"+ f" Set one of:\n"+ f" export {src}=sk-... # recommended\n"+ f" export COPILOT_PROVIDER_API_KEY=sk-... # also works\n"+ )+ raise SystemExit(1)++ if not _copilot_model_configured(copilot_args, env):+ click.echo(+ " Note: Copilot BYOK requires a model. Pass `--model <name>` "+ "or set `COPILOT_MODEL` / `COPILOT_PROVIDER_MODEL_ID`."+ )++ _launch_tool(+ binary=copilot_bin,+ args=copilot_args,+ env=env,+ port=port,+ no_proxy=no_proxy,+ tool_label="COPILOT",+ env_vars_display=env_vars_display,+ learn=False,+ memory=memory,+ agent_type="copilot",+ backend=backend,+ anyllm_provider=anyllm_provider,+ region=region,+ openai_api_url=openai_api_url,+ )+++# =============================================================================+# OpenAI Codex CLI+# =============================================================================++[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--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")+ "--code-graph",+ is_flag=True,+ help="Enable code graph indexing via codebase-memory-mcp (optional)",+)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")+ "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to AGENTS.md)"+)+ "--backend",+ default=None,+ help="API backend for the proxy: 'anthropic', 'anyllm', 'litellm-vertex', etc. (env: HEADROOM_BACKEND)",+)+ "--anyllm-provider",+ default=None,+ help="Provider for any-llm backend: openai, mistral, groq, etc. (env: HEADROOM_ANYLLM_PROVIDER)",+)+ "--region", default=None, help="Cloud region for Bedrock/Vertex (env: HEADROOM_REGION)"+)[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("codex_args", nargs=-1, type=click.UNPROCESSED)+def codex(+ port: int,+ no_rtk: bool,+ code_graph: bool,+ no_proxy: bool,+ learn: bool,+ memory: bool,+ backend: str | None,+ anyllm_provider: str | None,+ region: str | None,+ verbose: bool,+ prepare_only: bool,+ codex_args: tuple,+) -> None:+ """Launch OpenAI Codex CLI through Headroom proxy.++ \b+ Sets 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).++ \b+ Examples:+ headroom wrap codex # Start proxy + rtk + codex+ headroom wrap codex -- "fix the bug" # Pass prompt to codex+ headroom wrap codex --no-rtk # Skip rtk setup+ headroom wrap codex --port 9999 # Custom proxy port+ headroom wrap codex --backend anyllm --anyllm-provider groq+ """+ # Setup rtk for Codex (binary + AGENTS.md instructions, no hooks)+ 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)++ # Also inject into global ~/.codex/AGENTS.md+ global_agents = Path.home() / ".codex" / "AGENTS.md"+ _inject_rtk_instructions(global_agents, verbose=verbose)++ # Setup memory MCP server for Codex (native tool integration)+ if memory:+ click.echo(" Setting up memory for Codex...")+ mem_dir = Path.cwd() / ".headroom"+ mem_dir.mkdir(parents=True, exist_ok=True)+ db_path = str(mem_dir / "memory.db")+ mem_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))++ # Register MCP server in Codex config+ _inject_memory_mcp_config(db_path, mem_user)++ # Inject memory guidance into project AGENTS.md+ agents_md = Path.cwd() / "AGENTS.md"+ _inject_memory_agents_md(agents_md)++ # Sync Claude's memories → DB so MCP search finds them+ try:+ import asyncio++ from headroom.memory.backends.local import LocalBackend, LocalBackendConfig+ from headroom.memory.sync import sync_import+ from headroom.memory.sync_adapters.claude_code import (+ ClaudeCodeAdapter,+ get_claude_memory_dir,+ )++ claude_memory_dir = get_claude_memory_dir()++ async def _import_claude_memories() -> int:+ config = LocalBackendConfig(db_path=db_path)+ backend = LocalBackend(config)+ await backend._ensure_initialized()+ adapter = ClaudeCodeAdapter(claude_memory_dir)+ count = await sync_import(backend, adapter, mem_user)+ await backend.close()+ return count++ imported = asyncio.run(_import_claude_memories())+ if imported:+ click.echo(f" Memory: imported {imported} memories from Claude")+ except Exception as e:+ click.echo(f" Warning: Claude memory import failed: {e}")++ if prepare_only:+ _inject_codex_provider_config(port)+ return++ codex_bin = shutil.which("codex")+ if not codex_bin:+ click.echo("Error: 'codex' not found in PATH.")+ click.echo("Install Codex CLI: npm install -g @openai/codex")+ raise SystemExit(1)++ env, env_vars_display = _build_codex_launch_env(port, os.environ)++ # 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.+ # NOTE: this must run BEFORE _inject_memory_mcp_config because it rewrites+ # the config file. Re-inject MCP config after if memory is enabled.+ _inject_codex_provider_config(port)+ if memory:+ mem_dir = Path.cwd() / ".headroom"+ _inject_memory_mcp_config(+ str(mem_dir / "memory.db"),+ os.environ.get("USER", os.environ.get("USERNAME", "default")),+ )++ _launch_tool(+ binary=codex_bin,+ args=codex_args,+ env=env,+ port=port,+ no_proxy=no_proxy,+ tool_label="CODEX",+ env_vars_display=env_vars_display,+ learn=learn,+ memory=memory,+ agent_type="codex",+ code_graph=code_graph,+ backend=backend,+ anyllm_provider=anyllm_provider,+ region=region,+ )+++# =============================================================================+# Aider+# =============================================================================++[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--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")+ "--code-graph",+ is_flag=True,+ help="Enable code graph indexing via codebase-memory-mcp (optional)",+)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")[email protected]("--learn", is_flag=True, help="Enable live traffic learning")[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")+ "--backend", default=None, help="API backend: 'anthropic', 'anyllm', 'litellm-vertex', etc."+)[email protected]("--anyllm-provider", default=None, help="Provider for any-llm backend")[email protected]("--region", default=None, help="Cloud region for Bedrock/Vertex")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("aider_args", nargs=-1, type=click.UNPROCESSED)+def aider(+ port: int,+ no_rtk: bool,+ code_graph: bool,+ no_proxy: bool,+ learn: bool,+ memory: bool,+ backend: str | None,+ anyllm_provider: str | None,+ region: str | None,+ verbose: bool,+ prepare_only: bool,+ aider_args: tuple,+) -> None:+ """Launch aider through Headroom proxy.++ \b+ Sets 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.++ \b+ Examples:+ headroom wrap aider # Start proxy + rtk + aider+ headroom wrap aider -- --model gpt-4o # Use GPT-4o+ headroom wrap aider -- --model claude-sonnet-4 # Use Claude+ headroom wrap aider --no-rtk # Skip rtk setup+ headroom wrap aider --backend litellm-vertex --region us-central1+ """+ # Setup rtk for aider (binary + CONVENTIONS.md instructions)+ 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 prepare_only:+ return++ aider_bin = shutil.which("aider")+ if not aider_bin:+ click.echo("Error: 'aider' not found in PATH.")+ click.echo("Install aider: pip install aider-chat")+ raise SystemExit(1)++ env, env_vars_display = _build_aider_launch_env(port, os.environ)++ _launch_tool(+ binary=aider_bin,+ args=aider_args,+ env=env,+ port=port,+ no_proxy=no_proxy,+ tool_label="AIDER",+ env_vars_display=env_vars_display,+ learn=learn,+ memory=memory,+ agent_type="aider",+ code_graph=code_graph,+ backend=backend,+ anyllm_provider=anyllm_provider,+ region=region,+ )+++# =============================================================================+# Cursor+# =============================================================================++[email protected](context_settings={"ignore_unknown_options": True})[email protected]("--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")[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")+ "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to .cursor/rules/)"+)[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)+def cursor(+ port: int,+ no_rtk: bool,+ no_proxy: bool,+ learn: bool,+ memory: bool,+ verbose: bool,+ prepare_only: bool,+) -> None:+ """Start Headroom proxy for use with Cursor.++ \b+ Cursor 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.++ \b+ After running this command, open Cursor and configure:+ Settings > Models > OpenAI API Key > Advanced > Override Base URL++ \b+ Example:+ headroom wrap cursor # Start proxy + rtk + instructions+ headroom wrap cursor --no-rtk # Proxy only, no rtk+ headroom 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 prepare_only:+ return++ proxy_holder: list[subprocess.Popen | None] = [None]+ cleanup = _make_cleanup(proxy_holder, port)+ signal.signal(signal.SIGINT, cleanup)+ signal.signal(signal.SIGTERM, cleanup)++ try:+ click.echo()+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(" ║ HEADROOM WRAP: CURSOR ║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()++ proxy_holder[0] = _ensure_proxy(+ port, no_proxy, learn=learn, memory=memory, agent_type="cursor"+ )++ click.echo()+ for line in _render_cursor_setup_lines(port):+ click.echo(line)+ if not no_rtk:+ click.echo()+ 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.")+ click.echo()++ # Block until Ctrl+C+ try:+ while True:+ time.sleep(1)+ proc = proxy_holder[0]+ if proc and proc.poll() is not None:+ click.echo(" Proxy process exited unexpectedly.")+ raise SystemExit(1)+ except KeyboardInterrupt:+ click.echo("\n Shutting down...")++ except SystemExit:+ raise+ except Exception as e:+ click.echo(f" Error: {e}")+ raise SystemExit(1) from e+ finally:+ cleanup()+++# =============================================================================+# OpenClaw+# =============================================================================++[email protected]("openclaw")+ "--plugin-path",+ type=click.Path(path_type=Path, file_okay=False, dir_okay=True),+ default=None,+ help="Path to local OpenClaw plugin source directory (advanced/dev override)",+)+ "--plugin-spec",+ default="headroom-ai/openclaw",+ show_default=True,+ help="NPM plugin spec for OpenClaw install (used when --plugin-path is omitted)",+)+ "--skip-build",+ is_flag=True,+ help="Skip npm install/build in local source mode (--plugin-path)",+)+ "--copy",+ is_flag=True,+ help="Install by copying plugin path instead of using --link",+)[email protected]("--proxy-port", default=8787, type=int, help="Headroom proxy port")[email protected]("--startup-timeout-ms", default=20000, type=int, help="Proxy startup timeout")+ "--gateway-provider-id",+ "gateway_provider_ids",+ multiple=True,+ help="OpenClaw provider id to route through Headroom (repeatable; default: openai-codex)",+)+ "--python-path",+ default=None,+ help="Optional Python executable for proxy launcher fallback",+)+ "--no-auto-start",+ is_flag=True,+ help="Disable plugin auto-start of local headroom proxy",+)+ "--no-restart",+ is_flag=True,+ help="Do not restart OpenClaw gateway at the end",+)[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("--existing-entry-json", default=None, hidden=True)+def openclaw(+ plugin_path: Path | None,+ plugin_spec: str,+ skip_build: bool,+ copy: bool,+ proxy_port: int,+ startup_timeout_ms: int,+ gateway_provider_ids: tuple[str, ...],+ python_path: str | None,+ no_auto_start: bool,+ no_restart: bool,+ verbose: bool,+ prepare_only: bool,+ existing_entry_json: str | None,+) -> None:+ """Install and configure Headroom OpenClaw plugin in one command.++ \b+ What this command does:+ 1. Installs OpenClaw plugin from npm (or local --plugin-path)+ 2. Builds plugin source if --plugin-path is used+ 3. Writes minimal plugin config and sets contextEngine slot+ 4. Validates config+ 5. Restarts OpenClaw gateway (unless --no-restart)++ \b+ Example:+ headroom wrap openclaw+ headroom wrap openclaw --plugin-path C:\\git\\headroom\\plugins\\openclaw+ """+ if prepare_only:+ entry = _build_openclaw_plugin_entry(+ existing_entry=_decode_openclaw_entry_json(existing_entry_json),+ proxy_port=proxy_port,+ startup_timeout_ms=startup_timeout_ms,+ python_path=python_path,+ no_auto_start=no_auto_start,+ gateway_provider_ids=gateway_provider_ids,+ enabled=True,+ )+ click.echo(json.dumps(entry, separators=(",", ":")))+ return++ openclaw_bin = shutil.which("openclaw")+ if not openclaw_bin:+ raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")++ plugin_dir = plugin_path.resolve() if plugin_path else None+ local_source_mode = plugin_dir is not None+ if plugin_dir:+ if not plugin_dir.exists():+ raise click.ClickException(f"Plugin path not found: {plugin_dir}.")+ if not (plugin_dir / "package.json").exists():+ raise click.ClickException(f"Invalid plugin path (missing package.json): {plugin_dir}")+ if not (plugin_dir / "openclaw.plugin.json").exists():+ raise click.ClickException(+ f"Invalid plugin path (missing openclaw.plugin.json): {plugin_dir}"+ )++ npm_bin = shutil.which("npm")+ if local_source_mode and not skip_build and not npm_bin:+ raise click.ClickException(+ "'npm' not found in PATH. Install Node/npm or rerun with --skip-build."+ )++ click.echo()+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(" ║ HEADROOM WRAP: OPENCLAW ║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()+ if local_source_mode:+ click.echo(f" Plugin source: local ({plugin_dir})")+ else:+ click.echo(f" Plugin source: npm ({plugin_spec})")++ if local_source_mode and not skip_build:+ click.echo(" Building OpenClaw plugin (npm install + npm run build)...")+ _run_checked([npm_bin or "npm", "install"], cwd=plugin_dir, action="npm install")+ _run_checked([npm_bin or "npm", "run", "build"], cwd=plugin_dir, action="npm run build")+ elif not local_source_mode and skip_build:+ click.echo(" Skipping build: npm install mode does not build local source.")++ effective_python_path = python_path+ if effective_python_path is None and not no_auto_start and sys.executable:+ effective_python_path = sys.executable++ existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")+ entry = _build_openclaw_plugin_entry(+ existing_entry=existing_entry,+ proxy_port=proxy_port,+ startup_timeout_ms=startup_timeout_ms,+ python_path=effective_python_path,+ no_auto_start=no_auto_start,+ gateway_provider_ids=gateway_provider_ids,+ enabled=True,+ )++ click.echo(" Writing plugin configuration...")+ _write_openclaw_plugin_entry(openclaw_bin, entry)++ install_cmd = [+ openclaw_bin,+ "plugins",+ "install",+ "--dangerously-force-unsafe-install",+ ]+ if local_source_mode:+ if copy:+ install_cmd.append(str(plugin_dir))+ install_cwd = None+ else:+ install_cmd.extend(["--link", "."])+ install_cwd = plugin_dir+ else:+ install_cmd.append(plugin_spec)+ install_cwd = None++ click.echo(" Installing OpenClaw plugin with required unsafe-install flag...")+ install_result = subprocess.run(+ install_cmd,+ cwd=str(install_cwd) if install_cwd else None,+ capture_output=True,+ text=True,+ encoding="utf-8",+ errors="replace",+ )+ if install_result.returncode != 0:+ combined_error = "\n".join(+ x for x in [install_result.stderr.strip(), install_result.stdout.strip()] if x+ )+ plugin_already_exists = "plugin already exists" in combined_error.lower()+ linked_install_bug = (+ "also not a valid hook pack" in combined_error.lower()+ and "--dangerously-force-unsafe-install" in " ".join(install_cmd)+ )+ if plugin_already_exists:+ click.echo(" Plugin already installed; continuing with configuration/update steps.")+ elif linked_install_bug and local_source_mode and plugin_dir is not None:+ click.echo(+ " OpenClaw linked-path install bug detected; applying extension-path fallback..."+ )+ target_dir = _copy_openclaw_plugin_into_extensions(+ plugin_dir=plugin_dir,+ openclaw_bin=openclaw_bin,+ )+ click.echo(f" Fallback plugin copy completed: {target_dir}")+ else:+ details = combined_error or f"exit code {install_result.returncode}"+ raise click.ClickException(f"openclaw plugins install failed: {details}")+ elif verbose and install_result.stdout.strip():+ click.echo(install_result.stdout.strip())++ _set_openclaw_context_engine_slot(openclaw_bin, "headroom")+ _run_checked(+ [openclaw_bin, "config", "validate"],+ action="openclaw config validate",+ )++ if no_restart:+ click.echo(" Skipping gateway restart (--no-restart).")+ click.echo(+ " Run `openclaw gateway restart` (or `openclaw gateway start`) to apply plugin changes."+ )+ else:+ click.echo(" Applying plugin changes to OpenClaw gateway...")+ gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)+ click.echo(f" Gateway {gateway_action}.")+ if verbose and gateway_output:+ click.echo(gateway_output)++ inspect_result = _run_checked(+ [openclaw_bin, "plugins", "inspect", "headroom"],+ action="openclaw plugins inspect headroom",+ )+ if verbose and inspect_result.stdout.strip():+ click.echo(inspect_result.stdout.strip())++ click.echo()+ click.echo("✓ OpenClaw is configured to use Headroom context compression.")+ click.echo(" Plugin: headroom")+ click.echo(" Slot: plugins.slots.contextEngine = headroom")+ click.echo()++[email protected]("openclaw")[email protected]("--no-restart", is_flag=True, help="Do not restart OpenClaw gateway at the end")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("--existing-entry-json", default=None, hidden=True)+def unwrap_openclaw(+ no_restart: bool,+ verbose: bool,+ prepare_only: bool,+ existing_entry_json: str | None,+) -> None:+ """Disable the Headroom OpenClaw plugin and restore the legacy engine slot."""+ if prepare_only:+ click.echo(+ json.dumps(+ _build_openclaw_unwrap_entry(_decode_openclaw_entry_json(existing_entry_json)),+ separators=(",", ":"),+ )+ )+ return++ openclaw_bin = shutil.which("openclaw")+ if not openclaw_bin:+ raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")++ click.echo()+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(" ║ HEADROOM UNWRAP: OPENCLAW ║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()+ click.echo(" Disabling Headroom plugin and removing engine mapping...")++ existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")+ entry = _build_openclaw_unwrap_entry(existing_entry)+ _write_openclaw_plugin_entry(openclaw_bin, entry)+ _set_openclaw_context_engine_slot(openclaw_bin, "legacy")+ _run_checked(+ [openclaw_bin, "config", "validate"],+ action="openclaw config validate",+ )++ if no_restart:+ click.echo(" Skipping gateway restart (--no-restart).")+ click.echo(+ " Run `openclaw gateway restart` (or `openclaw gateway start`) to apply unwrap changes."+ )+ else:+ click.echo(" Applying unwrap changes to OpenClaw gateway...")+ gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)+ click.echo(f" Gateway {gateway_action}.")+ if verbose and gateway_output:+ click.echo(gateway_output)++ if verbose:+ inspect_result = _run_checked(+ [openclaw_bin, "plugins", "inspect", "headroom"],+ action="openclaw plugins inspect headroom",+ )+ if inspect_result.stdout.strip():+ click.echo(inspect_result.stdout.strip())++ click.echo()+ click.echo("✓ OpenClaw Headroom wrap removed.")+ click.echo(" Plugin: headroom (installed, disabled)")+ click.echo(" Slot: plugins.slots.contextEngine = legacy")+ click.echo()+++# =============================================================================+# OpenAI Codex CLI (unwrap)+# =============================================================================++[email protected]("codex")+def unwrap_codex() -> None:+ """Undo ``headroom wrap codex`` edits to ``~/.codex/config.toml``.++ Behaviour:++ * If a pre-wrap backup (``config.toml.headroom-backup``) exists, the+ original file is restored byte-for-byte and the backup is removed.+ * Otherwise, if the config file still contains the Headroom-managed+ block, that block is stripped out and the rest of the file is+ preserved.+ * If the config only ever contained Headroom-written content, the file+ is removed entirely so Codex falls back to its defaults.+ * If neither a backup nor a Headroom block is present, this is a safe+ no-op (the user either never wrapped, or already unwrapped).+ """+ click.echo()+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(" ║ HEADROOM UNWRAP: CODEX ║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()++ try:+ status, config_file = _restore_codex_provider_config()+ except Exception as e: # pragma: no cover - filesystem-level errors+ raise click.ClickException(f"could not unwrap Codex config: {e}") from e++ if status == "restored":+ click.echo(f" Restored prior {config_file} from pre-wrap backup.")+ elif status == "cleaned":+ click.echo(f" Removed Headroom block from {config_file}; other content preserved.")+ elif status == "removed":+ click.echo(f" Removed {config_file} (contained only Headroom-written config).")+ else:+ click.echo(f" Nothing to undo: {config_file} has no Headroom wrap markers.")++ click.echo()+ click.echo("✓ Codex is no longer routed through the Headroom proxy.")+ click.echo()diff --git a/headroom/compress.py b/headroom/compress.pyindex 1a9c387ae..09ac4f46f 100644--- a/headroom/compress.py+++ b/headroom/compress.py@@ -1,347 +1,347 @@-"""One-function compression API for Headroom.--The simplest way to use Headroom — no proxy, no config, just compress:-- from headroom import compress-- result = compress(messages, model="claude-sonnet-4-5-20250929")- result.messages # Compressed messages (same format, fewer tokens)- result.tokens_saved # Tokens saved- result.compression_ratio # e.g., 0.35 means 65% saved--Works with any LLM client, any proxy, any framework. Just compress-the messages before sending them.--Examples:-- # With Anthropic SDK- from anthropic import Anthropic- from headroom import compress-- client = Anthropic()- messages = [{"role": "user", "content": huge_tool_output}]- compressed = compress(messages, model="claude-sonnet-4-5-20250929")- response = client.messages.create(- model="claude-sonnet-4-5-20250929",- messages=compressed.messages,- )-- # With OpenAI SDK- from openai import OpenAI- from headroom import compress-- client = OpenAI()- messages = [{"role": "user", "content": "analyze this"}, {"role": "tool", "content": big_data}]- compressed = compress(messages, model="gpt-4o")- response = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)-- # With LiteLLM- import litellm- from headroom import compress-- messages = [...]- compressed = compress(messages, model="bedrock/claude-sonnet")- response = litellm.completion(model="bedrock/claude-sonnet", messages=compressed.messages)-- # With any HTTP client- import httpx- from headroom import compress-- compressed = compress(messages, model="claude-sonnet-4-5-20250929")- httpx.post("https://api.anthropic.com/v1/messages", json={- "model": "claude-sonnet-4-5-20250929",- "messages": compressed.messages,- })-"""--from __future__ import annotations--import logging-import threading-from dataclasses import dataclass, field-from typing import Any--from .observability import get_otel_metrics-from .pipeline import PipelineExtensionManager, PipelineStage, summarize_routing_markers-from .utils import extract_user_query as _extract_user_query--logger = logging.getLogger(__name__)---# Lazy-initialized singleton pipeline-_pipeline = None-_pipeline_lock = threading.Lock()---@dataclass-class CompressConfig:- """User-facing compression options.-- Controls what gets compressed, how aggressively, and with which model.- Pass to ``compress()`` or any integration that uses headroom.-- Examples::-- # Coding agent (default — skip user messages, protect recent)- compress(messages, model="gpt-4o")-- # Financial document (compress everything, keep 50%)- compress(messages, model="claude-opus-4-20250514",- compress_user_messages=True,- target_ratio=0.5,- protect_recent=0,- )-- # Aggressive (logs, search results)- compress(messages, model="gpt-4o", target_ratio=0.2)- """-- # What to compress- compress_user_messages: bool = False- """Compress user messages too (default: skip them for coding agents).- Set True for document compression, RAG pipelines, or when user messages- contain large tool outputs."""-- compress_system_messages: bool = True- """Compress system messages (default: True).- Set False to preserve system prompts exactly as-is. Useful for voice- agents where tool definitions and instructions must not be altered."""-- protect_recent: int = 4- """Don't compress the last N messages (they're the active conversation).- Set 0 to compress everything."""-- protect_analysis_context: bool = True- """Detect 'analyze'/'review' intent and protect code from compression."""-- # How aggressive- target_ratio: float | None = None- """Keep ratio for Kompress. None = model decides (~15% kept, aggressive).- 0.5 = keep 50% (safe for documents). 0.7 = keep 70% (conservative).- Only affects Kompress (text compression). SmartCrusher (JSON) has its- own logic based on array dedup."""-- min_tokens_to_compress: int = 250- """Minimum token count for a message to be compressed.- Messages shorter than this are left unchanged. Default 250.- Set lower for voice agents where turns are short."""-- # Model variant- kompress_model: str | None = None- """Kompress model ID. None = default (chopratejas/kompress-base).- Set to a HuggingFace model ID for domain-specific compression.- Set to 'disabled' to skip ML compression entirely- (only SmartCrusher + CacheAligner will run)."""---@dataclass-class CompressResult:- """Result of compressing messages.-- Attributes:- messages: The compressed messages (same format as input).- tokens_before: Token count before compression.- tokens_after: Token count after compression.- tokens_saved: Tokens removed by compression.- compression_ratio: Ratio of tokens saved (0.0 = no savings, 1.0 = 100% removed).- transforms_applied: List of transforms that were applied.- """-- messages: list[dict[str, Any]]- tokens_before: int = 0- tokens_after: int = 0- tokens_saved: int = 0- compression_ratio: float = 0.0- transforms_applied: list[str] = field(default_factory=list)---def compress(- messages: list[dict[str, Any]],- model: str = "claude-sonnet-4-5-20250929",- model_limit: int = 200000,- optimize: bool = True,- hooks: Any = None,- config: CompressConfig | None = None,- **kwargs: Any,-) -> CompressResult:- """Compress messages using Headroom's full compression pipeline.-- This is the simplest way to use Headroom. No proxy, no config needed.- Just pass messages and get compressed messages back.-- Args:- messages: List of messages in Anthropic or OpenAI format.- model: Model name (used for token counting and context limit).- model_limit: Model's context window size in tokens.- optimize: Whether to actually compress (False = passthrough for A/B testing).- hooks: Optional CompressionHooks instance for custom behavior.- config: Compression options (CompressConfig). Overrides defaults.- **kwargs: Shorthand for CompressConfig fields. These override config:- compress_user_messages, target_ratio, protect_recent,- protect_analysis_context, kompress_model.-- Returns:- CompressResult with compressed messages and metrics.-- Examples::-- # Default (coding agent)- result = compress(messages, model="gpt-4o")-- # Financial document (keep 50%, compress everything)- result = compress(messages, model="claude-opus-4-20250514",- compress_user_messages=True,- target_ratio=0.5,- protect_recent=0,- )- """- if not messages or not optimize:- return CompressResult(messages=messages)-- # Build config from explicit config + kwargs- cfg = config or CompressConfig()- config_fields = {f.name for f in cfg.__dataclass_fields__.values()}- for key, value in kwargs.items():- if key in config_fields:- setattr(cfg, key, value)-- pipeline = _get_pipeline()- pipeline_extensions = PipelineExtensionManager(hooks=hooks, discover=False)-- try:- # Compute biases from hooks if provided- biases = None- if hooks:- from headroom.hooks import CompressContext-- ctx = CompressContext(model=model)- messages = hooks.pre_compress(messages, ctx)- biases = hooks.compute_biases(messages, ctx)-- received_event = pipeline_extensions.emit(- PipelineStage.INPUT_RECEIVED,- operation="compress",- model=model,- messages=messages,- )- if received_event.messages is not None:- messages = received_event.messages-- # Extract user query from messages so transforms can score by- # relevance. Without this, SmartCrusher selects items by statistics- # alone (position, anomaly) and may drop relevant content.- context = _extract_user_query(messages)-- result = pipeline.apply(- messages=messages,- model=model,- model_limit=model_limit,- context=context,- biases=biases,- # Pass CompressConfig options through to transforms- compress_user_messages=cfg.compress_user_messages,- compress_system_messages=cfg.compress_system_messages,- target_ratio=cfg.target_ratio,- protect_recent=cfg.protect_recent,- protect_analysis_context=cfg.protect_analysis_context,- min_tokens_to_compress=cfg.min_tokens_to_compress,- kompress_model=cfg.kompress_model,- )-- tokens_before = result.tokens_before- tokens_after = result.tokens_after- compressed_messages = result.messages-- routing_markers = summarize_routing_markers(result.transforms_applied)- if routing_markers:- routed_event = pipeline_extensions.emit(- PipelineStage.INPUT_ROUTED,- operation="compress",- model=model,- messages=compressed_messages,- metadata={- "routing_markers": routing_markers,- "transforms_applied": result.transforms_applied,- },- )- if routed_event.messages is not None:- compressed_messages = routed_event.messages-- compressed_event = pipeline_extensions.emit(- PipelineStage.INPUT_COMPRESSED,- operation="compress",- model=model,- messages=compressed_messages,- metadata={- "tokens_before": tokens_before,- "tokens_after": tokens_after,- "transforms_applied": result.transforms_applied,- },- )- if compressed_event.messages is not None:- compressed_messages = compressed_event.messages-- tokens_saved = tokens_before - tokens_after- ratio = tokens_saved / tokens_before if tokens_before > 0 else 0.0-- # Post-compress hook- if hooks and tokens_saved > 0:- from headroom.hooks import CompressEvent-- hooks.post_compress(- CompressEvent(- tokens_before=tokens_before,- tokens_after=tokens_after,- tokens_saved=tokens_saved,- compression_ratio=ratio,- transforms_applied=result.transforms_applied,- model=model,- )- )-- return CompressResult(- messages=compressed_messages,- tokens_before=tokens_before,- tokens_after=tokens_after,- tokens_saved=tokens_saved,- compression_ratio=ratio,- transforms_applied=result.transforms_applied,- )-- except Exception as e:- get_otel_metrics().record_compression_failure(- model=model,- operation="compress",- error_type=type(e).__name__,- )- logger.warning("Compression failed, returning original messages: %s", e)- return CompressResult(- messages=messages,- tokens_before=0,- tokens_after=0,- tokens_saved=0,- compression_ratio=0.0,- )---def _get_pipeline() -> Any:- """Get or create the singleton compression pipeline."""- global _pipeline-- if _pipeline is not None:- return _pipeline-- with _pipeline_lock:- if _pipeline is not None:- return _pipeline-- from headroom.transforms import TransformPipeline-- # Default pipeline: CacheAligner → ContentRouter → IntelligentContext- # CacheAligner: stabilizes prefix for provider KV cache hits- # ContentRouter: routes to the right compressor per content type- # (SmartCrusher for JSON, CodeCompressor for code, Kompress for text)- # IntelligentContext: enforces token limits with score-based dropping- _pipeline = TransformPipeline()- logger.debug("Headroom compression pipeline initialized")- return _pipeline+"""One-function compression API for Headroom.++The simplest way to use Headroom — no proxy, no config, just compress:++ from headroom import compress++ result = compress(messages, model="claude-sonnet-4-5-20250929")+ result.messages # Compressed messages (same format, fewer tokens)+ result.tokens_saved # Tokens saved+ result.compression_ratio # e.g., 0.35 means 65% saved++Works with any LLM client, any proxy, any framework. Just compress+the messages before sending them.++Examples:++ # With Anthropic SDK+ from anthropic import Anthropic+ from headroom import compress++ client = Anthropic()+ messages = [{"role": "user", "content": huge_tool_output}]+ compressed = compress(messages, model="claude-sonnet-4-5-20250929")+ response = client.messages.create(+ model="claude-sonnet-4-5-20250929",+ messages=compressed.messages,+ )++ # With OpenAI SDK+ from openai import OpenAI+ from headroom import compress++ client = OpenAI()+ messages = [{"role": "user", "content": "analyze this"}, {"role": "tool", "content": big_data}]+ compressed = compress(messages, model="gpt-4o")+ response = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)++ # With LiteLLM+ import litellm+ from headroom import compress++ messages = [...]+ compressed = compress(messages, model="bedrock/claude-sonnet")+ response = litellm.completion(model="bedrock/claude-sonnet", messages=compressed.messages)++ # With any HTTP client+ import httpx+ from headroom import compress++ compressed = compress(messages, model="claude-sonnet-4-5-20250929")+ httpx.post("https://api.anthropic.com/v1/messages", json={+ "model": "claude-sonnet-4-5-20250929",+ "messages": compressed.messages,+ })+"""++from __future__ import annotations++import logging+import threading+from dataclasses import dataclass, field+from typing import Any++from .observability import get_otel_metrics+from .pipeline import PipelineExtensionManager, PipelineStage, summarize_routing_markers+from .utils import extract_user_query as _extract_user_query++logger = logging.getLogger(__name__)+++# Lazy-initialized singleton pipeline+_pipeline = None+_pipeline_lock = threading.Lock()+++@dataclass+class CompressConfig:+ """User-facing compression options.++ Controls what gets compressed, how aggressively, and with which model.+ Pass to ``compress()`` or any integration that uses headroom.++ Examples::++ # Coding agent (default — skip user messages, protect recent)+ compress(messages, model="gpt-4o")++ # Financial document (compress everything, keep 50%)+ compress(messages, model="claude-opus-4-20250514",+ compress_user_messages=True,+ target_ratio=0.5,+ protect_recent=0,+ )++ # Aggressive (logs, search results)+ compress(messages, model="gpt-4o", target_ratio=0.2)+ """++ # What to compress+ compress_user_messages: bool = False+ """Compress user messages too (default: skip them for coding agents).+ Set True for document compression, RAG pipelines, or when user messages+ contain large tool outputs."""++ compress_system_messages: bool = True+ """Compress system messages (default: True).+ Set False to preserve system prompts exactly as-is. Useful for voice+ agents where tool definitions and instructions must not be altered."""++ protect_recent: int = 4+ """Don't compress the last N messages (they're the active conversation).+ Set 0 to compress everything."""++ protect_analysis_context: bool = True+ """Detect 'analyze'/'review' intent and protect code from compression."""++ # How aggressive+ target_ratio: float | None = None+ """Keep ratio for Kompress. None = model decides (~15% kept, aggressive).+ 0.5 = keep 50% (safe for documents). 0.7 = keep 70% (conservative).+ Only affects Kompress (text compression). SmartCrusher (JSON) has its+ own logic based on array dedup."""++ min_tokens_to_compress: int = 250+ """Minimum token count for a message to be compressed.+ Messages shorter than this are left unchanged. Default 250.+ Set lower for voice agents where turns are short."""++ # Model variant+ kompress_model: str | None = None+ """Kompress model ID. None = default (chopratejas/kompress-base).+ Set to a HuggingFace model ID for domain-specific compression.+ Set to 'disabled' to skip ML compression entirely+ (only SmartCrusher + CacheAligner will run)."""+++@dataclass+class CompressResult:+ """Result of compressing messages.++ Attributes:+ messages: The compressed messages (same format as input).+ tokens_before: Token count before compression.+ tokens_after: Token count after compression.+ tokens_saved: Tokens removed by compression.+ compression_ratio: Ratio of tokens saved (0.0 = no savings, 1.0 = 100% removed).+ transforms_applied: List of transforms that were applied.+ """++ messages: list[dict[str, Any]]+ tokens_before: int = 0+ tokens_after: int = 0+ tokens_saved: int = 0+ compression_ratio: float = 0.0+ transforms_applied: list[str] = field(default_factory=list)+++def compress(+ messages: list[dict[str, Any]],+ model: str = "claude-sonnet-4-5-20250929",+ model_limit: int = 200000,+ optimize: bool = True,+ hooks: Any = None,+ config: CompressConfig | None = None,+ **kwargs: Any,+) -> CompressResult:+ """Compress messages using Headroom's full compression pipeline.++ This is the simplest way to use Headroom. No proxy, no config needed.+ Just pass messages and get compressed messages back.++ Args:+ messages: List of messages in Anthropic or OpenAI format.+ model: Model name (used for token counting and context limit).+ model_limit: Model's context window size in tokens.+ optimize: Whether to actually compress (False = passthrough for A/B testing).+ hooks: Optional CompressionHooks instance for custom behavior.+ config: Compression options (CompressConfig). Overrides defaults.+ **kwargs: Shorthand for CompressConfig fields. These override config:+ compress_user_messages, target_ratio, protect_recent,+ protect_analysis_context, kompress_model.++ Returns:+ CompressResult with compressed messages and metrics.++ Examples::++ # Default (coding agent)+ result = compress(messages, model="gpt-4o")++ # Financial document (keep 50%, compress everything)+ result = compress(messages, model="claude-opus-4-20250514",+ compress_user_messages=True,+ target_ratio=0.5,+ protect_recent=0,+ )+ """+ if not messages or not optimize:+ return CompressResult(messages=messages)++ # Build config from explicit config + kwargs+ cfg = config or CompressConfig()+ config_fields = {f.name for f in cfg.__dataclass_fields__.values()}+ for key, value in kwargs.items():+ if key in config_fields:+ setattr(cfg, key, value)++ pipeline = _get_pipeline()+ pipeline_extensions = PipelineExtensionManager(hooks=hooks, discover=False)++ try:+ # Compute biases from hooks if provided+ biases = None+ if hooks:+ from headroom.hooks import CompressContext++ ctx = CompressContext(model=model)+ messages = hooks.pre_compress(messages, ctx)+ biases = hooks.compute_biases(messages, ctx)++ received_event = pipeline_extensions.emit(+ PipelineStage.INPUT_RECEIVED,+ operation="compress",+ model=model,+ messages=messages,+ )+ if received_event.messages is not None:+ messages = received_event.messages++ # Extract user query from messages so transforms can score by+ # relevance. Without this, SmartCrusher selects items by statistics+ # alone (position, anomaly) and may drop relevant content.+ context = _extract_user_query(messages)++ result = pipeline.apply(+ messages=messages,+ model=model,+ model_limit=model_limit,+ context=context,+ biases=biases,+ # Pass CompressConfig options through to transforms+ compress_user_messages=cfg.compress_user_messages,+ compress_system_messages=cfg.compress_system_messages,+ target_ratio=cfg.target_ratio,+ protect_recent=cfg.protect_recent,+ protect_analysis_context=cfg.protect_analysis_context,+ min_tokens_to_compress=cfg.min_tokens_to_compress,+ kompress_model=cfg.kompress_model,+ )++ tokens_before = result.tokens_before+ tokens_after = result.tokens_after+ compressed_messages = result.messages++ routing_markers = summarize_routing_markers(result.transforms_applied)+ if routing_markers:+ routed_event = pipeline_extensions.emit(+ PipelineStage.INPUT_ROUTED,+ operation="compress",+ model=model,+ messages=compressed_messages,+ metadata={+ "routing_markers": routing_markers,+ "transforms_applied": result.transforms_applied,+ },+ )+ if routed_event.messages is not None:+ compressed_messages = routed_event.messages++ compressed_event = pipeline_extensions.emit(+ PipelineStage.INPUT_COMPRESSED,+ operation="compress",+ model=model,+ messages=compressed_messages,+ metadata={+ "tokens_before": tokens_before,+ "tokens_after": tokens_after,+ "transforms_applied": result.transforms_applied,+ },+ )+ if compressed_event.messages is not None:+ compressed_messages = compressed_event.messages++ tokens_saved = tokens_before - tokens_after+ ratio = tokens_saved / tokens_before if tokens_before > 0 else 0.0++ # Post-compress hook+ if hooks and tokens_saved > 0:+ from headroom.hooks import CompressEvent++ hooks.post_compress(+ CompressEvent(+ tokens_before=tokens_before,+ tokens_after=tokens_after,+ tokens_saved=tokens_saved,+ compression_ratio=ratio,+ transforms_applied=result.transforms_applied,+ model=model,+ )+ )++ return CompressResult(+ messages=compressed_messages,+ tokens_before=tokens_before,+ tokens_after=tokens_after,+ tokens_saved=tokens_saved,+ compression_ratio=ratio,+ transforms_applied=result.transforms_applied,+ )++ except Exception as e:+ get_otel_metrics().record_compression_failure(+ model=model,+ operation="compress",+ error_type=type(e).__name__,+ )+ logger.warning("Compression failed, returning original messages: %s", e)+ return CompressResult(+ messages=messages,+ tokens_before=0,+ tokens_after=0,+ tokens_saved=0,+ compression_ratio=0.0,+ )+++def _get_pipeline() -> Any:+ """Get or create the singleton compression pipeline."""+ global _pipeline++ if _pipeline is not None:+ return _pipeline++ with _pipeline_lock:+ if _pipeline is not None:+ return _pipeline++ from headroom.transforms import TransformPipeline++ # Default pipeline: CacheAligner → ContentRouter → IntelligentContext+ # CacheAligner: stabilizes prefix for provider KV cache hits+ # ContentRouter: routes to the right compressor per content type+ # (SmartCrusher for JSON, CodeCompressor for code, Kompress for text)+ # IntelligentContext: enforces token limits with score-based dropping+ _pipeline = TransformPipeline()+ logger.debug("Headroom compression pipeline initialized")+ return _pipelinediff --git a/headroom/copilot_auth.py b/headroom/copilot_auth.pyindex 4f8c8a577..ef77d6cae 100644--- a/headroom/copilot_auth.py+++ b/headroom/copilot_auth.py@@ -1,444 +1,444 @@-"""GitHub Copilot OAuth discovery and API-token exchange helpers."""--from __future__ import annotations--import asyncio-import ctypes-import json-import logging-import os-import subprocess-import time-from ctypes import wintypes-from dataclasses import dataclass-from datetime import datetime-from pathlib import Path-from typing import Any-from urllib import error as urllib_error-from urllib import request as urllib_request-from urllib.parse import urlparse--logger = logging.getLogger(__name__)--DEFAULT_API_URL = "https://api.githubcopilot.com"-DEFAULT_TOKEN_EXCHANGE_URL = "https://api.github.com/copilot_internal/v2/token"-DEFAULT_GITHUB_HOST = "github.com"-_TOKEN_EXPIRY_BUFFER_S = 60-_DEFAULT_EDITOR_VERSION = "vscode/1.104.1"-_DEFAULT_USER_AGENT = "GitHubCopilotChat/0.1"--_API_TOKEN_ENV_VARS = (- "GITHUB_COPILOT_API_TOKEN",- "COPILOT_PROVIDER_BEARER_TOKEN",-)-_OAUTH_TOKEN_ENV_VARS = (- "GITHUB_COPILOT_GITHUB_TOKEN",- "GITHUB_COPILOT_TOKEN",- "GITHUB_TOKEN",- "COPILOT_GITHUB_TOKEN",-)-_OAUTH_TOKEN_KEYS = (- "oauth_token",- "oauthToken",- "token",- "access_token",- "accessToken",-)-_EXPIRY_KEYS = ("expires_at", "expiresAt", "expiry", "expires")---@dataclass(frozen=True)-class CopilotAPIToken:- """Short-lived API token exchanged from a GitHub OAuth token."""-- token: str- expires_at: float- api_url: str = DEFAULT_API_URL- refresh_in: int | None = None- sku: str | None = None-- @property- def is_valid(self) -> bool:- return time.time() < (self.expires_at - _TOKEN_EXPIRY_BUFFER_S)---def _github_host() -> str:- return (os.environ.get("GITHUB_COPILOT_HOST") or DEFAULT_GITHUB_HOST).strip().lower()---def _token_exchange_url() -> str:- return os.environ.get("GITHUB_COPILOT_TOKEN_EXCHANGE_URL", DEFAULT_TOKEN_EXCHANGE_URL).strip()---def _should_exchange_oauth_token() -> bool:- raw = os.environ.get("GITHUB_COPILOT_USE_TOKEN_EXCHANGE", "").strip().lower()- return raw in {"1", "true", "yes", "on"}---def _resolve_token_file_paths() -> list[Path]:- override = os.environ.get("GITHUB_COPILOT_TOKEN_FILE", "").strip()- if override:- return [Path(override).expanduser()]-- paths: list[Path] = []- local_appdata = os.environ.get("LOCALAPPDATA", "").strip()- if local_appdata:- base = Path(local_appdata) / "github-copilot"- paths.extend([base / "apps.json", base / "hosts.json"])-- config_base = Path.home() / ".config" / "github-copilot"- paths.extend([config_base / "apps.json", config_base / "hosts.json"])- return paths---def _read_gh_cli_oauth_token() -> str | None:- gh_bin = os.environ.get("GH_PATH", "").strip() or "gh"- command = [gh_bin, "auth", "token"]- host = _github_host()- if host and host != DEFAULT_GITHUB_HOST:- command.extend(["--hostname", host])-- try:- result = subprocess.run(- command,- capture_output=True,- text=True,- encoding="utf-8",- errors="replace",- check=False,- )- except OSError as exc:- logger.debug("Unable to invoke GitHub CLI for Copilot auth discovery: %s", exc)- return None-- if result.returncode != 0:- logger.debug("GitHub CLI auth token lookup failed with exit code %s", result.returncode)- return None-- token = result.stdout.strip()- return token or None---def _read_windows_copilot_cli_oauth_token() -> str | None:- if os.name != "nt":- return None-- class FILETIME(ctypes.Structure):- _fields_ = [- ("dwLowDateTime", wintypes.DWORD),- ("dwHighDateTime", wintypes.DWORD),- ]-- class CREDENTIAL(ctypes.Structure):- _fields_ = [- ("Flags", wintypes.DWORD),- ("Type", wintypes.DWORD),- ("TargetName", wintypes.LPWSTR),- ("Comment", wintypes.LPWSTR),- ("LastWritten", FILETIME),- ("CredentialBlobSize", wintypes.DWORD),- ("CredentialBlob", ctypes.POINTER(ctypes.c_ubyte)),- ("Persist", wintypes.DWORD),- ("AttributeCount", wintypes.DWORD),- ("Attributes", wintypes.LPVOID),- ("TargetAlias", wintypes.LPWSTR),- ("UserName", wintypes.LPWSTR),- ]-- cred_ptr = ctypes.POINTER(CREDENTIAL)- credentials = ctypes.POINTER(cred_ptr)()- count = wintypes.DWORD()- win_dll = getattr(ctypes, "WinDLL", None)- if win_dll is None:- return None-- advapi32 = win_dll("Advapi32.dll")- advapi32.CredEnumerateW.argtypes = [- wintypes.LPCWSTR,- wintypes.DWORD,- ctypes.POINTER(wintypes.DWORD),- ctypes.POINTER(ctypes.POINTER(cred_ptr)),- ]- advapi32.CredEnumerateW.restype = wintypes.BOOL- advapi32.CredFree.argtypes = [wintypes.LPVOID]-- try:- if not advapi32.CredEnumerateW(None, 0, ctypes.byref(count), ctypes.byref(credentials)):- return None- except OSError as exc:- logger.debug("Unable to enumerate Windows credentials for Copilot auth discovery: %s", exc)- return None-- host = _github_host().lower()- service_prefixes = [f"copilot-cli/{host}:"]- if "://" not in host:- service_prefixes.append(f"copilot-cli/https://{host}:")-- try:- for idx in range(count.value):- credential = credentials[idx].contents- target = (credential.TargetName or "").strip().lower()- if not any(target.startswith(prefix) for prefix in service_prefixes):- continue- if credential.CredentialBlobSize <= 0 or not credential.CredentialBlob:- continue- blob = ctypes.string_at(credential.CredentialBlob, credential.CredentialBlobSize)- token = blob.decode("utf-8", errors="replace").strip()- if token:- return token- finally:- if credentials:- advapi32.CredFree(credentials)-- return None---def _parse_expiry(value: Any) -> float | None:- if value in (None, ""):- return None-- if isinstance(value, int | float):- number = float(value)- if number > 10_000_000_000:- return number / 1000.0- return number-- if isinstance(value, str):- raw = value.strip()- if not raw:- return None- if raw.isdigit():- return _parse_expiry(int(raw))- try:- normalized = raw.replace("Z", "+00:00")- return datetime.fromisoformat(normalized).timestamp()- except ValueError:- return None-- return None---def _entry_expired(entry: dict[str, Any]) -> bool:- for key in _EXPIRY_KEYS:- expiry = _parse_expiry(entry.get(key))- if expiry is None:- continue- return time.time() >= (expiry - _TOKEN_EXPIRY_BUFFER_S)- return False---def _extract_oauth_token(entry: dict[str, Any]) -> str | None:- if _entry_expired(entry):- return None-- for key in _OAUTH_TOKEN_KEYS:- value = entry.get(key)- if isinstance(value, str) and value.strip():- return value.strip()-- for value in entry.values():- if isinstance(value, dict):- nested = _extract_oauth_token(value)- if nested:- return nested-- return None---def _iter_file_entries(payload: Any) -> list[tuple[str, dict[str, Any]]]:- entries: list[tuple[str, dict[str, Any]]] = []- if isinstance(payload, dict):- for key, value in payload.items():- if isinstance(value, dict):- entries.append((str(key), value))- elif isinstance(payload, list):- for idx, value in enumerate(payload):- if isinstance(value, dict):- key = str(value.get("host") or value.get("githubHost") or idx)- entries.append((key, value))- return entries---def read_cached_oauth_token() -> str | None:- """Return a GitHub OAuth token for Copilot, if one is available."""-- for env_var in _OAUTH_TOKEN_ENV_VARS:- token = os.environ.get(env_var, "").strip()- if token:- return token-- windows_copilot_token = _read_windows_copilot_cli_oauth_token()- if windows_copilot_token:- return windows_copilot_token-- gh_token = _read_gh_cli_oauth_token()- if gh_token:- return gh_token-- host = _github_host()- for path in _resolve_token_file_paths():- try:- payload = json.loads(path.read_text(encoding="utf-8"))- except FileNotFoundError:- continue- except Exception as exc:- logger.debug("Unable to read Copilot credentials file %s: %s", path, exc)- continue-- for key, entry in _iter_file_entries(payload):- if host not in key.lower():- continue- cached_token = _extract_oauth_token(entry)- if cached_token:- return cached_token-- return None---def resolve_client_bearer_token() -> str | None:- """Return a bearer token suitable for satisfying Copilot provider auth checks."""-- for env_var in _API_TOKEN_ENV_VARS:- token = os.environ.get(env_var, "").strip()- if token:- return token- return read_cached_oauth_token()---def has_oauth_auth() -> bool:- """Return True when existing Copilot auth can be reused."""-- return resolve_client_bearer_token() is not None---def is_copilot_api_url(url: str | None) -> bool:- """Return True when the upstream URL points at GitHub Copilot."""-- if not url:- return False- parsed = urlparse(url)- host = parsed.netloc.lower() or parsed.path.lower()- return "githubcopilot.com" in host---def build_copilot_upstream_url(base_url: str, path: str) -> str:- """Build an upstream URL, normalizing GitHub Copilot's non-/v1 path layout."""-- normalized_base = base_url.rstrip("/")- normalized_path = path if path.startswith("/") else f"/{path}"- if is_copilot_api_url(normalized_base) and normalized_path.startswith("/v1/"):- normalized_path = normalized_path[3:]- return f"{normalized_base}{normalized_path}"---class CopilotTokenProvider:- """Resolve and cache short-lived Copilot API tokens."""-- def __init__(self) -> None:- self._lock = asyncio.Lock()- self._cached: CopilotAPIToken | None = None-- async def get_api_token(self) -> CopilotAPIToken:- explicit_api_token = os.environ.get("GITHUB_COPILOT_API_TOKEN", "").strip()- if explicit_api_token:- return CopilotAPIToken(- token=explicit_api_token,- expires_at=time.time() + 3600,- api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()- or DEFAULT_API_URL,- )-- cached = self._cached- if cached is not None and cached.is_valid:- return cached-- async with self._lock:- cached = self._cached- if cached is not None and cached.is_valid:- return cached-- oauth_token = read_cached_oauth_token()- if not oauth_token:- raise RuntimeError("No GitHub Copilot OAuth token is available.")-- if not _should_exchange_oauth_token():- direct_token = CopilotAPIToken(- token=oauth_token,- expires_at=time.time() + 3600,- api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()- or DEFAULT_API_URL,- )- self._cached = direct_token- return direct_token-- exchanged = await self._exchange_token(oauth_token)- self._cached = exchanged- return exchanged-- async def _exchange_token(self, oauth_token: str) -> CopilotAPIToken:- headers = {- "Authorization": f"token {oauth_token}",- "Accept": "application/json",- "Editor-Version": os.environ.get(- "GITHUB_COPILOT_EDITOR_VERSION", _DEFAULT_EDITOR_VERSION- ),- "User-Agent": _DEFAULT_USER_AGENT,- }- payload = await asyncio.to_thread(self._exchange_token_sync, headers)- token = str(payload.get("token") or "").strip()- if not token:- raise RuntimeError("Copilot token exchange returned an empty token.")-- expires_at = _parse_expiry(payload.get("expires_at")) or (time.time() + 1800)- raw_endpoints = payload.get("endpoints")- endpoints: dict[str, Any] = raw_endpoints if isinstance(raw_endpoints, dict) else {}- api_url = str(endpoints.get("api") or DEFAULT_API_URL).strip() or DEFAULT_API_URL- refresh_in = payload.get("refresh_in")- sku = payload.get("sku")- return CopilotAPIToken(- token=token,- expires_at=expires_at,- api_url=api_url,- refresh_in=int(refresh_in) if isinstance(refresh_in, int | float) else None,- sku=str(sku) if isinstance(sku, str) and sku.strip() else None,- )-- @staticmethod- def _exchange_token_sync(headers: dict[str, str]) -> dict[str, Any]:- request = urllib_request.Request(_token_exchange_url(), headers=headers, method="GET")- try:- with urllib_request.urlopen(request, timeout=10.0) as response:- payload = json.loads(response.read().decode("utf-8"))- return payload if isinstance(payload, dict) else {}- except urllib_error.HTTPError as exc:- body = exc.read().decode("utf-8", errors="replace")- raise RuntimeError(- f"Copilot token exchange failed with HTTP {exc.code}: {body}"- ) from exc---_provider: CopilotTokenProvider | None = None---def get_copilot_token_provider() -> CopilotTokenProvider:- """Return the shared Copilot token provider."""-- global _provider- if _provider is None:- _provider = CopilotTokenProvider()- return _provider---async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[str, str]:- """Replace Authorization with a fresh Copilot API token when targeting Copilot."""-- resolved = dict(headers)- if not is_copilot_api_url(url):- return resolved-- token = await get_copilot_token_provider().get_api_token()- for key in list(resolved):- if key.lower() == "authorization":- resolved.pop(key)- resolved["Authorization"] = f"Bearer {token.token}"- return resolved+"""GitHub Copilot OAuth discovery and API-token exchange helpers."""++from __future__ import annotations++import asyncio+import ctypes+import json+import logging+import os+import subprocess+import time+from ctypes import wintypes+from dataclasses import dataclass+from datetime import datetime+from pathlib import Path+from typing import Any+from urllib import error as urllib_error+from urllib import request as urllib_request+from urllib.parse import urlparse++logger = logging.getLogger(__name__)++DEFAULT_API_URL = "https://api.githubcopilot.com"+DEFAULT_TOKEN_EXCHANGE_URL = "https://api.github.com/copilot_internal/v2/token"+DEFAULT_GITHUB_HOST = "github.com"+_TOKEN_EXPIRY_BUFFER_S = 60+_DEFAULT_EDITOR_VERSION = "vscode/1.104.1"+_DEFAULT_USER_AGENT = "GitHubCopilotChat/0.1"++_API_TOKEN_ENV_VARS = (+ "GITHUB_COPILOT_API_TOKEN",+ "COPILOT_PROVIDER_BEARER_TOKEN",+)+_OAUTH_TOKEN_ENV_VARS = (+ "GITHUB_COPILOT_GITHUB_TOKEN",+ "GITHUB_COPILOT_TOKEN",+ "GITHUB_TOKEN",+ "COPILOT_GITHUB_TOKEN",+)+_OAUTH_TOKEN_KEYS = (+ "oauth_token",+ "oauthToken",+ "token",+ "access_token",+ "accessToken",+)+_EXPIRY_KEYS = ("expires_at", "expiresAt", "expiry", "expires")+++@dataclass(frozen=True)+class CopilotAPIToken:+ """Short-lived API token exchanged from a GitHub OAuth token."""++ token: str+ expires_at: float+ api_url: str = DEFAULT_API_URL+ refresh_in: int | None = None+ sku: str | None = None++ @property+ def is_valid(self) -> bool:+ return time.time() < (self.expires_at - _TOKEN_EXPIRY_BUFFER_S)+++def _github_host() -> str:+ return (os.environ.get("GITHUB_COPILOT_HOST") or DEFAULT_GITHUB_HOST).strip().lower()+++def _token_exchange_url() -> str:+ return os.environ.get("GITHUB_COPILOT_TOKEN_EXCHANGE_URL", DEFAULT_TOKEN_EXCHANGE_URL).strip()+++def _should_exchange_oauth_token() -> bool:+ raw = os.environ.get("GITHUB_COPILOT_USE_TOKEN_EXCHANGE", "").strip().lower()+ return raw in {"1", "true", "yes", "on"}+++def _resolve_token_file_paths() -> list[Path]:+ override = os.environ.get("GITHUB_COPILOT_TOKEN_FILE", "").strip()+ if override:+ return [Path(override).expanduser()]++ paths: list[Path] = []+ local_appdata = os.environ.get("LOCALAPPDATA", "").strip()+ if local_appdata:+ base = Path(local_appdata) / "github-copilot"+ paths.extend([base / "apps.json", base / "hosts.json"])++ config_base = Path.home() / ".config" / "github-copilot"+ paths.extend([config_base / "apps.json", config_base / "hosts.json"])+ return paths+++def _read_gh_cli_oauth_token() -> str | None:+ gh_bin = os.environ.get("GH_PATH", "").strip() or "gh"+ command = [gh_bin, "auth", "token"]+ host = _github_host()+ if host and host != DEFAULT_GITHUB_HOST:+ command.extend(["--hostname", host])++ try:+ result = subprocess.run(+ command,+ capture_output=True,+ text=True,+ encoding="utf-8",+ errors="replace",+ check=False,+ )+ except OSError as exc:+ logger.debug("Unable to invoke GitHub CLI for Copilot auth discovery: %s", exc)+ return None++ if result.returncode != 0:+ logger.debug("GitHub CLI auth token lookup failed with exit code %s", result.returncode)+ return None++ token = result.stdout.strip()+ return token or None+++def _read_windows_copilot_cli_oauth_token() -> str | None:+ if os.name != "nt":+ return None++ class FILETIME(ctypes.Structure):+ _fields_ = [+ ("dwLowDateTime", wintypes.DWORD),+ ("dwHighDateTime", wintypes.DWORD),+ ]++ class CREDENTIAL(ctypes.Structure):+ _fields_ = [+ ("Flags", wintypes.DWORD),+ ("Type", wintypes.DWORD),+ ("TargetName", wintypes.LPWSTR),+ ("Comment", wintypes.LPWSTR),+ ("LastWritten", FILETIME),+ ("CredentialBlobSize", wintypes.DWORD),+ ("CredentialBlob", ctypes.POINTER(ctypes.c_ubyte)),+ ("Persist", wintypes.DWORD),+ ("AttributeCount", wintypes.DWORD),+ ("Attributes", wintypes.LPVOID),+ ("TargetAlias", wintypes.LPWSTR),+ ("UserName", wintypes.LPWSTR),+ ]++ cred_ptr = ctypes.POINTER(CREDENTIAL)+ credentials = ctypes.POINTER(cred_ptr)()+ count = wintypes.DWORD()+ win_dll = getattr(ctypes, "WinDLL", None)+ if win_dll is None:+ return None++ advapi32 = win_dll("Advapi32.dll")+ advapi32.CredEnumerateW.argtypes = [+ wintypes.LPCWSTR,+ wintypes.DWORD,+ ctypes.POINTER(wintypes.DWORD),+ ctypes.POINTER(ctypes.POINTER(cred_ptr)),+ ]+ advapi32.CredEnumerateW.restype = wintypes.BOOL+ advapi32.CredFree.argtypes = [wintypes.LPVOID]++ try:+ if not advapi32.CredEnumerateW(None, 0, ctypes.byref(count), ctypes.byref(credentials)):+ return None+ except OSError as exc:+ logger.debug("Unable to enumerate Windows credentials for Copilot auth discovery: %s", exc)+ return None++ host = _github_host().lower()+ service_prefixes = [f"copilot-cli/{host}:"]+ if "://" not in host:+ service_prefixes.append(f"copilot-cli/https://{host}:")++ try:+ for idx in range(count.value):+ credential = credentials[idx].contents+ target = (credential.TargetName or "").strip().lower()+ if not any(target.startswith(prefix) for prefix in service_prefixes):+ continue+ if credential.CredentialBlobSize <= 0 or not credential.CredentialBlob:+ continue+ blob = ctypes.string_at(credential.CredentialBlob, credential.CredentialBlobSize)+ token = blob.decode("utf-8", errors="replace").strip()+ if token:+ return token+ finally:+ if credentials:+ advapi32.CredFree(credentials)++ return None+++def _parse_expiry(value: Any) -> float | None:+ if value in (None, ""):+ return None++ if isinstance(value, int | float):+ number = float(value)+ if number > 10_000_000_000:+ return number / 1000.0+ return number++ if isinstance(value, str):+ raw = value.strip()+ if not raw:+ return None+ if raw.isdigit():+ return _parse_expiry(int(raw))+ try:+ normalized = raw.replace("Z", "+00:00")+ return datetime.fromisoformat(normalized).timestamp()+ except ValueError:+ return None++ return None+++def _entry_expired(entry: dict[str, Any]) -> bool:+ for key in _EXPIRY_KEYS:+ expiry = _parse_expiry(entry.get(key))+ if expiry is None:+ continue+ return time.time() >= (expiry - _TOKEN_EXPIRY_BUFFER_S)+ return False+++def _extract_oauth_token(entry: dict[str, Any]) -> str | None:+ if _entry_expired(entry):+ return None++ for key in _OAUTH_TOKEN_KEYS:+ value = entry.get(key)+ if isinstance(value, str) and value.strip():+ return value.strip()++ for value in entry.values():+ if isinstance(value, dict):+ nested = _extract_oauth_token(value)+ if nested:+ return nested++ return None+++def _iter_file_entries(payload: Any) -> list[tuple[str, dict[str, Any]]]:+ entries: list[tuple[str, dict[str, Any]]] = []+ if isinstance(payload, dict):+ for key, value in payload.items():+ if isinstance(value, dict):+ entries.append((str(key), value))+ elif isinstance(payload, list):+ for idx, value in enumerate(payload):+ if isinstance(value, dict):+ key = str(value.get("host") or value.get("githubHost") or idx)+ entries.append((key, value))+ return entries+++def read_cached_oauth_token() -> str | None:+ """Return a GitHub OAuth token for Copilot, if one is available."""++ for env_var in _OAUTH_TOKEN_ENV_VARS:+ token = os.environ.get(env_var, "").strip()+ if token:+ return token++ windows_copilot_token = _read_windows_copilot_cli_oauth_token()+ if windows_copilot_token:+ return windows_copilot_token++ gh_token = _read_gh_cli_oauth_token()+ if gh_token:+ return gh_token++ host = _github_host()+ for path in _resolve_token_file_paths():+ try:+ payload = json.loads(path.read_text(encoding="utf-8"))+ except FileNotFoundError:+ continue+ except Exception as exc:+ logger.debug("Unable to read Copilot credentials file %s: %s", path, exc)+ continue++ for key, entry in _iter_file_entries(payload):+ if host not in key.lower():+ continue+ cached_token = _extract_oauth_token(entry)+ if cached_token:+ return cached_token++ return None+++def resolve_client_bearer_token() -> str | None:+ """Return a bearer token suitable for satisfying Copilot provider auth checks."""++ for env_var in _API_TOKEN_ENV_VARS:+ token = os.environ.get(env_var, "").strip()+ if token:+ return token+ return read_cached_oauth_token()+++def has_oauth_auth() -> bool:+ """Return True when existing Copilot auth can be reused."""++ return resolve_client_bearer_token() is not None+++def is_copilot_api_url(url: str | None) -> bool:+ """Return True when the upstream URL points at GitHub Copilot."""++ if not url:+ return False+ parsed = urlparse(url)+ host = parsed.netloc.lower() or parsed.path.lower()+ return "githubcopilot.com" in host+++def build_copilot_upstream_url(base_url: str, path: str) -> str:+ """Build an upstream URL, normalizing GitHub Copilot's non-/v1 path layout."""++ normalized_base = base_url.rstrip("/")+ normalized_path = path if path.startswith("/") else f"/{path}"+ if is_copilot_api_url(normalized_base) and normalized_path.startswith("/v1/"):+ normalized_path = normalized_path[3:]+ return f"{normalized_base}{normalized_path}"+++class CopilotTokenProvider:+ """Resolve and cache short-lived Copilot API tokens."""++ def __init__(self) -> None:+ self._lock = asyncio.Lock()+ self._cached: CopilotAPIToken | None = None++ async def get_api_token(self) -> CopilotAPIToken:+ explicit_api_token = os.environ.get("GITHUB_COPILOT_API_TOKEN", "").strip()+ if explicit_api_token:+ return CopilotAPIToken(+ token=explicit_api_token,+ expires_at=time.time() + 3600,+ api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()+ or DEFAULT_API_URL,+ )++ cached = self._cached+ if cached is not None and cached.is_valid:+ return cached++ async with self._lock:+ cached = self._cached+ if cached is not None and cached.is_valid:+ return cached++ oauth_token = read_cached_oauth_token()+ if not oauth_token:+ raise RuntimeError("No GitHub Copilot OAuth token is available.")++ if not _should_exchange_oauth_token():+ direct_token = CopilotAPIToken(+ token=oauth_token,+ expires_at=time.time() + 3600,+ api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()+ or DEFAULT_API_URL,+ )+ self._cached = direct_token+ return direct_token++ exchanged = await self._exchange_token(oauth_token)+ self._cached = exchanged+ return exchanged++ async def _exchange_token(self, oauth_token: str) -> CopilotAPIToken:+ headers = {+ "Authorization": f"token {oauth_token}",+ "Accept": "application/json",+ "Editor-Version": os.environ.get(+ "GITHUB_COPILOT_EDITOR_VERSION", _DEFAULT_EDITOR_VERSION+ ),+ "User-Agent": _DEFAULT_USER_AGENT,+ }+ payload = await asyncio.to_thread(self._exchange_token_sync, headers)+ token = str(payload.get("token") or "").strip()+ if not token:+ raise RuntimeError("Copilot token exchange returned an empty token.")++ expires_at = _parse_expiry(payload.get("expires_at")) or (time.time() + 1800)+ raw_endpoints = payload.get("endpoints")+ endpoints: dict[str, Any] = raw_endpoints if isinstance(raw_endpoints, dict) else {}+ api_url = str(endpoints.get("api") or DEFAULT_API_URL).strip() or DEFAULT_API_URL+ refresh_in = payload.get("refresh_in")+ sku = payload.get("sku")+ return CopilotAPIToken(+ token=token,+ expires_at=expires_at,+ api_url=api_url,+ refresh_in=int(refresh_in) if isinstance(refresh_in, int | float) else None,+ sku=str(sku) if isinstance(sku, str) and sku.strip() else None,+ )++ @staticmethod+ def _exchange_token_sync(headers: dict[str, str]) -> dict[str, Any]:+ request = urllib_request.Request(_token_exchange_url(), headers=headers, method="GET")+ try:+ with urllib_request.urlopen(request, timeout=10.0) as response:+ payload = json.loads(response.read().decode("utf-8"))+ return payload if isinstance(payload, dict) else {}+ except urllib_error.HTTPError as exc:+ body = exc.read().decode("utf-8", errors="replace")+ raise RuntimeError(+ f"Copilot token exchange failed with HTTP {exc.code}: {body}"+ ) from exc+++_provider: CopilotTokenProvider | None = None+++def get_copilot_token_provider() -> CopilotTokenProvider:+ """Return the shared Copilot token provider."""++ global _provider+ if _provider is None:+ _provider = CopilotTokenProvider()+ return _provider+++async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[str, str]:+ """Replace Authorization with a fresh Copilot API token when targeting Copilot."""++ resolved = dict(headers)+ if not is_copilot_api_url(url):+ return resolved++ token = await get_copilot_token_provider().get_api_token()+ for key in list(resolved):+ if key.lower() == "authorization":+ resolved.pop(key)+ resolved["Authorization"] = f"Bearer {token.token}"+ return resolveddiff --git a/headroom/install/health.py b/headroom/install/health.pyindex 1b4ae2fed..9bad174c8 100644--- a/headroom/install/health.py+++ b/headroom/install/health.py@@ -1,28 +1,28 @@-"""Health helpers for persistent deployments."""--from __future__ import annotations--import json-import urllib.error-import urllib.request-from typing import Any---def probe_json(url: str, timeout: float = 2.0) -> dict[str, Any] | None:- """Return a JSON payload from the URL when reachable."""-- try:- with urllib.request.urlopen(url, timeout=timeout) as response:- payload = json.loads(response.read().decode("utf-8"))- except (OSError, urllib.error.URLError, ValueError, json.JSONDecodeError):- return None- return payload if isinstance(payload, dict) else None---def probe_ready(url: str, timeout: float = 2.0) -> bool:- """Return True when the ready endpoint reports readiness."""-- payload = probe_json(url, timeout=timeout)- if not isinstance(payload, dict):- return False- return bool(payload.get("ready", False) or payload.get("status") == "healthy")+"""Health helpers for persistent deployments."""++from __future__ import annotations++import json+import urllib.error+import urllib.request+from typing import Any+++def probe_json(url: str, timeout: float = 2.0) -> dict[str, Any] | None:+ """Return a JSON payload from the URL when reachable."""++ try:+ with urllib.request.urlopen(url, timeout=timeout) as response:+ payload = json.loads(response.read().decode("utf-8"))+ except (OSError, urllib.error.URLError, ValueError, json.JSONDecodeError):+ return None+ return payload if isinstance(payload, dict) else None+++def probe_ready(url: str, timeout: float = 2.0) -> bool:+ """Return True when the ready endpoint reports readiness."""++ payload = probe_json(url, timeout=timeout)+ if not isinstance(payload, dict):+ return False+ return bool(payload.get("ready", False) or payload.get("status") == "healthy")diff --git a/headroom/install/providers.py b/headroom/install/providers.pyindex 5c410d9ba..4ee7c3d6e 100644--- a/headroom/install/providers.py+++ b/headroom/install/providers.py@@ -1,174 +1,174 @@-"""Tool-target configuration for persistent deployments."""--from __future__ import annotations--import os-import re-import subprocess-from pathlib import Path--from headroom.providers.install_registry import (- apply_provider_scope_mutations,- revert_provider_scope_mutation,-)--from .models import ConfigScope, DeploymentManifest, ManagedMutation-from .paths import (- unix_system_env_targets,- unix_user_env_targets,-)--_ENV_MARKER_START = "# >>> headroom persistent env >>>"-_ENV_MARKER_END = "# <<< headroom persistent env <<<"-_ENV_PATTERN = re.compile(- re.escape(_ENV_MARKER_START) + r".*?" + re.escape(_ENV_MARKER_END),- re.DOTALL,-)---def _merge_marker_block(file_path: Path, block: str, pattern: re.Pattern[str], marker: str) -> str:- if file_path.exists():- existing = file_path.read_text()- if marker in existing:- return pattern.sub(block, existing)- return existing.rstrip() + "\n\n" + block + "\n"- return block + "\n"---def _env_block(values: dict[str, str]) -> str:- lines = [_ENV_MARKER_START]- for name, value in values.items():- lines.append(f'export {name}="{value}"')- lines.append(_ENV_MARKER_END)- return "\n".join(lines)---def _powershell_literal(value: str) -> str:- return "'" + value.replace("'", "''") + "'"---def _unix_scope_values(manifest: DeploymentManifest) -> dict[str, str]:- merged = dict(manifest.base_env)- for env_map in manifest.tool_envs.values():- merged.update(env_map)- return merged---def _apply_unix_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:- values = _unix_scope_values(manifest)- block = _env_block(values)- if manifest.scope == ConfigScope.USER.value:- targets = unix_user_env_targets()- else:- targets = unix_system_env_targets()- mutations: list[ManagedMutation] = []- for path in targets:- path.parent.mkdir(parents=True, exist_ok=True)- merged = _merge_marker_block(path, block, _ENV_PATTERN, _ENV_MARKER_START)- path.write_text(merged)- mutations.append(ManagedMutation(target="env", kind="shell-block", path=str(path)))- return mutations---def _remove_unix_env_scope(mutations: list[ManagedMutation]) -> None:- for mutation in mutations:- if mutation.kind != "shell-block" or not mutation.path:- continue- path = Path(mutation.path)- if not path.exists():- continue- content = path.read_text()- if _ENV_MARKER_START not in content:- continue- path.write_text(_ENV_PATTERN.sub("", content).strip() + "\n")---def _apply_windows_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:- scope_name = "Machine" if manifest.scope == ConfigScope.SYSTEM.value else "User"- merged = _unix_scope_values(manifest)- mutations: list[ManagedMutation] = []- for name, value in merged.items():- previous = subprocess.run(- [- "powershell",- "-NoProfile",- "-Command",- f"$value = [Environment]::GetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(scope_name)}); "- "if ($null -eq $value) { '__HEADROOM_UNSET__' } else { $value }",- ],- capture_output=True,- text=True,- check=True,- ).stdout.strip()- command = [- "powershell",- "-NoProfile",- "-Command",- f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(value)},{_powershell_literal(scope_name)})",- ]- subprocess.run(command, check=True)- mutations.append(- ManagedMutation(- target="env",- kind="windows-env",- data={- "name": name,- "scope": scope_name,- "previous": None if previous == "__HEADROOM_UNSET__" else previous,- },- )- )- return mutations---def _remove_windows_env_scope(mutations: list[ManagedMutation]) -> None:- for mutation in mutations:- if mutation.kind != "windows-env":- continue- name = mutation.data.get("name")- if not isinstance(name, str):- raise ValueError("Windows environment mutation is missing a variable name")- scope_name = mutation.data.get("scope", "User")- if not isinstance(scope_name, str):- raise ValueError("Windows environment mutation is missing a valid scope")- previous = mutation.data.get("previous")- if previous is None:- value_literal = "$null"- else:- value_literal = _powershell_literal(previous)- command = [- "powershell",- "-NoProfile",- "-Command",- f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{value_literal},{_powershell_literal(scope_name)})",- ]- subprocess.run(command, check=True)---def apply_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:- """Apply provider/user/system configuration for a deployment."""-- mutations: list[ManagedMutation] = []- if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:- if os.name == "nt":- mutations.extend(_apply_windows_env_scope(manifest))- else:- mutations.extend(_apply_unix_env_scope(manifest))- mutations.extend(apply_provider_scope_mutations(manifest))- return mutations-- return [*mutations, *apply_provider_scope_mutations(manifest)]---def revert_mutations(manifest: DeploymentManifest) -> None:- """Undo the stored mutations for a deployment."""-- if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:- shell_mutations = [m for m in manifest.mutations if m.target == "env"]- if os.name == "nt":- _remove_windows_env_scope(shell_mutations)- else:- _remove_unix_env_scope(shell_mutations)-- for mutation in manifest.mutations:- revert_provider_scope_mutation(manifest, mutation)+"""Tool-target configuration for persistent deployments."""++from __future__ import annotations++import os+import re+import subprocess+from pathlib import Path++from headroom.providers.install_registry import (+ apply_provider_scope_mutations,+ revert_provider_scope_mutation,+)++from .models import ConfigScope, DeploymentManifest, ManagedMutation+from .paths import (+ unix_system_env_targets,+ unix_user_env_targets,+)++_ENV_MARKER_START = "# >>> headroom persistent env >>>"+_ENV_MARKER_END = "# <<< headroom persistent env <<<"+_ENV_PATTERN = re.compile(+ re.escape(_ENV_MARKER_START) + r".*?" + re.escape(_ENV_MARKER_END),+ re.DOTALL,+)+++def _merge_marker_block(file_path: Path, block: str, pattern: re.Pattern[str], marker: str) -> str:+ if file_path.exists():+ existing = file_path.read_text()+ if marker in existing:+ return pattern.sub(block, existing)+ return existing.rstrip() + "\n\n" + block + "\n"+ return block + "\n"+++def _env_block(values: dict[str, str]) -> str:+ lines = [_ENV_MARKER_START]+ for name, value in values.items():+ lines.append(f'export {name}="{value}"')+ lines.append(_ENV_MARKER_END)+ return "\n".join(lines)+++def _powershell_literal(value: str) -> str:+ return "'" + value.replace("'", "''") + "'"+++def _unix_scope_values(manifest: DeploymentManifest) -> dict[str, str]:+ merged = dict(manifest.base_env)+ for env_map in manifest.tool_envs.values():+ merged.update(env_map)+ return merged+++def _apply_unix_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:+ values = _unix_scope_values(manifest)+ block = _env_block(values)+ if manifest.scope == ConfigScope.USER.value:+ targets = unix_user_env_targets()+ else:+ targets = unix_system_env_targets()+ mutations: list[ManagedMutation] = []+ for path in targets:+ path.parent.mkdir(parents=True, exist_ok=True)+ merged = _merge_marker_block(path, block, _ENV_PATTERN, _ENV_MARKER_START)+ path.write_text(merged)+ mutations.append(ManagedMutation(target="env", kind="shell-block", path=str(path)))+ return mutations+++def _remove_unix_env_scope(mutations: list[ManagedMutation]) -> None:+ for mutation in mutations:+ if mutation.kind != "shell-block" or not mutation.path:+ continue+ path = Path(mutation.path)+ if not path.exists():+ continue+ content = path.read_text()+ if _ENV_MARKER_START not in content:+ continue+ path.write_text(_ENV_PATTERN.sub("", content).strip() + "\n")+++def _apply_windows_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:+ scope_name = "Machine" if manifest.scope == ConfigScope.SYSTEM.value else "User"+ merged = _unix_scope_values(manifest)+ mutations: list[ManagedMutation] = []+ for name, value in merged.items():+ previous = subprocess.run(+ [+ "powershell",+ "-NoProfile",+ "-Command",+ f"$value = [Environment]::GetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(scope_name)}); "+ "if ($null -eq $value) { '__HEADROOM_UNSET__' } else { $value }",+ ],+ capture_output=True,+ text=True,+ check=True,+ ).stdout.strip()+ command = [+ "powershell",+ "-NoProfile",+ "-Command",+ f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(value)},{_powershell_literal(scope_name)})",+ ]+ subprocess.run(command, check=True)+ mutations.append(+ ManagedMutation(+ target="env",+ kind="windows-env",+ data={+ "name": name,+ "scope": scope_name,+ "previous": None if previous == "__HEADROOM_UNSET__" else previous,+ },+ )+ )+ return mutations+++def _remove_windows_env_scope(mutations: list[ManagedMutation]) -> None:+ for mutation in mutations:+ if mutation.kind != "windows-env":+ continue+ name = mutation.data.get("name")+ if not isinstance(name, str):+ raise ValueError("Windows environment mutation is missing a variable name")+ scope_name = mutation.data.get("scope", "User")+ if not isinstance(scope_name, str):+ raise ValueError("Windows environment mutation is missing a valid scope")+ previous = mutation.data.get("previous")+ if previous is None:+ value_literal = "$null"+ else:+ value_literal = _powershell_literal(previous)+ command = [+ "powershell",+ "-NoProfile",+ "-Command",+ f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{value_literal},{_powershell_literal(scope_name)})",+ ]+ subprocess.run(command, check=True)+++def apply_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:+ """Apply provider/user/system configuration for a deployment."""++ mutations: list[ManagedMutation] = []+ if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:+ if os.name == "nt":+ mutations.extend(_apply_windows_env_scope(manifest))+ else:+ mutations.extend(_apply_unix_env_scope(manifest))+ mutations.extend(apply_provider_scope_mutations(manifest))+ return mutations++ return [*mutations, *apply_provider_scope_mutations(manifest)]+++def revert_mutations(manifest: DeploymentManifest) -> None:+ """Undo the stored mutations for a deployment."""++ if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:+ shell_mutations = [m for m in manifest.mutations if m.target == "env"]+ if os.name == "nt":+ _remove_windows_env_scope(shell_mutations)+ else:+ _remove_unix_env_scope(shell_mutations)++ for mutation in manifest.mutations:+ revert_provider_scope_mutation(manifest, mutation)diff --git a/headroom/install/runtime.py b/headroom/install/runtime.pyindex de7cb8fcd..d285197c6 100644--- a/headroom/install/runtime.py+++ b/headroom/install/runtime.py@@ -1,279 +1,279 @@-"""Runtime helpers for persistent deployments."""--from __future__ import annotations--import os-import shutil-import signal-import subprocess-import sys-import time-from pathlib import Path-from typing import Any--from .health import probe_ready-from .models import DeploymentManifest, InstallPreset, RuntimeKind-from .paths import log_path, pid_path--PASSTHROUGH_ENV_PREFIXES = (- "HEADROOM_",- "ANTHROPIC_",- "OPENAI_",- "GEMINI_",- "AWS_",- "AZURE_",- "VERTEX_",- "GOOGLE_",- "GOOGLE_CLOUD_",- "MISTRAL_",- "GROQ_",- "OPENROUTER_",- "XAI_",- "TOGETHER_",- "COHERE_",- "OLLAMA_",- "LITELLM_",- "OTEL_",- "SUPABASE_",- "QDRANT_",- "NEO4J_",- "LANGSMITH_",-)---def _is_windows() -> bool:- return sys.platform.startswith("win")---def _deployment_env(manifest: DeploymentManifest) -> dict[str, str]:- return {- "HEADROOM_DEPLOYMENT_PROFILE": manifest.profile,- "HEADROOM_DEPLOYMENT_PRESET": manifest.preset,- "HEADROOM_DEPLOYMENT_RUNTIME": manifest.runtime_kind,- "HEADROOM_DEPLOYMENT_SUPERVISOR": manifest.supervisor_kind,- "HEADROOM_DEPLOYMENT_SCOPE": manifest.scope,- }---def resolve_headroom_command() -> list[str]:- """Resolve the most reliable command to invoke headroom."""-- headroom_bin = shutil.which("headroom")- if headroom_bin:- return [headroom_bin]- return [sys.executable, "-m", "headroom.cli"]---def _runtime_env(manifest: DeploymentManifest) -> dict[str, str]:- env = os.environ.copy()- env.update(manifest.base_env)- env.update(_deployment_env(manifest))- return env---def _ensure_host_dirs() -> None:- for subdir in (".headroom", ".claude", ".codex", ".gemini"):- (Path.home() / subdir).mkdir(parents=True, exist_ok=True)---def _mount_source(home: str, subdir: str) -> str:- if _is_windows():- return f"{home}\\{subdir}"- return f"{home}/{subdir}"---def build_runtime_command(manifest: DeploymentManifest) -> list[str]:- """Build the raw foreground command that runs the proxy."""-- if manifest.runtime_kind == RuntimeKind.PYTHON.value:- return [sys.executable, "-m", "headroom.cli", "proxy", *manifest.proxy_args]-- _ensure_host_dirs()- home = str(Path.home())- container_home = "/tmp/headroom-home"- command = [- "docker",- "run",- "--rm",- "--name",- manifest.container_name,- "-p",- f"127.0.0.1:{manifest.port}:{manifest.port}",- "--workdir",- container_home,- "--env",- f"HOME={container_home}",- "--env",- "PYTHONUNBUFFERED=1",- # Canonical Headroom filesystem contract (issue #175).- "--env",- f"HEADROOM_WORKSPACE_DIR={container_home}/.headroom",- "--env",- f"HEADROOM_CONFIG_DIR={container_home}/.headroom/config",- "--volume",- f"{_mount_source(home, '.headroom')}:{container_home}/.headroom",- "--volume",- f"{_mount_source(home, '.claude')}:{container_home}/.claude",- "--volume",- f"{_mount_source(home, '.codex')}:{container_home}/.codex",- "--volume",- f"{_mount_source(home, '.gemini')}:{container_home}/.gemini",- ]- if not _is_windows():- getuid = getattr(os, "getuid", None)- getgid = getattr(os, "getgid", None)- if callable(getuid) and callable(getgid):- command.extend(["--user", f"{getuid()}:{getgid()}"])- runtime_env = {**manifest.base_env, **_deployment_env(manifest)}- for name, value in runtime_env.items():- command.extend(["--env", f"{name}={value}"])- for name in sorted(os.environ):- if name.startswith(PASSTHROUGH_ENV_PREFIXES):- command.extend(["--env", name])- command.extend(- [- manifest.image,- "headroom",- "proxy",- "--host",- "0.0.0.0",- *manifest.proxy_args[2:],- ]- )- return command---def _write_pid(profile: str, pid: int) -> None:- path = pid_path(profile)- path.parent.mkdir(parents=True, exist_ok=True)- path.write_text(str(pid))---def _read_pid(profile: str) -> int | None:- path = pid_path(profile)- if not path.exists():- return None- try:- return int(path.read_text().strip())- except ValueError:- return None---def _clear_pid(profile: str) -> None:- path = pid_path(profile)- if path.exists():- path.unlink()---def run_foreground(manifest: DeploymentManifest) -> int:- """Run the raw runtime command in the foreground."""-- command = build_runtime_command(manifest)- env = _runtime_env(manifest)- log_file_path = log_path(manifest.profile)- log_file_path.parent.mkdir(parents=True, exist_ok=True)-- with open(log_file_path, "a", encoding="utf-8", errors="replace") as log_file:- proc = subprocess.Popen(command, env=env, stdout=log_file, stderr=log_file)- _write_pid(manifest.profile, proc.pid)-- def _cleanup(signum: int | None = None, frame: Any = None) -> None:- if proc.poll() is None:- proc.terminate()- try:- proc.wait(timeout=10)- except subprocess.TimeoutExpired:- proc.kill()-- signal.signal(signal.SIGINT, _cleanup)- signal.signal(signal.SIGTERM, _cleanup)- try:- return proc.wait()- finally:- _clear_pid(manifest.profile)---def start_detached_agent(profile: str) -> subprocess.Popen[str]:- """Start `headroom install agent run` detached for the given profile."""-- command = [*resolve_headroom_command(), "install", "agent", "run", "--profile", profile]- log_file_path = log_path(profile)- log_file_path.parent.mkdir(parents=True, exist_ok=True)- log_file = open(log_file_path, "a", encoding="utf-8", errors="replace") # noqa: SIM115-- kwargs: dict[str, Any] = {"stdout": log_file, "stderr": log_file}- if _is_windows():- kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(- subprocess, "CREATE_NEW_PROCESS_GROUP", 0- )- else:- kwargs["start_new_session"] = True- return subprocess.Popen(command, **kwargs)---def start_persistent_docker(manifest: DeploymentManifest) -> None:- """Start a persistent Docker container with restart policy."""-- command = build_runtime_command(manifest)- docker_cmd = [- "docker",- "run",- "-d",- "--restart",- "unless-stopped",- "--name",- manifest.container_name,- *command[5:], # drop initial `docker run --rm --name ...`- ]- subprocess.run(["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True)- subprocess.run(docker_cmd, check=True)---def stop_runtime(manifest: DeploymentManifest) -> None:- """Stop the raw runtime for the deployment."""-- if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:- subprocess.run(["docker", "stop", manifest.container_name], capture_output=True, text=True)- subprocess.run(- ["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True- )- return-- pid = _read_pid(manifest.profile)- if pid is None:- return- try:- os.kill(pid, signal.SIGTERM)- except OSError:- pass- _clear_pid(manifest.profile)---def wait_ready(manifest: DeploymentManifest, timeout_seconds: int = 30) -> bool:- """Wait for the deployment to report ready."""-- for _ in range(timeout_seconds):- if probe_ready(manifest.health_url):- return True- time.sleep(1)- return False---def runtime_status(manifest: DeploymentManifest) -> str:- """Return a short status string for the deployment runtime."""-- if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:- result = subprocess.run(- ["docker", "ps", "--format", "{{.Names}}"], capture_output=True, text=True- )- if manifest.container_name in result.stdout.splitlines():- return "running"- return "stopped"- pid = _read_pid(manifest.profile)- if pid is None:- return "stopped"- try:- os.kill(pid, 0)- except OSError:- return "stopped"- return "running"+"""Runtime helpers for persistent deployments."""++from __future__ import annotations++import os+import shutil+import signal+import subprocess+import sys+import time+from pathlib import Path+from typing import Any++from .health import probe_ready+from .models import DeploymentManifest, InstallPreset, RuntimeKind+from .paths import log_path, pid_path++PASSTHROUGH_ENV_PREFIXES = (+ "HEADROOM_",+ "ANTHROPIC_",+ "OPENAI_",+ "GEMINI_",+ "AWS_",+ "AZURE_",+ "VERTEX_",+ "GOOGLE_",+ "GOOGLE_CLOUD_",+ "MISTRAL_",+ "GROQ_",+ "OPENROUTER_",+ "XAI_",+ "TOGETHER_",+ "COHERE_",+ "OLLAMA_",+ "LITELLM_",+ "OTEL_",+ "SUPABASE_",+ "QDRANT_",+ "NEO4J_",+ "LANGSMITH_",+)+++def _is_windows() -> bool:+ return sys.platform.startswith("win")+++def _deployment_env(manifest: DeploymentManifest) -> dict[str, str]:+ return {+ "HEADROOM_DEPLOYMENT_PROFILE": manifest.profile,+ "HEADROOM_DEPLOYMENT_PRESET": manifest.preset,+ "HEADROOM_DEPLOYMENT_RUNTIME": manifest.runtime_kind,+ "HEADROOM_DEPLOYMENT_SUPERVISOR": manifest.supervisor_kind,+ "HEADROOM_DEPLOYMENT_SCOPE": manifest.scope,+ }+++def resolve_headroom_command() -> list[str]:+ """Resolve the most reliable command to invoke headroom."""++ headroom_bin = shutil.which("headroom")+ if headroom_bin:+ return [headroom_bin]+ return [sys.executable, "-m", "headroom.cli"]+++def _runtime_env(manifest: DeploymentManifest) -> dict[str, str]:+ env = os.environ.copy()+ env.update(manifest.base_env)+ env.update(_deployment_env(manifest))+ return env+++def _ensure_host_dirs() -> None:+ for subdir in (".headroom", ".claude", ".codex", ".gemini"):+ (Path.home() / subdir).mkdir(parents=True, exist_ok=True)+++def _mount_source(home: str, subdir: str) -> str:+ if _is_windows():+ return f"{home}\\{subdir}"+ return f"{home}/{subdir}"+++def build_runtime_command(manifest: DeploymentManifest) -> list[str]:+ """Build the raw foreground command that runs the proxy."""++ if manifest.runtime_kind == RuntimeKind.PYTHON.value:+ return [sys.executable, "-m", "headroom.cli", "proxy", *manifest.proxy_args]++ _ensure_host_dirs()+ home = str(Path.home())+ container_home = "/tmp/headroom-home"+ command = [+ "docker",+ "run",+ "--rm",+ "--name",+ manifest.container_name,+ "-p",+ f"127.0.0.1:{manifest.port}:{manifest.port}",+ "--workdir",+ container_home,+ "--env",+ f"HOME={container_home}",+ "--env",+ "PYTHONUNBUFFERED=1",+ # Canonical Headroom filesystem contract (issue #175).+ "--env",+ f"HEADROOM_WORKSPACE_DIR={container_home}/.headroom",+ "--env",+ f"HEADROOM_CONFIG_DIR={container_home}/.headroom/config",+ "--volume",+ f"{_mount_source(home, '.headroom')}:{container_home}/.headroom",+ "--volume",+ f"{_mount_source(home, '.claude')}:{container_home}/.claude",+ "--volume",+ f"{_mount_source(home, '.codex')}:{container_home}/.codex",+ "--volume",+ f"{_mount_source(home, '.gemini')}:{container_home}/.gemini",+ ]+ if not _is_windows():+ getuid = getattr(os, "getuid", None)+ getgid = getattr(os, "getgid", None)+ if callable(getuid) and callable(getgid):+ command.extend(["--user", f"{getuid()}:{getgid()}"])+ runtime_env = {**manifest.base_env, **_deployment_env(manifest)}+ for name, value in runtime_env.items():+ command.extend(["--env", f"{name}={value}"])+ for name in sorted(os.environ):+ if name.startswith(PASSTHROUGH_ENV_PREFIXES):+ command.extend(["--env", name])+ command.extend(+ [+ manifest.image,+ "headroom",+ "proxy",+ "--host",+ "0.0.0.0",+ *manifest.proxy_args[2:],+ ]+ )+ return command+++def _write_pid(profile: str, pid: int) -> None:+ path = pid_path(profile)+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(str(pid))+++def _read_pid(profile: str) -> int | None:+ path = pid_path(profile)+ if not path.exists():+ return None+ try:+ return int(path.read_text().strip())+ except ValueError:+ return None+++def _clear_pid(profile: str) -> None:+ path = pid_path(profile)+ if path.exists():+ path.unlink()+++def run_foreground(manifest: DeploymentManifest) -> int:+ """Run the raw runtime command in the foreground."""++ command = build_runtime_command(manifest)+ env = _runtime_env(manifest)+ log_file_path = log_path(manifest.profile)+ log_file_path.parent.mkdir(parents=True, exist_ok=True)++ with open(log_file_path, "a", encoding="utf-8", errors="replace") as log_file:+ proc = subprocess.Popen(command, env=env, stdout=log_file, stderr=log_file)+ _write_pid(manifest.profile, proc.pid)++ def _cleanup(signum: int | None = None, frame: Any = None) -> None:+ if proc.poll() is None:+ proc.terminate()+ try:+ proc.wait(timeout=10)+ except subprocess.TimeoutExpired:+ proc.kill()++ signal.signal(signal.SIGINT, _cleanup)+ signal.signal(signal.SIGTERM, _cleanup)+ try:+ return proc.wait()+ finally:+ _clear_pid(manifest.profile)+++def start_detached_agent(profile: str) -> subprocess.Popen[str]:+ """Start `headroom install agent run` detached for the given profile."""++ command = [*resolve_headroom_command(), "install", "agent", "run", "--profile", profile]+ log_file_path = log_path(profile)+ log_file_path.parent.mkdir(parents=True, exist_ok=True)+ log_file = open(log_file_path, "a", encoding="utf-8", errors="replace") # noqa: SIM115++ kwargs: dict[str, Any] = {"stdout": log_file, "stderr": log_file}+ if _is_windows():+ kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(+ subprocess, "CREATE_NEW_PROCESS_GROUP", 0+ )+ else:+ kwargs["start_new_session"] = True+ return subprocess.Popen(command, **kwargs)+++def start_persistent_docker(manifest: DeploymentManifest) -> None:+ """Start a persistent Docker container with restart policy."""++ command = build_runtime_command(manifest)+ docker_cmd = [+ "docker",+ "run",+ "-d",+ "--restart",+ "unless-stopped",+ "--name",+ manifest.container_name,+ *command[5:], # drop initial `docker run --rm --name ...`+ ]+ subprocess.run(["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True)+ subprocess.run(docker_cmd, check=True)+++def stop_runtime(manifest: DeploymentManifest) -> None:+ """Stop the raw runtime for the deployment."""++ if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:+ subprocess.run(["docker", "stop", manifest.container_name], capture_output=True, text=True)+ subprocess.run(+ ["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True+ )+ return++ pid = _read_pid(manifest.profile)+ if pid is None:+ return+ try:+ os.kill(pid, signal.SIGTERM)+ except OSError:+ pass+ _clear_pid(manifest.profile)+++def wait_ready(manifest: DeploymentManifest, timeout_seconds: int = 30) -> bool:+ """Wait for the deployment to report ready."""++ for _ in range(timeout_seconds):+ if probe_ready(manifest.health_url):+ return True+ time.sleep(1)+ return False+++def runtime_status(manifest: DeploymentManifest) -> str:+ """Return a short status string for the deployment runtime."""++ if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:+ result = subprocess.run(+ ["docker", "ps", "--format", "{{.Names}}"], capture_output=True, text=True+ )+ if manifest.container_name in result.stdout.splitlines():+ return "running"+ return "stopped"+ pid = _read_pid(manifest.profile)+ if pid is None:+ return "stopped"+ try:+ os.kill(pid, 0)+ except OSError:+ return "stopped"+ return "running"diff --git a/headroom/providers/aider/install.py b/headroom/providers/aider/install.pyindex ceb326129..5e177d1c1 100644--- a/headroom/providers/aider/install.py+++ b/headroom/providers/aider/install.py@@ -1,12 +1,12 @@-"""Aider install-time helpers."""--from __future__ import annotations--from .runtime import build_launch_env---def build_install_env(*, port: int, backend: str) -> dict[str, str]:- """Build the persistent install environment for Aider."""- del backend- env, _lines = build_launch_env(port=port, environ={})- return {key: env[key] for key in ("OPENAI_API_BASE", "ANTHROPIC_BASE_URL")}+"""Aider install-time helpers."""++from __future__ import annotations++from .runtime import build_launch_env+++def build_install_env(*, port: int, backend: str) -> dict[str, str]:+ """Build the persistent install environment for Aider."""+ del backend+ env, _lines = build_launch_env(port=port, environ={})+ return {key: env[key] for key in ("OPENAI_API_BASE", "ANTHROPIC_BASE_URL")}diff --git a/headroom/providers/claude/install.py b/headroom/providers/claude/install.pyindex db5d03059..97f166018 100644--- a/headroom/providers/claude/install.py+++ b/headroom/providers/claude/install.py@@ -1,63 +1,63 @@-"""Claude install-time helpers."""--from __future__ import annotations--import json-from pathlib import Path--from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget-from headroom.install.paths import claude_settings_path--from .runtime import proxy_base_url---def build_install_env(*, port: int, backend: str) -> dict[str, str]:- """Build the persistent install environment for Claude."""- del backend- return {"ANTHROPIC_BASE_URL": proxy_base_url(port)}---def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:- """Apply Claude provider-scope configuration when requested."""- if manifest.scope != ConfigScope.PROVIDER.value:- return None-- path = claude_settings_path()- path.parent.mkdir(parents=True, exist_ok=True)- payload: dict[str, object] = {}- if path.exists():- payload = json.loads(path.read_text())- env = payload.get("env")- env_map = dict(env) if isinstance(env, dict) else {}- values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})- previous = {name: env_map.get(name) for name in values}- env_map.update(values)- payload["env"] = env_map- path.write_text(json.dumps(payload, indent=2) + "\n")- return ManagedMutation(- target=ToolTarget.CLAUDE.value,- kind="json-env",- path=str(path),- data={"previous": previous},- )---def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:- """Revert Claude provider-scope configuration."""- if not mutation.path:- return- path = Path(mutation.path)- if not path.exists():- return- payload = json.loads(path.read_text())- env = payload.get("env")- env_map = dict(env) if isinstance(env, dict) else {}- previous: dict[str, object] = mutation.data.get("previous", {})- values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})- for name in values:- if previous.get(name) is None:- env_map.pop(name, None)- else:- env_map[name] = previous[name]- payload["env"] = env_map- path.write_text(json.dumps(payload, indent=2) + "\n")+"""Claude install-time helpers."""++from __future__ import annotations++import json+from pathlib import Path++from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget+from headroom.install.paths import claude_settings_path++from .runtime import proxy_base_url+++def build_install_env(*, port: int, backend: str) -> dict[str, str]:+ """Build the persistent install environment for Claude."""+ del backend+ return {"ANTHROPIC_BASE_URL": proxy_base_url(port)}+++def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:+ """Apply Claude provider-scope configuration when requested."""+ if manifest.scope != ConfigScope.PROVIDER.value:+ return None++ path = claude_settings_path()+ path.parent.mkdir(parents=True, exist_ok=True)+ payload: dict[str, object] = {}+ if path.exists():+ payload = json.loads(path.read_text())+ env = payload.get("env")+ env_map = dict(env) if isinstance(env, dict) else {}+ values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})+ previous = {name: env_map.get(name) for name in values}+ env_map.update(values)+ payload["env"] = env_map+ path.write_text(json.dumps(payload, indent=2) + "\n")+ return ManagedMutation(+ target=ToolTarget.CLAUDE.value,+ kind="json-env",+ path=str(path),+ data={"previous": previous},+ )+++def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:+ """Revert Claude provider-scope configuration."""+ if not mutation.path:+ return+ path = Path(mutation.path)+ if not path.exists():+ return+ payload = json.loads(path.read_text())+ env = payload.get("env")+ env_map = dict(env) if isinstance(env, dict) else {}+ previous: dict[str, object] = mutation.data.get("previous", {})+ values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})+ for name in values:+ if previous.get(name) is None:+ env_map.pop(name, None)+ else:+ env_map[name] = previous[name]+ payload["env"] = env_map+ path.write_text(json.dumps(payload, indent=2) + "\n")diff --git a/headroom/providers/codex/install.py b/headroom/providers/codex/install.pyindex 0bdbbbc20..b8f718602 100644--- a/headroom/providers/codex/install.py+++ b/headroom/providers/codex/install.py@@ -1,68 +1,68 @@-"""Codex install-time helpers."""--from __future__ import annotations--import re-from pathlib import Path--from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget-from headroom.install.paths import codex_config_path--from .runtime import proxy_base_url--_CODEX_MARKER_START = "# --- Headroom persistent provider ---"-_CODEX_MARKER_END = "# --- end Headroom persistent provider ---"-_CODEX_PATTERN = re.compile(- re.escape(_CODEX_MARKER_START) + r".*?" + re.escape(_CODEX_MARKER_END),- re.DOTALL,-)---def build_install_env(*, port: int, backend: str) -> dict[str, str]:- """Build the persistent install environment for Codex."""- del backend- return {"OPENAI_BASE_URL": proxy_base_url(port)}---def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:- """Apply Codex provider-scope configuration when requested."""- if manifest.scope != ConfigScope.PROVIDER.value:- return None-- path = codex_config_path()- path.parent.mkdir(parents=True, exist_ok=True)- section = (- f"{_CODEX_MARKER_START}\n"- 'model_provider = "headroom"\n\n'- "[model_providers.headroom]\n"- 'name = "Headroom persistent proxy"\n'- f'base_url = "{proxy_base_url(manifest.port)}"\n'- 'env_key = "OPENAI_API_KEY"\n'- "requires_openai_auth = true\n"- "supports_websockets = true\n"- f"{_CODEX_MARKER_END}\n"- )- if path.exists():- existing = path.read_text()- if _CODEX_MARKER_START in existing:- merged = _CODEX_PATTERN.sub(section, existing)- else:- merged = existing.rstrip() + "\n\n" + section + "\n"- else:- merged = section + "\n"- path.write_text(merged)- return ManagedMutation(target=ToolTarget.CODEX.value, kind="toml-block", path=str(path))---def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:- """Revert Codex provider-scope configuration."""- del manifest- if not mutation.path:- return- path = Path(mutation.path)- if not path.exists():- return- content = path.read_text()- if _CODEX_MARKER_START not in content:- return- path.write_text(_CODEX_PATTERN.sub("", content).strip() + "\n")+"""Codex install-time helpers."""++from __future__ import annotations++import re+from pathlib import Path++from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget+from headroom.install.paths import codex_config_path++from .runtime import proxy_base_url++_CODEX_MARKER_START = "# --- Headroom persistent provider ---"+_CODEX_MARKER_END = "# --- end Headroom persistent provider ---"+_CODEX_PATTERN = re.compile(+ re.escape(_CODEX_MARKER_START) + r".*?" + re.escape(_CODEX_MARKER_END),+ re.DOTALL,+)+++def build_install_env(*, port: int, backend: str) -> dict[str, str]:+ """Build the persistent install environment for Codex."""+ del backend+ return {"OPENAI_BASE_URL": proxy_base_url(port)}+++def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:+ """Apply Codex provider-scope configuration when requested."""+ if manifest.scope != ConfigScope.PROVIDER.value:+ return None++ path = codex_config_path()+ path.parent.mkdir(parents=True, exist_ok=True)+ section = (+ f"{_CODEX_MARKER_START}\n"+ 'model_provider = "headroom"\n\n'+ "[model_providers.headroom]\n"+ 'name = "Headroom persistent proxy"\n'+ f'base_url = "{proxy_base_url(manifest.port)}"\n'+ 'env_key = "OPENAI_API_KEY"\n'+ "requires_openai_auth = true\n"+ "supports_websockets = true\n"+ f"{_CODEX_MARKER_END}\n"+ )+ if path.exists():+ existing = path.read_text()+ if _CODEX_MARKER_START in existing:+ merged = _CODEX_PATTERN.sub(section, existing)+ else:+ merged = existing.rstrip() + "\n\n" + section + "\n"+ else:+ merged = section + "\n"+ path.write_text(merged)+ return ManagedMutation(target=ToolTarget.CODEX.value, kind="toml-block", path=str(path))+++def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:+ """Revert Codex provider-scope configuration."""+ del manifest+ if not mutation.path:+ return+ path = Path(mutation.path)+ if not path.exists():+ return+ content = path.read_text()+ if _CODEX_MARKER_START not in content:+ return+ path.write_text(_CODEX_PATTERN.sub("", content).strip() + "\n")diff --git a/headroom/providers/copilot/install.py b/headroom/providers/copilot/install.pyindex 5b0df8e32..24c7ec941 100644--- a/headroom/providers/copilot/install.py+++ b/headroom/providers/copilot/install.py@@ -1,25 +1,25 @@-"""Copilot install-time helpers."""--from __future__ import annotations--from .wrap import build_launch_env, resolve_provider_type---def build_install_env(*, port: int, backend: str) -> dict[str, str]:- """Build the persistent install environment for Copilot."""- provider_type = resolve_provider_type(backend, "auto", {"HEADROOM_BACKEND": backend})- env, _lines = build_launch_env(- port=port,- provider_type=provider_type,- wire_api=None,- environ={},- )- return {- key: env[key]- for key in (- "COPILOT_PROVIDER_TYPE",- "COPILOT_PROVIDER_BASE_URL",- "COPILOT_PROVIDER_WIRE_API",- )- if key in env- }+"""Copilot install-time helpers."""++from __future__ import annotations++from .wrap import build_launch_env, resolve_provider_type+++def build_install_env(*, port: int, backend: str) -> dict[str, str]:+ """Build the persistent install environment for Copilot."""+ provider_type = resolve_provider_type(backend, "auto", {"HEADROOM_BACKEND": backend})+ env, _lines = build_launch_env(+ port=port,+ provider_type=provider_type,+ wire_api=None,+ environ={},+ )+ return {+ key: env[key]+ for key in (+ "COPILOT_PROVIDER_TYPE",+ "COPILOT_PROVIDER_BASE_URL",+ "COPILOT_PROVIDER_WIRE_API",+ )+ if key in env+ }diff --git a/headroom/providers/cursor/install.py b/headroom/providers/cursor/install.pyindex 6724f496f..181fcbdf0 100644--- a/headroom/providers/cursor/install.py+++ b/headroom/providers/cursor/install.py@@ -1,15 +1,15 @@-"""Cursor install-time helpers."""--from __future__ import annotations--from .runtime import build_proxy_targets---def build_install_env(*, port: int, backend: str) -> dict[str, str]:- """Build the persistent install environment for Cursor."""- del backend- targets = build_proxy_targets(port)- return {- "OPENAI_BASE_URL": targets.openai_base_url,- "ANTHROPIC_BASE_URL": targets.anthropic_base_url,- }+"""Cursor install-time helpers."""++from __future__ import annotations++from .runtime import build_proxy_targets+++def build_install_env(*, port: int, backend: str) -> dict[str, str]:+ """Build the persistent install environment for Cursor."""+ del backend+ targets = build_proxy_targets(port)+ return {+ "OPENAI_BASE_URL": targets.openai_base_url,+ "ANTHROPIC_BASE_URL": targets.anthropic_base_url,+ }diff --git a/headroom/providers/install_registry.py b/headroom/providers/install_registry.pyindex 416046655..99526435e 100644--- a/headroom/providers/install_registry.py+++ b/headroom/providers/install_registry.py@@ -1,86 +1,86 @@-"""Install-time provider registry helpers."""--from __future__ import annotations--from collections.abc import Callable--from headroom.install.models import DeploymentManifest, ManagedMutation-from headroom.providers.aider.install import build_install_env as _build_aider_install_env-from headroom.providers.claude.install import (- apply_provider_scope as _apply_claude_provider_scope,-)-from headroom.providers.claude.install import (- build_install_env as _build_claude_install_env,-)-from headroom.providers.claude.install import (- revert_provider_scope as _revert_claude_provider_scope,-)-from headroom.providers.codex.install import (- apply_provider_scope as _apply_codex_provider_scope,-)-from headroom.providers.codex.install import build_install_env as _build_codex_install_env-from headroom.providers.codex.install import (- revert_provider_scope as _revert_codex_provider_scope,-)-from headroom.providers.copilot.install import (- build_install_env as _build_copilot_install_env,-)-from headroom.providers.cursor.install import build_install_env as _build_cursor_install_env-from headroom.providers.openclaw.install import (- apply_provider_scope as _apply_openclaw_provider_scope,-)-from headroom.providers.openclaw.install import (- revert_provider_scope as _revert_openclaw_provider_scope,-)--_InstallEnvBuilder = Callable[..., dict[str, str]]-_ProviderScopeApplier = Callable[[DeploymentManifest], ManagedMutation | None]-_ProviderScopeReverter = Callable[[ManagedMutation, DeploymentManifest], None]--_ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {- "claude": _build_claude_install_env,- "copilot": _build_copilot_install_env,- "codex": _build_codex_install_env,- "aider": _build_aider_install_env,- "cursor": _build_cursor_install_env,-}--_PROVIDER_SCOPE_HANDLERS: dict[str, tuple[_ProviderScopeApplier, _ProviderScopeReverter]] = {- "claude": (_apply_claude_provider_scope, _revert_claude_provider_scope),- "codex": (_apply_codex_provider_scope, _revert_codex_provider_scope),- "openclaw": (_apply_openclaw_provider_scope, _revert_openclaw_provider_scope),-}---def build_install_target_envs(- port: int, backend: str, targets: list[str]-) -> dict[str, dict[str, str]]:- """Build per-target install environment values via provider slices."""- target_envs: dict[str, dict[str, str]] = {}- for target in targets:- builder = _ENV_BUILDERS.get(target)- if builder is None:- continue- target_envs[target] = builder(port=port, backend=backend)- return target_envs---def apply_provider_scope_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:- """Apply provider-scope mutations owned by provider slices."""- mutations: list[ManagedMutation] = []- for target in manifest.targets:- handlers = _PROVIDER_SCOPE_HANDLERS.get(target)- if handlers is None:- continue- mutation = handlers[0](manifest)- if mutation is not None:- mutations.append(mutation)- return mutations---def revert_provider_scope_mutation(manifest: DeploymentManifest, mutation: ManagedMutation) -> None:- """Revert a provider-scope mutation via the owning provider slice."""- handlers = _PROVIDER_SCOPE_HANDLERS.get(mutation.target)- if handlers is None:- return- handlers[1](mutation, manifest)+"""Install-time provider registry helpers."""++from __future__ import annotations++from collections.abc import Callable++from headroom.install.models import DeploymentManifest, ManagedMutation+from headroom.providers.aider.install import build_install_env as _build_aider_install_env+from headroom.providers.claude.install import (+ apply_provider_scope as _apply_claude_provider_scope,+)+from headroom.providers.claude.install import (+ build_install_env as _build_claude_install_env,+)+from headroom.providers.claude.install import (+ revert_provider_scope as _revert_claude_provider_scope,+)+from headroom.providers.codex.install import (+ apply_provider_scope as _apply_codex_provider_scope,+)+from headroom.providers.codex.install import build_install_env as _build_codex_install_env+from headroom.providers.codex.install import (+ revert_provider_scope as _revert_codex_provider_scope,+)+from headroom.providers.copilot.install import (+ build_install_env as _build_copilot_install_env,+)+from headroom.providers.cursor.install import build_install_env as _build_cursor_install_env+from headroom.providers.openclaw.install import (+ apply_provider_scope as _apply_openclaw_provider_scope,+)+from headroom.providers.openclaw.install import (+ revert_provider_scope as _revert_openclaw_provider_scope,+)++_InstallEnvBuilder = Callable[..., dict[str, str]]+_ProviderScopeApplier = Callable[[DeploymentManifest], ManagedMutation | None]+_ProviderScopeReverter = Callable[[ManagedMutation, DeploymentManifest], None]++_ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {+ "claude": _build_claude_install_env,+ "copilot": _build_copilot_install_env,+ "codex": _build_codex_install_env,+ "aider": _build_aider_install_env,+ "cursor": _build_cursor_install_env,+}++_PROVIDER_SCOPE_HANDLERS: dict[str, tuple[_ProviderScopeApplier, _ProviderScopeReverter]] = {+ "claude": (_apply_claude_provider_scope, _revert_claude_provider_scope),+ "codex": (_apply_codex_provider_scope, _revert_codex_provider_scope),+ "openclaw": (_apply_openclaw_provider_scope, _revert_openclaw_provider_scope),+}+++def build_install_target_envs(+ port: int, backend: str, targets: list[str]+) -> dict[str, dict[str, str]]:+ """Build per-target install environment values via provider slices."""+ target_envs: dict[str, dict[str, str]] = {}+ for target in targets:+ builder = _ENV_BUILDERS.get(target)+ if builder is None:+ continue+ target_envs[target] = builder(port=port, backend=backend)+ return target_envs+++def apply_provider_scope_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:+ """Apply provider-scope mutations owned by provider slices."""+ mutations: list[ManagedMutation] = []+ for target in manifest.targets:+ handlers = _PROVIDER_SCOPE_HANDLERS.get(target)+ if handlers is None:+ continue+ mutation = handlers[0](manifest)+ if mutation is not None:+ mutations.append(mutation)+ return mutations+++def revert_provider_scope_mutation(manifest: DeploymentManifest, mutation: ManagedMutation) -> None:+ """Revert a provider-scope mutation via the owning provider slice."""+ handlers = _PROVIDER_SCOPE_HANDLERS.get(mutation.target)+ if handlers is None:+ return+ handlers[1](mutation, manifest)diff --git a/headroom/providers/openclaw/install.py b/headroom/providers/openclaw/install.pyindex e7e2b6f59..97a3b1494 100644--- a/headroom/providers/openclaw/install.py+++ b/headroom/providers/openclaw/install.py@@ -1,50 +1,50 @@-"""OpenClaw install-time helpers."""--from __future__ import annotations--import click--from headroom.install.models import DeploymentManifest, ManagedMutation, ToolTarget-from headroom.install.paths import openclaw_config_path-from headroom.install.runtime import resolve_headroom_command---def shutil_which(name: str) -> str | None:- from shutil import which-- return which(name)---def _invoke_openclaw(command: list[str]) -> None:- import subprocess-- subprocess.run(command, check=True)---def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation:- """Configure OpenClaw to route through the persistent proxy."""- if not shutil_which("openclaw"):- raise click.ClickException("openclaw not found in PATH; cannot apply provider scope.")- command = [- *resolve_headroom_command(),- "wrap",- "openclaw",- "--no-auto-start",- "--proxy-port",- str(manifest.port),- ]- _invoke_openclaw(command)- return ManagedMutation(- target=ToolTarget.OPENCLAW.value,- kind="openclaw-wrap",- path=str(openclaw_config_path()),- )---def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:- """Undo OpenClaw persistent proxy configuration."""- del mutation, manifest- if not shutil_which("openclaw"):- return- command = [*resolve_headroom_command(), "unwrap", "openclaw"]- _invoke_openclaw(command)+"""OpenClaw install-time helpers."""++from __future__ import annotations++import click++from headroom.install.models import DeploymentManifest, ManagedMutation, ToolTarget+from headroom.install.paths import openclaw_config_path+from headroom.install.runtime import resolve_headroom_command+++def shutil_which(name: str) -> str | None:+ from shutil import which++ return which(name)+++def _invoke_openclaw(command: list[str]) -> None:+ import subprocess++ subprocess.run(command, check=True)+++def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation:+ """Configure OpenClaw to route through the persistent proxy."""+ if not shutil_which("openclaw"):+ raise click.ClickException("openclaw not found in PATH; cannot apply provider scope.")+ command = [+ *resolve_headroom_command(),+ "wrap",+ "openclaw",+ "--no-auto-start",+ "--proxy-port",+ str(manifest.port),+ ]+ _invoke_openclaw(command)+ return ManagedMutation(+ target=ToolTarget.OPENCLAW.value,+ kind="openclaw-wrap",+ path=str(openclaw_config_path()),+ )+++def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:+ """Undo OpenClaw persistent proxy configuration."""+ del mutation, manifest+ if not shutil_which("openclaw"):+ return+ command = [*resolve_headroom_command(), "unwrap", "openclaw"]+ _invoke_openclaw(command)diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 73207bfc6..877258a89 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -1,2746 +1,2746 @@-"""OpenAI handler mixin for HeadroomProxy.--Contains all OpenAI Chat Completions, Responses API, and passthrough handlers.-"""--from __future__ import annotations--import asyncio-import base64-import contextlib-import copy-import json-import logging-import os-import time-import uuid-from datetime import datetime-from typing import TYPE_CHECKING, Any--from headroom.proxy.helpers import jitter_delay_ms-from headroom.proxy.stage_timer import StageTimer, emit_stage_timings_log-from headroom.proxy.ws_session_registry import (- TerminationCause,- WebSocketSessionRegistry,- WSSessionHandle,-)--if TYPE_CHECKING:- from fastapi import Request, WebSocket- from fastapi.responses import JSONResponse, Response, StreamingResponse--import httpx--from headroom.copilot_auth import apply_copilot_api_auth, build_copilot_upstream_url-from headroom.pipeline import PipelineStage, summarize_routing_markers--logger = logging.getLogger("headroom.proxy")---# Interactive Responses turns are latency-sensitive. Fail open quickly rather-# than holding the session hostage on memory lookup.-RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS = 2.0--# Cap the wait for the first client frame after the WS handshake completes.-# A zombie or malicious client that accepts the upgrade but never sends the-# first response.create frame would otherwise hold a slot indefinitely and-# starve the session registry. 60 s is generous for real clients (Codex-# typically sends the first frame within a few hundred milliseconds of the-# accept) but short enough to bound the damage from a hung peer.-WS_FIRST_FRAME_TIMEOUT_SECONDS = 60.0---def _decode_openai_bearer_payload(headers: dict[str, str]) -> dict[str, Any] | None:- """Best-effort decode of an OpenAI OAuth bearer token payload.-- OpenClaw's Codex OAuth flow may forward only the bearer token after the- provider base URL is overridden. In that case the explicit- ``ChatGPT-Account-ID`` header can be missing even though the JWT still- carries the account id we need to route to the ChatGPT Codex backend.- """- auth = headers.get("authorization") or headers.get("Authorization")- if not auth:- return None-- scheme, _, token = auth.partition(" ")- if scheme.lower() != "bearer" or token.count(".") < 2:- return None-- payload = token.split(".", 2)[1]- payload += "=" * (-len(payload) % 4)- # Intentionally no signature verification here: this is only a best-effort- # routing hint extractor. Upstream still performs the actual auth/authz checks.- try:- decoded = base64.urlsafe_b64decode(payload.encode("ascii"))- data = json.loads(decoded.decode("utf-8"))- except (ValueError, UnicodeDecodeError):- return None-- return data if isinstance(data, dict) else None---def _resolve_codex_routing_headers(headers: dict[str, str]) -> tuple[dict[str, str], bool]:- """Resolve ChatGPT Codex routing hints from explicit headers or OAuth JWT."""- resolved = dict(headers)- lower_lookup = {k.lower(): k for k in resolved}-- if "chatgpt-account-id" in lower_lookup:- return resolved, True-- payload = _decode_openai_bearer_payload(resolved)- auth_claims = payload.get("https://api.openai.com/auth") if isinstance(payload, dict) else None- account_id = auth_claims.get("chatgpt_account_id") if isinstance(auth_claims, dict) else None- if isinstance(account_id, str) and account_id.strip():- resolved["ChatGPT-Account-ID"] = account_id.strip()- return resolved, True-- return resolved, False---class OpenAIHandlerMixin:- """Mixin providing OpenAI API handler methods for HeadroomProxy."""-- @staticmethod- def _strict_previous_turn_frozen_count(- messages: list[dict[str, Any]],- base_frozen_count: int,- ) -> int:- """Freeze all prior turns in cache mode; only final user turn is mutable."""- if not messages:- return base_frozen_count- final_idx = len(messages) - 1- if messages[final_idx].get("role") == "user":- return max(base_frozen_count, final_idx)- return len(messages)-- @staticmethod- def _restore_frozen_prefix(- original_messages: list[dict[str, Any]],- candidate_messages: list[dict[str, Any]],- *,- frozen_message_count: int,- ) -> tuple[list[dict[str, Any]], int]:- """Force frozen prefix bytes to match original request exactly."""- if frozen_message_count <= 0 or not original_messages:- return candidate_messages, 0-- frozen = min(frozen_message_count, len(original_messages))- restored = list(candidate_messages)-- if len(restored) < frozen:- return list(original_messages[:frozen]) + restored, frozen-- changed = 0- for idx in range(frozen):- if restored[idx] != original_messages[idx]:- restored[idx] = original_messages[idx]- changed += 1- return restored, changed-- async def handle_openai_chat(- self,- request: Request,- ) -> Response | StreamingResponse:- """Handle OpenAI /v1/chat/completions endpoint."""- if not hasattr(self, "pipeline_extensions"):- from headroom.pipeline import PipelineExtensionManager-- self.pipeline_extensions = PipelineExtensionManager(discover=False)-- from fastapi import HTTPException- from fastapi.responses import JSONResponse, Response-- from headroom.ccr import CCRToolInjector- from headroom.proxy.helpers import (- COMPRESSION_TIMEOUT_SECONDS,- MAX_MESSAGE_ARRAY_LENGTH,- MAX_REQUEST_BODY_SIZE,- _read_request_json,- )- from headroom.proxy.modes import is_cache_mode, is_token_mode- from headroom.tokenizers import get_tokenizer- from headroom.utils import extract_user_query-- start_time = time.time()- request_id = await self._next_request_id()-- # Check request body size- content_length = request.headers.get("content-length")- if content_length and int(content_length) > MAX_REQUEST_BODY_SIZE:- return JSONResponse(- status_code=413,- content={- "error": {- "message": f"Request body too large. Maximum size is {MAX_REQUEST_BODY_SIZE // (1024 * 1024)}MB",- "type": "invalid_request_error",- "code": "request_too_large",- }- },- )-- # Parse request- try:- body = await _read_request_json(request)- except (json.JSONDecodeError, ValueError) as e:- return JSONResponse(- status_code=400,- content={- "error": {- "message": f"Invalid request body: {e!s}",- "type": "invalid_request_error",- "code": "invalid_json",- }- },- )- model = body.get("model", "unknown")- messages = body.get("messages", [])- original_client_messages = copy.deepcopy(messages)- input_event = self.pipeline_extensions.emit(- PipelineStage.INPUT_RECEIVED,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=messages,- tools=body.get("tools"),- metadata={"path": "/v1/chat/completions", "stream": body.get("stream", False)},- )- if input_event.messages is not None:- messages = input_event.messages- original_client_messages = copy.deepcopy(messages)- if input_event.tools is not None:- body["tools"] = input_event.tools-- # Validate message array size- if len(messages) > MAX_MESSAGE_ARRAY_LENGTH:- return JSONResponse(- status_code=400,- content={- "error": {- "message": f"Message array too large ({len(messages)} messages). "- f"Maximum is {MAX_MESSAGE_ARRAY_LENGTH}.",- "type": "invalid_request_error",- "code": "invalid_request",- }- },- )-- stream = body.get("stream", False)-- # Bypass: skip ALL compression for explicit opt-out- _bypass = (- request.headers.get("x-headroom-bypass", "").lower() == "true"- or request.headers.get("x-headroom-mode", "").lower() == "passthrough"- )- if _bypass:- logger.info(f"[{request_id}] Bypass: skipping compression (header)")-- # Image compression: tile alignment + ML-based technique routing- if self.config.image_optimize and messages and not _bypass:- from headroom.proxy.helpers import _get_image_compressor-- compressor = _get_image_compressor()- if compressor and compressor.has_images(messages):- messages = compressor.compress(messages, provider="openai")- if compressor.last_result:- logger.info(- f"[{request_id}] Image: {compressor.last_result.technique.value} "- f"({compressor.last_result.savings_percent:.0f}% saved, "- f"{compressor.last_result.original_tokens} → "- f"{compressor.last_result.compressed_tokens} tokens)"- )-- headers = dict(request.headers.items())- headers.pop("host", None)- headers.pop("content-length", None)- # Strip accept-encoding so httpx negotiates its own encoding.- # Cloudflare Workers forward "br, zstd" which OpenAI may honor;- # if httpx lacks brotli support the response body is undecipherable → 502.- headers.pop("accept-encoding", None)- tags = self._extract_tags(headers)-- # Memory: Get user ID when memory is enabled- memory_user_id: str | None = None- if self.memory_handler:- memory_user_id = headers.get(- "x-headroom-user-id",- os.environ.get("USER", os.environ.get("USERNAME", "default")),- )-- # Rate limiting- if self.rate_limiter:- rate_key = headers.get("authorization", "default")[:20]- allowed, wait_seconds = await self.rate_limiter.check_request(rate_key)- if not allowed:- await self.metrics.record_rate_limited(provider="openai")- raise HTTPException(- status_code=429,- detail=f"Rate limited. Retry after {wait_seconds:.1f}s",- )-- # Check cache- if self.cache and not stream:- cached = await self.cache.get(messages, model)- if cached:- self.pipeline_extensions.emit(- PipelineStage.INPUT_CACHED,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=messages,- metadata={"cache_hit": True, "path": "/v1/chat/completions"},- )- await self.metrics.record_request(- provider="openai",- model=model,- input_tokens=0,- output_tokens=0,- tokens_saved=0, # Savings already counted when response was cached- latency_ms=(time.time() - start_time) * 1000,- cached=True,- )-- # Remove compression headers from cached response- response_headers = dict(cached.response_headers)- response_headers.pop("content-encoding", None)- response_headers.pop("content-length", None)-- return Response(content=cached.response_body, headers=response_headers)-- # Token counting- tokenizer = get_tokenizer(model)- original_tokens = tokenizer.count_messages(messages)-- # Hook: pre_compress- _hook_biases = None- if self.config.hooks:- from headroom.hooks import CompressContext-- _hook_ctx = CompressContext(model=model, provider="openai")- try:- messages = self.config.hooks.pre_compress(messages, _hook_ctx)- _hook_biases = self.config.hooks.compute_biases(messages, _hook_ctx)- except Exception as e:- logger.debug(f"[{request_id}] Hook error: {e}")-- # Optimization- transforms_applied = []- pipeline_timing: dict[str, float] = {}- waste_signals_dict: dict[str, int] | None = None- optimized_messages = messages- optimized_tokens = original_tokens-- # Get prefix cache tracker for this session- openai_session_id = self.session_tracker_store.compute_session_id(request, model, messages)- openai_prefix_tracker = self.session_tracker_store.get_or_create(- openai_session_id, "openai"- )- openai_frozen_count = openai_prefix_tracker.get_frozen_message_count()- if is_cache_mode(self.config.mode):- openai_frozen_count = self._strict_previous_turn_frozen_count(- original_client_messages,- openai_frozen_count,- )-- _compression_failed = False- original_messages = messages # Preserve for 400-retry fallback- _license_ok = self.usage_reporter.should_compress if self.usage_reporter else True- if self.config.optimize and messages and not _bypass and _license_ok:- try:- context_limit = self.openai_provider.get_context_limit(model)-- if is_token_mode(self.config.mode):- comp_cache = self._get_compression_cache(openai_session_id)-- # Zone 1: Swap cached compressed versions- working_messages = comp_cache.apply_cached(messages)-- # Re-freeze boundary- openai_frozen_count = comp_cache.compute_frozen_count(messages)-- result = await asyncio.wait_for(- asyncio.to_thread(- lambda: self.openai_pipeline.apply(- messages=working_messages,- model=model,- model_limit=context_limit,- context=extract_user_query(working_messages),- frozen_message_count=openai_frozen_count,- biases=_hook_biases,- )- ),- timeout=COMPRESSION_TIMEOUT_SECONDS,- )-- if result.messages != working_messages:- comp_cache.update_from_result(messages, result.messages)-- # Always use pipeline result in token mode- optimized_messages = result.messages- transforms_applied = result.transforms_applied- pipeline_timing = result.timing- # Keep original_tokens as the REAL original (pre-Zone-1-swap)- # so tokens_saved captures both Zone 1 + Zone 2 savings.- optimized_tokens = result.tokens_after- else:- result = await asyncio.wait_for(- asyncio.to_thread(- lambda: self.openai_pipeline.apply(- messages=messages,- model=model,- model_limit=context_limit,- context=extract_user_query(messages),- frozen_message_count=openai_frozen_count,- biases=_hook_biases,- )- ),- timeout=COMPRESSION_TIMEOUT_SECONDS,- )-- if result.messages != messages:- optimized_messages = result.messages- transforms_applied = result.transforms_applied- pipeline_timing = result.timing- original_tokens = result.tokens_before- optimized_tokens = result.tokens_after-- if result.waste_signals:- waste_signals_dict = result.waste_signals.to_dict()- except Exception as e:- logger.warning(f"Optimization failed: {e}")- # Flag compression failure for observability- _compression_failed = True-- # Guard: if "optimization" inflated tokens, revert to originals- if optimized_tokens > original_tokens:- logger.warning(- f"[{request_id}] Optimization inflated tokens "- f"({original_tokens} -> {optimized_tokens}), reverting to original messages"- )- optimized_messages = original_messages- optimized_tokens = original_tokens- transforms_applied = []-- tokens_saved = original_tokens - optimized_tokens- optimization_latency = (time.time() - start_time) * 1000-- routing_markers = summarize_routing_markers(transforms_applied)- if routing_markers:- routed_event = self.pipeline_extensions.emit(- PipelineStage.INPUT_ROUTED,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=optimized_messages,- metadata={- "routing_markers": routing_markers,- "transforms_applied": transforms_applied,- },- )- if routed_event.messages is not None:- optimized_messages = routed_event.messages- optimized_tokens = tokenizer.count_messages(optimized_messages)- tokens_saved = original_tokens - optimized_tokens-- compressed_event = self.pipeline_extensions.emit(- PipelineStage.INPUT_COMPRESSED,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=optimized_messages,- metadata={- "tokens_before": original_tokens,- "tokens_after": optimized_tokens,- "transforms_applied": transforms_applied,- },- )- if compressed_event.messages is not None:- optimized_messages = compressed_event.messages- optimized_tokens = tokenizer.count_messages(optimized_messages)- tokens_saved = original_tokens - optimized_tokens-- # Hook: post_compress- if self.config.hooks and tokens_saved > 0:- from headroom.hooks import CompressEvent-- try:- self.config.hooks.post_compress(- CompressEvent(- tokens_before=original_tokens,- tokens_after=optimized_tokens,- tokens_saved=tokens_saved,- compression_ratio=tokens_saved / original_tokens- if original_tokens > 0- else 0,- transforms_applied=transforms_applied,- model=model,- provider="openai",- )- )- except Exception as e:- logger.debug(f"[{request_id}] post_compress hook error: {e}")-- # CCR Tool Injection: Inject retrieval tool if compression occurred- tools = body.get("tools")- _original_tools = tools # Preserve for diagnostic / future retry- if (- self.config.ccr_inject_tool or self.config.ccr_inject_system_instructions- ) and not _bypass:- injector = CCRToolInjector(- provider="openai",- inject_tool=self.config.ccr_inject_tool,- inject_system_instructions=self.config.ccr_inject_system_instructions,- )- optimized_messages, tools, was_injected = injector.process_request(- optimized_messages, tools- )-- if injector.has_compressed_content:- if was_injected:- logger.debug(- f"[{request_id}] CCR: Injected retrieval tool for hashes: {injector.detected_hashes}"- )- else:- logger.debug(- f"[{request_id}] CCR: Tool already present (MCP?), skipped injection for hashes: {injector.detected_hashes}"- )-- # Query Echo: disabled — hurts prefix caching in long conversations.- if is_cache_mode(self.config.mode):- optimized_messages, restored_count = self._restore_frozen_prefix(- original_client_messages,- optimized_messages,- frozen_message_count=openai_frozen_count,- )- if restored_count > 0:- logger.warning(- f"[{request_id}] Restored {restored_count} frozen prefix message(s) "- "to preserve cache stability (openai)"- )-- # Memory: inject context and tools for OpenAI requests- memory_context_injected = False- memory_tools_injected = False- if self.memory_handler and memory_user_id:- try:- # Inject memory context (search similar memories, add as system message)- if self.memory_handler.config.inject_context:- memory_context = await self.memory_handler.search_and_format_context(- memory_user_id, optimized_messages- )- if memory_context:- # Prepend as system message for OpenAI format- optimized_messages = [- {"role": "system", "content": memory_context},- *optimized_messages,- ]- memory_context_injected = True- logger.info(- f"[{request_id}] Memory: Injected {len(memory_context)} chars "- f"of context for user {memory_user_id}"- )-- # Inject memory tools- if self.memory_handler.config.inject_tools:- tools, mem_tools_injected = self.memory_handler.inject_tools(tools, "openai")- if mem_tools_injected:- memory_tools_injected = True- logger.info(f"[{request_id}] Memory: Injected memory tools (openai)")- except Exception as e:- logger.warning(f"[{request_id}] Memory injection failed: {e}")-- if memory_context_injected or memory_tools_injected:- remembered_event = self.pipeline_extensions.emit(- PipelineStage.INPUT_REMEMBERED,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=optimized_messages,- tools=tools,- metadata={- "memory_context_injected": memory_context_injected,- "memory_tools_injected": memory_tools_injected,- },- )- if remembered_event.messages is not None:- optimized_messages = remembered_event.messages- if remembered_event.tools is not None:- tools = remembered_event.tools-- body["messages"] = optimized_messages- if tools is not None:- body["tools"] = tools-- presend_event = self.pipeline_extensions.emit(- PipelineStage.PRE_SEND,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=optimized_messages,- tools=tools,- headers=headers,- metadata={"path": "/v1/chat/completions", "stream": stream},- )- if presend_event.messages is not None:- optimized_messages = presend_event.messages- body["messages"] = optimized_messages- if presend_event.tools is not None:- tools = presend_event.tools- body["tools"] = tools- if presend_event.headers is not None:- headers = presend_event.headers- optimized_tokens = tokenizer.count_messages(body["messages"])- tokens_saved = original_tokens - optimized_tokens-- # Route through LiteLLM/any-llm backend if configured- if self.anthropic_backend is not None:- try:- if stream:- self.pipeline_extensions.emit(- PipelineStage.POST_SEND,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=body["messages"],- tools=tools,- metadata={"path": "/v1/chat/completions", "stream": True},- )- # Streaming: use stream_openai_message() → SSE events- return await self._stream_openai_via_backend(- body,- headers,- model,- request_id,- start_time,- original_tokens,- optimized_tokens,- tokens_saved,- transforms_applied,- tags,- optimization_latency,- pipeline_timing=pipeline_timing,- )- else:- # Non-streaming: use send_openai_message() → JSON- backend_response = await self.anthropic_backend.send_openai_message(- body, headers- )- self.pipeline_extensions.emit(- PipelineStage.POST_SEND,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=body["messages"],- tools=tools,- response=backend_response.body,- metadata={- "path": "/v1/chat/completions",- "stream": False,- "status_code": backend_response.status_code,- },- )- self.pipeline_extensions.emit(- PipelineStage.RESPONSE_RECEIVED,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- response=backend_response.body,- metadata={- "path": "/v1/chat/completions",- "stream": False,- "status_code": backend_response.status_code,- },- )-- if backend_response.error:- return JSONResponse(- status_code=backend_response.status_code,- content=backend_response.body,- )-- # Track metrics- total_latency = (time.time() - start_time) * 1000- usage = backend_response.body.get("usage", {})- output_tokens = usage.get("completion_tokens", 0)- total_input_tokens = usage.get("prompt_tokens", optimized_tokens)-- await self.metrics.record_request(- provider=self.anthropic_backend.name,- model=model,- input_tokens=total_input_tokens,- output_tokens=output_tokens,- tokens_saved=tokens_saved,- latency_ms=total_latency,- cached=False,- overhead_ms=optimization_latency,- pipeline_timing=pipeline_timing,- )-- if tokens_saved > 0:- logger.info(- f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "- f"(saved {tokens_saved:,} tokens) via {self.anthropic_backend.name}"- )-- return JSONResponse(- status_code=backend_response.status_code,- content=backend_response.body,- )- except Exception as e:- logger.error(f"[{request_id}] Backend error: {e}")- return JSONResponse(- status_code=500,- content={- "error": {- "message": str(e),- "type": "api_error",- "code": "backend_error",- }- },- )-- # Direct OpenAI API (no backend configured)- url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/chat/completions")-- try:- if stream:- # Inject stream_options to get usage stats in streaming response- # This allows accurate token counting instead of byte-based estimation- if "stream_options" not in body:- body["stream_options"] = {"include_usage": True}- elif isinstance(body.get("stream_options"), dict):- body["stream_options"]["include_usage"] = True-- self.pipeline_extensions.emit(- PipelineStage.POST_SEND,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=body["messages"],- tools=tools,- metadata={"path": "/v1/chat/completions", "stream": True},- )- return await self._stream_response(- url,- headers,- body,- "openai",- model,- request_id,- original_tokens,- optimized_tokens,- tokens_saved,- transforms_applied,- tags,- optimization_latency,- pipeline_timing=pipeline_timing,- prefix_tracker=openai_prefix_tracker,- )- else:- headers = await apply_copilot_api_auth(headers, url=url)- response = await self._retry_request("POST", url, headers, body)- self.pipeline_extensions.emit(- PipelineStage.POST_SEND,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- messages=body["messages"],- tools=tools,- response=response,- metadata={- "path": "/v1/chat/completions",- "stream": False,- "status_code": response.status_code,- },- )- self.pipeline_extensions.emit(- PipelineStage.RESPONSE_RECEIVED,- operation="proxy.request",- request_id=request_id,- provider="openai",- model=model,- response=response,- metadata={- "path": "/v1/chat/completions",- "stream": False,- "status_code": response.status_code,- },- )-- # Full diagnostic dump on upstream errors (OpenAI handler)- if response.status_code >= 400:- try:- err_body = response.json()- err_msg = err_body.get("error", {}).get("message", "")- err_type = err_body.get("error", {}).get("type", "")- except Exception:- err_body = {"raw": response.text[:2000]}- err_msg = str(response.text[:500])- err_type = "parse_error"-- logger.warning(- f"[{request_id}] UPSTREAM_ERROR "- f"status={response.status_code} "- f"error_type={err_type} "- f"error_msg={err_msg!r} "- f"model={model} "- f"compressed={'yes' if transforms_applied else 'no'} "- f"transforms={transforms_applied} "- f"original_tokens={original_tokens} "- f"optimized_tokens={optimized_tokens} "- f"message_count={len(body.get('messages', []))} "- f"stream={stream}"- )-- try:- from headroom import paths as _hr_paths-- debug_dir = _hr_paths.debug_400_dir()- debug_dir.mkdir(parents=True, exist_ok=True)- ts = datetime.now().strftime("%Y%m%d_%H%M%S")- debug_file = debug_dir / f"{ts}_{request_id}.json"-- safe_headers = {}- for k, v in headers.items():- if k.lower() in ("x-api-key", "authorization"):- safe_headers[k] = v[:12] + "..." if v else ""- else:- safe_headers[k] = v-- debug_payload = {- "request_id": request_id,- "timestamp": datetime.now().isoformat(),- "status_code": response.status_code,- "error_response": err_body,- "model": model,- "stream": stream,- "headers": safe_headers,- "compression": {- "was_compressed": bool(transforms_applied),- "transforms": transforms_applied,- "original_tokens": original_tokens,- "optimized_tokens": optimized_tokens,- "tokens_saved": tokens_saved,- "compression_failed": _compression_failed,- },- "tools_sent": body.get("tools"),- "tool_count": len(body.get("tools") or []),- "original_tool_count": len(_original_tools or []),- "messages_sent": body.get("messages"),- "message_count": len(body.get("messages", [])),- "original_messages": (- original_messages- if original_messages is not body.get("messages")- else "__same_as_sent__"- ),- "original_message_count": len(original_messages),- "system_prompt": body.get("system"),- }-- with open(debug_file, "w") as f:- json.dump(debug_payload, f, indent=2, default=str)-- logger.warning(f"[{request_id}] Full debug dump: {debug_file}")- except Exception as dump_err:- logger.error(f"[{request_id}] Failed to write debug dump: {dump_err}")-- total_latency = (time.time() - start_time) * 1000-- total_input_tokens = optimized_tokens # fallback- output_tokens = 0- cache_read_tokens = 0- resp_json = None- try:- resp_json = response.json()- usage = resp_json.get("usage", {})- total_input_tokens = usage.get("prompt_tokens", optimized_tokens)- output_tokens = usage.get("completion_tokens", 0)- # OpenAI returns cached_tokens in prompt_tokens_details- # These are charged at 50% of the input price- prompt_details = usage.get("prompt_tokens_details") or {}- cache_read_tokens = prompt_details.get("cached_tokens", 0)- except (KeyError, TypeError, AttributeError) as e:- logger.debug(- f"[{request_id}] Failed to extract cached tokens from OpenAI response: {e}"- )-- # Update prefix cache tracker for next turn- openai_prefix_tracker.update_from_response(- cache_read_tokens=cache_read_tokens,- cache_write_tokens=0, # OpenAI doesn't report write tokens- messages=optimized_messages,- )-- # OpenAI has no write penalty — uncached = total - cached- uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens)-- if self.cost_tracker:- self.cost_tracker.record_tokens(- model,- tokens_saved,- optimized_tokens,- cache_read_tokens=cache_read_tokens,- uncached_tokens=uncached_input_tokens,- )-- # Memory: handle memory tool calls in OpenAI Chat Completions response.- # After executing tools, send a continuation request so the model- # can produce a final user-facing response (not just tool_calls).- if (- self.memory_handler- and memory_user_id- and resp_json- and response.status_code == 200- and self.memory_handler.has_memory_tool_calls(resp_json, "openai")- ):- try:- tool_results = await self.memory_handler.handle_memory_tool_calls(- resp_json, memory_user_id, "openai"- )- if tool_results:- # Build continuation: original messages + assistant tool_calls + tool results- assistant_msg = resp_json.get("choices", [{}])[0].get("message", {})- continuation_messages = list(optimized_messages)- continuation_messages.append(assistant_msg)- continuation_messages.extend(tool_results)-- continuation_body = {- **body,- "messages": continuation_messages,- }-- cont_response = await self._retry_request(- "POST", url, headers, continuation_body- )- if cont_response.status_code == 200:- resp_json = cont_response.json()- response = cont_response-- logger.info(- f"[{request_id}] Memory: Handled {len(tool_results)} "- f"tool call(s) with continuation for user {memory_user_id}"- )- except Exception as e:- logger.warning(f"[{request_id}] Memory tool handling failed: {e}")-- # Cache- if self.cache and response.status_code == 200:- await self.cache.set(- messages,- model,- response.content,- dict(response.headers),- tokens_saved,- )-- # Capture Codex rate-limit window data from response headers- from headroom.subscription.codex_rate_limits import (- get_codex_rate_limit_state,- )-- get_codex_rate_limit_state().update_from_headers(dict(response.headers))-- await self.metrics.record_request(- provider="openai",- model=model,- input_tokens=total_input_tokens,- output_tokens=output_tokens,- tokens_saved=tokens_saved,- latency_ms=total_latency,- overhead_ms=optimization_latency,- pipeline_timing=pipeline_timing,- waste_signals=waste_signals_dict,- cache_read_tokens=cache_read_tokens,- uncached_input_tokens=uncached_input_tokens,- )-- if tokens_saved > 0:- logger.info(- f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "- f"(saved {tokens_saved:,} tokens)"- )-- # Remove compression headers since httpx already decompressed the response- response_headers = dict(response.headers)- response_headers.pop("content-encoding", None)- response_headers.pop("content-length", None) # Length changed after decompression-- # Inject Headroom compression metrics (for SaaS metering)- response_headers["x-headroom-tokens-before"] = str(original_tokens)- response_headers["x-headroom-tokens-after"] = str(optimized_tokens)- response_headers["x-headroom-tokens-saved"] = str(tokens_saved)- response_headers["x-headroom-model"] = model- if transforms_applied:- response_headers["x-headroom-transforms"] = ",".join(transforms_applied)- if cache_read_tokens > 0:- response_headers["x-headroom-cached"] = "true"- if _compression_failed:- response_headers["x-headroom-compression-failed"] = "true"-- return Response(- content=response.content,- status_code=response.status_code,- headers=response_headers,- )- except Exception as e:- await self.metrics.record_failed(provider="openai")- # Log full error details internally for debugging- logger.error(f"[{request_id}] OpenAI request failed: {type(e).__name__}: {e}")- # Return sanitized error message to client (don't expose internal details)- return JSONResponse(- status_code=502,- content={- "error": {- "message": "An error occurred while processing your request. Please try again.",- "type": "server_error",- "code": "proxy_error",- }- },- )-- async def handle_openai_responses(- self,- request: Request,- ) -> Response | StreamingResponse:- """Handle OpenAI /v1/responses endpoint (new Responses API).-- The Responses API differs from /v1/chat/completions:- - Input: `input` (string or array) instead of `messages`- - System: `instructions` instead of system message- - Output: `output[]` array instead of `choices[].message`- - State: `previous_response_id` for multi-turn- - Built-in tools: web_search, file_search, code_interpreter- """- from fastapi import HTTPException- from fastapi.responses import JSONResponse, Response-- from headroom.proxy.helpers import (- COMPRESSION_TIMEOUT_SECONDS,- MAX_REQUEST_BODY_SIZE,- _read_request_json,- )- from headroom.proxy.responses_converter import (- messages_to_responses_items,- responses_items_to_messages,- )- from headroom.tokenizers import get_tokenizer- from headroom.utils import extract_user_query-- start_time = time.time()- request_id = await self._next_request_id()-- # Check request body size- content_length = request.headers.get("content-length")- if content_length and int(content_length) > MAX_REQUEST_BODY_SIZE:- return JSONResponse(- status_code=413,- content={- "error": {- "message": f"Request body too large. Maximum size is {MAX_REQUEST_BODY_SIZE // (1024 * 1024)}MB",- "type": "invalid_request_error",- "code": "request_too_large",- }- },- )-- # Parse request- try:- body = await _read_request_json(request)- except (json.JSONDecodeError, ValueError) as e:- return JSONResponse(- status_code=400,- content={- "error": {- "message": f"Invalid request body: {e!s}",- "type": "invalid_request_error",- "code": "invalid_json",- }- },- )-- model = body.get("model", "unknown")- stream = body.get("stream", False)-- # Convert Responses API input to messages format for optimization.- # The Responses API uses a different item model (function_call,- # function_call_output, reasoning as top-level items) — we convert to- # Chat Completions messages for the pipeline, then convert back.-- input_data = body.get("input", "")- instructions = body.get("instructions")- previous_response_id = body.get("previous_response_id")-- messages: list[dict[str, Any]] = []- original_items: list[dict[str, Any]] | None = None- preserved_indices: list[int] = []-- if instructions:- messages.append({"role": "system", "content": instructions})-- if isinstance(input_data, str):- messages.append({"role": "user", "content": input_data})- elif isinstance(input_data, list):- original_items = input_data- converted, preserved_indices = responses_items_to_messages(input_data)- messages.extend(converted)-- headers = dict(request.headers.items())- headers.pop("host", None)- headers.pop("content-length", None)- # Strip accept-encoding so httpx negotiates its own encoding.- # Cloudflare Workers forward "br, zstd" which OpenAI may honor;- # if httpx lacks brotli support the response body is undecipherable → 502.- headers.pop("accept-encoding", None)- tags = self._extract_tags(headers)-- # Memory: Get user ID when memory is enabled- memory_user_id: str | None = None- if self.memory_handler:- memory_user_id = headers.get(- "x-headroom-user-id",- os.environ.get("USER", os.environ.get("USERNAME", "default")),- )-- # Rate limiting- if self.rate_limiter:- rate_key = headers.get("authorization", "default")[:20]- allowed, wait_seconds = await self.rate_limiter.check_request(rate_key)- if not allowed:- await self.metrics.record_rate_limited(provider="openai")- raise HTTPException(- status_code=429,- detail=f"Rate limited. Retry after {wait_seconds:.1f}s",- )-- # Token counting on converted messages- tokenizer = get_tokenizer(model)- original_tokens = tokenizer.count_messages(messages)-- # Optimize: convert items → compress → convert back- tokens_saved = 0- transforms_applied: list[str] = []- optimized_messages = messages- optimized_tokens = original_tokens-- _bypass = (- request.headers.get("x-headroom-bypass", "").lower() == "true"- or request.headers.get("x-headroom-mode", "").lower() == "passthrough"- )- _should_compress = (- self.config.optimize- and original_items is not None- and not previous_response_id- and not _bypass- and len(messages) > 1- )- _license_ok = self.usage_reporter.should_compress if self.usage_reporter else True-- if _should_compress and _license_ok:- try:- context_limit = self.openai_provider.get_context_limit(model)- result = await asyncio.wait_for(- asyncio.to_thread(- lambda: self.openai_pipeline.apply(- messages=messages,- model=model,- model_limit=context_limit,- context=extract_user_query(messages),- )- ),- timeout=COMPRESSION_TIMEOUT_SECONDS,- )- if result.messages != messages:- optimized_messages = result.messages- transforms_applied = result.transforms_applied- original_tokens = result.tokens_before- optimized_tokens = result.tokens_after- except Exception as e:- logger.warning(f"[{request_id}] Responses API optimization failed: {e}")-- # Guard: if "optimization" inflated tokens, revert to originals- if optimized_tokens > original_tokens:- logger.warning(- f"[{request_id}] Optimization inflated tokens "- f"({original_tokens} -> {optimized_tokens}), reverting to original messages"- )- optimized_messages = messages- optimized_tokens = original_tokens- transforms_applied = []-- tokens_saved = original_tokens - optimized_tokens- optimization_latency = (time.time() - start_time) * 1000-- # Convert compressed messages back to Responses API items- if optimized_messages is not messages and original_items is not None:- opt_msgs = optimized_messages- # Strip system message (instructions) — it's separate in Responses API- if instructions and opt_msgs and opt_msgs[0].get("role") == "system":- body["instructions"] = opt_msgs[0]["content"]- opt_msgs = opt_msgs[1:]-- body["input"] = messages_to_responses_items(opt_msgs, original_items, preserved_indices)-- # Memory: inject context and tools for Responses API requests- if self.memory_handler and memory_user_id:- try:- # Inject memory context into instructions (Responses API system prompt)- if self.memory_handler.config.inject_context:- try:- memory_context = await asyncio.wait_for(- self.memory_handler.search_and_format_context(- memory_user_id, optimized_messages- ),- timeout=RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS,- )- except asyncio.TimeoutError:- memory_context = None- logger.info(- f"[{request_id}] Memory context lookup exceeded "- f"{RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS:.1f}s; continuing without it"- )- if memory_context:- existing_instructions = body.get("instructions") or ""- if existing_instructions:- body["instructions"] = f"{existing_instructions}\n\n{memory_context}"- else:- body["instructions"] = memory_context- logger.info(- f"[{request_id}] Memory: Injected {len(memory_context)} chars "- f"of context into instructions for user {memory_user_id}"- )-- # Inject memory tools (Responses API format)- if self.memory_handler.config.inject_tools:- resp_tools = body.get("tools") or []- resp_tools, mem_tools_injected = self.memory_handler.inject_tools(- resp_tools, "openai"- )- if mem_tools_injected:- # Convert Chat Completions format to Responses API format- converted_tools = []- for t in resp_tools:- if t.get("type") == "function" and "function" in t:- fn = t["function"]- converted_tools.append(- {- "type": "function",- "name": fn.get("name"),- "description": fn.get("description", ""),- "parameters": fn.get("parameters", {}),- }- )- else:- converted_tools.append(t)- body["tools"] = converted_tools- logger.info(- f"[{request_id}] Memory: Injected memory tools (openai/responses)"- )- except Exception as e:- logger.warning(f"[{request_id}] Memory injection failed (responses): {e}")-- # /v1/responses is OpenAI-specific (Codex) — always routes direct.- # LiteLLM/AnyLLM backends use /v1/chat/completions or /v1/messages.- if self.anthropic_backend is not None:- logger.debug(- f"[{request_id}] /v1/responses always routes to OpenAI direct "- f"(backend '{self.anthropic_backend.name}' not used for Responses API)"- )-- headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)-- # Route to correct endpoint based on auth mode.- # ChatGPT session auth (codex login) uses chatgpt.com, not api.openai.com.- if is_chatgpt_auth:- url = "https://chatgpt.com/backend-api/codex/responses"- else:- url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")-- try:- if stream:- # Streaming for Responses API uses semantic events- return await self._stream_response(- url,- headers,- body,- "openai",- model,- request_id,- original_tokens,- optimized_tokens,- tokens_saved,- transforms_applied,- tags,- optimization_latency,- memory_user_id=memory_user_id,- )- else:- headers = await apply_copilot_api_auth(headers, url=url)- response = await self._retry_request("POST", url, headers, body)- total_latency = (time.time() - start_time) * 1000-- total_input_tokens = original_tokens # fallback- output_tokens = 0- try:- resp_json = response.json()- usage = resp_json.get("usage", {})- total_input_tokens = usage.get("input_tokens", original_tokens)- output_tokens = usage.get("output_tokens", 0)- except (KeyError, TypeError, AttributeError) as e:- logger.debug(- f"[{request_id}] Failed to extract cached tokens from OpenAI passthrough response: {e}"- )-- # Memory: handle memory tool calls in Responses API response- if (- self.memory_handler- and memory_user_id- and resp_json- and response.status_code == 200- and self.memory_handler.has_memory_tool_calls(resp_json, "openai")- ):- try:- # Extract function_call items from output- from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES-- output_items = resp_json.get("output", [])- memory_fc_items = [- item- for item in output_items- if isinstance(item, dict)- and item.get("type") == "function_call"- and item.get("name") in MEMORY_TOOL_NAMES- ]-- # Execute memory tool calls- tool_outputs: list[dict[str, Any]] = []- for fc in memory_fc_items:- call_id = fc.get("call_id", fc.get("id", ""))- name = fc.get("name", "")- args_str = fc.get("arguments", "{}")- try:- args = json.loads(args_str)- except json.JSONDecodeError:- args = {}-- await self.memory_handler._ensure_initialized()- if self.memory_handler._backend:- result = await self.memory_handler._execute_memory_tool(- name, args, memory_user_id, "openai"- )- else:- result = json.dumps({"error": "Memory backend not initialized"})-- tool_outputs.append(- {- "type": "function_call_output",- "call_id": call_id,- "output": result,- }- )-- if tool_outputs:- # Make continuation request with tool results- response_id = resp_json.get("id")- continuation_body = {- "model": model,- "input": tool_outputs,- }- if response_id:- continuation_body["previous_response_id"] = response_id- existing_tools = body.get("tools")- if existing_tools:- continuation_body["tools"] = existing_tools-- cont_response = await self._retry_request(- "POST", url, headers, continuation_body- )- resp_json = cont_response.json()- response = cont_response- logger.info(- f"[{request_id}] Memory: Handled {len(tool_outputs)} "- f"tool call(s) with continuation for user {memory_user_id} (responses)"- )- except Exception as e:- logger.warning(- f"[{request_id}] Memory tool handling failed (responses): {e}"- )-- if self.cost_tracker:- self.cost_tracker.record_tokens(model, tokens_saved, total_input_tokens)-- await self.metrics.record_request(- provider="openai",- model=model,- input_tokens=total_input_tokens,- output_tokens=output_tokens,- tokens_saved=tokens_saved,- latency_ms=total_latency,- overhead_ms=optimization_latency,- )-- logger.info(f"[{request_id}] /v1/responses {model}: {total_input_tokens:,} tokens")-- # Capture Codex rate-limit window data from response headers- from headroom.subscription.codex_rate_limits import (- get_codex_rate_limit_state,- )-- get_codex_rate_limit_state().update_from_headers(dict(response.headers))-- # Remove compression headers- response_headers = dict(response.headers)- response_headers.pop("content-encoding", None)- response_headers.pop("content-length", None)-- return Response(- content=response.content,- status_code=response.status_code,- headers=response_headers,- )- except Exception as e:- await self.metrics.record_failed(provider="openai")- logger.error(f"[{request_id}] OpenAI responses request failed: {type(e).__name__}: {e}")- return JSONResponse(- status_code=502,- content={- "error": {- "message": "An error occurred while processing your request. Please try again.",- "type": "server_error",- "code": "proxy_error",- }- },- )-- async def handle_openai_responses_ws(self, websocket: WebSocket) -> None:- """WebSocket proxy for /v1/responses (Codex gpt-5.4+).-- Newer Codex versions use WebSocket instead of HTTP POST for the- Responses API. This handler:- 1. Accepts the client WebSocket- 2. Receives the first message (``response.create`` request)- 3. Compresses the ``input`` array using the existing pipeline- 4. Opens an upstream WebSocket to OpenAI- 5. Sends the compressed request upstream- 6. Relays all subsequent messages bidirectionally- """- from headroom.proxy.helpers import COMPRESSION_TIMEOUT_SECONDS- from headroom.tokenizers import get_tokenizer- from headroom.utils import extract_user_query-- try:- import websockets- except ImportError:- await websocket.accept()- await websocket.close(- code=1011,- reason="websockets package not installed. pip install websockets",- )- return-- request_id = await self._next_request_id()- session_id = uuid.uuid4().hex-- # Stage-timer — captures per-stage durations for the structured- # log emitted on session close. Unit 2 instrumentation.- stage_timer = StageTimer()- session_started_at = time.perf_counter()-- # Unit 3: initialize registry variables *before* accept so the- # outermost ``finally`` can rely on them existing even if- # registration itself fails for some reason.- ws_sessions: WebSocketSessionRegistry | None = getattr(self, "ws_sessions", None)- session_handle: WSSessionHandle | None = None- termination_cause: TerminationCause = "unknown"-- # Forward client headers to upstream, adding required OpenAI-Beta header- ws_headers = dict(websocket.headers)-- # Extract subprotocol from client — this is an application-level negotiation- # that MUST be forwarded end-to-end (unlike sec-websocket-key which is per-connection).- # Codex and OpenAI negotiate a subprotocol; stripping it causes OpenAI to return 500.- client_subprotocols: list[str] = []- raw_protocol = ws_headers.get("sec-websocket-protocol", "")- if raw_protocol:- client_subprotocols = [p.strip() for p in raw_protocol.split(",") if p.strip()]-- # Accept client connection with the requested subprotocol- async with stage_timer.measure("accept"):- if client_subprotocols:- await websocket.accept(subprotocol=client_subprotocols[0])- else:- await websocket.accept()-- # --- Unit 3: register the session as soon as accept succeeds ---- client_addr: str | None = None- client_info = getattr(websocket, "client", None)- if client_info is not None:- host = getattr(client_info, "host", None)- port = getattr(client_info, "port", None)- if host is not None and port is not None:- client_addr = f"{host}:{port}"- elif host is not None:- client_addr = str(host)- if ws_sessions is not None:- session_handle = WSSessionHandle(- session_id=session_id,- request_id=request_id,- client_addr=client_addr,- upstream_url=None, # set below once upstream_url is computed- )- ws_sessions.register(session_handle)- metrics = getattr(self, "metrics", None)- if metrics is not None and hasattr(metrics, "inc_active_ws_sessions"):- try:- metrics.inc_active_ws_sessions()- except Exception: # pragma: no cover - defensive- pass-- # Forward all client headers except hop-by-hop / per-connection headers.- # These are WebSocket handshake mechanics that the `websockets` library- # generates fresh for the upstream connection — forwarding them would conflict.- # Everything else (auth, org, beta, user-agent, custom headers) is forwarded as-is.- _skip_headers = frozenset(- {- "host", # must match upstream, not local proxy- "connection", # hop-by-hop- "upgrade", # hop-by-hop- "sec-websocket-key", # per-connection cryptographic nonce- "sec-websocket-version", # protocol version (websockets lib sets this)- "sec-websocket-extensions", # per-connection negotiation- "sec-websocket-accept", # server-side only- "sec-websocket-protocol", # handled via subprotocols param below- "content-length", # hop-by-hop- "transfer-encoding", # hop-by-hop- }- )- upstream_headers: dict[str, str] = {}- for k, v in ws_headers.items():- if k.lower() not in _skip_headers:- upstream_headers[k] = v-- upstream_headers, is_chatgpt_auth = _resolve_codex_routing_headers(upstream_headers)- _lower_headers = {k.lower(): v for k, v in upstream_headers.items()}-- # Build upstream WebSocket URL based on auth mode- if is_chatgpt_auth:- # ChatGPT session auth → route to chatgpt.com backend- upstream_url = "wss://chatgpt.com/backend-api/codex/responses"- logger.debug(- f"[{request_id}] WS: ChatGPT session auth detected, routing to chatgpt.com"- )- else:- # API key auth → route to configured OpenAI API URL- base = self.OPENAI_API_URL- ws_base = base.replace("https://", "wss://").replace("http://", "ws://")- upstream_url = build_copilot_upstream_url(ws_base, "/v1/responses")-- # Unit 3: attach the resolved upstream URL to the session handle.- if session_handle is not None:- session_handle.upstream_url = upstream_url-- # Ensure Authorization header is present — fall back to OPENAI_API_KEY env var.- # Safety net for clients that don't forward auth headers via WebSocket upgrade.- if "authorization" not in _lower_headers:- api_key = os.environ.get("OPENAI_API_KEY")- if api_key:- upstream_headers["Authorization"] = f"Bearer {api_key}"- logger.debug(f"[{request_id}] WS: injected Authorization from OPENAI_API_KEY env")- else:- logger.warning(- f"[{request_id}] WS: no Authorization header from client and "- f"OPENAI_API_KEY not set — upstream will likely reject"- )-- upstream_headers = await apply_copilot_api_auth(upstream_headers, url=upstream_url)-- # Ensure the required beta header is present — OpenAI returns 500 without it.- # Codex sends `responses_websockets=2026-02-06`; only inject if missing entirely.- if "openai-beta" not in _lower_headers:- upstream_headers["OpenAI-Beta"] = "responses_websockets=2026-02-06"-- logger.debug(- f"[{request_id}] WS upstream headers: "- f"{[k for k in upstream_headers if k.lower() != 'authorization']}, "- f"subprotocols={client_subprotocols}"- )-- try:- # Receive the first message from client (the response.create request).- # Bound the wait with WS_FIRST_FRAME_TIMEOUT_SECONDS so a zombie- # client that opens the WS but never sends a frame cannot hold a- # session slot indefinitely. The StageTimer measurement still- # captures the elapsed time up to the timeout so operators can- # see the slow-client pattern in the stage-timings log.- try:- async with stage_timer.measure("first_client_frame"):- first_msg_raw = await asyncio.wait_for(- websocket.receive_text(),- timeout=WS_FIRST_FRAME_TIMEOUT_SECONDS,- )- except asyncio.TimeoutError:- logger.info(- f"[{request_id}] WS first-frame timeout after "- f"{WS_FIRST_FRAME_TIMEOUT_SECONDS:.0f}s; closing session "- f"{session_id} (no client data)"- )- termination_cause = "client_timeout"- with contextlib.suppress(Exception):- # 1001 (going away): server is cleanly terminating a slow- # client, not an internal error.- await websocket.close(code=1001, reason="first-frame timeout")- # Exit the outer try so the session-lifecycle ``finally`` runs- # deregister / metrics / stage-timings emission as usual.- return-- # --- Optional: compress the input in the first message ---- body: dict[str, Any] = {}- try:- body = json.loads(first_msg_raw)- tokens_saved = 0- ws_request_body = body.get("response", body)- input_data = (- ws_request_body.get("input") if isinstance(ws_request_body, dict) else None- )-- should_compress = (- self.config.optimize- and isinstance(input_data, list)- and len(input_data) > 1- and not (- ws_request_body.get("previous_response_id")- if isinstance(ws_request_body, dict)- else None- )- )- if should_compress:- try:- from headroom.proxy.responses_converter import (- messages_to_responses_items,- responses_items_to_messages,- )-- model = ws_request_body.get("model", "gpt-4o")- converted, preserved = responses_items_to_messages(input_data)-- messages: list[dict[str, Any]] = []- instructions = ws_request_body.get("instructions")- if instructions:- messages.append({"role": "system", "content": instructions})- messages.extend(converted)-- tokenizer = get_tokenizer(model)- original_tokens = tokenizer.count_messages(messages)-- context_limit = self.openai_provider.get_context_limit(model)- async with stage_timer.measure("compression"):- result = await asyncio.wait_for(- asyncio.to_thread(- lambda: self.openai_pipeline.apply(- messages=messages,- model=model,- model_limit=context_limit,- context=extract_user_query(messages),- )- ),- timeout=COMPRESSION_TIMEOUT_SECONDS,- )-- if result.messages != messages:- opt = result.messages- if instructions and opt and opt[0].get("role") == "system":- ws_request_body["instructions"] = opt[0]["content"]- opt = opt[1:]- if result.tokens_after <= original_tokens:- ws_request_body["input"] = messages_to_responses_items(- opt, input_data, preserved- )- else:- logger.warning(- f"[{request_id}] WS optimization inflated tokens "- f"({original_tokens} -> {result.tokens_after}), reverting"- )- tokens_saved = max(0, original_tokens - result.tokens_after)- if "response" in body and isinstance(body["response"], dict):- body["response"] = ws_request_body- else:- body = ws_request_body- first_msg_raw = json.dumps(body)- logger.info(- f"[{request_id}] WS /v1/responses compressed: "- f"saved {tokens_saved} tokens"- )- except Exception as e:- logger.warning(f"[{request_id}] WS compression failed: {e}")-- except json.JSONDecodeError:- # Not JSON — pass through as-is- tokens_saved = 0-- # --- Memory: inject context, tools, and instructions ---- memory_user_id: str | None = None- if self.memory_handler and body:- memory_user_id = ws_headers.get(- "x-headroom-user-id",- os.environ.get("USER", os.environ.get("USERNAME", "default")),- )- try:- # Unwrap response.create envelope to access the response body- ws_response_body = body.get("response", body)-- # Debug: log what Codex sends so we can see the full tool list- existing_tool_names = [- t.get("name") or t.get("function", {}).get("name", "?")- for t in (ws_response_body.get("tools") or [])- ]- instr_preview = (ws_response_body.get("instructions") or "")[:200]- logger.info(- f"[{request_id}] WS Memory: Codex tools={existing_tool_names}, "- f"instructions_len={len(ws_response_body.get('instructions') or '')}, "- f"instructions_preview={instr_preview!r}"- )-- # Inject memory context into instructions- if self.memory_handler.config.inject_context:- ws_input = ws_response_body.get("input", "")- ws_instructions = ws_response_body.get("instructions")- ws_msgs: list[dict[str, Any]] = []- if ws_instructions:- ws_msgs.append({"role": "system", "content": ws_instructions})- if isinstance(ws_input, str) and ws_input:- ws_msgs.append({"role": "user", "content": ws_input})- elif isinstance(ws_input, list):- from headroom.proxy.responses_converter import (- responses_items_to_messages,- )-- converted_msgs, _ = responses_items_to_messages(ws_input)- ws_msgs.extend(converted_msgs)-- try:- async with stage_timer.measure("memory_context"):- memory_context = await asyncio.wait_for(- self.memory_handler.search_and_format_context(- memory_user_id, ws_msgs- ),- timeout=RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS,- )- except asyncio.TimeoutError:- memory_context = None- logger.info(- f"[{request_id}] WS Memory: Context lookup exceeded "- f"{RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS:.1f}s; "- f"continuing without it"- )- if memory_context:- existing = ws_response_body.get("instructions") or ""- if existing:- ws_response_body["instructions"] = f"{existing}\n\n{memory_context}"- else:- ws_response_body["instructions"] = memory_context- logger.info(- f"[{request_id}] WS Memory: Injected {len(memory_context)} chars "- f"of context into instructions"- )-- # Inject memory tools (Responses API format)- if self.memory_handler.config.inject_tools:- ws_tools = ws_response_body.get("tools") or []- ws_tools, mem_injected = self.memory_handler.inject_tools(- ws_tools, "openai"- )- if mem_injected:- converted_tools = []- for t in ws_tools:- if t.get("type") == "function" and "function" in t:- fn = t["function"]- converted_tools.append(- {- "type": "function",- "name": fn.get("name"),- "description": fn.get("description", ""),- "parameters": fn.get("parameters", {}),- }- )- else:- converted_tools.append(t)- ws_response_body["tools"] = converted_tools-- # Add memory instruction so the model uses- # memory tools as persistent cross-session knowledge.- mem_instruction = (- "\n\n## Memory\n"- "You have persistent memory via memory_search and "- "memory_save tools. Memory stores knowledge across "- "sessions — user info, project details, org context, "- "decisions, architecture, conventions, anything worth "- "remembering.\n\n"- "- ALWAYS call memory_search BEFORE searching files "- "when the user asks a question that could be answered "- "from prior knowledge.\n"- "- Call memory_save to store important facts, decisions, "- "or context that would be useful in future sessions.\n"- "- Memory is your first source of truth for anything "- "not visible in the current conversation."- )- existing_instr = ws_response_body.get("instructions") or ""- ws_response_body["instructions"] = existing_instr + mem_instruction- logger.info(- f"[{request_id}] WS Memory: Injected memory tools + instruction"- )-- # Write back into envelope if it was wrapped- if "response" in body and isinstance(body["response"], dict):- body["response"] = ws_response_body- else:- body = ws_response_body-- first_msg_raw = json.dumps(body)- except Exception as e:- logger.warning(f"[{request_id}] WS Memory injection failed: {e}")-- # --- Connect to upstream OpenAI WebSocket ---- logger.info(f"[{request_id}] WS /v1/responses connecting to {upstream_url}")-- # Use ssl=True to let the websockets library handle SSL natively.- # Manual ssl.create_default_context() + certifi doesn't load the- # Windows system cert store, causing HTTP 500 on wss:// connections.- use_ssl: bool | None = True if upstream_url.startswith("wss://") else None-- ws_connected = False- ws_connect_attempts = max(1, getattr(self.config, "retry_max_attempts", 3))- ws_last_err: Exception | None = None- _upstream_connect_started = time.perf_counter()- _upstream_connect_recorded = False- _upstream_first_event_started: float | None = None-- for ws_attempt in range(ws_connect_attempts):- try:- async with websockets.connect(- upstream_url,- additional_headers=upstream_headers,- subprotocols=(- [websockets.Subprotocol(p) for p in client_subprotocols]- if client_subprotocols and hasattr(websockets, "Subprotocol")- else client_subprotocols or None- ),- ssl=use_ssl,- open_timeout=max(30, self.config.connect_timeout_seconds * 3),- close_timeout=10,- ping_interval=20,- ping_timeout=20,- ) as upstream:- ws_connected = True- if not _upstream_connect_recorded:- stage_timer.record(- "upstream_connect",- (time.perf_counter() - _upstream_connect_started) * 1000.0,- )- _upstream_connect_recorded = True- _upstream_first_event_started = time.perf_counter()- await upstream.send(first_msg_raw)-- # Unit 3: flag the upstream side flips on seeing- # ``response.completed`` so the outer cause- # classifier can prefer it over the raw- # "upstream iterator ended" default.- response_completed_seen = False- # Captures the first exception surfaced by the- # inner relay ``except`` blocks so the outer- # classifier can still tell ``upstream_error``- # from ``upstream_disconnect`` / ``response_completed``- # even though the halves swallow and log.- upstream_relay_error: BaseException | None = None- client_relay_error: BaseException | None = None-- async def _client_to_upstream() -> None:- nonlocal client_relay_error- try:- while True:- msg = await websocket.receive_text()- await upstream.send(msg)- except asyncio.CancelledError:- # Explicit cancel from the outer- # orchestrator — re-raise so- # ``t.cancelled()`` and ``t.exception()``- # behave correctly in the caller.- raise- except Exception as relay_err:- # Surface real errors to the classifier- # without re-raising (existing fork- # behavior: log and return so the- # partner task can be cancelled- # deterministically).- if "WebSocketDisconnect" not in type(relay_err).__name__:- client_relay_error = relay_err- logger.debug(- f"[{request_id}] WS client→upstream relay ended: {relay_err}"- )- with contextlib.suppress(Exception):- await upstream.close()-- async def _upstream_to_client() -> None:- """Relay upstream→client with transparent memory tool handling.-- Uses a buffer-then-decide approach:- 1. Buffer events until first output item arrives- 2. If first output is a memory tool → suppress entire response,- execute tools silently, send continuation upstream- 3. If first output is non-memory → flush buffer, stream normally- 4. Continuation response events are relayed to Codex seamlessly-- This prevents orphaned response.created events from confusing Codex.- """- from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES-- # Unit 3: surface response.completed observation- # to the outer scope so the termination-cause- # classifier can prefer ``response_completed``- # over ``upstream_disconnect``.- nonlocal response_completed_seen- nonlocal upstream_relay_error-- memory_enabled = bool(self.memory_handler and memory_user_id)-- # Per-response state (reset after each response.completed)- event_buffer: list[str] = []- decided = False- suppress_response = False- pending_fcs: list[dict[str, Any]] = []- resp_id: str | None = None-- def _reset() -> None:- nonlocal decided, suppress_response, resp_id- event_buffer.clear()- decided = False- suppress_response = False- pending_fcs.clear()- resp_id = None-- # The retry-loop variable is safe to close over here:- # ``_upstream_to_client`` is defined and awaited within- # a single iteration and never escapes.- _first_event_started_at = _upstream_first_event_started # noqa: B023-- try:- async for msg in upstream:- if (- _first_event_started_at is not None- and "upstream_first_event" not in stage_timer- ):- stage_timer.record(- "upstream_first_event",- (time.perf_counter() - _first_event_started_at)- * 1000.0,- )- if isinstance(msg, bytes):- await websocket.send_bytes(msg)- continue- msg_str = msg if isinstance(msg, str) else str(msg)-- if not memory_enabled:- await websocket.send_text(msg_str)- continue-- # Parse event- try:- event = json.loads(msg_str)- except (json.JSONDecodeError, TypeError):- await websocket.send_text(msg_str)- continue-- event_type = event.get("type", "")-- # --- Phase 1: Buffer until first output item ---- if not decided:- event_buffer.append(msg_str)-- if event_type == "response.output_item.added":- item = event.get("item", {})- if (- item.get("type") == "function_call"- and item.get("name") in MEMORY_TOOL_NAMES- ):- # Memory tool first → suppress entire response- suppress_response = True- decided = True- event_buffer.clear()- logger.info(- f"[{request_id}] WS Memory: Detected "- f"{item.get('name')} — suppressing response"- )- else:- # Non-memory first → flush buffer, pass through- decided = True- for buf in event_buffer:- await websocket.send_text(buf)- event_buffer.clear()-- elif event_type == "response.completed":- # No output items at all — flush- decided = True- for buf in event_buffer:- await websocket.send_text(buf)- event_buffer.clear()- _reset()- response_completed_seen = True-- continue-- # --- Phase 2a: Suppress mode (memory response) ---- if suppress_response:- if event_type == "response.output_item.done":- item = event.get("item", {})- if (- item.get("type") == "function_call"- and item.get("name") in MEMORY_TOOL_NAMES- ):- pending_fcs.append(item)-- elif event_type == "response.completed":- response_completed_seen = True- resp = event.get("response", {})- resp_id = resp.get("id")-- if pending_fcs:- logger.info(- f"[{request_id}] WS Memory: Executing "- f"{len(pending_fcs)} tool(s) transparently"- )-- # Execute memory tool calls- tool_outputs: list[dict[str, Any]] = []- for fc in pending_fcs:- call_id = fc.get("call_id", fc.get("id", ""))- fc_name = fc.get("name", "")- args_str = fc.get("arguments", "{}")- try:- fc_args = json.loads(args_str)- except json.JSONDecodeError:- fc_args = {}-- await self.memory_handler._ensure_initialized()- if self.memory_handler._backend:- result = await self.memory_handler._execute_memory_tool(- fc_name,- fc_args,- memory_user_id,- "openai",- )- else:- result = json.dumps(- {"error": "backend not ready"}- )-- tool_outputs.append(- {- "type": "function_call_output",- "call_id": call_id,- "output": result,- }- )- logger.info(- f"[{request_id}] WS Memory: Executed "- f"{fc_name} for user {memory_user_id}"- )-- # Send continuation upstream- cont: dict[str, Any] = {- "type": "response.create",- "response": {"input": tool_outputs},- }- if resp_id:- cont["response"]["previous_response_id"] = (- resp_id- )- await upstream.send(json.dumps(cont))- logger.info(- f"[{request_id}] WS Memory: Sent continuation "- f"with {len(tool_outputs)} result(s)"- )-- _reset()- # All events suppressed in this mode- continue-- # --- Phase 2b: Pass-through mode ---- await websocket.send_text(msg_str)-- except asyncio.CancelledError:- raise- except Exception as relay_err:- if "WebSocketDisconnect" not in type(relay_err).__name__:- # Capture for the outer classifier- # so ``upstream_error`` can be- # distinguished from a clean- # upstream disconnect.- upstream_relay_error = relay_err- logger.debug(- f"[{request_id}] WS upstream→client relay ended: {relay_err}"- )- finally:- with contextlib.suppress(Exception):- await websocket.close()-- # --- Unit 3: deterministic relay-task cancellation ---- # Spawn each half as a named task so we can:- # (a) attach them to the session registry for- # ``/debug/ws-sessions``,- # (b) cancel the survivor explicitly when the- # first one exits, and- # (c) classify the termination cause for the- # duration histogram.- client_task = asyncio.create_task(- _client_to_upstream(),- name=f"codex-ws-c2u-{session_id}",- )- upstream_task = asyncio.create_task(- _upstream_to_client(),- name=f"codex-ws-u2c-{session_id}",- )- relay_tasks = [client_task, upstream_task]- if ws_sessions is not None:- ws_sessions.attach_tasks(session_id, relay_tasks)- metrics_for_tasks = getattr(self, "metrics", None)- if metrics_for_tasks is not None and hasattr(- metrics_for_tasks, "inc_active_relay_tasks"- ):- try:- metrics_for_tasks.inc_active_relay_tasks(len(relay_tasks))- except Exception: # pragma: no cover - defensive- pass-- try:- done, pending = await asyncio.wait(- {client_task, upstream_task},- return_when=asyncio.FIRST_COMPLETED,- )- # Cancel the survivor so we don't leak the- # partner task. Suppress the CancelledError- # we just raised ourselves — any *other*- # exception from the cancelled task is- # already logged inside its own try/except.- for t in pending:- t.cancel()- if pending:- with contextlib.suppress(asyncio.CancelledError):- await asyncio.gather(*pending, return_exceptions=True)-- # Classify termination cause from whichever- # task completed first. ``CancelledError``- # can show up on the "done" side if the- # handler itself was cancelled from outside- # (e.g. server shutdown).- for t in done:- exc = None- # Cancelled tasks raise CancelledError from- # .exception(); surface it explicitly so the- # downstream ``isinstance(exc, CancelledError)``- # branches actually run. For any other- # unexpected state (``InvalidStateError`` if- # the task somehow isn't done — shouldn't- # happen post-gather but defensive), we- # suppress and leave ``exc`` as ``None``.- if t.cancelled():- exc = asyncio.CancelledError()- else:- with contextlib.suppress(asyncio.InvalidStateError):- exc = t.exception()- task_name = t.get_name() or ""- if t is client_task:- if client_relay_error is not None:- termination_cause = "client_error"- elif exc is None:- termination_cause = "client_disconnect"- elif isinstance(exc, asyncio.CancelledError):- termination_cause = "client_disconnect"- else:- # Distinguish legitimate client- # disconnect exceptions from- # real errors: WebSocketDisconnect- # is a normal client exit.- if "WebSocketDisconnect" in type(exc).__name__:- termination_cause = "client_disconnect"- else:- termination_cause = "client_error"- elif t is upstream_task:- if upstream_relay_error is not None:- termination_cause = "upstream_error"- logger.debug(- f"[{request_id}] WS relay {task_name} "- f"raised: {upstream_relay_error!r}"- )- elif exc is None:- termination_cause = (- "response_completed"- if response_completed_seen- else "upstream_disconnect"- )- elif isinstance(exc, asyncio.CancelledError):- termination_cause = "upstream_disconnect"- else:- termination_cause = "upstream_error"- logger.debug(- f"[{request_id}] WS relay {task_name} raised: {exc!r}"- )- finally:- # In case anything above raised before the- # cancel-and-await loop ran.- for t in relay_tasks:- if not t.done():- t.cancel()- with contextlib.suppress(asyncio.CancelledError):- await asyncio.gather(*relay_tasks, return_exceptions=True)-- logger.info(- f"[{request_id}] WS /v1/responses completed "- f"(tokens_saved={tokens_saved}, cause={termination_cause})"- )- break- except Exception as ws_err:- if ws_connected:- # WS was established but broke mid-stream — re-raise- raise-- ws_last_err = ws_err- if ws_attempt >= ws_connect_attempts - 1:- break-- delay_with_jitter = jitter_delay_ms(- self.config.retry_base_delay_ms,- self.config.retry_max_delay_ms,- ws_attempt,- )- logger.warning(- f"[{request_id}] WS upstream connect failed "- f"(attempt {ws_attempt + 1}/{ws_connect_attempts}): {ws_err}; "- f"retrying in {delay_with_jitter:.0f}ms"- )- await asyncio.sleep(delay_with_jitter / 1000)-- if not ws_connected:- # WS upgrade failed (HTTP 500 from OpenAI is common).- # Fall back to HTTP POST streaming and relay SSE events- # back over the client WebSocket transparently.- ws_err = ws_last_err or RuntimeError("unknown websocket connect failure")- _ws_detail = str(ws_err)- if hasattr(ws_err, "response"):- resp_body = getattr(getattr(ws_err, "response", None), "body", b"")- if resp_body:- _ws_detail += f" | {resp_body[:300].decode('utf-8', errors='replace')}"- logger.warning(- f"[{request_id}] WS upstream failed ({_ws_detail}), "- f"falling back to HTTP POST streaming"- )- await self._ws_http_fallback(- websocket, body, first_msg_raw, upstream_headers, request_id- )-- # Record metrics- if tokens_saved > 0:- model_name = body.get("model", "unknown") if isinstance(body, dict) else "unknown"- await self.metrics.record_request(- provider="openai",- model=model_name,- input_tokens=0,- output_tokens=0,- tokens_saved=tokens_saved,- latency_ms=0,- )-- except Exception as e:- if "WebSocketDisconnect" in type(e).__name__:- # Unit 3: client dropped the socket before or during- # relay. The registry classifier may already have set- # ``client_disconnect`` via the relay task exit path;- # preserve that, otherwise set it here.- if termination_cause == "unknown":- termination_cause = "client_disconnect"- else:- # Extract response body from websockets InvalidStatus for better debugging- error_detail = str(e)- if hasattr(e, "response"):- try:- resp = e.response- body_bytes = getattr(resp, "body", None) or b""- if body_bytes:- error_detail += (- f" | body: {body_bytes[:500].decode('utf-8', errors='replace')}"- )- except Exception:- pass- logger.error(f"[{request_id}] WS proxy error: {error_detail}")- if termination_cause == "unknown":- termination_cause = "client_error"- with contextlib.suppress(Exception):- await websocket.close(code=1011, reason=str(e)[:120])- finally:- # Unit 2: emit structured per-session stage timings.- stage_timer.record(- "total_session",- (time.perf_counter() - session_started_at) * 1000.0,- )- # Unit 3: deregister the session before (or independently- # of) the stage-timings log so a failure there cannot leak- # the registry entry. ``deregister`` is idempotent, so a- # session that never registered is a no-op.- if ws_sessions is not None and session_handle is not None:- # Use deregister_and_count so the handle pop and the- # relay-task count are read atomically inside the- # registry. Capturing ``len(session_handle.relay_tasks)``- # separately before ``deregister`` would risk drift if- # the registry's bookkeeping ever changes.- _deregistered, released_tasks = ws_sessions.deregister_and_count(- session_id, cause=termination_cause- )- session_duration_ms = (time.perf_counter() - session_started_at) * 1000.0- metrics_for_close = getattr(self, "metrics", None)- if metrics_for_close is not None:- with contextlib.suppress(Exception):- if hasattr(metrics_for_close, "dec_active_ws_sessions"):- metrics_for_close.dec_active_ws_sessions()- if released_tasks and hasattr(metrics_for_close, "dec_active_relay_tasks"):- metrics_for_close.dec_active_relay_tasks(released_tasks)- if hasattr(metrics_for_close, "record_ws_session_duration"):- metrics_for_close.record_ws_session_duration(- session_duration_ms, termination_cause- )- await emit_stage_timings_log(- path="openai_responses_ws",- request_id=request_id,- session_id=session_id,- stage_timer=stage_timer,- expected_stages=(- "accept",- "first_client_frame",- "upstream_connect",- "upstream_first_event",- "memory_context",- "compression",- "total_session",- ),- metrics=getattr(self, "metrics", None),- )-- async def _ws_http_fallback(- self,- websocket: WebSocket,- body: dict[str, Any],- first_msg_raw: str,- upstream_headers: dict[str, str],- request_id: str,- ) -> None:- """Fall back to HTTP POST streaming when upstream WS fails.-- Converts the WS ``response.create`` message to an HTTP POST to- ``/v1/responses?stream=true``, reads SSE events, and relays each- ``data:`` line as a WS text message to the client. This makes- Codex work immediately instead of exhausting its WS retry budget.- """- # Route to correct endpoint based on auth mode- _lower = {k.lower() for k in upstream_headers}- if "chatgpt-account-id" in _lower:- http_url = "https://chatgpt.com/backend-api/codex/responses"- else:- http_url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")-- # Build HTTP body from the WS response.create payload.- # WS messages use {"type": "response.create", "response": {...}} wrapper.- # The HTTP POST endpoint expects the inner response object directly.- http_body: dict[str, Any]- try:- parsed = json.loads(first_msg_raw) if isinstance(first_msg_raw, str) else body- except (json.JSONDecodeError, TypeError):- parsed = body-- # Normalize WebSocket response.create payload into the HTTP request body.- # Codex may send either:- # 1. {"type":"response.create","response":{...}}- # 2. {"type":"response.create", ...response fields...}- if isinstance(parsed, dict) and isinstance(parsed.get("response"), dict):- http_body = dict(parsed["response"])- elif isinstance(parsed, dict):- http_body = dict(parsed)- if http_body.get("type") == "response.create":- http_body.pop("type", None)- else:- http_body = body if isinstance(body, dict) else {}-- # Some clients include response-ish metadata that the HTTP endpoint rejects.- if http_body.get("type") in {"response.create", "response"}:- http_body.pop("type", None)-- # Ensure streaming is enabled so we get SSE events- http_body["stream"] = True-- # Build HTTP headers from the upstream headers (already stripped of WS- # hop-by-hop headers by the caller).- http_headers = dict(upstream_headers)- http_headers["content-type"] = "application/json"-- logger.debug(f"[{request_id}] WS→HTTP fallback POST to {http_url}")-- try:- retry_attempts = max(1, getattr(self.config, "retry_max_attempts", 3))- for http_attempt in range(retry_attempts):- try:- async with self.http_client.stream(- "POST",- http_url,- headers=http_headers,- json=http_body,- timeout=120.0,- ) as response:- if response.status_code != 200:- error_body = b""- async for chunk in response.aiter_bytes():- error_body += chunk- if len(error_body) > 2000:- break- error_text = error_body.decode("utf-8", errors="replace")- logger.error(- f"[{request_id}] WS→HTTP fallback got {response.status_code}: "- f"{error_text[:500]}"- )- # Send error as WS message so client sees it- error_event = {- "type": "error",- "error": {- "type": "server_error",- "message": f"Upstream returned {response.status_code}",- },- }- await websocket.send_text(json.dumps(error_event))- return-- # Relay SSE events as WS text messages- buffer = ""- async for chunk in response.aiter_text():- buffer += chunk- while "\n" in buffer:- line, buffer = buffer.split("\n", 1)- line = line.strip()- if not line:- continue- if line.startswith("data: "):- data = line[6:]- if data == "[DONE]":- continue- try:- await websocket.send_text(data)- except Exception:- return- elif line.startswith("event: "):- # SSE event type — skip, the data line contains the type- continue-- # Flush any remaining data in buffer- for line in buffer.strip().splitlines():- line = line.strip()- if line.startswith("data: ") and line[6:] != "[DONE]":- with contextlib.suppress(Exception):- await websocket.send_text(line[6:])- return- except (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) as http_err:- if http_attempt >= retry_attempts - 1:- raise-- delay_with_jitter = jitter_delay_ms(- self.config.retry_base_delay_ms,- self.config.retry_max_delay_ms,- http_attempt,- )- logger.warning(- f"[{request_id}] WS→HTTP fallback connect failed "- f"(attempt {http_attempt + 1}/{retry_attempts}): {http_err}; "- f"retrying in {delay_with_jitter:.0f}ms"- )- await asyncio.sleep(delay_with_jitter / 1000)-- except Exception as http_err:- logger.error(f"[{request_id}] WS→HTTP fallback failed: {http_err}")- error_event = {- "type": "error",- "error": {- "type": "server_error",- "message": f"HTTP fallback failed: {http_err!s}"[:200],- },- }- with contextlib.suppress(Exception):- await websocket.send_text(json.dumps(error_event))- finally:- with contextlib.suppress(Exception):- await websocket.close()-- async def handle_compress(self, request: Request) -> JSONResponse:- """Compress messages without calling an LLM.-- POST /v1/compress- Body: {"messages": [...], "model": "...", "config": {}}- Returns compressed messages + metrics.- """- from fastapi.responses import JSONResponse-- from headroom.proxy.helpers import _read_request_json-- # Check bypass header- if request.headers.get("x-headroom-bypass", "").lower() == "true":- try:- body = await _read_request_json(request)- except (json.JSONDecodeError, ValueError) as e:- return JSONResponse(- status_code=400,- content={"error": f"Invalid request body: {e!s}"},- )- messages = body.get("messages", [])- return JSONResponse(- {- "messages": messages,- "tokens_before": 0,- "tokens_after": 0,- "tokens_saved": 0,- "compression_ratio": 1.0,- "transforms_applied": [],- "ccr_hashes": [],- }- )-- try:- body = await _read_request_json(request)- except Exception:- return JSONResponse(- status_code=400,- content={- "error": {- "type": "invalid_request",- "message": "Invalid JSON in request body.",- }- },- )-- messages = body.get("messages")- model = body.get("model")-- if messages is None:- return JSONResponse(- status_code=400,- content={- "error": {- "type": "invalid_request",- "message": "Missing required field: messages",- }- },- )-- if model is None:- return JSONResponse(- status_code=400,- content={- "error": {- "type": "invalid_request",- "message": "Missing required field: model",- }- },- )-- if not messages:- return JSONResponse(- {- "messages": [],- "tokens_before": 0,- "tokens_after": 0,- "tokens_saved": 0,- "compression_ratio": 1.0,- "transforms_applied": [],- "ccr_hashes": [],- }- )-- try:- # Use OpenAI pipeline (messages are in OpenAI format from TS SDK)- # Allow optional token_budget to override model's context limit- # (used by OpenClaw compact() and other callers that need tighter budgets)- token_budget = body.get("token_budget")- context_limit = (- token_budget- if token_budget and isinstance(token_budget, int)- else self.openai_provider.get_context_limit(model)- )- # Extract CompressConfig options from request body- compress_config = body.get("config", {})- compress_user_messages = compress_config.get("compress_user_messages", False)- target_ratio = compress_config.get("target_ratio")- protect_recent = compress_config.get("protect_recent")- protect_analysis_context = compress_config.get("protect_analysis_context")-- pipeline_kwargs: dict = {"model_limit": context_limit}- if compress_user_messages:- pipeline_kwargs["compress_user_messages"] = True- if target_ratio is not None:- pipeline_kwargs["target_ratio"] = float(target_ratio)- if protect_recent is not None:- pipeline_kwargs["protect_recent"] = int(protect_recent)- if protect_analysis_context is not None:- pipeline_kwargs["protect_analysis_context"] = bool(protect_analysis_context)-- result = self.openai_pipeline.apply(- messages=messages,- model=model,- **pipeline_kwargs,- )-- return JSONResponse(- {- "messages": result.messages,- "tokens_before": result.tokens_before,- "tokens_after": result.tokens_after,- "tokens_saved": result.tokens_before - result.tokens_after,- "compression_ratio": (- result.tokens_after / result.tokens_before- if result.tokens_before > 0- else 1.0- ),- "transforms_applied": result.transforms_applied,- "transforms_summary": result.transforms_summary,- "ccr_hashes": result.markers_inserted,- }- )- except Exception as e:- logger.exception("Compression failed: %s", e)- return JSONResponse(- status_code=503,- content={- "error": {- "type": "compression_error",- "message": str(e),- }- },- )-- async def handle_passthrough(- self,- request: Request,- base_url: str,- endpoint_name: str | None = None,- provider: str | None = None,- ) -> Response:- """Pass through request unchanged.-- Args:- request: The incoming request- base_url: The upstream API base URL- endpoint_name: Optional name for stats tracking (e.g., "models", "embeddings")- provider: Optional provider name for stats (e.g., "openai", "anthropic", "gemini")- """- from fastapi.responses import Response-- start_time = time.time()- path = request.url.path- url = build_copilot_upstream_url(base_url, path)-- # Preserve query string parameters- if request.url.query:- url = f"{url}?{request.url.query}"-- headers = dict(request.headers.items())- headers.pop("host", None)- headers.pop("accept-encoding", None)-- body = await request.body()-- headers = await apply_copilot_api_auth(headers, url=url)- response = await self.http_client.request( # type: ignore[union-attr]- method=request.method,- url=url,- headers=headers,- content=body,- )-- # Remove compression headers since httpx already decompressed the response- response_headers = dict(response.headers)- response_headers.pop("content-encoding", None)- response_headers.pop("content-length", None) # Length changed after decompression-- # Track stats for passthrough requests- if endpoint_name and provider:- latency_ms = (time.time() - start_time) * 1000- await self.metrics.record_request(- provider=provider,- model=f"passthrough:{endpoint_name}",- input_tokens=0,- output_tokens=0,- tokens_saved=0,- latency_ms=latency_ms,- cached=False,- )-- return Response(- content=response.content,- status_code=response.status_code,- headers=response_headers,- )-- async def handle_databricks_invocations(- self,- request: Request,- model: str,- ) -> Response | StreamingResponse:- """Handle Databricks native /serving-endpoints/{model}/invocations endpoint.-- This enables using the Databricks CLI directly with Headroom:- databricks serving-endpoints query <model> --profile HEADROOM --json '{"messages": [...]}'-- The request/response format is identical to OpenAI chat completions,- so we inject the model from the path and delegate to handle_openai_chat.- """- from fastapi.responses import JSONResponse-- from headroom.proxy.helpers import _read_request_json-- request_id = await self._next_request_id()-- try:- body = await _read_request_json(request)- except Exception as e:- logger.error(f"[{request_id}] Failed to parse Databricks request body: {e}")- return JSONResponse(- status_code=400,- content={- "error": {- "message": f"Invalid JSON: {e}",- "type": "invalid_request_error",- }- },- )-- # Inject model from path into body (Databricks CLI passes model in URL, not body)- body["model"] = model-- logger.info(f"[{request_id}] Databricks invocation: model={model}")-- # Create a new request with the modified body- # We reuse the OpenAI chat handler since the format is identical- from starlette.requests import Request as StarletteRequest-- # Build new scope with the body already parsed- scope = dict(request.scope)-- # Create a simple receive function that returns our modified body- body_bytes = json.dumps(body).encode()-- async def receive():- return {"type": "http.request", "body": body_bytes}-- modified_request = StarletteRequest(scope, receive)-- # Delegate to the OpenAI chat handler (same format)- return await self.handle_openai_chat(modified_request)+"""OpenAI handler mixin for HeadroomProxy.++Contains all OpenAI Chat Completions, Responses API, and passthrough handlers.+"""++from __future__ import annotations++import asyncio+import base64+import contextlib+import copy+import json+import logging+import os+import time+import uuid+from datetime import datetime+from typing import TYPE_CHECKING, Any++from headroom.proxy.helpers import jitter_delay_ms+from headroom.proxy.stage_timer import StageTimer, emit_stage_timings_log+from headroom.proxy.ws_session_registry import (+ TerminationCause,+ WebSocketSessionRegistry,+ WSSessionHandle,+)++if TYPE_CHECKING:+ from fastapi import Request, WebSocket+ from fastapi.responses import JSONResponse, Response, StreamingResponse++import httpx++from headroom.copilot_auth import apply_copilot_api_auth, build_copilot_upstream_url+from headroom.pipeline import PipelineStage, summarize_routing_markers++logger = logging.getLogger("headroom.proxy")+++# Interactive Responses turns are latency-sensitive. Fail open quickly rather+# than holding the session hostage on memory lookup.+RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS = 2.0++# Cap the wait for the first client frame after the WS handshake completes.+# A zombie or malicious client that accepts the upgrade but never sends the+# first response.create frame would otherwise hold a slot indefinitely and+# starve the session registry. 60 s is generous for real clients (Codex+# typically sends the first frame within a few hundred milliseconds of the+# accept) but short enough to bound the damage from a hung peer.+WS_FIRST_FRAME_TIMEOUT_SECONDS = 60.0+++def _decode_openai_bearer_payload(headers: dict[str, str]) -> dict[str, Any] | None:+ """Best-effort decode of an OpenAI OAuth bearer token payload.++ OpenClaw's Codex OAuth flow may forward only the bearer token after the+ provider base URL is overridden. In that case the explicit+ ``ChatGPT-Account-ID`` header can be missing even though the JWT still+ carries the account id we need to route to the ChatGPT Codex backend.+ """+ auth = headers.get("authorization") or headers.get("Authorization")+ if not auth:+ return None++ scheme, _, token = auth.partition(" ")+ if scheme.lower() != "bearer" or token.count(".") < 2:+ return None++ payload = token.split(".", 2)[1]+ payload += "=" * (-len(payload) % 4)+ # Intentionally no signature verification here: this is only a best-effort+ # routing hint extractor. Upstream still performs the actual auth/authz checks.+ try:+ decoded = base64.urlsafe_b64decode(payload.encode("ascii"))+ data = json.loads(decoded.decode("utf-8"))+ except (ValueError, UnicodeDecodeError):+ return None++ return data if isinstance(data, dict) else None+++def _resolve_codex_routing_headers(headers: dict[str, str]) -> tuple[dict[str, str], bool]:+ """Resolve ChatGPT Codex routing hints from explicit headers or OAuth JWT."""+ resolved = dict(headers)+ lower_lookup = {k.lower(): k for k in resolved}++ if "chatgpt-account-id" in lower_lookup:+ return resolved, True++ payload = _decode_openai_bearer_payload(resolved)+ auth_claims = payload.get("https://api.openai.com/auth") if isinstance(payload, dict) else None+ account_id = auth_claims.get("chatgpt_account_id") if isinstance(auth_claims, dict) else None+ if isinstance(account_id, str) and account_id.strip():+ resolved["ChatGPT-Account-ID"] = account_id.strip()+ return resolved, True++ return resolved, False+++class OpenAIHandlerMixin:+ """Mixin providing OpenAI API handler methods for HeadroomProxy."""++ @staticmethod+ def _strict_previous_turn_frozen_count(+ messages: list[dict[str, Any]],+ base_frozen_count: int,+ ) -> int:+ """Freeze all prior turns in cache mode; only final user turn is mutable."""+ if not messages:+ return base_frozen_count+ final_idx = len(messages) - 1+ if messages[final_idx].get("role") == "user":+ return max(base_frozen_count, final_idx)+ return len(messages)++ @staticmethod+ def _restore_frozen_prefix(+ original_messages: list[dict[str, Any]],+ candidate_messages: list[dict[str, Any]],+ *,+ frozen_message_count: int,+ ) -> tuple[list[dict[str, Any]], int]:+ """Force frozen prefix bytes to match original request exactly."""+ if frozen_message_count <= 0 or not original_messages:+ return candidate_messages, 0++ frozen = min(frozen_message_count, len(original_messages))+ restored = list(candidate_messages)++ if len(restored) < frozen:+ return list(original_messages[:frozen]) + restored, frozen++ changed = 0+ for idx in range(frozen):+ if restored[idx] != original_messages[idx]:+ restored[idx] = original_messages[idx]+ changed += 1+ return restored, changed++ async def handle_openai_chat(+ self,+ request: Request,+ ) -> Response | StreamingResponse:+ """Handle OpenAI /v1/chat/completions endpoint."""+ if not hasattr(self, "pipeline_extensions"):+ from headroom.pipeline import PipelineExtensionManager++ self.pipeline_extensions = PipelineExtensionManager(discover=False)++ from fastapi import HTTPException+ from fastapi.responses import JSONResponse, Response++ from headroom.ccr import CCRToolInjector+ from headroom.proxy.helpers import (+ COMPRESSION_TIMEOUT_SECONDS,+ MAX_MESSAGE_ARRAY_LENGTH,+ MAX_REQUEST_BODY_SIZE,+ _read_request_json,+ )+ from headroom.proxy.modes import is_cache_mode, is_token_mode+ from headroom.tokenizers import get_tokenizer+ from headroom.utils import extract_user_query++ start_time = time.time()+ request_id = await self._next_request_id()++ # Check request body size+ content_length = request.headers.get("content-length")+ if content_length and int(content_length) > MAX_REQUEST_BODY_SIZE:+ return JSONResponse(+ status_code=413,+ content={+ "error": {+ "message": f"Request body too large. Maximum size is {MAX_REQUEST_BODY_SIZE // (1024 * 1024)}MB",+ "type": "invalid_request_error",+ "code": "request_too_large",+ }+ },+ )++ # Parse request+ try:+ body = await _read_request_json(request)+ except (json.JSONDecodeError, ValueError) as e:+ return JSONResponse(+ status_code=400,+ content={+ "error": {+ "message": f"Invalid request body: {e!s}",+ "type": "invalid_request_error",+ "code": "invalid_json",+ }+ },+ )+ model = body.get("model", "unknown")+ messages = body.get("messages", [])+ original_client_messages = copy.deepcopy(messages)+ input_event = self.pipeline_extensions.emit(+ PipelineStage.INPUT_RECEIVED,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=messages,+ tools=body.get("tools"),+ metadata={"path": "/v1/chat/completions", "stream": body.get("stream", False)},+ )+ if input_event.messages is not None:+ messages = input_event.messages+ original_client_messages = copy.deepcopy(messages)+ if input_event.tools is not None:+ body["tools"] = input_event.tools++ # Validate message array size+ if len(messages) > MAX_MESSAGE_ARRAY_LENGTH:+ return JSONResponse(+ status_code=400,+ content={+ "error": {+ "message": f"Message array too large ({len(messages)} messages). "+ f"Maximum is {MAX_MESSAGE_ARRAY_LENGTH}.",+ "type": "invalid_request_error",+ "code": "invalid_request",+ }+ },+ )++ stream = body.get("stream", False)++ # Bypass: skip ALL compression for explicit opt-out+ _bypass = (+ request.headers.get("x-headroom-bypass", "").lower() == "true"+ or request.headers.get("x-headroom-mode", "").lower() == "passthrough"+ )+ if _bypass:+ logger.info(f"[{request_id}] Bypass: skipping compression (header)")++ # Image compression: tile alignment + ML-based technique routing+ if self.config.image_optimize and messages and not _bypass:+ from headroom.proxy.helpers import _get_image_compressor++ compressor = _get_image_compressor()+ if compressor and compressor.has_images(messages):+ messages = compressor.compress(messages, provider="openai")+ if compressor.last_result:+ logger.info(+ f"[{request_id}] Image: {compressor.last_result.technique.value} "+ f"({compressor.last_result.savings_percent:.0f}% saved, "+ f"{compressor.last_result.original_tokens} → "+ f"{compressor.last_result.compressed_tokens} tokens)"+ )++ headers = dict(request.headers.items())+ headers.pop("host", None)+ headers.pop("content-length", None)+ # Strip accept-encoding so httpx negotiates its own encoding.+ # Cloudflare Workers forward "br, zstd" which OpenAI may honor;+ # if httpx lacks brotli support the response body is undecipherable → 502.+ headers.pop("accept-encoding", None)+ tags = self._extract_tags(headers)++ # Memory: Get user ID when memory is enabled+ memory_user_id: str | None = None+ if self.memory_handler:+ memory_user_id = headers.get(+ "x-headroom-user-id",+ os.environ.get("USER", os.environ.get("USERNAME", "default")),+ )++ # Rate limiting+ if self.rate_limiter:+ rate_key = headers.get("authorization", "default")[:20]+ allowed, wait_seconds = await self.rate_limiter.check_request(rate_key)+ if not allowed:+ await self.metrics.record_rate_limited(provider="openai")+ raise HTTPException(+ status_code=429,+ detail=f"Rate limited. Retry after {wait_seconds:.1f}s",+ )++ # Check cache+ if self.cache and not stream:+ cached = await self.cache.get(messages, model)+ if cached:+ self.pipeline_extensions.emit(+ PipelineStage.INPUT_CACHED,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=messages,+ metadata={"cache_hit": True, "path": "/v1/chat/completions"},+ )+ await self.metrics.record_request(+ provider="openai",+ model=model,+ input_tokens=0,+ output_tokens=0,+ tokens_saved=0, # Savings already counted when response was cached+ latency_ms=(time.time() - start_time) * 1000,+ cached=True,+ )++ # Remove compression headers from cached response+ response_headers = dict(cached.response_headers)+ response_headers.pop("content-encoding", None)+ response_headers.pop("content-length", None)++ return Response(content=cached.response_body, headers=response_headers)++ # Token counting+ tokenizer = get_tokenizer(model)+ original_tokens = tokenizer.count_messages(messages)++ # Hook: pre_compress+ _hook_biases = None+ if self.config.hooks:+ from headroom.hooks import CompressContext++ _hook_ctx = CompressContext(model=model, provider="openai")+ try:+ messages = self.config.hooks.pre_compress(messages, _hook_ctx)+ _hook_biases = self.config.hooks.compute_biases(messages, _hook_ctx)+ except Exception as e:+ logger.debug(f"[{request_id}] Hook error: {e}")++ # Optimization+ transforms_applied = []+ pipeline_timing: dict[str, float] = {}+ waste_signals_dict: dict[str, int] | None = None+ optimized_messages = messages+ optimized_tokens = original_tokens++ # Get prefix cache tracker for this session+ openai_session_id = self.session_tracker_store.compute_session_id(request, model, messages)+ openai_prefix_tracker = self.session_tracker_store.get_or_create(+ openai_session_id, "openai"+ )+ openai_frozen_count = openai_prefix_tracker.get_frozen_message_count()+ if is_cache_mode(self.config.mode):+ openai_frozen_count = self._strict_previous_turn_frozen_count(+ original_client_messages,+ openai_frozen_count,+ )++ _compression_failed = False+ original_messages = messages # Preserve for 400-retry fallback+ _license_ok = self.usage_reporter.should_compress if self.usage_reporter else True+ if self.config.optimize and messages and not _bypass and _license_ok:+ try:+ context_limit = self.openai_provider.get_context_limit(model)++ if is_token_mode(self.config.mode):+ comp_cache = self._get_compression_cache(openai_session_id)++ # Zone 1: Swap cached compressed versions+ working_messages = comp_cache.apply_cached(messages)++ # Re-freeze boundary+ openai_frozen_count = comp_cache.compute_frozen_count(messages)++ result = await asyncio.wait_for(+ asyncio.to_thread(+ lambda: self.openai_pipeline.apply(+ messages=working_messages,+ model=model,+ model_limit=context_limit,+ context=extract_user_query(working_messages),+ frozen_message_count=openai_frozen_count,+ biases=_hook_biases,+ )+ ),+ timeout=COMPRESSION_TIMEOUT_SECONDS,+ )++ if result.messages != working_messages:+ comp_cache.update_from_result(messages, result.messages)++ # Always use pipeline result in token mode+ optimized_messages = result.messages+ transforms_applied = result.transforms_applied+ pipeline_timing = result.timing+ # Keep original_tokens as the REAL original (pre-Zone-1-swap)+ # so tokens_saved captures both Zone 1 + Zone 2 savings.+ optimized_tokens = result.tokens_after+ else:+ result = await asyncio.wait_for(+ asyncio.to_thread(+ lambda: self.openai_pipeline.apply(+ messages=messages,+ model=model,+ model_limit=context_limit,+ context=extract_user_query(messages),+ frozen_message_count=openai_frozen_count,+ biases=_hook_biases,+ )+ ),+ timeout=COMPRESSION_TIMEOUT_SECONDS,+ )++ if result.messages != messages:+ optimized_messages = result.messages+ transforms_applied = result.transforms_applied+ pipeline_timing = result.timing+ original_tokens = result.tokens_before+ optimized_tokens = result.tokens_after++ if result.waste_signals:+ waste_signals_dict = result.waste_signals.to_dict()+ except Exception as e:+ logger.warning(f"Optimization failed: {e}")+ # Flag compression failure for observability+ _compression_failed = True++ # Guard: if "optimization" inflated tokens, revert to originals+ if optimized_tokens > original_tokens:+ logger.warning(+ f"[{request_id}] Optimization inflated tokens "+ f"({original_tokens} -> {optimized_tokens}), reverting to original messages"+ )+ optimized_messages = original_messages+ optimized_tokens = original_tokens+ transforms_applied = []++ tokens_saved = original_tokens - optimized_tokens+ optimization_latency = (time.time() - start_time) * 1000++ routing_markers = summarize_routing_markers(transforms_applied)+ if routing_markers:+ routed_event = self.pipeline_extensions.emit(+ PipelineStage.INPUT_ROUTED,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=optimized_messages,+ metadata={+ "routing_markers": routing_markers,+ "transforms_applied": transforms_applied,+ },+ )+ if routed_event.messages is not None:+ optimized_messages = routed_event.messages+ optimized_tokens = tokenizer.count_messages(optimized_messages)+ tokens_saved = original_tokens - optimized_tokens++ compressed_event = self.pipeline_extensions.emit(+ PipelineStage.INPUT_COMPRESSED,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=optimized_messages,+ metadata={+ "tokens_before": original_tokens,+ "tokens_after": optimized_tokens,+ "transforms_applied": transforms_applied,+ },+ )+ if compressed_event.messages is not None:+ optimized_messages = compressed_event.messages+ optimized_tokens = tokenizer.count_messages(optimized_messages)+ tokens_saved = original_tokens - optimized_tokens++ # Hook: post_compress+ if self.config.hooks and tokens_saved > 0:+ from headroom.hooks import CompressEvent++ try:+ self.config.hooks.post_compress(+ CompressEvent(+ tokens_before=original_tokens,+ tokens_after=optimized_tokens,+ tokens_saved=tokens_saved,+ compression_ratio=tokens_saved / original_tokens+ if original_tokens > 0+ else 0,+ transforms_applied=transforms_applied,+ model=model,+ provider="openai",+ )+ )+ except Exception as e:+ logger.debug(f"[{request_id}] post_compress hook error: {e}")++ # CCR Tool Injection: Inject retrieval tool if compression occurred+ tools = body.get("tools")+ _original_tools = tools # Preserve for diagnostic / future retry+ if (+ self.config.ccr_inject_tool or self.config.ccr_inject_system_instructions+ ) and not _bypass:+ injector = CCRToolInjector(+ provider="openai",+ inject_tool=self.config.ccr_inject_tool,+ inject_system_instructions=self.config.ccr_inject_system_instructions,+ )+ optimized_messages, tools, was_injected = injector.process_request(+ optimized_messages, tools+ )++ if injector.has_compressed_content:+ if was_injected:+ logger.debug(+ f"[{request_id}] CCR: Injected retrieval tool for hashes: {injector.detected_hashes}"+ )+ else:+ logger.debug(+ f"[{request_id}] CCR: Tool already present (MCP?), skipped injection for hashes: {injector.detected_hashes}"+ )++ # Query Echo: disabled — hurts prefix caching in long conversations.+ if is_cache_mode(self.config.mode):+ optimized_messages, restored_count = self._restore_frozen_prefix(+ original_client_messages,+ optimized_messages,+ frozen_message_count=openai_frozen_count,+ )+ if restored_count > 0:+ logger.warning(+ f"[{request_id}] Restored {restored_count} frozen prefix message(s) "+ "to preserve cache stability (openai)"+ )++ # Memory: inject context and tools for OpenAI requests+ memory_context_injected = False+ memory_tools_injected = False+ if self.memory_handler and memory_user_id:+ try:+ # Inject memory context (search similar memories, add as system message)+ if self.memory_handler.config.inject_context:+ memory_context = await self.memory_handler.search_and_format_context(+ memory_user_id, optimized_messages+ )+ if memory_context:+ # Prepend as system message for OpenAI format+ optimized_messages = [+ {"role": "system", "content": memory_context},+ *optimized_messages,+ ]+ memory_context_injected = True+ logger.info(+ f"[{request_id}] Memory: Injected {len(memory_context)} chars "+ f"of context for user {memory_user_id}"+ )++ # Inject memory tools+ if self.memory_handler.config.inject_tools:+ tools, mem_tools_injected = self.memory_handler.inject_tools(tools, "openai")+ if mem_tools_injected:+ memory_tools_injected = True+ logger.info(f"[{request_id}] Memory: Injected memory tools (openai)")+ except Exception as e:+ logger.warning(f"[{request_id}] Memory injection failed: {e}")++ if memory_context_injected or memory_tools_injected:+ remembered_event = self.pipeline_extensions.emit(+ PipelineStage.INPUT_REMEMBERED,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=optimized_messages,+ tools=tools,+ metadata={+ "memory_context_injected": memory_context_injected,+ "memory_tools_injected": memory_tools_injected,+ },+ )+ if remembered_event.messages is not None:+ optimized_messages = remembered_event.messages+ if remembered_event.tools is not None:+ tools = remembered_event.tools++ body["messages"] = optimized_messages+ if tools is not None:+ body["tools"] = tools++ presend_event = self.pipeline_extensions.emit(+ PipelineStage.PRE_SEND,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=optimized_messages,+ tools=tools,+ headers=headers,+ metadata={"path": "/v1/chat/completions", "stream": stream},+ )+ if presend_event.messages is not None:+ optimized_messages = presend_event.messages+ body["messages"] = optimized_messages+ if presend_event.tools is not None:+ tools = presend_event.tools+ body["tools"] = tools+ if presend_event.headers is not None:+ headers = presend_event.headers+ optimized_tokens = tokenizer.count_messages(body["messages"])+ tokens_saved = original_tokens - optimized_tokens++ # Route through LiteLLM/any-llm backend if configured+ if self.anthropic_backend is not None:+ try:+ if stream:+ self.pipeline_extensions.emit(+ PipelineStage.POST_SEND,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=body["messages"],+ tools=tools,+ metadata={"path": "/v1/chat/completions", "stream": True},+ )+ # Streaming: use stream_openai_message() → SSE events+ return await self._stream_openai_via_backend(+ body,+ headers,+ model,+ request_id,+ start_time,+ original_tokens,+ optimized_tokens,+ tokens_saved,+ transforms_applied,+ tags,+ optimization_latency,+ pipeline_timing=pipeline_timing,+ )+ else:+ # Non-streaming: use send_openai_message() → JSON+ backend_response = await self.anthropic_backend.send_openai_message(+ body, headers+ )+ self.pipeline_extensions.emit(+ PipelineStage.POST_SEND,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=body["messages"],+ tools=tools,+ response=backend_response.body,+ metadata={+ "path": "/v1/chat/completions",+ "stream": False,+ "status_code": backend_response.status_code,+ },+ )+ self.pipeline_extensions.emit(+ PipelineStage.RESPONSE_RECEIVED,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ response=backend_response.body,+ metadata={+ "path": "/v1/chat/completions",+ "stream": False,+ "status_code": backend_response.status_code,+ },+ )++ if backend_response.error:+ return JSONResponse(+ status_code=backend_response.status_code,+ content=backend_response.body,+ )++ # Track metrics+ total_latency = (time.time() - start_time) * 1000+ usage = backend_response.body.get("usage", {})+ output_tokens = usage.get("completion_tokens", 0)+ total_input_tokens = usage.get("prompt_tokens", optimized_tokens)++ await self.metrics.record_request(+ provider=self.anthropic_backend.name,+ model=model,+ input_tokens=total_input_tokens,+ output_tokens=output_tokens,+ tokens_saved=tokens_saved,+ latency_ms=total_latency,+ cached=False,+ overhead_ms=optimization_latency,+ pipeline_timing=pipeline_timing,+ )++ if tokens_saved > 0:+ logger.info(+ f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "+ f"(saved {tokens_saved:,} tokens) via {self.anthropic_backend.name}"+ )++ return JSONResponse(+ status_code=backend_response.status_code,+ content=backend_response.body,+ )+ except Exception as e:+ logger.error(f"[{request_id}] Backend error: {e}")+ return JSONResponse(+ status_code=500,+ content={+ "error": {+ "message": str(e),+ "type": "api_error",+ "code": "backend_error",+ }+ },+ )++ # Direct OpenAI API (no backend configured)+ url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/chat/completions")++ try:+ if stream:+ # Inject stream_options to get usage stats in streaming response+ # This allows accurate token counting instead of byte-based estimation+ if "stream_options" not in body:+ body["stream_options"] = {"include_usage": True}+ elif isinstance(body.get("stream_options"), dict):+ body["stream_options"]["include_usage"] = True++ self.pipeline_extensions.emit(+ PipelineStage.POST_SEND,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=body["messages"],+ tools=tools,+ metadata={"path": "/v1/chat/completions", "stream": True},+ )+ return await self._stream_response(+ url,+ headers,+ body,+ "openai",+ model,+ request_id,+ original_tokens,+ optimized_tokens,+ tokens_saved,+ transforms_applied,+ tags,+ optimization_latency,+ pipeline_timing=pipeline_timing,+ prefix_tracker=openai_prefix_tracker,+ )+ else:+ headers = await apply_copilot_api_auth(headers, url=url)+ response = await self._retry_request("POST", url, headers, body)+ self.pipeline_extensions.emit(+ PipelineStage.POST_SEND,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ messages=body["messages"],+ tools=tools,+ response=response,+ metadata={+ "path": "/v1/chat/completions",+ "stream": False,+ "status_code": response.status_code,+ },+ )+ self.pipeline_extensions.emit(+ PipelineStage.RESPONSE_RECEIVED,+ operation="proxy.request",+ request_id=request_id,+ provider="openai",+ model=model,+ response=response,+ metadata={+ "path": "/v1/chat/completions",+ "stream": False,+ "status_code": response.status_code,+ },+ )++ # Full diagnostic dump on upstream errors (OpenAI handler)+ if response.status_code >= 400:+ try:+ err_body = response.json()+ err_msg = err_body.get("error", {}).get("message", "")+ err_type = err_body.get("error", {}).get("type", "")+ except Exception:+ err_body = {"raw": response.text[:2000]}+ err_msg = str(response.text[:500])+ err_type = "parse_error"++ logger.warning(+ f"[{request_id}] UPSTREAM_ERROR "+ f"status={response.status_code} "+ f"error_type={err_type} "+ f"error_msg={err_msg!r} "+ f"model={model} "+ f"compressed={'yes' if transforms_applied else 'no'} "+ f"transforms={transforms_applied} "+ f"original_tokens={original_tokens} "+ f"optimized_tokens={optimized_tokens} "+ f"message_count={len(body.get('messages', []))} "+ f"stream={stream}"+ )++ try:+ from headroom import paths as _hr_paths++ debug_dir = _hr_paths.debug_400_dir()+ debug_dir.mkdir(parents=True, exist_ok=True)+ ts = datetime.now().strftime("%Y%m%d_%H%M%S")+ debug_file = debug_dir / f"{ts}_{request_id}.json"++ safe_headers = {}+ for k, v in headers.items():+ if k.lower() in ("x-api-key", "authorization"):+ safe_headers[k] = v[:12] + "..." if v else ""+ else:+ safe_headers[k] = v++ debug_payload = {+ "request_id": request_id,+ "timestamp": datetime.now().isoformat(),+ "status_code": response.status_code,+ "error_response": err_body,+ "model": model,+ "stream": stream,+ "headers": safe_headers,+ "compression": {+ "was_compressed": bool(transforms_applied),+ "transforms": transforms_applied,+ "original_tokens": original_tokens,+ "optimized_tokens": optimized_tokens,+ "tokens_saved": tokens_saved,+ "compression_failed": _compression_failed,+ },+ "tools_sent": body.get("tools"),+ "tool_count": len(body.get("tools") or []),+ "original_tool_count": len(_original_tools or []),+ "messages_sent": body.get("messages"),+ "message_count": len(body.get("messages", [])),+ "original_messages": (+ original_messages+ if original_messages is not body.get("messages")+ else "__same_as_sent__"+ ),+ "original_message_count": len(original_messages),+ "system_prompt": body.get("system"),+ }++ with open(debug_file, "w") as f:+ json.dump(debug_payload, f, indent=2, default=str)++ logger.warning(f"[{request_id}] Full debug dump: {debug_file}")+ except Exception as dump_err:+ logger.error(f"[{request_id}] Failed to write debug dump: {dump_err}")++ total_latency = (time.time() - start_time) * 1000++ total_input_tokens = optimized_tokens # fallback+ output_tokens = 0+ cache_read_tokens = 0+ resp_json = None+ try:+ resp_json = response.json()+ usage = resp_json.get("usage", {})+ total_input_tokens = usage.get("prompt_tokens", optimized_tokens)+ output_tokens = usage.get("completion_tokens", 0)+ # OpenAI returns cached_tokens in prompt_tokens_details+ # These are charged at 50% of the input price+ prompt_details = usage.get("prompt_tokens_details") or {}+ cache_read_tokens = prompt_details.get("cached_tokens", 0)+ except (KeyError, TypeError, AttributeError) as e:+ logger.debug(+ f"[{request_id}] Failed to extract cached tokens from OpenAI response: {e}"+ )++ # Update prefix cache tracker for next turn+ openai_prefix_tracker.update_from_response(+ cache_read_tokens=cache_read_tokens,+ cache_write_tokens=0, # OpenAI doesn't report write tokens+ messages=optimized_messages,+ )++ # OpenAI has no write penalty — uncached = total - cached+ uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens)++ if self.cost_tracker:+ self.cost_tracker.record_tokens(+ model,+ tokens_saved,+ optimized_tokens,+ cache_read_tokens=cache_read_tokens,+ uncached_tokens=uncached_input_tokens,+ )++ # Memory: handle memory tool calls in OpenAI Chat Completions response.+ # After executing tools, send a continuation request so the model+ # can produce a final user-facing response (not just tool_calls).+ if (+ self.memory_handler+ and memory_user_id+ and resp_json+ and response.status_code == 200+ and self.memory_handler.has_memory_tool_calls(resp_json, "openai")+ ):+ try:+ tool_results = await self.memory_handler.handle_memory_tool_calls(+ resp_json, memory_user_id, "openai"+ )+ if tool_results:+ # Build continuation: original messages + assistant tool_calls + tool results+ assistant_msg = resp_json.get("choices", [{}])[0].get("message", {})+ continuation_messages = list(optimized_messages)+ continuation_messages.append(assistant_msg)+ continuation_messages.extend(tool_results)++ continuation_body = {+ **body,+ "messages": continuation_messages,+ }++ cont_response = await self._retry_request(+ "POST", url, headers, continuation_body+ )+ if cont_response.status_code == 200:+ resp_json = cont_response.json()+ response = cont_response++ logger.info(+ f"[{request_id}] Memory: Handled {len(tool_results)} "+ f"tool call(s) with continuation for user {memory_user_id}"+ )+ except Exception as e:+ logger.warning(f"[{request_id}] Memory tool handling failed: {e}")++ # Cache+ if self.cache and response.status_code == 200:+ await self.cache.set(+ messages,+ model,+ response.content,+ dict(response.headers),+ tokens_saved,+ )++ # Capture Codex rate-limit window data from response headers+ from headroom.subscription.codex_rate_limits import (+ get_codex_rate_limit_state,+ )++ get_codex_rate_limit_state().update_from_headers(dict(response.headers))++ await self.metrics.record_request(+ provider="openai",+ model=model,+ input_tokens=total_input_tokens,+ output_tokens=output_tokens,+ tokens_saved=tokens_saved,+ latency_ms=total_latency,+ overhead_ms=optimization_latency,+ pipeline_timing=pipeline_timing,+ waste_signals=waste_signals_dict,+ cache_read_tokens=cache_read_tokens,+ uncached_input_tokens=uncached_input_tokens,+ )++ if tokens_saved > 0:+ logger.info(+ f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "+ f"(saved {tokens_saved:,} tokens)"+ )++ # Remove compression headers since httpx already decompressed the response+ response_headers = dict(response.headers)+ response_headers.pop("content-encoding", None)+ response_headers.pop("content-length", None) # Length changed after decompression++ # Inject Headroom compression metrics (for SaaS metering)+ response_headers["x-headroom-tokens-before"] = str(original_tokens)+ response_headers["x-headroom-tokens-after"] = str(optimized_tokens)+ response_headers["x-headroom-tokens-saved"] = str(tokens_saved)+ response_headers["x-headroom-model"] = model+ if transforms_applied:+ response_headers["x-headroom-transforms"] = ",".join(transforms_applied)+ if cache_read_tokens > 0:+ response_headers["x-headroom-cached"] = "true"+ if _compression_failed:+ response_headers["x-headroom-compression-failed"] = "true"++ return Response(+ content=response.content,+ status_code=response.status_code,+ headers=response_headers,+ )+ except Exception as e:+ await self.metrics.record_failed(provider="openai")+ # Log full error details internally for debugging+ logger.error(f"[{request_id}] OpenAI request failed: {type(e).__name__}: {e}")+ # Return sanitized error message to client (don't expose internal details)+ return JSONResponse(+ status_code=502,+ content={+ "error": {+ "message": "An error occurred while processing your request. Please try again.",+ "type": "server_error",+ "code": "proxy_error",+ }+ },+ )++ async def handle_openai_responses(+ self,+ request: Request,+ ) -> Response | StreamingResponse:+ """Handle OpenAI /v1/responses endpoint (new Responses API).++ The Responses API differs from /v1/chat/completions:+ - Input: `input` (string or array) instead of `messages`+ - System: `instructions` instead of system message+ - Output: `output[]` array instead of `choices[].message`+ - State: `previous_response_id` for multi-turn+ - Built-in tools: web_search, file_search, code_interpreter+ """+ from fastapi import HTTPException+ from fastapi.responses import JSONResponse, Response++ from headroom.proxy.helpers import (+ COMPRESSION_TIMEOUT_SECONDS,+ MAX_REQUEST_BODY_SIZE,+ _read_request_json,+ )+ from headroom.proxy.responses_converter import (+ messages_to_responses_items,+ responses_items_to_messages,+ )+ from headroom.tokenizers import get_tokenizer+ from headroom.utils import extract_user_query++ start_time = time.time()+ request_id = await self._next_request_id()++ # Check request body size+ content_length = request.headers.get("content-length")+ if content_length and int(content_length) > MAX_REQUEST_BODY_SIZE:+ return JSONResponse(+ status_code=413,+ content={+ "error": {+ "message": f"Request body too large. Maximum size is {MAX_REQUEST_BODY_SIZE // (1024 * 1024)}MB",+ "type": "invalid_request_error",+ "code": "request_too_large",+ }+ },+ )++ # Parse request+ try:+ body = await _read_request_json(request)+ except (json.JSONDecodeError, ValueError) as e:+ return JSONResponse(+ status_code=400,+ content={+ "error": {+ "message": f"Invalid request body: {e!s}",+ "type": "invalid_request_error",+ "code": "invalid_json",+ }+ },+ )++ model = body.get("model", "unknown")+ stream = body.get("stream", False)++ # Convert Responses API input to messages format for optimization.+ # The Responses API uses a different item model (function_call,+ # function_call_output, reasoning as top-level items) — we convert to+ # Chat Completions messages for the pipeline, then convert back.++ input_data = body.get("input", "")+ instructions = body.get("instructions")+ previous_response_id = body.get("previous_response_id")++ messages: list[dict[str, Any]] = []+ original_items: list[dict[str, Any]] | None = None+ preserved_indices: list[int] = []++ if instructions:+ messages.append({"role": "system", "content": instructions})++ if isinstance(input_data, str):+ messages.append({"role": "user", "content": input_data})+ elif isinstance(input_data, list):+ original_items = input_data+ converted, preserved_indices = responses_items_to_messages(input_data)+ messages.extend(converted)++ headers = dict(request.headers.items())+ headers.pop("host", None)+ headers.pop("content-length", None)+ # Strip accept-encoding so httpx negotiates its own encoding.+ # Cloudflare Workers forward "br, zstd" which OpenAI may honor;+ # if httpx lacks brotli support the response body is undecipherable → 502.+ headers.pop("accept-encoding", None)+ tags = self._extract_tags(headers)++ # Memory: Get user ID when memory is enabled+ memory_user_id: str | None = None+ if self.memory_handler:+ memory_user_id = headers.get(+ "x-headroom-user-id",+ os.environ.get("USER", os.environ.get("USERNAME", "default")),+ )++ # Rate limiting+ if self.rate_limiter:+ rate_key = headers.get("authorization", "default")[:20]+ allowed, wait_seconds = await self.rate_limiter.check_request(rate_key)+ if not allowed:+ await self.metrics.record_rate_limited(provider="openai")+ raise HTTPException(+ status_code=429,+ detail=f"Rate limited. Retry after {wait_seconds:.1f}s",+ )++ # Token counting on converted messages+ tokenizer = get_tokenizer(model)+ original_tokens = tokenizer.count_messages(messages)++ # Optimize: convert items → compress → convert back+ tokens_saved = 0+ transforms_applied: list[str] = []+ optimized_messages = messages+ optimized_tokens = original_tokens++ _bypass = (+ request.headers.get("x-headroom-bypass", "").lower() == "true"+ or request.headers.get("x-headroom-mode", "").lower() == "passthrough"+ )+ _should_compress = (+ self.config.optimize+ and original_items is not None+ and not previous_response_id+ and not _bypass+ and len(messages) > 1+ )+ _license_ok = self.usage_reporter.should_compress if self.usage_reporter else True++ if _should_compress and _license_ok:+ try:+ context_limit = self.openai_provider.get_context_limit(model)+ result = await asyncio.wait_for(+ asyncio.to_thread(+ lambda: self.openai_pipeline.apply(+ messages=messages,+ model=model,+ model_limit=context_limit,+ context=extract_user_query(messages),+ )+ ),+ timeout=COMPRESSION_TIMEOUT_SECONDS,+ )+ if result.messages != messages:+ optimized_messages = result.messages+ transforms_applied = result.transforms_applied+ original_tokens = result.tokens_before+ optimized_tokens = result.tokens_after+ except Exception as e:+ logger.warning(f"[{request_id}] Responses API optimization failed: {e}")++ # Guard: if "optimization" inflated tokens, revert to originals+ if optimized_tokens > original_tokens:+ logger.warning(+ f"[{request_id}] Optimization inflated tokens "+ f"({original_tokens} -> {optimized_tokens}), reverting to original messages"+ )+ optimized_messages = messages+ optimized_tokens = original_tokens+ transforms_applied = []++ tokens_saved = original_tokens - optimized_tokens+ optimization_latency = (time.time() - start_time) * 1000++ # Convert compressed messages back to Responses API items+ if optimized_messages is not messages and original_items is not None:+ opt_msgs = optimized_messages+ # Strip system message (instructions) — it's separate in Responses API+ if instructions and opt_msgs and opt_msgs[0].get("role") == "system":+ body["instructions"] = opt_msgs[0]["content"]+ opt_msgs = opt_msgs[1:]++ body["input"] = messages_to_responses_items(opt_msgs, original_items, preserved_indices)++ # Memory: inject context and tools for Responses API requests+ if self.memory_handler and memory_user_id:+ try:+ # Inject memory context into instructions (Responses API system prompt)+ if self.memory_handler.config.inject_context:+ try:+ memory_context = await asyncio.wait_for(+ self.memory_handler.search_and_format_context(+ memory_user_id, optimized_messages+ ),+ timeout=RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS,+ )+ except asyncio.TimeoutError:+ memory_context = None+ logger.info(+ f"[{request_id}] Memory context lookup exceeded "+ f"{RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS:.1f}s; continuing without it"+ )+ if memory_context:+ existing_instructions = body.get("instructions") or ""+ if existing_instructions:+ body["instructions"] = f"{existing_instructions}\n\n{memory_context}"+ else:+ body["instructions"] = memory_context+ logger.info(+ f"[{request_id}] Memory: Injected {len(memory_context)} chars "+ f"of context into instructions for user {memory_user_id}"+ )++ # Inject memory tools (Responses API format)+ if self.memory_handler.config.inject_tools:+ resp_tools = body.get("tools") or []+ resp_tools, mem_tools_injected = self.memory_handler.inject_tools(+ resp_tools, "openai"+ )+ if mem_tools_injected:+ # Convert Chat Completions format to Responses API format+ converted_tools = []+ for t in resp_tools:+ if t.get("type") == "function" and "function" in t:+ fn = t["function"]+ converted_tools.append(+ {+ "type": "function",+ "name": fn.get("name"),+ "description": fn.get("description", ""),+ "parameters": fn.get("parameters", {}),+ }+ )+ else:+ converted_tools.append(t)+ body["tools"] = converted_tools+ logger.info(+ f"[{request_id}] Memory: Injected memory tools (openai/responses)"+ )+ except Exception as e:+ logger.warning(f"[{request_id}] Memory injection failed (responses): {e}")++ # /v1/responses is OpenAI-specific (Codex) — always routes direct.+ # LiteLLM/AnyLLM backends use /v1/chat/completions or /v1/messages.+ if self.anthropic_backend is not None:+ logger.debug(+ f"[{request_id}] /v1/responses always routes to OpenAI direct "+ f"(backend '{self.anthropic_backend.name}' not used for Responses API)"+ )++ headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)++ # Route to correct endpoint based on auth mode.+ # ChatGPT session auth (codex login) uses chatgpt.com, not api.openai.com.+ if is_chatgpt_auth:+ url = "https://chatgpt.com/backend-api/codex/responses"+ else:+ url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")++ try:+ if stream:+ # Streaming for Responses API uses semantic events+ return await self._stream_response(+ url,+ headers,+ body,+ "openai",+ model,+ request_id,+ original_tokens,+ optimized_tokens,+ tokens_saved,+ transforms_applied,+ tags,+ optimization_latency,+ memory_user_id=memory_user_id,+ )+ else:+ headers = await apply_copilot_api_auth(headers, url=url)+ response = await self._retry_request("POST", url, headers, body)+ total_latency = (time.time() - start_time) * 1000++ total_input_tokens = original_tokens # fallback+ output_tokens = 0+ try:+ resp_json = response.json()+ usage = resp_json.get("usage", {})+ total_input_tokens = usage.get("input_tokens", original_tokens)+ output_tokens = usage.get("output_tokens", 0)+ except (KeyError, TypeError, AttributeError) as e:+ logger.debug(+ f"[{request_id}] Failed to extract cached tokens from OpenAI passthrough response: {e}"+ )++ # Memory: handle memory tool calls in Responses API response+ if (+ self.memory_handler+ and memory_user_id+ and resp_json+ and response.status_code == 200+ and self.memory_handler.has_memory_tool_calls(resp_json, "openai")+ ):+ try:+ # Extract function_call items from output+ from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES++ output_items = resp_json.get("output", [])+ memory_fc_items = [+ item+ for item in output_items+ if isinstance(item, dict)+ and item.get("type") == "function_call"+ and item.get("name") in MEMORY_TOOL_NAMES+ ]++ # Execute memory tool calls+ tool_outputs: list[dict[str, Any]] = []+ for fc in memory_fc_items:+ call_id = fc.get("call_id", fc.get("id", ""))+ name = fc.get("name", "")+ args_str = fc.get("arguments", "{}")+ try:+ args = json.loads(args_str)+ except json.JSONDecodeError:+ args = {}++ await self.memory_handler._ensure_initialized()+ if self.memory_handler._backend:+ result = await self.memory_handler._execute_memory_tool(+ name, args, memory_user_id, "openai"+ )+ else:+ result = json.dumps({"error": "Memory backend not initialized"})++ tool_outputs.append(+ {+ "type": "function_call_output",+ "call_id": call_id,+ "output": result,+ }+ )++ if tool_outputs:+ # Make continuation request with tool results+ response_id = resp_json.get("id")+ continuation_body = {+ "model": model,+ "input": tool_outputs,+ }+ if response_id:+ continuation_body["previous_response_id"] = response_id+ existing_tools = body.get("tools")+ if existing_tools:+ continuation_body["tools"] = existing_tools++ cont_response = await self._retry_request(+ "POST", url, headers, continuation_body+ )+ resp_json = cont_response.json()+ response = cont_response+ logger.info(+ f"[{request_id}] Memory: Handled {len(tool_outputs)} "+ f"tool call(s) with continuation for user {memory_user_id} (responses)"+ )+ except Exception as e:+ logger.warning(+ f"[{request_id}] Memory tool handling failed (responses): {e}"+ )++ if self.cost_tracker:+ self.cost_tracker.record_tokens(model, tokens_saved, total_input_tokens)++ await self.metrics.record_request(+ provider="openai",+ model=model,+ input_tokens=total_input_tokens,+ output_tokens=output_tokens,+ tokens_saved=tokens_saved,+ latency_ms=total_latency,+ overhead_ms=optimization_latency,+ )++ logger.info(f"[{request_id}] /v1/responses {model}: {total_input_tokens:,} tokens")++ # Capture Codex rate-limit window data from response headers+ from headroom.subscription.codex_rate_limits import (+ get_codex_rate_limit_state,+ )++ get_codex_rate_limit_state().update_from_headers(dict(response.headers))++ # Remove compression headers+ response_headers = dict(response.headers)+ response_headers.pop("content-encoding", None)+ response_headers.pop("content-length", None)++ return Response(+ content=response.content,+ status_code=response.status_code,+ headers=response_headers,+ )+ except Exception as e:+ await self.metrics.record_failed(provider="openai")+ logger.error(f"[{request_id}] OpenAI responses request failed: {type(e).__name__}: {e}")+ return JSONResponse(+ status_code=502,+ content={+ "error": {+ "message": "An error occurred while processing your request. Please try again.",+ "type": "server_error",+ "code": "proxy_error",+ }+ },+ )++ async def handle_openai_responses_ws(self, websocket: WebSocket) -> None:+ """WebSocket proxy for /v1/responses (Codex gpt-5.4+).++ Newer Codex versions use WebSocket instead of HTTP POST for the+ Responses API. This handler:+ 1. Accepts the client WebSocket+ 2. Receives the first message (``response.create`` request)+ 3. Compresses the ``input`` array using the existing pipeline+ 4. Opens an upstream WebSocket to OpenAI+ 5. Sends the compressed request upstream+ 6. Relays all subsequent messages bidirectionally+ """+ from headroom.proxy.helpers import COMPRESSION_TIMEOUT_SECONDS+ from headroom.tokenizers import get_tokenizer+ from headroom.utils import extract_user_query++ try:+ import websockets+ except ImportError:+ await websocket.accept()+ await websocket.close(+ code=1011,+ reason="websockets package not installed. pip install websockets",+ )+ return++ request_id = await self._next_request_id()+ session_id = uuid.uuid4().hex++ # Stage-timer — captures per-stage durations for the structured+ # log emitted on session close. Unit 2 instrumentation.+ stage_timer = StageTimer()+ session_started_at = time.perf_counter()++ # Unit 3: initialize registry variables *before* accept so the+ # outermost ``finally`` can rely on them existing even if+ # registration itself fails for some reason.+ ws_sessions: WebSocketSessionRegistry | None = getattr(self, "ws_sessions", None)+ session_handle: WSSessionHandle | None = None+ termination_cause: TerminationCause = "unknown"++ # Forward client headers to upstream, adding required OpenAI-Beta header+ ws_headers = dict(websocket.headers)++ # Extract subprotocol from client — this is an application-level negotiation+ # that MUST be forwarded end-to-end (unlike sec-websocket-key which is per-connection).+ # Codex and OpenAI negotiate a subprotocol; stripping it causes OpenAI to return 500.+ client_subprotocols: list[str] = []+ raw_protocol = ws_headers.get("sec-websocket-protocol", "")+ if raw_protocol:+ client_subprotocols = [p.strip() for p in raw_protocol.split(",") if p.strip()]++ # Accept client connection with the requested subprotocol+ async with stage_timer.measure("accept"):+ if client_subprotocols:+ await websocket.accept(subprotocol=client_subprotocols[0])+ else:+ await websocket.accept()++ # --- Unit 3: register the session as soon as accept succeeds ---+ client_addr: str | None = None+ client_info = getattr(websocket, "client", None)+ if client_info is not None:+ host = getattr(client_info, "host", None)+ port = getattr(client_info, "port", None)+ if host is not None and port is not None:+ client_addr = f"{host}:{port}"+ elif host is not None:+ client_addr = str(host)+ if ws_sessions is not None:+ session_handle = WSSessionHandle(+ session_id=session_id,+ request_id=request_id,+ client_addr=client_addr,+ upstream_url=None, # set below once upstream_url is computed+ )+ ws_sessions.register(session_handle)+ metrics = getattr(self, "metrics", None)+ if metrics is not None and hasattr(metrics, "inc_active_ws_sessions"):+ try:+ metrics.inc_active_ws_sessions()+ except Exception: # pragma: no cover - defensive+ pass++ # Forward all client headers except hop-by-hop / per-connection headers.+ # These are WebSocket handshake mechanics that the `websockets` library+ # generates fresh for the upstream connection — forwarding them would conflict.+ # Everything else (auth, org, beta, user-agent, custom headers) is forwarded as-is.+ _skip_headers = frozenset(+ {+ "host", # must match upstream, not local proxy+ "connection", # hop-by-hop+ "upgrade", # hop-by-hop+ "sec-websocket-key", # per-connection cryptographic nonce+ "sec-websocket-version", # protocol version (websockets lib sets this)+ "sec-websocket-extensions", # per-connection negotiation+ "sec-websocket-accept", # server-side only+ "sec-websocket-protocol", # handled via subprotocols param below+ "content-length", # hop-by-hop+ "transfer-encoding", # hop-by-hop+ }+ )+ upstream_headers: dict[str, str] = {}+ for k, v in ws_headers.items():+ if k.lower() not in _skip_headers:+ upstream_headers[k] = v++ upstream_headers, is_chatgpt_auth = _resolve_codex_routing_headers(upstream_headers)+ _lower_headers = {k.lower(): v for k, v in upstream_headers.items()}++ # Build upstream WebSocket URL based on auth mode+ if is_chatgpt_auth:+ # ChatGPT session auth → route to chatgpt.com backend+ upstream_url = "wss://chatgpt.com/backend-api/codex/responses"+ logger.debug(+ f"[{request_id}] WS: ChatGPT session auth detected, routing to chatgpt.com"+ )+ else:+ # API key auth → route to configured OpenAI API URL+ base = self.OPENAI_API_URL+ ws_base = base.replace("https://", "wss://").replace("http://", "ws://")+ upstream_url = build_copilot_upstream_url(ws_base, "/v1/responses")++ # Unit 3: attach the resolved upstream URL to the session handle.+ if session_handle is not None:+ session_handle.upstream_url = upstream_url++ # Ensure Authorization header is present — fall back to OPENAI_API_KEY env var.+ # Safety net for clients that don't forward auth headers via WebSocket upgrade.+ if "authorization" not in _lower_headers:+ api_key = os.environ.get("OPENAI_API_KEY")+ if api_key:+ upstream_headers["Authorization"] = f"Bearer {api_key}"+ logger.debug(f"[{request_id}] WS: injected Authorization from OPENAI_API_KEY env")+ else:+ logger.warning(+ f"[{request_id}] WS: no Authorization header from client and "+ f"OPENAI_API_KEY not set — upstream will likely reject"+ )++ upstream_headers = await apply_copilot_api_auth(upstream_headers, url=upstream_url)++ # Ensure the required beta header is present — OpenAI returns 500 without it.+ # Codex sends `responses_websockets=2026-02-06`; only inject if missing entirely.+ if "openai-beta" not in _lower_headers:+ upstream_headers["OpenAI-Beta"] = "responses_websockets=2026-02-06"++ logger.debug(+ f"[{request_id}] WS upstream headers: "+ f"{[k for k in upstream_headers if k.lower() != 'authorization']}, "+ f"subprotocols={client_subprotocols}"+ )++ try:+ # Receive the first message from client (the response.create request).+ # Bound the wait with WS_FIRST_FRAME_TIMEOUT_SECONDS so a zombie+ # client that opens the WS but never sends a frame cannot hold a+ # session slot indefinitely. The StageTimer measurement still+ # captures the elapsed time up to the timeout so operators can+ # see the slow-client pattern in the stage-timings log.+ try:+ async with stage_timer.measure("first_client_frame"):+ first_msg_raw = await asyncio.wait_for(+ websocket.receive_text(),+ timeout=WS_FIRST_FRAME_TIMEOUT_SECONDS,+ )+ except asyncio.TimeoutError:+ logger.info(+ f"[{request_id}] WS first-frame timeout after "+ f"{WS_FIRST_FRAME_TIMEOUT_SECONDS:.0f}s; closing session "+ f"{session_id} (no client data)"+ )+ termination_cause = "client_timeout"+ with contextlib.suppress(Exception):+ # 1001 (going away): server is cleanly terminating a slow+ # client, not an internal error.+ await websocket.close(code=1001, reason="first-frame timeout")+ # Exit the outer try so the session-lifecycle ``finally`` runs+ # deregister / metrics / stage-timings emission as usual.+ return++ # --- Optional: compress the input in the first message ---+ body: dict[str, Any] = {}+ try:+ body = json.loads(first_msg_raw)+ tokens_saved = 0+ ws_request_body = body.get("response", body)+ input_data = (+ ws_request_body.get("input") if isinstance(ws_request_body, dict) else None+ )++ should_compress = (+ self.config.optimize+ and isinstance(input_data, list)+ and len(input_data) > 1+ and not (+ ws_request_body.get("previous_response_id")+ if isinstance(ws_request_body, dict)+ else None+ )+ )+ if should_compress:+ try:+ from headroom.proxy.responses_converter import (+ messages_to_responses_items,+ responses_items_to_messages,+ )++ model = ws_request_body.get("model", "gpt-4o")+ converted, preserved = responses_items_to_messages(input_data)++ messages: list[dict[str, Any]] = []+ instructions = ws_request_body.get("instructions")+ if instructions:+ messages.append({"role": "system", "content": instructions})+ messages.extend(converted)++ tokenizer = get_tokenizer(model)+ original_tokens = tokenizer.count_messages(messages)++ context_limit = self.openai_provider.get_context_limit(model)+ async with stage_timer.measure("compression"):+ result = await asyncio.wait_for(+ asyncio.to_thread(+ lambda: self.openai_pipeline.apply(+ messages=messages,+ model=model,+ model_limit=context_limit,+ context=extract_user_query(messages),+ )+ ),+ timeout=COMPRESSION_TIMEOUT_SECONDS,+ )++ if result.messages != messages:+ opt = result.messages+ if instructions and opt and opt[0].get("role") == "system":+ ws_request_body["instructions"] = opt[0]["content"]+ opt = opt[1:]+ if result.tokens_after <= original_tokens:+ ws_request_body["input"] = messages_to_responses_items(+ opt, input_data, preserved+ )+ else:+ logger.warning(+ f"[{request_id}] WS optimization inflated tokens "+ f"({original_tokens} -> {result.tokens_after}), reverting"+ )+ tokens_saved = max(0, original_tokens - result.tokens_after)+ if "response" in body and isinstance(body["response"], dict):+ body["response"] = ws_request_body+ else:+ body = ws_request_body+ first_msg_raw = json.dumps(body)+ logger.info(+ f"[{request_id}] WS /v1/responses compressed: "+ f"saved {tokens_saved} tokens"+ )+ except Exception as e:+ logger.warning(f"[{request_id}] WS compression failed: {e}")++ except json.JSONDecodeError:+ # Not JSON — pass through as-is+ tokens_saved = 0++ # --- Memory: inject context, tools, and instructions ---+ memory_user_id: str | None = None+ if self.memory_handler and body:+ memory_user_id = ws_headers.get(+ "x-headroom-user-id",+ os.environ.get("USER", os.environ.get("USERNAME", "default")),+ )+ try:+ # Unwrap response.create envelope to access the response body+ ws_response_body = body.get("response", body)++ # Debug: log what Codex sends so we can see the full tool list+ existing_tool_names = [+ t.get("name") or t.get("function", {}).get("name", "?")+ for t in (ws_response_body.get("tools") or [])+ ]+ instr_preview = (ws_response_body.get("instructions") or "")[:200]+ logger.info(+ f"[{request_id}] WS Memory: Codex tools={existing_tool_names}, "+ f"instructions_len={len(ws_response_body.get('instructions') or '')}, "+ f"instructions_preview={instr_preview!r}"+ )++ # Inject memory context into instructions+ if self.memory_handler.config.inject_context:+ ws_input = ws_response_body.get("input", "")+ ws_instructions = ws_response_body.get("instructions")+ ws_msgs: list[dict[str, Any]] = []+ if ws_instructions:+ ws_msgs.append({"role": "system", "content": ws_instructions})+ if isinstance(ws_input, str) and ws_input:+ ws_msgs.append({"role": "user", "content": ws_input})+ elif isinstance(ws_input, list):+ from headroom.proxy.responses_converter import (+ responses_items_to_messages,+ )++ converted_msgs, _ = responses_items_to_messages(ws_input)+ ws_msgs.extend(converted_msgs)++ try:+ async with stage_timer.measure("memory_context"):+ memory_context = await asyncio.wait_for(+ self.memory_handler.search_and_format_context(+ memory_user_id, ws_msgs+ ),+ timeout=RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS,+ )+ except asyncio.TimeoutError:+ memory_context = None+ logger.info(+ f"[{request_id}] WS Memory: Context lookup exceeded "+ f"{RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS:.1f}s; "+ f"continuing without it"+ )+ if memory_context:+ existing = ws_response_body.get("instructions") or ""+ if existing:+ ws_response_body["instructions"] = f"{existing}\n\n{memory_context}"+ else:+ ws_response_body["instructions"] = memory_context+ logger.info(+ f"[{request_id}] WS Memory: Injected {len(memory_context)} chars "+ f"of context into instructions"+ )++ # Inject memory tools (Responses API format)+ if self.memory_handler.config.inject_tools:+ ws_tools = ws_response_body.get("tools") or []+ ws_tools, mem_injected = self.memory_handler.inject_tools(+ ws_tools, "openai"+ )+ if mem_injected:+ converted_tools = []+ for t in ws_tools:+ if t.get("type") == "function" and "function" in t:+ fn = t["function"]+ converted_tools.append(+ {+ "type": "function",+ "name": fn.get("name"),+ "description": fn.get("description", ""),+ "parameters": fn.get("parameters", {}),+ }+ )+ else:+ converted_tools.append(t)+ ws_response_body["tools"] = converted_tools++ # Add memory instruction so the model uses+ # memory tools as persistent cross-session knowledge.+ mem_instruction = (+ "\n\n## Memory\n"+ "You have persistent memory via memory_search and "+ "memory_save tools. Memory stores knowledge across "+ "sessions — user info, project details, org context, "+ "decisions, architecture, conventions, anything worth "+ "remembering.\n\n"+ "- ALWAYS call memory_search BEFORE searching files "+ "when the user asks a question that could be answered "+ "from prior knowledge.\n"+ "- Call memory_save to store important facts, decisions, "+ "or context that would be useful in future sessions.\n"+ "- Memory is your first source of truth for anything "+ "not visible in the current conversation."+ )+ existing_instr = ws_response_body.get("instructions") or ""+ ws_response_body["instructions"] = existing_instr + mem_instruction+ logger.info(+ f"[{request_id}] WS Memory: Injected memory tools + instruction"+ )++ # Write back into envelope if it was wrapped+ if "response" in body and isinstance(body["response"], dict):+ body["response"] = ws_response_body+ else:+ body = ws_response_body++ first_msg_raw = json.dumps(body)+ except Exception as e:+ logger.warning(f"[{request_id}] WS Memory injection failed: {e}")++ # --- Connect to upstream OpenAI WebSocket ---+ logger.info(f"[{request_id}] WS /v1/responses connecting to {upstream_url}")++ # Use ssl=True to let the websockets library handle SSL natively.+ # Manual ssl.create_default_context() + certifi doesn't load the+ # Windows system cert store, causing HTTP 500 on wss:// connections.+ use_ssl: bool | None = True if upstream_url.startswith("wss://") else None++ ws_connected = False+ ws_connect_attempts = max(1, getattr(self.config, "retry_max_attempts", 3))+ ws_last_err: Exception | None = None+ _upstream_connect_started = time.perf_counter()+ _upstream_connect_recorded = False+ _upstream_first_event_started: float | None = None++ for ws_attempt in range(ws_connect_attempts):+ try:+ async with websockets.connect(+ upstream_url,+ additional_headers=upstream_headers,+ subprotocols=(+ [websockets.Subprotocol(p) for p in client_subprotocols]+ if client_subprotocols and hasattr(websockets, "Subprotocol")+ else client_subprotocols or None+ ),+ ssl=use_ssl,+ open_timeout=max(30, self.config.connect_timeout_seconds * 3),+ close_timeout=10,+ ping_interval=20,+ ping_timeout=20,+ ) as upstream:+ ws_connected = True+ if not _upstream_connect_recorded:+ stage_timer.record(+ "upstream_connect",+ (time.perf_counter() - _upstream_connect_started) * 1000.0,+ )+ _upstream_connect_recorded = True+ _upstream_first_event_started = time.perf_counter()+ await upstream.send(first_msg_raw)++ # Unit 3: flag the upstream side flips on seeing+ # ``response.completed`` so the outer cause+ # classifier can prefer it over the raw+ # "upstream iterator ended" default.+ response_completed_seen = False+ # Captures the first exception surfaced by the+ # inner relay ``except`` blocks so the outer+ # classifier can still tell ``upstream_error``+ # from ``upstream_disconnect`` / ``response_completed``+ # even though the halves swallow and log.+ upstream_relay_error: BaseException | None = None+ client_relay_error: BaseException | None = None++ async def _client_to_upstream() -> None:+ nonlocal client_relay_error+ try:+ while True:+ msg = await websocket.receive_text()+ await upstream.send(msg)+ except asyncio.CancelledError:+ # Explicit cancel from the outer+ # orchestrator — re-raise so+ # ``t.cancelled()`` and ``t.exception()``+ # behave correctly in the caller.+ raise+ except Exception as relay_err:+ # Surface real errors to the classifier+ # without re-raising (existing fork+ # behavior: log and return so the+ # partner task can be cancelled+ # deterministically).+ if "WebSocketDisconnect" not in type(relay_err).__name__:+ client_relay_error = relay_err+ logger.debug(+ f"[{request_id}] WS client→upstream relay ended: {relay_err}"+ )+ with contextlib.suppress(Exception):+ await upstream.close()++ async def _upstream_to_client() -> None:+ """Relay upstream→client with transparent memory tool handling.++ Uses a buffer-then-decide approach:+ 1. Buffer events until first output item arrives+ 2. If first output is a memory tool → suppress entire response,+ execute tools silently, send continuation upstream+ 3. If first output is non-memory → flush buffer, stream normally+ 4. Continuation response events are relayed to Codex seamlessly++ This prevents orphaned response.created events from confusing Codex.+ """+ from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES++ # Unit 3: surface response.completed observation+ # to the outer scope so the termination-cause+ # classifier can prefer ``response_completed``+ # over ``upstream_disconnect``.+ nonlocal response_completed_seen+ nonlocal upstream_relay_error++ memory_enabled = bool(self.memory_handler and memory_user_id)++ # Per-response state (reset after each response.completed)+ event_buffer: list[str] = []+ decided = False+ suppress_response = False+ pending_fcs: list[dict[str, Any]] = []+ resp_id: str | None = None++ def _reset() -> None:+ nonlocal decided, suppress_response, resp_id+ event_buffer.clear()+ decided = False+ suppress_response = False+ pending_fcs.clear()+ resp_id = None++ # The retry-loop variable is safe to close over here:+ # ``_upstream_to_client`` is defined and awaited within+ # a single iteration and never escapes.+ _first_event_started_at = _upstream_first_event_started # noqa: B023++ try:+ async for msg in upstream:+ if (+ _first_event_started_at is not None+ and "upstream_first_event" not in stage_timer+ ):+ stage_timer.record(+ "upstream_first_event",+ (time.perf_counter() - _first_event_started_at)+ * 1000.0,+ )+ if isinstance(msg, bytes):+ await websocket.send_bytes(msg)+ continue+ msg_str = msg if isinstance(msg, str) else str(msg)++ if not memory_enabled:+ await websocket.send_text(msg_str)+ continue++ # Parse event+ try:+ event = json.loads(msg_str)+ except (json.JSONDecodeError, TypeError):+ await websocket.send_text(msg_str)+ continue++ event_type = event.get("type", "")++ # --- Phase 1: Buffer until first output item ---+ if not decided:+ event_buffer.append(msg_str)++ if event_type == "response.output_item.added":+ item = event.get("item", {})+ if (+ item.get("type") == "function_call"+ and item.get("name") in MEMORY_TOOL_NAMES+ ):+ # Memory tool first → suppress entire response+ suppress_response = True+ decided = True+ event_buffer.clear()+ logger.info(+ f"[{request_id}] WS Memory: Detected "+ f"{item.get('name')} — suppressing response"+ )+ else:+ # Non-memory first → flush buffer, pass through+ decided = True+ for buf in event_buffer:+ await websocket.send_text(buf)+ event_buffer.clear()++ elif event_type == "response.completed":+ # No output items at all — flush+ decided = True+ for buf in event_buffer:+ await websocket.send_text(buf)+ event_buffer.clear()+ _reset()+ response_completed_seen = True++ continue++ # --- Phase 2a: Suppress mode (memory response) ---+ if suppress_response:+ if event_type == "response.output_item.done":+ item = event.get("item", {})+ if (+ item.get("type") == "function_call"+ and item.get("name") in MEMORY_TOOL_NAMES+ ):+ pending_fcs.append(item)++ elif event_type == "response.completed":+ response_completed_seen = True+ resp = event.get("response", {})+ resp_id = resp.get("id")++ if pending_fcs:+ logger.info(+ f"[{request_id}] WS Memory: Executing "+ f"{len(pending_fcs)} tool(s) transparently"+ )++ # Execute memory tool calls+ tool_outputs: list[dict[str, Any]] = []+ for fc in pending_fcs:+ call_id = fc.get("call_id", fc.get("id", ""))+ fc_name = fc.get("name", "")+ args_str = fc.get("arguments", "{}")+ try:+ fc_args = json.loads(args_str)+ except json.JSONDecodeError:+ fc_args = {}++ await self.memory_handler._ensure_initialized()+ if self.memory_handler._backend:+ result = await self.memory_handler._execute_memory_tool(+ fc_name,+ fc_args,+ memory_user_id,+ "openai",+ )+ else:+ result = json.dumps(+ {"error": "backend not ready"}+ )++ tool_outputs.append(+ {+ "type": "function_call_output",+ "call_id": call_id,+ "output": result,+ }+ )+ logger.info(+ f"[{request_id}] WS Memory: Executed "+ f"{fc_name} for user {memory_user_id}"+ )++ # Send continuation upstream+ cont: dict[str, Any] = {+ "type": "response.create",+ "response": {"input": tool_outputs},+ }+ if resp_id:+ cont["response"]["previous_response_id"] = (+ resp_id+ )+ await upstream.send(json.dumps(cont))+ logger.info(+ f"[{request_id}] WS Memory: Sent continuation "+ f"with {len(tool_outputs)} result(s)"+ )++ _reset()+ # All events suppressed in this mode+ continue++ # --- Phase 2b: Pass-through mode ---+ await websocket.send_text(msg_str)++ except asyncio.CancelledError:+ raise+ except Exception as relay_err:+ if "WebSocketDisconnect" not in type(relay_err).__name__:+ # Capture for the outer classifier+ # so ``upstream_error`` can be+ # distinguished from a clean+ # upstream disconnect.+ upstream_relay_error = relay_err+ logger.debug(+ f"[{request_id}] WS upstream→client relay ended: {relay_err}"+ )+ finally:+ with contextlib.suppress(Exception):+ await websocket.close()++ # --- Unit 3: deterministic relay-task cancellation ---+ # Spawn each half as a named task so we can:+ # (a) attach them to the session registry for+ # ``/debug/ws-sessions``,+ # (b) cancel the survivor explicitly when the+ # first one exits, and+ # (c) classify the termination cause for the+ # duration histogram.+ client_task = asyncio.create_task(+ _client_to_upstream(),+ name=f"codex-ws-c2u-{session_id}",+ )+ upstream_task = asyncio.create_task(+ _upstream_to_client(),+ name=f"codex-ws-u2c-{session_id}",+ )+ relay_tasks = [client_task, upstream_task]+ if ws_sessions is not None:+ ws_sessions.attach_tasks(session_id, relay_tasks)+ metrics_for_tasks = getattr(self, "metrics", None)+ if metrics_for_tasks is not None and hasattr(+ metrics_for_tasks, "inc_active_relay_tasks"+ ):+ try:+ metrics_for_tasks.inc_active_relay_tasks(len(relay_tasks))+ except Exception: # pragma: no cover - defensive+ pass++ try:+ done, pending = await asyncio.wait(+ {client_task, upstream_task},+ return_when=asyncio.FIRST_COMPLETED,+ )+ # Cancel the survivor so we don't leak the+ # partner task. Suppress the CancelledError+ # we just raised ourselves — any *other*+ # exception from the cancelled task is+ # already logged inside its own try/except.+ for t in pending:+ t.cancel()+ if pending:+ with contextlib.suppress(asyncio.CancelledError):+ await asyncio.gather(*pending, return_exceptions=True)++ # Classify termination cause from whichever+ # task completed first. ``CancelledError``+ # can show up on the "done" side if the+ # handler itself was cancelled from outside+ # (e.g. server shutdown).+ for t in done:+ exc = None+ # Cancelled tasks raise CancelledError from+ # .exception(); surface it explicitly so the+ # downstream ``isinstance(exc, CancelledError)``+ # branches actually run. For any other+ # unexpected state (``InvalidStateError`` if+ # the task somehow isn't done — shouldn't+ # happen post-gather but defensive), we+ # suppress and leave ``exc`` as ``None``.+ if t.cancelled():+ exc = asyncio.CancelledError()+ else:+ with contextlib.suppress(asyncio.InvalidStateError):+ exc = t.exception()+ task_name = t.get_name() or ""+ if t is client_task:+ if client_relay_error is not None:+ termination_cause = "client_error"+ elif exc is None:+ termination_cause = "client_disconnect"+ elif isinstance(exc, asyncio.CancelledError):+ termination_cause = "client_disconnect"+ else:+ # Distinguish legitimate client+ # disconnect exceptions from+ # real errors: WebSocketDisconnect+ # is a normal client exit.+ if "WebSocketDisconnect" in type(exc).__name__:+ termination_cause = "client_disconnect"+ else:+ termination_cause = "client_error"+ elif t is upstream_task:+ if upstream_relay_error is not None:+ termination_cause = "upstream_error"+ logger.debug(+ f"[{request_id}] WS relay {task_name} "+ f"raised: {upstream_relay_error!r}"+ )+ elif exc is None:+ termination_cause = (+ "response_completed"+ if response_completed_seen+ else "upstream_disconnect"+ )+ elif isinstance(exc, asyncio.CancelledError):+ termination_cause = "upstream_disconnect"+ else:+ termination_cause = "upstream_error"+ logger.debug(+ f"[{request_id}] WS relay {task_name} raised: {exc!r}"+ )+ finally:+ # In case anything above raised before the+ # cancel-and-await loop ran.+ for t in relay_tasks:+ if not t.done():+ t.cancel()+ with contextlib.suppress(asyncio.CancelledError):+ await asyncio.gather(*relay_tasks, return_exceptions=True)++ logger.info(+ f"[{request_id}] WS /v1/responses completed "+ f"(tokens_saved={tokens_saved}, cause={termination_cause})"+ )+ break+ except Exception as ws_err:+ if ws_connected:+ # WS was established but broke mid-stream — re-raise+ raise++ ws_last_err = ws_err+ if ws_attempt >= ws_connect_attempts - 1:+ break++ delay_with_jitter = jitter_delay_ms(+ self.config.retry_base_delay_ms,+ self.config.retry_max_delay_ms,+ ws_attempt,+ )+ logger.warning(+ f"[{request_id}] WS upstream connect failed "+ f"(attempt {ws_attempt + 1}/{ws_connect_attempts}): {ws_err}; "+ f"retrying in {delay_with_jitter:.0f}ms"+ )+ await asyncio.sleep(delay_with_jitter / 1000)++ if not ws_connected:+ # WS upgrade failed (HTTP 500 from OpenAI is common).+ # Fall back to HTTP POST streaming and relay SSE events+ # back over the client WebSocket transparently.+ ws_err = ws_last_err or RuntimeError("unknown websocket connect failure")+ _ws_detail = str(ws_err)+ if hasattr(ws_err, "response"):+ resp_body = getattr(getattr(ws_err, "response", None), "body", b"")+ if resp_body:+ _ws_detail += f" | {resp_body[:300].decode('utf-8', errors='replace')}"+ logger.warning(+ f"[{request_id}] WS upstream failed ({_ws_detail}), "+ f"falling back to HTTP POST streaming"+ )+ await self._ws_http_fallback(+ websocket, body, first_msg_raw, upstream_headers, request_id+ )++ # Record metrics+ if tokens_saved > 0:+ model_name = body.get("model", "unknown") if isinstance(body, dict) else "unknown"+ await self.metrics.record_request(+ provider="openai",+ model=model_name,+ input_tokens=0,+ output_tokens=0,+ tokens_saved=tokens_saved,+ latency_ms=0,+ )++ except Exception as e:+ if "WebSocketDisconnect" in type(e).__name__:+ # Unit 3: client dropped the socket before or during+ # relay. The registry classifier may already have set+ # ``client_disconnect`` via the relay task exit path;+ # preserve that, otherwise set it here.+ if termination_cause == "unknown":+ termination_cause = "client_disconnect"+ else:+ # Extract response body from websockets InvalidStatus for better debugging+ error_detail = str(e)+ if hasattr(e, "response"):+ try:+ resp = e.response+ body_bytes = getattr(resp, "body", None) or b""+ if body_bytes:+ error_detail += (+ f" | body: {body_bytes[:500].decode('utf-8', errors='replace')}"+ )+ except Exception:+ pass+ logger.error(f"[{request_id}] WS proxy error: {error_detail}")+ if termination_cause == "unknown":+ termination_cause = "client_error"+ with contextlib.suppress(Exception):+ await websocket.close(code=1011, reason=str(e)[:120])+ finally:+ # Unit 2: emit structured per-session stage timings.+ stage_timer.record(+ "total_session",+ (time.perf_counter() - session_started_at) * 1000.0,+ )+ # Unit 3: deregister the session before (or independently+ # of) the stage-timings log so a failure there cannot leak+ # the registry entry. ``deregister`` is idempotent, so a+ # session that never registered is a no-op.+ if ws_sessions is not None and session_handle is not None:+ # Use deregister_and_count so the handle pop and the+ # relay-task count are read atomically inside the+ # registry. Capturing ``len(session_handle.relay_tasks)``+ # separately before ``deregister`` would risk drift if+ # the registry's bookkeeping ever changes.+ _deregistered, released_tasks = ws_sessions.deregister_and_count(+ session_id, cause=termination_cause+ )+ session_duration_ms = (time.perf_counter() - session_started_at) * 1000.0+ metrics_for_close = getattr(self, "metrics", None)+ if metrics_for_close is not None:+ with contextlib.suppress(Exception):+ if hasattr(metrics_for_close, "dec_active_ws_sessions"):+ metrics_for_close.dec_active_ws_sessions()+ if released_tasks and hasattr(metrics_for_close, "dec_active_relay_tasks"):+ metrics_for_close.dec_active_relay_tasks(released_tasks)+ if hasattr(metrics_for_close, "record_ws_session_duration"):+ metrics_for_close.record_ws_session_duration(+ session_duration_ms, termination_cause+ )+ await emit_stage_timings_log(+ path="openai_responses_ws",+ request_id=request_id,+ session_id=session_id,+ stage_timer=stage_timer,+ expected_stages=(+ "accept",+ "first_client_frame",+ "upstream_connect",+ "upstream_first_event",+ "memory_context",+ "compression",+ "total_session",+ ),+ metrics=getattr(self, "metrics", None),+ )++ async def _ws_http_fallback(+ self,+ websocket: WebSocket,+ body: dict[str, Any],+ first_msg_raw: str,+ upstream_headers: dict[str, str],+ request_id: str,+ ) -> None:+ """Fall back to HTTP POST streaming when upstream WS fails.++ Converts the WS ``response.create`` message to an HTTP POST to+ ``/v1/responses?stream=true``, reads SSE events, and relays each+ ``data:`` line as a WS text message to the client. This makes+ Codex work immediately instead of exhausting its WS retry budget.+ """+ # Route to correct endpoint based on auth mode+ _lower = {k.lower() for k in upstream_headers}+ if "chatgpt-account-id" in _lower:+ http_url = "https://chatgpt.com/backend-api/codex/responses"+ else:+ http_url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")++ # Build HTTP body from the WS response.create payload.+ # WS messages use {"type": "response.create", "response": {...}} wrapper.+ # The HTTP POST endpoint expects the inner response object directly.+ http_body: dict[str, Any]+ try:+ parsed = json.loads(first_msg_raw) if isinstance(first_msg_raw, str) else body+ except (json.JSONDecodeError, TypeError):+ parsed = body++ # Normalize WebSocket response.create payload into the HTTP request body.+ # Codex may send either:+ # 1. {"type":"response.create","response":{...}}+ # 2. {"type":"response.create", ...response fields...}+ if isinstance(parsed, dict) and isinstance(parsed.get("response"), dict):+ http_body = dict(parsed["response"])+ elif isinstance(parsed, dict):+ http_body = dict(parsed)+ if http_body.get("type") == "response.create":+ http_body.pop("type", None)+ else:+ http_body = body if isinstance(body, dict) else {}++ # Some clients include response-ish metadata that the HTTP endpoint rejects.+ if http_body.get("type") in {"response.create", "response"}:+ http_body.pop("type", None)++ # Ensure streaming is enabled so we get SSE events+ http_body["stream"] = True++ # Build HTTP headers from the upstream headers (already stripped of WS+ # hop-by-hop headers by the caller).+ http_headers = dict(upstream_headers)+ http_headers["content-type"] = "application/json"++ logger.debug(f"[{request_id}] WS→HTTP fallback POST to {http_url}")++ try:+ retry_attempts = max(1, getattr(self.config, "retry_max_attempts", 3))+ for http_attempt in range(retry_attempts):+ try:+ async with self.http_client.stream(+ "POST",+ http_url,+ headers=http_headers,+ json=http_body,+ timeout=120.0,+ ) as response:+ if response.status_code != 200:+ error_body = b""+ async for chunk in response.aiter_bytes():+ error_body += chunk+ if len(error_body) > 2000:+ break+ error_text = error_body.decode("utf-8", errors="replace")+ logger.error(+ f"[{request_id}] WS→HTTP fallback got {response.status_code}: "+ f"{error_text[:500]}"+ )+ # Send error as WS message so client sees it+ error_event = {+ "type": "error",+ "error": {+ "type": "server_error",+ "message": f"Upstream returned {response.status_code}",+ },+ }+ await websocket.send_text(json.dumps(error_event))+ return++ # Relay SSE events as WS text messages+ buffer = ""+ async for chunk in response.aiter_text():+ buffer += chunk+ while "\n" in buffer:+ line, buffer = buffer.split("\n", 1)+ line = line.strip()+ if not line:+ continue+ if line.startswith("data: "):+ data = line[6:]+ if data == "[DONE]":+ continue+ try:+ await websocket.send_text(data)+ except Exception:+ return+ elif line.startswith("event: "):+ # SSE event type — skip, the data line contains the type+ continue++ # Flush any remaining data in buffer+ for line in buffer.strip().splitlines():+ line = line.strip()+ if line.startswith("data: ") and line[6:] != "[DONE]":+ with contextlib.suppress(Exception):+ await websocket.send_text(line[6:])+ return+ except (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) as http_err:+ if http_attempt >= retry_attempts - 1:+ raise++ delay_with_jitter = jitter_delay_ms(+ self.config.retry_base_delay_ms,+ self.config.retry_max_delay_ms,+ http_attempt,+ )+ logger.warning(+ f"[{request_id}] WS→HTTP fallback connect failed "+ f"(attempt {http_attempt + 1}/{retry_attempts}): {http_err}; "+ f"retrying in {delay_with_jitter:.0f}ms"+ )+ await asyncio.sleep(delay_with_jitter / 1000)++ except Exception as http_err:+ logger.error(f"[{request_id}] WS→HTTP fallback failed: {http_err}")+ error_event = {+ "type": "error",+ "error": {+ "type": "server_error",+ "message": f"HTTP fallback failed: {http_err!s}"[:200],+ },+ }+ with contextlib.suppress(Exception):+ await websocket.send_text(json.dumps(error_event))+ finally:+ with contextlib.suppress(Exception):+ await websocket.close()++ async def handle_compress(self, request: Request) -> JSONResponse:+ """Compress messages without calling an LLM.++ POST /v1/compress+ Body: {"messages": [...], "model": "...", "config": {}}+ Returns compressed messages + metrics.+ """+ from fastapi.responses import JSONResponse++ from headroom.proxy.helpers import _read_request_json++ # Check bypass header+ if request.headers.get("x-headroom-bypass", "").lower() == "true":+ try:+ body = await _read_request_json(request)+ except (json.JSONDecodeError, ValueError) as e:+ return JSONResponse(+ status_code=400,+ content={"error": f"Invalid request body: {e!s}"},+ )+ messages = body.get("messages", [])+ return JSONResponse(+ {+ "messages": messages,+ "tokens_before": 0,+ "tokens_after": 0,+ "tokens_saved": 0,+ "compression_ratio": 1.0,+ "transforms_applied": [],+ "ccr_hashes": [],+ }+ )++ try:+ body = await _read_request_json(request)+ except Exception:+ return JSONResponse(+ status_code=400,+ content={+ "error": {+ "type": "invalid_request",+ "message": "Invalid JSON in request body.",+ }+ },+ )++ messages = body.get("messages")+ model = body.get("model")++ if messages is None:+ return JSONResponse(+ status_code=400,+ content={+ "error": {+ "type": "invalid_request",+ "message": "Missing required field: messages",+ }+ },+ )++ if model is None:+ return JSONResponse(+ status_code=400,+ content={+ "error": {+ "type": "invalid_request",+ "message": "Missing required field: model",+ }+ },+ )++ if not messages:+ return JSONResponse(+ {+ "messages": [],+ "tokens_before": 0,+ "tokens_after": 0,+ "tokens_saved": 0,+ "compression_ratio": 1.0,+ "transforms_applied": [],+ "ccr_hashes": [],+ }+ )++ try:+ # Use OpenAI pipeline (messages are in OpenAI format from TS SDK)+ # Allow optional token_budget to override model's context limit+ # (used by OpenClaw compact() and other callers that need tighter budgets)+ token_budget = body.get("token_budget")+ context_limit = (+ token_budget+ if token_budget and isinstance(token_budget, int)+ else self.openai_provider.get_context_limit(model)+ )+ # Extract CompressConfig options from request body+ compress_config = body.get("config", {})+ compress_user_messages = compress_config.get("compress_user_messages", False)+ target_ratio = compress_config.get("target_ratio")+ protect_recent = compress_config.get("protect_recent")+ protect_analysis_context = compress_config.get("protect_analysis_context")++ pipeline_kwargs: dict = {"model_limit": context_limit}+ if compress_user_messages:+ pipeline_kwargs["compress_user_messages"] = True+ if target_ratio is not None:+ pipeline_kwargs["target_ratio"] = float(target_ratio)+ if protect_recent is not None:+ pipeline_kwargs["protect_recent"] = int(protect_recent)+ if protect_analysis_context is not None:+ pipeline_kwargs["protect_analysis_context"] = bool(protect_analysis_context)++ result = self.openai_pipeline.apply(+ messages=messages,+ model=model,+ **pipeline_kwargs,+ )++ return JSONResponse(+ {+ "messages": result.messages,+ "tokens_before": result.tokens_before,+ "tokens_after": result.tokens_after,+ "tokens_saved": result.tokens_before - result.tokens_after,+ "compression_ratio": (+ result.tokens_after / result.tokens_before+ if result.tokens_before > 0+ else 1.0+ ),+ "transforms_applied": result.transforms_applied,+ "transforms_summary": result.transforms_summary,+ "ccr_hashes": result.markers_inserted,+ }+ )+ except Exception as e:+ logger.exception("Compression failed: %s", e)+ return JSONResponse(+ status_code=503,+ content={+ "error": {+ "type": "compression_error",+ "message": str(e),+ }+ },+ )++ async def handle_passthrough(+ self,+ request: Request,+ base_url: str,+ endpoint_name: str | None = None,+ provider: str | None = None,+ ) -> Response:+ """Pass through request unchanged.++ Args:+ request: The incoming request+ base_url: The upstream API base URL+ endpoint_name: Optional name for stats tracking (e.g., "models", "embeddings")+ provider: Optional provider name for stats (e.g., "openai", "anthropic", "gemini")+ """+ from fastapi.responses import Response++ start_time = time.time()+ path = request.url.path+ url = build_copilot_upstream_url(base_url, path)++ # Preserve query string parameters+ if request.url.query:+ url = f"{url}?{request.url.query}"++ headers = dict(request.headers.items())+ headers.pop("host", None)+ headers.pop("accept-encoding", None)++ body = await request.body()++ headers = await apply_copilot_api_auth(headers, url=url)+ response = await self.http_client.request( # type: ignore[union-attr]+ method=request.method,+ url=url,+ headers=headers,+ content=body,+ )++ # Remove compression headers since httpx already decompressed the response+ response_headers = dict(response.headers)+ response_headers.pop("content-encoding", None)+ response_headers.pop("content-length", None) # Length changed after decompression++ # Track stats for passthrough requests+ if endpoint_name and provider:+ latency_ms = (time.time() - start_time) * 1000+ await self.metrics.record_request(+ provider=provider,+ model=f"passthrough:{endpoint_name}",+ input_tokens=0,+ output_tokens=0,+ tokens_saved=0,+ latency_ms=latency_ms,+ cached=False,+ )++ return Response(+ content=response.content,+ status_code=response.status_code,+ headers=response_headers,+ )++ async def handle_databricks_invocations(+ self,+ request: Request,+ model: str,+ ) -> Response | StreamingResponse:+ """Handle Databricks native /serving-endpoints/{model}/invocations endpoint.++ This enables using the Databricks CLI directly with Headroom:+ databricks serving-endpoints query <model> --profile HEADROOM --json '{"messages": [...]}'++ The request/response format is identical to OpenAI chat completions,+ so we inject the model from the path and delegate to handle_openai_chat.+ """+ from fastapi.responses import JSONResponse++ from headroom.proxy.helpers import _read_request_json++ request_id = await self._next_request_id()++ try:+ body = await _read_request_json(request)+ except Exception as e:+ logger.error(f"[{request_id}] Failed to parse Databricks request body: {e}")+ return JSONResponse(+ status_code=400,+ content={+ "error": {+ "message": f"Invalid JSON: {e}",+ "type": "invalid_request_error",+ }+ },+ )++ # Inject model from path into body (Databricks CLI passes model in URL, not body)+ body["model"] = model++ logger.info(f"[{request_id}] Databricks invocation: model={model}")++ # Create a new request with the modified body+ # We reuse the OpenAI chat handler since the format is identical+ from starlette.requests import Request as StarletteRequest++ # Build new scope with the body already parsed+ scope = dict(request.scope)++ # Create a simple receive function that returns our modified body+ body_bytes = json.dumps(body).encode()++ async def receive():+ return {"type": "http.request", "body": body_bytes}++ modified_request = StarletteRequest(scope, receive)++ # Delegate to the OpenAI chat handler (same format)+ return await self.handle_openai_chat(modified_request)diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 8cdcbe714..256776c70 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -1,2620 +1,2620 @@-"""Headroom Proxy Server - Production Ready.--A full-featured LLM proxy with optimization, caching, rate limiting,-and observability.--Features:-- Context optimization (SmartCrusher, CacheAligner, RollingWindow)-- Semantic caching (save costs on repeated queries)-- Rate limiting (token bucket)-- Retry with exponential backoff-- Cost tracking and budgets-- Request tagging and metadata-- Provider fallback-- Prometheus metrics-- Full request/response logging--Usage:- python -m headroom.proxy.server --port 8787-- # With Claude Code:- ANTHROPIC_BASE_URL=http://localhost:8787 claude-"""--from __future__ import annotations--import argparse-import asyncio-import json-import logging-import os-import sys-import time-from datetime import datetime, timezone-from pathlib import Path-from typing import TYPE_CHECKING, Any, Literal, cast--if TYPE_CHECKING:- from ..backends.base import Backend- from ..cache.compression_cache import CompressionCache- from ..memory.tracker import MemoryTracker---import httpx--try:- import uvicorn- from fastapi import Depends, FastAPI, HTTPException, Request, Response- from fastapi.middleware.cors import CORSMiddleware- from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse-- FASTAPI_AVAILABLE = True-except ImportError:- FASTAPI_AVAILABLE = False--# Add parent to path for imports-sys.path.insert(0, str(Path(__file__).parent.parent.parent))--from headroom._version import __version__-from headroom.cache.compression_feedback import get_compression_feedback-from headroom.cache.compression_store import get_compression_store-from headroom.ccr import (- CCR_TOOL_NAME,- # Batch processing- CCRResponseHandler,- CCRToolInjector,- ContextTracker,- ContextTrackerConfig,- ResponseHandlerConfig,- parse_tool_call,-)-from headroom.config import (- CacheAlignerConfig,- CCRConfig,- IntelligentContextConfig,- ReadLifecycleConfig,- RollingWindowConfig,- SmartCrusherConfig,-)-from headroom.dashboard import get_dashboard_html-from headroom.observability import (- LangfuseTracingConfig,- OTelMetricsConfig,- configure_langfuse_tracing,- configure_otel_metrics,- get_langfuse_tracing_status,- get_otel_metrics_status,- shutdown_headroom_tracing,- shutdown_otel_metrics,-)-from headroom.pipeline import PipelineExtensionManager, PipelineStage-from headroom.providers.proxy_routes import register_provider_routes-from headroom.providers.registry import (- DEFAULT_ANTHROPIC_API_URL,- DEFAULT_CLOUDCODE_API_URL,- DEFAULT_GEMINI_API_URL,- DEFAULT_OPENAI_API_URL,- build_proxy_provider_runtime,- create_proxy_backend,- format_backend_status,-)--# =============================================================================-# Extracted modules (re-exported for backward compatibility)-# =============================================================================-from headroom.proxy.cost import (- _CACHE_ECONOMICS, # noqa: F401- CostTracker, # noqa: F401- _summarize_transforms, # noqa: F401- build_prefix_cache_stats, # noqa: F401- build_session_summary, # noqa: F401- merge_cost_stats, # noqa: F401-)-from headroom.proxy.helpers import (- COMPRESSION_TIMEOUT_SECONDS, # noqa: F401- MAX_COMPRESSION_CACHE_SESSIONS, # noqa: F401- MAX_MESSAGE_ARRAY_LENGTH, # noqa: F401- MAX_REQUEST_BODY_SIZE, # noqa: F401- MAX_SSE_BUFFER_SIZE, # noqa: F401- _get_image_compressor, # noqa: F401- _get_rtk_stats, # noqa: F401- _read_request_json, # noqa: F401- _setup_file_logging, # noqa: F401- is_anthropic_auth, # noqa: F401- jitter_delay_ms,-)-from headroom.proxy.memory_handler import MemoryConfig, MemoryHandler--# Data models (extracted to headroom/proxy/models.py for maintainability)-from headroom.proxy.models import CacheEntry, ProxyConfig, RateLimitState, RequestLog # noqa: F401-from headroom.proxy.modes import (- PROXY_MODE_CACHE,- PROXY_MODE_TOKEN,- is_token_mode,- normalize_proxy_mode,-)-from headroom.proxy.prometheus_metrics import PrometheusMetrics # noqa: F401-from headroom.proxy.rate_limiter import TokenBucketRateLimiter # noqa: F401-from headroom.proxy.request_logger import RequestLogger # noqa: F401-from headroom.proxy.semantic_cache import SemanticCache # noqa: F401-from headroom.proxy.warmup import WarmupRegistry-from headroom.proxy.ws_session_registry import WebSocketSessionRegistry-from headroom.subscription.base import get_quota_registry, reset_quota_registry-from headroom.subscription.codex_rate_limits import get_codex_rate_limit_state-from headroom.subscription.copilot_quota import get_copilot_quota_tracker-from headroom.subscription.tracker import (- configure_subscription_tracker,- get_subscription_tracker,-)-from headroom.telemetry import get_telemetry_collector-from headroom.telemetry.beacon import is_telemetry_enabled-from headroom.telemetry.toin import get_toin-from headroom.transforms import (- CacheAligner,- CodeAwareCompressor,- CodeCompressorConfig,- ContentRouter,- ContentRouterConfig,- IntelligentContextManager,- RollingWindow,- SmartCrusher,- Transform,- TransformPipeline,- is_tree_sitter_available,-)--AnyLLMBackend: Any = None-LiteLLMBackend: Any = None--fcntl: Any = None-try:- import fcntl as _fcntl-- fcntl = _fcntl- HAS_FCNTL = True-except ImportError:- HAS_FCNTL = False--_build_prefix_cache_stats = build_prefix_cache_stats-_build_session_summary = build_session_summary-_merge_cost_stats = merge_cost_stats---logging.basicConfig(- level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"-)-logger = logging.getLogger("headroom.proxy")--# Always-on file logging to ~/.headroom/logs/ for `headroom perf` analysis-_setup_file_logging()---# Compression pipeline timeout in seconds---from headroom.proxy.handlers import ( # noqa: E402- AnthropicHandlerMixin,- BatchHandlerMixin,- GeminiHandlerMixin,- OpenAIHandlerMixin,- StreamingMixin,-)---class HeadroomProxy(- StreamingMixin,- AnthropicHandlerMixin,- OpenAIHandlerMixin,- GeminiHandlerMixin,- BatchHandlerMixin,-):- """Production-ready Headroom optimization proxy."""-- ANTHROPIC_API_URL = DEFAULT_ANTHROPIC_API_URL- OPENAI_API_URL = DEFAULT_OPENAI_API_URL- GEMINI_API_URL = DEFAULT_GEMINI_API_URL- CLOUDCODE_API_URL = DEFAULT_CLOUDCODE_API_URL-- def __init__(self, config: ProxyConfig):- self.config = config- self.config.mode = normalize_proxy_mode(self.config.mode)- self.pipeline_extensions = PipelineExtensionManager(- hooks=config.hooks,- extensions=config.pipeline_extensions,- discover=config.discover_pipeline_extensions,- )-- self.provider_runtime = build_proxy_provider_runtime(config)- api_targets = self.provider_runtime.api_targets-- # Preserve the long-standing proxy compatibility surface while keeping- # provider_runtime as the source of truth for resolved upstream targets.- HeadroomProxy.ANTHROPIC_API_URL = api_targets.anthropic- HeadroomProxy.OPENAI_API_URL = api_targets.openai- HeadroomProxy.GEMINI_API_URL = api_targets.gemini- HeadroomProxy.CLOUDCODE_API_URL = api_targets.cloudcode- self.anthropic_provider = self.provider_runtime.pipeline_provider("anthropic")- self.openai_provider = self.provider_runtime.pipeline_provider("openai")-- # Initialize transforms based on routing mode- # Choose context manager: IntelligentContextManager (smart) or RollingWindow (legacy)- context_manager: Transform # Can be either IntelligentContextManager or RollingWindow- if config.intelligent_context:- # Get TOIN instance for learned pattern integration- toin = get_toin() if config.intelligent_context_scoring else None- context_manager = IntelligentContextManager(- config=IntelligentContextConfig(- enabled=True,- keep_system=True,- keep_last_turns=config.keep_last_turns,- use_importance_scoring=config.intelligent_context_scoring,- toin_integration=config.intelligent_context_scoring,- compress_threshold=0.10 if config.intelligent_context_compress_first else 0.0,- ),- toin=toin,- )- self._context_manager_status = "intelligent"- else:- context_manager = RollingWindow(- RollingWindowConfig(- enabled=True,- keep_system=True,- keep_last_turns=config.keep_last_turns,- )- )- self._context_manager_status = "rolling_window"-- if config.smart_routing:- # Smart routing: ContentRouter handles all content types intelligently- # It lazy-loads compressors only when needed- router_config = ContentRouterConfig(- enable_code_aware=config.code_aware_enabled,- tool_profiles=config.tool_profiles,- read_lifecycle=ReadLifecycleConfig(enabled=config.read_lifecycle),- )- # Token mode: allow compression of older excluded-tool results- if is_token_mode(config.mode):- router_config.protect_recent_reads_fraction = 0.3- transforms = [- CacheAligner(CacheAlignerConfig(enabled=False)),- ContentRouter(router_config),- context_manager,- ]- self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"- else:- # Legacy mode: sequential pipeline- transforms = [- CacheAligner(CacheAlignerConfig(enabled=False)),- SmartCrusher(- SmartCrusherConfig( # type: ignore[arg-type]- enabled=True,- min_tokens_to_crush=config.min_tokens_to_crush,- max_items_after_crush=config.max_items_after_crush,- ),- ccr_config=CCRConfig(- enabled=config.ccr_inject_tool,- inject_retrieval_marker=config.ccr_inject_tool, # Add CCR markers- ),- ),- context_manager,- ]- # Add CodeAware if enabled and available- self._code_aware_status = self._setup_code_aware(config, transforms)-- self.anthropic_pipeline = TransformPipeline(- transforms=transforms,- provider=self.anthropic_provider,- )- self.openai_pipeline = TransformPipeline(- transforms=transforms,- provider=self.openai_provider,- )-- # Initialize components- self.cache = (- SemanticCache(- max_entries=config.cache_max_entries,- ttl_seconds=config.cache_ttl_seconds,- )- if config.cache_enabled- else None- )-- self.rate_limiter = (- TokenBucketRateLimiter(- requests_per_minute=config.rate_limit_requests_per_minute,- tokens_per_minute=config.rate_limit_tokens_per_minute,- )- if config.rate_limit_enabled- else None- )-- self.cost_tracker = (- CostTracker(- budget_limit_usd=config.budget_limit_usd,- budget_period=config.budget_period,- )- if config.cost_tracking_enabled- else None- )-- self.metrics = PrometheusMetrics(cost_tracker=self.cost_tracker)-- # Prefix cache tracking: freeze already-cached messages to avoid- # invalidating the provider's prefix cache with our transforms- from headroom.cache.prefix_tracker import PrefixFreezeConfig, SessionTrackerStore-- self.session_tracker_store = SessionTrackerStore(- default_config=PrefixFreezeConfig(- enabled=config.prefix_freeze_enabled,- session_ttl_seconds=config.prefix_freeze_session_ttl,- )- )-- # Compression cache store for token mode (session-scoped)- self._compression_caches: dict[str, CompressionCache] = {}-- self.logger = (- RequestLogger(- log_file=config.log_file,- log_full_messages=config.log_full_messages,- )- if config.log_requests- else None- )-- # Enterprise security plugin (loaded dynamically if available + licensed)- self.security = None-- # HTTP client- self.http_client: httpx.AsyncClient | None = None-- # Shared cold-start warmup registry (populated by startup()).- # Holds typed slots with loaded / loading / null / error status for- # each preloaded heavy asset. Exposed as ``proxy.warmup`` and- # serialized by the /debug/warmup route (Unit 5).- self.warmup: WarmupRegistry = WarmupRegistry()- # Unit 3: live registry of Codex WS sessions. Populated by- # ``handle_openai_responses_ws`` on accept; drained in its- # outermost ``finally``. Consumed by ``/debug/ws-sessions``.- self.ws_sessions: WebSocketSessionRegistry = WebSocketSessionRegistry()-- # Unit 4: bounded pre-upstream concurrency for the Anthropic HTTP- # path. Caps how many ``handle_anthropic_messages`` calls may be- # running deep-copy / first-stage compression / memory-context- # lookup / upstream connect concurrently. ``/livez``, ``/readyz``,- # ``/health``, ``/metrics``, ``/stats``, and the Codex WS path are- # intentionally NOT gated by this semaphore.- #- # A value of ``0`` or negative disables the semaphore (unbounded- # mode); this is useful for the Unit 6 counter-factual where we- # deliberately reproduce the original starvation. The default is- # ``max(2, min(8, os.cpu_count() or 4))``.- _pre_upstream_cfg = config.anthropic_pre_upstream_concurrency- if _pre_upstream_cfg is None:- _pre_upstream_resolved = max(2, min(8, os.cpu_count() or 4))- else:- _pre_upstream_resolved = _pre_upstream_cfg- self.anthropic_pre_upstream_concurrency: int = _pre_upstream_resolved- self.anthropic_pre_upstream_acquire_timeout_seconds = float(- config.anthropic_pre_upstream_acquire_timeout_seconds- )- self.anthropic_pre_upstream_memory_context_timeout_seconds = float(- config.anthropic_pre_upstream_memory_context_timeout_seconds- )- if _pre_upstream_resolved > 0:- self.anthropic_pre_upstream_sem: asyncio.Semaphore | None = asyncio.Semaphore(- _pre_upstream_resolved- )- else:- self.anthropic_pre_upstream_sem = None-- # Backend for Anthropic API (direct, LiteLLM, or any-llm)- # Supports: "anthropic" (direct), "bedrock", "vertex", "litellm-<provider>", or "anyllm"- self.anthropic_backend: Backend | None = create_proxy_backend(- backend=config.backend,- anyllm_provider=config.anyllm_provider,- bedrock_region=config.bedrock_region,- logger=logger,- anyllm_backend_cls=AnyLLMBackend,- litellm_backend_cls=LiteLLMBackend,- )-- # Request counter for IDs- self._request_counter = 0- self._request_counter_lock = asyncio.Lock()-- # CCR tool injectors (one per provider)- self.anthropic_tool_injector = CCRToolInjector(- provider="anthropic",- inject_tool=config.ccr_inject_tool,- inject_system_instructions=config.ccr_inject_system_instructions,- )- self.openai_tool_injector = CCRToolInjector(- provider="openai",- inject_tool=config.ccr_inject_tool,- inject_system_instructions=config.ccr_inject_system_instructions,- )-- # CCR Response Handler (handles CCR tool calls automatically)- self.ccr_response_handler = (- CCRResponseHandler(- ResponseHandlerConfig(- enabled=True,- max_retrieval_rounds=config.ccr_max_retrieval_rounds,- )- )- if config.ccr_handle_responses- else None- )-- # CCR Context Tracker (tracks compressed content across turns)- self.ccr_context_tracker = (- ContextTracker(- ContextTrackerConfig(- enabled=True,- proactive_expansion=config.ccr_proactive_expansion,- max_proactive_expansions=config.ccr_max_proactive_expansions,- )- )- if config.ccr_context_tracking- else None- )-- # Turn counter for context tracking- self._turn_counter = 0-- # Memory Handler (persistent user memory)- self.memory_handler: MemoryHandler | None = None- if config.memory_enabled:- # Resolve memory DB path: empty → project-scoped default- _mem_db_path = config.memory_db_path- if not _mem_db_path:- _mem_dir = Path.cwd() / ".headroom"- _mem_dir.mkdir(parents=True, exist_ok=True)- _mem_db_path = str(_mem_dir / "memory.db")- logger.info(f"Memory: Project-scoped DB at {_mem_db_path}")-- memory_config = MemoryConfig(- enabled=True,- backend=config.memory_backend,- db_path=_mem_db_path,- inject_tools=config.memory_inject_tools,- use_native_tool=config.memory_use_native_tool,- inject_context=config.memory_inject_context,- top_k=config.memory_top_k,- min_similarity=config.memory_min_similarity,- qdrant_host=config.memory_qdrant_host,- qdrant_port=config.memory_qdrant_port,- neo4j_uri=config.memory_neo4j_uri,- neo4j_user=config.memory_neo4j_user,- neo4j_password=config.memory_neo4j_password,- bridge_enabled=config.memory_bridge_enabled,- bridge_md_paths=config.memory_bridge_md_paths,- bridge_md_format=config.memory_bridge_md_format,- bridge_auto_import=config.memory_bridge_auto_import,- bridge_export_path=config.memory_bridge_export_path,- )- self.memory_handler = MemoryHandler(- memory_config,- agent_type=config.traffic_learning_agent_type,- )-- # Usage Reporter (license validation + phone-home for managed/enterprise)- self.usage_reporter: UsageReporter | None = None- if config.license_key:- from headroom.telemetry.reporter import UsageReporter-- self.usage_reporter = UsageReporter(- license_key=config.license_key,- cloud_url=config.license_cloud_url,- report_interval=config.license_report_interval,- )-- # Traffic Learner (live pattern extraction from proxy traffic)- # Only activates with --learn flag; requires --memory for backend- self.traffic_learner: TrafficLearner | None = None- self.traffic_learning_agent_type: str = config.traffic_learning_agent_type- if config.traffic_learning_enabled:- from headroom.memory.traffic_learner import TrafficLearner-- self.traffic_learner = TrafficLearner(- user_id=os.environ.get("HEADROOM_USER_ID", os.environ.get("USER", "default")),- agent_type=config.traffic_learning_agent_type,- )-- # Code graph file watcher (live reindex on file changes)- self.code_graph_watcher: CodeGraphWatcher | None = None # type: ignore[annotation-unchecked]- if config.code_graph_watcher:- from headroom.graph.watcher import CodeGraphWatcher-- self.code_graph_watcher = CodeGraphWatcher(project_dir=Path.cwd())- if self.code_graph_watcher.start():- logger.info("Code graph: file watcher started")- else:- self.code_graph_watcher = None-- self.pipeline_extensions.emit(- PipelineStage.SETUP,- operation="proxy.setup",- metadata={- "mode": self.config.mode,- "optimize": self.config.optimize,- "backend": self.config.backend,- "memory_enabled": self.config.memory_enabled,- },- )-- def _get_compression_cache(self, session_id: str) -> CompressionCache:- """Get or create a CompressionCache for a session."""- if session_id not in self._compression_caches:- from headroom.cache.compression_cache import CompressionCache-- # Evict oldest caches if at capacity- if len(self._compression_caches) >= MAX_COMPRESSION_CACHE_SESSIONS:- # Remove oldest quarter to amortize cleanup cost- oldest_keys = list(self._compression_caches.keys())[- : MAX_COMPRESSION_CACHE_SESSIONS // 4- ]- for key in oldest_keys:- del self._compression_caches[key]- logger.info(- "Evicted %d compression caches (exceeded %d max sessions)",- len(oldest_keys),- MAX_COMPRESSION_CACHE_SESSIONS,- )-- self._compression_caches[session_id] = CompressionCache()- return self._compression_caches[session_id]-- def _setup_code_aware(self, config: ProxyConfig, transforms: list) -> str:- """Set up code-aware compression if enabled.-- Args:- config: Proxy configuration- transforms: Transform list to append to-- Returns:- Status string for logging: 'enabled', 'disabled', 'available', 'unavailable'- """- if config.code_aware_enabled:- if is_tree_sitter_available():- code_config = CodeCompressorConfig(- preserve_imports=True,- preserve_signatures=True,- preserve_type_annotations=True,- )- # Insert before RollingWindow (which should be last)- transforms.insert(-1, CodeAwareCompressor(code_config))- return "enabled"- else:- logger.warning(- "Code-aware compression requested but tree-sitter not installed. "- "Install with: pip install headroom-ai[code]"- )- return "unavailable"- else:- if is_tree_sitter_available():- return "available" # Available but not enabled- return "disabled"-- async def startup(self):- """Initialize async resources."""- self.pipeline_extensions.emit(- PipelineStage.PRE_START,- operation="proxy.startup",- metadata={"port": self.config.port, "host": self.config.host},- )- self.http_client = httpx.AsyncClient(- timeout=httpx.Timeout(- connect=self.config.connect_timeout_seconds,- read=self.config.request_timeout_seconds,- write=self.config.request_timeout_seconds,- pool=self.config.connect_timeout_seconds,- ),- limits=httpx.Limits(- max_connections=self.config.max_connections,- max_keepalive_connections=self.config.max_keepalive_connections,- ),- http2=self.config.http2,- )- logger.info("Headroom Proxy started")- logger.info(f"Optimization: {'ENABLED' if self.config.optimize else 'DISABLED'}")- self.config.mode = normalize_proxy_mode(self.config.mode)- logger.info(f"Mode: {self.config.mode}")- if self.config.mode == PROXY_MODE_TOKEN:- logger.info(" Prefix freeze: re-freeze after compression")- logger.info(" Read protection window: 30%% of excluded-tool messages")- logger.info(" CCR TTL: extended for session lifetime")- logger.info(" Compression cache: active")- if self.config.mode == PROXY_MODE_CACHE:- logger.info(" Prefix freeze: strict (all prior turns immutable)")- logger.info(" Mutations: latest turn only")- logger.info(f"Caching: {'ENABLED' if self.config.cache_enabled else 'DISABLED'}")- logger.info(f"Rate Limiting: {'ENABLED' if self.config.rate_limit_enabled else 'DISABLED'}")- logger.info(- f"Connection Pool: max_connections={self.config.max_connections}, "- f"max_keepalive={self.config.max_keepalive_connections}, "- f"http2={'ENABLED' if self.config.http2 else 'DISABLED'}"- )-- # Unit 4 pre-upstream concurrency announcement. Report the resolved- # value (auto-detected vs. explicit) so operators can correlate- # ``pre_upstream_wait_ms`` log lines with the configured cap.- if self.anthropic_pre_upstream_sem is None:- logger.info("Anthropic pre-upstream concurrency: unbounded (explicitly disabled)")- else:- _explicit = self.config.anthropic_pre_upstream_concurrency- _origin = "auto-detected" if _explicit is None else "explicit"- logger.info(- "Anthropic pre-upstream concurrency: %d (%s)",- self.anthropic_pre_upstream_concurrency,- _origin,- )- logger.info(- "Anthropic pre-upstream timeouts: acquire=%.1fs compression=%.1fs memory_context=%.1fs",- self.anthropic_pre_upstream_acquire_timeout_seconds,- float(COMPRESSION_TIMEOUT_SECONDS),- self.anthropic_pre_upstream_memory_context_timeout_seconds,- )-- # Smart routing status- if self.config.smart_routing:- logger.info("Smart Routing: ENABLED (intelligent content detection)")- else:- logger.info("Smart Routing: DISABLED (legacy sequential mode)")-- # Eagerly load ALL compressors, parsers, and detectors at startup- # This eliminates cold-start latency spikes on first requests.- # Iterate BOTH pipelines (Anthropic + OpenAI) and dedupe transforms- # by id() so shared-transform instances never load twice. The- # resulting status dict is merged into ``self.warmup`` so /debug/warmup- # (Unit 5) and /readyz have a single source of truth.- self._kompress_status = "not installed"- eager_status: dict[str, str] = {}-- if self.config.optimize:- logger.info("Pre-loading compressors and parsers...")- seen_transform_ids: set[int] = set()- pipelines = (self.anthropic_pipeline, self.openai_pipeline)- for pipeline in pipelines:- for transform in pipeline.transforms:- if id(transform) in seen_transform_ids:- continue- seen_transform_ids.add(id(transform))- if not hasattr(transform, "eager_load_compressors"):- continue- try:- transform_status = transform.eager_load_compressors()- except Exception as exc:- logger.warning(- "Eager preload failed for %s: %s",- type(transform).__name__,- exc,- )- continue- if not isinstance(transform_status, dict):- continue- # Merge: later writers win only if the key wasn't set.- # Preload a transform ONCE — if another pipeline also has- # ``eager_load_compressors`` it contributes only new keys.- for key, value in transform_status.items():- eager_status.setdefault(key, value)- self.warmup.merge_transform_status(transform_status)-- # Update internal status from eager loading results- if eager_status.get("kompress") == "enabled":- self._kompress_status = "enabled"- if eager_status.get("code_aware") == "enabled":- self._code_aware_status = "enabled"-- # Log component status- if self._kompress_status == "enabled":- logger.info("Kompress: ENABLED (ModernBERT token compressor)")- elif self.config.optimize:- logger.info("Kompress: not installed (pip install headroom-ai[ml] for ML compression)")-- if self._code_aware_status == "enabled":- logger.info("Code-Aware: ENABLED (AST-based compression)")- if "tree_sitter" in eager_status:- logger.info(f"Tree-Sitter: {eager_status['tree_sitter']}")- elif self._code_aware_status == "lazy":- logger.info("Code-Aware: LAZY (will load when code content detected)")- elif self._code_aware_status == "available":- logger.info("Code-Aware: available but disabled (use --code-aware)")- elif self._code_aware_status == "unavailable":- logger.info("Code-Aware: not installed (pip install headroom-ai[code])")- elif self._code_aware_status == "disabled":- logger.info("Code-Aware: DISABLED")-- if eager_status.get("magika") == "enabled":- logger.info("Magika: ENABLED (ML content detection)")-- if self.memory_handler:- self.warmup.memory_backend.mark_loading()- try:- await self.memory_handler.ensure_initialized()- except Exception as exc: # pragma: no cover - defensive- self.warmup.memory_backend.mark_error(str(exc))- logger.warning("Memory: backend initialization failed (startup continues): %s", exc)- memory_status = self.memory_handler.health_status()- if memory_status.get("initialized"):- self.warmup.memory_backend.mark_loaded(- handle=self.memory_handler,- backend=memory_status.get("backend"),- )- # Force one embed call so the ONNX graph is compiled now,- # not lazily during the first request. Best-effort — any- # failure is swallowed inside warmup_embedder.- self.warmup.memory_embedder.mark_loading()- warmed = await self.memory_handler.warmup_embedder()- if warmed:- self.warmup.memory_embedder.mark_loaded()- else:- # Not an error — e.g. qdrant-neo4j has no embedder slot- # we can reach, or the backend simply exposes no handle.- self.warmup.memory_embedder.mark_null()- else:- if self.warmup.memory_backend.status != "error":- self.warmup.memory_backend.mark_null()- self.warmup.memory_embedder.mark_null()- logger.info(- "Memory: ENABLED "- f"(backend={memory_status['backend']}, initialized={memory_status['initialized']})"- )- else:- logger.info("Memory: DISABLED")-- # CCR status- ccr_features = []- if self.config.ccr_inject_tool:- ccr_features.append("tool_injection")- if self.config.ccr_handle_responses:- ccr_features.append("response_handling")- if self.config.ccr_context_tracking:- ccr_features.append("context_tracking")- if self.config.ccr_proactive_expansion:- ccr_features.append("proactive_expansion")- if ccr_features:- logger.info(f"CCR (Compress-Cache-Retrieve): ENABLED ({', '.join(ccr_features)})")- else:- logger.info("CCR: DISABLED")- logger.info(f"Savings history: {self.metrics.savings_tracker.storage_path}")-- # Reset and rebuild the quota tracker registry for this server instance.- # reset_quota_registry() ensures a clean slate when the proxy is restarted- # (e.g. in tests that spin up multiple app instances in the same process).- reset_quota_registry()- registry = get_quota_registry()- tracker = configure_subscription_tracker(- poll_interval_s=self.config.subscription_poll_interval_s,- active_window_s=self.config.subscription_active_window_s,- enabled=self.config.subscription_tracking_enabled,- )- registry.register(tracker)- registry.register(get_codex_rate_limit_state())- registry.register(get_copilot_quota_tracker())- await registry.start_all()-- if self.config.subscription_tracking_enabled:- logger.info(- "Subscription tracking: ENABLED "- f"(poll_interval={self.config.subscription_poll_interval_s}s, "- f"active_window={self.config.subscription_active_window_s}s)"- )- else:- logger.info("Subscription tracking: DISABLED")-- copilot_tracker = get_copilot_quota_tracker()- if copilot_tracker.is_available():- logger.info("GitHub Copilot quota tracking: ENABLED")- else:- logger.info(- "GitHub Copilot quota tracking: DISABLED "- "(set GITHUB_TOKEN or GITHUB_COPILOT_GITHUB_TOKEN to enable)"- )-- # Log anonymous telemetry status so operators can see it in the log stream- if is_telemetry_enabled():- logger.info(- "Anonymous telemetry: ENABLED (aggregate stats only — no prompts or content). "- "Opt out: HEADROOM_TELEMETRY=off or --no-telemetry"- )- else:- logger.info("Anonymous telemetry: DISABLED")-- self.pipeline_extensions.emit(- PipelineStage.POST_START,- operation="proxy.startup",- metadata={- "port": self.config.port,- "host": self.config.host,- "warmup": self.warmup.to_dict(),- },- )-- async def shutdown(self):- """Cleanup async resources."""- if self.http_client:- await self.http_client.aclose()- self.http_client = None-- if self.memory_handler and hasattr(self.memory_handler, "close"):- await self.memory_handler.close()-- # Stop all quota trackers via the registry- await get_quota_registry().stop_all()-- # Print final stats- self._print_summary()-- def _print_summary(self):- """Print session summary."""- m = self.metrics- logger.info("=" * 70)- logger.info("HEADROOM PROXY SESSION SUMMARY")- logger.info("=" * 70)- logger.info(f"Total requests: {m.requests_total}")- logger.info(f"Cached responses: {m.requests_cached}")- logger.info(f"Rate limited: {m.requests_rate_limited}")- logger.info(f"Failed: {m.requests_failed}")- logger.info(f"Input tokens: {m.tokens_input_total:,}")- logger.info(f"Output tokens: {m.tokens_output_total:,}")- logger.info(f"Tokens saved: {m.tokens_saved_total:,}")- if m.tokens_input_total > 0:- savings_pct = (- m.tokens_saved_total / (m.tokens_input_total + m.tokens_saved_total)- ) * 100- logger.info(f"Token savings: {savings_pct:.1f}%")- if m.latency_count > 0:- avg_latency = m.latency_sum_ms / m.latency_count- logger.info(f"Avg latency: {avg_latency:.0f}ms")- logger.info("=" * 70)-- async def _next_request_id(self) -> str:- """Generate unique request ID."""- async with self._request_counter_lock:- self._request_counter += 1- return f"hr_{int(time.time())}_{self._request_counter:06d}"-- def _extract_tags(self, headers: dict) -> dict[str, str]:- """Extract Headroom tags from headers."""- tags = {}- for key, value in headers.items():- if key.lower().startswith("x-headroom-"):- tag_name = key.lower().replace("x-headroom-", "")- tags[tag_name] = value- return tags-- def _inject_system_context(- self,- messages: list[dict[str, Any]],- context: str,- body: dict[str, Any] | None = None,- ) -> list[dict[str, Any]]:- """Inject context into the system message/parameter.-- For Anthropic API: Uses top-level 'system' parameter (not messages array).- For OpenAI API: Uses system role in messages array.-- Args:- messages: The messages list.- context: Context to inject.- body: Optional request body to update system parameter (for Anthropic).-- Returns:- Updated messages list.- """- messages = list(messages) # Copy to avoid mutation-- # For Anthropic API: use top-level 'system' parameter- if body is not None:- existing_system = body.get("system", "")- if isinstance(existing_system, str):- body["system"] = (existing_system + "\n\n" + context).strip()- elif isinstance(existing_system, list):- # system is a list of content blocks (e.g., with cache_control).- # Append memory context as a new text block — never overwrite.- body["system"] = existing_system + [{"type": "text", "text": context}]- else:- # No existing system prompt — set as string- body["system"] = context- return messages-- # For OpenAI API: use system role in messages- for i, msg in enumerate(messages):- if msg.get("role") == "system":- content = msg.get("content", "")- if isinstance(content, str):- messages[i] = {**msg, "content": content + "\n\n" + context}- return messages-- # No system message found - prepend one- messages.insert(0, {"role": "system", "content": context})- return messages-- async def _retry_request(- self,- method: str,- url: str,- headers: dict,- body: dict,- stream: bool = False,- ) -> httpx.Response:- """Make request with retry and exponential backoff."""- last_error = None-- for attempt in range(self.config.retry_max_attempts):- try:- if stream:- # For streaming, we return early - retry happens at higher level- return await self.http_client.post(url, json=body, headers=headers) # type: ignore[union-attr]- else:- response = await self.http_client.post(url, json=body, headers=headers) # type: ignore[union-attr]-- # Don't retry client errors (4xx)- if 400 <= response.status_code < 500:- return response-- # Retry server errors (5xx)- if response.status_code >= 500:- raise httpx.HTTPStatusError(- f"Server error: {response.status_code}",- request=response.request,- response=response,- )-- return response-- except (httpx.ConnectError, httpx.ReadTimeout, httpx.HTTPStatusError) as e:- last_error = e-- if not self.config.retry_enabled or attempt >= self.config.retry_max_attempts - 1:- raise-- # Exponential backoff with jitter- delay_with_jitter = jitter_delay_ms(- self.config.retry_base_delay_ms,- self.config.retry_max_delay_ms,- attempt,- )-- logger.warning(- f"Request failed (attempt {attempt + 1}), retrying in {delay_with_jitter:.0f}ms: {e}"- )- await asyncio.sleep(delay_with_jitter / 1000)-- raise last_error # type: ignore[misc]---async def _log_toin_stats_periodically(interval_seconds: int = 300) -> None:- """Background task that logs TOIN stats periodically.-- Args:- interval_seconds: How often to log stats (default: 5 minutes).- """- while True:- await asyncio.sleep(interval_seconds)- try:- toin = get_toin()- stats = toin.get_stats()- total_compressions = stats.get("total_compressions", 0)- if total_compressions > 0:- patterns = stats.get("patterns_tracked", 0)- retrievals = stats.get("total_retrievals", 0)- retrieval_rate = stats.get("global_retrieval_rate", 0.0)- logger.info(- "TOIN: %d patterns, %d compressions, %d retrievals, %.1f%% retrieval rate",- patterns,- total_compressions,- retrievals,- retrieval_rate * 100,- )- except Exception as e:- logger.debug("Failed to log TOIN stats: %s", e)---def _register_memory_components(proxy: HeadroomProxy, tracker: MemoryTracker) -> None:- """Register all memory-tracked components with the tracker.-- This function is idempotent - it checks if components are already registered.-- Args:- proxy: The HeadroomProxy instance.- tracker: The MemoryTracker instance.- """- # Register compression store (global singleton)- if "compression_store" not in tracker.registered_components:- store = get_compression_store()- tracker.register("compression_store", store.get_memory_stats)-- # Register semantic cache (instance on proxy)- if proxy.cache and "semantic_cache" not in tracker.registered_components:- tracker.register("semantic_cache", proxy.cache.get_memory_stats)-- # Register request logger (instance on proxy)- if proxy.logger and "request_logger" not in tracker.registered_components:- tracker.register("request_logger", proxy.logger.get_memory_stats)-- # Register batch context store (global singleton)- if "batch_context_store" not in tracker.registered_components:- try:- from ..ccr.batch_store import get_batch_context_store-- batch_store = get_batch_context_store()- if hasattr(batch_store, "get_memory_stats"):- tracker.register("batch_context_store", batch_store.get_memory_stats)- except ImportError:- pass-- # Note: graph_store and vector_index are created per-user within the- # LocalMemoryBackend, not as global singletons. They would need to be- # registered when the memory system is initialized with specific backends.---def create_app(config: ProxyConfig | None = None) -> FastAPI:- """Create FastAPI application."""- if not FASTAPI_AVAILABLE:- raise ImportError("FastAPI required. Install: pip install fastapi uvicorn httpx")-- from contextlib import asynccontextmanager-- config = config or ProxyConfig()- proxy = HeadroomProxy(config)-- # Telemetry beacon (anonymous aggregate stats).- # With uvicorn workers > 1, each worker runs the lifespan independently.- # We must ensure only ONE beacon runs across all workers — otherwise each- # worker creates its own beacon, spamming the telemetry table with N rows- # per cycle instead of 1 (all reading the same /stats from the same port).- #- # Strategy: use a file lock to ensure only the first worker starts the- # beacon. Other workers see the lock and skip.- from headroom.telemetry.beacon import TelemetryBeacon-- _beacon = TelemetryBeacon(- port=config.port if hasattr(config, "port") else 8787,- sdk=os.environ.get("HEADROOM_SDK", "proxy").strip() or "proxy",- backend=config.backend if hasattr(config, "backend") else "anthropic",- )- from headroom import paths as _hr_paths-- _beacon_lock_path = _hr_paths.beacon_lock_path(config.port)- _beacon_lock_fd: list = [None] # mutable holder for the lock file descriptor- _beacon_is_owner: list = [False]-- def _try_acquire_beacon_lock() -> bool:- """Try to acquire the beacon file lock (non-blocking).-- Returns True if this process is the beacon owner.- """- if not HAS_FCNTL:- return True-- fd = None- try:- _beacon_lock_path.parent.mkdir(parents=True, exist_ok=True)- fd = open(_beacon_lock_path, "w") # noqa: SIM115- fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)- fd.write(str(os.getpid()))- fd.flush()- _beacon_lock_fd[0] = fd- return True- except OSError:- if fd is not None:- fd.close()- return False-- def _release_beacon_lock() -> None:- """Release the beacon file lock."""- fd = _beacon_lock_fd[0]- if fd:- try:- if HAS_FCNTL:- fcntl.flock(fd, fcntl.LOCK_UN)- fd.close()- except Exception:- pass- _beacon_lock_fd[0] = None- try:- _beacon_lock_path.unlink(missing_ok=True)- except Exception:- pass-- @asynccontextmanager- async def lifespan(app: FastAPI): # type: ignore[no-untyped-def]- configure_otel_metrics(OTelMetricsConfig.from_env(default_service_name="headroom-proxy"))- configure_langfuse_tracing(- LangfuseTracingConfig.from_env(default_service_name="headroom-proxy")- )-- app.state.started_at = time.time()- app.state.ready = False- app.state.startup_error = None-- try:- try:- # Startup- await proxy.startup()- asyncio.create_task(_log_toin_stats_periodically())- if proxy.usage_reporter:- await proxy.usage_reporter.start(proxy)- if proxy.traffic_learner:- await proxy.traffic_learner.start()-- # Only start beacon if we acquire the lock (first worker wins)- _beacon_is_owner[0] = _try_acquire_beacon_lock()- if _beacon_is_owner[0]:- await _beacon.start()- else:- logger.debug("Beacon: skipping (another worker owns the lock)")-- app.state.ready = True- yield- except Exception as exc:- app.state.startup_error = str(exc)- raise- finally:- app.state.ready = False- # Shutdown- if _beacon_is_owner[0]:- await _beacon.stop()- _release_beacon_lock()- if proxy.usage_reporter:- await proxy.usage_reporter.stop()- if proxy.traffic_learner:- await proxy.traffic_learner.stop()- if proxy.code_graph_watcher:- proxy.code_graph_watcher.stop()- await proxy.shutdown()- shutdown_headroom_tracing()- shutdown_otel_metrics()-- app = FastAPI(- title="Headroom Proxy",- description="Production-ready LLM optimization proxy",- version=__version__,- lifespan=lifespan,- )- app.state.proxy = proxy- app.state.started_at = None- app.state.ready = False- app.state.startup_error = None-- def _iso_utc_now() -> str:- return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")-- def _uptime_seconds() -> float:- started_at = getattr(app.state, "started_at", None)- if not isinstance(started_at, int | float):- return 0.0- return round(max(0.0, time.time() - float(started_at)), 3)-- def _component_health(- *,- enabled: bool,- ready: bool,- **details: Any,- ) -> dict[str, Any]:- status = "disabled" if not enabled else ("healthy" if ready else "unhealthy")- return {- "enabled": enabled,- "ready": (ready if enabled else True),- "status": status,- **details,- }-- def _health_checks() -> dict[str, dict[str, Any]]:- memory_status = (- proxy.memory_handler.health_status()- if proxy.memory_handler- else {- "enabled": False,- "backend": None,- "initialized": False,- "native_tool": False,- "bridge_enabled": False,- }- )- memory_enabled = bool(memory_status.get("enabled", False))- memory_initialized = bool(memory_status.get("initialized", False))- return {- "startup": _component_health(- enabled=True,- ready=bool(getattr(app.state, "ready", False)),- error=getattr(app.state, "startup_error", None),- ),- "http_client": _component_health(- enabled=True,- ready=proxy.http_client is not None,- ),- "cache": _component_health(- enabled=config.cache_enabled,- ready=(proxy.cache is not None),- ),- "rate_limiter": _component_health(- enabled=config.rate_limit_enabled,- ready=(proxy.rate_limiter is not None),- ),- "memory": _component_health(- enabled=memory_enabled,- ready=memory_initialized,- backend=memory_status["backend"],- initialized=memory_initialized,- native_tool=bool(memory_status.get("native_tool", False)),- bridge_enabled=bool(memory_status.get("bridge_enabled", False)),- ),- }-- def _runtime_payload() -> dict[str, Any]:- ws_registry = getattr(proxy, "ws_sessions", None)- ws_active_sessions = ws_registry.active_count() if ws_registry is not None else 0- ws_active_relay_tasks = (- ws_registry.active_relay_task_count() if ws_registry is not None else 0- )- return {- "anthropic_pre_upstream": {- "enabled": proxy.anthropic_pre_upstream_sem is not None,- "resolved_concurrency": proxy.anthropic_pre_upstream_concurrency,- "source": (- "auto" if config.anthropic_pre_upstream_concurrency is None else "explicit"- ),- "acquire_timeout_seconds": proxy.anthropic_pre_upstream_acquire_timeout_seconds,- "compression_timeout_seconds": float(COMPRESSION_TIMEOUT_SECONDS),- "memory_context_timeout_seconds": (- proxy.anthropic_pre_upstream_memory_context_timeout_seconds- ),- "codex_ws_gated": False,- },- "websocket_sessions": {- "active_sessions": ws_active_sessions,- "active_relay_tasks": ws_active_relay_tasks,- },- }-- def _health_payload(*, include_config: bool) -> dict[str, Any]:- checks = _health_checks()- ready = all(check["ready"] for check in checks.values())- payload: dict[str, Any] = {- "service": "headroom-proxy",- "status": "healthy" if ready else "unhealthy",- "ready": ready,- "version": __version__,- "timestamp": _iso_utc_now(),- "uptime_seconds": _uptime_seconds(),- "checks": checks,- "runtime": _runtime_payload(),- }- deployment_profile = os.environ.get("HEADROOM_DEPLOYMENT_PROFILE")- if deployment_profile:- payload["deployment"] = {- "profile": deployment_profile,- "preset": os.environ.get("HEADROOM_DEPLOYMENT_PRESET"),- "runtime": os.environ.get("HEADROOM_DEPLOYMENT_RUNTIME"),- "supervisor": os.environ.get("HEADROOM_DEPLOYMENT_SUPERVISOR"),- "scope": os.environ.get("HEADROOM_DEPLOYMENT_SCOPE"),- }- if include_config:- payload["config"] = {- "backend": config.backend,- "optimize": config.optimize,- "cache": config.cache_enabled,- "rate_limit": config.rate_limit_enabled,- "memory": config.memory_enabled,- "learn": config.traffic_learning_enabled,- "code_graph": config.code_graph_watcher,- "pid": os.getpid(),- }- return payload-- # CORS- app.add_middleware(- CORSMiddleware,- allow_origins=["*"],- allow_credentials=True,- allow_methods=["*"],- allow_headers=["*"],- )-- # X-Headroom-Stack: SDK adapters (TS openai/anthropic/etc.) tag their- # requests so telemetry can segment by integration surface. Registered- # before extension middleware so any extension-level auth/guards run- # outermost and we don't count requests they reject.- @app.middleware("http")- async def _record_headroom_stack(request, call_next):- if request.url.path.startswith("/v1/"):- stack = request.headers.get("x-headroom-stack")- if stack:- try:- proxy.metrics.record_stack(stack)- except Exception:- logger.debug("record_stack failed", exc_info=True)- return await call_next(request)-- # Third-party proxy extensions (Enterprise, custom plugins). Discovered via- # the `headroom.proxy_extension` entry-point group. An extension that raises- # from its install() is a deliberate fail-closed signal and aborts startup.- from headroom.proxy.extensions import install_all as _install_extensions-- _install_extensions(app, config)-- # Health & Metrics- @app.get("/livez")- async def livez():- return JSONResponse(- status_code=200,- content={- "service": "headroom-proxy",- "status": "healthy",- "alive": True,- "version": __version__,- "timestamp": _iso_utc_now(),- "uptime_seconds": _uptime_seconds(),- },- )-- @app.get("/readyz")- async def readyz():- payload = _health_payload(include_config=False)- return JSONResponse(status_code=200 if payload["ready"] else 503, content=payload)-- @app.get("/health")- async def health():- payload = _health_payload(include_config=True)- return JSONResponse(status_code=200, content=payload)-- # Loopback-only debug introspection (Unit 5). A remote IP gets 404 —- # debug endpoints are invisible to external scanners.- from headroom.proxy.debug_introspection import (- collect_tasks as _collect_tasks,- )- from headroom.proxy.loopback_guard import require_loopback as _require_loopback-- @app.get("/debug/tasks", dependencies=[Depends(_require_loopback)])- async def debug_tasks(stack: bool = False):- """Enumerate running asyncio tasks.-- Default is cheap — ``stack_depth`` is ``null`` in every entry so- a storm snapshot does not walk 50+ coroutine frames synchronously.- Pass ``?stack=true`` to compute ``stack_depth`` for each task- (useful for single-shot human debugging).- """- ws_registry = getattr(proxy, "ws_sessions", None)- return JSONResponse(- status_code=200,- content=_collect_tasks(ws_registry, with_stack_depth=stack),- )-- @app.get("/debug/ws-sessions", dependencies=[Depends(_require_loopback)])- async def debug_ws_sessions():- ws_registry = getattr(proxy, "ws_sessions", None)- snapshot = ws_registry.snapshot() if ws_registry is not None else []- return JSONResponse(status_code=200, content=snapshot)-- @app.get("/debug/warmup", dependencies=[Depends(_require_loopback)])- async def debug_warmup():- warmup_registry = getattr(proxy, "warmup", None)- payload = warmup_registry.to_dict() if warmup_registry is not None else {}- payload["runtime"] = _runtime_payload()- return JSONResponse(status_code=200, content=payload)-- @app.get("/dashboard", response_class=HTMLResponse)- async def dashboard():- """Serve the Headroom dashboard UI."""- return get_dashboard_html()-- DASHBOARD_STATS_CACHE_TTL_SECONDS = 5.0- _stats_snapshot_lock = asyncio.Lock()- _stats_snapshot: dict[str, Any] = {"expires_at": 0.0, "value": None}-- async def _build_stats_payload() -> dict[str, Any]:- """Build the full `/stats` response payload.-- This is the main stats endpoint - it aggregates data from all subsystems:- - Request metrics (total, cached, failed, by model/provider)- - Token usage and savings- - Cost tracking- - Canonical persisted display_session metrics for downstream dashboards- - Compression (CCR) statistics- - Telemetry/TOIN (data flywheel) statistics- - Cache and rate limiter stats- """- m = proxy.metrics-- # Calculate average latency- avg_latency_ms = round(m.latency_sum_ms / m.latency_count, 2) if m.latency_count > 0 else 0- min_latency_ms = (- round(m.latency_min_ms, 2)- if m.latency_count > 0 and m.latency_min_ms != float("inf")- else 0- )- max_latency_ms = round(m.latency_max_ms, 2) if m.latency_count > 0 else 0-- # Calculate Headroom overhead (optimization time only, excludes pass-through requests)- avg_overhead_ms = (- round(m.overhead_sum_ms / m.overhead_count, 2) if m.overhead_count > 0 else 0- )- min_overhead_ms = (- round(m.overhead_min_ms, 2)- if m.overhead_count > 0 and m.overhead_min_ms != float("inf")- else 0- )- max_overhead_ms = round(m.overhead_max_ms, 2) if m.overhead_count > 0 else 0-- # Calculate TTFB (time to first byte)- avg_ttfb_ms = round(m.ttfb_sum_ms / m.ttfb_count, 2) if m.ttfb_count > 0 else 0- min_ttfb_ms = (- round(m.ttfb_min_ms, 2) if m.ttfb_count > 0 and m.ttfb_min_ms != float("inf") else 0- )- max_ttfb_ms = round(m.ttfb_max_ms, 2) if m.ttfb_count > 0 else 0-- # Get compression store stats- store = get_compression_store()- compression_stats = store.get_stats()-- # Get telemetry/TOIN stats- telemetry = get_telemetry_collector()- telemetry_stats = telemetry.get_stats()-- # Get feedback loop stats- feedback = get_compression_feedback()- feedback_stats = feedback.get_stats()-- # 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()- cli_tokens_avoided = (- cli_filtering_stats.get("tokens_saved", 0) if cli_filtering_stats else 0- )-- # Calculate total tokens before compression- total_tokens_before = m.tokens_input_total + m.tokens_saved_total-- # Build human-readable summary- summary = _build_session_summary(- proxy, m, prefix_cache_stats, cli_tokens_avoided, total_tokens_before- )- # DEBUG: log the summary payload for external upsert consumers- try:- logger.debug("/stats summary data: %r", summary)- except Exception:- logger.warning("Failed to log /stats summary payload")-- # Compression cache stats (token mode)- compression_cache_stats: dict = {}- if proxy.config.mode == PROXY_MODE_TOKEN and proxy._compression_caches:- total_entries = 0- total_hits = 0- total_misses = 0- total_tokens_saved = 0- for cache in proxy._compression_caches.values():- s = cache.get_stats()- total_entries += s.get("entries", 0)- total_hits += s.get("hits", 0)- total_misses += s.get("misses", 0)- total_tokens_saved += s.get("total_tokens_saved", 0)- compression_cache_stats = {- "mode": PROXY_MODE_TOKEN,- "active_sessions": len(proxy._compression_caches),- "total_entries": total_entries,- "total_hits": total_hits,- "total_misses": total_misses,- "hit_rate": round(total_hits / max(1, total_hits + total_misses) * 100, 1),- "total_tokens_saved": total_tokens_saved,- }- else:- compression_cache_stats = {"mode": proxy.config.mode}-- # Build unified savings summary (all layers)- compression_tokens = m.tokens_saved_total- cache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)- total_tokens_all_layers = compression_tokens + cli_tokens_avoided- persistent_savings = m.savings_tracker.stats_preview()- display_session = persistent_savings.get("display_session", {})-- return {- "summary": summary,- "savings": {- "total_tokens": total_tokens_all_layers,- "by_layer": {- "cli_filtering": {- "tokens": cli_tokens_avoided,- "description": "Tokens avoided by CLI output filtering (rtk) before reaching context",- },- "compression": {- "tokens": compression_tokens,- "description": "Tokens removed by proxy compression (SmartCrusher, ContentRouter, etc.)",- },- "prefix_cache": {- "discount_usd": round(cache_net_usd, 4),- "description": (- "Cost discount from provider prefix caching. "- "Headroom's CacheAligner improves hit rates; "- "baseline caching is provider-native."- ),- },- },- },- "requests": {- "total": m.requests_total,- "cached": m.requests_cached,- "rate_limited": m.requests_rate_limited,- "failed": m.requests_failed,- "by_provider": dict(m.requests_by_provider),- "by_model": dict(m.requests_by_model),- "by_stack": dict(m.requests_by_stack),- },- "tokens": {- "input": m.tokens_input_total,- "output": m.tokens_output_total,- "saved": m.tokens_saved_total,- "cli_tokens_avoided": cli_tokens_avoided,- "total_before_compression": total_tokens_before,- "savings_percent": round(- (m.tokens_saved_total / total_tokens_before * 100)- if total_tokens_before > 0- else 0,- 2,- ),- },- "latency": {- "average_ms": avg_latency_ms,- "min_ms": min_latency_ms,- "max_ms": max_latency_ms,- "total_requests": m.latency_count,- },- "overhead": {- "average_ms": avg_overhead_ms,- "min_ms": min_overhead_ms,- "max_ms": max_overhead_ms,- },- "ttfb": {- "average_ms": avg_ttfb_ms,- "min_ms": min_ttfb_ms,- "max_ms": max_ttfb_ms,- },- "pipeline_timing": {- name: {- "average_ms": round(- m.transform_timing_sum[name] / m.transform_timing_count[name], 2- ),- "max_ms": round(m.transform_timing_max[name], 2),- "count": m.transform_timing_count[name],- }- for name in sorted(m.transform_timing_sum.keys())- }- if m.transform_timing_sum- else {},- "waste_signals": dict(m.waste_signals_total) if m.waste_signals_total else {},- "savings_history": m.savings_history[-100:], # Last 100 data points- "display_session": display_session,- "persistent_savings": persistent_savings,- "prefix_cache": prefix_cache_stats,- "cost": _merge_cost_stats(- proxy.cost_tracker.stats() if proxy.cost_tracker else None,- prefix_cache_stats,- cli_tokens_avoided=cli_tokens_avoided,- ),- "compression": {- "ccr_entries": compression_stats.get("entry_count", 0),- "ccr_max_entries": compression_stats.get("max_entries", 0),- "original_tokens_cached": compression_stats.get("total_original_tokens", 0),- "compressed_tokens_cached": compression_stats.get("total_compressed_tokens", 0),- "ccr_retrievals": compression_stats.get("total_retrievals", 0),- },- "compression_cache": compression_cache_stats,- "anon_telemetry_shipping": is_telemetry_enabled(),- "telemetry": {- "enabled": telemetry_stats.get("enabled", False),- "total_compressions": telemetry_stats.get("total_compressions", 0),- "total_retrievals": telemetry_stats.get("total_retrievals", 0),- "global_retrieval_rate": round(telemetry_stats.get("global_retrieval_rate", 0), 4),- "tool_signatures_tracked": telemetry_stats.get("tool_signatures_tracked", 0),- "avg_compression_ratio": round(telemetry_stats.get("avg_compression_ratio", 0), 4),- "avg_token_reduction": round(telemetry_stats.get("avg_token_reduction", 0), 4),- },- "otel": get_otel_metrics_status(),- "langfuse": get_langfuse_tracing_status(),- "feedback_loop": {- "tools_tracked": feedback_stats.get("tools_tracked", 0),- "total_compressions": feedback_stats.get("total_compressions", 0),- "total_retrievals": feedback_stats.get("total_retrievals", 0),- "global_retrieval_rate": round(feedback_stats.get("global_retrieval_rate", 0), 4),- "tools_with_high_retrieval": sum(- 1- for p in feedback_stats.get("tool_patterns", {}).values()- if p.get("retrieval_rate", 0) > 0.3- ),- },- "toin": get_toin().get_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,- "recent_requests": proxy.logger.get_recent(10) if proxy.logger else [],- "log_full_messages": proxy.config.log_full_messages if proxy else False,- **get_quota_registry().get_all_stats(),- }-- async def _get_cached_stats_payload() -> dict[str, Any]:- """Return a short-TTL cached `/stats` snapshot for dashboard polling."""- now = time.monotonic()- cached_payload = cast(dict[str, Any] | None, _stats_snapshot.get("value"))- if cached_payload is not None and now < float(_stats_snapshot["expires_at"]):- return cached_payload-- async with _stats_snapshot_lock:- now = time.monotonic()- cached_payload = cast(dict[str, Any] | None, _stats_snapshot.get("value"))- if cached_payload is not None and now < float(_stats_snapshot["expires_at"]):- return cached_payload-- payload = await _build_stats_payload()- _stats_snapshot["value"] = payload- _stats_snapshot["expires_at"] = time.monotonic() + DASHBOARD_STATS_CACHE_TTL_SECONDS- return payload-- @app.get("/stats")- async def stats(cached: bool = False):- """Get comprehensive proxy statistics.-- This is the main stats endpoint - it aggregates data from all subsystems:- - Request metrics (total, cached, failed, by model/provider)- - Token usage and savings- - Cost tracking- - Canonical persisted display_session metrics for downstream dashboards- - Compression (CCR) statistics- - Telemetry/TOIN (data flywheel) statistics- - Cache and rate limiter stats-- Use ``?cached=1`` for the dashboard fast path. That returns a short-TTL- snapshot to avoid rebuilding the full payload on every UI poll.- """- if cached:- return await _get_cached_stats_payload()- return await _build_stats_payload()-- @app.get("/stats-history")- async def stats_history(- format: Literal["json", "csv"] = "json",- series: Literal["history", "hourly", "daily", "weekly", "monthly"] = "history",- history_mode: Literal["compact", "full", "none"] = "compact",- ):- """Get durable proxy compression history plus display-session state."""- if format == "csv":- filename = f"headroom-stats-history-{series}.csv"- return Response(- content=proxy.metrics.savings_tracker.export_csv(series=series),- media_type="text/csv; charset=utf-8",- headers={"Content-Disposition": f'attachment; filename="{filename}"'},- )-- return proxy.metrics.savings_tracker.history_response(history_mode=history_mode)-- @app.get("/transformations/feed")- async def transformations_feed(limit: int = 20):- """Get recent message transformations for the live feed.-- Returns empty list if log_full_messages is disabled (messages are not stored).- """- if limit > 100:- limit = 100-- transformations = []- log_full_messages = proxy.config.log_full_messages if proxy else False-- if proxy and proxy.logger:- logs = proxy.logger.get_recent_with_messages(limit)- for log in logs:- transformations.append(- {- "request_id": log.get("request_id"),- "timestamp": log.get("timestamp"),- "provider": log.get("provider"),- "model": log.get("model"),- "input_tokens_original": log.get("input_tokens_original"),- "input_tokens_optimized": log.get("input_tokens_optimized"),- "tokens_saved": log.get("tokens_saved"),- "savings_percent": log.get("savings_percent"),- "transforms_applied": log.get("transforms_applied", []),- "request_messages": log.get("request_messages"),- "response_content": log.get("response_content"),- "turn_id": log.get("turn_id"),- }- )-- return {"transformations": transformations, "log_full_messages": log_full_messages}-- @app.get("/subscription-window")- async def subscription_window():- """Current Anthropic subscription window utilisation and Headroom contribution."""- tracker = get_subscription_tracker()- if tracker is None:- return JSONResponse(- status_code=503,- content={"error": "Subscription tracking is not enabled"},- )- return JSONResponse(content=tracker.state)-- @app.get("/quota")- async def quota():- """Unified quota/rate-limit stats for all registered providers (Anthropic, Codex, Copilot)."""- return JSONResponse(content=get_quota_registry().get_all_stats())-- @app.get("/metrics")- async def metrics():- """Prometheus metrics endpoint."""- return PlainTextResponse(- await proxy.metrics.export(),- media_type="text/plain; version=0.0.4",- )-- # Debug endpoints- @app.get("/debug/memory")- async def debug_memory():- """Get detailed memory usage statistics.-- Returns memory usage for all tracked components including:- - Process-level memory (RSS, VMS, percent)- - Per-component memory usage and budgets- - Cache hit/miss statistics- - Total tracked vs target budget-- This endpoint is useful for debugging memory issues and- monitoring memory budgets.- """- from ..memory.tracker import MemoryTracker-- tracker = MemoryTracker.get()-- # Register components if not already registered- _register_memory_components(proxy, tracker)-- report = tracker.get_report()- return report.to_dict()-- @app.post("/cache/clear")- async def clear_cache():- """Clear the response cache."""- if proxy.cache:- await proxy.cache.clear()- return {"status": "cleared"}- return {"status": "cache disabled"}-- # CCR (Compress-Cache-Retrieve) endpoints- @app.post("/v1/retrieve")- async def ccr_retrieve(request: Request):- """Retrieve original content from CCR compression cache.-- This is the "Retrieve" part of CCR (Compress-Cache-Retrieve).- When SmartCrusher compresses tool outputs, the original data is cached.- LLMs can call this endpoint to get more data if needed.-- Request body:- hash (str): Hash key from compression marker (required)- query (str): Optional search query to filter results-- Response:- Full retrieval: {"hash": "...", "original_content": "...", ...}- Search: {"hash": "...", "query": "...", "results": [...], "count": N}- """- data = await request.json()- hash_key = data.get("hash")- query = data.get("query")-- if not hash_key:- raise HTTPException(status_code=400, detail="hash required")-- store = get_compression_store()-- if query:- # Search within cached content- results = store.search(hash_key, query)- return {- "hash": hash_key,- "query": query,- "results": results,- "count": len(results),- }- else:- # Return full original content- entry = store.retrieve(hash_key)- if entry:- return {- "hash": hash_key,- "original_content": entry.original_content,- "original_tokens": entry.original_tokens,- "original_item_count": entry.original_item_count,- "compressed_item_count": entry.compressed_item_count,- "tool_name": entry.tool_name,- "retrieval_count": entry.retrieval_count,- }- raise HTTPException(- status_code=404, detail="Entry not found or expired (TTL: 5 minutes)"- )-- @app.get("/v1/retrieve/stats")- async def ccr_stats():- """Get CCR compression store statistics."""- store = get_compression_store()- stats = store.get_stats()- events = store.get_retrieval_events(limit=20)- return {- "store": stats,- "recent_retrievals": [- {- "hash": e.hash,- "query": e.query,- "items_retrieved": e.items_retrieved,- "total_items": e.total_items,- "tool_name": e.tool_name,- "retrieval_type": e.retrieval_type,- }- for e in events- ],- }-- @app.get("/v1/feedback")- async def ccr_feedback():- """Get CCR feedback loop statistics and learned patterns.-- This endpoint exposes the feedback loop's learned patterns for monitoring- and debugging. It shows:- - Per-tool retrieval rates (high = compress less aggressively)- - Common search queries per tool- - Queried fields (suggest what to preserve)-- Use this to understand how well compression is working and whether- the feedback loop is adjusting appropriately.- """- feedback = get_compression_feedback()- stats = feedback.get_stats()- return {- "feedback": stats,- "hints_example": {- tool_name: {- "hints": {- "max_items": hints.max_items- if (hints := feedback.get_compression_hints(tool_name))- else 15,- "suggested_items": hints.suggested_items if hints else None,- "skip_compression": hints.skip_compression if hints else False,- "preserve_fields": hints.preserve_fields if hints else [],- "reason": hints.reason if hints else "",- }- }- for tool_name in list(stats.get("tool_patterns", {}).keys())[:5]- },- }-- @app.get("/v1/feedback/{tool_name}")- async def ccr_feedback_for_tool(tool_name: str):- """Get compression hints for a specific tool.-- Returns feedback-based hints that would be used for compressing- this tool's output.- """- feedback = get_compression_feedback()- hints = feedback.get_compression_hints(tool_name)- patterns = feedback.get_all_patterns().get(tool_name)-- return {- "tool_name": tool_name,- "hints": {- "max_items": hints.max_items,- "min_items": hints.min_items,- "suggested_items": hints.suggested_items,- "aggressiveness": hints.aggressiveness,- "skip_compression": hints.skip_compression,- "preserve_fields": hints.preserve_fields,- "reason": hints.reason,- },- "pattern": {- "total_compressions": patterns.total_compressions if patterns else 0,- "total_retrievals": patterns.total_retrievals if patterns else 0,- "retrieval_rate": patterns.retrieval_rate if patterns else 0.0,- "full_retrieval_rate": patterns.full_retrieval_rate if patterns else 0.0,- "search_rate": patterns.search_rate if patterns else 0.0,- "common_queries": list(patterns.common_queries.keys())[:10] if patterns else [],- "queried_fields": list(patterns.queried_fields.keys())[:10] if patterns else [],- }- if patterns- else None,- }-- # Telemetry endpoints (Data Flywheel)- @app.get("/v1/telemetry")- async def telemetry_stats():- """Get telemetry statistics for the data flywheel.-- This endpoint exposes privacy-preserving telemetry data that powers- the data flywheel - learning optimal compression strategies across- tool types based on usage patterns.-- What's collected (anonymized):- - Tool output structure patterns (field types, not values)- - Compression decisions and ratios- - Retrieval patterns (rate, type, not content)- - Strategy effectiveness-- What's NOT collected:- - Actual data values- - User identifiers- - Queries or search terms- - File paths or tool names (hashed by default)- """- telemetry = get_telemetry_collector()- return telemetry.get_stats()-- @app.get("/v1/telemetry/export")- async def telemetry_export():- """Export full telemetry data for aggregation.-- This endpoint exports all telemetry data in a format suitable for- cross-user aggregation. The data is privacy-preserving - no actual- values are included, only structural patterns and statistics.-- Use this for:- - Building a central learning service- - Sharing learned patterns across instances- - Analysis and debugging- """- telemetry = get_telemetry_collector()- return telemetry.export_stats()-- @app.post("/v1/telemetry/import")- async def telemetry_import(request: Request):- """Import telemetry data from another source.-- This allows merging telemetry from multiple sources for cross-user- learning. The imported data is merged with existing statistics.-- Request body: Telemetry export data from /v1/telemetry/export- """- telemetry = get_telemetry_collector()- data = await request.json()- telemetry.import_stats(data)- return {"status": "imported", "current_stats": telemetry.get_stats()}-- @app.get("/v1/telemetry/tools")- async def telemetry_tools():- """Get telemetry statistics for all tracked tool signatures.-- Returns statistics per tool signature (anonymized), including:- - Compression ratios and strategy usage- - Retrieval rates (high = compression too aggressive)- - Learned recommendations- """- telemetry = get_telemetry_collector()- all_stats = telemetry.get_all_tool_stats()- return {- "tool_count": len(all_stats),- "tools": {sig_hash: stats.to_dict() for sig_hash, stats in all_stats.items()},- }-- @app.get("/v1/telemetry/tools/{signature_hash}")- async def telemetry_tool_detail(signature_hash: str):- """Get detailed telemetry for a specific tool signature.-- Includes learned recommendations if enough data has been collected.- """- telemetry = get_telemetry_collector()- stats = telemetry.get_tool_stats(signature_hash)- recommendations = telemetry.get_recommendations(signature_hash)-- if stats is None:- raise HTTPException(- status_code=404, detail=f"No telemetry found for signature: {signature_hash}"- )-- return {- "signature_hash": signature_hash,- "stats": stats.to_dict(),- "recommendations": recommendations,- }-- # TOIN (Tool Output Intelligence Network) endpoints- @app.get("/v1/toin/stats")- async def toin_stats():- """Get overall TOIN statistics.-- Returns aggregated statistics from the Tool Output Intelligence Network,- which learns optimal compression strategies across all tool types.-- Response includes:- - enabled: Whether TOIN is enabled- - patterns_tracked: Number of unique tool patterns being tracked- - total_compressions: Total compression events recorded- - total_retrievals: Total retrieval events recorded- - global_retrieval_rate: Overall retrieval rate (high = compression too aggressive)- - patterns_with_recommendations: Patterns with enough data for recommendations- """- toin = get_toin()- return toin.get_stats()-- @app.get("/v1/toin/patterns")- async def toin_patterns(limit: int = 20):- """List TOIN patterns with most samples.-- Returns patterns sorted by sample_size descending. Use this to see- which tool types have the most data and their learned behaviors.-- Query params:- limit: Maximum number of patterns to return (default 20)-- Response includes for each pattern:- - hash: Truncated tool signature hash (12 chars)- - compressions: Total compression events- - retrievals: Total retrieval events- - retrieval_rate: Percentage of compressions that triggered retrieval- - confidence: Confidence level in recommendations (0.0-1.0)- - skip_recommended: Whether TOIN recommends skipping compression- - optimal_max_items: Learned optimal max_items setting- """- toin = get_toin()- exported = toin.export_patterns()- patterns_data = exported.get("patterns", {})-- # Convert to list and sort by sample_size- patterns_list = []- for sig_hash, pattern_dict in patterns_data.items():- sample_size = pattern_dict.get("sample_size", 0)- total_compressions = pattern_dict.get("total_compressions", 0)- total_retrievals = pattern_dict.get("total_retrievals", 0)- retrieval_rate = (- total_retrievals / total_compressions if total_compressions > 0 else 0.0- )-- patterns_list.append(- {- "hash": sig_hash[:12],- "compressions": total_compressions,- "retrievals": total_retrievals,- "retrieval_rate": f"{retrieval_rate:.1%}",- "confidence": round(pattern_dict.get("confidence", 0.0), 3),- "skip_recommended": pattern_dict.get("skip_compression_recommended", False),- "optimal_max_items": pattern_dict.get("optimal_max_items", 20),- "sample_size": sample_size,- }- )-- # Sort by sample_size descending- patterns_list.sort(key=lambda p: p["sample_size"], reverse=True)-- # Remove sample_size from output (used only for sorting)- for p in patterns_list:- del p["sample_size"]-- return patterns_list[:limit]-- @app.get("/v1/toin/pattern/{hash_prefix}")- async def toin_pattern_detail(hash_prefix: str):- """Get detailed TOIN pattern info by hash prefix.-- Searches for a pattern where the tool signature hash starts with- the provided prefix. Returns full pattern details if found.-- Path params:- hash_prefix: Beginning of the tool signature hash (min 4 chars recommended)-- Response: Full pattern.to_dict() with all learned statistics and recommendations.- """- toin = get_toin()- exported = toin.export_patterns()- patterns_data = exported.get("patterns", {})-- # Search for pattern with matching hash prefix- for sig_hash, pattern_dict in patterns_data.items():- if sig_hash.startswith(hash_prefix):- return pattern_dict-- raise HTTPException(- status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"- )-- @app.get("/v1/retrieve/{hash_key}")- async def ccr_retrieve_get(hash_key: str, query: str | None = None):- """GET version of CCR retrieve for easier testing."""- store = get_compression_store()-- if query:- results = store.search(hash_key, query)- return {- "hash": hash_key,- "query": query,- "results": results,- "count": len(results),- }- else:- entry = store.retrieve(hash_key)- if entry:- return {- "hash": hash_key,- "original_content": entry.original_content,- "original_tokens": entry.original_tokens,- "original_item_count": entry.original_item_count,- "compressed_item_count": entry.compressed_item_count,- "tool_name": entry.tool_name,- "retrieval_count": entry.retrieval_count,- }- raise HTTPException(status_code=404, detail="Entry not found or expired")-- # CCR Tool Call Handler - for agent frameworks to call when LLM uses headroom_retrieve- @app.post("/v1/retrieve/tool_call")- async def ccr_handle_tool_call(request: Request):- """Handle a CCR tool call from an LLM response.-- This endpoint accepts tool call formats from various providers and returns- a properly formatted tool result. Agent frameworks can use this to handle- CCR tool calls without implementing the retrieval logic themselves.-- Request body (Anthropic format):- {- "tool_call": {- "id": "toolu_123",- "name": "headroom_retrieve",- "input": {"hash": "abc123", "query": "optional search"}- },- "provider": "anthropic"- }-- Request body (OpenAI format):- {- "tool_call": {- "id": "call_123",- "function": {- "name": "headroom_retrieve",- "arguments": "{\"hash\": \"abc123\"}"- }- },- "provider": "openai"- }-- Response:- {- "tool_result": {...}, # Formatted for the provider- "success": true,- "data": {...} # Raw retrieval data- }- """- data = await request.json()- tool_call = data.get("tool_call", {})- provider = data.get("provider", "anthropic")-- # Parse the tool call- hash_key, query = parse_tool_call(tool_call, provider)-- if hash_key is None:- raise HTTPException(- status_code=400, detail=f"Invalid tool call or not a {CCR_TOOL_NAME} call"- )-- # Perform retrieval- store = get_compression_store()-- if query:- results = store.search(hash_key, query)- retrieval_data = {- "hash": hash_key,- "query": query,- "results": results,- "count": len(results),- }- else:- entry = store.retrieve(hash_key)- if entry:- retrieval_data = {- "hash": hash_key,- "original_content": entry.original_content,- "original_item_count": entry.original_item_count,- "compressed_item_count": entry.compressed_item_count,- }- else:- retrieval_data = {- "error": "Entry not found or expired (TTL: 5 minutes)",- "hash": hash_key,- }-- # Format tool result for provider- tool_call_id = tool_call.get("id", "")- result_content = json.dumps(retrieval_data, indent=2)-- if provider == "anthropic":- tool_result = {- "type": "tool_result",- "tool_use_id": tool_call_id,- "content": result_content,- }- elif provider == "openai":- tool_result = {- "role": "tool",- "tool_call_id": tool_call_id,- "content": result_content,- }- else:- tool_result = {- "tool_call_id": tool_call_id,- "content": result_content,- }-- return {- "tool_result": tool_result,- "success": "error" not in retrieval_data,- "data": retrieval_data,- }-- # Compression-only endpoint (for TypeScript SDK and other HTTP clients)- @app.post("/v1/compress")- async def compress_messages(request: Request):- return await proxy.handle_compress(request)-- register_provider_routes(app, proxy)-- return app---def _get_code_aware_banner_status(config: ProxyConfig) -> str:- """Get code-aware compression status line for banner."""- if config.code_aware_enabled:- if is_tree_sitter_available():- return "ENABLED (AST-based)"- else:- return "NOT INSTALLED (pip install headroom-ai[code])"- else:- if is_tree_sitter_available():- return "DISABLED (remove --no-code-aware to enable)"- return "DISABLED"---def run_server(- config: ProxyConfig | None = None,- workers: int = 1,- limit_concurrency: int = 1000,-):- """Run the proxy server.-- Args:- config: Proxy configuration- workers: Number of worker processes (use N for multi-core scaling)- limit_concurrency: Max concurrent connections before 503 response- """- if not FASTAPI_AVAILABLE:- print("ERROR: FastAPI required. Install: pip install fastapi uvicorn httpx")- sys.exit(1)-- config = config or ProxyConfig()- app = create_app(config)-- code_aware_status = _get_code_aware_banner_status(config)-- # Format connection pool info- pool_info = f"max={config.max_connections}, keepalive={config.max_keepalive_connections}"- http2_status = "ENABLED" if config.http2 else "DISABLED"-- backend_status = format_backend_status(- backend=config.backend,- anyllm_provider=config.anyllm_provider,- bedrock_region=config.bedrock_region,- )-- print(f"""-╔══════════════════════════════════════════════════════════════════════╗-║ HEADROOM PROXY SERVER ║-╠══════════════════════════════════════════════════════════════════════╣-║ Version: 1.0.0 ║-║ Listening: http://{config.host}:{config.port:<5} ║-║ Workers: {workers:<3} Concurrency Limit: {limit_concurrency:<5} ║-║ Backend: {backend_status:<59}║-╠══════════════════════════════════════════════════════════════════════╣-║ FEATURES: ║-║ Optimization: {"ENABLED " if config.optimize else "DISABLED"} ║-║ Caching: {"ENABLED " if config.cache_enabled else "DISABLED"} (TTL: {config.cache_ttl_seconds}s) ║-║ Rate Limiting: {"ENABLED " if config.rate_limit_enabled else "DISABLED"} ({config.rate_limit_requests_per_minute} req/min, {config.rate_limit_tokens_per_minute:,} tok/min) ║-║ Retry: {"ENABLED " if config.retry_enabled else "DISABLED"} (max {config.retry_max_attempts} attempts) ║-║ Cost Tracking: {"ENABLED " if config.cost_tracking_enabled else "DISABLED"} (budget: {"$" + str(config.budget_limit_usd) + "/" + config.budget_period if config.budget_limit_usd else "unlimited"}) ║-║ Code-Aware: {code_aware_status:<52}║-║ HTTP/2: {http2_status:<52}║-║ Conn Pool: {pool_info:<52}║-╠══════════════════════════════════════════════════════════════════════╣-║ USAGE: ║-║ Claude Code: ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude ║-║ Cursor: Set base URL in settings ║-╠══════════════════════════════════════════════════════════════════════╣-║ ENDPOINTS: ║-║ /livez Process liveness ║-║ /readyz Traffic readiness ║-║ /health Aggregate health ║-║ /stats Detailed statistics ║-║ /metrics Prometheus metrics ║-║ /cache/clear Clear response cache ║-║ /v1/retrieve CCR: Retrieve compressed content ║-║ /v1/retrieve/stats CCR: Compression store stats ║-║ /v1/retrieve/tool_call CCR: Handle LLM tool calls ║-║ /v1/feedback CCR: Feedback loop stats & patterns ║-║ /v1/feedback/{{tool}} CCR: Compression hints for a tool ║-║ /v1/telemetry Data flywheel: Telemetry stats ║-║ /v1/telemetry/export Data flywheel: Export for aggregation ║-║ /v1/telemetry/tools Data flywheel: Per-tool stats ║-║ /v1/toin/stats TOIN: Overall intelligence stats ║-║ /v1/toin/patterns TOIN: List learned patterns ║-║ /v1/toin/pattern/{{hash}} TOIN: Pattern details by hash ║-╚══════════════════════════════════════════════════════════════════════╝-""")-- uvicorn.run(- app,- host=config.host,- port=config.port,- log_level="warning",- workers=workers if workers > 1 else None, # None = single process (default)- limit_concurrency=limit_concurrency,- # Defense-in-depth: the loopback guard for /debug/* endpoints trusts- # request.client.host. uvicorn's ProxyHeadersMiddleware rewrites that- # from X-Forwarded-For when FORWARDED_ALLOW_IPS is broader than the- # default. Disabling proxy_headers here guarantees the guard sees the- # real peer address regardless of env.- proxy_headers=False,- )---def _get_env_bool(name: str, default: bool) -> bool:- """Get boolean from environment variable."""- val = os.environ.get(name)- if val is None:- return default- return val.lower() in ("true", "1", "yes", "on")---def _get_env_int(name: str, default: int) -> int:- """Get integer from environment variable."""- val = os.environ.get(name)- if val is None:- return default- try:- return int(val)- except ValueError:- return default---def _get_env_float(name: str, default: float) -> float:- """Get float from environment variable."""- val = os.environ.get(name)- if val is None:- return default- try:- return float(val)- except ValueError:- return default---def _get_env_str(name: str, default: str) -> str:- """Get string from environment variable."""- return os.environ.get(name, default)---def _parse_tool_profiles(cli_profiles: list[str]) -> dict[str, Any]:- """Parse tool profiles from CLI args and HEADROOM_TOOL_PROFILES env var.-- Format: ToolName:level (e.g., Grep:conservative, Bash:moderate)- Env var format: comma-separated (e.g., "Grep:conservative,Bash:moderate")-- Returns:- Dict mapping tool names to CompressionProfile instances.- """- from headroom.config import PROFILE_PRESETS, CompressionProfile-- profiles: dict[str, CompressionProfile] = {}- raw_entries: list[str] = list(cli_profiles)-- # Also check env var- env_val = os.environ.get("HEADROOM_TOOL_PROFILES", "")- if env_val:- raw_entries.extend(e.strip() for e in env_val.split(",") if e.strip())-- for entry in raw_entries:- if ":" not in entry:- logger.warning("Invalid tool profile format (expected ToolName:level): %s", entry)- continue- tool_name, level = entry.split(":", 1)- tool_name = tool_name.strip()- level = level.strip().lower()-- if level in PROFILE_PRESETS:- profiles[tool_name] = PROFILE_PRESETS[level]- else:- logger.warning(- "Unknown profile level '%s' for tool '%s'. Use: conservative, moderate, aggressive",- level,- tool_name,- )-- return profiles---if __name__ == "__main__":- parser = argparse.ArgumentParser(description="Headroom Proxy Server")-- # Server- parser.add_argument("--host", default="127.0.0.1")- parser.add_argument("--port", type=int, default=8787)- parser.add_argument(- "--openai-api-url", help=f"Custom OpenAI API URL (default: {DEFAULT_OPENAI_API_URL})"- )- parser.add_argument(- "--anthropic-api-url",- help=f"Custom Anthropic API URL (default: {DEFAULT_ANTHROPIC_API_URL})",- )-- # Backend (anthropic direct, bedrock, openrouter, anyllm, or litellm-<provider>)- parser.add_argument(- "--backend",- default="anthropic",- help=(- "Backend: 'anthropic' (direct), 'bedrock' (AWS), 'openrouter', "- "'anyllm' (any-llm), or 'litellm-<provider>' (e.g., litellm-hosted_vllm, litellm-vertex)"- ),- )- parser.add_argument(- "--bedrock-region",- default="us-west-2",- help="AWS region for Bedrock backend (default: us-west-2)",- )- parser.add_argument(- "--bedrock-profile",- help="AWS profile for Bedrock backend (default: use default credentials)",- )- parser.add_argument(- "--openrouter-api-key",- help="OpenRouter API key (or set OPENROUTER_API_KEY env var)",- )- parser.add_argument(- "--anyllm-provider",- default="openai",- help="any-llm provider: openai, anthropic, mistral, groq, ollama, bedrock, etc. (default: openai)",- )-- # Connection pool (scalability)- parser.add_argument(- "--max-connections",- type=int,- default=500,- help="Max connections to upstream APIs (default: 500)",- )- parser.add_argument(- "--max-keepalive", type=int, default=100, help="Max keepalive connections (default: 100)"- )- parser.add_argument(- "--no-http2",- action="store_true",- help="Disable HTTP/2 (enabled by default for better throughput)",- )- parser.add_argument(- "--workers",- type=int,- default=1,- help="Number of worker processes (default: 1, use N for multi-core)",- )- parser.add_argument(- "--limit-concurrency",- type=int,- default=1000,- help="Max concurrent connections before 503 (default: 1000)",- )-- # Optimization- parser.add_argument("--no-optimize", action="store_true", help="Disable optimization")- parser.add_argument("--min-tokens", type=int, default=500, help="Min tokens to crush")- parser.add_argument("--max-items", type=int, default=50, help="Max items after crush")- parser.add_argument(- "--tool-profile",- action="append",- default=[],- help="Per-tool compression profile: ToolName:level (e.g., Grep:conservative, Bash:moderate, WebFetch:aggressive). "- "Can be specified multiple times. Also settable via HEADROOM_TOOL_PROFILES env var.",- )-- # Caching- parser.add_argument("--no-cache", action="store_true", help="Disable caching")- parser.add_argument("--cache-ttl", type=int, default=3600, help="Cache TTL seconds")-- # Rate limiting- parser.add_argument("--no-rate-limit", action="store_true", help="Disable rate limiting")- parser.add_argument("--rpm", type=int, default=60, help="Requests per minute")- parser.add_argument("--tpm", type=int, default=100000, help="Tokens per minute")-- # Cost- parser.add_argument("--budget", type=float, help="Budget limit in USD")- parser.add_argument("--budget-period", choices=["hourly", "daily", "monthly"], default="daily")-- # Logging- parser.add_argument("--log-file", help="Log file path")- parser.add_argument("--log-messages", action="store_true", help="Log full messages")-- # Smart routing (content-aware compression)- parser.add_argument(- "--no-smart-routing",- action="store_true",- help="Disable smart routing (use legacy sequential pipeline)",- )-- # Code-aware compression- parser.add_argument(- "--code-aware",- action="store_true",- help="Enable AST-based code compression (requires: pip install headroom-ai[code])",- )- parser.add_argument(- "--no-code-aware",- action="store_true",- help="Disable code-aware compression",- )-- args = parser.parse_args()-- # Environment variable defaults (HEADROOM_* prefix)- # CLI args override env vars, env vars override ProxyConfig defaults- env_smart_routing = _get_env_bool("HEADROOM_SMART_ROUTING", True)- env_code_aware = _get_env_bool("HEADROOM_CODE_AWARE_ENABLED", True)- env_optimize = _get_env_bool("HEADROOM_OPTIMIZE", True)- env_cache = _get_env_bool("HEADROOM_CACHE_ENABLED", True)- env_rate_limit = _get_env_bool("HEADROOM_RATE_LIMIT_ENABLED", True)-- # Determine settings: CLI flags override env vars- # --no-X explicitly disables, --X explicitly enables, neither uses env var- smart_routing = env_smart_routing if not args.no_smart_routing else False- code_aware_enabled = (- env_code_aware- if not (args.code_aware or args.no_code_aware)- else (args.code_aware or not args.no_code_aware)- )- optimize = env_optimize if not args.no_optimize else False- cache_enabled = env_cache if not args.no_cache else False- rate_limit_enabled = env_rate_limit if not args.no_rate_limit else False-- # Set OpenRouter API key from CLI if provided- if hasattr(args, "openrouter_api_key") and args.openrouter_api_key:- os.environ["OPENROUTER_API_KEY"] = args.openrouter_api_key-- # Parse per-tool compression profiles from CLI and env var- tool_profiles = _parse_tool_profiles(args.tool_profile)-- config = ProxyConfig(- host=_get_env_str("HEADROOM_HOST", args.host),- port=_get_env_int("HEADROOM_PORT", args.port),- openai_api_url=_get_env_str("OPENAI_TARGET_API_URL", args.openai_api_url),- anthropic_api_url=_get_env_str("ANTHROPIC_TARGET_API_URL", args.anthropic_api_url),- # Backend settings- backend=_get_env_str("HEADROOM_BACKEND", args.backend), # type: ignore[arg-type]- bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", args.bedrock_region),- bedrock_profile=args.bedrock_profile or os.environ.get("AWS_PROFILE"),- anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", args.anyllm_provider),- optimize=optimize,- min_tokens_to_crush=_get_env_int("HEADROOM_MIN_TOKENS", args.min_tokens),- max_items_after_crush=_get_env_int("HEADROOM_MAX_ITEMS", args.max_items),- cache_enabled=cache_enabled,- cache_ttl_seconds=_get_env_int("HEADROOM_CACHE_TTL", args.cache_ttl),- rate_limit_enabled=rate_limit_enabled,- rate_limit_requests_per_minute=_get_env_int("HEADROOM_RPM", args.rpm),- rate_limit_tokens_per_minute=_get_env_int("HEADROOM_TPM", args.tpm),- budget_limit_usd=args.budget,- budget_period=args.budget_period,- log_file=_get_env_str("HEADROOM_LOG_FILE", args.log_file)- if args.log_file- else os.environ.get("HEADROOM_LOG_FILE"),- log_full_messages=args.log_messages or _get_env_bool("HEADROOM_LOG_MESSAGES", False),- smart_routing=smart_routing,- code_aware_enabled=code_aware_enabled,- # Connection pool settings- max_connections=_get_env_int("HEADROOM_MAX_CONNECTIONS", args.max_connections),- max_keepalive_connections=_get_env_int("HEADROOM_MAX_KEEPALIVE", args.max_keepalive),- http2=not args.no_http2 and _get_env_bool("HEADROOM_HTTP2", True),- tool_profiles=tool_profiles if tool_profiles else None,- mode=normalize_proxy_mode(_get_env_str("HEADROOM_MODE", PROXY_MODE_TOKEN)),- )-- # Get worker and concurrency settings- workers = _get_env_int("HEADROOM_WORKERS", args.workers)- limit_concurrency = _get_env_int("HEADROOM_LIMIT_CONCURRENCY", args.limit_concurrency)-- run_server(config, workers=workers, limit_concurrency=limit_concurrency)+"""Headroom Proxy Server - Production Ready.++A full-featured LLM proxy with optimization, caching, rate limiting,+and observability.++Features:+- Context optimization (SmartCrusher, CacheAligner, RollingWindow)+- Semantic caching (save costs on repeated queries)+- Rate limiting (token bucket)+- Retry with exponential backoff+- Cost tracking and budgets+- Request tagging and metadata+- Provider fallback+- Prometheus metrics+- Full request/response logging++Usage:+ python -m headroom.proxy.server --port 8787++ # With Claude Code:+ ANTHROPIC_BASE_URL=http://localhost:8787 claude+"""++from __future__ import annotations++import argparse+import asyncio+import json+import logging+import os+import sys+import time+from datetime import datetime, timezone+from pathlib import Path+from typing import TYPE_CHECKING, Any, Literal, cast++if TYPE_CHECKING:+ from ..backends.base import Backend+ from ..cache.compression_cache import CompressionCache+ from ..memory.tracker import MemoryTracker+++import httpx++try:+ import uvicorn+ from fastapi import Depends, FastAPI, HTTPException, Request, Response+ from fastapi.middleware.cors import CORSMiddleware+ from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse++ FASTAPI_AVAILABLE = True+except ImportError:+ FASTAPI_AVAILABLE = False++# Add parent to path for imports+sys.path.insert(0, str(Path(__file__).parent.parent.parent))++from headroom._version import __version__+from headroom.cache.compression_feedback import get_compression_feedback+from headroom.cache.compression_store import get_compression_store+from headroom.ccr import (+ CCR_TOOL_NAME,+ # Batch processing+ CCRResponseHandler,+ CCRToolInjector,+ ContextTracker,+ ContextTrackerConfig,+ ResponseHandlerConfig,+ parse_tool_call,+)+from headroom.config import (+ CacheAlignerConfig,+ CCRConfig,+ IntelligentContextConfig,+ ReadLifecycleConfig,+ RollingWindowConfig,+ SmartCrusherConfig,+)+from headroom.dashboard import get_dashboard_html+from headroom.observability import (+ LangfuseTracingConfig,+ OTelMetricsConfig,+ configure_langfuse_tracing,+ configure_otel_metrics,+ get_langfuse_tracing_status,+ get_otel_metrics_status,+ shutdown_headroom_tracing,+ shutdown_otel_metrics,+)+from headroom.pipeline import PipelineExtensionManager, PipelineStage+from headroom.providers.proxy_routes import register_provider_routes+from headroom.providers.registry import (+ DEFAULT_ANTHROPIC_API_URL,+ DEFAULT_CLOUDCODE_API_URL,+ DEFAULT_GEMINI_API_URL,+ DEFAULT_OPENAI_API_URL,+ build_proxy_provider_runtime,+ create_proxy_backend,+ format_backend_status,+)++# =============================================================================+# Extracted modules (re-exported for backward compatibility)+# =============================================================================+from headroom.proxy.cost import (+ _CACHE_ECONOMICS, # noqa: F401+ CostTracker, # noqa: F401+ _summarize_transforms, # noqa: F401+ build_prefix_cache_stats, # noqa: F401+ build_session_summary, # noqa: F401+ merge_cost_stats, # noqa: F401+)+from headroom.proxy.helpers import (+ COMPRESSION_TIMEOUT_SECONDS, # noqa: F401+ MAX_COMPRESSION_CACHE_SESSIONS, # noqa: F401+ MAX_MESSAGE_ARRAY_LENGTH, # noqa: F401+ MAX_REQUEST_BODY_SIZE, # noqa: F401+ MAX_SSE_BUFFER_SIZE, # noqa: F401+ _get_image_compressor, # noqa: F401+ _get_rtk_stats, # noqa: F401+ _read_request_json, # noqa: F401+ _setup_file_logging, # noqa: F401+ is_anthropic_auth, # noqa: F401+ jitter_delay_ms,+)+from headroom.proxy.memory_handler import MemoryConfig, MemoryHandler++# Data models (extracted to headroom/proxy/models.py for maintainability)+from headroom.proxy.models import CacheEntry, ProxyConfig, RateLimitState, RequestLog # noqa: F401+from headroom.proxy.modes import (+ PROXY_MODE_CACHE,+ PROXY_MODE_TOKEN,+ is_token_mode,+ normalize_proxy_mode,+)+from headroom.proxy.prometheus_metrics import PrometheusMetrics # noqa: F401+from headroom.proxy.rate_limiter import TokenBucketRateLimiter # noqa: F401+from headroom.proxy.request_logger import RequestLogger # noqa: F401+from headroom.proxy.semantic_cache import SemanticCache # noqa: F401+from headroom.proxy.warmup import WarmupRegistry+from headroom.proxy.ws_session_registry import WebSocketSessionRegistry+from headroom.subscription.base import get_quota_registry, reset_quota_registry+from headroom.subscription.codex_rate_limits import get_codex_rate_limit_state+from headroom.subscription.copilot_quota import get_copilot_quota_tracker+from headroom.subscription.tracker import (+ configure_subscription_tracker,+ get_subscription_tracker,+)+from headroom.telemetry import get_telemetry_collector+from headroom.telemetry.beacon import is_telemetry_enabled+from headroom.telemetry.toin import get_toin+from headroom.transforms import (+ CacheAligner,+ CodeAwareCompressor,+ CodeCompressorConfig,+ ContentRouter,+ ContentRouterConfig,+ IntelligentContextManager,+ RollingWindow,+ SmartCrusher,+ Transform,+ TransformPipeline,+ is_tree_sitter_available,+)++AnyLLMBackend: Any = None+LiteLLMBackend: Any = None++fcntl: Any = None+try:+ import fcntl as _fcntl++ fcntl = _fcntl+ HAS_FCNTL = True+except ImportError:+ HAS_FCNTL = False++_build_prefix_cache_stats = build_prefix_cache_stats+_build_session_summary = build_session_summary+_merge_cost_stats = merge_cost_stats+++logging.basicConfig(+ level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"+)+logger = logging.getLogger("headroom.proxy")++# Always-on file logging to ~/.headroom/logs/ for `headroom perf` analysis+_setup_file_logging()+++# Compression pipeline timeout in seconds+++from headroom.proxy.handlers import ( # noqa: E402+ AnthropicHandlerMixin,+ BatchHandlerMixin,+ GeminiHandlerMixin,+ OpenAIHandlerMixin,+ StreamingMixin,+)+++class HeadroomProxy(+ StreamingMixin,+ AnthropicHandlerMixin,+ OpenAIHandlerMixin,+ GeminiHandlerMixin,+ BatchHandlerMixin,+):+ """Production-ready Headroom optimization proxy."""++ ANTHROPIC_API_URL = DEFAULT_ANTHROPIC_API_URL+ OPENAI_API_URL = DEFAULT_OPENAI_API_URL+ GEMINI_API_URL = DEFAULT_GEMINI_API_URL+ CLOUDCODE_API_URL = DEFAULT_CLOUDCODE_API_URL++ def __init__(self, config: ProxyConfig):+ self.config = config+ self.config.mode = normalize_proxy_mode(self.config.mode)+ self.pipeline_extensions = PipelineExtensionManager(+ hooks=config.hooks,+ extensions=config.pipeline_extensions,+ discover=config.discover_pipeline_extensions,+ )++ self.provider_runtime = build_proxy_provider_runtime(config)+ api_targets = self.provider_runtime.api_targets++ # Preserve the long-standing proxy compatibility surface while keeping+ # provider_runtime as the source of truth for resolved upstream targets.+ HeadroomProxy.ANTHROPIC_API_URL = api_targets.anthropic+ HeadroomProxy.OPENAI_API_URL = api_targets.openai+ HeadroomProxy.GEMINI_API_URL = api_targets.gemini+ HeadroomProxy.CLOUDCODE_API_URL = api_targets.cloudcode+ self.anthropic_provider = self.provider_runtime.pipeline_provider("anthropic")+ self.openai_provider = self.provider_runtime.pipeline_provider("openai")++ # Initialize transforms based on routing mode+ # Choose context manager: IntelligentContextManager (smart) or RollingWindow (legacy)+ context_manager: Transform # Can be either IntelligentContextManager or RollingWindow+ if config.intelligent_context:+ # Get TOIN instance for learned pattern integration+ toin = get_toin() if config.intelligent_context_scoring else None+ context_manager = IntelligentContextManager(+ config=IntelligentContextConfig(+ enabled=True,+ keep_system=True,+ keep_last_turns=config.keep_last_turns,+ use_importance_scoring=config.intelligent_context_scoring,+ toin_integration=config.intelligent_context_scoring,+ compress_threshold=0.10 if config.intelligent_context_compress_first else 0.0,+ ),+ toin=toin,+ )+ self._context_manager_status = "intelligent"+ else:+ context_manager = RollingWindow(+ RollingWindowConfig(+ enabled=True,+ keep_system=True,+ keep_last_turns=config.keep_last_turns,+ )+ )+ self._context_manager_status = "rolling_window"++ if config.smart_routing:+ # Smart routing: ContentRouter handles all content types intelligently+ # It lazy-loads compressors only when needed+ router_config = ContentRouterConfig(+ enable_code_aware=config.code_aware_enabled,+ tool_profiles=config.tool_profiles,+ read_lifecycle=ReadLifecycleConfig(enabled=config.read_lifecycle),+ )+ # Token mode: allow compression of older excluded-tool results+ if is_token_mode(config.mode):+ router_config.protect_recent_reads_fraction = 0.3+ transforms = [+ CacheAligner(CacheAlignerConfig(enabled=False)),+ ContentRouter(router_config),+ context_manager,+ ]+ self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"+ else:+ # Legacy mode: sequential pipeline+ transforms = [+ CacheAligner(CacheAlignerConfig(enabled=False)),+ SmartCrusher(+ SmartCrusherConfig( # type: ignore[arg-type]+ enabled=True,+ min_tokens_to_crush=config.min_tokens_to_crush,+ max_items_after_crush=config.max_items_after_crush,+ ),+ ccr_config=CCRConfig(+ enabled=config.ccr_inject_tool,+ inject_retrieval_marker=config.ccr_inject_tool, # Add CCR markers+ ),+ ),+ context_manager,+ ]+ # Add CodeAware if enabled and available+ self._code_aware_status = self._setup_code_aware(config, transforms)++ self.anthropic_pipeline = TransformPipeline(+ transforms=transforms,+ provider=self.anthropic_provider,+ )+ self.openai_pipeline = TransformPipeline(+ transforms=transforms,+ provider=self.openai_provider,+ )++ # Initialize components+ self.cache = (+ SemanticCache(+ max_entries=config.cache_max_entries,+ ttl_seconds=config.cache_ttl_seconds,+ )+ if config.cache_enabled+ else None+ )++ self.rate_limiter = (+ TokenBucketRateLimiter(+ requests_per_minute=config.rate_limit_requests_per_minute,+ tokens_per_minute=config.rate_limit_tokens_per_minute,+ )+ if config.rate_limit_enabled+ else None+ )++ self.cost_tracker = (+ CostTracker(+ budget_limit_usd=config.budget_limit_usd,+ budget_period=config.budget_period,+ )+ if config.cost_tracking_enabled+ else None+ )++ self.metrics = PrometheusMetrics(cost_tracker=self.cost_tracker)++ # Prefix cache tracking: freeze already-cached messages to avoid+ # invalidating the provider's prefix cache with our transforms+ from headroom.cache.prefix_tracker import PrefixFreezeConfig, SessionTrackerStore++ self.session_tracker_store = SessionTrackerStore(+ default_config=PrefixFreezeConfig(+ enabled=config.prefix_freeze_enabled,+ session_ttl_seconds=config.prefix_freeze_session_ttl,+ )+ )++ # Compression cache store for token mode (session-scoped)+ self._compression_caches: dict[str, CompressionCache] = {}++ self.logger = (+ RequestLogger(+ log_file=config.log_file,+ log_full_messages=config.log_full_messages,+ )+ if config.log_requests+ else None+ )++ # Enterprise security plugin (loaded dynamically if available + licensed)+ self.security = None++ # HTTP client+ self.http_client: httpx.AsyncClient | None = None++ # Shared cold-start warmup registry (populated by startup()).+ # Holds typed slots with loaded / loading / null / error status for+ # each preloaded heavy asset. Exposed as ``proxy.warmup`` and+ # serialized by the /debug/warmup route (Unit 5).+ self.warmup: WarmupRegistry = WarmupRegistry()+ # Unit 3: live registry of Codex WS sessions. Populated by+ # ``handle_openai_responses_ws`` on accept; drained in its+ # outermost ``finally``. Consumed by ``/debug/ws-sessions``.+ self.ws_sessions: WebSocketSessionRegistry = WebSocketSessionRegistry()++ # Unit 4: bounded pre-upstream concurrency for the Anthropic HTTP+ # path. Caps how many ``handle_anthropic_messages`` calls may be+ # running deep-copy / first-stage compression / memory-context+ # lookup / upstream connect concurrently. ``/livez``, ``/readyz``,+ # ``/health``, ``/metrics``, ``/stats``, and the Codex WS path are+ # intentionally NOT gated by this semaphore.+ #+ # A value of ``0`` or negative disables the semaphore (unbounded+ # mode); this is useful for the Unit 6 counter-factual where we+ # deliberately reproduce the original starvation. The default is+ # ``max(2, min(8, os.cpu_count() or 4))``.+ _pre_upstream_cfg = config.anthropic_pre_upstream_concurrency+ if _pre_upstream_cfg is None:+ _pre_upstream_resolved = max(2, min(8, os.cpu_count() or 4))+ else:+ _pre_upstream_resolved = _pre_upstream_cfg+ self.anthropic_pre_upstream_concurrency: int = _pre_upstream_resolved+ self.anthropic_pre_upstream_acquire_timeout_seconds = float(+ config.anthropic_pre_upstream_acquire_timeout_seconds+ )+ self.anthropic_pre_upstream_memory_context_timeout_seconds = float(+ config.anthropic_pre_upstream_memory_context_timeout_seconds+ )+ if _pre_upstream_resolved > 0:+ self.anthropic_pre_upstream_sem: asyncio.Semaphore | None = asyncio.Semaphore(+ _pre_upstream_resolved+ )+ else:+ self.anthropic_pre_upstream_sem = None++ # Backend for Anthropic API (direct, LiteLLM, or any-llm)+ # Supports: "anthropic" (direct), "bedrock", "vertex", "litellm-<provider>", or "anyllm"+ self.anthropic_backend: Backend | None = create_proxy_backend(+ backend=config.backend,+ anyllm_provider=config.anyllm_provider,+ bedrock_region=config.bedrock_region,+ logger=logger,+ anyllm_backend_cls=AnyLLMBackend,+ litellm_backend_cls=LiteLLMBackend,+ )++ # Request counter for IDs+ self._request_counter = 0+ self._request_counter_lock = asyncio.Lock()++ # CCR tool injectors (one per provider)+ self.anthropic_tool_injector = CCRToolInjector(+ provider="anthropic",+ inject_tool=config.ccr_inject_tool,+ inject_system_instructions=config.ccr_inject_system_instructions,+ )+ self.openai_tool_injector = CCRToolInjector(+ provider="openai",+ inject_tool=config.ccr_inject_tool,+ inject_system_instructions=config.ccr_inject_system_instructions,+ )++ # CCR Response Handler (handles CCR tool calls automatically)+ self.ccr_response_handler = (+ CCRResponseHandler(+ ResponseHandlerConfig(+ enabled=True,+ max_retrieval_rounds=config.ccr_max_retrieval_rounds,+ )+ )+ if config.ccr_handle_responses+ else None+ )++ # CCR Context Tracker (tracks compressed content across turns)+ self.ccr_context_tracker = (+ ContextTracker(+ ContextTrackerConfig(+ enabled=True,+ proactive_expansion=config.ccr_proactive_expansion,+ max_proactive_expansions=config.ccr_max_proactive_expansions,+ )+ )+ if config.ccr_context_tracking+ else None+ )++ # Turn counter for context tracking+ self._turn_counter = 0++ # Memory Handler (persistent user memory)+ self.memory_handler: MemoryHandler | None = None+ if config.memory_enabled:+ # Resolve memory DB path: empty → project-scoped default+ _mem_db_path = config.memory_db_path+ if not _mem_db_path:+ _mem_dir = Path.cwd() / ".headroom"+ _mem_dir.mkdir(parents=True, exist_ok=True)+ _mem_db_path = str(_mem_dir / "memory.db")+ logger.info(f"Memory: Project-scoped DB at {_mem_db_path}")++ memory_config = MemoryConfig(+ enabled=True,+ backend=config.memory_backend,+ db_path=_mem_db_path,+ inject_tools=config.memory_inject_tools,+ use_native_tool=config.memory_use_native_tool,+ inject_context=config.memory_inject_context,+ top_k=config.memory_top_k,+ min_similarity=config.memory_min_similarity,+ qdrant_host=config.memory_qdrant_host,+ qdrant_port=config.memory_qdrant_port,+ neo4j_uri=config.memory_neo4j_uri,+ neo4j_user=config.memory_neo4j_user,+ neo4j_password=config.memory_neo4j_password,+ bridge_enabled=config.memory_bridge_enabled,+ bridge_md_paths=config.memory_bridge_md_paths,+ bridge_md_format=config.memory_bridge_md_format,+ bridge_auto_import=config.memory_bridge_auto_import,+ bridge_export_path=config.memory_bridge_export_path,+ )+ self.memory_handler = MemoryHandler(+ memory_config,+ agent_type=config.traffic_learning_agent_type,+ )++ # Usage Reporter (license validation + phone-home for managed/enterprise)+ self.usage_reporter: UsageReporter | None = None+ if config.license_key:+ from headroom.telemetry.reporter import UsageReporter++ self.usage_reporter = UsageReporter(+ license_key=config.license_key,+ cloud_url=config.license_cloud_url,+ report_interval=config.license_report_interval,+ )++ # Traffic Learner (live pattern extraction from proxy traffic)+ # Only activates with --learn flag; requires --memory for backend+ self.traffic_learner: TrafficLearner | None = None+ self.traffic_learning_agent_type: str = config.traffic_learning_agent_type+ if config.traffic_learning_enabled:+ from headroom.memory.traffic_learner import TrafficLearner++ self.traffic_learner = TrafficLearner(+ user_id=os.environ.get("HEADROOM_USER_ID", os.environ.get("USER", "default")),+ agent_type=config.traffic_learning_agent_type,+ )++ # Code graph file watcher (live reindex on file changes)+ self.code_graph_watcher: CodeGraphWatcher | None = None # type: ignore[annotation-unchecked]+ if config.code_graph_watcher:+ from headroom.graph.watcher import CodeGraphWatcher++ self.code_graph_watcher = CodeGraphWatcher(project_dir=Path.cwd())+ if self.code_graph_watcher.start():+ logger.info("Code graph: file watcher started")+ else:+ self.code_graph_watcher = None++ self.pipeline_extensions.emit(+ PipelineStage.SETUP,+ operation="proxy.setup",+ metadata={+ "mode": self.config.mode,+ "optimize": self.config.optimize,+ "backend": self.config.backend,+ "memory_enabled": self.config.memory_enabled,+ },+ )++ def _get_compression_cache(self, session_id: str) -> CompressionCache:+ """Get or create a CompressionCache for a session."""+ if session_id not in self._compression_caches:+ from headroom.cache.compression_cache import CompressionCache++ # Evict oldest caches if at capacity+ if len(self._compression_caches) >= MAX_COMPRESSION_CACHE_SESSIONS:+ # Remove oldest quarter to amortize cleanup cost+ oldest_keys = list(self._compression_caches.keys())[+ : MAX_COMPRESSION_CACHE_SESSIONS // 4+ ]+ for key in oldest_keys:+ del self._compression_caches[key]+ logger.info(+ "Evicted %d compression caches (exceeded %d max sessions)",+ len(oldest_keys),+ MAX_COMPRESSION_CACHE_SESSIONS,+ )++ self._compression_caches[session_id] = CompressionCache()+ return self._compression_caches[session_id]++ def _setup_code_aware(self, config: ProxyConfig, transforms: list) -> str:+ """Set up code-aware compression if enabled.++ Args:+ config: Proxy configuration+ transforms: Transform list to append to++ Returns:+ Status string for logging: 'enabled', 'disabled', 'available', 'unavailable'+ """+ if config.code_aware_enabled:+ if is_tree_sitter_available():+ code_config = CodeCompressorConfig(+ preserve_imports=True,+ preserve_signatures=True,+ preserve_type_annotations=True,+ )+ # Insert before RollingWindow (which should be last)+ transforms.insert(-1, CodeAwareCompressor(code_config))+ return "enabled"+ else:+ logger.warning(+ "Code-aware compression requested but tree-sitter not installed. "+ "Install with: pip install headroom-ai[code]"+ )+ return "unavailable"+ else:+ if is_tree_sitter_available():+ return "available" # Available but not enabled+ return "disabled"++ async def startup(self):+ """Initialize async resources."""+ self.pipeline_extensions.emit(+ PipelineStage.PRE_START,+ operation="proxy.startup",+ metadata={"port": self.config.port, "host": self.config.host},+ )+ self.http_client = httpx.AsyncClient(+ timeout=httpx.Timeout(+ connect=self.config.connect_timeout_seconds,+ read=self.config.request_timeout_seconds,+ write=self.config.request_timeout_seconds,+ pool=self.config.connect_timeout_seconds,+ ),+ limits=httpx.Limits(+ max_connections=self.config.max_connections,+ max_keepalive_connections=self.config.max_keepalive_connections,+ ),+ http2=self.config.http2,+ )+ logger.info("Headroom Proxy started")+ logger.info(f"Optimization: {'ENABLED' if self.config.optimize else 'DISABLED'}")+ self.config.mode = normalize_proxy_mode(self.config.mode)+ logger.info(f"Mode: {self.config.mode}")+ if self.config.mode == PROXY_MODE_TOKEN:+ logger.info(" Prefix freeze: re-freeze after compression")+ logger.info(" Read protection window: 30%% of excluded-tool messages")+ logger.info(" CCR TTL: extended for session lifetime")+ logger.info(" Compression cache: active")+ if self.config.mode == PROXY_MODE_CACHE:+ logger.info(" Prefix freeze: strict (all prior turns immutable)")+ logger.info(" Mutations: latest turn only")+ logger.info(f"Caching: {'ENABLED' if self.config.cache_enabled else 'DISABLED'}")+ logger.info(f"Rate Limiting: {'ENABLED' if self.config.rate_limit_enabled else 'DISABLED'}")+ logger.info(+ f"Connection Pool: max_connections={self.config.max_connections}, "+ f"max_keepalive={self.config.max_keepalive_connections}, "+ f"http2={'ENABLED' if self.config.http2 else 'DISABLED'}"+ )++ # Unit 4 pre-upstream concurrency announcement. Report the resolved+ # value (auto-detected vs. explicit) so operators can correlate+ # ``pre_upstream_wait_ms`` log lines with the configured cap.+ if self.anthropic_pre_upstream_sem is None:+ logger.info("Anthropic pre-upstream concurrency: unbounded (explicitly disabled)")+ else:+ _explicit = self.config.anthropic_pre_upstream_concurrency+ _origin = "auto-detected" if _explicit is None else "explicit"+ logger.info(+ "Anthropic pre-upstream concurrency: %d (%s)",+ self.anthropic_pre_upstream_concurrency,+ _origin,+ )+ logger.info(+ "Anthropic pre-upstream timeouts: acquire=%.1fs compression=%.1fs memory_context=%.1fs",+ self.anthropic_pre_upstream_acquire_timeout_seconds,+ float(COMPRESSION_TIMEOUT_SECONDS),+ self.anthropic_pre_upstream_memory_context_timeout_seconds,+ )++ # Smart routing status+ if self.config.smart_routing:+ logger.info("Smart Routing: ENABLED (intelligent content detection)")+ else:+ logger.info("Smart Routing: DISABLED (legacy sequential mode)")++ # Eagerly load ALL compressors, parsers, and detectors at startup+ # This eliminates cold-start latency spikes on first requests.+ # Iterate BOTH pipelines (Anthropic + OpenAI) and dedupe transforms+ # by id() so shared-transform instances never load twice. The+ # resulting status dict is merged into ``self.warmup`` so /debug/warmup+ # (Unit 5) and /readyz have a single source of truth.+ self._kompress_status = "not installed"+ eager_status: dict[str, str] = {}++ if self.config.optimize:+ logger.info("Pre-loading compressors and parsers...")+ seen_transform_ids: set[int] = set()+ pipelines = (self.anthropic_pipeline, self.openai_pipeline)+ for pipeline in pipelines:+ for transform in pipeline.transforms:+ if id(transform) in seen_transform_ids:+ continue+ seen_transform_ids.add(id(transform))+ if not hasattr(transform, "eager_load_compressors"):+ continue+ try:+ transform_status = transform.eager_load_compressors()+ except Exception as exc:+ logger.warning(+ "Eager preload failed for %s: %s",+ type(transform).__name__,+ exc,+ )+ continue+ if not isinstance(transform_status, dict):+ continue+ # Merge: later writers win only if the key wasn't set.+ # Preload a transform ONCE — if another pipeline also has+ # ``eager_load_compressors`` it contributes only new keys.+ for key, value in transform_status.items():+ eager_status.setdefault(key, value)+ self.warmup.merge_transform_status(transform_status)++ # Update internal status from eager loading results+ if eager_status.get("kompress") == "enabled":+ self._kompress_status = "enabled"+ if eager_status.get("code_aware") == "enabled":+ self._code_aware_status = "enabled"++ # Log component status+ if self._kompress_status == "enabled":+ logger.info("Kompress: ENABLED (ModernBERT token compressor)")+ elif self.config.optimize:+ logger.info("Kompress: not installed (pip install headroom-ai[ml] for ML compression)")++ if self._code_aware_status == "enabled":+ logger.info("Code-Aware: ENABLED (AST-based compression)")+ if "tree_sitter" in eager_status:+ logger.info(f"Tree-Sitter: {eager_status['tree_sitter']}")+ elif self._code_aware_status == "lazy":+ logger.info("Code-Aware: LAZY (will load when code content detected)")+ elif self._code_aware_status == "available":+ logger.info("Code-Aware: available but disabled (use --code-aware)")+ elif self._code_aware_status == "unavailable":+ logger.info("Code-Aware: not installed (pip install headroom-ai[code])")+ elif self._code_aware_status == "disabled":+ logger.info("Code-Aware: DISABLED")++ if eager_status.get("magika") == "enabled":+ logger.info("Magika: ENABLED (ML content detection)")++ if self.memory_handler:+ self.warmup.memory_backend.mark_loading()+ try:+ await self.memory_handler.ensure_initialized()+ except Exception as exc: # pragma: no cover - defensive+ self.warmup.memory_backend.mark_error(str(exc))+ logger.warning("Memory: backend initialization failed (startup continues): %s", exc)+ memory_status = self.memory_handler.health_status()+ if memory_status.get("initialized"):+ self.warmup.memory_backend.mark_loaded(+ handle=self.memory_handler,+ backend=memory_status.get("backend"),+ )+ # Force one embed call so the ONNX graph is compiled now,+ # not lazily during the first request. Best-effort — any+ # failure is swallowed inside warmup_embedder.+ self.warmup.memory_embedder.mark_loading()+ warmed = await self.memory_handler.warmup_embedder()+ if warmed:+ self.warmup.memory_embedder.mark_loaded()+ else:+ # Not an error — e.g. qdrant-neo4j has no embedder slot+ # we can reach, or the backend simply exposes no handle.+ self.warmup.memory_embedder.mark_null()+ else:+ if self.warmup.memory_backend.status != "error":+ self.warmup.memory_backend.mark_null()+ self.warmup.memory_embedder.mark_null()+ logger.info(+ "Memory: ENABLED "+ f"(backend={memory_status['backend']}, initialized={memory_status['initialized']})"+ )+ else:+ logger.info("Memory: DISABLED")++ # CCR status+ ccr_features = []+ if self.config.ccr_inject_tool:+ ccr_features.append("tool_injection")+ if self.config.ccr_handle_responses:+ ccr_features.append("response_handling")+ if self.config.ccr_context_tracking:+ ccr_features.append("context_tracking")+ if self.config.ccr_proactive_expansion:+ ccr_features.append("proactive_expansion")+ if ccr_features:+ logger.info(f"CCR (Compress-Cache-Retrieve): ENABLED ({', '.join(ccr_features)})")+ else:+ logger.info("CCR: DISABLED")+ logger.info(f"Savings history: {self.metrics.savings_tracker.storage_path}")++ # Reset and rebuild the quota tracker registry for this server instance.+ # reset_quota_registry() ensures a clean slate when the proxy is restarted+ # (e.g. in tests that spin up multiple app instances in the same process).+ reset_quota_registry()+ registry = get_quota_registry()+ tracker = configure_subscription_tracker(+ poll_interval_s=self.config.subscription_poll_interval_s,+ active_window_s=self.config.subscription_active_window_s,+ enabled=self.config.subscription_tracking_enabled,+ )+ registry.register(tracker)+ registry.register(get_codex_rate_limit_state())+ registry.register(get_copilot_quota_tracker())+ await registry.start_all()++ if self.config.subscription_tracking_enabled:+ logger.info(+ "Subscription tracking: ENABLED "+ f"(poll_interval={self.config.subscription_poll_interval_s}s, "+ f"active_window={self.config.subscription_active_window_s}s)"+ )+ else:+ logger.info("Subscription tracking: DISABLED")++ copilot_tracker = get_copilot_quota_tracker()+ if copilot_tracker.is_available():+ logger.info("GitHub Copilot quota tracking: ENABLED")+ else:+ logger.info(+ "GitHub Copilot quota tracking: DISABLED "+ "(set GITHUB_TOKEN or GITHUB_COPILOT_GITHUB_TOKEN to enable)"+ )++ # Log anonymous telemetry status so operators can see it in the log stream+ if is_telemetry_enabled():+ logger.info(+ "Anonymous telemetry: ENABLED (aggregate stats only — no prompts or content). "+ "Opt out: HEADROOM_TELEMETRY=off or --no-telemetry"+ )+ else:+ logger.info("Anonymous telemetry: DISABLED")++ self.pipeline_extensions.emit(+ PipelineStage.POST_START,+ operation="proxy.startup",+ metadata={+ "port": self.config.port,+ "host": self.config.host,+ "warmup": self.warmup.to_dict(),+ },+ )++ async def shutdown(self):+ """Cleanup async resources."""+ if self.http_client:+ await self.http_client.aclose()+ self.http_client = None++ if self.memory_handler and hasattr(self.memory_handler, "close"):+ await self.memory_handler.close()++ # Stop all quota trackers via the registry+ await get_quota_registry().stop_all()++ # Print final stats+ self._print_summary()++ def _print_summary(self):+ """Print session summary."""+ m = self.metrics+ logger.info("=" * 70)+ logger.info("HEADROOM PROXY SESSION SUMMARY")+ logger.info("=" * 70)+ logger.info(f"Total requests: {m.requests_total}")+ logger.info(f"Cached responses: {m.requests_cached}")+ logger.info(f"Rate limited: {m.requests_rate_limited}")+ logger.info(f"Failed: {m.requests_failed}")+ logger.info(f"Input tokens: {m.tokens_input_total:,}")+ logger.info(f"Output tokens: {m.tokens_output_total:,}")+ logger.info(f"Tokens saved: {m.tokens_saved_total:,}")+ if m.tokens_input_total > 0:+ savings_pct = (+ m.tokens_saved_total / (m.tokens_input_total + m.tokens_saved_total)+ ) * 100+ logger.info(f"Token savings: {savings_pct:.1f}%")+ if m.latency_count > 0:+ avg_latency = m.latency_sum_ms / m.latency_count+ logger.info(f"Avg latency: {avg_latency:.0f}ms")+ logger.info("=" * 70)++ async def _next_request_id(self) -> str:+ """Generate unique request ID."""+ async with self._request_counter_lock:+ self._request_counter += 1+ return f"hr_{int(time.time())}_{self._request_counter:06d}"++ def _extract_tags(self, headers: dict) -> dict[str, str]:+ """Extract Headroom tags from headers."""+ tags = {}+ for key, value in headers.items():+ if key.lower().startswith("x-headroom-"):+ tag_name = key.lower().replace("x-headroom-", "")+ tags[tag_name] = value+ return tags++ def _inject_system_context(+ self,+ messages: list[dict[str, Any]],+ context: str,+ body: dict[str, Any] | None = None,+ ) -> list[dict[str, Any]]:+ """Inject context into the system message/parameter.++ For Anthropic API: Uses top-level 'system' parameter (not messages array).+ For OpenAI API: Uses system role in messages array.++ Args:+ messages: The messages list.+ context: Context to inject.+ body: Optional request body to update system parameter (for Anthropic).++ Returns:+ Updated messages list.+ """+ messages = list(messages) # Copy to avoid mutation++ # For Anthropic API: use top-level 'system' parameter+ if body is not None:+ existing_system = body.get("system", "")+ if isinstance(existing_system, str):+ body["system"] = (existing_system + "\n\n" + context).strip()+ elif isinstance(existing_system, list):+ # system is a list of content blocks (e.g., with cache_control).+ # Append memory context as a new text block — never overwrite.+ body["system"] = existing_system + [{"type": "text", "text": context}]+ else:+ # No existing system prompt — set as string+ body["system"] = context+ return messages++ # For OpenAI API: use system role in messages+ for i, msg in enumerate(messages):+ if msg.get("role") == "system":+ content = msg.get("content", "")+ if isinstance(content, str):+ messages[i] = {**msg, "content": content + "\n\n" + context}+ return messages++ # No system message found - prepend one+ messages.insert(0, {"role": "system", "content": context})+ return messages++ async def _retry_request(+ self,+ method: str,+ url: str,+ headers: dict,+ body: dict,+ stream: bool = False,+ ) -> httpx.Response:+ """Make request with retry and exponential backoff."""+ last_error = None++ for attempt in range(self.config.retry_max_attempts):+ try:+ if stream:+ # For streaming, we return early - retry happens at higher level+ return await self.http_client.post(url, json=body, headers=headers) # type: ignore[union-attr]+ else:+ response = await self.http_client.post(url, json=body, headers=headers) # type: ignore[union-attr]++ # Don't retry client errors (4xx)+ if 400 <= response.status_code < 500:+ return response++ # Retry server errors (5xx)+ if response.status_code >= 500:+ raise httpx.HTTPStatusError(+ f"Server error: {response.status_code}",+ request=response.request,+ response=response,+ )++ return response++ except (httpx.ConnectError, httpx.ReadTimeout, httpx.HTTPStatusError) as e:+ last_error = e++ if not self.config.retry_enabled or attempt >= self.config.retry_max_attempts - 1:+ raise++ # Exponential backoff with jitter+ delay_with_jitter = jitter_delay_ms(+ self.config.retry_base_delay_ms,+ self.config.retry_max_delay_ms,+ attempt,+ )++ logger.warning(+ f"Request failed (attempt {attempt + 1}), retrying in {delay_with_jitter:.0f}ms: {e}"+ )+ await asyncio.sleep(delay_with_jitter / 1000)++ raise last_error # type: ignore[misc]+++async def _log_toin_stats_periodically(interval_seconds: int = 300) -> None:+ """Background task that logs TOIN stats periodically.++ Args:+ interval_seconds: How often to log stats (default: 5 minutes).+ """+ while True:+ await asyncio.sleep(interval_seconds)+ try:+ toin = get_toin()+ stats = toin.get_stats()+ total_compressions = stats.get("total_compressions", 0)+ if total_compressions > 0:+ patterns = stats.get("patterns_tracked", 0)+ retrievals = stats.get("total_retrievals", 0)+ retrieval_rate = stats.get("global_retrieval_rate", 0.0)+ logger.info(+ "TOIN: %d patterns, %d compressions, %d retrievals, %.1f%% retrieval rate",+ patterns,+ total_compressions,+ retrievals,+ retrieval_rate * 100,+ )+ except Exception as e:+ logger.debug("Failed to log TOIN stats: %s", e)+++def _register_memory_components(proxy: HeadroomProxy, tracker: MemoryTracker) -> None:+ """Register all memory-tracked components with the tracker.++ This function is idempotent - it checks if components are already registered.++ Args:+ proxy: The HeadroomProxy instance.+ tracker: The MemoryTracker instance.+ """+ # Register compression store (global singleton)+ if "compression_store" not in tracker.registered_components:+ store = get_compression_store()+ tracker.register("compression_store", store.get_memory_stats)++ # Register semantic cache (instance on proxy)+ if proxy.cache and "semantic_cache" not in tracker.registered_components:+ tracker.register("semantic_cache", proxy.cache.get_memory_stats)++ # Register request logger (instance on proxy)+ if proxy.logger and "request_logger" not in tracker.registered_components:+ tracker.register("request_logger", proxy.logger.get_memory_stats)++ # Register batch context store (global singleton)+ if "batch_context_store" not in tracker.registered_components:+ try:+ from ..ccr.batch_store import get_batch_context_store++ batch_store = get_batch_context_store()+ if hasattr(batch_store, "get_memory_stats"):+ tracker.register("batch_context_store", batch_store.get_memory_stats)+ except ImportError:+ pass++ # Note: graph_store and vector_index are created per-user within the+ # LocalMemoryBackend, not as global singletons. They would need to be+ # registered when the memory system is initialized with specific backends.+++def create_app(config: ProxyConfig | None = None) -> FastAPI:+ """Create FastAPI application."""+ if not FASTAPI_AVAILABLE:+ raise ImportError("FastAPI required. Install: pip install fastapi uvicorn httpx")++ from contextlib import asynccontextmanager++ config = config or ProxyConfig()+ proxy = HeadroomProxy(config)++ # Telemetry beacon (anonymous aggregate stats).+ # With uvicorn workers > 1, each worker runs the lifespan independently.+ # We must ensure only ONE beacon runs across all workers — otherwise each+ # worker creates its own beacon, spamming the telemetry table with N rows+ # per cycle instead of 1 (all reading the same /stats from the same port).+ #+ # Strategy: use a file lock to ensure only the first worker starts the+ # beacon. Other workers see the lock and skip.+ from headroom.telemetry.beacon import TelemetryBeacon++ _beacon = TelemetryBeacon(+ port=config.port if hasattr(config, "port") else 8787,+ sdk=os.environ.get("HEADROOM_SDK", "proxy").strip() or "proxy",+ backend=config.backend if hasattr(config, "backend") else "anthropic",+ )+ from headroom import paths as _hr_paths++ _beacon_lock_path = _hr_paths.beacon_lock_path(config.port)+ _beacon_lock_fd: list = [None] # mutable holder for the lock file descriptor+ _beacon_is_owner: list = [False]++ def _try_acquire_beacon_lock() -> bool:+ """Try to acquire the beacon file lock (non-blocking).++ Returns True if this process is the beacon owner.+ """+ if not HAS_FCNTL:+ return True++ fd = None+ try:+ _beacon_lock_path.parent.mkdir(parents=True, exist_ok=True)+ fd = open(_beacon_lock_path, "w") # noqa: SIM115+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)+ fd.write(str(os.getpid()))+ fd.flush()+ _beacon_lock_fd[0] = fd+ return True+ except OSError:+ if fd is not None:+ fd.close()+ return False++ def _release_beacon_lock() -> None:+ """Release the beacon file lock."""+ fd = _beacon_lock_fd[0]+ if fd:+ try:+ if HAS_FCNTL:+ fcntl.flock(fd, fcntl.LOCK_UN)+ fd.close()+ except Exception:+ pass+ _beacon_lock_fd[0] = None+ try:+ _beacon_lock_path.unlink(missing_ok=True)+ except Exception:+ pass++ @asynccontextmanager+ async def lifespan(app: FastAPI): # type: ignore[no-untyped-def]+ configure_otel_metrics(OTelMetricsConfig.from_env(default_service_name="headroom-proxy"))+ configure_langfuse_tracing(+ LangfuseTracingConfig.from_env(default_service_name="headroom-proxy")+ )++ app.state.started_at = time.time()+ app.state.ready = False+ app.state.startup_error = None++ try:+ try:+ # Startup+ await proxy.startup()+ asyncio.create_task(_log_toin_stats_periodically())+ if proxy.usage_reporter:+ await proxy.usage_reporter.start(proxy)+ if proxy.traffic_learner:+ await proxy.traffic_learner.start()++ # Only start beacon if we acquire the lock (first worker wins)+ _beacon_is_owner[0] = _try_acquire_beacon_lock()+ if _beacon_is_owner[0]:+ await _beacon.start()+ else:+ logger.debug("Beacon: skipping (another worker owns the lock)")++ app.state.ready = True+ yield+ except Exception as exc:+ app.state.startup_error = str(exc)+ raise+ finally:+ app.state.ready = False+ # Shutdown+ if _beacon_is_owner[0]:+ await _beacon.stop()+ _release_beacon_lock()+ if proxy.usage_reporter:+ await proxy.usage_reporter.stop()+ if proxy.traffic_learner:+ await proxy.traffic_learner.stop()+ if proxy.code_graph_watcher:+ proxy.code_graph_watcher.stop()+ await proxy.shutdown()+ shutdown_headroom_tracing()+ shutdown_otel_metrics()++ app = FastAPI(+ title="Headroom Proxy",+ description="Production-ready LLM optimization proxy",+ version=__version__,+ lifespan=lifespan,+ )+ app.state.proxy = proxy+ app.state.started_at = None+ app.state.ready = False+ app.state.startup_error = None++ def _iso_utc_now() -> str:+ return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")++ def _uptime_seconds() -> float:+ started_at = getattr(app.state, "started_at", None)+ if not isinstance(started_at, int | float):+ return 0.0+ return round(max(0.0, time.time() - float(started_at)), 3)++ def _component_health(+ *,+ enabled: bool,+ ready: bool,+ **details: Any,+ ) -> dict[str, Any]:+ status = "disabled" if not enabled else ("healthy" if ready else "unhealthy")+ return {+ "enabled": enabled,+ "ready": (ready if enabled else True),+ "status": status,+ **details,+ }++ def _health_checks() -> dict[str, dict[str, Any]]:+ memory_status = (+ proxy.memory_handler.health_status()+ if proxy.memory_handler+ else {+ "enabled": False,+ "backend": None,+ "initialized": False,+ "native_tool": False,+ "bridge_enabled": False,+ }+ )+ memory_enabled = bool(memory_status.get("enabled", False))+ memory_initialized = bool(memory_status.get("initialized", False))+ return {+ "startup": _component_health(+ enabled=True,+ ready=bool(getattr(app.state, "ready", False)),+ error=getattr(app.state, "startup_error", None),+ ),+ "http_client": _component_health(+ enabled=True,+ ready=proxy.http_client is not None,+ ),+ "cache": _component_health(+ enabled=config.cache_enabled,+ ready=(proxy.cache is not None),+ ),+ "rate_limiter": _component_health(+ enabled=config.rate_limit_enabled,+ ready=(proxy.rate_limiter is not None),+ ),+ "memory": _component_health(+ enabled=memory_enabled,+ ready=memory_initialized,+ backend=memory_status["backend"],+ initialized=memory_initialized,+ native_tool=bool(memory_status.get("native_tool", False)),+ bridge_enabled=bool(memory_status.get("bridge_enabled", False)),+ ),+ }++ def _runtime_payload() -> dict[str, Any]:+ ws_registry = getattr(proxy, "ws_sessions", None)+ ws_active_sessions = ws_registry.active_count() if ws_registry is not None else 0+ ws_active_relay_tasks = (+ ws_registry.active_relay_task_count() if ws_registry is not None else 0+ )+ return {+ "anthropic_pre_upstream": {+ "enabled": proxy.anthropic_pre_upstream_sem is not None,+ "resolved_concurrency": proxy.anthropic_pre_upstream_concurrency,+ "source": (+ "auto" if config.anthropic_pre_upstream_concurrency is None else "explicit"+ ),+ "acquire_timeout_seconds": proxy.anthropic_pre_upstream_acquire_timeout_seconds,+ "compression_timeout_seconds": float(COMPRESSION_TIMEOUT_SECONDS),+ "memory_context_timeout_seconds": (+ proxy.anthropic_pre_upstream_memory_context_timeout_seconds+ ),+ "codex_ws_gated": False,+ },+ "websocket_sessions": {+ "active_sessions": ws_active_sessions,+ "active_relay_tasks": ws_active_relay_tasks,+ },+ }++ def _health_payload(*, include_config: bool) -> dict[str, Any]:+ checks = _health_checks()+ ready = all(check["ready"] for check in checks.values())+ payload: dict[str, Any] = {+ "service": "headroom-proxy",+ "status": "healthy" if ready else "unhealthy",+ "ready": ready,+ "version": __version__,+ "timestamp": _iso_utc_now(),+ "uptime_seconds": _uptime_seconds(),+ "checks": checks,+ "runtime": _runtime_payload(),+ }+ deployment_profile = os.environ.get("HEADROOM_DEPLOYMENT_PROFILE")+ if deployment_profile:+ payload["deployment"] = {+ "profile": deployment_profile,+ "preset": os.environ.get("HEADROOM_DEPLOYMENT_PRESET"),+ "runtime": os.environ.get("HEADROOM_DEPLOYMENT_RUNTIME"),+ "supervisor": os.environ.get("HEADROOM_DEPLOYMENT_SUPERVISOR"),+ "scope": os.environ.get("HEADROOM_DEPLOYMENT_SCOPE"),+ }+ if include_config:+ payload["config"] = {+ "backend": config.backend,+ "optimize": config.optimize,+ "cache": config.cache_enabled,+ "rate_limit": config.rate_limit_enabled,+ "memory": config.memory_enabled,+ "learn": config.traffic_learning_enabled,+ "code_graph": config.code_graph_watcher,+ "pid": os.getpid(),+ }+ return payload++ # CORS+ app.add_middleware(+ CORSMiddleware,+ allow_origins=["*"],+ allow_credentials=True,+ allow_methods=["*"],+ allow_headers=["*"],+ )++ # X-Headroom-Stack: SDK adapters (TS openai/anthropic/etc.) tag their+ # requests so telemetry can segment by integration surface. Registered+ # before extension middleware so any extension-level auth/guards run+ # outermost and we don't count requests they reject.+ @app.middleware("http")+ async def _record_headroom_stack(request, call_next):+ if request.url.path.startswith("/v1/"):+ stack = request.headers.get("x-headroom-stack")+ if stack:+ try:+ proxy.metrics.record_stack(stack)+ except Exception:+ logger.debug("record_stack failed", exc_info=True)+ return await call_next(request)++ # Third-party proxy extensions (Enterprise, custom plugins). Discovered via+ # the `headroom.proxy_extension` entry-point group. An extension that raises+ # from its install() is a deliberate fail-closed signal and aborts startup.+ from headroom.proxy.extensions import install_all as _install_extensions++ _install_extensions(app, config)++ # Health & Metrics+ @app.get("/livez")+ async def livez():+ return JSONResponse(+ status_code=200,+ content={+ "service": "headroom-proxy",+ "status": "healthy",+ "alive": True,+ "version": __version__,+ "timestamp": _iso_utc_now(),+ "uptime_seconds": _uptime_seconds(),+ },+ )++ @app.get("/readyz")+ async def readyz():+ payload = _health_payload(include_config=False)+ return JSONResponse(status_code=200 if payload["ready"] else 503, content=payload)++ @app.get("/health")+ async def health():+ payload = _health_payload(include_config=True)+ return JSONResponse(status_code=200, content=payload)++ # Loopback-only debug introspection (Unit 5). A remote IP gets 404 —+ # debug endpoints are invisible to external scanners.+ from headroom.proxy.debug_introspection import (+ collect_tasks as _collect_tasks,+ )+ from headroom.proxy.loopback_guard import require_loopback as _require_loopback++ @app.get("/debug/tasks", dependencies=[Depends(_require_loopback)])+ async def debug_tasks(stack: bool = False):+ """Enumerate running asyncio tasks.++ Default is cheap — ``stack_depth`` is ``null`` in every entry so+ a storm snapshot does not walk 50+ coroutine frames synchronously.+ Pass ``?stack=true`` to compute ``stack_depth`` for each task+ (useful for single-shot human debugging).+ """+ ws_registry = getattr(proxy, "ws_sessions", None)+ return JSONResponse(+ status_code=200,+ content=_collect_tasks(ws_registry, with_stack_depth=stack),+ )++ @app.get("/debug/ws-sessions", dependencies=[Depends(_require_loopback)])+ async def debug_ws_sessions():+ ws_registry = getattr(proxy, "ws_sessions", None)+ snapshot = ws_registry.snapshot() if ws_registry is not None else []+ return JSONResponse(status_code=200, content=snapshot)++ @app.get("/debug/warmup", dependencies=[Depends(_require_loopback)])+ async def debug_warmup():+ warmup_registry = getattr(proxy, "warmup", None)+ payload = warmup_registry.to_dict() if warmup_registry is not None else {}+ payload["runtime"] = _runtime_payload()+ return JSONResponse(status_code=200, content=payload)++ @app.get("/dashboard", response_class=HTMLResponse)+ async def dashboard():+ """Serve the Headroom dashboard UI."""+ return get_dashboard_html()++ DASHBOARD_STATS_CACHE_TTL_SECONDS = 5.0+ _stats_snapshot_lock = asyncio.Lock()+ _stats_snapshot: dict[str, Any] = {"expires_at": 0.0, "value": None}++ async def _build_stats_payload() -> dict[str, Any]:+ """Build the full `/stats` response payload.++ This is the main stats endpoint - it aggregates data from all subsystems:+ - Request metrics (total, cached, failed, by model/provider)+ - Token usage and savings+ - Cost tracking+ - Canonical persisted display_session metrics for downstream dashboards+ - Compression (CCR) statistics+ - Telemetry/TOIN (data flywheel) statistics+ - Cache and rate limiter stats+ """+ m = proxy.metrics++ # Calculate average latency+ avg_latency_ms = round(m.latency_sum_ms / m.latency_count, 2) if m.latency_count > 0 else 0+ min_latency_ms = (+ round(m.latency_min_ms, 2)+ if m.latency_count > 0 and m.latency_min_ms != float("inf")+ else 0+ )+ max_latency_ms = round(m.latency_max_ms, 2) if m.latency_count > 0 else 0++ # Calculate Headroom overhead (optimization time only, excludes pass-through requests)+ avg_overhead_ms = (+ round(m.overhead_sum_ms / m.overhead_count, 2) if m.overhead_count > 0 else 0+ )+ min_overhead_ms = (+ round(m.overhead_min_ms, 2)+ if m.overhead_count > 0 and m.overhead_min_ms != float("inf")+ else 0+ )+ max_overhead_ms = round(m.overhead_max_ms, 2) if m.overhead_count > 0 else 0++ # Calculate TTFB (time to first byte)+ avg_ttfb_ms = round(m.ttfb_sum_ms / m.ttfb_count, 2) if m.ttfb_count > 0 else 0+ min_ttfb_ms = (+ round(m.ttfb_min_ms, 2) if m.ttfb_count > 0 and m.ttfb_min_ms != float("inf") else 0+ )+ max_ttfb_ms = round(m.ttfb_max_ms, 2) if m.ttfb_count > 0 else 0++ # Get compression store stats+ store = get_compression_store()+ compression_stats = store.get_stats()++ # Get telemetry/TOIN stats+ telemetry = get_telemetry_collector()+ telemetry_stats = telemetry.get_stats()++ # Get feedback loop stats+ feedback = get_compression_feedback()+ feedback_stats = feedback.get_stats()++ # 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()+ cli_tokens_avoided = (+ cli_filtering_stats.get("tokens_saved", 0) if cli_filtering_stats else 0+ )++ # Calculate total tokens before compression+ total_tokens_before = m.tokens_input_total + m.tokens_saved_total++ # Build human-readable summary+ summary = _build_session_summary(+ proxy, m, prefix_cache_stats, cli_tokens_avoided, total_tokens_before+ )+ # DEBUG: log the summary payload for external upsert consumers+ try:+ logger.debug("/stats summary data: %r", summary)+ except Exception:+ logger.warning("Failed to log /stats summary payload")++ # Compression cache stats (token mode)+ compression_cache_stats: dict = {}+ if proxy.config.mode == PROXY_MODE_TOKEN and proxy._compression_caches:+ total_entries = 0+ total_hits = 0+ total_misses = 0+ total_tokens_saved = 0+ for cache in proxy._compression_caches.values():+ s = cache.get_stats()+ total_entries += s.get("entries", 0)+ total_hits += s.get("hits", 0)+ total_misses += s.get("misses", 0)+ total_tokens_saved += s.get("total_tokens_saved", 0)+ compression_cache_stats = {+ "mode": PROXY_MODE_TOKEN,+ "active_sessions": len(proxy._compression_caches),+ "total_entries": total_entries,+ "total_hits": total_hits,+ "total_misses": total_misses,+ "hit_rate": round(total_hits / max(1, total_hits + total_misses) * 100, 1),+ "total_tokens_saved": total_tokens_saved,+ }+ else:+ compression_cache_stats = {"mode": proxy.config.mode}++ # Build unified savings summary (all layers)+ compression_tokens = m.tokens_saved_total+ cache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)+ total_tokens_all_layers = compression_tokens + cli_tokens_avoided+ persistent_savings = m.savings_tracker.stats_preview()+ display_session = persistent_savings.get("display_session", {})++ return {+ "summary": summary,+ "savings": {+ "total_tokens": total_tokens_all_layers,+ "by_layer": {+ "cli_filtering": {+ "tokens": cli_tokens_avoided,+ "description": "Tokens avoided by CLI output filtering (rtk) before reaching context",+ },+ "compression": {+ "tokens": compression_tokens,+ "description": "Tokens removed by proxy compression (SmartCrusher, ContentRouter, etc.)",+ },+ "prefix_cache": {+ "discount_usd": round(cache_net_usd, 4),+ "description": (+ "Cost discount from provider prefix caching. "+ "Headroom's CacheAligner improves hit rates; "+ "baseline caching is provider-native."+ ),+ },+ },+ },+ "requests": {+ "total": m.requests_total,+ "cached": m.requests_cached,+ "rate_limited": m.requests_rate_limited,+ "failed": m.requests_failed,+ "by_provider": dict(m.requests_by_provider),+ "by_model": dict(m.requests_by_model),+ "by_stack": dict(m.requests_by_stack),+ },+ "tokens": {+ "input": m.tokens_input_total,+ "output": m.tokens_output_total,+ "saved": m.tokens_saved_total,+ "cli_tokens_avoided": cli_tokens_avoided,+ "total_before_compression": total_tokens_before,+ "savings_percent": round(+ (m.tokens_saved_total / total_tokens_before * 100)+ if total_tokens_before > 0+ else 0,+ 2,+ ),+ },+ "latency": {+ "average_ms": avg_latency_ms,+ "min_ms": min_latency_ms,+ "max_ms": max_latency_ms,+ "total_requests": m.latency_count,+ },+ "overhead": {+ "average_ms": avg_overhead_ms,+ "min_ms": min_overhead_ms,+ "max_ms": max_overhead_ms,+ },+ "ttfb": {+ "average_ms": avg_ttfb_ms,+ "min_ms": min_ttfb_ms,+ "max_ms": max_ttfb_ms,+ },+ "pipeline_timing": {+ name: {+ "average_ms": round(+ m.transform_timing_sum[name] / m.transform_timing_count[name], 2+ ),+ "max_ms": round(m.transform_timing_max[name], 2),+ "count": m.transform_timing_count[name],+ }+ for name in sorted(m.transform_timing_sum.keys())+ }+ if m.transform_timing_sum+ else {},+ "waste_signals": dict(m.waste_signals_total) if m.waste_signals_total else {},+ "savings_history": m.savings_history[-100:], # Last 100 data points+ "display_session": display_session,+ "persistent_savings": persistent_savings,+ "prefix_cache": prefix_cache_stats,+ "cost": _merge_cost_stats(+ proxy.cost_tracker.stats() if proxy.cost_tracker else None,+ prefix_cache_stats,+ cli_tokens_avoided=cli_tokens_avoided,+ ),+ "compression": {+ "ccr_entries": compression_stats.get("entry_count", 0),+ "ccr_max_entries": compression_stats.get("max_entries", 0),+ "original_tokens_cached": compression_stats.get("total_original_tokens", 0),+ "compressed_tokens_cached": compression_stats.get("total_compressed_tokens", 0),+ "ccr_retrievals": compression_stats.get("total_retrievals", 0),+ },+ "compression_cache": compression_cache_stats,+ "anon_telemetry_shipping": is_telemetry_enabled(),+ "telemetry": {+ "enabled": telemetry_stats.get("enabled", False),+ "total_compressions": telemetry_stats.get("total_compressions", 0),+ "total_retrievals": telemetry_stats.get("total_retrievals", 0),+ "global_retrieval_rate": round(telemetry_stats.get("global_retrieval_rate", 0), 4),+ "tool_signatures_tracked": telemetry_stats.get("tool_signatures_tracked", 0),+ "avg_compression_ratio": round(telemetry_stats.get("avg_compression_ratio", 0), 4),+ "avg_token_reduction": round(telemetry_stats.get("avg_token_reduction", 0), 4),+ },+ "otel": get_otel_metrics_status(),+ "langfuse": get_langfuse_tracing_status(),+ "feedback_loop": {+ "tools_tracked": feedback_stats.get("tools_tracked", 0),+ "total_compressions": feedback_stats.get("total_compressions", 0),+ "total_retrievals": feedback_stats.get("total_retrievals", 0),+ "global_retrieval_rate": round(feedback_stats.get("global_retrieval_rate", 0), 4),+ "tools_with_high_retrieval": sum(+ 1+ for p in feedback_stats.get("tool_patterns", {}).values()+ if p.get("retrieval_rate", 0) > 0.3+ ),+ },+ "toin": get_toin().get_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,+ "recent_requests": proxy.logger.get_recent(10) if proxy.logger else [],+ "log_full_messages": proxy.config.log_full_messages if proxy else False,+ **get_quota_registry().get_all_stats(),+ }++ async def _get_cached_stats_payload() -> dict[str, Any]:+ """Return a short-TTL cached `/stats` snapshot for dashboard polling."""+ now = time.monotonic()+ cached_payload = cast(dict[str, Any] | None, _stats_snapshot.get("value"))+ if cached_payload is not None and now < float(_stats_snapshot["expires_at"]):+ return cached_payload++ async with _stats_snapshot_lock:+ now = time.monotonic()+ cached_payload = cast(dict[str, Any] | None, _stats_snapshot.get("value"))+ if cached_payload is not None and now < float(_stats_snapshot["expires_at"]):+ return cached_payload++ payload = await _build_stats_payload()+ _stats_snapshot["value"] = payload+ _stats_snapshot["expires_at"] = time.monotonic() + DASHBOARD_STATS_CACHE_TTL_SECONDS+ return payload++ @app.get("/stats")+ async def stats(cached: bool = False):+ """Get comprehensive proxy statistics.++ This is the main stats endpoint - it aggregates data from all subsystems:+ - Request metrics (total, cached, failed, by model/provider)+ - Token usage and savings+ - Cost tracking+ - Canonical persisted display_session metrics for downstream dashboards+ - Compression (CCR) statistics+ - Telemetry/TOIN (data flywheel) statistics+ - Cache and rate limiter stats++ Use ``?cached=1`` for the dashboard fast path. That returns a short-TTL+ snapshot to avoid rebuilding the full payload on every UI poll.+ """+ if cached:+ return await _get_cached_stats_payload()+ return await _build_stats_payload()++ @app.get("/stats-history")+ async def stats_history(+ format: Literal["json", "csv"] = "json",+ series: Literal["history", "hourly", "daily", "weekly", "monthly"] = "history",+ history_mode: Literal["compact", "full", "none"] = "compact",+ ):+ """Get durable proxy compression history plus display-session state."""+ if format == "csv":+ filename = f"headroom-stats-history-{series}.csv"+ return Response(+ content=proxy.metrics.savings_tracker.export_csv(series=series),+ media_type="text/csv; charset=utf-8",+ headers={"Content-Disposition": f'attachment; filename="{filename}"'},+ )++ return proxy.metrics.savings_tracker.history_response(history_mode=history_mode)++ @app.get("/transformations/feed")+ async def transformations_feed(limit: int = 20):+ """Get recent message transformations for the live feed.++ Returns empty list if log_full_messages is disabled (messages are not stored).+ """+ if limit > 100:+ limit = 100++ transformations = []+ log_full_messages = proxy.config.log_full_messages if proxy else False++ if proxy and proxy.logger:+ logs = proxy.logger.get_recent_with_messages(limit)+ for log in logs:+ transformations.append(+ {+ "request_id": log.get("request_id"),+ "timestamp": log.get("timestamp"),+ "provider": log.get("provider"),+ "model": log.get("model"),+ "input_tokens_original": log.get("input_tokens_original"),+ "input_tokens_optimized": log.get("input_tokens_optimized"),+ "tokens_saved": log.get("tokens_saved"),+ "savings_percent": log.get("savings_percent"),+ "transforms_applied": log.get("transforms_applied", []),+ "request_messages": log.get("request_messages"),+ "response_content": log.get("response_content"),+ "turn_id": log.get("turn_id"),+ }+ )++ return {"transformations": transformations, "log_full_messages": log_full_messages}++ @app.get("/subscription-window")+ async def subscription_window():+ """Current Anthropic subscription window utilisation and Headroom contribution."""+ tracker = get_subscription_tracker()+ if tracker is None:+ return JSONResponse(+ status_code=503,+ content={"error": "Subscription tracking is not enabled"},+ )+ return JSONResponse(content=tracker.state)++ @app.get("/quota")+ async def quota():+ """Unified quota/rate-limit stats for all registered providers (Anthropic, Codex, Copilot)."""+ return JSONResponse(content=get_quota_registry().get_all_stats())++ @app.get("/metrics")+ async def metrics():+ """Prometheus metrics endpoint."""+ return PlainTextResponse(+ await proxy.metrics.export(),+ media_type="text/plain; version=0.0.4",+ )++ # Debug endpoints+ @app.get("/debug/memory")+ async def debug_memory():+ """Get detailed memory usage statistics.++ Returns memory usage for all tracked components including:+ - Process-level memory (RSS, VMS, percent)+ - Per-component memory usage and budgets+ - Cache hit/miss statistics+ - Total tracked vs target budget++ This endpoint is useful for debugging memory issues and+ monitoring memory budgets.+ """+ from ..memory.tracker import MemoryTracker++ tracker = MemoryTracker.get()++ # Register components if not already registered+ _register_memory_components(proxy, tracker)++ report = tracker.get_report()+ return report.to_dict()++ @app.post("/cache/clear")+ async def clear_cache():+ """Clear the response cache."""+ if proxy.cache:+ await proxy.cache.clear()+ return {"status": "cleared"}+ return {"status": "cache disabled"}++ # CCR (Compress-Cache-Retrieve) endpoints+ @app.post("/v1/retrieve")+ async def ccr_retrieve(request: Request):+ """Retrieve original content from CCR compression cache.++ This is the "Retrieve" part of CCR (Compress-Cache-Retrieve).+ When SmartCrusher compresses tool outputs, the original data is cached.+ LLMs can call this endpoint to get more data if needed.++ Request body:+ hash (str): Hash key from compression marker (required)+ query (str): Optional search query to filter results++ Response:+ Full retrieval: {"hash": "...", "original_content": "...", ...}+ Search: {"hash": "...", "query": "...", "results": [...], "count": N}+ """+ data = await request.json()+ hash_key = data.get("hash")+ query = data.get("query")++ if not hash_key:+ raise HTTPException(status_code=400, detail="hash required")++ store = get_compression_store()++ if query:+ # Search within cached content+ results = store.search(hash_key, query)+ return {+ "hash": hash_key,+ "query": query,+ "results": results,+ "count": len(results),+ }+ else:+ # Return full original content+ entry = store.retrieve(hash_key)+ if entry:+ return {+ "hash": hash_key,+ "original_content": entry.original_content,+ "original_tokens": entry.original_tokens,+ "original_item_count": entry.original_item_count,+ "compressed_item_count": entry.compressed_item_count,+ "tool_name": entry.tool_name,+ "retrieval_count": entry.retrieval_count,+ }+ raise HTTPException(+ status_code=404, detail="Entry not found or expired (TTL: 5 minutes)"+ )++ @app.get("/v1/retrieve/stats")+ async def ccr_stats():+ """Get CCR compression store statistics."""+ store = get_compression_store()+ stats = store.get_stats()+ events = store.get_retrieval_events(limit=20)+ return {+ "store": stats,+ "recent_retrievals": [+ {+ "hash": e.hash,+ "query": e.query,+ "items_retrieved": e.items_retrieved,+ "total_items": e.total_items,+ "tool_name": e.tool_name,+ "retrieval_type": e.retrieval_type,+ }+ for e in events+ ],+ }++ @app.get("/v1/feedback")+ async def ccr_feedback():+ """Get CCR feedback loop statistics and learned patterns.++ This endpoint exposes the feedback loop's learned patterns for monitoring+ and debugging. It shows:+ - Per-tool retrieval rates (high = compress less aggressively)+ - Common search queries per tool+ - Queried fields (suggest what to preserve)++ Use this to understand how well compression is working and whether+ the feedback loop is adjusting appropriately.+ """+ feedback = get_compression_feedback()+ stats = feedback.get_stats()+ return {+ "feedback": stats,+ "hints_example": {+ tool_name: {+ "hints": {+ "max_items": hints.max_items+ if (hints := feedback.get_compression_hints(tool_name))+ else 15,+ "suggested_items": hints.suggested_items if hints else None,+ "skip_compression": hints.skip_compression if hints else False,+ "preserve_fields": hints.preserve_fields if hints else [],+ "reason": hints.reason if hints else "",+ }+ }+ for tool_name in list(stats.get("tool_patterns", {}).keys())[:5]+ },+ }++ @app.get("/v1/feedback/{tool_name}")+ async def ccr_feedback_for_tool(tool_name: str):+ """Get compression hints for a specific tool.++ Returns feedback-based hints that would be used for compressing+ this tool's output.+ """+ feedback = get_compression_feedback()+ hints = feedback.get_compression_hints(tool_name)+ patterns = feedback.get_all_patterns().get(tool_name)++ return {+ "tool_name": tool_name,+ "hints": {+ "max_items": hints.max_items,+ "min_items": hints.min_items,+ "suggested_items": hints.suggested_items,+ "aggressiveness": hints.aggressiveness,+ "skip_compression": hints.skip_compression,+ "preserve_fields": hints.preserve_fields,+ "reason": hints.reason,+ },+ "pattern": {+ "total_compressions": patterns.total_compressions if patterns else 0,+ "total_retrievals": patterns.total_retrievals if patterns else 0,+ "retrieval_rate": patterns.retrieval_rate if patterns else 0.0,+ "full_retrieval_rate": patterns.full_retrieval_rate if patterns else 0.0,+ "search_rate": patterns.search_rate if patterns else 0.0,+ "common_queries": list(patterns.common_queries.keys())[:10] if patterns else [],+ "queried_fields": list(patterns.queried_fields.keys())[:10] if patterns else [],+ }+ if patterns+ else None,+ }++ # Telemetry endpoints (Data Flywheel)+ @app.get("/v1/telemetry")+ async def telemetry_stats():+ """Get telemetry statistics for the data flywheel.++ This endpoint exposes privacy-preserving telemetry data that powers+ the data flywheel - learning optimal compression strategies across+ tool types based on usage patterns.++ What's collected (anonymized):+ - Tool output structure patterns (field types, not values)+ - Compression decisions and ratios+ - Retrieval patterns (rate, type, not content)+ - Strategy effectiveness++ What's NOT collected:+ - Actual data values+ - User identifiers+ - Queries or search terms+ - File paths or tool names (hashed by default)+ """+ telemetry = get_telemetry_collector()+ return telemetry.get_stats()++ @app.get("/v1/telemetry/export")+ async def telemetry_export():+ """Export full telemetry data for aggregation.++ This endpoint exports all telemetry data in a format suitable for+ cross-user aggregation. The data is privacy-preserving - no actual+ values are included, only structural patterns and statistics.++ Use this for:+ - Building a central learning service+ - Sharing learned patterns across instances+ - Analysis and debugging+ """+ telemetry = get_telemetry_collector()+ return telemetry.export_stats()++ @app.post("/v1/telemetry/import")+ async def telemetry_import(request: Request):+ """Import telemetry data from another source.++ This allows merging telemetry from multiple sources for cross-user+ learning. The imported data is merged with existing statistics.++ Request body: Telemetry export data from /v1/telemetry/export+ """+ telemetry = get_telemetry_collector()+ data = await request.json()+ telemetry.import_stats(data)+ return {"status": "imported", "current_stats": telemetry.get_stats()}++ @app.get("/v1/telemetry/tools")+ async def telemetry_tools():+ """Get telemetry statistics for all tracked tool signatures.++ Returns statistics per tool signature (anonymized), including:+ - Compression ratios and strategy usage+ - Retrieval rates (high = compression too aggressive)+ - Learned recommendations+ """+ telemetry = get_telemetry_collector()+ all_stats = telemetry.get_all_tool_stats()+ return {+ "tool_count": len(all_stats),+ "tools": {sig_hash: stats.to_dict() for sig_hash, stats in all_stats.items()},+ }++ @app.get("/v1/telemetry/tools/{signature_hash}")+ async def telemetry_tool_detail(signature_hash: str):+ """Get detailed telemetry for a specific tool signature.++ Includes learned recommendations if enough data has been collected.+ """+ telemetry = get_telemetry_collector()+ stats = telemetry.get_tool_stats(signature_hash)+ recommendations = telemetry.get_recommendations(signature_hash)++ if stats is None:+ raise HTTPException(+ status_code=404, detail=f"No telemetry found for signature: {signature_hash}"+ )++ return {+ "signature_hash": signature_hash,+ "stats": stats.to_dict(),+ "recommendations": recommendations,+ }++ # TOIN (Tool Output Intelligence Network) endpoints+ @app.get("/v1/toin/stats")+ async def toin_stats():+ """Get overall TOIN statistics.++ Returns aggregated statistics from the Tool Output Intelligence Network,+ which learns optimal compression strategies across all tool types.++ Response includes:+ - enabled: Whether TOIN is enabled+ - patterns_tracked: Number of unique tool patterns being tracked+ - total_compressions: Total compression events recorded+ - total_retrievals: Total retrieval events recorded+ - global_retrieval_rate: Overall retrieval rate (high = compression too aggressive)+ - patterns_with_recommendations: Patterns with enough data for recommendations+ """+ toin = get_toin()+ return toin.get_stats()++ @app.get("/v1/toin/patterns")+ async def toin_patterns(limit: int = 20):+ """List TOIN patterns with most samples.++ Returns patterns sorted by sample_size descending. Use this to see+ which tool types have the most data and their learned behaviors.++ Query params:+ limit: Maximum number of patterns to return (default 20)++ Response includes for each pattern:+ - hash: Truncated tool signature hash (12 chars)+ - compressions: Total compression events+ - retrievals: Total retrieval events+ - retrieval_rate: Percentage of compressions that triggered retrieval+ - confidence: Confidence level in recommendations (0.0-1.0)+ - skip_recommended: Whether TOIN recommends skipping compression+ - optimal_max_items: Learned optimal max_items setting+ """+ toin = get_toin()+ exported = toin.export_patterns()+ patterns_data = exported.get("patterns", {})++ # Convert to list and sort by sample_size+ patterns_list = []+ for sig_hash, pattern_dict in patterns_data.items():+ sample_size = pattern_dict.get("sample_size", 0)+ total_compressions = pattern_dict.get("total_compressions", 0)+ total_retrievals = pattern_dict.get("total_retrievals", 0)+ retrieval_rate = (+ total_retrievals / total_compressions if total_compressions > 0 else 0.0+ )++ patterns_list.append(+ {+ "hash": sig_hash[:12],+ "compressions": total_compressions,+ "retrievals": total_retrievals,+ "retrieval_rate": f"{retrieval_rate:.1%}",+ "confidence": round(pattern_dict.get("confidence", 0.0), 3),+ "skip_recommended": pattern_dict.get("skip_compression_recommended", False),+ "optimal_max_items": pattern_dict.get("optimal_max_items", 20),+ "sample_size": sample_size,+ }+ )++ # Sort by sample_size descending+ patterns_list.sort(key=lambda p: p["sample_size"], reverse=True)++ # Remove sample_size from output (used only for sorting)+ for p in patterns_list:+ del p["sample_size"]++ return patterns_list[:limit]++ @app.get("/v1/toin/pattern/{hash_prefix}")+ async def toin_pattern_detail(hash_prefix: str):+ """Get detailed TOIN pattern info by hash prefix.++ Searches for a pattern where the tool signature hash starts with+ the provided prefix. Returns full pattern details if found.++ Path params:+ hash_prefix: Beginning of the tool signature hash (min 4 chars recommended)++ Response: Full pattern.to_dict() with all learned statistics and recommendations.+ """+ toin = get_toin()+ exported = toin.export_patterns()+ patterns_data = exported.get("patterns", {})++ # Search for pattern with matching hash prefix+ for sig_hash, pattern_dict in patterns_data.items():+ if sig_hash.startswith(hash_prefix):+ return pattern_dict++ raise HTTPException(+ status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"+ )++ @app.get("/v1/retrieve/{hash_key}")+ async def ccr_retrieve_get(hash_key: str, query: str | None = None):+ """GET version of CCR retrieve for easier testing."""+ store = get_compression_store()++ if query:+ results = store.search(hash_key, query)+ return {+ "hash": hash_key,+ "query": query,+ "results": results,+ "count": len(results),+ }+ else:+ entry = store.retrieve(hash_key)+ if entry:+ return {+ "hash": hash_key,+ "original_content": entry.original_content,+ "original_tokens": entry.original_tokens,+ "original_item_count": entry.original_item_count,+ "compressed_item_count": entry.compressed_item_count,+ "tool_name": entry.tool_name,+ "retrieval_count": entry.retrieval_count,+ }+ raise HTTPException(status_code=404, detail="Entry not found or expired")++ # CCR Tool Call Handler - for agent frameworks to call when LLM uses headroom_retrieve+ @app.post("/v1/retrieve/tool_call")+ async def ccr_handle_tool_call(request: Request):+ """Handle a CCR tool call from an LLM response.++ This endpoint accepts tool call formats from various providers and returns+ a properly formatted tool result. Agent frameworks can use this to handle+ CCR tool calls without implementing the retrieval logic themselves.++ Request body (Anthropic format):+ {+ "tool_call": {+ "id": "toolu_123",+ "name": "headroom_retrieve",+ "input": {"hash": "abc123", "query": "optional search"}+ },+ "provider": "anthropic"+ }++ Request body (OpenAI format):+ {+ "tool_call": {+ "id": "call_123",+ "function": {+ "name": "headroom_retrieve",+ "arguments": "{\"hash\": \"abc123\"}"+ }+ },+ "provider": "openai"+ }++ Response:+ {+ "tool_result": {...}, # Formatted for the provider+ "success": true,+ "data": {...} # Raw retrieval data+ }+ """+ data = await request.json()+ tool_call = data.get("tool_call", {})+ provider = data.get("provider", "anthropic")++ # Parse the tool call+ hash_key, query = parse_tool_call(tool_call, provider)++ if hash_key is None:+ raise HTTPException(+ status_code=400, detail=f"Invalid tool call or not a {CCR_TOOL_NAME} call"+ )++ # Perform retrieval+ store = get_compression_store()++ if query:+ results = store.search(hash_key, query)+ retrieval_data = {+ "hash": hash_key,+ "query": query,+ "results": results,+ "count": len(results),+ }+ else:+ entry = store.retrieve(hash_key)+ if entry:+ retrieval_data = {+ "hash": hash_key,+ "original_content": entry.original_content,+ "original_item_count": entry.original_item_count,+ "compressed_item_count": entry.compressed_item_count,+ }+ else:+ retrieval_data = {+ "error": "Entry not found or expired (TTL: 5 minutes)",+ "hash": hash_key,+ }++ # Format tool result for provider+ tool_call_id = tool_call.get("id", "")+ result_content = json.dumps(retrieval_data, indent=2)++ if provider == "anthropic":+ tool_result = {+ "type": "tool_result",+ "tool_use_id": tool_call_id,+ "content": result_content,+ }+ elif provider == "openai":+ tool_result = {+ "role": "tool",+ "tool_call_id": tool_call_id,+ "content": result_content,+ }+ else:+ tool_result = {+ "tool_call_id": tool_call_id,+ "content": result_content,+ }++ return {+ "tool_result": tool_result,+ "success": "error" not in retrieval_data,+ "data": retrieval_data,+ }++ # Compression-only endpoint (for TypeScript SDK and other HTTP clients)+ @app.post("/v1/compress")+ async def compress_messages(request: Request):+ return await proxy.handle_compress(request)++ register_provider_routes(app, proxy)++ return app+++def _get_code_aware_banner_status(config: ProxyConfig) -> str:+ """Get code-aware compression status line for banner."""+ if config.code_aware_enabled:+ if is_tree_sitter_available():+ return "ENABLED (AST-based)"+ else:+ return "NOT INSTALLED (pip install headroom-ai[code])"+ else:+ if is_tree_sitter_available():+ return "DISABLED (remove --no-code-aware to enable)"+ return "DISABLED"+++def run_server(+ config: ProxyConfig | None = None,+ workers: int = 1,+ limit_concurrency: int = 1000,+):+ """Run the proxy server.++ Args:+ config: Proxy configuration+ workers: Number of worker processes (use N for multi-core scaling)+ limit_concurrency: Max concurrent connections before 503 response+ """+ if not FASTAPI_AVAILABLE:+ print("ERROR: FastAPI required. Install: pip install fastapi uvicorn httpx")+ sys.exit(1)++ config = config or ProxyConfig()+ app = create_app(config)++ code_aware_status = _get_code_aware_banner_status(config)++ # Format connection pool info+ pool_info = f"max={config.max_connections}, keepalive={config.max_keepalive_connections}"+ http2_status = "ENABLED" if config.http2 else "DISABLED"++ backend_status = format_backend_status(+ backend=config.backend,+ anyllm_provider=config.anyllm_provider,+ bedrock_region=config.bedrock_region,+ )++ print(f"""+╔══════════════════════════════════════════════════════════════════════╗+║ HEADROOM PROXY SERVER ║+╠══════════════════════════════════════════════════════════════════════╣+║ Version: 1.0.0 ║+║ Listening: http://{config.host}:{config.port:<5} ║+║ Workers: {workers:<3} Concurrency Limit: {limit_concurrency:<5} ║+║ Backend: {backend_status:<59}║+╠══════════════════════════════════════════════════════════════════════╣+║ FEATURES: ║+║ Optimization: {"ENABLED " if config.optimize else "DISABLED"} ║+║ Caching: {"ENABLED " if config.cache_enabled else "DISABLED"} (TTL: {config.cache_ttl_seconds}s) ║+║ Rate Limiting: {"ENABLED " if config.rate_limit_enabled else "DISABLED"} ({config.rate_limit_requests_per_minute} req/min, {config.rate_limit_tokens_per_minute:,} tok/min) ║+║ Retry: {"ENABLED " if config.retry_enabled else "DISABLED"} (max {config.retry_max_attempts} attempts) ║+║ Cost Tracking: {"ENABLED " if config.cost_tracking_enabled else "DISABLED"} (budget: {"$" + str(config.budget_limit_usd) + "/" + config.budget_period if config.budget_limit_usd else "unlimited"}) ║+║ Code-Aware: {code_aware_status:<52}║+║ HTTP/2: {http2_status:<52}║+║ Conn Pool: {pool_info:<52}║+╠══════════════════════════════════════════════════════════════════════╣+║ USAGE: ║+║ Claude Code: ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude ║+║ Cursor: Set base URL in settings ║+╠══════════════════════════════════════════════════════════════════════╣+║ ENDPOINTS: ║+║ /livez Process liveness ║+║ /readyz Traffic readiness ║+║ /health Aggregate health ║+║ /stats Detailed statistics ║+║ /metrics Prometheus metrics ║+║ /cache/clear Clear response cache ║+║ /v1/retrieve CCR: Retrieve compressed content ║+║ /v1/retrieve/stats CCR: Compression store stats ║+║ /v1/retrieve/tool_call CCR: Handle LLM tool calls ║+║ /v1/feedback CCR: Feedback loop stats & patterns ║+║ /v1/feedback/{{tool}} CCR: Compression hints for a tool ║+║ /v1/telemetry Data flywheel: Telemetry stats ║+║ /v1/telemetry/export Data flywheel: Export for aggregation ║+║ /v1/telemetry/tools Data flywheel: Per-tool stats ║+║ /v1/toin/stats TOIN: Overall intelligence stats ║+║ /v1/toin/patterns TOIN: List learned patterns ║+║ /v1/toin/pattern/{{hash}} TOIN: Pattern details by hash ║+╚══════════════════════════════════════════════════════════════════════╝+""")++ uvicorn.run(+ app,+ host=config.host,+ port=config.port,+ log_level="warning",+ workers=workers if workers > 1 else None, # None = single process (default)+ limit_concurrency=limit_concurrency,+ # Defense-in-depth: the loopback guard for /debug/* endpoints trusts+ # request.client.host. uvicorn's ProxyHeadersMiddleware rewrites that+ # from X-Forwarded-For when FORWARDED_ALLOW_IPS is broader than the+ # default. Disabling proxy_headers here guarantees the guard sees the+ # real peer address regardless of env.+ proxy_headers=False,+ )+++def _get_env_bool(name: str, default: bool) -> bool:+ """Get boolean from environment variable."""+ val = os.environ.get(name)+ if val is None:+ return default+ return val.lower() in ("true", "1", "yes", "on")+++def _get_env_int(name: str, default: int) -> int:+ """Get integer from environment variable."""+ val = os.environ.get(name)+ if val is None:+ return default+ try:+ return int(val)+ except ValueError:+ return default+++def _get_env_float(name: str, default: float) -> float:+ """Get float from environment variable."""+ val = os.environ.get(name)+ if val is None:+ return default+ try:+ return float(val)+ except ValueError:+ return default+++def _get_env_str(name: str, default: str) -> str:+ """Get string from environment variable."""+ return os.environ.get(name, default)+++def _parse_tool_profiles(cli_profiles: list[str]) -> dict[str, Any]:+ """Parse tool profiles from CLI args and HEADROOM_TOOL_PROFILES env var.++ Format: ToolName:level (e.g., Grep:conservative, Bash:moderate)+ Env var format: comma-separated (e.g., "Grep:conservative,Bash:moderate")++ Returns:+ Dict mapping tool names to CompressionProfile instances.+ """+ from headroom.config import PROFILE_PRESETS, CompressionProfile++ profiles: dict[str, CompressionProfile] = {}+ raw_entries: list[str] = list(cli_profiles)++ # Also check env var+ env_val = os.environ.get("HEADROOM_TOOL_PROFILES", "")+ if env_val:+ raw_entries.extend(e.strip() for e in env_val.split(",") if e.strip())++ for entry in raw_entries:+ if ":" not in entry:+ logger.warning("Invalid tool profile format (expected ToolName:level): %s", entry)+ continue+ tool_name, level = entry.split(":", 1)+ tool_name = tool_name.strip()+ level = level.strip().lower()++ if level in PROFILE_PRESETS:+ profiles[tool_name] = PROFILE_PRESETS[level]+ else:+ logger.warning(+ "Unknown profile level '%s' for tool '%s'. Use: conservative, moderate, aggressive",+ level,+ tool_name,+ )++ return profiles+++if __name__ == "__main__":+ parser = argparse.ArgumentParser(description="Headroom Proxy Server")++ # Server+ parser.add_argument("--host", default="127.0.0.1")+ parser.add_argument("--port", type=int, default=8787)+ parser.add_argument(+ "--openai-api-url", help=f"Custom OpenAI API URL (default: {DEFAULT_OPENAI_API_URL})"+ )+ parser.add_argument(+ "--anthropic-api-url",+ help=f"Custom Anthropic API URL (default: {DEFAULT_ANTHROPIC_API_URL})",+ )++ # Backend (anthropic direct, bedrock, openrouter, anyllm, or litellm-<provider>)+ parser.add_argument(+ "--backend",+ default="anthropic",+ help=(+ "Backend: 'anthropic' (direct), 'bedrock' (AWS), 'openrouter', "+ "'anyllm' (any-llm), or 'litellm-<provider>' (e.g., litellm-hosted_vllm, litellm-vertex)"+ ),+ )+ parser.add_argument(+ "--bedrock-region",+ default="us-west-2",+ help="AWS region for Bedrock backend (default: us-west-2)",+ )+ parser.add_argument(+ "--bedrock-profile",+ help="AWS profile for Bedrock backend (default: use default credentials)",+ )+ parser.add_argument(+ "--openrouter-api-key",+ help="OpenRouter API key (or set OPENROUTER_API_KEY env var)",+ )+ parser.add_argument(+ "--anyllm-provider",+ default="openai",+ help="any-llm provider: openai, anthropic, mistral, groq, ollama, bedrock, etc. (default: openai)",+ )++ # Connection pool (scalability)+ parser.add_argument(+ "--max-connections",+ type=int,+ default=500,+ help="Max connections to upstream APIs (default: 500)",+ )+ parser.add_argument(+ "--max-keepalive", type=int, default=100, help="Max keepalive connections (default: 100)"+ )+ parser.add_argument(+ "--no-http2",+ action="store_true",+ help="Disable HTTP/2 (enabled by default for better throughput)",+ )+ parser.add_argument(+ "--workers",+ type=int,+ default=1,+ help="Number of worker processes (default: 1, use N for multi-core)",+ )+ parser.add_argument(+ "--limit-concurrency",+ type=int,+ default=1000,+ help="Max concurrent connections before 503 (default: 1000)",+ )++ # Optimization+ parser.add_argument("--no-optimize", action="store_true", help="Disable optimization")+ parser.add_argument("--min-tokens", type=int, default=500, help="Min tokens to crush")+ parser.add_argument("--max-items", type=int, default=50, help="Max items after crush")+ parser.add_argument(+ "--tool-profile",+ action="append",+ default=[],+ help="Per-tool compression profile: ToolName:level (e.g., Grep:conservative, Bash:moderate, WebFetch:aggressive). "+ "Can be specified multiple times. Also settable via HEADROOM_TOOL_PROFILES env var.",+ )++ # Caching+ parser.add_argument("--no-cache", action="store_true", help="Disable caching")+ parser.add_argument("--cache-ttl", type=int, default=3600, help="Cache TTL seconds")++ # Rate limiting+ parser.add_argument("--no-rate-limit", action="store_true", help="Disable rate limiting")+ parser.add_argument("--rpm", type=int, default=60, help="Requests per minute")+ parser.add_argument("--tpm", type=int, default=100000, help="Tokens per minute")++ # Cost+ parser.add_argument("--budget", type=float, help="Budget limit in USD")+ parser.add_argument("--budget-period", choices=["hourly", "daily", "monthly"], default="daily")++ # Logging+ parser.add_argument("--log-file", help="Log file path")+ parser.add_argument("--log-messages", action="store_true", help="Log full messages")++ # Smart routing (content-aware compression)+ parser.add_argument(+ "--no-smart-routing",+ action="store_true",+ help="Disable smart routing (use legacy sequential pipeline)",+ )++ # Code-aware compression+ parser.add_argument(+ "--code-aware",+ action="store_true",+ help="Enable AST-based code compression (requires: pip install headroom-ai[code])",+ )+ parser.add_argument(+ "--no-code-aware",+ action="store_true",+ help="Disable code-aware compression",+ )++ args = parser.parse_args()++ # Environment variable defaults (HEADROOM_* prefix)+ # CLI args override env vars, env vars override ProxyConfig defaults+ env_smart_routing = _get_env_bool("HEADROOM_SMART_ROUTING", True)+ env_code_aware = _get_env_bool("HEADROOM_CODE_AWARE_ENABLED", True)+ env_optimize = _get_env_bool("HEADROOM_OPTIMIZE", True)+ env_cache = _get_env_bool("HEADROOM_CACHE_ENABLED", True)+ env_rate_limit = _get_env_bool("HEADROOM_RATE_LIMIT_ENABLED", True)++ # Determine settings: CLI flags override env vars+ # --no-X explicitly disables, --X explicitly enables, neither uses env var+ smart_routing = env_smart_routing if not args.no_smart_routing else False+ code_aware_enabled = (+ env_code_aware+ if not (args.code_aware or args.no_code_aware)+ else (args.code_aware or not args.no_code_aware)+ )+ optimize = env_optimize if not args.no_optimize else False+ cache_enabled = env_cache if not args.no_cache else False+ rate_limit_enabled = env_rate_limit if not args.no_rate_limit else False++ # Set OpenRouter API key from CLI if provided+ if hasattr(args, "openrouter_api_key") and args.openrouter_api_key:+ os.environ["OPENROUTER_API_KEY"] = args.openrouter_api_key++ # Parse per-tool compression profiles from CLI and env var+ tool_profiles = _parse_tool_profiles(args.tool_profile)++ config = ProxyConfig(+ host=_get_env_str("HEADROOM_HOST", args.host),+ port=_get_env_int("HEADROOM_PORT", args.port),+ openai_api_url=_get_env_str("OPENAI_TARGET_API_URL", args.openai_api_url),+ anthropic_api_url=_get_env_str("ANTHROPIC_TARGET_API_URL", args.anthropic_api_url),+ # Backend settings+ backend=_get_env_str("HEADROOM_BACKEND", args.backend), # type: ignore[arg-type]+ bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", args.bedrock_region),+ bedrock_profile=args.bedrock_profile or os.environ.get("AWS_PROFILE"),+ anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", args.anyllm_provider),+ optimize=optimize,+ min_tokens_to_crush=_get_env_int("HEADROOM_MIN_TOKENS", args.min_tokens),+ max_items_after_crush=_get_env_int("HEADROOM_MAX_ITEMS", args.max_items),+ cache_enabled=cache_enabled,+ cache_ttl_seconds=_get_env_int("HEADROOM_CACHE_TTL", args.cache_ttl),+ rate_limit_enabled=rate_limit_enabled,+ rate_limit_requests_per_minute=_get_env_int("HEADROOM_RPM", args.rpm),+ rate_limit_tokens_per_minute=_get_env_int("HEADROOM_TPM", args.tpm),+ budget_limit_usd=args.budget,+ budget_period=args.budget_period,+ log_file=_get_env_str("HEADROOM_LOG_FILE", args.log_file)+ if args.log_file+ else os.environ.get("HEADROOM_LOG_FILE"),+ log_full_messages=args.log_messages or _get_env_bool("HEADROOM_LOG_MESSAGES", False),+ smart_routing=smart_routing,+ code_aware_enabled=code_aware_enabled,+ # Connection pool settings+ max_connections=_get_env_int("HEADROOM_MAX_CONNECTIONS", args.max_connections),+ max_keepalive_connections=_get_env_int("HEADROOM_MAX_KEEPALIVE", args.max_keepalive),+ http2=not args.no_http2 and _get_env_bool("HEADROOM_HTTP2", True),+ tool_profiles=tool_profiles if tool_profiles else None,+ mode=normalize_proxy_mode(_get_env_str("HEADROOM_MODE", PROXY_MODE_TOKEN)),+ )++ # Get worker and concurrency settings+ workers = _get_env_int("HEADROOM_WORKERS", args.workers)+ limit_concurrency = _get_env_int("HEADROOM_LIMIT_CONCURRENCY", args.limit_concurrency)++ run_server(config, workers=workers, limit_concurrency=limit_concurrency)diff --git a/headroom/release_version.py b/headroom/release_version.pyindex 951a8bfc0..cf99835c1 100644--- a/headroom/release_version.py+++ b/headroom/release_version.py@@ -1,310 +1,310 @@-"""Release version helpers for the GitHub Actions release workflow."""--from __future__ import annotations--import os-import re-import subprocess-from collections.abc import Sequence-from dataclasses import dataclass, replace-from pathlib import Path--SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")-RELEASE_TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)(?:\.(\d+))?$")-CONVENTIONAL_COMMIT_RE = re.compile(- r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"-)-BREAKING_CHANGE_RE = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)-FIELD_SEP = "\x1f"-RECORD_SEP = "\x1e"-GIT_LOG_FORMAT = "%s%x1f%b%x1e"-BUMP_PRIORITY = {"patch": 0, "minor": 1, "major": 2}---@dataclass(frozen=True, order=True)-class SemVer:- """Semantic version tuple with simple bump helpers."""-- major: int- minor: int- patch: int-- @classmethod- def parse(cls, value: str) -> SemVer:- match = SEMVER_RE.match(value)- if not match:- raise ValueError(f"Invalid semantic version: {value}")- return cls(*(int(part) for part in match.groups()))-- def bump(self, level: str) -> SemVer:- if level == "major":- return SemVer(self.major + 1, 0, 0)- if level == "minor":- return SemVer(self.major, self.minor + 1, 0)- if level == "patch":- return SemVer(self.major, self.minor, self.patch + 1)- raise ValueError(f"Unsupported bump level: {level}")-- def __str__(self) -> str:- return f"{self.major}.{self.minor}.{self.patch}"---@dataclass(frozen=True)-class ReleaseVersionInfo:- """Workflow outputs for release version calculation."""-- version: str- npm_version: str- canonical: str- height: str- bump: str- previous_tag: str-- def as_outputs(self) -> dict[str, str]:- return {- "version": self.version,- "npm_version": self.npm_version,- "canonical": self.canonical,- "height": self.height,- "bump": self.bump,- "previous_tag": self.previous_tag,- }---@dataclass(frozen=True, order=True)-class ReleaseTag:- """Parsed release tag metadata used for sorting and normalization."""-- version: SemVer- legacy_height: int = -1- raw: str = ""---@dataclass(frozen=True)-class CommitInfo:- """Commit subject/body pair used for bump detection."""-- subject: str- body: str = ""---def parse_release_tag(tag: str) -> ReleaseTag:- """Parse a release tag, preserving legacy fourth-component ordering."""-- match = RELEASE_TAG_RE.match(tag)- if not match:- raise ValueError(f"Invalid release tag: {tag}")- major, minor, patch, extra = match.groups()- return ReleaseTag(- version=SemVer(int(major), int(minor), int(patch)),- legacy_height=int(extra) if extra is not None else -1,- raw=tag,- )---def normalize_release_tag(tag: str) -> SemVer:- """Collapse historic 4-part release tags into their base semantic version."""-- return parse_release_tag(tag).version---def find_latest_release_tag(tags: Sequence[str]) -> str | None:- """Return the latest release tag after normalizing legacy 4-part tags."""-- candidates: list[ReleaseTag] = []- for tag in tags:- if RELEASE_TAG_RE.match(tag):- candidates.append(parse_release_tag(tag))- if not candidates:- return None- candidates.sort(reverse=True)- return candidates[0].raw---def _merge_summary(subject: str, body: str) -> str:- """Return the first meaningful body line for merge commits."""-- if not subject.startswith("Merge "):- return ""- for line in body.splitlines():- stripped = line.strip()- if stripped:- return stripped- return ""---def classify_commit_bump(commit: CommitInfo) -> str:- """Classify one commit using conventional commit semantics."""-- merge_summary = _merge_summary(commit.subject, commit.body)- candidates = [commit.subject]- if merge_summary:- candidates.insert(0, merge_summary)-- has_breaking_change = bool(BREAKING_CHANGE_RE.search(commit.body))- for candidate in candidates:- match = CONVENTIONAL_COMMIT_RE.match(candidate)- if not match:- continue- if has_breaking_change or bool(match.group(3)):- return "major"- if match.group(1) == "feat":- return "minor"- return "patch"-- if has_breaking_change:- return "major"- return "patch"---def determine_bump_level(commits: Sequence[CommitInfo]) -> str:- """Return the highest required bump across a commit range."""-- level = "patch"- for commit in commits:- candidate = classify_commit_bump(commit)- if BUMP_PRIORITY[candidate] > BUMP_PRIORITY[level]:- level = candidate- return level---def compute_release_version(- canonical_version: str,- level: str,- tags: Sequence[str],- manual_version: str = "",-) -> ReleaseVersionInfo:- """Compute the next release version from the canonical version and existing tags."""-- if manual_version:- manual = str(SemVer.parse(manual_version))- return ReleaseVersionInfo(- version=manual,- npm_version=manual,- canonical=canonical_version,- height="0",- bump="manual",- previous_tag="",- )-- canonical = SemVer.parse(canonical_version)- previous_tag = find_latest_release_tag(tags)- current = canonical- if previous_tag is not None:- current = max(current, normalize_release_tag(previous_tag))-- next_version = str(current.bump(level))- return ReleaseVersionInfo(- version=next_version,- npm_version=next_version,- canonical=canonical_version,- height="0",- bump=level,- previous_tag=previous_tag or "",- )---def get_canonical_version(root: Path) -> str:- """Read the canonical project version from pyproject.toml."""-- try:- import tomllib- except ModuleNotFoundError: # pragma: no cover - Python 3.10 compatibility- import tomli as tomllib-- with open(root / "pyproject.toml", "rb") as file:- project = tomllib.load(file)["project"]- return str(project["version"])---def list_release_tags(root: Path) -> list[str]:- """List release tags from the local Git checkout."""-- result = subprocess.run(- ["git", "tag", "-l", "v*"],- cwd=root,- check=True,- capture_output=True,- text=True,- )- return [tag.strip() for tag in result.stdout.splitlines() if tag.strip()]---def list_release_commits(root: Path, previous_tag: str) -> list[CommitInfo]:- """List commit subject/body pairs since the previous release tag."""-- cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]- if previous_tag:- cmd.append(f"{previous_tag}..HEAD")- else:- cmd.append("HEAD")-- result = subprocess.run(- cmd,- cwd=root,- check=True,- capture_output=True,- text=True,- )-- commits: list[CommitInfo] = []- for raw_entry in result.stdout.split(RECORD_SEP):- if not raw_entry or FIELD_SEP not in raw_entry:- continue- subject, body = raw_entry.split(FIELD_SEP, 1)- commits.append(CommitInfo(subject=subject.strip(), body=body.strip()))- return commits---def commit_height_since(root: Path, previous_tag: str) -> str:- """Count commits since the previous release tag for changelog/debug outputs."""-- if not previous_tag:- return "0"-- result = subprocess.run(- ["git", "rev-list", f"{previous_tag}..HEAD", "--count"],- cwd=root,- check=True,- capture_output=True,- text=True,- )- return result.stdout.strip() or "0"---def write_github_outputs(info: ReleaseVersionInfo, output_path: str) -> None:- """Append workflow outputs to the GitHub Actions output file."""-- with open(output_path, "a", encoding="utf-8") as output_file:- for key, value in info.as_outputs().items():- output_file.write(f"{key}={value}\n")---def main() -> None:- root = Path.cwd()- manual_version = os.environ.get("MANUAL_VER", "").strip()- tags = list_release_tags(root)- previous_tag = find_latest_release_tag(tags) or ""- level = os.environ.get("LEVEL", "").strip()- if not level:- level = determine_bump_level(list_release_commits(root, previous_tag))-- info = compute_release_version(- canonical_version=get_canonical_version(root),- level=level,- tags=tags,- manual_version=manual_version,- )- info = replace(info, height=commit_height_since(root, info.previous_tag))-- output_path = os.environ.get("GITHUB_OUTPUT", "").strip()- if output_path:- write_github_outputs(info, output_path)- return-- for key, value in info.as_outputs().items():- print(f"{key}={value}")---if __name__ == "__main__":- main()+"""Release version helpers for the GitHub Actions release workflow."""++from __future__ import annotations++import os+import re+import subprocess+from collections.abc import Sequence+from dataclasses import dataclass, replace+from pathlib import Path++SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")+RELEASE_TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)(?:\.(\d+))?$")+CONVENTIONAL_COMMIT_RE = re.compile(+ r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"+)+BREAKING_CHANGE_RE = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)+FIELD_SEP = "\x1f"+RECORD_SEP = "\x1e"+GIT_LOG_FORMAT = "%s%x1f%b%x1e"+BUMP_PRIORITY = {"patch": 0, "minor": 1, "major": 2}+++@dataclass(frozen=True, order=True)+class SemVer:+ """Semantic version tuple with simple bump helpers."""++ major: int+ minor: int+ patch: int++ @classmethod+ def parse(cls, value: str) -> SemVer:+ match = SEMVER_RE.match(value)+ if not match:+ raise ValueError(f"Invalid semantic version: {value}")+ return cls(*(int(part) for part in match.groups()))++ def bump(self, level: str) -> SemVer:+ if level == "major":+ return SemVer(self.major + 1, 0, 0)+ if level == "minor":+ return SemVer(self.major, self.minor + 1, 0)+ if level == "patch":+ return SemVer(self.major, self.minor, self.patch + 1)+ raise ValueError(f"Unsupported bump level: {level}")++ def __str__(self) -> str:+ return f"{self.major}.{self.minor}.{self.patch}"+++@dataclass(frozen=True)+class ReleaseVersionInfo:+ """Workflow outputs for release version calculation."""++ version: str+ npm_version: str+ canonical: str+ height: str+ bump: str+ previous_tag: str++ def as_outputs(self) -> dict[str, str]:+ return {+ "version": self.version,+ "npm_version": self.npm_version,+ "canonical": self.canonical,+ "height": self.height,+ "bump": self.bump,+ "previous_tag": self.previous_tag,+ }+++@dataclass(frozen=True, order=True)+class ReleaseTag:+ """Parsed release tag metadata used for sorting and normalization."""++ version: SemVer+ legacy_height: int = -1+ raw: str = ""+++@dataclass(frozen=True)+class CommitInfo:+ """Commit subject/body pair used for bump detection."""++ subject: str+ body: str = ""+++def parse_release_tag(tag: str) -> ReleaseTag:+ """Parse a release tag, preserving legacy fourth-component ordering."""++ match = RELEASE_TAG_RE.match(tag)+ if not match:+ raise ValueError(f"Invalid release tag: {tag}")+ major, minor, patch, extra = match.groups()+ return ReleaseTag(+ version=SemVer(int(major), int(minor), int(patch)),+ legacy_height=int(extra) if extra is not None else -1,+ raw=tag,+ )+++def normalize_release_tag(tag: str) -> SemVer:+ """Collapse historic 4-part release tags into their base semantic version."""++ return parse_release_tag(tag).version+++def find_latest_release_tag(tags: Sequence[str]) -> str | None:+ """Return the latest release tag after normalizing legacy 4-part tags."""++ candidates: list[ReleaseTag] = []+ for tag in tags:+ if RELEASE_TAG_RE.match(tag):+ candidates.append(parse_release_tag(tag))+ if not candidates:+ return None+ candidates.sort(reverse=True)+ return candidates[0].raw+++def _merge_summary(subject: str, body: str) -> str:+ """Return the first meaningful body line for merge commits."""++ if not subject.startswith("Merge "):+ return ""+ for line in body.splitlines():+ stripped = line.strip()+ if stripped:+ return stripped+ return ""+++def classify_commit_bump(commit: CommitInfo) -> str:+ """Classify one commit using conventional commit semantics."""++ merge_summary = _merge_summary(commit.subject, commit.body)+ candidates = [commit.subject]+ if merge_summary:+ candidates.insert(0, merge_summary)++ has_breaking_change = bool(BREAKING_CHANGE_RE.search(commit.body))+ for candidate in candidates:+ match = CONVENTIONAL_COMMIT_RE.match(candidate)+ if not match:+ continue+ if has_breaking_change or bool(match.group(3)):+ return "major"+ if match.group(1) == "feat":+ return "minor"+ return "patch"++ if has_breaking_change:+ return "major"+ return "patch"+++def determine_bump_level(commits: Sequence[CommitInfo]) -> str:+ """Return the highest required bump across a commit range."""++ level = "patch"+ for commit in commits:+ candidate = classify_commit_bump(commit)+ if BUMP_PRIORITY[candidate] > BUMP_PRIORITY[level]:+ level = candidate+ return level+++def compute_release_version(+ canonical_version: str,+ level: str,+ tags: Sequence[str],+ manual_version: str = "",+) -> ReleaseVersionInfo:+ """Compute the next release version from the canonical version and existing tags."""++ if manual_version:+ manual = str(SemVer.parse(manual_version))+ return ReleaseVersionInfo(+ version=manual,+ npm_version=manual,+ canonical=canonical_version,+ height="0",+ bump="manual",+ previous_tag="",+ )++ canonical = SemVer.parse(canonical_version)+ previous_tag = find_latest_release_tag(tags)+ current = canonical+ if previous_tag is not None:+ current = max(current, normalize_release_tag(previous_tag))++ next_version = str(current.bump(level))+ return ReleaseVersionInfo(+ version=next_version,+ npm_version=next_version,+ canonical=canonical_version,+ height="0",+ bump=level,+ previous_tag=previous_tag or "",+ )+++def get_canonical_version(root: Path) -> str:+ """Read the canonical project version from pyproject.toml."""++ try:+ import tomllib+ except ModuleNotFoundError: # pragma: no cover - Python 3.10 compatibility+ import tomli as tomllib++ with open(root / "pyproject.toml", "rb") as file:+ project = tomllib.load(file)["project"]+ return str(project["version"])+++def list_release_tags(root: Path) -> list[str]:+ """List release tags from the local Git checkout."""++ result = subprocess.run(+ ["git", "tag", "-l", "v*"],+ cwd=root,+ check=True,+ capture_output=True,+ text=True,+ )+ return [tag.strip() for tag in result.stdout.splitlines() if tag.strip()]+++def list_release_commits(root: Path, previous_tag: str) -> list[CommitInfo]:+ """List commit subject/body pairs since the previous release tag."""++ cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]+ if previous_tag:+ cmd.append(f"{previous_tag}..HEAD")+ else:+ cmd.append("HEAD")++ result = subprocess.run(+ cmd,+ cwd=root,+ check=True,+ capture_output=True,+ text=True,+ )++ commits: list[CommitInfo] = []+ for raw_entry in result.stdout.split(RECORD_SEP):+ if not raw_entry or FIELD_SEP not in raw_entry:+ continue+ subject, body = raw_entry.split(FIELD_SEP, 1)+ commits.append(CommitInfo(subject=subject.strip(), body=body.strip()))+ return commits+++def commit_height_since(root: Path, previous_tag: str) -> str:+ """Count commits since the previous release tag for changelog/debug outputs."""++ if not previous_tag:+ return "0"++ result = subprocess.run(+ ["git", "rev-list", f"{previous_tag}..HEAD", "--count"],+ cwd=root,+ check=True,+ capture_output=True,+ text=True,+ )+ return result.stdout.strip() or "0"+++def write_github_outputs(info: ReleaseVersionInfo, output_path: str) -> None:+ """Append workflow outputs to the GitHub Actions output file."""++ with open(output_path, "a", encoding="utf-8") as output_file:+ for key, value in info.as_outputs().items():+ output_file.write(f"{key}={value}\n")+++def main() -> None:+ root = Path.cwd()+ manual_version = os.environ.get("MANUAL_VER", "").strip()+ tags = list_release_tags(root)+ previous_tag = find_latest_release_tag(tags) or ""+ level = os.environ.get("LEVEL", "").strip()+ if not level:+ level = determine_bump_level(list_release_commits(root, previous_tag))++ info = compute_release_version(+ canonical_version=get_canonical_version(root),+ level=level,+ tags=tags,+ manual_version=manual_version,+ )+ info = replace(info, height=commit_height_since(root, info.previous_tag))++ output_path = os.environ.get("GITHUB_OUTPUT", "").strip()+ if output_path:+ write_github_outputs(info, output_path)+ return++ for key, value in info.as_outputs().items():+ print(f"{key}={value}")+++if __name__ == "__main__":+ main()diff --git a/headroom/subscription/__init__.py b/headroom/subscription/__init__.pyindex e4760c942..8ab04220b 100644--- a/headroom/subscription/__init__.py+++ b/headroom/subscription/__init__.py@@ -1,72 +1,72 @@-"""Subscription window tracking for Anthropic Claude Code accounts and Codex rate limits."""--from headroom.subscription.base import (- QuotaTracker,- QuotaTrackerRegistry,- get_quota_registry,- reset_quota_registry,-)-from headroom.subscription.client import SubscriptionClient, read_cached_oauth_token-from headroom.subscription.codex_rate_limits import (- CodexCreditsSnapshot,- CodexRateLimitSnapshot,- CodexRateLimitState,- CodexRateLimitWindow,- get_codex_rate_limit_state,- parse_codex_rate_limits,-)-from headroom.subscription.copilot_quota import (- CopilotQuotaCategory,- CopilotQuotaSnapshot,- CopilotQuotaState,- discover_github_token,- get_copilot_quota_tracker,- parse_copilot_quota,-)-from headroom.subscription.models import (- ExtraUsage,- HeadroomContribution,- RateLimitWindow,- SubscriptionSnapshot,- SubscriptionState,- WindowDiscrepancy,- WindowTokens,-)-from headroom.subscription.tracker import (- SubscriptionTracker,- configure_subscription_tracker,- get_subscription_tracker,- shutdown_subscription_tracker,-)--__all__ = [- "CodexCreditsSnapshot",- "CodexRateLimitSnapshot",- "CodexRateLimitState",- "CodexRateLimitWindow",- "CopilotQuotaCategory",- "CopilotQuotaSnapshot",- "CopilotQuotaState",- "ExtraUsage",- "HeadroomContribution",- "QuotaTracker",- "QuotaTrackerRegistry",- "RateLimitWindow",- "SubscriptionClient",- "SubscriptionSnapshot",- "SubscriptionState",- "SubscriptionTracker",- "WindowDiscrepancy",- "WindowTokens",- "configure_subscription_tracker",- "discover_github_token",- "get_codex_rate_limit_state",- "get_copilot_quota_tracker",- "get_quota_registry",- "get_subscription_tracker",- "parse_codex_rate_limits",- "parse_copilot_quota",- "read_cached_oauth_token",- "reset_quota_registry",- "shutdown_subscription_tracker",-]+"""Subscription window tracking for Anthropic Claude Code accounts and Codex rate limits."""++from headroom.subscription.base import (+ QuotaTracker,+ QuotaTrackerRegistry,+ get_quota_registry,+ reset_quota_registry,+)+from headroom.subscription.client import SubscriptionClient, read_cached_oauth_token+from headroom.subscription.codex_rate_limits import (+ CodexCreditsSnapshot,+ CodexRateLimitSnapshot,+ CodexRateLimitState,+ CodexRateLimitWindow,+ get_codex_rate_limit_state,+ parse_codex_rate_limits,+)+from headroom.subscription.copilot_quota import (+ CopilotQuotaCategory,+ CopilotQuotaSnapshot,+ CopilotQuotaState,+ discover_github_token,+ get_copilot_quota_tracker,+ parse_copilot_quota,+)+from headroom.subscription.models import (+ ExtraUsage,+ HeadroomContribution,+ RateLimitWindow,+ SubscriptionSnapshot,+ SubscriptionState,+ WindowDiscrepancy,+ WindowTokens,+)+from headroom.subscription.tracker import (+ SubscriptionTracker,+ configure_subscription_tracker,+ get_subscription_tracker,+ shutdown_subscription_tracker,+)++__all__ = [+ "CodexCreditsSnapshot",+ "CodexRateLimitSnapshot",+ "CodexRateLimitState",+ "CodexRateLimitWindow",+ "CopilotQuotaCategory",+ "CopilotQuotaSnapshot",+ "CopilotQuotaState",+ "ExtraUsage",+ "HeadroomContribution",+ "QuotaTracker",+ "QuotaTrackerRegistry",+ "RateLimitWindow",+ "SubscriptionClient",+ "SubscriptionSnapshot",+ "SubscriptionState",+ "SubscriptionTracker",+ "WindowDiscrepancy",+ "WindowTokens",+ "configure_subscription_tracker",+ "discover_github_token",+ "get_codex_rate_limit_state",+ "get_copilot_quota_tracker",+ "get_quota_registry",+ "get_subscription_tracker",+ "parse_codex_rate_limits",+ "parse_copilot_quota",+ "read_cached_oauth_token",+ "reset_quota_registry",+ "shutdown_subscription_tracker",+]diff --git a/headroom/subscription/base.py b/headroom/subscription/base.pyindex c6664f5a8..e5847a86d 100644--- a/headroom/subscription/base.py+++ b/headroom/subscription/base.py@@ -1,230 +1,230 @@-"""Base abstractions for pluggable AI-tool quota / rate-limit trackers.--Every provider tracker (Anthropic, Codex, Copilot, …) inherits from-:class:`QuotaTracker` and is registered with the process-global-:class:`QuotaTrackerRegistry`. ``server.py`` only interacts with the-registry — adding a new provider requires *zero* changes to the server.--Quick-start for a new provider::-- from headroom.subscription.base import QuotaTracker, get_quota_registry-- class GeminiQuotaTracker(QuotaTracker):- key = "gemini_quota"- label = "Google Gemini"-- def is_available(self) -> bool:- return bool(os.environ.get("GOOGLE_API_KEY"))-- async def start(self) -> None: ... # launch background poll- async def stop(self) -> None: ... # cancel poll task-- def get_stats(self) -> dict | None:- return ... # serialisable dict or None if no data yet-- get_quota_registry().register(GeminiQuotaTracker())-"""--from __future__ import annotations--import abc-import logging-from threading import Lock-from typing import Any--logger = logging.getLogger(__name__)---class QuotaTracker(abc.ABC):- """Abstract base for a single AI-tool quota / rate-limit tracker.-- Subclasses must define :attr:`key`, :attr:`label`, and- :meth:`get_stats`. All other methods have sensible defaults.- """-- # ------------------------------------------------------------------ #- # Class-level identity — subclasses should override as class attributes- # ------------------------------------------------------------------ #-- @property- @abc.abstractmethod- def key(self) -> str:- """Stats key used in ``/stats`` and the dashboard.-- Must be unique across all registered trackers.- Examples: ``"subscription_window"``, ``"codex_rate_limits"``.- """-- @property- @abc.abstractmethod- def label(self) -> str:- """Human-readable name for log messages.-- Example: ``"Anthropic Claude Code"``.- """-- # ------------------------------------------------------------------ #- # Availability gate- # ------------------------------------------------------------------ #-- def is_available(self) -> bool:- """Return ``True`` if this tracker should be activated.-- Override to gate on environment variables, config flags, etc.- The registry calls this before :meth:`start` and skips trackers- that return ``False``. Default: always available.- """- return True-- # ------------------------------------------------------------------ #- # Lifecycle — default no-ops (suitable for passive/header-based trackers)- # ------------------------------------------------------------------ #-- async def start(self) -> None: # noqa: B027- """Start background polling. No-op for passive trackers."""-- async def stop(self) -> None: # noqa: B027- """Stop background polling. No-op for passive trackers."""-- # ------------------------------------------------------------------ #- # Stats- # ------------------------------------------------------------------ #-- @abc.abstractmethod- def get_stats(self) -> dict[str, Any] | None:- """Return the current snapshot as a serialisable dict, or ``None``.-- ``None`` means "no data yet" and causes the key to be omitted from- ``/stats`` rather than appearing as ``null``.- """---# --------------------------------------------------------------------------- #-# Registry-# --------------------------------------------------------------------------- #---class QuotaTrackerRegistry:- """Process-global registry of all :class:`QuotaTracker` instances.-- Typical usage::-- registry = get_quota_registry()- registry.register(SubscriptionTracker(...))- registry.register(get_codex_rate_limit_state())- registry.register(get_copilot_quota_tracker())-- # server startup- await registry.start_all()-- # /stats assembly- stats.update(registry.get_all_stats())-- # server shutdown- await registry.stop_all()- """-- def __init__(self) -> None:- self._trackers: list[QuotaTracker] = []- self._lock = Lock()-- # ------------------------------------------------------------------ #- # Registration- # ------------------------------------------------------------------ #-- def register(self, tracker: QuotaTracker) -> None:- """Register a tracker. Duplicate keys are rejected."""- with self._lock:- existing_keys = {t.key for t in self._trackers}- if tracker.key in existing_keys:- raise ValueError(- f"A tracker with key '{tracker.key}' is already registered. "- "Each tracker must have a unique key."- )- self._trackers.append(tracker)-- def get(self, key: str) -> QuotaTracker | None:- """Return the registered tracker for *key*, or ``None``."""- with self._lock:- for t in self._trackers:- if t.key == key:- return t- return None-- @property- def trackers(self) -> list[QuotaTracker]:- """Read-only snapshot of the registered tracker list."""- with self._lock:- return list(self._trackers)-- # ------------------------------------------------------------------ #- # Lifecycle- # ------------------------------------------------------------------ #-- async def start_all(self) -> None:- """Start every available tracker and log its status."""- for tracker in self.trackers:- if tracker.is_available():- await tracker.start()- logger.info("%s quota tracking: ENABLED", tracker.label)- else:- logger.info("%s quota tracking: DISABLED (not available)", tracker.label)-- async def stop_all(self) -> None:- """Stop all registered trackers (regardless of availability)."""- for tracker in self.trackers:- try:- await tracker.stop()- except Exception as exc: # noqa: BLE001- logger.warning("Error stopping %s tracker: %s", tracker.label, exc)-- # ------------------------------------------------------------------ #- # Stats- # ------------------------------------------------------------------ #-- def get_all_stats(self) -> dict[str, dict[str, Any] | None]:- """Return ``{key: stats_dict}`` for every available tracker.-- Trackers that are unavailable or return ``None`` are excluded.- """- result: dict[str, dict[str, Any] | None] = {}- for tracker in self.trackers:- if not tracker.is_available():- continue- stats = tracker.get_stats()- if stats is not None:- result[tracker.key] = stats- return result-- def get_stats(self, key: str) -> dict[str, Any] | None:- """Return stats for a single tracker by key, or ``None``."""- tracker = self.get(key)- return tracker.get_stats() if tracker is not None else None---# --------------------------------------------------------------------------- #-# Process-global singleton-# --------------------------------------------------------------------------- #--_registry: QuotaTrackerRegistry | None = None-_registry_lock = Lock()---def get_quota_registry() -> QuotaTrackerRegistry:- """Return the process-global :class:`QuotaTrackerRegistry` singleton."""- global _registry- if _registry is None:- with _registry_lock:- if _registry is None:- _registry = QuotaTrackerRegistry()- return _registry---def reset_quota_registry() -> None:- """Replace the global registry with a fresh empty instance.-- Intended for use in tests only.- """- global _registry- with _registry_lock:- _registry = QuotaTrackerRegistry()+"""Base abstractions for pluggable AI-tool quota / rate-limit trackers.++Every provider tracker (Anthropic, Codex, Copilot, …) inherits from+:class:`QuotaTracker` and is registered with the process-global+:class:`QuotaTrackerRegistry`. ``server.py`` only interacts with the+registry — adding a new provider requires *zero* changes to the server.++Quick-start for a new provider::++ from headroom.subscription.base import QuotaTracker, get_quota_registry++ class GeminiQuotaTracker(QuotaTracker):+ key = "gemini_quota"+ label = "Google Gemini"++ def is_available(self) -> bool:+ return bool(os.environ.get("GOOGLE_API_KEY"))++ async def start(self) -> None: ... # launch background poll+ async def stop(self) -> None: ... # cancel poll task++ def get_stats(self) -> dict | None:+ return ... # serialisable dict or None if no data yet++ get_quota_registry().register(GeminiQuotaTracker())+"""++from __future__ import annotations++import abc+import logging+from threading import Lock+from typing import Any++logger = logging.getLogger(__name__)+++class QuotaTracker(abc.ABC):+ """Abstract base for a single AI-tool quota / rate-limit tracker.++ Subclasses must define :attr:`key`, :attr:`label`, and+ :meth:`get_stats`. All other methods have sensible defaults.+ """++ # ------------------------------------------------------------------ #+ # Class-level identity — subclasses should override as class attributes+ # ------------------------------------------------------------------ #++ @property+ @abc.abstractmethod+ def key(self) -> str:+ """Stats key used in ``/stats`` and the dashboard.++ Must be unique across all registered trackers.+ Examples: ``"subscription_window"``, ``"codex_rate_limits"``.+ """++ @property+ @abc.abstractmethod+ def label(self) -> str:+ """Human-readable name for log messages.++ Example: ``"Anthropic Claude Code"``.+ """++ # ------------------------------------------------------------------ #+ # Availability gate+ # ------------------------------------------------------------------ #++ def is_available(self) -> bool:+ """Return ``True`` if this tracker should be activated.++ Override to gate on environment variables, config flags, etc.+ The registry calls this before :meth:`start` and skips trackers+ that return ``False``. Default: always available.+ """+ return True++ # ------------------------------------------------------------------ #+ # Lifecycle — default no-ops (suitable for passive/header-based trackers)+ # ------------------------------------------------------------------ #++ async def start(self) -> None: # noqa: B027+ """Start background polling. No-op for passive trackers."""++ async def stop(self) -> None: # noqa: B027+ """Stop background polling. No-op for passive trackers."""++ # ------------------------------------------------------------------ #+ # Stats+ # ------------------------------------------------------------------ #++ @abc.abstractmethod+ def get_stats(self) -> dict[str, Any] | None:+ """Return the current snapshot as a serialisable dict, or ``None``.++ ``None`` means "no data yet" and causes the key to be omitted from+ ``/stats`` rather than appearing as ``null``.+ """+++# --------------------------------------------------------------------------- #+# Registry+# --------------------------------------------------------------------------- #+++class QuotaTrackerRegistry:+ """Process-global registry of all :class:`QuotaTracker` instances.++ Typical usage::++ registry = get_quota_registry()+ registry.register(SubscriptionTracker(...))+ registry.register(get_codex_rate_limit_state())+ registry.register(get_copilot_quota_tracker())++ # server startup+ await registry.start_all()++ # /stats assembly+ stats.update(registry.get_all_stats())++ # server shutdown+ await registry.stop_all()+ """++ def __init__(self) -> None:+ self._trackers: list[QuotaTracker] = []+ self._lock = Lock()++ # ------------------------------------------------------------------ #+ # Registration+ # ------------------------------------------------------------------ #++ def register(self, tracker: QuotaTracker) -> None:+ """Register a tracker. Duplicate keys are rejected."""+ with self._lock:+ existing_keys = {t.key for t in self._trackers}+ if tracker.key in existing_keys:+ raise ValueError(+ f"A tracker with key '{tracker.key}' is already registered. "+ "Each tracker must have a unique key."+ )+ self._trackers.append(tracker)++ def get(self, key: str) -> QuotaTracker | None:+ """Return the registered tracker for *key*, or ``None``."""+ with self._lock:+ for t in self._trackers:+ if t.key == key:+ return t+ return None++ @property+ def trackers(self) -> list[QuotaTracker]:+ """Read-only snapshot of the registered tracker list."""+ with self._lock:+ return list(self._trackers)++ # ------------------------------------------------------------------ #+ # Lifecycle+ # ------------------------------------------------------------------ #++ async def start_all(self) -> None:+ """Start every available tracker and log its status."""+ for tracker in self.trackers:+ if tracker.is_available():+ await tracker.start()+ logger.info("%s quota tracking: ENABLED", tracker.label)+ else:+ logger.info("%s quota tracking: DISABLED (not available)", tracker.label)++ async def stop_all(self) -> None:+ """Stop all registered trackers (regardless of availability)."""+ for tracker in self.trackers:+ try:+ await tracker.stop()+ except Exception as exc: # noqa: BLE001+ logger.warning("Error stopping %s tracker: %s", tracker.label, exc)++ # ------------------------------------------------------------------ #+ # Stats+ # ------------------------------------------------------------------ #++ def get_all_stats(self) -> dict[str, dict[str, Any] | None]:+ """Return ``{key: stats_dict}`` for every available tracker.++ Trackers that are unavailable or return ``None`` are excluded.+ """+ result: dict[str, dict[str, Any] | None] = {}+ for tracker in self.trackers:+ if not tracker.is_available():+ continue+ stats = tracker.get_stats()+ if stats is not None:+ result[tracker.key] = stats+ return result++ def get_stats(self, key: str) -> dict[str, Any] | None:+ """Return stats for a single tracker by key, or ``None``."""+ tracker = self.get(key)+ return tracker.get_stats() if tracker is not None else None+++# --------------------------------------------------------------------------- #+# Process-global singleton+# --------------------------------------------------------------------------- #++_registry: QuotaTrackerRegistry | None = None+_registry_lock = Lock()+++def get_quota_registry() -> QuotaTrackerRegistry:+ """Return the process-global :class:`QuotaTrackerRegistry` singleton."""+ global _registry+ if _registry is None:+ with _registry_lock:+ if _registry is None:+ _registry = QuotaTrackerRegistry()+ return _registry+++def reset_quota_registry() -> None:+ """Replace the global registry with a fresh empty instance.++ Intended for use in tests only.+ """+ global _registry+ with _registry_lock:+ _registry = QuotaTrackerRegistry()diff --git a/headroom/subscription/client.py b/headroom/subscription/client.pyindex 55a7a8cbd..11b6b08fa 100644--- a/headroom/subscription/client.py+++ b/headroom/subscription/client.py@@ -1,131 +1,131 @@-"""Async HTTP client for Anthropic's OAuth usage API.--Endpoint: GET https://api.anthropic.com/api/oauth/usage-Required header: anthropic-beta: oauth-2025-04-20-Auth: Authorization: Bearer <oauth_access_token>--Token resolution order (highest → lowest priority):- 1. Explicit token passed to :meth:`fetch`- 2. ``CLAUDE_CODE_OAUTH_TOKEN`` env-var- 3. ``~/.claude/.credentials.json`` → ``claudeAiOauth.accessToken``- (respects ``CLAUDE_CONFIG_DIR`` env-var override)-"""--from __future__ import annotations--import json-import logging-import os-from pathlib import Path-from typing import Any--import httpx--from headroom.subscription.models import SubscriptionSnapshot--logger = logging.getLogger(__name__)--_USAGE_URL = "https://api.anthropic.com/api/oauth/usage"-_BETA_HEADER = "oauth-2025-04-20"-_TOKEN_EXPIRY_BUFFER_S = 60---def _credentials_path() -> Path:- base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")- return Path(base) / ".credentials.json"---def _load_credentials_file() -> dict[str, Any] | None:- """Load raw credentials dict from the Claude Code credentials file."""- path = _credentials_path()- try:- with path.open() as fh:- return json.load(fh) # type: ignore[no-any-return]- except FileNotFoundError:- return None- except Exception as exc:- logger.debug("Cannot read credentials file %s: %s", path, exc)- return None---def read_cached_oauth_token() -> str | None:- """Resolve a stored OAuth token for background polling (no request needed).-- Returns the raw access token string if found and not expired, else None.- """- # 1. Env var- env_token = os.environ.get("CLAUDE_CODE_OAUTH_TOKEN", "").strip()- if env_token:- return env_token-- # 2. Credentials file- creds = _load_credentials_file()- if not creds:- return None- oauth = creds.get("claudeAiOauth") or {}- token = oauth.get("accessToken") or ""- if not token:- return None-- # Check expiry (Anthropic stores timestamp in milliseconds)- expires_at_ms = oauth.get("expiresAt")- if expires_at_ms is not None:- import time-- now_ms = time.time() * 1000- if now_ms >= (expires_at_ms - _TOKEN_EXPIRY_BUFFER_S * 1000):- logger.debug("Cached OAuth token expired; skipping background poll")- return None-- return token---class SubscriptionClient:- """Thin async wrapper around the Anthropic OAuth usage endpoint."""-- def __init__(self, timeout: float = 10.0) -> None:- self._timeout = timeout-- async def fetch(self, token: str | None = None) -> SubscriptionSnapshot | None:- """Fetch current subscription window data.-- :param token: OAuth access token. When *None*, falls back to- :func:`read_cached_oauth_token`.- :returns: :class:`SubscriptionSnapshot` or *None* on auth failure /- unsupported account.- """- resolved = (token or "").strip() or read_cached_oauth_token()- if not resolved:- logger.debug("No OAuth token available for subscription polling")- return None-- headers = {- "Authorization": f"Bearer {resolved}",- "anthropic-beta": _BETA_HEADER,- "Content-Type": "application/json",- }-- try:- async with httpx.AsyncClient(timeout=self._timeout) as client:- resp = await client.get(_USAGE_URL, headers=headers)-- if resp.status_code == 401:- logger.debug("OAuth token rejected (401) by Anthropic usage API")- return None- if resp.status_code == 404:- # API key accounts (non-subscription) return 404- logger.debug("Subscription usage API returned 404; likely API-key account")- return None- if resp.status_code != 200:- logger.warning("Anthropic usage API returned %s", resp.status_code)- return None-- data: dict[str, Any] = resp.json()- return SubscriptionSnapshot.from_api_response(data, token=resolved)-- except httpx.TimeoutException:- logger.debug("Timeout fetching Anthropic subscription window")- return None- except Exception as exc:- logger.warning("Error fetching subscription window: %s", exc)- return None+"""Async HTTP client for Anthropic's OAuth usage API.++Endpoint: GET https://api.anthropic.com/api/oauth/usage+Required header: anthropic-beta: oauth-2025-04-20+Auth: Authorization: Bearer <oauth_access_token>++Token resolution order (highest → lowest priority):+ 1. Explicit token passed to :meth:`fetch`+ 2. ``CLAUDE_CODE_OAUTH_TOKEN`` env-var+ 3. ``~/.claude/.credentials.json`` → ``claudeAiOauth.accessToken``+ (respects ``CLAUDE_CONFIG_DIR`` env-var override)+"""++from __future__ import annotations++import json+import logging+import os+from pathlib import Path+from typing import Any++import httpx++from headroom.subscription.models import SubscriptionSnapshot++logger = logging.getLogger(__name__)++_USAGE_URL = "https://api.anthropic.com/api/oauth/usage"+_BETA_HEADER = "oauth-2025-04-20"+_TOKEN_EXPIRY_BUFFER_S = 60+++def _credentials_path() -> Path:+ base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")+ return Path(base) / ".credentials.json"+++def _load_credentials_file() -> dict[str, Any] | None:+ """Load raw credentials dict from the Claude Code credentials file."""+ path = _credentials_path()+ try:+ with path.open() as fh:+ return json.load(fh) # type: ignore[no-any-return]+ except FileNotFoundError:+ return None+ except Exception as exc:+ logger.debug("Cannot read credentials file %s: %s", path, exc)+ return None+++def read_cached_oauth_token() -> str | None:+ """Resolve a stored OAuth token for background polling (no request needed).++ Returns the raw access token string if found and not expired, else None.+ """+ # 1. Env var+ env_token = os.environ.get("CLAUDE_CODE_OAUTH_TOKEN", "").strip()+ if env_token:+ return env_token++ # 2. Credentials file+ creds = _load_credentials_file()+ if not creds:+ return None+ oauth = creds.get("claudeAiOauth") or {}+ token = oauth.get("accessToken") or ""+ if not token:+ return None++ # Check expiry (Anthropic stores timestamp in milliseconds)+ expires_at_ms = oauth.get("expiresAt")+ if expires_at_ms is not None:+ import time++ now_ms = time.time() * 1000+ if now_ms >= (expires_at_ms - _TOKEN_EXPIRY_BUFFER_S * 1000):+ logger.debug("Cached OAuth token expired; skipping background poll")+ return None++ return token+++class SubscriptionClient:+ """Thin async wrapper around the Anthropic OAuth usage endpoint."""++ def __init__(self, timeout: float = 10.0) -> None:+ self._timeout = timeout++ async def fetch(self, token: str | None = None) -> SubscriptionSnapshot | None:+ """Fetch current subscription window data.++ :param token: OAuth access token. When *None*, falls back to+ :func:`read_cached_oauth_token`.+ :returns: :class:`SubscriptionSnapshot` or *None* on auth failure /+ unsupported account.+ """+ resolved = (token or "").strip() or read_cached_oauth_token()+ if not resolved:+ logger.debug("No OAuth token available for subscription polling")+ return None++ headers = {+ "Authorization": f"Bearer {resolved}",+ "anthropic-beta": _BETA_HEADER,+ "Content-Type": "application/json",+ }++ try:+ async with httpx.AsyncClient(timeout=self._timeout) as client:+ resp = await client.get(_USAGE_URL, headers=headers)++ if resp.status_code == 401:+ logger.debug("OAuth token rejected (401) by Anthropic usage API")+ return None+ if resp.status_code == 404:+ # API key accounts (non-subscription) return 404+ logger.debug("Subscription usage API returned 404; likely API-key account")+ return None+ if resp.status_code != 200:+ logger.warning("Anthropic usage API returned %s", resp.status_code)+ return None++ data: dict[str, Any] = resp.json()+ return SubscriptionSnapshot.from_api_response(data, token=resolved)++ except httpx.TimeoutException:+ logger.debug("Timeout fetching Anthropic subscription window")+ return None+ except Exception as exc:+ logger.warning("Error fetching subscription window: %s", exc)+ return Nonediff --git a/headroom/subscription/codex_rate_limits.py b/headroom/subscription/codex_rate_limits.pyindex 3934ff8b1..f66f24780 100644--- a/headroom/subscription/codex_rate_limits.py+++ b/headroom/subscription/codex_rate_limits.py@@ -1,247 +1,247 @@-"""Passive tracking of OpenAI Codex rate-limit window data from response headers.--Codex (OpenAI) embeds rate-limit data directly in API response headers-(``x-codex-primary-used-percent``, ``x-codex-primary-window-minutes``, etc.)-rather than exposing a dedicated usage endpoint. This module captures those-headers from responses that headroom proxies and makes them available in-``/stats`` and the dashboard.--Header schema (parsed by codex-rs ``rate_limits.rs``):- x-codex-primary-used-percent float 0-100- x-codex-primary-window-minutes int window size- x-codex-primary-reset-at int Unix timestamp (seconds)- x-codex-secondary-used-percent float 0-100 (optional)- x-codex-secondary-window-minutes int (optional)- x-codex-secondary-reset-at int (optional)- x-codex-credits-has-credits bool- x-codex-credits-unlimited bool- x-codex-credits-balance str e.g. "$5.00"- x-codex-promo-message str server announcement- x-codex-limit-name str e.g. "gpt-5.2-codex-sonic"-"""--from __future__ import annotations--import time-from dataclasses import dataclass, field-from threading import Lock--from headroom.subscription.base import QuotaTracker---@dataclass-class CodexRateLimitWindow:- """Usage data for a single rolling rate-limit window."""-- used_percent: float- window_minutes: int | None = None- resets_at: int | None = None # Unix timestamp (seconds)-- @property- def window_label(self) -> str:- if self.window_minutes is None:- return "unknown"- if self.window_minutes < 60:- return f"{self.window_minutes}m"- hours = self.window_minutes // 60- mins = self.window_minutes % 60- return f"{hours}h{mins:02d}m" if mins else f"{hours}h"-- @property- def seconds_until_reset(self) -> int | None:- if self.resets_at is None:- return None- return max(0, self.resets_at - int(time.time()))-- def to_dict(self) -> dict:- return {- "used_percent": self.used_percent,- "window_minutes": self.window_minutes,- "window_label": self.window_label,- "resets_at": self.resets_at,- "seconds_until_reset": self.seconds_until_reset,- }---@dataclass-class CodexCreditsSnapshot:- """OpenAI credits balance for Codex."""-- has_credits: bool- unlimited: bool- balance: str | None = None-- def to_dict(self) -> dict:- return {- "has_credits": self.has_credits,- "unlimited": self.unlimited,- "balance": self.balance,- }---@dataclass-class CodexRateLimitSnapshot:- """Full rate-limit snapshot parsed from a single Codex API response."""-- limit_id: str = "codex"- limit_name: str | None = None- primary: CodexRateLimitWindow | None = None- secondary: CodexRateLimitWindow | None = None- credits: CodexCreditsSnapshot | None = None- promo_message: str | None = None- captured_at: float = field(default_factory=time.time)-- def to_dict(self) -> dict:- return {- "limit_id": self.limit_id,- "limit_name": self.limit_name,- "primary": self.primary.to_dict() if self.primary else None,- "secondary": self.secondary.to_dict() if self.secondary else None,- "credits": self.credits.to_dict() if self.credits else None,- "promo_message": self.promo_message,- "captured_at": self.captured_at,- }---# ----------------------------------------------------------------------------# Header parsing helpers-# ------------------------------------------------------------------------------def _parse_float(headers: dict[str, str], name: str) -> float | None:- raw = headers.get(name)- if raw is None:- return None- try:- v = float(raw)- return v if v == v else None # NaN guard- except (ValueError, TypeError):- return None---def _parse_int(headers: dict[str, str], name: str) -> int | None:- raw = headers.get(name)- if raw is None:- return None- try:- return int(raw)- except (ValueError, TypeError):- return None---def _parse_bool(headers: dict[str, str], name: str) -> bool | None:- raw = headers.get(name)- if raw is None:- return None- if raw.lower() in ("true", "1"):- return True- if raw.lower() in ("false", "0"):- return False- return None---def _parse_window(headers: dict[str, str], prefix: str, which: str) -> CodexRateLimitWindow | None:- used_pct = _parse_float(headers, f"{prefix}-{which}-used-percent")- if used_pct is None:- return None- return CodexRateLimitWindow(- used_percent=used_pct,- window_minutes=_parse_int(headers, f"{prefix}-{which}-window-minutes"),- resets_at=_parse_int(headers, f"{prefix}-{which}-reset-at"),- )---def _parse_credits(headers: dict[str, str]) -> CodexCreditsSnapshot | None:- has_credits = _parse_bool(headers, "x-codex-credits-has-credits")- if has_credits is None:- return None- unlimited = _parse_bool(headers, "x-codex-credits-unlimited") or False- raw_balance = headers.get("x-codex-credits-balance", "").strip()- return CodexCreditsSnapshot(- has_credits=has_credits,- unlimited=unlimited,- balance=raw_balance or None,- )---def parse_codex_rate_limits(headers: dict[str, str]) -> CodexRateLimitSnapshot | None:- """Parse a :class:`CodexRateLimitSnapshot` from a dict of HTTP response headers.-- Returns ``None`` when no Codex rate-limit headers are present (e.g. the- response came from a non-Codex OpenAI endpoint or a cached reply).- """- prefix = "x-codex"- primary = _parse_window(headers, prefix, "primary")- secondary = _parse_window(headers, prefix, "secondary")- credits = _parse_credits(headers)- raw_promo = headers.get("x-codex-promo-message", "").strip()- promo = raw_promo or None- raw_limit_name = headers.get("x-codex-limit-name", "").strip()- limit_name = raw_limit_name or None-- if primary is None and secondary is None and credits is None and promo is None:- return None # Not a Codex response with rate-limit headers-- return CodexRateLimitSnapshot(- limit_id="codex",- limit_name=limit_name,- primary=primary,- secondary=secondary,- credits=credits,- promo_message=promo,- )---# ----------------------------------------------------------------------------# Singleton state store-# ------------------------------------------------------------------------------class CodexRateLimitState(QuotaTracker):- """Thread-safe store for the latest Codex rate-limit snapshot.-- Implements :class:`~headroom.subscription.base.QuotaTracker` so it can- be registered with the :class:`~headroom.subscription.base.QuotaTrackerRegistry`.- This tracker is *passive* — it is updated by the OpenAI proxy handler- each time a response containing ``x-codex-*`` headers passes through- headroom, so :meth:`start` and :meth:`stop` are no-ops.- """-- # QuotaTracker identity- key = "codex_rate_limits"- label = "OpenAI Codex"-- def __init__(self) -> None:- self._lock = Lock()- self._latest: CodexRateLimitSnapshot | None = None-- def update_from_headers(self, headers: dict[str, str]) -> None:- """Update state from a response header dict (no-op if no Codex headers)."""- snapshot = parse_codex_rate_limits(headers)- if snapshot is None:- return- with self._lock:- self._latest = snapshot-- @property- def latest(self) -> CodexRateLimitSnapshot | None:- with self._lock:- return self._latest-- def get_stats(self) -> dict | None:- snap = self.latest- return snap.to_dict() if snap is not None else None---_state: CodexRateLimitState | None = None-_state_lock = Lock()---def get_codex_rate_limit_state() -> CodexRateLimitState:- """Return the process-global :class:`CodexRateLimitState` singleton."""- global _state- if _state is None:- with _state_lock:- if _state is None:- _state = CodexRateLimitState()- return _state+"""Passive tracking of OpenAI Codex rate-limit window data from response headers.++Codex (OpenAI) embeds rate-limit data directly in API response headers+(``x-codex-primary-used-percent``, ``x-codex-primary-window-minutes``, etc.)+rather than exposing a dedicated usage endpoint. This module captures those+headers from responses that headroom proxies and makes them available in+``/stats`` and the dashboard.++Header schema (parsed by codex-rs ``rate_limits.rs``):+ x-codex-primary-used-percent float 0-100+ x-codex-primary-window-minutes int window size+ x-codex-primary-reset-at int Unix timestamp (seconds)+ x-codex-secondary-used-percent float 0-100 (optional)+ x-codex-secondary-window-minutes int (optional)+ x-codex-secondary-reset-at int (optional)+ x-codex-credits-has-credits bool+ x-codex-credits-unlimited bool+ x-codex-credits-balance str e.g. "$5.00"+ x-codex-promo-message str server announcement+ x-codex-limit-name str e.g. "gpt-5.2-codex-sonic"+"""++from __future__ import annotations++import time+from dataclasses import dataclass, field+from threading import Lock++from headroom.subscription.base import QuotaTracker+++@dataclass+class CodexRateLimitWindow:+ """Usage data for a single rolling rate-limit window."""++ used_percent: float+ window_minutes: int | None = None+ resets_at: int | None = None # Unix timestamp (seconds)++ @property+ def window_label(self) -> str:+ if self.window_minutes is None:+ return "unknown"+ if self.window_minutes < 60:+ return f"{self.window_minutes}m"+ hours = self.window_minutes // 60+ mins = self.window_minutes % 60+ return f"{hours}h{mins:02d}m" if mins else f"{hours}h"++ @property+ def seconds_until_reset(self) -> int | None:+ if self.resets_at is None:+ return None+ return max(0, self.resets_at - int(time.time()))++ def to_dict(self) -> dict:+ return {+ "used_percent": self.used_percent,+ "window_minutes": self.window_minutes,+ "window_label": self.window_label,+ "resets_at": self.resets_at,+ "seconds_until_reset": self.seconds_until_reset,+ }+++@dataclass+class CodexCreditsSnapshot:+ """OpenAI credits balance for Codex."""++ has_credits: bool+ unlimited: bool+ balance: str | None = None++ def to_dict(self) -> dict:+ return {+ "has_credits": self.has_credits,+ "unlimited": self.unlimited,+ "balance": self.balance,+ }+++@dataclass+class CodexRateLimitSnapshot:+ """Full rate-limit snapshot parsed from a single Codex API response."""++ limit_id: str = "codex"+ limit_name: str | None = None+ primary: CodexRateLimitWindow | None = None+ secondary: CodexRateLimitWindow | None = None+ credits: CodexCreditsSnapshot | None = None+ promo_message: str | None = None+ captured_at: float = field(default_factory=time.time)++ def to_dict(self) -> dict:+ return {+ "limit_id": self.limit_id,+ "limit_name": self.limit_name,+ "primary": self.primary.to_dict() if self.primary else None,+ "secondary": self.secondary.to_dict() if self.secondary else None,+ "credits": self.credits.to_dict() if self.credits else None,+ "promo_message": self.promo_message,+ "captured_at": self.captured_at,+ }+++# ---------------------------------------------------------------------------+# Header parsing helpers+# ---------------------------------------------------------------------------+++def _parse_float(headers: dict[str, str], name: str) -> float | None:+ raw = headers.get(name)+ if raw is None:+ return None+ try:+ v = float(raw)+ return v if v == v else None # NaN guard+ except (ValueError, TypeError):+ return None+++def _parse_int(headers: dict[str, str], name: str) -> int | None:+ raw = headers.get(name)+ if raw is None:+ return None+ try:+ return int(raw)+ except (ValueError, TypeError):+ return None+++def _parse_bool(headers: dict[str, str], name: str) -> bool | None:+ raw = headers.get(name)+ if raw is None:+ return None+ if raw.lower() in ("true", "1"):+ return True+ if raw.lower() in ("false", "0"):+ return False+ return None+++def _parse_window(headers: dict[str, str], prefix: str, which: str) -> CodexRateLimitWindow | None:+ used_pct = _parse_float(headers, f"{prefix}-{which}-used-percent")+ if used_pct is None:+ return None+ return CodexRateLimitWindow(+ used_percent=used_pct,+ window_minutes=_parse_int(headers, f"{prefix}-{which}-window-minutes"),+ resets_at=_parse_int(headers, f"{prefix}-{which}-reset-at"),+ )+++def _parse_credits(headers: dict[str, str]) -> CodexCreditsSnapshot | None:+ has_credits = _parse_bool(headers, "x-codex-credits-has-credits")+ if has_credits is None:+ return None+ unlimited = _parse_bool(headers, "x-codex-credits-unlimited") or False+ raw_balance = headers.get("x-codex-credits-balance", "").strip()+ return CodexCreditsSnapshot(+ has_credits=has_credits,+ unlimited=unlimited,+ balance=raw_balance or None,+ )+++def parse_codex_rate_limits(headers: dict[str, str]) -> CodexRateLimitSnapshot | None:+ """Parse a :class:`CodexRateLimitSnapshot` from a dict of HTTP response headers.++ Returns ``None`` when no Codex rate-limit headers are present (e.g. the+ response came from a non-Codex OpenAI endpoint or a cached reply).+ """+ prefix = "x-codex"+ primary = _parse_window(headers, prefix, "primary")+ secondary = _parse_window(headers, prefix, "secondary")+ credits = _parse_credits(headers)+ raw_promo = headers.get("x-codex-promo-message", "").strip()+ promo = raw_promo or None+ raw_limit_name = headers.get("x-codex-limit-name", "").strip()+ limit_name = raw_limit_name or None++ if primary is None and secondary is None and credits is None and promo is None:+ return None # Not a Codex response with rate-limit headers++ return CodexRateLimitSnapshot(+ limit_id="codex",+ limit_name=limit_name,+ primary=primary,+ secondary=secondary,+ credits=credits,+ promo_message=promo,+ )+++# ---------------------------------------------------------------------------+# Singleton state store+# ---------------------------------------------------------------------------+++class CodexRateLimitState(QuotaTracker):+ """Thread-safe store for the latest Codex rate-limit snapshot.++ Implements :class:`~headroom.subscription.base.QuotaTracker` so it can+ be registered with the :class:`~headroom.subscription.base.QuotaTrackerRegistry`.+ This tracker is *passive* — it is updated by the OpenAI proxy handler+ each time a response containing ``x-codex-*`` headers passes through+ headroom, so :meth:`start` and :meth:`stop` are no-ops.+ """++ # QuotaTracker identity+ key = "codex_rate_limits"+ label = "OpenAI Codex"++ def __init__(self) -> None:+ self._lock = Lock()+ self._latest: CodexRateLimitSnapshot | None = None++ def update_from_headers(self, headers: dict[str, str]) -> None:+ """Update state from a response header dict (no-op if no Codex headers)."""+ snapshot = parse_codex_rate_limits(headers)+ if snapshot is None:+ return+ with self._lock:+ self._latest = snapshot++ @property+ def latest(self) -> CodexRateLimitSnapshot | None:+ with self._lock:+ return self._latest++ def get_stats(self) -> dict | None:+ snap = self.latest+ return snap.to_dict() if snap is not None else None+++_state: CodexRateLimitState | None = None+_state_lock = Lock()+++def get_codex_rate_limit_state() -> CodexRateLimitState:+ """Return the process-global :class:`CodexRateLimitState` singleton."""+ global _state+ if _state is None:+ with _state_lock:+ if _state is None:+ _state = CodexRateLimitState()+ return _statediff --git a/headroom/subscription/copilot_quota.py b/headroom/subscription/copilot_quota.pyindex c7b03628f..acdb29954 100644--- a/headroom/subscription/copilot_quota.py+++ b/headroom/subscription/copilot_quota.py@@ -1,366 +1,366 @@-"""GitHub Copilot monthly quota tracking via the copilot_internal/user API.--GitHub Copilot exposes per-category monthly quotas (chat, completions,-premium_interactions) at ``GET https://api.github.com/copilot_internal/user``-authenticated with a GitHub Bearer token.--Token discovery order (first non-empty wins):- 1. GITHUB_COPILOT_GITHUB_TOKEN- 2. GITHUB_TOKEN- 3. COPILOT_GITHUB_TOKEN- 4. GITHUB_COPILOT_API_TOKEN--The poll is triggered every ``poll_interval_s`` seconds (default 60) as long as-a GitHub token is available. No proxy traffic interception is needed — tokens-come from the environment at headroom start-up.--API response schema (relevant fields from ``/copilot_internal/user``):- login str GitHub username- copilot_plan str "free" | "individual" | "business" | "enterprise"- access_type_sku str plan SKU string- quota_reset_date_utc str ISO-8601 date when monthly quota resets- quota_snapshots:- chat / completions / premium_interactions:- entitlement int total monthly allocation- remaining int remaining uses this month- quota_remaining int (alias for remaining)- percent_remaining float 0-100- overage_count int uses beyond entitlement- overage_permitted bool whether overage is allowed- unlimited bool whether this category is unlimited- timestamp_utc str when the snapshot was recorded-"""--from __future__ import annotations--import asyncio-import logging-import os-import time-from dataclasses import dataclass, field-from threading import Lock-from typing import Any--from headroom.subscription.base import QuotaTracker--logger = logging.getLogger(__name__)--_GITHUB_API_BASE = "https://api.github.com"-_TOKEN_ENV_VARS = [- "GITHUB_COPILOT_GITHUB_TOKEN",- "GITHUB_TOKEN",- "COPILOT_GITHUB_TOKEN",- "GITHUB_COPILOT_API_TOKEN",-]--# Categories surfaced by the quota_snapshots endpoint-QUOTA_CATEGORIES = ("chat", "completions", "premium_interactions")---# ----------------------------------------------------------------------------# Data classes-# ------------------------------------------------------------------------------@dataclass-class CopilotQuotaCategory:- """Quota data for a single Copilot usage category."""-- name: str- entitlement: int | None = None # total monthly allocation- remaining: int | None = None # remaining uses- percent_remaining: float | None = None # 0-100- overage_count: int = 0 # uses beyond entitlement- overage_permitted: bool = False- unlimited: bool = False- timestamp_utc: str | None = None-- @property- def used(self) -> int | None:- if self.entitlement is not None and self.remaining is not None:- return max(0, self.entitlement - self.remaining)- return None-- @property- def used_percent(self) -> float | None:- if self.unlimited:- return 0.0- if self.percent_remaining is not None:- return max(0.0, 100.0 - self.percent_remaining)- if self.entitlement and self.entitlement > 0 and self.remaining is not None:- return 100.0 * (self.entitlement - self.remaining) / self.entitlement- return None-- def to_dict(self) -> dict[str, Any]:- return {- "name": self.name,- "entitlement": self.entitlement,- "remaining": self.remaining,- "used": self.used,- "percent_remaining": self.percent_remaining,- "used_percent": self.used_percent,- "overage_count": self.overage_count,- "overage_permitted": self.overage_permitted,- "unlimited": self.unlimited,- "timestamp_utc": self.timestamp_utc,- }---@dataclass-class CopilotQuotaSnapshot:- """Full quota snapshot from one /copilot_internal/user response."""-- login: str | None = None- copilot_plan: str | None = None- access_type_sku: str | None = None- quota_reset_date_utc: str | None = None- categories: dict[str, CopilotQuotaCategory] = field(default_factory=dict)- fetched_at: float = field(default_factory=time.time)-- def to_dict(self) -> dict[str, Any]:- return {- "login": self.login,- "copilot_plan": self.copilot_plan,- "access_type_sku": self.access_type_sku,- "quota_reset_date_utc": self.quota_reset_date_utc,- "categories": {k: v.to_dict() for k, v in self.categories.items()},- "fetched_at": self.fetched_at,- }---@dataclass-class CopilotQuotaState:- """Thread-safe singleton state for Copilot quota tracking."""-- latest: CopilotQuotaSnapshot | None = None- last_error: str | None = None- last_updated: float | None = None-- def to_dict(self) -> dict[str, Any]:- return {- "latest": self.latest.to_dict() if self.latest else None,- "last_error": self.last_error,- "last_updated": self.last_updated,- }---# ----------------------------------------------------------------------------# Parsing-# ------------------------------------------------------------------------------def parse_copilot_quota(data: dict[str, Any]) -> CopilotQuotaSnapshot:- """Parse a /copilot_internal/user response into a ``CopilotQuotaSnapshot``."""- snapshot = CopilotQuotaSnapshot(- login=data.get("login"),- copilot_plan=data.get("copilot_plan"),- access_type_sku=data.get("access_type_sku"),- quota_reset_date_utc=data.get("quota_reset_date_utc") or data.get("quota_reset_date"),- )-- raw_qs = data.get("quota_snapshots") or {}- for cat_name in QUOTA_CATEGORIES:- raw = raw_qs.get(cat_name)- if not raw:- continue- remaining = raw.get("remaining") or raw.get("quota_remaining")- cat = CopilotQuotaCategory(- name=cat_name,- entitlement=raw.get("entitlement"),- remaining=remaining,- percent_remaining=raw.get("percent_remaining"),- overage_count=raw.get("overage_count") or 0,- overage_permitted=bool(raw.get("overage_permitted")),- unlimited=bool(raw.get("unlimited")),- timestamp_utc=raw.get("timestamp_utc"),- )- snapshot.categories[cat_name] = cat-- return snapshot---# ----------------------------------------------------------------------------# Token discovery-# ------------------------------------------------------------------------------def discover_github_token() -> str | None:- """Return the first GitHub token found from known environment variables."""- for var in _TOKEN_ENV_VARS:- val = os.environ.get(var, "").strip()- if val:- return val- return None---# ----------------------------------------------------------------------------# Background tracker singleton-# ------------------------------------------------------------------------------class _CopilotQuotaTracker(QuotaTracker):- """Singleton background poller for GitHub Copilot quota.-- Implements :class:`~headroom.subscription.base.QuotaTracker` so it can be- registered with the :class:`~headroom.subscription.base.QuotaTrackerRegistry`.- Availability is gated on a GitHub token being present in the environment.- """-- # QuotaTracker identity- key = "copilot_quota"- label = "GitHub Copilot"-- def __init__(self, poll_interval_s: float = 60.0) -> None:- self._poll_interval_s = poll_interval_s- self._state = CopilotQuotaState()- self._lock = Lock()- self._stop_event: asyncio.Event | None = None- self._task: asyncio.Task | None = None # type: ignore[type-arg]-- # ------------------------------------------------------------------- # QuotaTracker interface- # -------------------------------------------------------------------- def is_available(self) -> bool:- """Returns ``True`` when a GitHub token is available in the environment."""- return discover_github_token() is not None-- def get_stats(self) -> dict[str, Any] | None:- """Return the latest quota state dict, or ``None`` if no data yet."""- data = self.state- if not data.get("latest"):- return None- return data-- # ------------------------------------------------------------------- # Lifecycle- # -------------------------------------------------------------------- async def start(self) -> None:- """Start the background polling loop."""- if self._task is not None and not self._task.done():- return- self._stop_event = asyncio.Event()- self._task = asyncio.create_task(self._poll_loop())-- async def stop(self) -> None:- """Stop the polling loop."""- if self._stop_event:- self._stop_event.set()- if self._task:- try:- await asyncio.wait_for(self._task, timeout=5.0)- except (asyncio.TimeoutError, asyncio.CancelledError):- # Mirror SubscriptionTracker.stop(): on timeout or outer- # cancellation, cancel the underlying poll task. Without- # this, a wedged poll task would leak past ``stop()``.- self._task.cancel()-- # ------------------------------------------------------------------- # State- # -------------------------------------------------------------------- @property- def state(self) -> dict[str, Any]:- with self._lock:- return self._state.to_dict()-- # ------------------------------------------------------------------- # Poll loop- # -------------------------------------------------------------------- async def _poll_loop(self) -> None:- assert self._stop_event is not None- while not self._stop_event.is_set():- try:- await self._maybe_poll()- except Exception as exc:- logger.warning("Copilot quota poll error: %s", exc)- try:- # NOTE: do NOT wrap in asyncio.shield() — shield prevents the- # inner Event.wait() from being cancelled when wait_for times- # out, leaking one Task per poll interval. See the matching- # note in headroom/subscription/tracker.py:_poll_loop.- await asyncio.wait_for(- self._stop_event.wait(),- timeout=self._poll_interval_s,- )- break # stop event was set- except asyncio.TimeoutError:- pass # normal: poll interval elapsed-- async def _maybe_poll(self) -> None:- token = discover_github_token()- if not token:- return-- try:- import aiohttp- except ImportError:- logger.debug("aiohttp not available; skipping Copilot quota poll")- return-- url = f"{_GITHUB_API_BASE}/copilot_internal/user"- headers = {- "Authorization": f"Bearer {token}",- "Accept": "application/json",- "X-GitHub-Api-Version": "2022-11-28",- }-- try:- async with aiohttp.ClientSession() as session:- async with session.get(- url, headers=headers, timeout=aiohttp.ClientTimeout(total=10)- ) as resp:- if resp.status == 401:- with self._lock:- self._state.last_error = "unauthorized — check GITHUB_TOKEN"- return- if resp.status == 404:- # API-key-only account or endpoint not available- with self._lock:- self._state.last_error = "endpoint not found (non-Copilot account?)"- return- if not resp.ok:- with self._lock:- self._state.last_error = f"HTTP {resp.status}"- return-- data = await resp.json()- except Exception as exc:- with self._lock:- self._state.last_error = str(exc)- logger.debug("Copilot quota fetch failed: %s", exc)- return-- try:- snapshot = parse_copilot_quota(data)- except Exception as exc:- with self._lock:- self._state.last_error = f"parse error: {exc}"- return-- with self._lock:- self._state.latest = snapshot- self._state.last_error = None- self._state.last_updated = time.time()-- logger.debug(- "Copilot quota polled: plan=%s categories=%s",- snapshot.copilot_plan,- list(snapshot.categories.keys()),- )---_singleton_lock = Lock()-_singleton: _CopilotQuotaTracker | None = None---def get_copilot_quota_tracker() -> _CopilotQuotaTracker:- """Return the global ``_CopilotQuotaTracker`` singleton."""- global _singleton- if _singleton is None:- with _singleton_lock:- if _singleton is None:- _singleton = _CopilotQuotaTracker()- return _singleton+"""GitHub Copilot monthly quota tracking via the copilot_internal/user API.++GitHub Copilot exposes per-category monthly quotas (chat, completions,+premium_interactions) at ``GET https://api.github.com/copilot_internal/user``+authenticated with a GitHub Bearer token.++Token discovery order (first non-empty wins):+ 1. GITHUB_COPILOT_GITHUB_TOKEN+ 2. GITHUB_TOKEN+ 3. COPILOT_GITHUB_TOKEN+ 4. GITHUB_COPILOT_API_TOKEN++The poll is triggered every ``poll_interval_s`` seconds (default 60) as long as+a GitHub token is available. No proxy traffic interception is needed — tokens+come from the environment at headroom start-up.++API response schema (relevant fields from ``/copilot_internal/user``):+ login str GitHub username+ copilot_plan str "free" | "individual" | "business" | "enterprise"+ access_type_sku str plan SKU string+ quota_reset_date_utc str ISO-8601 date when monthly quota resets+ quota_snapshots:+ chat / completions / premium_interactions:+ entitlement int total monthly allocation+ remaining int remaining uses this month+ quota_remaining int (alias for remaining)+ percent_remaining float 0-100+ overage_count int uses beyond entitlement+ overage_permitted bool whether overage is allowed+ unlimited bool whether this category is unlimited+ timestamp_utc str when the snapshot was recorded+"""++from __future__ import annotations++import asyncio+import logging+import os+import time+from dataclasses import dataclass, field+from threading import Lock+from typing import Any++from headroom.subscription.base import QuotaTracker++logger = logging.getLogger(__name__)++_GITHUB_API_BASE = "https://api.github.com"+_TOKEN_ENV_VARS = [+ "GITHUB_COPILOT_GITHUB_TOKEN",+ "GITHUB_TOKEN",+ "COPILOT_GITHUB_TOKEN",+ "GITHUB_COPILOT_API_TOKEN",+]++# Categories surfaced by the quota_snapshots endpoint+QUOTA_CATEGORIES = ("chat", "completions", "premium_interactions")+++# ---------------------------------------------------------------------------+# Data classes+# ---------------------------------------------------------------------------+++@dataclass+class CopilotQuotaCategory:+ """Quota data for a single Copilot usage category."""++ name: str+ entitlement: int | None = None # total monthly allocation+ remaining: int | None = None # remaining uses+ percent_remaining: float | None = None # 0-100+ overage_count: int = 0 # uses beyond entitlement+ overage_permitted: bool = False+ unlimited: bool = False+ timestamp_utc: str | None = None++ @property+ def used(self) -> int | None:+ if self.entitlement is not None and self.remaining is not None:+ return max(0, self.entitlement - self.remaining)+ return None++ @property+ def used_percent(self) -> float | None:+ if self.unlimited:+ return 0.0+ if self.percent_remaining is not None:+ return max(0.0, 100.0 - self.percent_remaining)+ if self.entitlement and self.entitlement > 0 and self.remaining is not None:+ return 100.0 * (self.entitlement - self.remaining) / self.entitlement+ return None++ def to_dict(self) -> dict[str, Any]:+ return {+ "name": self.name,+ "entitlement": self.entitlement,+ "remaining": self.remaining,+ "used": self.used,+ "percent_remaining": self.percent_remaining,+ "used_percent": self.used_percent,+ "overage_count": self.overage_count,+ "overage_permitted": self.overage_permitted,+ "unlimited": self.unlimited,+ "timestamp_utc": self.timestamp_utc,+ }+++@dataclass+class CopilotQuotaSnapshot:+ """Full quota snapshot from one /copilot_internal/user response."""++ login: str | None = None+ copilot_plan: str | None = None+ access_type_sku: str | None = None+ quota_reset_date_utc: str | None = None+ categories: dict[str, CopilotQuotaCategory] = field(default_factory=dict)+ fetched_at: float = field(default_factory=time.time)++ def to_dict(self) -> dict[str, Any]:+ return {+ "login": self.login,+ "copilot_plan": self.copilot_plan,+ "access_type_sku": self.access_type_sku,+ "quota_reset_date_utc": self.quota_reset_date_utc,+ "categories": {k: v.to_dict() for k, v in self.categories.items()},+ "fetched_at": self.fetched_at,+ }+++@dataclass+class CopilotQuotaState:+ """Thread-safe singleton state for Copilot quota tracking."""++ latest: CopilotQuotaSnapshot | None = None+ last_error: str | None = None+ last_updated: float | None = None++ def to_dict(self) -> dict[str, Any]:+ return {+ "latest": self.latest.to_dict() if self.latest else None,+ "last_error": self.last_error,+ "last_updated": self.last_updated,+ }+++# ---------------------------------------------------------------------------+# Parsing+# ---------------------------------------------------------------------------+++def parse_copilot_quota(data: dict[str, Any]) -> CopilotQuotaSnapshot:+ """Parse a /copilot_internal/user response into a ``CopilotQuotaSnapshot``."""+ snapshot = CopilotQuotaSnapshot(+ login=data.get("login"),+ copilot_plan=data.get("copilot_plan"),+ access_type_sku=data.get("access_type_sku"),+ quota_reset_date_utc=data.get("quota_reset_date_utc") or data.get("quota_reset_date"),+ )++ raw_qs = data.get("quota_snapshots") or {}+ for cat_name in QUOTA_CATEGORIES:+ raw = raw_qs.get(cat_name)+ if not raw:+ continue+ remaining = raw.get("remaining") or raw.get("quota_remaining")+ cat = CopilotQuotaCategory(+ name=cat_name,+ entitlement=raw.get("entitlement"),+ remaining=remaining,+ percent_remaining=raw.get("percent_remaining"),+ overage_count=raw.get("overage_count") or 0,+ overage_permitted=bool(raw.get("overage_permitted")),+ unlimited=bool(raw.get("unlimited")),+ timestamp_utc=raw.get("timestamp_utc"),+ )+ snapshot.categories[cat_name] = cat++ return snapshot+++# ---------------------------------------------------------------------------+# Token discovery+# ---------------------------------------------------------------------------+++def discover_github_token() -> str | None:+ """Return the first GitHub token found from known environment variables."""+ for var in _TOKEN_ENV_VARS:+ val = os.environ.get(var, "").strip()+ if val:+ return val+ return None+++# ---------------------------------------------------------------------------+# Background tracker singleton+# ---------------------------------------------------------------------------+++class _CopilotQuotaTracker(QuotaTracker):+ """Singleton background poller for GitHub Copilot quota.++ Implements :class:`~headroom.subscription.base.QuotaTracker` so it can be+ registered with the :class:`~headroom.subscription.base.QuotaTrackerRegistry`.+ Availability is gated on a GitHub token being present in the environment.+ """++ # QuotaTracker identity+ key = "copilot_quota"+ label = "GitHub Copilot"++ def __init__(self, poll_interval_s: float = 60.0) -> None:+ self._poll_interval_s = poll_interval_s+ self._state = CopilotQuotaState()+ self._lock = Lock()+ self._stop_event: asyncio.Event | None = None+ self._task: asyncio.Task | None = None # type: ignore[type-arg]++ # ------------------------------------------------------------------+ # QuotaTracker interface+ # ------------------------------------------------------------------++ def is_available(self) -> bool:+ """Returns ``True`` when a GitHub token is available in the environment."""+ return discover_github_token() is not None++ def get_stats(self) -> dict[str, Any] | None:+ """Return the latest quota state dict, or ``None`` if no data yet."""+ data = self.state+ if not data.get("latest"):+ return None+ return data++ # ------------------------------------------------------------------+ # Lifecycle+ # ------------------------------------------------------------------++ async def start(self) -> None:+ """Start the background polling loop."""+ if self._task is not None and not self._task.done():+ return+ self._stop_event = asyncio.Event()+ self._task = asyncio.create_task(self._poll_loop())++ async def stop(self) -> None:+ """Stop the polling loop."""+ if self._stop_event:+ self._stop_event.set()+ if self._task:+ try:+ await asyncio.wait_for(self._task, timeout=5.0)+ except (asyncio.TimeoutError, asyncio.CancelledError):+ # Mirror SubscriptionTracker.stop(): on timeout or outer+ # cancellation, cancel the underlying poll task. Without+ # this, a wedged poll task would leak past ``stop()``.+ self._task.cancel()++ # ------------------------------------------------------------------+ # State+ # ------------------------------------------------------------------++ @property+ def state(self) -> dict[str, Any]:+ with self._lock:+ return self._state.to_dict()++ # ------------------------------------------------------------------+ # Poll loop+ # ------------------------------------------------------------------++ async def _poll_loop(self) -> None:+ assert self._stop_event is not None+ while not self._stop_event.is_set():+ try:+ await self._maybe_poll()+ except Exception as exc:+ logger.warning("Copilot quota poll error: %s", exc)+ try:+ # NOTE: do NOT wrap in asyncio.shield() — shield prevents the+ # inner Event.wait() from being cancelled when wait_for times+ # out, leaking one Task per poll interval. See the matching+ # note in headroom/subscription/tracker.py:_poll_loop.+ await asyncio.wait_for(+ self._stop_event.wait(),+ timeout=self._poll_interval_s,+ )+ break # stop event was set+ except asyncio.TimeoutError:+ pass # normal: poll interval elapsed++ async def _maybe_poll(self) -> None:+ token = discover_github_token()+ if not token:+ return++ try:+ import aiohttp+ except ImportError:+ logger.debug("aiohttp not available; skipping Copilot quota poll")+ return++ url = f"{_GITHUB_API_BASE}/copilot_internal/user"+ headers = {+ "Authorization": f"Bearer {token}",+ "Accept": "application/json",+ "X-GitHub-Api-Version": "2022-11-28",+ }++ try:+ async with aiohttp.ClientSession() as session:+ async with session.get(+ url, headers=headers, timeout=aiohttp.ClientTimeout(total=10)+ ) as resp:+ if resp.status == 401:+ with self._lock:+ self._state.last_error = "unauthorized — check GITHUB_TOKEN"+ return+ if resp.status == 404:+ # API-key-only account or endpoint not available+ with self._lock:+ self._state.last_error = "endpoint not found (non-Copilot account?)"+ return+ if not resp.ok:+ with self._lock:+ self._state.last_error = f"HTTP {resp.status}"+ return++ data = await resp.json()+ except Exception as exc:+ with self._lock:+ self._state.last_error = str(exc)+ logger.debug("Copilot quota fetch failed: %s", exc)+ return++ try:+ snapshot = parse_copilot_quota(data)+ except Exception as exc:+ with self._lock:+ self._state.last_error = f"parse error: {exc}"+ return++ with self._lock:+ self._state.latest = snapshot+ self._state.last_error = None+ self._state.last_updated = time.time()++ logger.debug(+ "Copilot quota polled: plan=%s categories=%s",+ snapshot.copilot_plan,+ list(snapshot.categories.keys()),+ )+++_singleton_lock = Lock()+_singleton: _CopilotQuotaTracker | None = None+++def get_copilot_quota_tracker() -> _CopilotQuotaTracker:+ """Return the global ``_CopilotQuotaTracker`` singleton."""+ global _singleton+ if _singleton is None:+ with _singleton_lock:+ if _singleton is None:+ _singleton = _CopilotQuotaTracker()+ return _singletondiff --git a/headroom/subscription/models.py b/headroom/subscription/models.pyindex c621f4df0..136a10cda 100644--- a/headroom/subscription/models.py+++ b/headroom/subscription/models.py@@ -1,395 +1,395 @@-"""Data models for Anthropic subscription window tracking.--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- - Window discrepancy detection (surge pricing, cache-miss anomalies)-"""--from __future__ import annotations--from dataclasses import dataclass, field-from datetime import datetime, timezone-from typing import Any--# ----------------------------------------------------------------------------# Helpers-# ------------------------------------------------------------------------------def _utc_now() -> datetime:- return datetime.now(timezone.utc)---def _to_utc_iso(dt: datetime) -> str:- return dt.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")---def _parse_timestamp(value: Any) -> datetime | None:- if not isinstance(value, str) or not value:- return None- normalized = value.replace("Z", "+00:00")- try:- dt = datetime.fromisoformat(normalized)- except ValueError:- return None- if dt.tzinfo is None:- dt = dt.replace(tzinfo=timezone.utc)- return dt.astimezone(timezone.utc)---def _safe_float(value: Any) -> float | None:- if value is None:- return None- try:- return float(value)- except (TypeError, ValueError):- return None---def _safe_int(value: Any) -> int | None:- if value is None:- return None- try:- return int(value)- except (TypeError, ValueError):- return None---# ----------------------------------------------------------------------------# Rate-limit window (five_hour / seven_day / seven_day_opus / seven_day_sonnet)-# ------------------------------------------------------------------------------@dataclass-class RateLimitWindow:- """A single rolling rate-limit window returned by the Anthropic usage API.-- ``used`` and ``limit`` are in Anthropic's internal token-equivalent units- (not raw tokens; Anthropic weights tokens differently per model family).- ``utilization_pct`` is the authoritative 0–100 % figure from the API.- """-- used: int = 0- limit: int = 0- utilization_pct: float = 0.0- resets_at: datetime | None = None-- @classmethod- def from_api_dict(cls, data: dict[str, Any]) -> RateLimitWindow:- return cls(- used=int(data.get("used") or 0),- limit=int(data.get("limit") or 0),- utilization_pct=float(data.get("utilization") or 0.0),- resets_at=_parse_timestamp(data.get("resets_at")),- )-- def seconds_to_reset(self, *, now: datetime | None = None) -> float | None:- if self.resets_at is None:- return None- return max((self.resets_at - (now or _utc_now())).total_seconds(), 0.0)-- def to_dict(self) -> dict[str, Any]:- return {- "used": self.used,- "limit": self.limit,- "utilization_pct": round(self.utilization_pct, 2),- "resets_at": _to_utc_iso(self.resets_at) if self.resets_at else None,- "seconds_to_reset": self.seconds_to_reset(),- }---# ----------------------------------------------------------------------------# Extra-usage / overage block-# ------------------------------------------------------------------------------@dataclass-class ExtraUsage:- """Overage / extra-usage block from the Anthropic usage API.-- ``monthly_limit_cents`` and ``used_credits_cents`` are in US cents as- returned by the API (divide by 100 for USD).- """-- is_enabled: bool = False- monthly_limit_cents: int | None = None- used_credits_cents: int | None = None- utilization_pct: float | None = None-- @classmethod- def from_api_dict(cls, data: dict[str, Any]) -> ExtraUsage:- return cls(- is_enabled=bool(data.get("is_enabled", False)),- monthly_limit_cents=_safe_int(data.get("monthly_limit")),- used_credits_cents=_safe_int(data.get("used_credits")),- utilization_pct=_safe_float(data.get("utilization")),- )-- @property- def monthly_limit_usd(self) -> float | None:- if self.monthly_limit_cents is None:- return None- return self.monthly_limit_cents / 100.0-- @property- def used_credits_usd(self) -> float | None:- if self.used_credits_cents is None:- return None- return self.used_credits_cents / 100.0-- def to_dict(self) -> dict[str, Any]:- return {- "is_enabled": self.is_enabled,- "monthly_limit_usd": round(self.monthly_limit_usd, 2)- if self.monthly_limit_usd is not None- else None,- "used_credits_usd": round(self.used_credits_usd, 4)- if self.used_credits_usd is not None- else None,- "utilization_pct": round(self.utilization_pct, 2)- if self.utilization_pct is not None- else None,- }---# ----------------------------------------------------------------------------# Full snapshot from one API poll-# ------------------------------------------------------------------------------@dataclass-class SubscriptionSnapshot:- """One complete poll of GET /api/oauth/usage."""-- five_hour: RateLimitWindow = field(default_factory=RateLimitWindow)- seven_day: RateLimitWindow = field(default_factory=RateLimitWindow)- seven_day_opus: RateLimitWindow | None = None- seven_day_sonnet: RateLimitWindow | None = None- extra_usage: ExtraUsage = field(default_factory=ExtraUsage)- polled_at: datetime = field(default_factory=_utc_now)- token_prefix: str = ""- """First 8 chars of the OAuth token (for multi-account detection)."""-- @classmethod- def from_api_response(cls, data: dict[str, Any], *, token: str = "") -> SubscriptionSnapshot:- snap = cls(token_prefix=token[:8] if token else "")- if "five_hour" in data and data["five_hour"]:- snap.five_hour = RateLimitWindow.from_api_dict(data["five_hour"])- if "seven_day" in data and data["seven_day"]:- snap.seven_day = RateLimitWindow.from_api_dict(data["seven_day"])- if "seven_day_opus" in data and data["seven_day_opus"]:- snap.seven_day_opus = RateLimitWindow.from_api_dict(data["seven_day_opus"])- if "seven_day_sonnet" in data and data["seven_day_sonnet"]:- snap.seven_day_sonnet = RateLimitWindow.from_api_dict(data["seven_day_sonnet"])- if "extra_usage" in data and data["extra_usage"]:- snap.extra_usage = ExtraUsage.from_api_dict(data["extra_usage"])- return snap-- def to_dict(self) -> dict[str, Any]:- d: dict[str, Any] = {- "five_hour": self.five_hour.to_dict(),- "seven_day": self.seven_day.to_dict(),- "extra_usage": self.extra_usage.to_dict(),- "polled_at": _to_utc_iso(self.polled_at),- "token_prefix": self.token_prefix,- }- if self.seven_day_opus:- d["seven_day_opus"] = self.seven_day_opus.to_dict()- if self.seven_day_sonnet:- d["seven_day_sonnet"] = self.seven_day_sonnet.to_dict()- return d---# ----------------------------------------------------------------------------# Transcript-based window token breakdown-# ------------------------------------------------------------------------------@dataclass-class WindowTokens:- """Token breakdown from Claude transcript JSONL files for one time window."""-- input: int = 0- output: int = 0- cache_reads: int = 0- cache_writes_5m: int = 0- cache_writes_1h: int = 0- cache_writes_total: int = 0- by_model: dict[str, dict[str, int]] = field(default_factory=dict)- weighted_token_equivalent: float = 0.0- """Sonnet-normalised weighted total (opus×2, sonnet×1, haiku×0.5)."""-- def total_raw(self) -> int:- return self.input + self.output + self.cache_reads + self.cache_writes_total-- def to_dict(self) -> dict[str, Any]:- return {- "input": self.input,- "output": self.output,- "cache_reads": self.cache_reads,- "cache_writes_5m": self.cache_writes_5m,- "cache_writes_1h": self.cache_writes_1h,- "cache_writes_total": self.cache_writes_total,- "total_raw": self.total_raw(),- "weighted_token_equivalent": round(self.weighted_token_equivalent, 1),- "by_model": self.by_model,- }---# ----------------------------------------------------------------------------# Headroom contribution estimate-# ------------------------------------------------------------------------------@dataclass-class HeadroomContribution:- """Tokens conserved within the current 5h window by Headroom's layers.-- These are cumulative counters reset when the 5h window rolls over.- """-- tokens_submitted: int = 0- """Raw input tokens actually forwarded to Anthropic by the proxy."""-- tokens_saved_compression: int = 0- """Input tokens removed by proxy compression."""-- tokens_saved_rtk: int = 0- """Tokens avoided by CLI filtering (rtk) before reaching context."""-- tokens_saved_cache_reads: int = 0- """Input tokens served from Anthropic prefix-cache (discounted reads)."""-- compression_savings_usd: float = 0.0- cache_savings_usd: float = 0.0-- def total_saved(self) -> int:- return self.tokens_saved_compression + self.tokens_saved_rtk + self.tokens_saved_cache_reads-- def total_savings_usd(self) -> float:- return self.compression_savings_usd + self.cache_savings_usd-- def raw_without_headroom(self) -> int:- return self.tokens_submitted + self.tokens_saved_compression + self.tokens_saved_rtk-- def efficiency_pct(self) -> float:- raw = self.raw_without_headroom()- if raw == 0:- return 0.0- return round(self.total_saved() / raw * 100, 1)-- def to_dict(self) -> dict[str, Any]:- return {- "tokens_submitted": self.tokens_submitted,- "tokens_saved": {- "compression": self.tokens_saved_compression,- "rtk": self.tokens_saved_rtk,- "cache_reads": self.tokens_saved_cache_reads,- "total": self.total_saved(),- },- "raw_without_headroom": self.raw_without_headroom(),- "efficiency_pct": self.efficiency_pct(),- "savings_usd": {- "compression": round(self.compression_savings_usd, 4),- "cache": round(self.cache_savings_usd, 4),- "total": round(self.total_savings_usd(), 4),- },- }---# ----------------------------------------------------------------------------# Anomaly / discrepancy record-# ------------------------------------------------------------------------------@dataclass-class WindowDiscrepancy:- """Detected anomaly between expected and API-reported utilization."""-- kind: str- """'surge_pricing' | 'cache_miss' | 'none'"""-- description: str = ""- severity: str = "info"- """'info' | 'warning' | 'alert'"""-- expected_utilization_pct: float | None = None- actual_utilization_pct: float | None = None- delta_pct: float | None = None-- def to_dict(self) -> dict[str, Any]:- return {- "kind": self.kind,- "description": self.description,- "severity": self.severity,- "expected_utilization_pct": self.expected_utilization_pct,- "actual_utilization_pct": self.actual_utilization_pct,- "delta_pct": self.delta_pct,- }---# ----------------------------------------------------------------------------# Full tracker state-# ------------------------------------------------------------------------------@dataclass-class SubscriptionState:- """Persistent state for the subscription tracker."""-- latest: SubscriptionSnapshot | None = None- window_tokens: WindowTokens | None = None- """Transcript-derived token breakdown for the current 5h window."""-- contribution: HeadroomContribution = field(default_factory=HeadroomContribution)- discrepancies: list[WindowDiscrepancy] = field(default_factory=list)- history: list[SubscriptionSnapshot] = field(default_factory=list)-- poll_count: int = 0- poll_errors: int = 0- last_error: str | None = None- last_active_at: datetime | None = None-- _MAX_HISTORY: int = field(default=100, init=False, repr=False)- _MAX_DISCREPANCIES: int = field(default=20, init=False, repr=False)-- def add_snapshot(self, snapshot: SubscriptionSnapshot) -> None:- self.latest = snapshot- self.history.append(snapshot)- if len(self.history) > self._MAX_HISTORY:- self.history = self.history[-self._MAX_HISTORY :]- self.poll_count += 1-- def mark_error(self, msg: str) -> None:- self.poll_errors += 1- self.last_error = msg-- def add_discrepancy(self, d: WindowDiscrepancy) -> None:- self.discrepancies.append(d)- if len(self.discrepancies) > self._MAX_DISCREPANCIES:- self.discrepancies = self.discrepancies[-self._MAX_DISCREPANCIES :]-- def is_active(self, *, active_window_s: float = 60.0) -> bool:- if self.last_active_at is None:- return False- return (_utc_now() - self.last_active_at).total_seconds() <= active_window_s-- def to_dict(self) -> dict[str, Any]:- return {- "latest": self.latest.to_dict() if self.latest else None,- "window_tokens": self.window_tokens.to_dict() if self.window_tokens else None,- "contribution": self.contribution.to_dict(),- "discrepancies": [d.to_dict() for d in self.discrepancies[-5:]],- "poll_count": self.poll_count,- "poll_errors": self.poll_errors,- "last_error": self.last_error,- "last_active_at": _to_utc_iso(self.last_active_at) if self.last_active_at else None,- }-- def to_persist_dict(self) -> dict[str, Any]:- d = self.to_dict()- d["history"] = [s.to_dict() for s in self.history[-20:]]- return d+"""Data models for Anthropic subscription window tracking.++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+ - Window discrepancy detection (surge pricing, cache-miss anomalies)+"""++from __future__ import annotations++from dataclasses import dataclass, field+from datetime import datetime, timezone+from typing import Any++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _utc_now() -> datetime:+ return datetime.now(timezone.utc)+++def _to_utc_iso(dt: datetime) -> str:+ return dt.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")+++def _parse_timestamp(value: Any) -> datetime | None:+ if not isinstance(value, str) or not value:+ return None+ normalized = value.replace("Z", "+00:00")+ try:+ dt = datetime.fromisoformat(normalized)+ except ValueError:+ return None+ if dt.tzinfo is None:+ dt = dt.replace(tzinfo=timezone.utc)+ return dt.astimezone(timezone.utc)+++def _safe_float(value: Any) -> float | None:+ if value is None:+ return None+ try:+ return float(value)+ except (TypeError, ValueError):+ return None+++def _safe_int(value: Any) -> int | None:+ if value is None:+ return None+ try:+ return int(value)+ except (TypeError, ValueError):+ return None+++# ---------------------------------------------------------------------------+# Rate-limit window (five_hour / seven_day / seven_day_opus / seven_day_sonnet)+# ---------------------------------------------------------------------------+++@dataclass+class RateLimitWindow:+ """A single rolling rate-limit window returned by the Anthropic usage API.++ ``used`` and ``limit`` are in Anthropic's internal token-equivalent units+ (not raw tokens; Anthropic weights tokens differently per model family).+ ``utilization_pct`` is the authoritative 0–100 % figure from the API.+ """++ used: int = 0+ limit: int = 0+ utilization_pct: float = 0.0+ resets_at: datetime | None = None++ @classmethod+ def from_api_dict(cls, data: dict[str, Any]) -> RateLimitWindow:+ return cls(+ used=int(data.get("used") or 0),+ limit=int(data.get("limit") or 0),+ utilization_pct=float(data.get("utilization") or 0.0),+ resets_at=_parse_timestamp(data.get("resets_at")),+ )++ def seconds_to_reset(self, *, now: datetime | None = None) -> float | None:+ if self.resets_at is None:+ return None+ return max((self.resets_at - (now or _utc_now())).total_seconds(), 0.0)++ def to_dict(self) -> dict[str, Any]:+ return {+ "used": self.used,+ "limit": self.limit,+ "utilization_pct": round(self.utilization_pct, 2),+ "resets_at": _to_utc_iso(self.resets_at) if self.resets_at else None,+ "seconds_to_reset": self.seconds_to_reset(),+ }+++# ---------------------------------------------------------------------------+# Extra-usage / overage block+# ---------------------------------------------------------------------------+++@dataclass+class ExtraUsage:+ """Overage / extra-usage block from the Anthropic usage API.++ ``monthly_limit_cents`` and ``used_credits_cents`` are in US cents as+ returned by the API (divide by 100 for USD).+ """++ is_enabled: bool = False+ monthly_limit_cents: int | None = None+ used_credits_cents: int | None = None+ utilization_pct: float | None = None++ @classmethod+ def from_api_dict(cls, data: dict[str, Any]) -> ExtraUsage:+ return cls(+ is_enabled=bool(data.get("is_enabled", False)),+ monthly_limit_cents=_safe_int(data.get("monthly_limit")),+ used_credits_cents=_safe_int(data.get("used_credits")),+ utilization_pct=_safe_float(data.get("utilization")),+ )++ @property+ def monthly_limit_usd(self) -> float | None:+ if self.monthly_limit_cents is None:+ return None+ return self.monthly_limit_cents / 100.0++ @property+ def used_credits_usd(self) -> float | None:+ if self.used_credits_cents is None:+ return None+ return self.used_credits_cents / 100.0++ def to_dict(self) -> dict[str, Any]:+ return {+ "is_enabled": self.is_enabled,+ "monthly_limit_usd": round(self.monthly_limit_usd, 2)+ if self.monthly_limit_usd is not None+ else None,+ "used_credits_usd": round(self.used_credits_usd, 4)+ if self.used_credits_usd is not None+ else None,+ "utilization_pct": round(self.utilization_pct, 2)+ if self.utilization_pct is not None+ else None,+ }+++# ---------------------------------------------------------------------------+# Full snapshot from one API poll+# ---------------------------------------------------------------------------+++@dataclass+class SubscriptionSnapshot:+ """One complete poll of GET /api/oauth/usage."""++ five_hour: RateLimitWindow = field(default_factory=RateLimitWindow)+ seven_day: RateLimitWindow = field(default_factory=RateLimitWindow)+ seven_day_opus: RateLimitWindow | None = None+ seven_day_sonnet: RateLimitWindow | None = None+ extra_usage: ExtraUsage = field(default_factory=ExtraUsage)+ polled_at: datetime = field(default_factory=_utc_now)+ token_prefix: str = ""+ """First 8 chars of the OAuth token (for multi-account detection)."""++ @classmethod+ def from_api_response(cls, data: dict[str, Any], *, token: str = "") -> SubscriptionSnapshot:+ snap = cls(token_prefix=token[:8] if token else "")+ if "five_hour" in data and data["five_hour"]:+ snap.five_hour = RateLimitWindow.from_api_dict(data["five_hour"])+ if "seven_day" in data and data["seven_day"]:+ snap.seven_day = RateLimitWindow.from_api_dict(data["seven_day"])+ if "seven_day_opus" in data and data["seven_day_opus"]:+ snap.seven_day_opus = RateLimitWindow.from_api_dict(data["seven_day_opus"])+ if "seven_day_sonnet" in data and data["seven_day_sonnet"]:+ snap.seven_day_sonnet = RateLimitWindow.from_api_dict(data["seven_day_sonnet"])+ if "extra_usage" in data and data["extra_usage"]:+ snap.extra_usage = ExtraUsage.from_api_dict(data["extra_usage"])+ return snap++ def to_dict(self) -> dict[str, Any]:+ d: dict[str, Any] = {+ "five_hour": self.five_hour.to_dict(),+ "seven_day": self.seven_day.to_dict(),+ "extra_usage": self.extra_usage.to_dict(),+ "polled_at": _to_utc_iso(self.polled_at),+ "token_prefix": self.token_prefix,+ }+ if self.seven_day_opus:+ d["seven_day_opus"] = self.seven_day_opus.to_dict()+ if self.seven_day_sonnet:+ d["seven_day_sonnet"] = self.seven_day_sonnet.to_dict()+ return d+++# ---------------------------------------------------------------------------+# Transcript-based window token breakdown+# ---------------------------------------------------------------------------+++@dataclass+class WindowTokens:+ """Token breakdown from Claude transcript JSONL files for one time window."""++ input: int = 0+ output: int = 0+ cache_reads: int = 0+ cache_writes_5m: int = 0+ cache_writes_1h: int = 0+ cache_writes_total: int = 0+ by_model: dict[str, dict[str, int]] = field(default_factory=dict)+ weighted_token_equivalent: float = 0.0+ """Sonnet-normalised weighted total (opus×2, sonnet×1, haiku×0.5)."""++ def total_raw(self) -> int:+ return self.input + self.output + self.cache_reads + self.cache_writes_total++ def to_dict(self) -> dict[str, Any]:+ return {+ "input": self.input,+ "output": self.output,+ "cache_reads": self.cache_reads,+ "cache_writes_5m": self.cache_writes_5m,+ "cache_writes_1h": self.cache_writes_1h,+ "cache_writes_total": self.cache_writes_total,+ "total_raw": self.total_raw(),+ "weighted_token_equivalent": round(self.weighted_token_equivalent, 1),+ "by_model": self.by_model,+ }+++# ---------------------------------------------------------------------------+# Headroom contribution estimate+# ---------------------------------------------------------------------------+++@dataclass+class HeadroomContribution:+ """Tokens conserved within the current 5h window by Headroom's layers.++ These are cumulative counters reset when the 5h window rolls over.+ """++ tokens_submitted: int = 0+ """Raw input tokens actually forwarded to Anthropic by the proxy."""++ tokens_saved_compression: int = 0+ """Input tokens removed by proxy compression."""++ tokens_saved_rtk: int = 0+ """Tokens avoided by CLI filtering (rtk) before reaching context."""++ tokens_saved_cache_reads: int = 0+ """Input tokens served from Anthropic prefix-cache (discounted reads)."""++ compression_savings_usd: float = 0.0+ cache_savings_usd: float = 0.0++ def total_saved(self) -> int:+ return self.tokens_saved_compression + self.tokens_saved_rtk + self.tokens_saved_cache_reads++ def total_savings_usd(self) -> float:+ return self.compression_savings_usd + self.cache_savings_usd++ def raw_without_headroom(self) -> int:+ return self.tokens_submitted + self.tokens_saved_compression + self.tokens_saved_rtk++ def efficiency_pct(self) -> float:+ raw = self.raw_without_headroom()+ if raw == 0:+ return 0.0+ return round(self.total_saved() / raw * 100, 1)++ def to_dict(self) -> dict[str, Any]:+ return {+ "tokens_submitted": self.tokens_submitted,+ "tokens_saved": {+ "compression": self.tokens_saved_compression,+ "rtk": self.tokens_saved_rtk,+ "cache_reads": self.tokens_saved_cache_reads,+ "total": self.total_saved(),+ },+ "raw_without_headroom": self.raw_without_headroom(),+ "efficiency_pct": self.efficiency_pct(),+ "savings_usd": {+ "compression": round(self.compression_savings_usd, 4),+ "cache": round(self.cache_savings_usd, 4),+ "total": round(self.total_savings_usd(), 4),+ },+ }+++# ---------------------------------------------------------------------------+# Anomaly / discrepancy record+# ---------------------------------------------------------------------------+++@dataclass+class WindowDiscrepancy:+ """Detected anomaly between expected and API-reported utilization."""++ kind: str+ """'surge_pricing' | 'cache_miss' | 'none'"""++ description: str = ""+ severity: str = "info"+ """'info' | 'warning' | 'alert'"""++ expected_utilization_pct: float | None = None+ actual_utilization_pct: float | None = None+ delta_pct: float | None = None++ def to_dict(self) -> dict[str, Any]:+ return {+ "kind": self.kind,+ "description": self.description,+ "severity": self.severity,+ "expected_utilization_pct": self.expected_utilization_pct,+ "actual_utilization_pct": self.actual_utilization_pct,+ "delta_pct": self.delta_pct,+ }+++# ---------------------------------------------------------------------------+# Full tracker state+# ---------------------------------------------------------------------------+++@dataclass+class SubscriptionState:+ """Persistent state for the subscription tracker."""++ latest: SubscriptionSnapshot | None = None+ window_tokens: WindowTokens | None = None+ """Transcript-derived token breakdown for the current 5h window."""++ contribution: HeadroomContribution = field(default_factory=HeadroomContribution)+ discrepancies: list[WindowDiscrepancy] = field(default_factory=list)+ history: list[SubscriptionSnapshot] = field(default_factory=list)++ poll_count: int = 0+ poll_errors: int = 0+ last_error: str | None = None+ last_active_at: datetime | None = None++ _MAX_HISTORY: int = field(default=100, init=False, repr=False)+ _MAX_DISCREPANCIES: int = field(default=20, init=False, repr=False)++ def add_snapshot(self, snapshot: SubscriptionSnapshot) -> None:+ self.latest = snapshot+ self.history.append(snapshot)+ if len(self.history) > self._MAX_HISTORY:+ self.history = self.history[-self._MAX_HISTORY :]+ self.poll_count += 1++ def mark_error(self, msg: str) -> None:+ self.poll_errors += 1+ self.last_error = msg++ def add_discrepancy(self, d: WindowDiscrepancy) -> None:+ self.discrepancies.append(d)+ if len(self.discrepancies) > self._MAX_DISCREPANCIES:+ self.discrepancies = self.discrepancies[-self._MAX_DISCREPANCIES :]++ def is_active(self, *, active_window_s: float = 60.0) -> bool:+ if self.last_active_at is None:+ return False+ return (_utc_now() - self.last_active_at).total_seconds() <= active_window_s++ def to_dict(self) -> dict[str, Any]:+ return {+ "latest": self.latest.to_dict() if self.latest else None,+ "window_tokens": self.window_tokens.to_dict() if self.window_tokens else None,+ "contribution": self.contribution.to_dict(),+ "discrepancies": [d.to_dict() for d in self.discrepancies[-5:]],+ "poll_count": self.poll_count,+ "poll_errors": self.poll_errors,+ "last_error": self.last_error,+ "last_active_at": _to_utc_iso(self.last_active_at) if self.last_active_at else None,+ }++ def to_persist_dict(self) -> dict[str, Any]:+ d = self.to_dict()+ d["history"] = [s.to_dict() for s in self.history[-20:]]+ return ddiff --git a/headroom/subscription/session_tracking.py b/headroom/subscription/session_tracking.pyindex 9367d79dd..754fa7746 100644--- a/headroom/subscription/session_tracking.py+++ b/headroom/subscription/session_tracking.py@@ -1,189 +1,189 @@-"""Parse Claude Code transcript JSONL files for per-window token breakdowns.--Mirrors the approach in the ClaudeCacheTTLStatusLine TypeScript reference-implementation (session-tracking.ts). Reads ~/.claude/projects/**/*.jsonl-and aggregates token usage for entries whose timestamp falls within a window.--Model weights (Sonnet-normalised, empirical estimates):- opus: 2.0× (higher rate-limit cost)- sonnet: 1.0× (baseline)- haiku: 0.5× (cheaper, lower rate-limit cost)--The weighted_token_equivalent lets callers detect surge pricing by comparing-it against the API-reported utilisation × window_limit.-"""--from __future__ import annotations--import json-import logging-import os-from pathlib import Path-from typing import Any--from headroom.subscription.models import WindowTokens--logger = logging.getLogger(__name__)--# Maximum bytes to read per transcript file (10 MB cap — generous, typical files <1 MB)-_MAX_FILE_BYTES = 10 * 1024 * 1024--# Sonnet-normalised model family weights-MODEL_FAMILY_WEIGHTS: dict[str, float] = {- "opus": 2.0,- "sonnet": 1.0,- "haiku": 0.5,-}-DEFAULT_MODEL_WEIGHT: float = 1.0---def _claude_config_dir() -> Path:- base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")- return Path(base)---def get_model_weight(model_id: str) -> float:- """Return the Sonnet-normalised weight for a model ID.-- Matches against known family names using a word-boundary check.- Falls back to DEFAULT_MODEL_WEIGHT for unrecognised models.- """- lower = model_id.lower()- import re-- for family, weight in MODEL_FAMILY_WEIGHTS.items():- if re.search(rf"(?<![a-z]){family}(?![a-z])", lower):- return weight- return DEFAULT_MODEL_WEIGHT---def find_transcript_files() -> list[Path]:- """Return all .jsonl files under ~/.claude/projects."""- projects = _claude_config_dir() / "projects"- results: list[Path] = []- _walk_jsonl(projects, results)- return results---def _walk_jsonl(directory: Path, results: list[Path]) -> None:- try:- entries = list(directory.iterdir())- except (OSError, PermissionError):- return- for entry in entries:- try:- if entry.is_dir():- _walk_jsonl(entry, results)- elif entry.suffix == ".jsonl":- results.append(entry)- except OSError:- continue---def _read_transcript_lines(path: Path) -> list[str]:- try:- size = path.stat().st_size- read_size = min(size, _MAX_FILE_BYTES)- with path.open("rb") as fh:- raw = fh.read(read_size)- return [line for line in raw.decode("utf-8", errors="replace").splitlines() if line.strip()]- except Exception:- return []---def _add_usage_to_tokens(dest: WindowTokens, usage: dict[str, Any]) -> None:- dest.input += int(usage.get("input_tokens") or 0)- dest.output += int(usage.get("output_tokens") or 0)- dest.cache_reads += int(usage.get("cache_read_input_tokens") or 0)-- cache_creation = usage.get("cache_creation") or {}- w5m = int(cache_creation.get("ephemeral_5m_input_tokens") or 0)- w1h = int(cache_creation.get("ephemeral_1h_input_tokens") or 0)- total_writes = int(usage.get("cache_creation_input_tokens") or (w5m + w1h))-- dest.cache_writes_5m += w5m- dest.cache_writes_1h += w1h- dest.cache_writes_total += total_writes---def compute_window_tokens(start_ts: float, end_ts: float) -> WindowTokens:- """Sum transcript token usage for entries in [start_ts, end_ts).-- Args:- start_ts: Window start as a Unix timestamp (seconds).- end_ts: Window end as a Unix timestamp (seconds).-- Returns:- :class:`WindowTokens` with aggregate + per-model breakdown and- ``weighted_token_equivalent`` (Sonnet-normalised).- """- totals = WindowTokens()- by_model: dict[str, WindowTokens] = {}- unattributed = WindowTokens()-- for path in find_transcript_files():- for line in _read_transcript_lines(path):- try:- entry: dict[str, Any] = json.loads(line)- except (json.JSONDecodeError, ValueError):- continue-- ts_str = entry.get("timestamp")- if not ts_str:- continue- try:- from datetime import datetime-- dt = datetime.fromisoformat(str(ts_str).replace("Z", "+00:00"))- ts = dt.timestamp()- except (ValueError, TypeError):- continue-- if ts < start_ts or ts >= end_ts:- continue-- msg = entry.get("message") or {}- usage = msg.get("usage")- if not usage:- continue-- _add_usage_to_tokens(totals, usage)-- model_id: str | None = msg.get("model")- if model_id:- if model_id not in by_model:- by_model[model_id] = WindowTokens()- _add_usage_to_tokens(by_model[model_id], usage)- else:- _add_usage_to_tokens(unattributed, usage)-- # Compute Sonnet-normalised weighted equivalent- model_weights: dict[str, float] = {}- weighted = 0.0-- for model_id, model_tokens in by_model.items():- w = get_model_weight(model_id)- model_weights[model_id] = w- weighted += _total_token_count(model_tokens) * w-- weighted += _total_token_count(unattributed) * DEFAULT_MODEL_WEIGHT-- totals.weighted_token_equivalent = weighted- totals.by_model = {mid: _window_tokens_to_dict(mt) for mid, mt in by_model.items()}-- return totals---def _total_token_count(t: WindowTokens) -> int:- return t.input + t.output + t.cache_reads + t.cache_writes_total---def _window_tokens_to_dict(t: WindowTokens) -> dict[str, int]:- return {- "input": t.input,- "output": t.output,- "cache_reads": t.cache_reads,- "cache_writes_5m": t.cache_writes_5m,- "cache_writes_1h": t.cache_writes_1h,- "cache_writes_total": t.cache_writes_total,- }+"""Parse Claude Code transcript JSONL files for per-window token breakdowns.++Mirrors the approach in the ClaudeCacheTTLStatusLine TypeScript reference+implementation (session-tracking.ts). Reads ~/.claude/projects/**/*.jsonl+and aggregates token usage for entries whose timestamp falls within a window.++Model weights (Sonnet-normalised, empirical estimates):+ opus: 2.0× (higher rate-limit cost)+ sonnet: 1.0× (baseline)+ haiku: 0.5× (cheaper, lower rate-limit cost)++The weighted_token_equivalent lets callers detect surge pricing by comparing+it against the API-reported utilisation × window_limit.+"""++from __future__ import annotations++import json+import logging+import os+from pathlib import Path+from typing import Any++from headroom.subscription.models import WindowTokens++logger = logging.getLogger(__name__)++# Maximum bytes to read per transcript file (10 MB cap — generous, typical files <1 MB)+_MAX_FILE_BYTES = 10 * 1024 * 1024++# Sonnet-normalised model family weights+MODEL_FAMILY_WEIGHTS: dict[str, float] = {+ "opus": 2.0,+ "sonnet": 1.0,+ "haiku": 0.5,+}+DEFAULT_MODEL_WEIGHT: float = 1.0+++def _claude_config_dir() -> Path:+ base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")+ return Path(base)+++def get_model_weight(model_id: str) -> float:+ """Return the Sonnet-normalised weight for a model ID.++ Matches against known family names using a word-boundary check.+ Falls back to DEFAULT_MODEL_WEIGHT for unrecognised models.+ """+ lower = model_id.lower()+ import re++ for family, weight in MODEL_FAMILY_WEIGHTS.items():+ if re.search(rf"(?<![a-z]){family}(?![a-z])", lower):+ return weight+ return DEFAULT_MODEL_WEIGHT+++def find_transcript_files() -> list[Path]:+ """Return all .jsonl files under ~/.claude/projects."""+ projects = _claude_config_dir() / "projects"+ results: list[Path] = []+ _walk_jsonl(projects, results)+ return results+++def _walk_jsonl(directory: Path, results: list[Path]) -> None:+ try:+ entries = list(directory.iterdir())+ except (OSError, PermissionError):+ return+ for entry in entries:+ try:+ if entry.is_dir():+ _walk_jsonl(entry, results)+ elif entry.suffix == ".jsonl":+ results.append(entry)+ except OSError:+ continue+++def _read_transcript_lines(path: Path) -> list[str]:+ try:+ size = path.stat().st_size+ read_size = min(size, _MAX_FILE_BYTES)+ with path.open("rb") as fh:+ raw = fh.read(read_size)+ return [line for line in raw.decode("utf-8", errors="replace").splitlines() if line.strip()]+ except Exception:+ return []+++def _add_usage_to_tokens(dest: WindowTokens, usage: dict[str, Any]) -> None:+ dest.input += int(usage.get("input_tokens") or 0)+ dest.output += int(usage.get("output_tokens") or 0)+ dest.cache_reads += int(usage.get("cache_read_input_tokens") or 0)++ cache_creation = usage.get("cache_creation") or {}+ w5m = int(cache_creation.get("ephemeral_5m_input_tokens") or 0)+ w1h = int(cache_creation.get("ephemeral_1h_input_tokens") or 0)+ total_writes = int(usage.get("cache_creation_input_tokens") or (w5m + w1h))++ dest.cache_writes_5m += w5m+ dest.cache_writes_1h += w1h+ dest.cache_writes_total += total_writes+++def compute_window_tokens(start_ts: float, end_ts: float) -> WindowTokens:+ """Sum transcript token usage for entries in [start_ts, end_ts).++ Args:+ start_ts: Window start as a Unix timestamp (seconds).+ end_ts: Window end as a Unix timestamp (seconds).++ Returns:+ :class:`WindowTokens` with aggregate + per-model breakdown and+ ``weighted_token_equivalent`` (Sonnet-normalised).+ """+ totals = WindowTokens()+ by_model: dict[str, WindowTokens] = {}+ unattributed = WindowTokens()++ for path in find_transcript_files():+ for line in _read_transcript_lines(path):+ try:+ entry: dict[str, Any] = json.loads(line)+ except (json.JSONDecodeError, ValueError):+ continue++ ts_str = entry.get("timestamp")+ if not ts_str:+ continue+ try:+ from datetime import datetime++ dt = datetime.fromisoformat(str(ts_str).replace("Z", "+00:00"))+ ts = dt.timestamp()+ except (ValueError, TypeError):+ continue++ if ts < start_ts or ts >= end_ts:+ continue++ msg = entry.get("message") or {}+ usage = msg.get("usage")+ if not usage:+ continue++ _add_usage_to_tokens(totals, usage)++ model_id: str | None = msg.get("model")+ if model_id:+ if model_id not in by_model:+ by_model[model_id] = WindowTokens()+ _add_usage_to_tokens(by_model[model_id], usage)+ else:+ _add_usage_to_tokens(unattributed, usage)++ # Compute Sonnet-normalised weighted equivalent+ model_weights: dict[str, float] = {}+ weighted = 0.0++ for model_id, model_tokens in by_model.items():+ w = get_model_weight(model_id)+ model_weights[model_id] = w+ weighted += _total_token_count(model_tokens) * w++ weighted += _total_token_count(unattributed) * DEFAULT_MODEL_WEIGHT++ totals.weighted_token_equivalent = weighted+ totals.by_model = {mid: _window_tokens_to_dict(mt) for mid, mt in by_model.items()}++ return totals+++def _total_token_count(t: WindowTokens) -> int:+ return t.input + t.output + t.cache_reads + t.cache_writes_total+++def _window_tokens_to_dict(t: WindowTokens) -> dict[str, int]:+ return {+ "input": t.input,+ "output": t.output,+ "cache_reads": t.cache_reads,+ "cache_writes_5m": t.cache_writes_5m,+ "cache_writes_1h": t.cache_writes_1h,+ "cache_writes_total": t.cache_writes_total,+ }diff --git a/headroom/subscription/tracker.py b/headroom/subscription/tracker.pyindex 70e5e9467..3eae0bb53 100644--- a/headroom/subscription/tracker.py+++ b/headroom/subscription/tracker.py@@ -1,464 +1,464 @@-"""Background subscription window tracker for Anthropic OAuth accounts.--Polls GET https://api.anthropic.com/api/oauth/usage on a configurable interval-while there has been at least one active OAuth session within the last minute.-Falls back to a stored token from ~/.claude/.credentials.json when no live-request has come through the proxy recently.--Architecture:-- Single asyncio.Task polling loop (started in start(), stopped via asyncio.Event)-- Thread-safe state updates via threading.Lock (consistent with headroom patterns)-- Atomic JSON persistence via tempfile + os.replace()-- Module-level singleton via get_subscription_tracker() / configure_subscription_tracker()--Also reads Claude transcript JSONL files (via session_tracking module) to provide-token breakdowns per window that enable:- - Headroom efficiency metrics (tokens saved = raw - what proxy sent)- - Surge pricing detection (API utilization vs expected from weighted tokens)- - Cache miss detection (low cache_reads despite high input tokens)-"""--from __future__ import annotations--import asyncio-import json-import logging-import os-import tempfile-import threading-from pathlib import Path-from typing import Any--from headroom import paths as _paths-from headroom.subscription.base import QuotaTracker-from headroom.subscription.client import SubscriptionClient-from headroom.subscription.models import (- HeadroomContribution,- SubscriptionSnapshot,- SubscriptionState,- WindowDiscrepancy,- WindowTokens,- _utc_now,-)--logger = logging.getLogger(__name__)--_DEFAULT_POLL_INTERVAL_S = 300-_DEFAULT_ACTIVE_WINDOW_S = 60-_PERSIST_FILE_ENV = _paths.HEADROOM_SUBSCRIPTION_STATE_PATH_ENV-_DEFAULT_PERSIST_DIR = ".headroom"-_DEFAULT_PERSIST_FILE = "subscription_state.json"--# Surge pricing threshold: if actual utilization is >N% higher than expected,-# flag it as a potential surge pricing event.-_SURGE_THRESHOLD_PCT = 15.0--# Cache miss threshold: if cache_reads < N% of total input when we expect-# heavy caching (>50k input tokens in window), flag it.-_CACHE_MISS_RATIO_THRESHOLD = 0.10---def _get_persist_path() -> Path:- return _paths.subscription_state_path()---class SubscriptionTracker(QuotaTracker):- """Background tracker for Anthropic Claude Code subscription windows.-- Implements :class:`~headroom.subscription.base.QuotaTracker` so it can- be registered with :func:`~headroom.subscription.base.get_quota_registry`- alongside the Codex and Copilot trackers.-- Args:- poll_interval_s: Seconds between polls while active (1–3600, default 300).- active_window_s: Seconds since last notify_active call that keeps- polling alive (default 60 = 1 minute).- enabled: Set to ``False`` to disable tracking (mirrors- ``ProxyConfig.subscription_tracking_enabled``).- persist_path: Where to persist state across restarts.- client: Injected client (for testing); defaults to SubscriptionClient().- """-- # QuotaTracker identity- key = "subscription_window"- label = "Anthropic Claude Code"-- def __init__(- self,- poll_interval_s: int = _DEFAULT_POLL_INTERVAL_S,- active_window_s: float = _DEFAULT_ACTIVE_WINDOW_S,- enabled: bool = True,- persist_path: Path | None = None,- client: SubscriptionClient | None = None,- ) -> None:- self._enabled = enabled- self._poll_interval_s = max(1, min(poll_interval_s, 3600))- self._active_window_s = max(5.0, active_window_s)- self._persist_path = persist_path or _get_persist_path()- self._client = client or SubscriptionClient()-- self._lock = threading.Lock()- self._state = SubscriptionState()- self._current_token: str | None = None- self._full_tokens: dict[str, int] = {} # token_prefix -> count of requests-- self._stop_event: asyncio.Event | None = None- self._poll_task: asyncio.Task[None] | None = None-- self._load_persisted_state()-- # ------------------------------------------------------------------- # QuotaTracker interface- # -------------------------------------------------------------------- def is_available(self) -> bool:- """Returns ``True`` when subscription tracking is enabled in config."""- return self._enabled-- def get_stats(self) -> dict[str, Any] | None:- """Return current tracker state dict for ``/stats``."""- return self.state-- # ------------------------------------------------------------------- # Lifecycle- # -------------------------------------------------------------------- async def start(self) -> None:- """Start the background polling loop."""- if self._poll_task and not self._poll_task.done():- return- self._stop_event = asyncio.Event()- self._poll_task = asyncio.create_task(self._poll_loop(), name="subscription-tracker")- logger.info("Subscription tracker started (poll_interval=%ds)", self._poll_interval_s)-- async def stop(self) -> None:- """Stop the background polling loop and persist current state."""- if self._stop_event:- self._stop_event.set()- if self._poll_task:- try:- await asyncio.wait_for(self._poll_task, timeout=5.0)- except (asyncio.TimeoutError, asyncio.CancelledError):- self._poll_task.cancel()- self._persist_state()- logger.info("Subscription tracker stopped")-- # ------------------------------------------------------------------- # Proxy integration hooks- # -------------------------------------------------------------------- def notify_active(self, token: str) -> None:- """Called by the proxy handler when an OAuth request comes through.-- Stores the token for polling and marks the tracker as recently active.- Only processes Bearer tokens that look like OAuth (not API keys).- """- if not token or not token.startswith("Bearer "):- return- raw = token[len("Bearer ") :]- # Skip raw API keys (not OAuth tokens)- if raw.startswith("sk-ant-api"):- return- with self._lock:- self._current_token = raw- self._state.last_active_at = _utc_now()- prefix = raw[:8]- self._full_tokens[prefix] = self._full_tokens.get(prefix, 0) + 1-- def update_contribution(- self,- *,- tokens_submitted: int = 0,- tokens_saved_compression: int = 0,- tokens_saved_rtk: int = 0,- tokens_saved_cache_reads: int = 0,- compression_savings_usd: float = 0.0,- cache_savings_usd: float = 0.0,- ) -> None:- """Update headroom contribution counters for the current session window.-- Called after each proxy request completes with the actual token deltas.- """- with self._lock:- c = self._state.contribution- 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_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)-- # ------------------------------------------------------------------- # State access- # -------------------------------------------------------------------- @property- def state(self) -> dict[str, Any]:- """Return current tracker state as a serialisable dict."""- with self._lock:- return self._state.to_dict()-- @property- def latest_snapshot(self) -> SubscriptionSnapshot | None:- with self._lock:- return self._state.latest-- def is_active(self) -> bool:- with self._lock:- return self._state.is_active(active_window_s=self._active_window_s)-- # ------------------------------------------------------------------- # Poll loop- # -------------------------------------------------------------------- async def _poll_loop(self) -> None:- assert self._stop_event is not None- while not self._stop_event.is_set():- try:- await self._maybe_poll()- except Exception as exc:- logger.warning("Subscription tracker poll error: %s", exc)- try:- # NOTE: do NOT wrap in asyncio.shield() — shield prevents the- # inner Event.wait() from being cancelled when wait_for times- # out, leaking one Task per poll interval. Over hours the- # accumulated idle waiters bog down the event loop scheduler- # (observed as the "aged proxy degradation" in 2026-04-17).- await asyncio.wait_for(- self._stop_event.wait(),- timeout=self._poll_interval_s,- )- break # stop event was set- except asyncio.TimeoutError:- pass # normal: poll interval elapsed-- async def _maybe_poll(self) -> None:- with self._lock:- is_active = self._state.is_active(active_window_s=self._active_window_s)- token = self._current_token-- if not is_active:- # Try background poll using credentials file token- from headroom.subscription.client import read_cached_oauth_token-- bg_token = read_cached_oauth_token()- if not bg_token:- return- token = token or bg_token-- snapshot = await self._client.fetch(token)- if snapshot is None:- with self._lock:- self._state.mark_error("fetch returned None")- return-- # Read transcript-based window tokens- window_tokens = _compute_window_tokens_for_snapshot(snapshot)-- # Detect anomalies- discrepancies = _detect_discrepancies(snapshot, window_tokens)-- with self._lock:- self._state.add_snapshot(snapshot)- self._state.window_tokens = window_tokens- for d in discrepancies:- self._state.add_discrepancy(d)- self._state.last_error = None- # Reset contribution when 5h window rolls over- self._maybe_reset_contribution(snapshot)-- self._persist_state()- logger.debug(- "Subscription poll: 5h=%.1f%% 7d=%.1f%%",- snapshot.five_hour.utilization_pct,- snapshot.seven_day.utilization_pct,- )-- # Update OTEL metrics if configured- try:- from headroom.observability.metrics import get_otel_metrics-- get_otel_metrics().record_subscription_window(self._state.to_dict())- except Exception:- pass-- def _maybe_reset_contribution(self, snapshot: SubscriptionSnapshot) -> None:- """Reset contribution counters when the 5h window rolls over."""- prev = self._state.history[-2] if len(self._state.history) >= 2 else None- if prev is None:- return- prev_resets_at = prev.five_hour.resets_at- curr_resets_at = snapshot.five_hour.resets_at- if (- prev_resets_at is not None- and curr_resets_at is not None- and curr_resets_at != prev_resets_at- ):- logger.info("5h window rolled over; resetting headroom contribution counters")- self._state.contribution = HeadroomContribution()-- # ------------------------------------------------------------------- # Persistence- # -------------------------------------------------------------------- def _persist_state(self) -> None:- try:- self._persist_path.parent.mkdir(parents=True, exist_ok=True)- with self._lock:- data = self._state.to_persist_dict()- with tempfile.NamedTemporaryFile(- mode="w",- dir=self._persist_path.parent,- delete=False,- suffix=".tmp",- encoding="utf-8",- ) as fh:- json.dump(data, fh, indent=2)- tmp_path = fh.name- os.replace(tmp_path, self._persist_path)- except Exception as exc:- logger.debug("Failed to persist subscription state: %s", exc)-- def _load_persisted_state(self) -> None:- try:- with open(self._persist_path, encoding="utf-8") as fh:- raw = json.load(fh)- # Restore only the contribution counters and poll counts for now;- # snapshot data is re-fetched on first active poll.- contrib = raw.get("contribution", {})- c = self._state.contribution- c.tokens_submitted = int(contrib.get("tokens_submitted", 0))- saved = contrib.get("tokens_saved", {})- c.tokens_saved_compression = int(saved.get("compression", 0))- c.tokens_saved_rtk = int(saved.get("rtk", 0))- c.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))- c.cache_savings_usd = float(savings_usd.get("cache", 0.0))- self._state.poll_count = int(raw.get("poll_count", 0))- logger.debug("Loaded persisted subscription state from %s", self._persist_path)- except FileNotFoundError:- pass- except Exception as exc:- logger.debug("Could not load persisted subscription state: %s", exc)---# ----------------------------------------------------------------------------# Transcript-based window token computation-# ------------------------------------------------------------------------------def _compute_window_tokens_for_snapshot(snapshot: SubscriptionSnapshot) -> WindowTokens:- """Read Claude transcript files and sum tokens for the current 5h window."""- try:- from headroom.subscription import session_tracking-- resets_at = snapshot.five_hour.resets_at- if resets_at is None:- return WindowTokens()- window_duration_s = 5 * 3600 # 5-hour window- start_ts = resets_at.timestamp() - window_duration_s- end_ts = resets_at.timestamp()- return session_tracking.compute_window_tokens(start_ts, end_ts)- except Exception as exc:- logger.debug("Could not compute window tokens from transcripts: %s", exc)- return WindowTokens()---# ----------------------------------------------------------------------------# Anomaly detection-# ------------------------------------------------------------------------------def _detect_discrepancies(- snapshot: SubscriptionSnapshot,- window_tokens: WindowTokens,-) -> list[WindowDiscrepancy]:- """Detect surge pricing or cache miss anomalies in the snapshot."""- discrepancies: list[WindowDiscrepancy] = []-- if snapshot.five_hour.limit > 0 and window_tokens.weighted_token_equivalent > 0:- expected_pct = window_tokens.weighted_token_equivalent / snapshot.five_hour.limit * 100.0- actual_pct = snapshot.five_hour.utilization_pct- delta = actual_pct - expected_pct-- if delta > _SURGE_THRESHOLD_PCT:- discrepancies.append(- WindowDiscrepancy(- kind="surge_pricing",- description=(- f"API 5h utilization ({actual_pct:.1f}%) is "- f"{delta:.1f}% higher than transcript-implied "- f"({expected_pct:.1f}%); possible surge weighting."- ),- severity="warning" if delta < 30 else "alert",- expected_utilization_pct=round(expected_pct, 2),- actual_utilization_pct=round(actual_pct, 2),- delta_pct=round(delta, 2),- )- )-- total_input = window_tokens.input- total_cache_reads = window_tokens.cache_reads- if total_input > 50_000 and total_cache_reads < total_input * _CACHE_MISS_RATIO_THRESHOLD:- cache_ratio = total_cache_reads / total_input if total_input else 0- discrepancies.append(- WindowDiscrepancy(- kind="cache_miss",- description=(- f"Cache-read ratio is {cache_ratio:.1%} (threshold "- f"{_CACHE_MISS_RATIO_THRESHOLD:.0%}); system may not be "- "using prefix cache effectively."- ),- severity="warning",- expected_utilization_pct=None,- actual_utilization_pct=None,- delta_pct=None,- )- )-- return discrepancies---# ----------------------------------------------------------------------------# Module-level singleton-# -----------------------------------------------------------------------------_tracker_lock = threading.Lock()-_tracker_instance: SubscriptionTracker | None = None---def get_subscription_tracker() -> SubscriptionTracker | None:- """Return the global singleton tracker, or None if not configured."""- return _tracker_instance---def configure_subscription_tracker(- poll_interval_s: int = _DEFAULT_POLL_INTERVAL_S,- active_window_s: float = _DEFAULT_ACTIVE_WINDOW_S,- enabled: bool = True,- persist_path: Path | None = None,- client: SubscriptionClient | None = None,-) -> SubscriptionTracker:- """Create (or return existing) global tracker singleton."""- global _tracker_instance- with _tracker_lock:- if _tracker_instance is None:- _tracker_instance = SubscriptionTracker(- poll_interval_s=poll_interval_s,- active_window_s=active_window_s,- enabled=enabled,- persist_path=persist_path,- client=client,- )- return _tracker_instance---async def shutdown_subscription_tracker() -> None:- """Stop and clean up the global tracker."""- global _tracker_instance- with _tracker_lock:- tracker = _tracker_instance- _tracker_instance = None- if tracker:- await tracker.stop()+"""Background subscription window tracker for Anthropic OAuth accounts.++Polls GET https://api.anthropic.com/api/oauth/usage on a configurable interval+while there has been at least one active OAuth session within the last minute.+Falls back to a stored token from ~/.claude/.credentials.json when no live+request has come through the proxy recently.++Architecture:+- Single asyncio.Task polling loop (started in start(), stopped via asyncio.Event)+- Thread-safe state updates via threading.Lock (consistent with headroom patterns)+- Atomic JSON persistence via tempfile + os.replace()+- Module-level singleton via get_subscription_tracker() / configure_subscription_tracker()++Also reads Claude transcript JSONL files (via session_tracking module) to provide+token breakdowns per window that enable:+ - Headroom efficiency metrics (tokens saved = raw - what proxy sent)+ - Surge pricing detection (API utilization vs expected from weighted tokens)+ - Cache miss detection (low cache_reads despite high input tokens)+"""++from __future__ import annotations++import asyncio+import json+import logging+import os+import tempfile+import threading+from pathlib import Path+from typing import Any++from headroom import paths as _paths+from headroom.subscription.base import QuotaTracker+from headroom.subscription.client import SubscriptionClient+from headroom.subscription.models import (+ HeadroomContribution,+ SubscriptionSnapshot,+ SubscriptionState,+ WindowDiscrepancy,+ WindowTokens,+ _utc_now,+)++logger = logging.getLogger(__name__)++_DEFAULT_POLL_INTERVAL_S = 300+_DEFAULT_ACTIVE_WINDOW_S = 60+_PERSIST_FILE_ENV = _paths.HEADROOM_SUBSCRIPTION_STATE_PATH_ENV+_DEFAULT_PERSIST_DIR = ".headroom"+_DEFAULT_PERSIST_FILE = "subscription_state.json"++# Surge pricing threshold: if actual utilization is >N% higher than expected,+# flag it as a potential surge pricing event.+_SURGE_THRESHOLD_PCT = 15.0++# Cache miss threshold: if cache_reads < N% of total input when we expect+# heavy caching (>50k input tokens in window), flag it.+_CACHE_MISS_RATIO_THRESHOLD = 0.10+++def _get_persist_path() -> Path:+ return _paths.subscription_state_path()+++class SubscriptionTracker(QuotaTracker):+ """Background tracker for Anthropic Claude Code subscription windows.++ Implements :class:`~headroom.subscription.base.QuotaTracker` so it can+ be registered with :func:`~headroom.subscription.base.get_quota_registry`+ alongside the Codex and Copilot trackers.++ Args:+ poll_interval_s: Seconds between polls while active (1–3600, default 300).+ active_window_s: Seconds since last notify_active call that keeps+ polling alive (default 60 = 1 minute).+ enabled: Set to ``False`` to disable tracking (mirrors+ ``ProxyConfig.subscription_tracking_enabled``).+ persist_path: Where to persist state across restarts.+ client: Injected client (for testing); defaults to SubscriptionClient().+ """++ # QuotaTracker identity+ key = "subscription_window"+ label = "Anthropic Claude Code"++ def __init__(+ self,+ poll_interval_s: int = _DEFAULT_POLL_INTERVAL_S,+ active_window_s: float = _DEFAULT_ACTIVE_WINDOW_S,+ enabled: bool = True,+ persist_path: Path | None = None,+ client: SubscriptionClient | None = None,+ ) -> None:+ self._enabled = enabled+ self._poll_interval_s = max(1, min(poll_interval_s, 3600))+ self._active_window_s = max(5.0, active_window_s)+ self._persist_path = persist_path or _get_persist_path()+ self._client = client or SubscriptionClient()++ self._lock = threading.Lock()+ self._state = SubscriptionState()+ self._current_token: str | None = None+ self._full_tokens: dict[str, int] = {} # token_prefix -> count of requests++ self._stop_event: asyncio.Event | None = None+ self._poll_task: asyncio.Task[None] | None = None++ self._load_persisted_state()++ # ------------------------------------------------------------------+ # QuotaTracker interface+ # ------------------------------------------------------------------++ def is_available(self) -> bool:+ """Returns ``True`` when subscription tracking is enabled in config."""+ return self._enabled++ def get_stats(self) -> dict[str, Any] | None:+ """Return current tracker state dict for ``/stats``."""+ return self.state++ # ------------------------------------------------------------------+ # Lifecycle+ # ------------------------------------------------------------------++ async def start(self) -> None:+ """Start the background polling loop."""+ if self._poll_task and not self._poll_task.done():+ return+ self._stop_event = asyncio.Event()+ self._poll_task = asyncio.create_task(self._poll_loop(), name="subscription-tracker")+ logger.info("Subscription tracker started (poll_interval=%ds)", self._poll_interval_s)++ async def stop(self) -> None:+ """Stop the background polling loop and persist current state."""+ if self._stop_event:+ self._stop_event.set()+ if self._poll_task:+ try:+ await asyncio.wait_for(self._poll_task, timeout=5.0)+ except (asyncio.TimeoutError, asyncio.CancelledError):+ self._poll_task.cancel()+ self._persist_state()+ logger.info("Subscription tracker stopped")++ # ------------------------------------------------------------------+ # Proxy integration hooks+ # ------------------------------------------------------------------++ def notify_active(self, token: str) -> None:+ """Called by the proxy handler when an OAuth request comes through.++ Stores the token for polling and marks the tracker as recently active.+ Only processes Bearer tokens that look like OAuth (not API keys).+ """+ if not token or not token.startswith("Bearer "):+ return+ raw = token[len("Bearer ") :]+ # Skip raw API keys (not OAuth tokens)+ if raw.startswith("sk-ant-api"):+ return+ with self._lock:+ self._current_token = raw+ self._state.last_active_at = _utc_now()+ prefix = raw[:8]+ self._full_tokens[prefix] = self._full_tokens.get(prefix, 0) + 1++ def update_contribution(+ self,+ *,+ tokens_submitted: int = 0,+ tokens_saved_compression: int = 0,+ tokens_saved_rtk: int = 0,+ tokens_saved_cache_reads: int = 0,+ compression_savings_usd: float = 0.0,+ cache_savings_usd: float = 0.0,+ ) -> None:+ """Update headroom contribution counters for the current session window.++ Called after each proxy request completes with the actual token deltas.+ """+ with self._lock:+ c = self._state.contribution+ 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_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)++ # ------------------------------------------------------------------+ # State access+ # ------------------------------------------------------------------++ @property+ def state(self) -> dict[str, Any]:+ """Return current tracker state as a serialisable dict."""+ with self._lock:+ return self._state.to_dict()++ @property+ def latest_snapshot(self) -> SubscriptionSnapshot | None:+ with self._lock:+ return self._state.latest++ def is_active(self) -> bool:+ with self._lock:+ return self._state.is_active(active_window_s=self._active_window_s)++ # ------------------------------------------------------------------+ # Poll loop+ # ------------------------------------------------------------------++ async def _poll_loop(self) -> None:+ assert self._stop_event is not None+ while not self._stop_event.is_set():+ try:+ await self._maybe_poll()+ except Exception as exc:+ logger.warning("Subscription tracker poll error: %s", exc)+ try:+ # NOTE: do NOT wrap in asyncio.shield() — shield prevents the+ # inner Event.wait() from being cancelled when wait_for times+ # out, leaking one Task per poll interval. Over hours the+ # accumulated idle waiters bog down the event loop scheduler+ # (observed as the "aged proxy degradation" in 2026-04-17).+ await asyncio.wait_for(+ self._stop_event.wait(),+ timeout=self._poll_interval_s,+ )+ break # stop event was set+ except asyncio.TimeoutError:+ pass # normal: poll interval elapsed++ async def _maybe_poll(self) -> None:+ with self._lock:+ is_active = self._state.is_active(active_window_s=self._active_window_s)+ token = self._current_token++ if not is_active:+ # Try background poll using credentials file token+ from headroom.subscription.client import read_cached_oauth_token++ bg_token = read_cached_oauth_token()+ if not bg_token:+ return+ token = token or bg_token++ snapshot = await self._client.fetch(token)+ if snapshot is None:+ with self._lock:+ self._state.mark_error("fetch returned None")+ return++ # Read transcript-based window tokens+ window_tokens = _compute_window_tokens_for_snapshot(snapshot)++ # Detect anomalies+ discrepancies = _detect_discrepancies(snapshot, window_tokens)++ with self._lock:+ self._state.add_snapshot(snapshot)+ self._state.window_tokens = window_tokens+ for d in discrepancies:+ self._state.add_discrepancy(d)+ self._state.last_error = None+ # Reset contribution when 5h window rolls over+ self._maybe_reset_contribution(snapshot)++ self._persist_state()+ logger.debug(+ "Subscription poll: 5h=%.1f%% 7d=%.1f%%",+ snapshot.five_hour.utilization_pct,+ snapshot.seven_day.utilization_pct,+ )++ # Update OTEL metrics if configured+ try:+ from headroom.observability.metrics import get_otel_metrics++ get_otel_metrics().record_subscription_window(self._state.to_dict())+ except Exception:+ pass++ def _maybe_reset_contribution(self, snapshot: SubscriptionSnapshot) -> None:+ """Reset contribution counters when the 5h window rolls over."""+ prev = self._state.history[-2] if len(self._state.history) >= 2 else None+ if prev is None:+ return+ prev_resets_at = prev.five_hour.resets_at+ curr_resets_at = snapshot.five_hour.resets_at+ if (+ prev_resets_at is not None+ and curr_resets_at is not None+ and curr_resets_at != prev_resets_at+ ):+ logger.info("5h window rolled over; resetting headroom contribution counters")+ self._state.contribution = HeadroomContribution()++ # ------------------------------------------------------------------+ # Persistence+ # ------------------------------------------------------------------++ def _persist_state(self) -> None:+ try:+ self._persist_path.parent.mkdir(parents=True, exist_ok=True)+ with self._lock:+ data = self._state.to_persist_dict()+ with tempfile.NamedTemporaryFile(+ mode="w",+ dir=self._persist_path.parent,+ delete=False,+ suffix=".tmp",+ encoding="utf-8",+ ) as fh:+ json.dump(data, fh, indent=2)+ tmp_path = fh.name+ os.replace(tmp_path, self._persist_path)+ except Exception as exc:+ logger.debug("Failed to persist subscription state: %s", exc)++ def _load_persisted_state(self) -> None:+ try:+ with open(self._persist_path, encoding="utf-8") as fh:+ raw = json.load(fh)+ # Restore only the contribution counters and poll counts for now;+ # snapshot data is re-fetched on first active poll.+ contrib = raw.get("contribution", {})+ c = self._state.contribution+ c.tokens_submitted = int(contrib.get("tokens_submitted", 0))+ saved = contrib.get("tokens_saved", {})+ c.tokens_saved_compression = int(saved.get("compression", 0))+ c.tokens_saved_rtk = int(saved.get("rtk", 0))+ c.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))+ c.cache_savings_usd = float(savings_usd.get("cache", 0.0))+ self._state.poll_count = int(raw.get("poll_count", 0))+ logger.debug("Loaded persisted subscription state from %s", self._persist_path)+ except FileNotFoundError:+ pass+ except Exception as exc:+ logger.debug("Could not load persisted subscription state: %s", exc)+++# ---------------------------------------------------------------------------+# Transcript-based window token computation+# ---------------------------------------------------------------------------+++def _compute_window_tokens_for_snapshot(snapshot: SubscriptionSnapshot) -> WindowTokens:+ """Read Claude transcript files and sum tokens for the current 5h window."""+ try:+ from headroom.subscription import session_tracking++ resets_at = snapshot.five_hour.resets_at+ if resets_at is None:+ return WindowTokens()+ window_duration_s = 5 * 3600 # 5-hour window+ start_ts = resets_at.timestamp() - window_duration_s+ end_ts = resets_at.timestamp()+ return session_tracking.compute_window_tokens(start_ts, end_ts)+ except Exception as exc:+ logger.debug("Could not compute window tokens from transcripts: %s", exc)+ return WindowTokens()+++# ---------------------------------------------------------------------------+# Anomaly detection+# ---------------------------------------------------------------------------+++def _detect_discrepancies(+ snapshot: SubscriptionSnapshot,+ window_tokens: WindowTokens,+) -> list[WindowDiscrepancy]:+ """Detect surge pricing or cache miss anomalies in the snapshot."""+ discrepancies: list[WindowDiscrepancy] = []++ if snapshot.five_hour.limit > 0 and window_tokens.weighted_token_equivalent > 0:+ expected_pct = window_tokens.weighted_token_equivalent / snapshot.five_hour.limit * 100.0+ actual_pct = snapshot.five_hour.utilization_pct+ delta = actual_pct - expected_pct++ if delta > _SURGE_THRESHOLD_PCT:+ discrepancies.append(+ WindowDiscrepancy(+ kind="surge_pricing",+ description=(+ f"API 5h utilization ({actual_pct:.1f}%) is "+ f"{delta:.1f}% higher than transcript-implied "+ f"({expected_pct:.1f}%); possible surge weighting."+ ),+ severity="warning" if delta < 30 else "alert",+ expected_utilization_pct=round(expected_pct, 2),+ actual_utilization_pct=round(actual_pct, 2),+ delta_pct=round(delta, 2),+ )+ )++ total_input = window_tokens.input+ total_cache_reads = window_tokens.cache_reads+ if total_input > 50_000 and total_cache_reads < total_input * _CACHE_MISS_RATIO_THRESHOLD:+ cache_ratio = total_cache_reads / total_input if total_input else 0+ discrepancies.append(+ WindowDiscrepancy(+ kind="cache_miss",+ description=(+ f"Cache-read ratio is {cache_ratio:.1%} (threshold "+ f"{_CACHE_MISS_RATIO_THRESHOLD:.0%}); system may not be "+ "using prefix cache effectively."+ ),+ severity="warning",+ expected_utilization_pct=None,+ actual_utilization_pct=None,+ delta_pct=None,+ )+ )++ return discrepancies+++# ---------------------------------------------------------------------------+# Module-level singleton+# ---------------------------------------------------------------------------++_tracker_lock = threading.Lock()+_tracker_instance: SubscriptionTracker | None = None+++def get_subscription_tracker() -> SubscriptionTracker | None:+ """Return the global singleton tracker, or None if not configured."""+ return _tracker_instance+++def configure_subscription_tracker(+ poll_interval_s: int = _DEFAULT_POLL_INTERVAL_S,+ active_window_s: float = _DEFAULT_ACTIVE_WINDOW_S,+ enabled: bool = True,+ persist_path: Path | None = None,+ client: SubscriptionClient | None = None,+) -> SubscriptionTracker:+ """Create (or return existing) global tracker singleton."""+ global _tracker_instance+ with _tracker_lock:+ if _tracker_instance is None:+ _tracker_instance = SubscriptionTracker(+ poll_interval_s=poll_interval_s,+ active_window_s=active_window_s,+ enabled=enabled,+ persist_path=persist_path,+ client=client,+ )+ return _tracker_instance+++async def shutdown_subscription_tracker() -> None:+ """Stop and clean up the global tracker."""+ global _tracker_instance+ with _tracker_lock:+ tracker = _tracker_instance+ _tracker_instance = None+ if tracker:+ await tracker.stop()diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 1c98f6cd5..8c264fc7c 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -1,2130 +1,2130 @@-"""Content router for intelligent compression strategy selection.--This module provides the ContentRouter, which analyzes content and routes it-to the optimal compressor. It handles mixed content by splitting, routing-each section to the appropriate compressor, and reassembling.--Supported Compressors:-- CodeAwareCompressor: Source code (AST-preserving)-- SmartCrusher: JSON arrays-- SearchCompressor: grep/ripgrep results-- LogCompressor: Build/test output-- KompressCompressor: Plain text (ML-based)-- Kompress: Plain text (ML-based, requires [ml] extra)--Routing Strategy:-1. Use source hint if available (highest confidence)-2. Check for mixed content (split and route sections)-3. Detect content type (JSON, code, search, logs, text)-4. Route to appropriate compressor-5. Reassemble and return with routing metadata--Usage:- >>> from headroom.transforms import ContentRouter- >>> router = ContentRouter()- >>> result = router.compress(content) # Auto-routes to best compressor- >>> print(result.strategy_used)- >>> print(result.routing_log)--Pipeline Usage:- >>> pipeline = TransformPipeline([- ... ContentRouter(), # Handles all content types- ... RollingWindow(), # Final size constraint- ... ])-"""--from __future__ import annotations--import hashlib-import logging-import os-import re-import time-from concurrent.futures import ThreadPoolExecutor-from dataclasses import dataclass, field-from enum import Enum-from typing import Any--from ..config import DEFAULT_EXCLUDE_TOOLS, ReadLifecycleConfig, TransformResult-from ..tokenizer import Tokenizer-from .base import Transform-from .content_detector import ContentType, DetectionResult, detect_content_type--logger = logging.getLogger(__name__)--_magika_detector: Any | None = None-_magika_status: bool | None = None---def _get_magika_detector() -> Any | None:- """Load the Magika detector only when router detection actually runs."""- global _magika_detector, _magika_status-- if _magika_status is False:- return None- if _magika_detector is not None:- return _magika_detector-- try:- from ..compression.detector import get_detector-- _magika_detector = get_detector(prefer_magika=True)- _magika_status = True- logger.info("ContentRouter: Using Magika ML-based content detection")- except ImportError:- _magika_status = False- logger.debug("Magika not available, using regex-based detection")-- return _magika_detector---def _detect_content(content: str) -> DetectionResult:- """Detect content type using Magika if available, else regex fallback."""- magika_detector = _get_magika_detector()- if magika_detector is not None:- result = magika_detector.detect(content)- # Map Magika ContentType to router's expected format- type_map = {- "json": ContentType.JSON_ARRAY,- "code": ContentType.SOURCE_CODE,- "log": ContentType.BUILD_OUTPUT,- "diff": ContentType.GIT_DIFF,- "markdown": ContentType.PLAIN_TEXT,- "text": ContentType.PLAIN_TEXT,- "unknown": ContentType.PLAIN_TEXT,- }- mapped_type = type_map.get(result.content_type.value, ContentType.PLAIN_TEXT)- return DetectionResult(- content_type=mapped_type,- confidence=result.confidence,- metadata={"language": result.language, "raw_label": result.raw_label},- )- else:- return detect_content_type(content)---def _create_content_signature(- content_type: str,- content: str,- language: str | None = None,-) -> Any:- """Create a ToolSignature for non-JSON content types.-- This allows TOIN to track compression patterns for code, search results,- logs, and text - not just JSON arrays.-- Args:- content_type: The type of content (e.g., "code_aware", "search", "log", "text").- content: The content being compressed (for structural hints).- language: Optional language hint for code.-- Returns:- A ToolSignature for TOIN tracking.- """- try:- from ..telemetry.models import ToolSignature-- # Create a deterministic structure hash based on content type- # This groups similar content types together for pattern learning- if language:- hash_input = f"content:{content_type}:{language}"- else:- hash_input = f"content:{content_type}"-- # Add a structural hint from the content (first 100 chars, hashed)- # This helps differentiate tool outputs of the same type- content_sample = content[:100] if content else ""- structure_hint = hashlib.sha256(content_sample.encode()).hexdigest()[:8]- hash_input = f"{hash_input}:{structure_hint}"-- # Keep SHA256: structure_hash feeds into TOIN which persists to disk.- # Changing hash function would invalidate all learned patterns.- structure_hash = hashlib.sha256(hash_input.encode()).hexdigest()[:24]-- return ToolSignature(- structure_hash=structure_hash,- field_count=0, # Not applicable for non-JSON- has_nested_objects=False,- has_arrays=False,- max_depth=0,- )- except ImportError:- return None---class CompressionCache:- """Two-tier compression cache with TTL.-- Tier 1 (skip set): content hashes that won't compress — instant skip,- near-zero memory (just ints in a set).-- Tier 2 (result cache): compressed results for content that DID compress —- reuse the compressed text on subsequent requests.-- Entries expire after TTL (default 30min). No max-entries cap — TTL is the- natural bound. Memory grows proportional to compressible content × TTL,- which is bounded by session duration.-- Uses in-process dict for ultra-fast lookups (~100ns). Could be backed- by memcached/Redis for multi-process deployments.- """-- def __init__(self, ttl_seconds: int = 1800):- # Tier 2: compressed results {hash: (text, ratio, strategy, timestamp)}- self._results: dict[int, tuple[str, float, str, float]] = {}- # Tier 1: hashes of content that won't compress {hash: timestamp}- self._skip: dict[int, float] = {}- self._ttl_seconds = ttl_seconds- # Metrics- self._hits = 0- self._misses = 0- self._skip_hits = 0- self._evictions = 0- self._total_lookup_ns = 0- self._lookup_count = 0-- def get(self, key: int) -> tuple[str, float, str] | None:- """Get cached compression result.-- Returns (compressed_text, ratio, strategy) or None if not found/expired.- Use is_skipped() first to check if content is known non-compressible.- """- t0 = time.perf_counter_ns()- entry = self._results.get(key)- if entry is not None:- compressed, ratio, strategy, created_at = entry- if (time.time() - created_at) < self._ttl_seconds:- self._hits += 1- self._total_lookup_ns += time.perf_counter_ns() - t0- self._lookup_count += 1- return (compressed, ratio, strategy)- else:- del self._results[key]- self._evictions += 1- self._misses += 1- self._total_lookup_ns += time.perf_counter_ns() - t0- self._lookup_count += 1- return None-- def is_skipped(self, key: int) -> bool:- """Check if content is known non-compressible (Tier 1)."""- ts = self._skip.get(key)- if ts is not None:- if (time.time() - ts) < self._ttl_seconds:- self._skip_hits += 1- return True- else:- del self._skip[key]- self._evictions += 1- return False-- def put(self, key: int, compressed: str, ratio: float, strategy: str) -> None:- """Store a compressed result (Tier 2)."""- self._results[key] = (compressed, ratio, strategy, time.time())-- def mark_skip(self, key: int) -> None:- """Mark content as non-compressible (Tier 1)."""- self._skip[key] = time.time()-- def move_to_skip(self, key: int) -> None:- """Move a result to skip set (threshold tightened, no longer qualifies)."""- self._results.pop(key, None)- self._skip[key] = time.time()-- @property- def size(self) -> int:- return len(self._results)-- @property- def skip_size(self) -> int:- return len(self._skip)-- @property- def stats(self) -> dict[str, int | float]:- avg_ns = self._total_lookup_ns / self._lookup_count if self._lookup_count else 0- return {- "cache_hits": self._hits,- "cache_skip_hits": self._skip_hits,- "cache_misses": self._misses,- "cache_evictions": self._evictions,- "cache_size": len(self._results),- "cache_skip_size": len(self._skip),- "cache_avg_lookup_ns": avg_ns,- }-- def clear(self) -> None:- """Clear all entries (e.g., on session end)."""- self._results.clear()- self._skip.clear()---class CompressionStrategy(Enum):- """Available compression strategies."""-- CODE_AWARE = "code_aware"- SMART_CRUSHER = "smart_crusher"- SEARCH = "search"- LOG = "log"- KOMPRESS = "kompress"- TEXT = "text"- DIFF = "diff"- HTML = "html"- MIXED = "mixed"- PASSTHROUGH = "passthrough"---@dataclass-class RoutingDecision:- """Record of a single routing decision."""-- content_type: ContentType- strategy: CompressionStrategy- original_tokens: int- compressed_tokens: int- confidence: float = 1.0- section_index: int = 0-- @property- def compression_ratio(self) -> float:- if self.original_tokens == 0:- return 1.0- return self.compressed_tokens / self.original_tokens---@dataclass-class ContentSection:- """A typed section of content."""-- content: str- content_type: ContentType- language: str | None = None- start_line: int = 0- end_line: int = 0- is_code_fence: bool = False---@dataclass-class RouterCompressionResult:- """Result from ContentRouter with routing metadata.-- Attributes:- compressed: The compressed content.- original: Original content before compression.- strategy_used: Primary strategy used for compression.- routing_log: List of routing decisions made.- sections_processed: Number of content sections processed.- """-- compressed: str- original: str- strategy_used: CompressionStrategy- routing_log: list[RoutingDecision] = field(default_factory=list)- sections_processed: int = 1-- @property- def total_original_tokens(self) -> int:- """Total tokens before compression."""- return sum(r.original_tokens for r in self.routing_log)-- @property- def total_compressed_tokens(self) -> int:- """Total tokens after compression."""- return sum(r.compressed_tokens for r in self.routing_log)-- @property- def compression_ratio(self) -> float:- """Overall compression ratio."""- if self.total_original_tokens == 0:- return 1.0- return self.total_compressed_tokens / self.total_original_tokens-- @property- def tokens_saved(self) -> int:- """Number of tokens saved."""- return max(0, self.total_original_tokens - self.total_compressed_tokens)-- @property- def savings_percentage(self) -> float:- """Percentage of tokens saved."""- if self.total_original_tokens == 0:- return 0.0- return (self.tokens_saved / self.total_original_tokens) * 100-- def summary(self) -> str:- """Human-readable routing summary."""- if self.strategy_used == CompressionStrategy.MIXED:- strategies = {r.strategy.value for r in self.routing_log}- return (- f"Mixed content: {self.sections_processed} sections, "- f"routed to {strategies}. "- f"{self.total_original_tokens:,}→{self.total_compressed_tokens:,} tokens "- f"({self.savings_percentage:.0f}% saved)"- )- else:- return (- f"Pure {self.strategy_used.value}: "- f"{self.total_original_tokens:,}→{self.total_compressed_tokens:,} tokens "- f"({self.savings_percentage:.0f}% saved)"- )---@dataclass-class ContentRouterConfig:- """Configuration for intelligent content routing.-- Attributes:- enable_code_aware: Enable AST-based code compression.- enable_smart_crusher: Enable JSON array compression.- enable_search_compressor: Enable search result compression.- enable_log_compressor: Enable build/test log compression.- enable_image_optimizer: Enable image token optimization.- prefer_code_aware_for_code: Use CodeAware over Kompress for code.- mixed_content_threshold: Min distinct types to consider "mixed".- min_section_tokens: Minimum tokens for a section to compress.- fallback_strategy: Strategy when no compressor matches.- skip_user_messages: Never compress user messages (they're the subject).- skip_recent_messages: Don't compress last N messages (likely the subject).- protect_analysis_context: Detect "analyze/review" intent, skip compression.- """-- # Enable/disable specific compressors- enable_code_aware: bool = False # Disabled: use code graph MCP tools instead- enable_kompress: bool = True # Kompress: ModernBERT token compressor- enable_smart_crusher: bool = True- enable_search_compressor: bool = True- enable_log_compressor: bool = True- enable_html_extractor: bool = True # HTML content extraction- enable_image_optimizer: bool = True # Image token optimization-- # Routing preferences- prefer_code_aware_for_code: bool = False # Disabled: let code pass through unmangled- mixed_content_threshold: int = 2 # Min types to consider mixed- min_section_tokens: int = 20 # Min tokens to compress a section-- # Fallback: Kompress handles unknown/mixed content instead of passing through- fallback_strategy: CompressionStrategy = CompressionStrategy.KOMPRESS-- # Protection: Don't compress content that's likely the subject of analysis- skip_user_messages: bool = True # User messages contain what they want analyzed- protect_recent_code: int = 4 # Don't compress CODE in last N messages (0 = disabled)- protect_analysis_context: bool = True # Detect "analyze/review" intent, protect code-- # Adaptive Read protection: fraction of total messages to protect from- # compression. At 10 msgs, protects ~5 Reads. At 100 msgs, protects ~10.- # Old Reads beyond this window become compressible even though they are- # in DEFAULT_EXCLUDE_TOOLS. 0.0 = always exclude all (old behavior).- protect_recent_reads_fraction: float = (- 0.0 # 0.0 = protect ALL excluded-tool outputs (safest for coding agents)- )-- # Adaptive compression ratio: scales with context pressure.- # At low pressure (<30% full), use the relaxed threshold (reject marginal).- # At high pressure (>80% full), use the aggressive threshold (accept anything helpful).- # Linearly interpolates between the two.- min_ratio_relaxed: float = 0.85 # when context is mostly empty- min_ratio_aggressive: float = 0.65 # when context is nearly full-- # CCR (Compress-Cache-Retrieve) settings for SmartCrusher- ccr_enabled: bool = True # Enable CCR marker injection for reversible compression- ccr_inject_marker: bool = True # Add retrieval markers to compressed content-- # Tag protection: preserve custom/workflow XML tags from text compression.- # When False (default), entire <custom-tag>content</custom-tag> blocks are- # protected verbatim. When True, only the tag markers are protected and- # the content between them can be compressed.- compress_tagged_content: bool = False-- # Tools to exclude from compression (output passed through unmodified)- # Set to None to use DEFAULT_EXCLUDE_TOOLS, or provide custom set- exclude_tools: set[str] | None = None-- # Read lifecycle management (stale/superseded detection)- read_lifecycle: ReadLifecycleConfig = field(default_factory=ReadLifecycleConfig)-- # Per-tool compression profiles (tool_name → CompressionProfile)- # Set to None to use DEFAULT_TOOL_PROFILES from config- tool_profiles: dict[str, Any] | None = None---# Patterns for detecting mixed content-_CODE_FENCE_PATTERN = re.compile(r"^```(\w*)\s*$", re.MULTILINE)-_JSON_BLOCK_START = re.compile(r"^\s*[\[{]", re.MULTILINE)-_SEARCH_RESULT_PATTERN = re.compile(r"^\S+:\d+:", re.MULTILINE)-_PROSE_PATTERN = re.compile(r"[A-Z][a-z]+\s+\w+\s+\w+")---def is_mixed_content(content: str) -> bool:- """Detect if content contains multiple distinct types.-- Args:- content: Content to analyze.-- Returns:- True if content appears to be mixed (multiple types).- """- indicators = {- "has_code_fences": bool(_CODE_FENCE_PATTERN.search(content)),- "has_json_blocks": bool(_JSON_BLOCK_START.search(content)),- "has_prose": len(_PROSE_PATTERN.findall(content)) > 5,- "has_search_results": bool(_SEARCH_RESULT_PATTERN.search(content)),- }-- # Mixed if 2+ indicators are true- return sum(indicators.values()) >= 2---def split_into_sections(content: str) -> list[ContentSection]:- """Parse mixed content into typed sections.-- Args:- content: Mixed content to split.-- Returns:- List of ContentSection objects.- """- sections: list[ContentSection] = []- lines = content.split("\n")-- i = 0- while i < len(lines):- line = lines[i]-- # Code fence: ```language- if match := _CODE_FENCE_PATTERN.match(line):- language = match.group(1) or "unknown"- code_lines = []- start_line = i- i += 1-- while i < len(lines) and not lines[i].startswith("```"):- code_lines.append(lines[i])- i += 1-- sections.append(- ContentSection(- content="\n".join(code_lines),- content_type=ContentType.SOURCE_CODE,- language=language,- start_line=start_line,- end_line=i,- is_code_fence=True,- )- )- i += 1 # Skip closing ```- continue-- # JSON block- if line.strip().startswith(("[", "{")):- json_content, end_i = _extract_json_block(lines, i)- if json_content:- sections.append(- ContentSection(- content=json_content,- content_type=ContentType.JSON_ARRAY,- start_line=i,- end_line=end_i,- )- )- i = end_i + 1- continue-- # Search result lines- if _SEARCH_RESULT_PATTERN.match(line):- search_lines = []- start_line = i- while i < len(lines) and _SEARCH_RESULT_PATTERN.match(lines[i]):- search_lines.append(lines[i])- i += 1- sections.append(- ContentSection(- content="\n".join(search_lines),- content_type=ContentType.SEARCH_RESULTS,- start_line=start_line,- end_line=i - 1,- )- )- continue-- # Collect text until next special section- text_lines = [line]- start_line = i- i += 1-- while i < len(lines):- next_line = lines[i]- # Stop if we hit a special section- if (- _CODE_FENCE_PATTERN.match(next_line)- or next_line.strip().startswith(("[", "{"))- or _SEARCH_RESULT_PATTERN.match(next_line)- ):- break- text_lines.append(next_line)- i += 1-- # Only add non-empty text sections- text_content = "\n".join(text_lines)- if text_content.strip():- sections.append(- ContentSection(- content=text_content,- content_type=ContentType.PLAIN_TEXT,- start_line=start_line,- end_line=i - 1,- )- )-- return sections---def _extract_json_block(lines: list[str], start: int) -> tuple[str | None, int]:- """Extract a complete JSON block from lines.-- Args:- lines: All lines of content.- start: Starting line index.-- Returns:- Tuple of (json_content, end_line_index) or (None, start) if invalid.- """- bracket_count = 0- brace_count = 0- json_lines = []-- for i in range(start, len(lines)):- line = lines[i]- json_lines.append(line)-- bracket_count += line.count("[") - line.count("]")- brace_count += line.count("{") - line.count("}")-- if bracket_count <= 0 and brace_count <= 0 and json_lines:- return "\n".join(json_lines), i-- # Didn't find complete JSON- return None, start---class ContentRouter(Transform):- """Intelligent router that selects optimal compression strategy.-- ContentRouter is the recommended entry point for Headroom's compression.- It analyzes content and routes it to the most appropriate compressor,- handling mixed content by splitting and reassembling.-- Key Features:- - Automatic content type detection- - Source hint support for high-confidence routing- - Mixed content handling (split → route → reassemble)- - Graceful fallback when compressors unavailable- - Rich routing metadata for debugging-- Example:- >>> router = ContentRouter()- >>>- >>> # Automatically uses CodeAwareCompressor- >>> result = router.compress(python_code)- >>> print(result.strategy_used) # CompressionStrategy.CODE_AWARE- >>>- >>> # Automatically uses SmartCrusher- >>> result = router.compress(json_array)- >>> print(result.strategy_used) # CompressionStrategy.SMART_CRUSHER- >>>- >>> # Splits and routes each section- >>> result = router.compress(readme_with_code)- >>> print(result.strategy_used) # CompressionStrategy.MIXED-- Pipeline Integration:- >>> pipeline = TransformPipeline([- ... ContentRouter(), # Handles ALL content types- ... RollingWindow(), # Final size constraint- ... ])- """-- name: str = "content_router"-- def __init__(self, config: ContentRouterConfig | None = None):- """Initialize content router.-- Args:- config: Router configuration. Uses defaults if None.- """- self.config = config or ContentRouterConfig()-- # Lazy-loaded compressors- self._code_compressor: Any = None- self._smart_crusher: Any = None- self._search_compressor: Any = None- self._log_compressor: Any = None- self._diff_compressor: Any = None- self._html_extractor: Any = None- self._kompress: Any = None- self._image_optimizer: Any = None-- # TOIN integration for cross-strategy learning- self._toin: Any = None-- self._cache = CompressionCache()-- def _record_to_toin(- self,- strategy: CompressionStrategy,- content: str,- compressed: str,- original_tokens: int,- compressed_tokens: int,- language: str | None = None,- context: str = "",- ) -> None:- """Record compression to TOIN for cross-user learning.-- This allows TOIN to track compression patterns for ALL content types,- not just JSON arrays. When the LLM retrieves original content via CCR,- TOIN learns which compressions users need to expand.-- Args:- strategy: The compression strategy used.- content: Original content (for signature generation).- compressed: Compressed content.- original_tokens: Token count before compression.- compressed_tokens: Token count after compression.- language: Optional language hint for code.- context: Query context for pattern learning.- """- # Skip SmartCrusher - it handles its own TOIN recording- if strategy == CompressionStrategy.SMART_CRUSHER:- return-- # Skip if no actual compression happened- if original_tokens <= compressed_tokens:- return-- try:- # Lazy load TOIN- if self._toin is None:- from ..telemetry.toin import get_toin-- self._toin = get_toin()-- # Create a content-type signature- signature = _create_content_signature(- content_type=strategy.value,- content=content,- language=language,- )-- if signature is None:- return-- # Record the compression- self._toin.record_compression(- tool_signature=signature,- original_count=1, # Single content block- compressed_count=1,- original_tokens=original_tokens,- compressed_tokens=compressed_tokens,- strategy=strategy.value,- query_context=context if context else None,- )-- logger.debug(- "TOIN: Recorded %s compression: %d → %d tokens",- strategy.value,- original_tokens,- compressed_tokens,- )-- except Exception as e:- # TOIN recording should never break compression- logger.debug("TOIN recording failed (non-fatal): %s", e)-- def _timed_compress(- self, content: str, context: str, bias: float- ) -> tuple[RouterCompressionResult, float]:- """Compress with wall-clock timing. Used by parallel executor."""- t0 = time.perf_counter()- result = self.compress(content, context=context, bias=bias)- return result, (time.perf_counter() - t0) * 1000-- def compress(- self,- content: str,- context: str = "",- question: str | None = None,- bias: float = 1.0,- ) -> RouterCompressionResult:- """Compress content using optimal strategy based on content detection.-- Args:- content: Content to compress.- context: Optional context for relevance-aware compression.- question: Optional question for QA-aware compression. When provided,- tokens relevant to answering this question are preserved.- bias: Compression bias multiplier (>1 = keep more, <1 = keep fewer).-- Returns:- RouterCompressionResult with compressed content and routing metadata.- """- if not content or not content.strip():- return RouterCompressionResult(- compressed=content,- original=content,- strategy_used=CompressionStrategy.PASSTHROUGH,- routing_log=[],- )-- # Determine strategy from content analysis- strategy = self._determine_strategy(content)-- if strategy == CompressionStrategy.MIXED:- return self._compress_mixed(content, context, question, bias=bias)- else:- return self._compress_pure(content, strategy, context, question, bias=bias)-- def _determine_strategy(self, content: str) -> CompressionStrategy:- """Determine the compression strategy from content analysis.-- Args:- content: Content to analyze.-- Returns:- Selected compression strategy.- """- # 1. Check for mixed content- if is_mixed_content(content):- return CompressionStrategy.MIXED-- # 2. Detect content type from content itself- detection = _detect_content(content)- return self._strategy_from_detection(detection)-- def _strategy_from_detection(self, detection: Any) -> CompressionStrategy:- """Get strategy from content detection result.-- Args:- detection: Result from detect_content_type.-- Returns:- Selected strategy.- """- mapping = {- ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,- ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,- ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,- ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,- ContentType.GIT_DIFF: CompressionStrategy.DIFF,- ContentType.HTML: CompressionStrategy.HTML,- ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,- }-- strategy = mapping.get(detection.content_type, self.config.fallback_strategy)-- # Override: prefer CodeAware for code if configured- if (- strategy == CompressionStrategy.CODE_AWARE- and not self.config.prefer_code_aware_for_code- ):- strategy = CompressionStrategy.KOMPRESS-- return strategy-- def _compress_mixed(- self,- content: str,- context: str,- question: str | None = None,- bias: float = 1.0,- ) -> RouterCompressionResult:- """Compress mixed content by splitting and routing sections.-- Args:- content: Mixed content to compress.- context: User context for relevance.- question: Optional question for QA-aware compression.- bias: Compression bias multiplier.-- Returns:- RouterCompressionResult with reassembled content.- """- sections = split_into_sections(content)-- if not sections:- return RouterCompressionResult(- compressed=content,- original=content,- strategy_used=CompressionStrategy.PASSTHROUGH,- )-- compressed_sections: list[str] = []- routing_log: list[RoutingDecision] = []-- for i, section in enumerate(sections):- # Get strategy for this section- strategy = self._strategy_from_detection_type(section.content_type)-- # Compress section- original_tokens = len(section.content.split())- compressed_content, compressed_tokens = self._apply_strategy_to_content(- section.content,- strategy,- context,- section.language,- question,- bias=bias,- )-- # Preserve code fence markers- if section.is_code_fence and section.language:- compressed_content = f"```{section.language}\n{compressed_content}\n```"-- compressed_sections.append(compressed_content)- routing_log.append(- RoutingDecision(- content_type=section.content_type,- strategy=strategy,- original_tokens=original_tokens,- compressed_tokens=compressed_tokens,- section_index=i,- )- )-- return RouterCompressionResult(- compressed="\n\n".join(compressed_sections),- original=content,- strategy_used=CompressionStrategy.MIXED,- routing_log=routing_log,- sections_processed=len(sections),- )-- def _compress_pure(- self,- content: str,- strategy: CompressionStrategy,- context: str,- question: str | None = None,- bias: float = 1.0,- ) -> RouterCompressionResult:- """Compress pure (non-mixed) content.-- Args:- content: Content to compress.- strategy: Selected strategy.- context: User context.- question: Optional question for QA-aware compression.- bias: Compression bias multiplier.-- Returns:- RouterCompressionResult.- """- original_tokens = len(content.split())-- compressed, compressed_tokens = self._apply_strategy_to_content(- content, strategy, context, question=question, bias=bias- )-- return RouterCompressionResult(- compressed=compressed,- original=content,- strategy_used=strategy,- routing_log=[- RoutingDecision(- content_type=self._content_type_from_strategy(strategy),- strategy=strategy,- original_tokens=original_tokens,- compressed_tokens=compressed_tokens,- )- ],- )-- def _apply_strategy_to_content(- self,- content: str,- strategy: CompressionStrategy,- context: str,- language: str | None = None,- question: str | None = None,- bias: float = 1.0,- ) -> tuple[str, int]:- """Apply a compression strategy to content.-- Args:- content: Content to compress.- strategy: Strategy to use.- context: User context.- language: Language hint for code.- question: Optional question for QA-aware compression.- bias: Compression bias multiplier (>1 = keep more, <1 = keep fewer).-- Returns:- Tuple of (compressed_content, compressed_token_count).- """- # Track original tokens for TOIN recording- original_tokens = len(content.split())- compressed: str | None = None- compressed_tokens: int | None = None-- try:- if strategy == CompressionStrategy.CODE_AWARE:- if self.config.enable_code_aware:- compressor = self._get_code_compressor()- if compressor:- result = compressor.compress(content, language=language, context=context)- compressed, compressed_tokens = result.compressed, result.compressed_tokens- if compressed is None:- # Fallback to Kompress- compressed, compressed_tokens = self._try_ml_compressor(- content, context, question- )- strategy = CompressionStrategy.KOMPRESS # Update for TOIN-- elif strategy == CompressionStrategy.SMART_CRUSHER:- # SmartCrusher handles its own TOIN recording- if self.config.enable_smart_crusher:- crusher = self._get_smart_crusher()- if crusher:- result = crusher.crush(content, query=context, bias=bias)- return result.compressed, len(result.compressed.split())-- elif strategy == CompressionStrategy.SEARCH:- if self.config.enable_search_compressor:- compressor = self._get_search_compressor()- if compressor:- result = compressor.compress(content, context=context, bias=bias)- compressed, compressed_tokens = (- result.compressed,- len(result.compressed.split()),- )-- elif strategy == CompressionStrategy.LOG:- if self.config.enable_log_compressor:- compressor = self._get_log_compressor()- if compressor:- result = compressor.compress(content, bias=bias)- compressed, compressed_tokens = (- result.compressed,- result.compressed_line_count,- )-- elif strategy == CompressionStrategy.DIFF:- compressor = self._get_diff_compressor()- if compressor:- result = compressor.compress(content, context=context)- compressed, compressed_tokens = (- result.compressed,- result.compressed_line_count,- )-- elif strategy == CompressionStrategy.HTML:- if self.config.enable_html_extractor:- extractor = self._get_html_extractor()- if extractor:- result = extractor.extract(content)- compressed = result.extracted- # Estimate tokens from extracted text (simple word count)- compressed_tokens = len(compressed.split()) if compressed else 0-- elif strategy == CompressionStrategy.KOMPRESS:- compressed, compressed_tokens = self._try_ml_compressor(content, context, question)-- elif strategy == CompressionStrategy.TEXT:- # Prefer Kompress ML compressor for text- # Passes through unchanged if Kompress not available- compressed, compressed_tokens = self._try_ml_compressor(content, context, question)-- except Exception as e:- logger.warning("Compression with %s failed: %s", strategy.value, e)-- # If compression succeeded, record to TOIN- if compressed is not None and compressed_tokens is not None:- self._record_to_toin(- strategy=strategy,- content=content,- compressed=compressed,- original_tokens=original_tokens,- compressed_tokens=compressed_tokens,- language=language,- context=context,- )- return compressed, compressed_tokens-- # Fallback: return unchanged- return content, original_tokens-- def _try_ml_compressor(- self, content: str, context: str, question: str | None = None- ) -> tuple[str, int]:- """ML-based compression using Kompress.-- Kompress (ModernBERT, trained on 330K structured tool outputs)- auto-downloads from HuggingFace on first use. No heuristic fallback.-- Custom/workflow XML tags (<system-reminder>, <tool_call>, <thinking>)- are protected before compression and restored after. Standard HTML- tags are left alone (HTMLExtractor handles those separately).-- Args:- content: Content to compress.- context: User context.- question: Optional question for QA-aware compression.-- Returns:- Tuple of (compressed, token_count).- """- from .tag_protector import protect_tags, restore_tags-- # Protect custom tags before any ML compression- cleaned, protected = protect_tags(- content,- compress_tagged_content=self.config.compress_tagged_content,- )-- # If the entire content is custom tags with nothing to compress- if protected and not cleaned.strip():- return content, len(content.split())-- # Use the cleaned (tag-free) text for compression- text_to_compress = cleaned if protected else content- compressed: str | None = None- compressed_tokens: int | None = None-- # Primary: Kompress — downloads from chopratejas/kompress-base on first use- if self.config.enable_kompress:- compressor = self._get_kompress()- if compressor:- try:- result = compressor.compress(- text_to_compress,- context=context,- question=question,- target_ratio=getattr(self, "_runtime_target_ratio", None),- )- compressed = result.compressed- compressed_tokens = result.compressed_tokens- except Exception as e:- logger.warning("Kompress failed: %s", e)-- if compressed is None:- return content, len(content.split())-- # Restore protected tag blocks into the compressed text- if protected:- compressed = restore_tags(compressed, protected)- compressed_tokens = len(compressed.split())-- return compressed, compressed_tokens or len(compressed.split())-- def _strategy_from_detection_type(self, content_type: ContentType) -> CompressionStrategy:- """Get strategy from ContentType enum."""- mapping = {- ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,- ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,- ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,- ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,- ContentType.GIT_DIFF: CompressionStrategy.DIFF,- ContentType.HTML: CompressionStrategy.HTML,- ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,- }- return mapping.get(content_type, self.config.fallback_strategy)-- def _content_type_from_strategy(self, strategy: CompressionStrategy) -> ContentType:- """Get ContentType from strategy."""- mapping = {- CompressionStrategy.CODE_AWARE: ContentType.SOURCE_CODE,- CompressionStrategy.SMART_CRUSHER: ContentType.JSON_ARRAY,- CompressionStrategy.SEARCH: ContentType.SEARCH_RESULTS,- CompressionStrategy.LOG: ContentType.BUILD_OUTPUT,- CompressionStrategy.DIFF: ContentType.GIT_DIFF,- CompressionStrategy.HTML: ContentType.HTML,- CompressionStrategy.TEXT: ContentType.PLAIN_TEXT,- CompressionStrategy.KOMPRESS: ContentType.PLAIN_TEXT,- CompressionStrategy.PASSTHROUGH: ContentType.PLAIN_TEXT,- }- return mapping.get(strategy, ContentType.PLAIN_TEXT)-- # Lazy compressor getters-- def _get_code_compressor(self) -> Any:- """Get CodeAwareCompressor (lazy load)."""- if self._code_compressor is None:- try:- from .code_compressor import CodeAwareCompressor, _check_tree_sitter_available-- if _check_tree_sitter_available():- self._code_compressor = CodeAwareCompressor()- else:- logger.debug("tree-sitter not available")- except ImportError:- logger.debug("CodeAwareCompressor not available")- return self._code_compressor-- def _get_smart_crusher(self) -> Any:- """Get SmartCrusher (lazy load) with CCR config."""- if self._smart_crusher is None:- try:- from ..config import CCRConfig- from .smart_crusher import SmartCrusher-- # Pass CCR config for marker injection- ccr_config = CCRConfig(- enabled=self.config.ccr_enabled,- inject_retrieval_marker=self.config.ccr_inject_marker,- )- self._smart_crusher = SmartCrusher(ccr_config=ccr_config)- except ImportError:- logger.debug("SmartCrusher not available")- return self._smart_crusher-- def _get_search_compressor(self) -> Any:- """Get SearchCompressor (lazy load)."""- if self._search_compressor is None:- try:- from .search_compressor import SearchCompressor-- self._search_compressor = SearchCompressor()- except ImportError:- logger.debug("SearchCompressor not available")- return self._search_compressor-- def _get_log_compressor(self) -> Any:- """Get LogCompressor (lazy load)."""- if self._log_compressor is None:- try:- from .log_compressor import LogCompressor-- self._log_compressor = LogCompressor()- except ImportError:- logger.debug("LogCompressor not available")- return self._log_compressor-- def _get_diff_compressor(self) -> Any:- """Get DiffCompressor (lazy load)."""- if self._diff_compressor is None:- try:- from .diff_compressor import DiffCompressor-- self._diff_compressor = DiffCompressor()- except ImportError:- logger.debug("DiffCompressor not available")- return self._diff_compressor-- def _get_html_extractor(self) -> Any:- """Get HTMLExtractor (lazy load)."""- if self._html_extractor is None:- try:- from .html_extractor import HTMLExtractor-- self._html_extractor = HTMLExtractor()- except ImportError:- logger.debug("HTMLExtractor not available (install trafilatura)")- return self._html_extractor-- def eager_load_compressors(self) -> dict[str, str]:- """Pre-load compressors at startup to avoid first-request latency.-- Call this during proxy startup to load models and parsers- before any requests arrive. Eliminates cold-start latency spikes.-- Returns:- Dict of component name -> status string for logging.- """- status: dict[str, str] = {}-- # 1. ML text compressor: Kompress- if self.config.enable_kompress:- compressor = self._get_kompress()- if compressor:- logger.info("Kompress model pre-loaded at startup")- status["kompress"] = "enabled"- else:- status["kompress"] = "unavailable"-- # 2. Magika content detector (avoids 100-200ms on first content detection)- try:- from ..compression.detector import _get_magika, _magika_available-- if _magika_available():- _get_magika() # Initializes the singleton- logger.info("Magika content detector pre-loaded at startup")- status["magika"] = "enabled"- else:- status["magika"] = "not installed"- except Exception as e:- logger.debug("Magika pre-load skipped: %s", e)- status["magika"] = "skipped"-- # 3. CodeAware compressor + common tree-sitter parsers- if self.config.enable_code_aware:- code_compressor = self._get_code_compressor()- if code_compressor:- status["code_aware"] = "enabled"- # Pre-load tree-sitter parsers for common languages- # Each parser is ~50ms to load; doing it here avoids 500ms+ on first code hit- try:- from .code_compressor import _check_tree_sitter_available, _get_parser-- if _check_tree_sitter_available():- common_languages = [- "python",- "javascript",- "typescript",- "go",- "rust",- "java",- "c",- "cpp",- ]- loaded = []- for lang in common_languages:- try:- _get_parser(lang)- loaded.append(lang)- except (ValueError, ImportError):- pass # Language not available, skip- if loaded:- logger.info("Tree-sitter parsers pre-loaded: %s", ", ".join(loaded))- status["tree_sitter"] = f"loaded ({len(loaded)} languages)"- except Exception as e:- logger.debug("Tree-sitter pre-load skipped: %s", e)- status["tree_sitter"] = "skipped"- else:- status["code_aware"] = "not installed"-- # 4. SmartCrusher (lightweight init, but ensures import + TOIN ready)- smart_crusher = self._get_smart_crusher()- if smart_crusher:- status["smart_crusher"] = "ready"-- return status-- def _get_kompress(self) -> Any:- """Get KompressCompressor (lazy load). Downloads from HuggingFace on first use.-- Respects runtime kompress_model kwarg:- - None: use default (chopratejas/kompress-base) — cached on self- - "disabled": return None (skip ML compression entirely)- - any model ID string: create compressor with that model- (model weights are cached at module level in kompress_compressor.py,- so repeated calls with the same model_id are cheap)- """- model_id = getattr(self, "_runtime_kompress_model", None)-- # Explicitly disabled — no ML compression- if model_id == "disabled":- return None-- # Custom model — don't touch self._kompress (that's the default cache)- if model_id:- try:- from .kompress_compressor import (- KompressCompressor,- KompressConfig,- is_kompress_available,- )-- if is_kompress_available():- return KompressCompressor(config=KompressConfig(model_id=model_id))- except ImportError:- pass- return None-- # Default path — exactly as before, cached on self- if self._kompress is None:- try:- from .kompress_compressor import KompressCompressor, is_kompress_available-- if is_kompress_available():- self._kompress = KompressCompressor()- except ImportError:- logger.debug("Kompress dependencies not available")- return self._kompress-- def _get_image_optimizer(self) -> Any:- """Get ImageCompressor (lazy load).-- The ImageCompressor handles image token compression using:- - Trained MiniLM classifier from HuggingFace (chopratejas/technique-router)- - SigLIP for image analysis- - Provider-specific compression (OpenAI detail, Anthropic/Google resize)- """- if self._image_optimizer is None:- try:- from ..image import ImageCompressor-- self._image_optimizer = ImageCompressor()- except ImportError:- logger.debug("ImageCompressor not available")- return self._image_optimizer-- def optimize_images_in_messages(- self,- messages: list[dict[str, Any]],- tokenizer: Tokenizer,- provider: str = "openai",- user_query: str | None = None,- ) -> tuple[list[dict[str, Any]], dict[str, Any]]:- """Optimize images in messages.-- This is a convenience method for image optimization that can be called- directly or as part of the transform pipeline.-- Uses ImageCompressor with trained MiniLM router from HuggingFace- (chopratejas/technique-router) + SigLIP for image analysis.-- Args:- messages: Messages potentially containing images.- tokenizer: Tokenizer for token counting (unused, kept for API compat).- provider: LLM provider (openai, anthropic, google).- user_query: User query for task intent detection (unused, auto-extracted).-- Returns:- Tuple of (optimized_messages, metrics).- """- if not self.config.enable_image_optimizer:- return messages, {"images_optimized": 0, "tokens_saved": 0}-- compressor = self._get_image_optimizer()- if compressor is None:- return messages, {"images_optimized": 0, "tokens_saved": 0}-- # Check if there are images to compress- if not compressor.has_images(messages):- return messages, {"images_optimized": 0, "tokens_saved": 0}-- # Compress images (query is auto-extracted from messages)- optimized = compressor.compress(messages, provider=provider)-- # Get metrics from last compression- result = compressor.last_result- if result:- metrics = {- "images_optimized": result.compressed_tokens < result.original_tokens,- "tokens_before": result.original_tokens,- "tokens_after": result.compressed_tokens,- "tokens_saved": result.original_tokens - result.compressed_tokens,- "technique": result.technique.value,- "confidence": result.confidence,- }- else:- metrics = {"images_optimized": 0, "tokens_saved": 0}-- return optimized, metrics-- # Transform interface-- def _build_tool_name_map(self, messages: list[dict[str, Any]]) -> dict[str, str]:- """Build mapping from tool_call_id to tool_name.-- Scans assistant messages to find tool calls and extract their names.- Supports both OpenAI and Anthropic message formats.- """- mapping: dict[str, str] = {}-- for msg in messages:- if msg.get("role") != "assistant":- continue-- # OpenAI format: tool_calls array- for tc in msg.get("tool_calls", []):- if isinstance(tc, dict):- tc_id = tc.get("id", "")- name = tc.get("function", {}).get("name", "")- if tc_id and name:- mapping[tc_id] = name-- # Anthropic format: content blocks with type=tool_use- content = msg.get("content", [])- if isinstance(content, list):- for block in content:- if isinstance(block, dict) and block.get("type") == "tool_use":- tc_id = block.get("id", "")- name = block.get("name", "")- if tc_id and name:- mapping[tc_id] = name-- return mapping-- def apply(- self,- messages: list[dict[str, Any]],- tokenizer: Tokenizer,- **kwargs: Any,- ) -> TransformResult:- """Apply intelligent routing to messages.-- Args:- messages: Messages to transform.- tokenizer: Tokenizer for counting.- **kwargs: Additional arguments (context).-- Returns:- TransformResult with routed and compressed messages.- """- # Pre-process: Read lifecycle management (stale/superseded detection)- if self.config.read_lifecycle.enabled:- from .read_lifecycle import ReadLifecycleManager-- lifecycle_mgr = ReadLifecycleManager(- self.config.read_lifecycle,- compression_store=kwargs.get("compression_store"),- )- lifecycle_result = lifecycle_mgr.apply(- messages,- frozen_message_count=kwargs.get("frozen_message_count", 0),- )- messages = lifecycle_result.messages- # lifecycle transforms tracked separately, merged at the end- lifecycle_transforms = lifecycle_result.transforms_applied- lifecycle_ccr_hashes = lifecycle_result.ccr_hashes- else:- lifecycle_transforms = []- lifecycle_ccr_hashes = []-- # Runtime overrides from CompressConfig (via kwargs from compress())- # These override self.config defaults for this call only.- skip_user = (- kwargs.get("compress_user_messages") is not True and self.config.skip_user_messages- )- skip_system = kwargs.get("compress_system_messages") is False- protect_recent = kwargs.get("protect_recent", self.config.protect_recent_code)- protect_analysis = kwargs.get(- "protect_analysis_context", self.config.protect_analysis_context- )- min_tokens = kwargs.get("min_tokens_to_compress", 50)- # Store runtime options on self for access by _route_and_compress_block- self._runtime_target_ratio: float | None = kwargs.get("target_ratio")- self._runtime_kompress_model: str | None = kwargs.get("kompress_model")-- tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)- context = kwargs.get("context", "")- hook_biases: dict[int, float] = kwargs.get("biases") or {}-- # Build tool name map for exclusion checking- tool_name_map = self._build_tool_name_map(messages)-- # Compute excluded tool IDs based on config- exclude_tools = (- self.config.exclude_tools- if self.config.exclude_tools is not None- else DEFAULT_EXCLUDE_TOOLS- )- excluded_tool_ids = {- tool_id for tool_id, name in tool_name_map.items() if name in exclude_tools- }-- # --- Adaptive parameters based on context pressure ---- num_messages = len(messages)- model_limit = kwargs.get("model_limit", 0)-- # Adaptive Read protection: protect a fraction of recent messages- if self.config.protect_recent_reads_fraction > 0:- # Scale: at 10 msgs protect 5, at 50 msgs protect 25, at 200 msgs protect 100- # But cap at a reasonable floor so very short convos still protect everything- read_protection_window = max(- 4, # always protect at least last 4 messages- int(num_messages * self.config.protect_recent_reads_fraction),- )- else:- read_protection_window = num_messages # 0.0 = protect all (old behavior)-- # Adaptive compression ratio: scale with context pressure- if model_limit > 0:- context_pressure = min(1.0, tokens_before / model_limit)- else:- context_pressure = 0.5 # default: moderate-- # Linear interpolation between relaxed and aggressive thresholds- # pressure 0.0 → relaxed, pressure 1.0 → aggressive- min_ratio = (- self.config.min_ratio_relaxed- + (self.config.min_ratio_aggressive - self.config.min_ratio_relaxed) * context_pressure- )- # Clamp to [aggressive, relaxed] range- min_ratio = max(- self.config.min_ratio_aggressive,- min(self.config.min_ratio_relaxed, min_ratio),- )-- if context_pressure > 0.3:- logger.debug(- "content_router adaptive: pressure=%.2f, min_ratio=%.2f, "- "read_protect_window=%d/%d msgs",- context_pressure,- min_ratio,- read_protection_window,- num_messages,- )-- transformed_messages: list[dict[str, Any]] = []- transforms_applied: list[str] = []- warnings: list[str] = []- compressor_timing: dict[str, float] = {} # strategy → cumulative ms-- # Routing reason counters for summary logging- route_counts: dict[str, int] = {- "excluded_tool": 0,- "user_msg": 0,- "small": 0,- "recent_code": 0,- "analysis_ctx": 0,- "ratio_too_high": 0,- "non_string": 0,- "content_blocks": 0,- }- compressed_details: list[str] = [] # e.g. ["code_aware:0.72", "kompress:0.65"]-- # Check for analysis intent in the most recent user message- analysis_intent = False- if self.config.protect_analysis_context:- analysis_intent = self._detect_analysis_intent(messages)-- frozen_message_count = kwargs.get("frozen_message_count", 0)-- # ------------------------------------------------------------------- # Two-pass parallel compression.- #- # Pass 1 (sequential): categorise every message — frozen, protected,- # cached, small, etc. are resolved immediately. Cache-miss messages- # that need full compression are collected into *pending_tasks*.- #- # Pass 2 (parallel): all cache-miss compressions run concurrently in- # a thread pool. Each self.compress() call is independent.- #- # Pass 3 (sequential): results are stitched back into message order,- # caches updated, and counters incremented.- # -------------------------------------------------------------------- # Pre-allocate result slots — None means "pending compression".- result_slots: list[dict[str, Any] | None] = [None] * num_messages-- # Tasks: list of (slot_index, content, context, bias, content_key)- _PendingTask = tuple[int, str, str, float, int]- pending_tasks: list[_PendingTask] = []-- for i, message in enumerate(messages):- # Skip frozen messages (in provider's prefix cache).- # Modifying these would invalidate the cache, replacing a 90%- # read discount with a 25% write penalty (Anthropic).- if i < frozen_message_count:- result_slots[i] = message- continue-- role = message.get("role", "")- content = message.get("content", "")- bias = 1.0 # Default bias, may be overridden for tool messages-- messages_from_end = num_messages - i-- # Handle list content (Anthropic format with content blocks)- if isinstance(content, list):- transformed_message = self._process_content_blocks(- message,- content,- context,- transforms_applied,- excluded_tool_ids,- tool_name_map=tool_name_map,- route_counts=route_counts,- compressed_details=compressed_details,- min_ratio=min_ratio,- read_protection_window=read_protection_window,- messages_from_end=messages_from_end,- compressor_timing=compressor_timing,- )- result_slots[i] = transformed_message- route_counts["content_blocks"] += 1- continue-- # Skip non-string content (other types)- if not isinstance(content, str):- result_slots[i] = message- route_counts["non_string"] += 1- continue-- # Skip OpenAI-style tool messages for excluded tools- # BUT: allow compression of old excluded-tool outputs beyond the- # adaptive protection window (age-based decay).- if role == "tool":- tool_call_id = message.get("tool_call_id", "")- if tool_call_id in excluded_tool_ids:- if messages_from_end <= read_protection_window:- # Recent — protect as before- result_slots[i] = message- transforms_applied.append("router:excluded:tool")- route_counts["excluded_tool"] += 1- continue- # Old excluded-tool output — fall through to compression- # (the LLM is unlikely to need exact content from this far back,- # and CCR provides retrieval if it does)- # Look up tool-specific compression bias for OpenAI tool messages- tool_name = tool_name_map.get(tool_call_id, "")- bias = self._get_tool_bias(tool_name) if tool_name else 1.0-- # Protection 1: Never compress user messages (unless overridden)- if skip_user and role == "user":- result_slots[i] = message- transforms_applied.append("router:protected:user_message")- route_counts["user_msg"] += 1- continue-- # Protection 1b: Never compress system messages (when disabled)- if skip_system and role == "system":- result_slots[i] = message- transforms_applied.append("router:protected:system_message")- route_counts.setdefault("system_msg", 0)- route_counts["system_msg"] += 1- continue-- if not content or tokenizer.count_text(content) < min_tokens:- # Skip small content- result_slots[i] = message- route_counts["small"] += 1- continue-- # Detect content type for protection decisions- detection = _detect_content(content)- is_code = detection.content_type == ContentType.SOURCE_CODE-- # Protection 2: Don't compress recent CODE- messages_from_end = num_messages - i- if protect_recent > 0 and messages_from_end <= protect_recent and is_code:- result_slots[i] = message- transforms_applied.append("router:protected:recent_code")- route_counts["recent_code"] += 1- continue-- # Protection 3: Don't compress CODE when analysis intent detected- if protect_analysis and analysis_intent and is_code:- result_slots[i] = message- transforms_applied.append("router:protected:analysis_context")- route_counts["analysis_ctx"] += 1- continue-- # Compression pinning: if this message was already compressed- # (contains a CCR retrieval marker), skip recompression.- # Recompressing would change byte content and break provider- # prefix caching with no meaningful further reduction.- if "Retrieve more: hash=" in content or "Retrieve original: hash=" in content:- result_slots[i] = message- route_counts.setdefault("already_compressed", 0)- route_counts["already_compressed"] += 1- continue-- # Route and compress based on content detection- # Merge tool-specific bias with hook-provided bias (multiplicative)- msg_bias = bias if role == "tool" else 1.0- if i in hook_biases:- msg_bias *= hook_biases[i]-- # Two-tier compression cache.- # Tier 1 (skip): known won't-compress → instant skip.- # Tier 2 (result): known compresses → reuse compressed text.- content_key = hash(content)-- # Tier 1: skip set — instant rejection- if self._cache.is_skipped(content_key):- result_slots[i] = message- route_counts["ratio_too_high"] += 1- route_counts.setdefault("cache_hit", 0)- route_counts["cache_hit"] += 1- continue-- # Tier 2: result cache — reuse compressed output- cached = self._cache.get(content_key)- if cached is not None:- cached_compressed, cached_ratio, cached_strategy = cached- # Re-check ratio against current min_ratio (shifts with context pressure)- if cached_ratio < min_ratio:- result_slots[i] = {**message, "content": cached_compressed}- transforms_applied.append(f"router:{cached_strategy}:{cached_ratio:.2f}")- compressed_details.append(f"{cached_strategy}:{cached_ratio:.2f}")- else:- # Threshold tightened — no longer qualifies. Move to skip.- self._cache.move_to_skip(content_key)- result_slots[i] = message- route_counts["ratio_too_high"] += 1- route_counts.setdefault("cache_hit", 0)- route_counts["cache_hit"] += 1- continue-- # Cache miss — defer to parallel compression pass- route_counts.setdefault("cache_miss", 0)- route_counts["cache_miss"] += 1- pending_tasks.append((i, content, context, msg_bias, content_key))-- # --- Pass 2: Parallel compression of all cache-miss messages ---- if pending_tasks:- max_workers = min(- len(pending_tasks), int(os.environ.get("HEADROOM_COMPRESS_WORKERS", "4"))- )- t_parallel_start = time.perf_counter()-- if max_workers <= 1 or len(pending_tasks) == 1:- # Single task or parallelism disabled — compress inline- task_results = []- for _, task_content, task_ctx, task_bias, _ in pending_tasks:- t0 = time.perf_counter()- r = self.compress(task_content, context=task_ctx, bias=task_bias)- task_results.append((r, (time.perf_counter() - t0) * 1000))- else:- # Parallel compression via thread pool- with ThreadPoolExecutor(max_workers=max_workers) as executor:- futures = []- for _, task_content, task_ctx, task_bias, _ in pending_tasks:- futures.append(- executor.submit(self._timed_compress, task_content, task_ctx, task_bias)- )- task_results = [f.result() for f in futures]-- parallel_ms = (time.perf_counter() - t_parallel_start) * 1000- compressor_timing["parallel_compress_total"] = parallel_ms-- # --- Pass 3: Merge results back (sequential, updates caches) ---- for (slot_idx, _, _, _, content_key), (result, compress_ms) in zip(- pending_tasks, task_results- ):- message = messages[slot_idx]- strategy_key = f"compressor:{result.strategy_used.value}"- compressor_timing[strategy_key] = (- compressor_timing.get(strategy_key, 0.0) + compress_ms- )-- if result.compression_ratio < min_ratio:- # Compressed — store in result cache- self._cache.put(- content_key,- result.compressed,- result.compression_ratio,- result.strategy_used.value,- )- result_slots[slot_idx] = {**message, "content": result.compressed}- transforms_applied.append(- f"router:{result.strategy_used.value}:{result.compression_ratio:.2f}"- )- compressed_details.append(- f"{result.strategy_used.value}:{result.compression_ratio:.2f}"- )- else:- # Didn't compress — add to skip set- self._cache.mark_skip(content_key)- result_slots[slot_idx] = message- route_counts["ratio_too_high"] += 1-- # Build final message list from slots- transformed_messages = [m for m in result_slots if m is not None]-- tokens_after = sum(- tokenizer.count_text(str(m.get("content", ""))) for m in transformed_messages- )-- # Log routing summary- parts = []- if compressed_details:- parts.append(f"{len(compressed_details)} compressed ({', '.join(compressed_details)})")- if route_counts["excluded_tool"]:- parts.append(f"{route_counts['excluded_tool']} excluded (Read/Glob)")- if route_counts["user_msg"]:- parts.append(f"{route_counts['user_msg']} skipped (user)")- if route_counts["small"]:- parts.append(f"{route_counts['small']} skipped (<50 words)")- if route_counts["recent_code"]:- parts.append(f"{route_counts['recent_code']} protected (recent code)")- if route_counts["analysis_ctx"]:- parts.append(f"{route_counts['analysis_ctx']} protected (analysis ctx)")- if route_counts.get("already_compressed"):- parts.append(f"{route_counts['already_compressed']} pinned (already compressed)")- if route_counts["ratio_too_high"]:- parts.append(f"{route_counts['ratio_too_high']} unchanged (ratio>={min_ratio:.2f})")- if route_counts["content_blocks"]:- parts.append(f"{route_counts['content_blocks']} content-block msgs")- if route_counts["non_string"]:- parts.append(f"{route_counts['non_string']} non-string")- if route_counts.get("cache_hit"):- parts.append(f"{route_counts['cache_hit']} cache hits")- if route_counts.get("cache_miss"):- parts.append(f"{route_counts['cache_miss']} cache misses")- cs = self._cache.stats- if cs["cache_size"] > 0 or cs["cache_skip_size"] > 0:- parts.append(- f"cache[{cs['cache_size']} results, {cs['cache_skip_size']} skips, "- f"{cs['cache_avg_lookup_ns']:.0f}ns avg]"- )- if parts:- logger.info(- "content_router: %d msgs — %s",- num_messages,- ", ".join(parts),- )-- all_transforms = lifecycle_transforms + transforms_applied- return TransformResult(- messages=transformed_messages,- tokens_before=tokens_before,- tokens_after=tokens_after,- transforms_applied=all_transforms if all_transforms else ["router:noop"],- markers_inserted=lifecycle_ccr_hashes,- warnings=warnings,- timing=compressor_timing,- )-- def _get_tool_bias(self, tool_name: str) -> float:- """Look up compression bias for a tool name.-- Checks user-configured profiles first, then DEFAULT_TOOL_PROFILES.- Returns 1.0 (moderate) if no profile is configured.- """- from ..config import DEFAULT_TOOL_PROFILES-- # Check user-configured profiles- if self.config.tool_profiles:- profile = self.config.tool_profiles.get(tool_name)- if profile:- return float(profile.bias)-- # Check default profiles- profile = DEFAULT_TOOL_PROFILES.get(tool_name)- if profile:- return profile.bias-- return 1.0 # Default: moderate-- def _process_content_blocks(- self,- message: dict[str, Any],- content_blocks: list[Any],- context: str,- transforms_applied: list[str],- excluded_tool_ids: set[str],- tool_name_map: dict[str, str] | None = None,- route_counts: dict[str, int] | None = None,- compressed_details: list[str] | None = None,- min_ratio: float = 0.85,- read_protection_window: int = 8,- messages_from_end: int = 0,- compressor_timing: dict[str, float] | None = None,- ) -> dict[str, Any]:- """Process content blocks (Anthropic format) for tool_result compression.-- Handles tool_result blocks by compressing their string content using- the appropriate strategy (typically SmartCrusher for JSON arrays).-- Args:- message: The original message.- content_blocks: List of content blocks.- context: Context for compression.- transforms_applied: List to append transform names to.- excluded_tool_ids: Tool IDs to skip compression for.- tool_name_map: Mapping from tool_call_id to tool_name for profile lookup.- route_counts: Optional routing reason counters to update.- compressed_details: Optional list to append compression details to.- min_ratio: Adaptive compression ratio threshold.- read_protection_window: Messages from end within which excluded tools are protected.- messages_from_end: How far this message is from the end of the conversation.-- Returns:- Transformed message with compressed content blocks.- """- new_blocks = []- any_compressed = False-- for block in content_blocks:- if not isinstance(block, dict):- new_blocks.append(block)- continue-- block_type = block.get("type")-- # Handle tool_result blocks- if block_type == "tool_result":- # Check if tool is excluded from compression- tool_use_id = block.get("tool_use_id", "")- if tool_use_id in excluded_tool_ids:- if messages_from_end <= read_protection_window:- # Recent — protect as before- new_blocks.append(block)- transforms_applied.append("router:excluded:tool")- if route_counts is not None:- route_counts["excluded_tool"] += 1- continue- # Old excluded-tool output — fall through to compression-- # Look up tool-specific compression bias- tool_name = (tool_name_map or {}).get(tool_use_id, "")- bias = self._get_tool_bias(tool_name) if tool_name else 1.0-- tool_content = block.get("content", "")-- # Only process string content- if isinstance(tool_content, str) and len(tool_content) > 500:- # Compression pinning: skip already-compressed content- if (- "Retrieve more: hash=" in tool_content- or "Retrieve original: hash=" in tool_content- ):- new_blocks.append(block)- if route_counts is not None:- route_counts.setdefault("already_compressed", 0)- route_counts["already_compressed"] += 1- continue-- # Two-tier compression cache- content_key = hash(tool_content)-- # Tier 1: skip set — instant rejection- if self._cache.is_skipped(content_key):- new_blocks.append(block)- if route_counts is not None:- route_counts["ratio_too_high"] += 1- route_counts.setdefault("cache_hit", 0)- route_counts["cache_hit"] += 1- continue-- # Tier 2: result cache — reuse compressed output- cached = self._cache.get(content_key)- if cached is not None:- cached_compressed, cached_ratio, cached_strategy = cached- if cached_ratio < min_ratio:- new_blocks.append({**block, "content": cached_compressed})- transforms_applied.append(f"router:tool_result:{cached_strategy}")- if compressed_details is not None:- compressed_details.append(- f"tool:{cached_strategy}:{cached_ratio:.2f}"- )- any_compressed = True- else:- # Threshold tightened — move to skip- self._cache.move_to_skip(content_key)- new_blocks.append(block)- if route_counts is not None:- route_counts["ratio_too_high"] += 1- if route_counts is not None:- route_counts.setdefault("cache_hit", 0)- route_counts["cache_hit"] += 1- continue-- # Cache miss — run full compression- if route_counts is not None:- route_counts.setdefault("cache_miss", 0)- route_counts["cache_miss"] += 1- t0 = time.perf_counter()- result = self.compress(tool_content, context=context, bias=bias)- compress_ms = (time.perf_counter() - t0) * 1000- if compressor_timing is not None:- key = f"compressor:{result.strategy_used.value}"- compressor_timing[key] = compressor_timing.get(key, 0.0) + compress_ms- if result.compression_ratio < min_ratio:- # Compressed — store in result cache- self._cache.put(- content_key,- result.compressed,- result.compression_ratio,- result.strategy_used.value,- )- new_blocks.append({**block, "content": result.compressed})- transforms_applied.append(- f"router:tool_result:{result.strategy_used.value}"- )- if compressed_details is not None:- compressed_details.append(- f"tool:{result.strategy_used.value}:{result.compression_ratio:.2f}"- )- any_compressed = True- continue- else:- # Didn't compress — add to skip set- self._cache.mark_skip(content_key)- if route_counts is not None:- route_counts["ratio_too_high"] += 1- else:- if route_counts is not None:- route_counts["small"] += 1-- # Keep block unchanged- new_blocks.append(block)-- if any_compressed:- return {**message, "content": new_blocks}- return message-- def _detect_analysis_intent(self, messages: list[dict[str, Any]]) -> bool:- """Detect if user wants to analyze/review code.-- Looks at the most recent user message for analysis keywords.-- Args:- messages: Conversation messages.-- Returns:- True if analysis intent detected.- """- # Analysis keywords that suggest user wants full code details- analysis_keywords = {- "analyze",- "analyse",- "review",- "audit",- "inspect",- "security",- "vulnerability",- "bug",- "issue",- "problem",- "explain",- "understand",- "how does",- "what does",- "debug",- "fix",- "error",- "wrong",- "broken",- "refactor",- "improve",- "optimize",- "clean up",- }-- # Find most recent user message- for message in reversed(messages):- if message.get("role") == "user":- content = message.get("content", "")- if isinstance(content, str):- content_lower = content.lower()- for keyword in analysis_keywords:- if keyword in content_lower:- return True- break-- return False-- def should_apply(- self,- messages: list[dict[str, Any]],- tokenizer: Tokenizer,- **kwargs: Any,- ) -> bool:- """Check if routing should be applied.-- Always returns True - the router handles all content types.- """- return True---def route_and_compress(- content: str,- context: str = "",-) -> str:- """Convenience function for one-off routing and compression.-- Args:- content: Content to compress.- context: Optional context for relevance-aware compression.-- Returns:- Compressed content.-- Example:- >>> compressed = route_and_compress(mixed_content)- """- router = ContentRouter()- result = router.compress(content, context=context)- return result.compressed+"""Content router for intelligent compression strategy selection.++This module provides the ContentRouter, which analyzes content and routes it+to the optimal compressor. It handles mixed content by splitting, routing+each section to the appropriate compressor, and reassembling.++Supported Compressors:+- CodeAwareCompressor: Source code (AST-preserving)+- SmartCrusher: JSON arrays+- SearchCompressor: grep/ripgrep results+- LogCompressor: Build/test output+- KompressCompressor: Plain text (ML-based)+- Kompress: Plain text (ML-based, requires [ml] extra)++Routing Strategy:+1. Use source hint if available (highest confidence)+2. Check for mixed content (split and route sections)+3. Detect content type (JSON, code, search, logs, text)+4. Route to appropriate compressor+5. Reassemble and return with routing metadata++Usage:+ >>> from headroom.transforms import ContentRouter+ >>> router = ContentRouter()+ >>> result = router.compress(content) # Auto-routes to best compressor+ >>> print(result.strategy_used)+ >>> print(result.routing_log)++Pipeline Usage:+ >>> pipeline = TransformPipeline([+ ... ContentRouter(), # Handles all content types+ ... RollingWindow(), # Final size constraint+ ... ])+"""++from __future__ import annotations++import hashlib+import logging+import os+import re+import time+from concurrent.futures import ThreadPoolExecutor+from dataclasses import dataclass, field+from enum import Enum+from typing import Any++from ..config import DEFAULT_EXCLUDE_TOOLS, ReadLifecycleConfig, TransformResult+from ..tokenizer import Tokenizer+from .base import Transform+from .content_detector import ContentType, DetectionResult, detect_content_type++logger = logging.getLogger(__name__)++_magika_detector: Any | None = None+_magika_status: bool | None = None+++def _get_magika_detector() -> Any | None:+ """Load the Magika detector only when router detection actually runs."""+ global _magika_detector, _magika_status++ if _magika_status is False:+ return None+ if _magika_detector is not None:+ return _magika_detector++ try:+ from ..compression.detector import get_detector++ _magika_detector = get_detector(prefer_magika=True)+ _magika_status = True+ logger.info("ContentRouter: Using Magika ML-based content detection")+ except ImportError:+ _magika_status = False+ logger.debug("Magika not available, using regex-based detection")++ return _magika_detector+++def _detect_content(content: str) -> DetectionResult:+ """Detect content type using Magika if available, else regex fallback."""+ magika_detector = _get_magika_detector()+ if magika_detector is not None:+ result = magika_detector.detect(content)+ # Map Magika ContentType to router's expected format+ type_map = {+ "json": ContentType.JSON_ARRAY,+ "code": ContentType.SOURCE_CODE,+ "log": ContentType.BUILD_OUTPUT,+ "diff": ContentType.GIT_DIFF,+ "markdown": ContentType.PLAIN_TEXT,+ "text": ContentType.PLAIN_TEXT,+ "unknown": ContentType.PLAIN_TEXT,+ }+ mapped_type = type_map.get(result.content_type.value, ContentType.PLAIN_TEXT)+ return DetectionResult(+ content_type=mapped_type,+ confidence=result.confidence,+ metadata={"language": result.language, "raw_label": result.raw_label},+ )+ else:+ return detect_content_type(content)+++def _create_content_signature(+ content_type: str,+ content: str,+ language: str | None = None,+) -> Any:+ """Create a ToolSignature for non-JSON content types.++ This allows TOIN to track compression patterns for code, search results,+ logs, and text - not just JSON arrays.++ Args:+ content_type: The type of content (e.g., "code_aware", "search", "log", "text").+ content: The content being compressed (for structural hints).+ language: Optional language hint for code.++ Returns:+ A ToolSignature for TOIN tracking.+ """+ try:+ from ..telemetry.models import ToolSignature++ # Create a deterministic structure hash based on content type+ # This groups similar content types together for pattern learning+ if language:+ hash_input = f"content:{content_type}:{language}"+ else:+ hash_input = f"content:{content_type}"++ # Add a structural hint from the content (first 100 chars, hashed)+ # This helps differentiate tool outputs of the same type+ content_sample = content[:100] if content else ""+ structure_hint = hashlib.sha256(content_sample.encode()).hexdigest()[:8]+ hash_input = f"{hash_input}:{structure_hint}"++ # Keep SHA256: structure_hash feeds into TOIN which persists to disk.+ # Changing hash function would invalidate all learned patterns.+ structure_hash = hashlib.sha256(hash_input.encode()).hexdigest()[:24]++ return ToolSignature(+ structure_hash=structure_hash,+ field_count=0, # Not applicable for non-JSON+ has_nested_objects=False,+ has_arrays=False,+ max_depth=0,+ )+ except ImportError:+ return None+++class CompressionCache:+ """Two-tier compression cache with TTL.++ Tier 1 (skip set): content hashes that won't compress — instant skip,+ near-zero memory (just ints in a set).++ Tier 2 (result cache): compressed results for content that DID compress —+ reuse the compressed text on subsequent requests.++ Entries expire after TTL (default 30min). No max-entries cap — TTL is the+ natural bound. Memory grows proportional to compressible content × TTL,+ which is bounded by session duration.++ Uses in-process dict for ultra-fast lookups (~100ns). Could be backed+ by memcached/Redis for multi-process deployments.+ """++ def __init__(self, ttl_seconds: int = 1800):+ # Tier 2: compressed results {hash: (text, ratio, strategy, timestamp)}+ self._results: dict[int, tuple[str, float, str, float]] = {}+ # Tier 1: hashes of content that won't compress {hash: timestamp}+ self._skip: dict[int, float] = {}+ self._ttl_seconds = ttl_seconds+ # Metrics+ self._hits = 0+ self._misses = 0+ self._skip_hits = 0+ self._evictions = 0+ self._total_lookup_ns = 0+ self._lookup_count = 0++ def get(self, key: int) -> tuple[str, float, str] | None:+ """Get cached compression result.++ Returns (compressed_text, ratio, strategy) or None if not found/expired.+ Use is_skipped() first to check if content is known non-compressible.+ """+ t0 = time.perf_counter_ns()+ entry = self._results.get(key)+ if entry is not None:+ compressed, ratio, strategy, created_at = entry+ if (time.time() - created_at) < self._ttl_seconds:+ self._hits += 1+ self._total_lookup_ns += time.perf_counter_ns() - t0+ self._lookup_count += 1+ return (compressed, ratio, strategy)+ else:+ del self._results[key]+ self._evictions += 1+ self._misses += 1+ self._total_lookup_ns += time.perf_counter_ns() - t0+ self._lookup_count += 1+ return None++ def is_skipped(self, key: int) -> bool:+ """Check if content is known non-compressible (Tier 1)."""+ ts = self._skip.get(key)+ if ts is not None:+ if (time.time() - ts) < self._ttl_seconds:+ self._skip_hits += 1+ return True+ else:+ del self._skip[key]+ self._evictions += 1+ return False++ def put(self, key: int, compressed: str, ratio: float, strategy: str) -> None:+ """Store a compressed result (Tier 2)."""+ self._results[key] = (compressed, ratio, strategy, time.time())++ def mark_skip(self, key: int) -> None:+ """Mark content as non-compressible (Tier 1)."""+ self._skip[key] = time.time()++ def move_to_skip(self, key: int) -> None:+ """Move a result to skip set (threshold tightened, no longer qualifies)."""+ self._results.pop(key, None)+ self._skip[key] = time.time()++ @property+ def size(self) -> int:+ return len(self._results)++ @property+ def skip_size(self) -> int:+ return len(self._skip)++ @property+ def stats(self) -> dict[str, int | float]:+ avg_ns = self._total_lookup_ns / self._lookup_count if self._lookup_count else 0+ return {+ "cache_hits": self._hits,+ "cache_skip_hits": self._skip_hits,+ "cache_misses": self._misses,+ "cache_evictions": self._evictions,+ "cache_size": len(self._results),+ "cache_skip_size": len(self._skip),+ "cache_avg_lookup_ns": avg_ns,+ }++ def clear(self) -> None:+ """Clear all entries (e.g., on session end)."""+ self._results.clear()+ self._skip.clear()+++class CompressionStrategy(Enum):+ """Available compression strategies."""++ CODE_AWARE = "code_aware"+ SMART_CRUSHER = "smart_crusher"+ SEARCH = "search"+ LOG = "log"+ KOMPRESS = "kompress"+ TEXT = "text"+ DIFF = "diff"+ HTML = "html"+ MIXED = "mixed"+ PASSTHROUGH = "passthrough"+++@dataclass+class RoutingDecision:+ """Record of a single routing decision."""++ content_type: ContentType+ strategy: CompressionStrategy+ original_tokens: int+ compressed_tokens: int+ confidence: float = 1.0+ section_index: int = 0++ @property+ def compression_ratio(self) -> float:+ if self.original_tokens == 0:+ return 1.0+ return self.compressed_tokens / self.original_tokens+++@dataclass+class ContentSection:+ """A typed section of content."""++ content: str+ content_type: ContentType+ language: str | None = None+ start_line: int = 0+ end_line: int = 0+ is_code_fence: bool = False+++@dataclass+class RouterCompressionResult:+ """Result from ContentRouter with routing metadata.++ Attributes:+ compressed: The compressed content.+ original: Original content before compression.+ strategy_used: Primary strategy used for compression.+ routing_log: List of routing decisions made.+ sections_processed: Number of content sections processed.+ """++ compressed: str+ original: str+ strategy_used: CompressionStrategy+ routing_log: list[RoutingDecision] = field(default_factory=list)+ sections_processed: int = 1++ @property+ def total_original_tokens(self) -> int:+ """Total tokens before compression."""+ return sum(r.original_tokens for r in self.routing_log)++ @property+ def total_compressed_tokens(self) -> int:+ """Total tokens after compression."""+ return sum(r.compressed_tokens for r in self.routing_log)++ @property+ def compression_ratio(self) -> float:+ """Overall compression ratio."""+ if self.total_original_tokens == 0:+ return 1.0+ return self.total_compressed_tokens / self.total_original_tokens++ @property+ def tokens_saved(self) -> int:+ """Number of tokens saved."""+ return max(0, self.total_original_tokens - self.total_compressed_tokens)++ @property+ def savings_percentage(self) -> float:+ """Percentage of tokens saved."""+ if self.total_original_tokens == 0:+ return 0.0+ return (self.tokens_saved / self.total_original_tokens) * 100++ def summary(self) -> str:+ """Human-readable routing summary."""+ if self.strategy_used == CompressionStrategy.MIXED:+ strategies = {r.strategy.value for r in self.routing_log}+ return (+ f"Mixed content: {self.sections_processed} sections, "+ f"routed to {strategies}. "+ f"{self.total_original_tokens:,}→{self.total_compressed_tokens:,} tokens "+ f"({self.savings_percentage:.0f}% saved)"+ )+ else:+ return (+ f"Pure {self.strategy_used.value}: "+ f"{self.total_original_tokens:,}→{self.total_compressed_tokens:,} tokens "+ f"({self.savings_percentage:.0f}% saved)"+ )+++@dataclass+class ContentRouterConfig:+ """Configuration for intelligent content routing.++ Attributes:+ enable_code_aware: Enable AST-based code compression.+ enable_smart_crusher: Enable JSON array compression.+ enable_search_compressor: Enable search result compression.+ enable_log_compressor: Enable build/test log compression.+ enable_image_optimizer: Enable image token optimization.+ prefer_code_aware_for_code: Use CodeAware over Kompress for code.+ mixed_content_threshold: Min distinct types to consider "mixed".+ min_section_tokens: Minimum tokens for a section to compress.+ fallback_strategy: Strategy when no compressor matches.+ skip_user_messages: Never compress user messages (they're the subject).+ skip_recent_messages: Don't compress last N messages (likely the subject).+ protect_analysis_context: Detect "analyze/review" intent, skip compression.+ """++ # Enable/disable specific compressors+ enable_code_aware: bool = False # Disabled: use code graph MCP tools instead+ enable_kompress: bool = True # Kompress: ModernBERT token compressor+ enable_smart_crusher: bool = True+ enable_search_compressor: bool = True+ enable_log_compressor: bool = True+ enable_html_extractor: bool = True # HTML content extraction+ enable_image_optimizer: bool = True # Image token optimization++ # Routing preferences+ prefer_code_aware_for_code: bool = False # Disabled: let code pass through unmangled+ mixed_content_threshold: int = 2 # Min types to consider mixed+ min_section_tokens: int = 20 # Min tokens to compress a section++ # Fallback: Kompress handles unknown/mixed content instead of passing through+ fallback_strategy: CompressionStrategy = CompressionStrategy.KOMPRESS++ # Protection: Don't compress content that's likely the subject of analysis+ skip_user_messages: bool = True # User messages contain what they want analyzed+ protect_recent_code: int = 4 # Don't compress CODE in last N messages (0 = disabled)+ protect_analysis_context: bool = True # Detect "analyze/review" intent, protect code++ # Adaptive Read protection: fraction of total messages to protect from+ # compression. At 10 msgs, protects ~5 Reads. At 100 msgs, protects ~10.+ # Old Reads beyond this window become compressible even though they are+ # in DEFAULT_EXCLUDE_TOOLS. 0.0 = always exclude all (old behavior).+ protect_recent_reads_fraction: float = (+ 0.0 # 0.0 = protect ALL excluded-tool outputs (safest for coding agents)+ )++ # Adaptive compression ratio: scales with context pressure.+ # At low pressure (<30% full), use the relaxed threshold (reject marginal).+ # At high pressure (>80% full), use the aggressive threshold (accept anything helpful).+ # Linearly interpolates between the two.+ min_ratio_relaxed: float = 0.85 # when context is mostly empty+ min_ratio_aggressive: float = 0.65 # when context is nearly full++ # CCR (Compress-Cache-Retrieve) settings for SmartCrusher+ ccr_enabled: bool = True # Enable CCR marker injection for reversible compression+ ccr_inject_marker: bool = True # Add retrieval markers to compressed content++ # Tag protection: preserve custom/workflow XML tags from text compression.+ # When False (default), entire <custom-tag>content</custom-tag> blocks are+ # protected verbatim. When True, only the tag markers are protected and+ # the content between them can be compressed.+ compress_tagged_content: bool = False++ # Tools to exclude from compression (output passed through unmodified)+ # Set to None to use DEFAULT_EXCLUDE_TOOLS, or provide custom set+ exclude_tools: set[str] | None = None++ # Read lifecycle management (stale/superseded detection)+ read_lifecycle: ReadLifecycleConfig = field(default_factory=ReadLifecycleConfig)++ # Per-tool compression profiles (tool_name → CompressionProfile)+ # Set to None to use DEFAULT_TOOL_PROFILES from config+ tool_profiles: dict[str, Any] | None = None+++# Patterns for detecting mixed content+_CODE_FENCE_PATTERN = re.compile(r"^```(\w*)\s*$", re.MULTILINE)+_JSON_BLOCK_START = re.compile(r"^\s*[\[{]", re.MULTILINE)+_SEARCH_RESULT_PATTERN = re.compile(r"^\S+:\d+:", re.MULTILINE)+_PROSE_PATTERN = re.compile(r"[A-Z][a-z]+\s+\w+\s+\w+")+++def is_mixed_content(content: str) -> bool:+ """Detect if content contains multiple distinct types.++ Args:+ content: Content to analyze.++ Returns:+ True if content appears to be mixed (multiple types).+ """+ indicators = {+ "has_code_fences": bool(_CODE_FENCE_PATTERN.search(content)),+ "has_json_blocks": bool(_JSON_BLOCK_START.search(content)),+ "has_prose": len(_PROSE_PATTERN.findall(content)) > 5,+ "has_search_results": bool(_SEARCH_RESULT_PATTERN.search(content)),+ }++ # Mixed if 2+ indicators are true+ return sum(indicators.values()) >= 2+++def split_into_sections(content: str) -> list[ContentSection]:+ """Parse mixed content into typed sections.++ Args:+ content: Mixed content to split.++ Returns:+ List of ContentSection objects.+ """+ sections: list[ContentSection] = []+ lines = content.split("\n")++ i = 0+ while i < len(lines):+ line = lines[i]++ # Code fence: ```language+ if match := _CODE_FENCE_PATTERN.match(line):+ language = match.group(1) or "unknown"+ code_lines = []+ start_line = i+ i += 1++ while i < len(lines) and not lines[i].startswith("```"):+ code_lines.append(lines[i])+ i += 1++ sections.append(+ ContentSection(+ content="\n".join(code_lines),+ content_type=ContentType.SOURCE_CODE,+ language=language,+ start_line=start_line,+ end_line=i,+ is_code_fence=True,+ )+ )+ i += 1 # Skip closing ```+ continue++ # JSON block+ if line.strip().startswith(("[", "{")):+ json_content, end_i = _extract_json_block(lines, i)+ if json_content:+ sections.append(+ ContentSection(+ content=json_content,+ content_type=ContentType.JSON_ARRAY,+ start_line=i,+ end_line=end_i,+ )+ )+ i = end_i + 1+ continue++ # Search result lines+ if _SEARCH_RESULT_PATTERN.match(line):+ search_lines = []+ start_line = i+ while i < len(lines) and _SEARCH_RESULT_PATTERN.match(lines[i]):+ search_lines.append(lines[i])+ i += 1+ sections.append(+ ContentSection(+ content="\n".join(search_lines),+ content_type=ContentType.SEARCH_RESULTS,+ start_line=start_line,+ end_line=i - 1,+ )+ )+ continue++ # Collect text until next special section+ text_lines = [line]+ start_line = i+ i += 1++ while i < len(lines):+ next_line = lines[i]+ # Stop if we hit a special section+ if (+ _CODE_FENCE_PATTERN.match(next_line)+ or next_line.strip().startswith(("[", "{"))+ or _SEARCH_RESULT_PATTERN.match(next_line)+ ):+ break+ text_lines.append(next_line)+ i += 1++ # Only add non-empty text sections+ text_content = "\n".join(text_lines)+ if text_content.strip():+ sections.append(+ ContentSection(+ content=text_content,+ content_type=ContentType.PLAIN_TEXT,+ start_line=start_line,+ end_line=i - 1,+ )+ )++ return sections+++def _extract_json_block(lines: list[str], start: int) -> tuple[str | None, int]:+ """Extract a complete JSON block from lines.++ Args:+ lines: All lines of content.+ start: Starting line index.++ Returns:+ Tuple of (json_content, end_line_index) or (None, start) if invalid.+ """+ bracket_count = 0+ brace_count = 0+ json_lines = []++ for i in range(start, len(lines)):+ line = lines[i]+ json_lines.append(line)++ bracket_count += line.count("[") - line.count("]")+ brace_count += line.count("{") - line.count("}")++ if bracket_count <= 0 and brace_count <= 0 and json_lines:+ return "\n".join(json_lines), i++ # Didn't find complete JSON+ return None, start+++class ContentRouter(Transform):+ """Intelligent router that selects optimal compression strategy.++ ContentRouter is the recommended entry point for Headroom's compression.+ It analyzes content and routes it to the most appropriate compressor,+ handling mixed content by splitting and reassembling.++ Key Features:+ - Automatic content type detection+ - Source hint support for high-confidence routing+ - Mixed content handling (split → route → reassemble)+ - Graceful fallback when compressors unavailable+ - Rich routing metadata for debugging++ Example:+ >>> router = ContentRouter()+ >>>+ >>> # Automatically uses CodeAwareCompressor+ >>> result = router.compress(python_code)+ >>> print(result.strategy_used) # CompressionStrategy.CODE_AWARE+ >>>+ >>> # Automatically uses SmartCrusher+ >>> result = router.compress(json_array)+ >>> print(result.strategy_used) # CompressionStrategy.SMART_CRUSHER+ >>>+ >>> # Splits and routes each section+ >>> result = router.compress(readme_with_code)+ >>> print(result.strategy_used) # CompressionStrategy.MIXED++ Pipeline Integration:+ >>> pipeline = TransformPipeline([+ ... ContentRouter(), # Handles ALL content types+ ... RollingWindow(), # Final size constraint+ ... ])+ """++ name: str = "content_router"++ def __init__(self, config: ContentRouterConfig | None = None):+ """Initialize content router.++ Args:+ config: Router configuration. Uses defaults if None.+ """+ self.config = config or ContentRouterConfig()++ # Lazy-loaded compressors+ self._code_compressor: Any = None+ self._smart_crusher: Any = None+ self._search_compressor: Any = None+ self._log_compressor: Any = None+ self._diff_compressor: Any = None+ self._html_extractor: Any = None+ self._kompress: Any = None+ self._image_optimizer: Any = None++ # TOIN integration for cross-strategy learning+ self._toin: Any = None++ self._cache = CompressionCache()++ def _record_to_toin(+ self,+ strategy: CompressionStrategy,+ content: str,+ compressed: str,+ original_tokens: int,+ compressed_tokens: int,+ language: str | None = None,+ context: str = "",+ ) -> None:+ """Record compression to TOIN for cross-user learning.++ This allows TOIN to track compression patterns for ALL content types,+ not just JSON arrays. When the LLM retrieves original content via CCR,+ TOIN learns which compressions users need to expand.++ Args:+ strategy: The compression strategy used.+ content: Original content (for signature generation).+ compressed: Compressed content.+ original_tokens: Token count before compression.+ compressed_tokens: Token count after compression.+ language: Optional language hint for code.+ context: Query context for pattern learning.+ """+ # Skip SmartCrusher - it handles its own TOIN recording+ if strategy == CompressionStrategy.SMART_CRUSHER:+ return++ # Skip if no actual compression happened+ if original_tokens <= compressed_tokens:+ return++ try:+ # Lazy load TOIN+ if self._toin is None:+ from ..telemetry.toin import get_toin++ self._toin = get_toin()++ # Create a content-type signature+ signature = _create_content_signature(+ content_type=strategy.value,+ content=content,+ language=language,+ )++ if signature is None:+ return++ # Record the compression+ self._toin.record_compression(+ tool_signature=signature,+ original_count=1, # Single content block+ compressed_count=1,+ original_tokens=original_tokens,+ compressed_tokens=compressed_tokens,+ strategy=strategy.value,+ query_context=context if context else None,+ )++ logger.debug(+ "TOIN: Recorded %s compression: %d → %d tokens",+ strategy.value,+ original_tokens,+ compressed_tokens,+ )++ except Exception as e:+ # TOIN recording should never break compression+ logger.debug("TOIN recording failed (non-fatal): %s", e)++ def _timed_compress(+ self, content: str, context: str, bias: float+ ) -> tuple[RouterCompressionResult, float]:+ """Compress with wall-clock timing. Used by parallel executor."""+ t0 = time.perf_counter()+ result = self.compress(content, context=context, bias=bias)+ return result, (time.perf_counter() - t0) * 1000++ def compress(+ self,+ content: str,+ context: str = "",+ question: str | None = None,+ bias: float = 1.0,+ ) -> RouterCompressionResult:+ """Compress content using optimal strategy based on content detection.++ Args:+ content: Content to compress.+ context: Optional context for relevance-aware compression.+ question: Optional question for QA-aware compression. When provided,+ tokens relevant to answering this question are preserved.+ bias: Compression bias multiplier (>1 = keep more, <1 = keep fewer).++ Returns:+ RouterCompressionResult with compressed content and routing metadata.+ """+ if not content or not content.strip():+ return RouterCompressionResult(+ compressed=content,+ original=content,+ strategy_used=CompressionStrategy.PASSTHROUGH,+ routing_log=[],+ )++ # Determine strategy from content analysis+ strategy = self._determine_strategy(content)++ if strategy == CompressionStrategy.MIXED:+ return self._compress_mixed(content, context, question, bias=bias)+ else:+ return self._compress_pure(content, strategy, context, question, bias=bias)++ def _determine_strategy(self, content: str) -> CompressionStrategy:+ """Determine the compression strategy from content analysis.++ Args:+ content: Content to analyze.++ Returns:+ Selected compression strategy.+ """+ # 1. Check for mixed content+ if is_mixed_content(content):+ return CompressionStrategy.MIXED++ # 2. Detect content type from content itself+ detection = _detect_content(content)+ return self._strategy_from_detection(detection)++ def _strategy_from_detection(self, detection: Any) -> CompressionStrategy:+ """Get strategy from content detection result.++ Args:+ detection: Result from detect_content_type.++ Returns:+ Selected strategy.+ """+ mapping = {+ ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,+ ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,+ ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,+ ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,+ ContentType.GIT_DIFF: CompressionStrategy.DIFF,+ ContentType.HTML: CompressionStrategy.HTML,+ ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,+ }++ strategy = mapping.get(detection.content_type, self.config.fallback_strategy)++ # Override: prefer CodeAware for code if configured+ if (+ strategy == CompressionStrategy.CODE_AWARE+ and not self.config.prefer_code_aware_for_code+ ):+ strategy = CompressionStrategy.KOMPRESS++ return strategy++ def _compress_mixed(+ self,+ content: str,+ context: str,+ question: str | None = None,+ bias: float = 1.0,+ ) -> RouterCompressionResult:+ """Compress mixed content by splitting and routing sections.++ Args:+ content: Mixed content to compress.+ context: User context for relevance.+ question: Optional question for QA-aware compression.+ bias: Compression bias multiplier.++ Returns:+ RouterCompressionResult with reassembled content.+ """+ sections = split_into_sections(content)++ if not sections:+ return RouterCompressionResult(+ compressed=content,+ original=content,+ strategy_used=CompressionStrategy.PASSTHROUGH,+ )++ compressed_sections: list[str] = []+ routing_log: list[RoutingDecision] = []++ for i, section in enumerate(sections):+ # Get strategy for this section+ strategy = self._strategy_from_detection_type(section.content_type)++ # Compress section+ original_tokens = len(section.content.split())+ compressed_content, compressed_tokens = self._apply_strategy_to_content(+ section.content,+ strategy,+ context,+ section.language,+ question,+ bias=bias,+ )++ # Preserve code fence markers+ if section.is_code_fence and section.language:+ compressed_content = f"```{section.language}\n{compressed_content}\n```"++ compressed_sections.append(compressed_content)+ routing_log.append(+ RoutingDecision(+ content_type=section.content_type,+ strategy=strategy,+ original_tokens=original_tokens,+ compressed_tokens=compressed_tokens,+ section_index=i,+ )+ )++ return RouterCompressionResult(+ compressed="\n\n".join(compressed_sections),+ original=content,+ strategy_used=CompressionStrategy.MIXED,+ routing_log=routing_log,+ sections_processed=len(sections),+ )++ def _compress_pure(+ self,+ content: str,+ strategy: CompressionStrategy,+ context: str,+ question: str | None = None,+ bias: float = 1.0,+ ) -> RouterCompressionResult:+ """Compress pure (non-mixed) content.++ Args:+ content: Content to compress.+ strategy: Selected strategy.+ context: User context.+ question: Optional question for QA-aware compression.+ bias: Compression bias multiplier.++ Returns:+ RouterCompressionResult.+ """+ original_tokens = len(content.split())++ compressed, compressed_tokens = self._apply_strategy_to_content(+ content, strategy, context, question=question, bias=bias+ )++ return RouterCompressionResult(+ compressed=compressed,+ original=content,+ strategy_used=strategy,+ routing_log=[+ RoutingDecision(+ content_type=self._content_type_from_strategy(strategy),+ strategy=strategy,+ original_tokens=original_tokens,+ compressed_tokens=compressed_tokens,+ )+ ],+ )++ def _apply_strategy_to_content(+ self,+ content: str,+ strategy: CompressionStrategy,+ context: str,+ language: str | None = None,+ question: str | None = None,+ bias: float = 1.0,+ ) -> tuple[str, int]:+ """Apply a compression strategy to content.++ Args:+ content: Content to compress.+ strategy: Strategy to use.+ context: User context.+ language: Language hint for code.+ question: Optional question for QA-aware compression.+ bias: Compression bias multiplier (>1 = keep more, <1 = keep fewer).++ Returns:+ Tuple of (compressed_content, compressed_token_count).+ """+ # Track original tokens for TOIN recording+ original_tokens = len(content.split())+ compressed: str | None = None+ compressed_tokens: int | None = None++ try:+ if strategy == CompressionStrategy.CODE_AWARE:+ if self.config.enable_code_aware:+ compressor = self._get_code_compressor()+ if compressor:+ result = compressor.compress(content, language=language, context=context)+ compressed, compressed_tokens = result.compressed, result.compressed_tokens+ if compressed is None:+ # Fallback to Kompress+ compressed, compressed_tokens = self._try_ml_compressor(+ content, context, question+ )+ strategy = CompressionStrategy.KOMPRESS # Update for TOIN++ elif strategy == CompressionStrategy.SMART_CRUSHER:+ # SmartCrusher handles its own TOIN recording+ if self.config.enable_smart_crusher:+ crusher = self._get_smart_crusher()+ if crusher:+ result = crusher.crush(content, query=context, bias=bias)+ return result.compressed, len(result.compressed.split())++ elif strategy == CompressionStrategy.SEARCH:+ if self.config.enable_search_compressor:+ compressor = self._get_search_compressor()+ if compressor:+ result = compressor.compress(content, context=context, bias=bias)+ compressed, compressed_tokens = (+ result.compressed,+ len(result.compressed.split()),+ )++ elif strategy == CompressionStrategy.LOG:+ if self.config.enable_log_compressor:+ compressor = self._get_log_compressor()+ if compressor:+ result = compressor.compress(content, bias=bias)+ compressed, compressed_tokens = (+ result.compressed,+ result.compressed_line_count,+ )++ elif strategy == CompressionStrategy.DIFF:+ compressor = self._get_diff_compressor()+ if compressor:+ result = compressor.compress(content, context=context)+ compressed, compressed_tokens = (+ result.compressed,+ result.compressed_line_count,+ )++ elif strategy == CompressionStrategy.HTML:+ if self.config.enable_html_extractor:+ extractor = self._get_html_extractor()+ if extractor:+ result = extractor.extract(content)+ compressed = result.extracted+ # Estimate tokens from extracted text (simple word count)+ compressed_tokens = len(compressed.split()) if compressed else 0++ elif strategy == CompressionStrategy.KOMPRESS:+ compressed, compressed_tokens = self._try_ml_compressor(content, context, question)++ elif strategy == CompressionStrategy.TEXT:+ # Prefer Kompress ML compressor for text+ # Passes through unchanged if Kompress not available+ compressed, compressed_tokens = self._try_ml_compressor(content, context, question)++ except Exception as e:+ logger.warning("Compression with %s failed: %s", strategy.value, e)++ # If compression succeeded, record to TOIN+ if compressed is not None and compressed_tokens is not None:+ self._record_to_toin(+ strategy=strategy,+ content=content,+ compressed=compressed,+ original_tokens=original_tokens,+ compressed_tokens=compressed_tokens,+ language=language,+ context=context,+ )+ return compressed, compressed_tokens++ # Fallback: return unchanged+ return content, original_tokens++ def _try_ml_compressor(+ self, content: str, context: str, question: str | None = None+ ) -> tuple[str, int]:+ """ML-based compression using Kompress.++ Kompress (ModernBERT, trained on 330K structured tool outputs)+ auto-downloads from HuggingFace on first use. No heuristic fallback.++ Custom/workflow XML tags (<system-reminder>, <tool_call>, <thinking>)+ are protected before compression and restored after. Standard HTML+ tags are left alone (HTMLExtractor handles those separately).++ Args:+ content: Content to compress.+ context: User context.+ question: Optional question for QA-aware compression.++ Returns:+ Tuple of (compressed, token_count).+ """+ from .tag_protector import protect_tags, restore_tags++ # Protect custom tags before any ML compression+ cleaned, protected = protect_tags(+ content,+ compress_tagged_content=self.config.compress_tagged_content,+ )++ # If the entire content is custom tags with nothing to compress+ if protected and not cleaned.strip():+ return content, len(content.split())++ # Use the cleaned (tag-free) text for compression+ text_to_compress = cleaned if protected else content+ compressed: str | None = None+ compressed_tokens: int | None = None++ # Primary: Kompress — downloads from chopratejas/kompress-base on first use+ if self.config.enable_kompress:+ compressor = self._get_kompress()+ if compressor:+ try:+ result = compressor.compress(+ text_to_compress,+ context=context,+ question=question,+ target_ratio=getattr(self, "_runtime_target_ratio", None),+ )+ compressed = result.compressed+ compressed_tokens = result.compressed_tokens+ except Exception as e:+ logger.warning("Kompress failed: %s", e)++ if compressed is None:+ return content, len(content.split())++ # Restore protected tag blocks into the compressed text+ if protected:+ compressed = restore_tags(compressed, protected)+ compressed_tokens = len(compressed.split())++ return compressed, compressed_tokens or len(compressed.split())++ def _strategy_from_detection_type(self, content_type: ContentType) -> CompressionStrategy:+ """Get strategy from ContentType enum."""+ mapping = {+ ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,+ ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,+ ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,+ ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,+ ContentType.GIT_DIFF: CompressionStrategy.DIFF,+ ContentType.HTML: CompressionStrategy.HTML,+ ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,+ }+ return mapping.get(content_type, self.config.fallback_strategy)++ def _content_type_from_strategy(self, strategy: CompressionStrategy) -> ContentType:+ """Get ContentType from strategy."""+ mapping = {+ CompressionStrategy.CODE_AWARE: ContentType.SOURCE_CODE,+ CompressionStrategy.SMART_CRUSHER: ContentType.JSON_ARRAY,+ CompressionStrategy.SEARCH: ContentType.SEARCH_RESULTS,+ CompressionStrategy.LOG: ContentType.BUILD_OUTPUT,+ CompressionStrategy.DIFF: ContentType.GIT_DIFF,+ CompressionStrategy.HTML: ContentType.HTML,+ CompressionStrategy.TEXT: ContentType.PLAIN_TEXT,+ CompressionStrategy.KOMPRESS: ContentType.PLAIN_TEXT,+ CompressionStrategy.PASSTHROUGH: ContentType.PLAIN_TEXT,+ }+ return mapping.get(strategy, ContentType.PLAIN_TEXT)++ # Lazy compressor getters++ def _get_code_compressor(self) -> Any:+ """Get CodeAwareCompressor (lazy load)."""+ if self._code_compressor is None:+ try:+ from .code_compressor import CodeAwareCompressor, _check_tree_sitter_available++ if _check_tree_sitter_available():+ self._code_compressor = CodeAwareCompressor()+ else:+ logger.debug("tree-sitter not available")+ except ImportError:+ logger.debug("CodeAwareCompressor not available")+ return self._code_compressor++ def _get_smart_crusher(self) -> Any:+ """Get SmartCrusher (lazy load) with CCR config."""+ if self._smart_crusher is None:+ try:+ from ..config import CCRConfig+ from .smart_crusher import SmartCrusher++ # Pass CCR config for marker injection+ ccr_config = CCRConfig(+ enabled=self.config.ccr_enabled,+ inject_retrieval_marker=self.config.ccr_inject_marker,+ )+ self._smart_crusher = SmartCrusher(ccr_config=ccr_config)+ except ImportError:+ logger.debug("SmartCrusher not available")+ return self._smart_crusher++ def _get_search_compressor(self) -> Any:+ """Get SearchCompressor (lazy load)."""+ if self._search_compressor is None:+ try:+ from .search_compressor import SearchCompressor++ self._search_compressor = SearchCompressor()+ except ImportError:+ logger.debug("SearchCompressor not available")+ return self._search_compressor++ def _get_log_compressor(self) -> Any:+ """Get LogCompressor (lazy load)."""+ if self._log_compressor is None:+ try:+ from .log_compressor import LogCompressor++ self._log_compressor = LogCompressor()+ except ImportError:+ logger.debug("LogCompressor not available")+ return self._log_compressor++ def _get_diff_compressor(self) -> Any:+ """Get DiffCompressor (lazy load)."""+ if self._diff_compressor is None:+ try:+ from .diff_compressor import DiffCompressor++ self._diff_compressor = DiffCompressor()+ except ImportError:+ logger.debug("DiffCompressor not available")+ return self._diff_compressor++ def _get_html_extractor(self) -> Any:+ """Get HTMLExtractor (lazy load)."""+ if self._html_extractor is None:+ try:+ from .html_extractor import HTMLExtractor++ self._html_extractor = HTMLExtractor()+ except ImportError:+ logger.debug("HTMLExtractor not available (install trafilatura)")+ return self._html_extractor++ def eager_load_compressors(self) -> dict[str, str]:+ """Pre-load compressors at startup to avoid first-request latency.++ Call this during proxy startup to load models and parsers+ before any requests arrive. Eliminates cold-start latency spikes.++ Returns:+ Dict of component name -> status string for logging.+ """+ status: dict[str, str] = {}++ # 1. ML text compressor: Kompress+ if self.config.enable_kompress:+ compressor = self._get_kompress()+ if compressor:+ logger.info("Kompress model pre-loaded at startup")+ status["kompress"] = "enabled"+ else:+ status["kompress"] = "unavailable"++ # 2. Magika content detector (avoids 100-200ms on first content detection)+ try:+ from ..compression.detector import _get_magika, _magika_available++ if _magika_available():+ _get_magika() # Initializes the singleton+ logger.info("Magika content detector pre-loaded at startup")+ status["magika"] = "enabled"+ else:+ status["magika"] = "not installed"+ except Exception as e:+ logger.debug("Magika pre-load skipped: %s", e)+ status["magika"] = "skipped"++ # 3. CodeAware compressor + common tree-sitter parsers+ if self.config.enable_code_aware:+ code_compressor = self._get_code_compressor()+ if code_compressor:+ status["code_aware"] = "enabled"+ # Pre-load tree-sitter parsers for common languages+ # Each parser is ~50ms to load; doing it here avoids 500ms+ on first code hit+ try:+ from .code_compressor import _check_tree_sitter_available, _get_parser++ if _check_tree_sitter_available():+ common_languages = [+ "python",+ "javascript",+ "typescript",+ "go",+ "rust",+ "java",+ "c",+ "cpp",+ ]+ loaded = []+ for lang in common_languages:+ try:+ _get_parser(lang)+ loaded.append(lang)+ except (ValueError, ImportError):+ pass # Language not available, skip+ if loaded:+ logger.info("Tree-sitter parsers pre-loaded: %s", ", ".join(loaded))+ status["tree_sitter"] = f"loaded ({len(loaded)} languages)"+ except Exception as e:+ logger.debug("Tree-sitter pre-load skipped: %s", e)+ status["tree_sitter"] = "skipped"+ else:+ status["code_aware"] = "not installed"++ # 4. SmartCrusher (lightweight init, but ensures import + TOIN ready)+ smart_crusher = self._get_smart_crusher()+ if smart_crusher:+ status["smart_crusher"] = "ready"++ return status++ def _get_kompress(self) -> Any:+ """Get KompressCompressor (lazy load). Downloads from HuggingFace on first use.++ Respects runtime kompress_model kwarg:+ - None: use default (chopratejas/kompress-base) — cached on self+ - "disabled": return None (skip ML compression entirely)+ - any model ID string: create compressor with that model+ (model weights are cached at module level in kompress_compressor.py,+ so repeated calls with the same model_id are cheap)+ """+ model_id = getattr(self, "_runtime_kompress_model", None)++ # Explicitly disabled — no ML compression+ if model_id == "disabled":+ return None++ # Custom model — don't touch self._kompress (that's the default cache)+ if model_id:+ try:+ from .kompress_compressor import (+ KompressCompressor,+ KompressConfig,+ is_kompress_available,+ )++ if is_kompress_available():+ return KompressCompressor(config=KompressConfig(model_id=model_id))+ except ImportError:+ pass+ return None++ # Default path — exactly as before, cached on self+ if self._kompress is None:+ try:+ from .kompress_compressor import KompressCompressor, is_kompress_available++ if is_kompress_available():+ self._kompress = KompressCompressor()+ except ImportError:+ logger.debug("Kompress dependencies not available")+ return self._kompress++ def _get_image_optimizer(self) -> Any:+ """Get ImageCompressor (lazy load).++ The ImageCompressor handles image token compression using:+ - Trained MiniLM classifier from HuggingFace (chopratejas/technique-router)+ - SigLIP for image analysis+ - Provider-specific compression (OpenAI detail, Anthropic/Google resize)+ """+ if self._image_optimizer is None:+ try:+ from ..image import ImageCompressor++ self._image_optimizer = ImageCompressor()+ except ImportError:+ logger.debug("ImageCompressor not available")+ return self._image_optimizer++ def optimize_images_in_messages(+ self,+ messages: list[dict[str, Any]],+ tokenizer: Tokenizer,+ provider: str = "openai",+ user_query: str | None = None,+ ) -> tuple[list[dict[str, Any]], dict[str, Any]]:+ """Optimize images in messages.++ This is a convenience method for image optimization that can be called+ directly or as part of the transform pipeline.++ Uses ImageCompressor with trained MiniLM router from HuggingFace+ (chopratejas/technique-router) + SigLIP for image analysis.++ Args:+ messages: Messages potentially containing images.+ tokenizer: Tokenizer for token counting (unused, kept for API compat).+ provider: LLM provider (openai, anthropic, google).+ user_query: User query for task intent detection (unused, auto-extracted).++ Returns:+ Tuple of (optimized_messages, metrics).+ """+ if not self.config.enable_image_optimizer:+ return messages, {"images_optimized": 0, "tokens_saved": 0}++ compressor = self._get_image_optimizer()+ if compressor is None:+ return messages, {"images_optimized": 0, "tokens_saved": 0}++ # Check if there are images to compress+ if not compressor.has_images(messages):+ return messages, {"images_optimized": 0, "tokens_saved": 0}++ # Compress images (query is auto-extracted from messages)+ optimized = compressor.compress(messages, provider=provider)++ # Get metrics from last compression+ result = compressor.last_result+ if result:+ metrics = {+ "images_optimized": result.compressed_tokens < result.original_tokens,+ "tokens_before": result.original_tokens,+ "tokens_after": result.compressed_tokens,+ "tokens_saved": result.original_tokens - result.compressed_tokens,+ "technique": result.technique.value,+ "confidence": result.confidence,+ }+ else:+ metrics = {"images_optimized": 0, "tokens_saved": 0}++ return optimized, metrics++ # Transform interface++ def _build_tool_name_map(self, messages: list[dict[str, Any]]) -> dict[str, str]:+ """Build mapping from tool_call_id to tool_name.++ Scans assistant messages to find tool calls and extract their names.+ Supports both OpenAI and Anthropic message formats.+ """+ mapping: dict[str, str] = {}++ for msg in messages:+ if msg.get("role") != "assistant":+ continue++ # OpenAI format: tool_calls array+ for tc in msg.get("tool_calls", []):+ if isinstance(tc, dict):+ tc_id = tc.get("id", "")+ name = tc.get("function", {}).get("name", "")+ if tc_id and name:+ mapping[tc_id] = name++ # Anthropic format: content blocks with type=tool_use+ content = msg.get("content", [])+ if isinstance(content, list):+ for block in content:+ if isinstance(block, dict) and block.get("type") == "tool_use":+ tc_id = block.get("id", "")+ name = block.get("name", "")+ if tc_id and name:+ mapping[tc_id] = name++ return mapping++ def apply(+ self,+ messages: list[dict[str, Any]],+ tokenizer: Tokenizer,+ **kwargs: Any,+ ) -> TransformResult:+ """Apply intelligent routing to messages.++ Args:+ messages: Messages to transform.+ tokenizer: Tokenizer for counting.+ **kwargs: Additional arguments (context).++ Returns:+ TransformResult with routed and compressed messages.+ """+ # Pre-process: Read lifecycle management (stale/superseded detection)+ if self.config.read_lifecycle.enabled:+ from .read_lifecycle import ReadLifecycleManager++ lifecycle_mgr = ReadLifecycleManager(+ self.config.read_lifecycle,+ compression_store=kwargs.get("compression_store"),+ )+ lifecycle_result = lifecycle_mgr.apply(+ messages,+ frozen_message_count=kwargs.get("frozen_message_count", 0),+ )+ messages = lifecycle_result.messages+ # lifecycle transforms tracked separately, merged at the end+ lifecycle_transforms = lifecycle_result.transforms_applied+ lifecycle_ccr_hashes = lifecycle_result.ccr_hashes+ else:+ lifecycle_transforms = []+ lifecycle_ccr_hashes = []++ # Runtime overrides from CompressConfig (via kwargs from compress())+ # These override self.config defaults for this call only.+ skip_user = (+ kwargs.get("compress_user_messages") is not True and self.config.skip_user_messages+ )+ skip_system = kwargs.get("compress_system_messages") is False+ protect_recent = kwargs.get("protect_recent", self.config.protect_recent_code)+ protect_analysis = kwargs.get(+ "protect_analysis_context", self.config.protect_analysis_context+ )+ min_tokens = kwargs.get("min_tokens_to_compress", 50)+ # Store runtime options on self for access by _route_and_compress_block+ self._runtime_target_ratio: float | None = kwargs.get("target_ratio")+ self._runtime_kompress_model: str | None = kwargs.get("kompress_model")++ tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)+ context = kwargs.get("context", "")+ hook_biases: dict[int, float] = kwargs.get("biases") or {}++ # Build tool name map for exclusion checking+ tool_name_map = self._build_tool_name_map(messages)++ # Compute excluded tool IDs based on config+ exclude_tools = (+ self.config.exclude_tools+ if self.config.exclude_tools is not None+ else DEFAULT_EXCLUDE_TOOLS+ )+ excluded_tool_ids = {+ tool_id for tool_id, name in tool_name_map.items() if name in exclude_tools+ }++ # --- Adaptive parameters based on context pressure ---+ num_messages = len(messages)+ model_limit = kwargs.get("model_limit", 0)++ # Adaptive Read protection: protect a fraction of recent messages+ if self.config.protect_recent_reads_fraction > 0:+ # Scale: at 10 msgs protect 5, at 50 msgs protect 25, at 200 msgs protect 100+ # But cap at a reasonable floor so very short convos still protect everything+ read_protection_window = max(+ 4, # always protect at least last 4 messages+ int(num_messages * self.config.protect_recent_reads_fraction),+ )+ else:+ read_protection_window = num_messages # 0.0 = protect all (old behavior)++ # Adaptive compression ratio: scale with context pressure+ if model_limit > 0:+ context_pressure = min(1.0, tokens_before / model_limit)+ else:+ context_pressure = 0.5 # default: moderate++ # Linear interpolation between relaxed and aggressive thresholds+ # pressure 0.0 → relaxed, pressure 1.0 → aggressive+ min_ratio = (+ self.config.min_ratio_relaxed+ + (self.config.min_ratio_aggressive - self.config.min_ratio_relaxed) * context_pressure+ )+ # Clamp to [aggressive, relaxed] range+ min_ratio = max(+ self.config.min_ratio_aggressive,+ min(self.config.min_ratio_relaxed, min_ratio),+ )++ if context_pressure > 0.3:+ logger.debug(+ "content_router adaptive: pressure=%.2f, min_ratio=%.2f, "+ "read_protect_window=%d/%d msgs",+ context_pressure,+ min_ratio,+ read_protection_window,+ num_messages,+ )++ transformed_messages: list[dict[str, Any]] = []+ transforms_applied: list[str] = []+ warnings: list[str] = []+ compressor_timing: dict[str, float] = {} # strategy → cumulative ms++ # Routing reason counters for summary logging+ route_counts: dict[str, int] = {+ "excluded_tool": 0,+ "user_msg": 0,+ "small": 0,+ "recent_code": 0,+ "analysis_ctx": 0,+ "ratio_too_high": 0,+ "non_string": 0,+ "content_blocks": 0,+ }+ compressed_details: list[str] = [] # e.g. ["code_aware:0.72", "kompress:0.65"]++ # Check for analysis intent in the most recent user message+ analysis_intent = False+ if self.config.protect_analysis_context:+ analysis_intent = self._detect_analysis_intent(messages)++ frozen_message_count = kwargs.get("frozen_message_count", 0)++ # ------------------------------------------------------------------+ # Two-pass parallel compression.+ #+ # Pass 1 (sequential): categorise every message — frozen, protected,+ # cached, small, etc. are resolved immediately. Cache-miss messages+ # that need full compression are collected into *pending_tasks*.+ #+ # Pass 2 (parallel): all cache-miss compressions run concurrently in+ # a thread pool. Each self.compress() call is independent.+ #+ # Pass 3 (sequential): results are stitched back into message order,+ # caches updated, and counters incremented.+ # ------------------------------------------------------------------++ # Pre-allocate result slots — None means "pending compression".+ result_slots: list[dict[str, Any] | None] = [None] * num_messages++ # Tasks: list of (slot_index, content, context, bias, content_key)+ _PendingTask = tuple[int, str, str, float, int]+ pending_tasks: list[_PendingTask] = []++ for i, message in enumerate(messages):+ # Skip frozen messages (in provider's prefix cache).+ # Modifying these would invalidate the cache, replacing a 90%+ # read discount with a 25% write penalty (Anthropic).+ if i < frozen_message_count:+ result_slots[i] = message+ continue++ role = message.get("role", "")+ content = message.get("content", "")+ bias = 1.0 # Default bias, may be overridden for tool messages++ messages_from_end = num_messages - i++ # Handle list content (Anthropic format with content blocks)+ if isinstance(content, list):+ transformed_message = self._process_content_blocks(+ message,+ content,+ context,+ transforms_applied,+ excluded_tool_ids,+ tool_name_map=tool_name_map,+ route_counts=route_counts,+ compressed_details=compressed_details,+ min_ratio=min_ratio,+ read_protection_window=read_protection_window,+ messages_from_end=messages_from_end,+ compressor_timing=compressor_timing,+ )+ result_slots[i] = transformed_message+ route_counts["content_blocks"] += 1+ continue++ # Skip non-string content (other types)+ if not isinstance(content, str):+ result_slots[i] = message+ route_counts["non_string"] += 1+ continue++ # Skip OpenAI-style tool messages for excluded tools+ # BUT: allow compression of old excluded-tool outputs beyond the+ # adaptive protection window (age-based decay).+ if role == "tool":+ tool_call_id = message.get("tool_call_id", "")+ if tool_call_id in excluded_tool_ids:+ if messages_from_end <= read_protection_window:+ # Recent — protect as before+ result_slots[i] = message+ transforms_applied.append("router:excluded:tool")+ route_counts["excluded_tool"] += 1+ continue+ # Old excluded-tool output — fall through to compression+ # (the LLM is unlikely to need exact content from this far back,+ # and CCR provides retrieval if it does)+ # Look up tool-specific compression bias for OpenAI tool messages+ tool_name = tool_name_map.get(tool_call_id, "")+ bias = self._get_tool_bias(tool_name) if tool_name else 1.0++ # Protection 1: Never compress user messages (unless overridden)+ if skip_user and role == "user":+ result_slots[i] = message+ transforms_applied.append("router:protected:user_message")+ route_counts["user_msg"] += 1+ continue++ # Protection 1b: Never compress system messages (when disabled)+ if skip_system and role == "system":+ result_slots[i] = message+ transforms_applied.append("router:protected:system_message")+ route_counts.setdefault("system_msg", 0)+ route_counts["system_msg"] += 1+ continue++ if not content or tokenizer.count_text(content) < min_tokens:+ # Skip small content+ result_slots[i] = message+ route_counts["small"] += 1+ continue++ # Detect content type for protection decisions+ detection = _detect_content(content)+ is_code = detection.content_type == ContentType.SOURCE_CODE++ # Protection 2: Don't compress recent CODE+ messages_from_end = num_messages - i+ if protect_recent > 0 and messages_from_end <= protect_recent and is_code:+ result_slots[i] = message+ transforms_applied.append("router:protected:recent_code")+ route_counts["recent_code"] += 1+ continue++ # Protection 3: Don't compress CODE when analysis intent detected+ if protect_analysis and analysis_intent and is_code:+ result_slots[i] = message+ transforms_applied.append("router:protected:analysis_context")+ route_counts["analysis_ctx"] += 1+ continue++ # Compression pinning: if this message was already compressed+ # (contains a CCR retrieval marker), skip recompression.+ # Recompressing would change byte content and break provider+ # prefix caching with no meaningful further reduction.+ if "Retrieve more: hash=" in content or "Retrieve original: hash=" in content:+ result_slots[i] = message+ route_counts.setdefault("already_compressed", 0)+ route_counts["already_compressed"] += 1+ continue++ # Route and compress based on content detection+ # Merge tool-specific bias with hook-provided bias (multiplicative)+ msg_bias = bias if role == "tool" else 1.0+ if i in hook_biases:+ msg_bias *= hook_biases[i]++ # Two-tier compression cache.+ # Tier 1 (skip): known won't-compress → instant skip.+ # Tier 2 (result): known compresses → reuse compressed text.+ content_key = hash(content)++ # Tier 1: skip set — instant rejection+ if self._cache.is_skipped(content_key):+ result_slots[i] = message+ route_counts["ratio_too_high"] += 1+ route_counts.setdefault("cache_hit", 0)+ route_counts["cache_hit"] += 1+ continue++ # Tier 2: result cache — reuse compressed output+ cached = self._cache.get(content_key)+ if cached is not None:+ cached_compressed, cached_ratio, cached_strategy = cached+ # Re-check ratio against current min_ratio (shifts with context pressure)+ if cached_ratio < min_ratio:+ result_slots[i] = {**message, "content": cached_compressed}+ transforms_applied.append(f"router:{cached_strategy}:{cached_ratio:.2f}")+ compressed_details.append(f"{cached_strategy}:{cached_ratio:.2f}")+ else:+ # Threshold tightened — no longer qualifies. Move to skip.+ self._cache.move_to_skip(content_key)+ result_slots[i] = message+ route_counts["ratio_too_high"] += 1+ route_counts.setdefault("cache_hit", 0)+ route_counts["cache_hit"] += 1+ continue++ # Cache miss — defer to parallel compression pass+ route_counts.setdefault("cache_miss", 0)+ route_counts["cache_miss"] += 1+ pending_tasks.append((i, content, context, msg_bias, content_key))++ # --- Pass 2: Parallel compression of all cache-miss messages ---+ if pending_tasks:+ max_workers = min(+ len(pending_tasks), int(os.environ.get("HEADROOM_COMPRESS_WORKERS", "4"))+ )+ t_parallel_start = time.perf_counter()++ if max_workers <= 1 or len(pending_tasks) == 1:+ # Single task or parallelism disabled — compress inline+ task_results = []+ for _, task_content, task_ctx, task_bias, _ in pending_tasks:+ t0 = time.perf_counter()+ r = self.compress(task_content, context=task_ctx, bias=task_bias)+ task_results.append((r, (time.perf_counter() - t0) * 1000))+ else:+ # Parallel compression via thread pool+ with ThreadPoolExecutor(max_workers=max_workers) as executor:+ futures = []+ for _, task_content, task_ctx, task_bias, _ in pending_tasks:+ futures.append(+ executor.submit(self._timed_compress, task_content, task_ctx, task_bias)+ )+ task_results = [f.result() for f in futures]++ parallel_ms = (time.perf_counter() - t_parallel_start) * 1000+ compressor_timing["parallel_compress_total"] = parallel_ms++ # --- Pass 3: Merge results back (sequential, updates caches) ---+ for (slot_idx, _, _, _, content_key), (result, compress_ms) in zip(+ pending_tasks, task_results+ ):+ message = messages[slot_idx]+ strategy_key = f"compressor:{result.strategy_used.value}"+ compressor_timing[strategy_key] = (+ compressor_timing.get(strategy_key, 0.0) + compress_ms+ )++ if result.compression_ratio < min_ratio:+ # Compressed — store in result cache+ self._cache.put(+ content_key,+ result.compressed,+ result.compression_ratio,+ result.strategy_used.value,+ )+ result_slots[slot_idx] = {**message, "content": result.compressed}+ transforms_applied.append(+ f"router:{result.strategy_used.value}:{result.compression_ratio:.2f}"+ )+ compressed_details.append(+ f"{result.strategy_used.value}:{result.compression_ratio:.2f}"+ )+ else:+ # Didn't compress — add to skip set+ self._cache.mark_skip(content_key)+ result_slots[slot_idx] = message+ route_counts["ratio_too_high"] += 1++ # Build final message list from slots+ transformed_messages = [m for m in result_slots if m is not None]++ tokens_after = sum(+ tokenizer.count_text(str(m.get("content", ""))) for m in transformed_messages+ )++ # Log routing summary+ parts = []+ if compressed_details:+ parts.append(f"{len(compressed_details)} compressed ({', '.join(compressed_details)})")+ if route_counts["excluded_tool"]:+ parts.append(f"{route_counts['excluded_tool']} excluded (Read/Glob)")+ if route_counts["user_msg"]:+ parts.append(f"{route_counts['user_msg']} skipped (user)")+ if route_counts["small"]:+ parts.append(f"{route_counts['small']} skipped (<50 words)")+ if route_counts["recent_code"]:+ parts.append(f"{route_counts['recent_code']} protected (recent code)")+ if route_counts["analysis_ctx"]:+ parts.append(f"{route_counts['analysis_ctx']} protected (analysis ctx)")+ if route_counts.get("already_compressed"):+ parts.append(f"{route_counts['already_compressed']} pinned (already compressed)")+ if route_counts["ratio_too_high"]:+ parts.append(f"{route_counts['ratio_too_high']} unchanged (ratio>={min_ratio:.2f})")+ if route_counts["content_blocks"]:+ parts.append(f"{route_counts['content_blocks']} content-block msgs")+ if route_counts["non_string"]:+ parts.append(f"{route_counts['non_string']} non-string")+ if route_counts.get("cache_hit"):+ parts.append(f"{route_counts['cache_hit']} cache hits")+ if route_counts.get("cache_miss"):+ parts.append(f"{route_counts['cache_miss']} cache misses")+ cs = self._cache.stats+ if cs["cache_size"] > 0 or cs["cache_skip_size"] > 0:+ parts.append(+ f"cache[{cs['cache_size']} results, {cs['cache_skip_size']} skips, "+ f"{cs['cache_avg_lookup_ns']:.0f}ns avg]"+ )+ if parts:+ logger.info(+ "content_router: %d msgs — %s",+ num_messages,+ ", ".join(parts),+ )++ all_transforms = lifecycle_transforms + transforms_applied+ return TransformResult(+ messages=transformed_messages,+ tokens_before=tokens_before,+ tokens_after=tokens_after,+ transforms_applied=all_transforms if all_transforms else ["router:noop"],+ markers_inserted=lifecycle_ccr_hashes,+ warnings=warnings,+ timing=compressor_timing,+ )++ def _get_tool_bias(self, tool_name: str) -> float:+ """Look up compression bias for a tool name.++ Checks user-configured profiles first, then DEFAULT_TOOL_PROFILES.+ Returns 1.0 (moderate) if no profile is configured.+ """+ from ..config import DEFAULT_TOOL_PROFILES++ # Check user-configured profiles+ if self.config.tool_profiles:+ profile = self.config.tool_profiles.get(tool_name)+ if profile:+ return float(profile.bias)++ # Check default profiles+ profile = DEFAULT_TOOL_PROFILES.get(tool_name)+ if profile:+ return profile.bias++ return 1.0 # Default: moderate++ def _process_content_blocks(+ self,+ message: dict[str, Any],+ content_blocks: list[Any],+ context: str,+ transforms_applied: list[str],+ excluded_tool_ids: set[str],+ tool_name_map: dict[str, str] | None = None,+ route_counts: dict[str, int] | None = None,+ compressed_details: list[str] | None = None,+ min_ratio: float = 0.85,+ read_protection_window: int = 8,+ messages_from_end: int = 0,+ compressor_timing: dict[str, float] | None = None,+ ) -> dict[str, Any]:+ """Process content blocks (Anthropic format) for tool_result compression.++ Handles tool_result blocks by compressing their string content using+ the appropriate strategy (typically SmartCrusher for JSON arrays).++ Args:+ message: The original message.+ content_blocks: List of content blocks.+ context: Context for compression.+ transforms_applied: List to append transform names to.+ excluded_tool_ids: Tool IDs to skip compression for.+ tool_name_map: Mapping from tool_call_id to tool_name for profile lookup.+ route_counts: Optional routing reason counters to update.+ compressed_details: Optional list to append compression details to.+ min_ratio: Adaptive compression ratio threshold.+ read_protection_window: Messages from end within which excluded tools are protected.+ messages_from_end: How far this message is from the end of the conversation.++ Returns:+ Transformed message with compressed content blocks.+ """+ new_blocks = []+ any_compressed = False++ for block in content_blocks:+ if not isinstance(block, dict):+ new_blocks.append(block)+ continue++ block_type = block.get("type")++ # Handle tool_result blocks+ if block_type == "tool_result":+ # Check if tool is excluded from compression+ tool_use_id = block.get("tool_use_id", "")+ if tool_use_id in excluded_tool_ids:+ if messages_from_end <= read_protection_window:+ # Recent — protect as before+ new_blocks.append(block)+ transforms_applied.append("router:excluded:tool")+ if route_counts is not None:+ route_counts["excluded_tool"] += 1+ continue+ # Old excluded-tool output — fall through to compression++ # Look up tool-specific compression bias+ tool_name = (tool_name_map or {}).get(tool_use_id, "")+ bias = self._get_tool_bias(tool_name) if tool_name else 1.0++ tool_content = block.get("content", "")++ # Only process string content+ if isinstance(tool_content, str) and len(tool_content) > 500:+ # Compression pinning: skip already-compressed content+ if (+ "Retrieve more: hash=" in tool_content+ or "Retrieve original: hash=" in tool_content+ ):+ new_blocks.append(block)+ if route_counts is not None:+ route_counts.setdefault("already_compressed", 0)+ route_counts["already_compressed"] += 1+ continue++ # Two-tier compression cache+ content_key = hash(tool_content)++ # Tier 1: skip set — instant rejection+ if self._cache.is_skipped(content_key):+ new_blocks.append(block)+ if route_counts is not None:+ route_counts["ratio_too_high"] += 1+ route_counts.setdefault("cache_hit", 0)+ route_counts["cache_hit"] += 1+ continue++ # Tier 2: result cache — reuse compressed output+ cached = self._cache.get(content_key)+ if cached is not None:+ cached_compressed, cached_ratio, cached_strategy = cached+ if cached_ratio < min_ratio:+ new_blocks.append({**block, "content": cached_compressed})+ transforms_applied.append(f"router:tool_result:{cached_strategy}")+ if compressed_details is not None:+ compressed_details.append(+ f"tool:{cached_strategy}:{cached_ratio:.2f}"+ )+ any_compressed = True+ else:+ # Threshold tightened — move to skip+ self._cache.move_to_skip(content_key)+ new_blocks.append(block)+ if route_counts is not None:+ route_counts["ratio_too_high"] += 1+ if route_counts is not None:+ route_counts.setdefault("cache_hit", 0)+ route_counts["cache_hit"] += 1+ continue++ # Cache miss — run full compression+ if route_counts is not None:+ route_counts.setdefault("cache_miss", 0)+ route_counts["cache_miss"] += 1+ t0 = time.perf_counter()+ result = self.compress(tool_content, context=context, bias=bias)+ compress_ms = (time.perf_counter() - t0) * 1000+ if compressor_timing is not None:+ key = f"compressor:{result.strategy_used.value}"+ compressor_timing[key] = compressor_timing.get(key, 0.0) + compress_ms+ if result.compression_ratio < min_ratio:+ # Compressed — store in result cache+ self._cache.put(+ content_key,+ result.compressed,+ result.compression_ratio,+ result.strategy_used.value,+ )+ new_blocks.append({**block, "content": result.compressed})+ transforms_applied.append(+ f"router:tool_result:{result.strategy_used.value}"+ )+ if compressed_details is not None:+ compressed_details.append(+ f"tool:{result.strategy_used.value}:{result.compression_ratio:.2f}"+ )+ any_compressed = True+ continue+ else:+ # Didn't compress — add to skip set+ self._cache.mark_skip(content_key)+ if route_counts is not None:+ route_counts["ratio_too_high"] += 1+ else:+ if route_counts is not None:+ route_counts["small"] += 1++ # Keep block unchanged+ new_blocks.append(block)++ if any_compressed:+ return {**message, "content": new_blocks}+ return message++ def _detect_analysis_intent(self, messages: list[dict[str, Any]]) -> bool:+ """Detect if user wants to analyze/review code.++ Looks at the most recent user message for analysis keywords.++ Args:+ messages: Conversation messages.++ Returns:+ True if analysis intent detected.+ """+ # Analysis keywords that suggest user wants full code details+ analysis_keywords = {+ "analyze",+ "analyse",+ "review",+ "audit",+ "inspect",+ "security",+ "vulnerability",+ "bug",+ "issue",+ "problem",+ "explain",+ "understand",+ "how does",+ "what does",+ "debug",+ "fix",+ "error",+ "wrong",+ "broken",+ "refactor",+ "improve",+ "optimize",+ "clean up",+ }++ # Find most recent user message+ for message in reversed(messages):+ if message.get("role") == "user":+ content = message.get("content", "")+ if isinstance(content, str):+ content_lower = content.lower()+ for keyword in analysis_keywords:+ if keyword in content_lower:+ return True+ break++ return False++ def should_apply(+ self,+ messages: list[dict[str, Any]],+ tokenizer: Tokenizer,+ **kwargs: Any,+ ) -> bool:+ """Check if routing should be applied.++ Always returns True - the router handles all content types.+ """+ return True+++def route_and_compress(+ content: str,+ context: str = "",+) -> str:+ """Convenience function for one-off routing and compression.++ Args:+ content: Content to compress.+ context: Optional context for relevance-aware compression.++ Returns:+ Compressed content.++ Example:+ >>> compressed = route_and_compress(mixed_content)+ """+ router = ContentRouter()+ result = router.compress(content, context=context)+ return result.compresseddiff --git a/scripts/changelog-gen.py b/scripts/changelog-gen.pyindex 761591643..3364e1794 100644--- a/scripts/changelog-gen.py+++ b/scripts/changelog-gen.py@@ -1,203 +1,203 @@-#!/usr/bin/env python3-"""Generate changelog from conventional commits."""--from __future__ import annotations--import argparse-import re-import subprocess-from datetime import date-from pathlib import Path-from typing import NamedTuple--ROOT = Path(__file__).parent.parent--COMMIT_PATTERN = re.compile(- r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"-)-BREAKING_CHANGE_PATTERN = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)-COMMIT_ENTRY_PATTERN = re.compile(r"^(.+?)(?:\n(.+))?\|(\w+)$", re.MULTILINE)-FIELD_SEP = "\x1f"-RECORD_SEP = "\x1e"-GIT_LOG_FORMAT = "%s%x1f%b%x1f%h%x1e"--TYPE_LABELS: dict[str, str] = {- "feat": "Features",- "fix": "Bug Fixes",- "ci": "CI/CD",- "chore": "Chores",- "perf": "Performance",- "refactor": "Refactors",- "docs": "Documentation",- "style": "Styles",- "test": "Tests",- "other": "Other Changes",-}---class ParsedCommit(NamedTuple):- type: str- scope: str | None- breaking: bool- message: str- hash: str---def iter_commit_entries(log_output: str) -> list[tuple[str, str, str]]:- """Split raw git log output into (subject, body, hash) tuples."""-- if not log_output.strip():- return []-- if RECORD_SEP in log_output and FIELD_SEP in log_output:- entries: list[tuple[str, str, str]] = []- for raw_entry in log_output.split(RECORD_SEP):- if not raw_entry:- continue- if FIELD_SEP not in raw_entry:- continue- subject, body_and_hash = raw_entry.split(FIELD_SEP, 1)- if FIELD_SEP not in body_and_hash:- continue- body, commit_hash = body_and_hash.rsplit(FIELD_SEP, 1)- entries.append((subject.strip(), body.strip(), commit_hash.strip()))- return entries-- return [- (- match.group(1).strip(),- (match.group(2) or "").strip(),- match.group(3).strip(),- )- for match in COMMIT_ENTRY_PATTERN.finditer(log_output)- ]---def get_merge_summary(subject: str, body: str) -> str:- """Return the first meaningful summary line for a merge commit."""-- if not subject.startswith("Merge "):- return ""-- for line in body.splitlines():- stripped = line.strip()- if stripped:- return stripped- return ""---def parse_commits(log_output: str) -> list[ParsedCommit]:- """Parse git log output into structured commits."""-- commits: list[ParsedCommit] = []-- for subject, body, commit_hash in iter_commit_entries(log_output):- is_breaking = bool(BREAKING_CHANGE_PATTERN.search(body))- merge_summary = get_merge_summary(subject, body)- candidates = [subject]- if merge_summary:- candidates.insert(0, merge_summary)-- for candidate in candidates:- commit_match = COMMIT_PATTERN.match(candidate)- if not commit_match:- continue-- scope = commit_match.group(2)- if scope:- scope = scope[1:-1]- commits.append(- ParsedCommit(- type=commit_match.group(1),- scope=scope,- breaking=is_breaking or bool(commit_match.group(3)),- message=commit_match.group(4),- hash=commit_hash,- )- )- break- else:- fallback_message = merge_summary or subject- if not fallback_message or fallback_message.startswith("Merge "):- continue- commits.append(- ParsedCommit(- type="other",- scope=None,- breaking=is_breaking,- message=fallback_message,- hash=commit_hash,- )- )-- return commits---def generate_changelog(version: str, commits: list[ParsedCommit]) -> str:- """Generate markdown changelog from parsed commits."""- today = date.today().isoformat()- lines = [f"## [{version}] - {today}", ""]-- # Collect breaking changes- breaking_commits = [c for c in commits if c.breaking]- if breaking_commits:- lines.append("### Breaking Changes")- for commit in breaking_commits:- if commit.scope:- lines.append(f"- **{commit.scope}**: {commit.message} ({commit.hash})")- else:- lines.append(f"- {commit.message} ({commit.hash})")- lines.append("")-- # Group by type- by_type: dict[str, list[ParsedCommit]] = {}- for commit in commits:- by_type.setdefault(commit.type, []).append(commit)-- for commit_type, label in TYPE_LABELS.items():- type_commits = by_type.get(commit_type, [])- if not type_commits:- continue- lines.append(f"### {label}")- for commit in type_commits:- if commit.scope:- lines.append(f"- **{commit.scope}**: {commit.message} ({commit.hash})")- else:- lines.append(f"- {commit.message} ({commit.hash})")- lines.append("")-- return "\n".join(lines) + "\n"---def run_git_log(since: str | None, cwd: Path) -> str:- """Run git log command and return output."""- cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]- if since:- cmd.append(f"{since}..HEAD")- else:- cmd.append("HEAD")- result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)- return result.stdout---def main() -> None:- parser = argparse.ArgumentParser(description="Generate changelog from conventional commits")- parser.add_argument("--version", required=True, help="Version number (e.g., 0.6.0)")- parser.add_argument("--since", help="Starting tag (exclusive)")- parser.add_argument("--dry-run", action="store_true", help="Print to stdout instead of writing")- args = parser.parse_args()-- log_output = run_git_log(args.since, ROOT)- commits = parse_commits(log_output)- changelog = generate_changelog(args.version, commits)-- if args.dry_run:- print(changelog)- else:- output_path = ROOT / ".changelog.md"- output_path.write_text(changelog, encoding="utf-8")- print(f"Changelog written to {output_path}")---if __name__ == "__main__":- main()+#!/usr/bin/env python3+"""Generate changelog from conventional commits."""++from __future__ import annotations++import argparse+import re+import subprocess+from datetime import date+from pathlib import Path+from typing import NamedTuple++ROOT = Path(__file__).parent.parent++COMMIT_PATTERN = re.compile(+ r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"+)+BREAKING_CHANGE_PATTERN = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)+COMMIT_ENTRY_PATTERN = re.compile(r"^(.+?)(?:\n(.+))?\|(\w+)$", re.MULTILINE)+FIELD_SEP = "\x1f"+RECORD_SEP = "\x1e"+GIT_LOG_FORMAT = "%s%x1f%b%x1f%h%x1e"++TYPE_LABELS: dict[str, str] = {+ "feat": "Features",+ "fix": "Bug Fixes",+ "ci": "CI/CD",+ "chore": "Chores",+ "perf": "Performance",+ "refactor": "Refactors",+ "docs": "Documentation",+ "style": "Styles",+ "test": "Tests",+ "other": "Other Changes",+}+++class ParsedCommit(NamedTuple):+ type: str+ scope: str | None+ breaking: bool+ message: str+ hash: str+++def iter_commit_entries(log_output: str) -> list[tuple[str, str, str]]:+ """Split raw git log output into (subject, body, hash) tuples."""++ if not log_output.strip():+ return []++ if RECORD_SEP in log_output and FIELD_SEP in log_output:+ entries: list[tuple[str, str, str]] = []+ for raw_entry in log_output.split(RECORD_SEP):+ if not raw_entry:+ continue+ if FIELD_SEP not in raw_entry:+ continue+ subject, body_and_hash = raw_entry.split(FIELD_SEP, 1)+ if FIELD_SEP not in body_and_hash:+ continue+ body, commit_hash = body_and_hash.rsplit(FIELD_SEP, 1)+ entries.append((subject.strip(), body.strip(), commit_hash.strip()))+ return entries++ return [+ (+ match.group(1).strip(),+ (match.group(2) or "").strip(),+ match.group(3).strip(),+ )+ for match in COMMIT_ENTRY_PATTERN.finditer(log_output)+ ]+++def get_merge_summary(subject: str, body: str) -> str:+ """Return the first meaningful summary line for a merge commit."""++ if not subject.startswith("Merge "):+ return ""++ for line in body.splitlines():+ stripped = line.strip()+ if stripped:+ return stripped+ return ""+++def parse_commits(log_output: str) -> list[ParsedCommit]:+ """Parse git log output into structured commits."""++ commits: list[ParsedCommit] = []++ for subject, body, commit_hash in iter_commit_entries(log_output):+ is_breaking = bool(BREAKING_CHANGE_PATTERN.search(body))+ merge_summary = get_merge_summary(subject, body)+ candidates = [subject]+ if merge_summary:+ candidates.insert(0, merge_summary)++ for candidate in candidates:+ commit_match = COMMIT_PATTERN.match(candidate)+ if not commit_match:+ continue++ scope = commit_match.group(2)+ if scope:+ scope = scope[1:-1]+ commits.append(+ ParsedCommit(+ type=commit_match.group(1),+ scope=scope,+ breaking=is_breaking or bool(commit_match.group(3)),+ message=commit_match.group(4),+ hash=commit_hash,+ )+ )+ break+ else:+ fallback_message = merge_summary or subject+ if not fallback_message or fallback_message.startswith("Merge "):+ continue+ commits.append(+ ParsedCommit(+ type="other",+ scope=None,+ breaking=is_breaking,+ message=fallback_message,+ hash=commit_hash,+ )+ )++ return commits+++def generate_changelog(version: str, commits: list[ParsedCommit]) -> str:+ """Generate markdown changelog from parsed commits."""+ today = date.today().isoformat()+ lines = [f"## [{version}] - {today}", ""]++ # Collect breaking changes+ breaking_commits = [c for c in commits if c.breaking]+ if breaking_commits:+ lines.append("### Breaking Changes")+ for commit in breaking_commits:+ if commit.scope:+ lines.append(f"- **{commit.scope}**: {commit.message} ({commit.hash})")+ else:+ lines.append(f"- {commit.message} ({commit.hash})")+ lines.append("")++ # Group by type+ by_type: dict[str, list[ParsedCommit]] = {}+ for commit in commits:+ by_type.setdefault(commit.type, []).append(commit)++ for commit_type, label in TYPE_LABELS.items():+ type_commits = by_type.get(commit_type, [])+ if not type_commits:+ continue+ lines.append(f"### {label}")+ for commit in type_commits:+ if commit.scope:+ lines.append(f"- **{commit.scope}**: {commit.message} ({commit.hash})")+ else:+ lines.append(f"- {commit.message} ({commit.hash})")+ lines.append("")++ return "\n".join(lines) + "\n"+++def run_git_log(since: str | None, cwd: Path) -> str:+ """Run git log command and return output."""+ cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]+ if since:+ cmd.append(f"{since}..HEAD")+ else:+ cmd.append("HEAD")+ result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)+ return result.stdout+++def main() -> None:+ parser = argparse.ArgumentParser(description="Generate changelog from conventional commits")+ parser.add_argument("--version", required=True, help="Version number (e.g., 0.6.0)")+ parser.add_argument("--since", help="Starting tag (exclusive)")+ parser.add_argument("--dry-run", action="store_true", help="Print to stdout instead of writing")+ args = parser.parse_args()++ log_output = run_git_log(args.since, ROOT)+ commits = parse_commits(log_output)+ changelog = generate_changelog(args.version, commits)++ if args.dry_run:+ print(changelog)+ else:+ output_path = ROOT / ".changelog.md"+ output_path.write_text(changelog, encoding="utf-8")+ print(f"Changelog written to {output_path}")+++if __name__ == "__main__":+ main()diff --git a/scripts/sync-plugin-versions.py b/scripts/sync-plugin-versions.pyindex e26217226..b8d88d4f1 100644--- a/scripts/sync-plugin-versions.py+++ b/scripts/sync-plugin-versions.py@@ -1,55 +1,55 @@-"""Sync plugin manifest versions to the repo's computed release semver."""--from __future__ import annotations--import subprocess-import sys-from pathlib import Path--ROOT = Path(__file__).resolve().parent.parent-if str(ROOT) not in sys.path:- sys.path.insert(0, str(ROOT))--from headroom.release_version import ( # noqa: E402- compute_release_version,- determine_bump_level,- find_latest_release_tag,- get_canonical_version,- list_release_commits,- list_release_tags,-)---def compute_repo_semver(root: Path) -> str:- """Return the npm-style semver for the repo's next release."""- tags = list_release_tags(root)- previous_tag = find_latest_release_tag(tags) or ""- level = determine_bump_level(list_release_commits(root, previous_tag))- info = compute_release_version(- canonical_version=get_canonical_version(root),- level=level,- tags=tags,- )- return info.npm_version---def main() -> None:- root = ROOT- version = compute_repo_semver(root)- subprocess.run(- [- sys.executable,- str(root / "scripts" / "version-sync.py"),- "--root",- str(root),- "--version",- version,- "--plugin-manifests-only",- ],- cwd=root,- check=True,- )---if __name__ == "__main__":- main()+"""Sync plugin manifest versions to the repo's computed release semver."""++from __future__ import annotations++import subprocess+import sys+from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent+if str(ROOT) not in sys.path:+ sys.path.insert(0, str(ROOT))++from headroom.release_version import ( # noqa: E402+ compute_release_version,+ determine_bump_level,+ find_latest_release_tag,+ get_canonical_version,+ list_release_commits,+ list_release_tags,+)+++def compute_repo_semver(root: Path) -> str:+ """Return the npm-style semver for the repo's next release."""+ tags = list_release_tags(root)+ previous_tag = find_latest_release_tag(tags) or ""+ level = determine_bump_level(list_release_commits(root, previous_tag))+ info = compute_release_version(+ canonical_version=get_canonical_version(root),+ level=level,+ tags=tags,+ )+ return info.npm_version+++def main() -> None:+ root = ROOT+ version = compute_repo_semver(root)+ subprocess.run(+ [+ sys.executable,+ str(root / "scripts" / "version-sync.py"),+ "--root",+ str(root),+ "--version",+ version,+ "--plugin-manifests-only",+ ],+ cwd=root,+ check=True,+ )+++if __name__ == "__main__":+ main()diff --git a/scripts/tests/test_changelog_gen.py b/scripts/tests/test_changelog_gen.pyindex 00ba618a8..cca0022e8 100644--- a/scripts/tests/test_changelog_gen.py+++ b/scripts/tests/test_changelog_gen.py@@ -1,302 +1,302 @@-"""Tests for changelog-gen.py."""--from __future__ import annotations--import importlib.util-from pathlib import Path--import pytest--ROOT = Path(__file__).resolve().parent.parent.parent--# Load changelog_gen module from scripts directory (filename has hyphen)-_spec = importlib.util.spec_from_file_location(- "changelog_gen", ROOT / "scripts" / "changelog-gen.py"-)-if _spec is None:- raise ImportError("Could not load changelog_gen module")-_changelog_gen = importlib.util.module_from_spec(_spec)-if _spec.loader is None:- raise ImportError("Could not load changelog_gen module")-_spec.loader.exec_module(_changelog_gen)--COMMIT_PATTERN = _changelog_gen.COMMIT_PATTERN-BREAKING_CHANGE_PATTERN = _changelog_gen.BREAKING_CHANGE_PATTERN-FIELD_SEP = _changelog_gen.FIELD_SEP-RECORD_SEP = _changelog_gen.RECORD_SEP-ParsedCommit = _changelog_gen.ParsedCommit-generate_changelog = _changelog_gen.generate_changelog-iter_commit_entries = _changelog_gen.iter_commit_entries-parse_commits = _changelog_gen.parse_commits---def make_log_entry(subject: str, commit_hash: str, body: str = "") -> str:- return f"{subject}{FIELD_SEP}{body}{FIELD_SEP}{commit_hash}{RECORD_SEP}"---class TestParseCommits:- """Tests for parse_commits function."""-- def test_parses_feat_commit(self) -> None:- log_output = make_log_entry("feat(core): add feature", "abc1234")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "feat"- assert commits[0].scope == "core"- assert commits[0].message == "add feature"- assert commits[0].hash == "abc1234"- assert commits[0].breaking is False-- def test_parses_fix_commit(self) -> None:- log_output = make_log_entry("fix(ui): fix bug", "def5678")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "fix"- assert commits[0].scope == "ui"- assert commits[0].message == "fix bug"- assert commits[0].hash == "def5678"-- def test_parses_ci_commit(self) -> None:- log_output = make_log_entry("ci: update github actions", "xyz789")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "ci"- assert commits[0].scope is None- assert commits[0].message == "update github actions"- assert commits[0].hash == "xyz789"-- def test_parses_chore_commit(self) -> None:- log_output = make_log_entry("chore: cleanup", "xyz999")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "chore"- assert commits[0].scope is None-- def test_parses_perf_commit(self) -> None:- log_output = make_log_entry("perf(dashboard): improve performance", "abc111")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "perf"- assert commits[0].scope == "dashboard"-- def test_parses_refactor_commit(self) -> None:- log_output = make_log_entry("refactor(api): refactor endpoint", "abc222")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "refactor"- assert commits[0].scope == "api"-- def test_parses_docs_commit(self) -> None:- log_output = make_log_entry("docs: update readme", "abc333")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "docs"-- def test_parses_style_commit(self) -> None:- log_output = make_log_entry("style: format code", "abc444")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "style"-- def test_parses_test_commit(self) -> None:- log_output = make_log_entry("test: add tests for feature", "abc555")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "test"-- def test_detects_breaking_change_in_body(self) -> None:- log_output = make_log_entry(- "feat(core): add feature",- "abc666",- "BREAKING CHANGE: api changed",- )- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].breaking is True-- def test_detects_breaking_change_exclamation(self) -> None:- log_output = make_log_entry("feat(core)!: api changed", "abc777")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].breaking is True-- def test_no_scope_no_problem(self) -> None:- log_output = make_log_entry("feat: simple feature", "abc888")- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].scope is None- assert commits[0].message == "simple feature"-- def test_uses_pr_title_from_merge_commit_body(self) -> None:- log_output = make_log_entry(- "Merge pull request #173 from JerrettDavis/fix/pipeline-permissions-and-docs",- "73f6673",- "fix: repair release and docs pipelines",- )- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "fix"- assert commits[0].message == "repair release and docs pipelines"-- def test_falls_back_to_other_changes_for_non_conventional_merge(self) -> None:- log_output = make_log_entry(- "Merge pull request #186 from skorokithakis/patch-1",- "1e80ee3",- "Add support for custom Anthropic API URL",- )- commits = parse_commits(log_output)- assert len(commits) == 1- assert commits[0].type == "other"- assert commits[0].message == "Add support for custom Anthropic API URL"-- def test_iter_commit_entries_parses_real_git_log_delimiters(self) -> None:- log_output = make_log_entry(- "fix: patch release flow", "abc1234", "BREAKING CHANGE: no"- ) + make_log_entry("docs: update readme", "def5678")- assert iter_commit_entries(log_output) == [- ("fix: patch release flow", "BREAKING CHANGE: no", "abc1234"),- ("docs: update readme", "", "def5678"),- ]-- def test_iter_commit_entries_keeps_field_separator_inside_body(self) -> None:- body = f"line one{FIELD_SEP}line two"- log_output = make_log_entry("fix: patch release flow", "abc1234", body)- assert iter_commit_entries(log_output) == [- ("fix: patch release flow", body, "abc1234"),- ]---class TestGenerateChangelog:- """Tests for generate_changelog function."""-- def test_generates_version_header(self) -> None:- commits = [- ParsedCommit(type="feat", scope=None, breaking=False, message="test", hash="abc123")- ]- result = generate_changelog("0.6.0", commits)- assert "## [0.6.0]" in result-- def test_includes_date(self) -> None:- commits = []- result = generate_changelog("0.6.0", commits)- import re-- date_match = re.search(r"\d{4}-\d{2}-\d{2}", result)- assert date_match is not None-- def test_groups_by_type(self) -> None:- commits = [- ParsedCommit(- type="feat", scope=None, breaking=False, message="add feature", hash="abc123"- ),- ParsedCommit(type="fix", scope=None, breaking=False, message="fix bug", hash="def456"),- ]- result = generate_changelog("0.6.0", commits)- assert "### Features" in result- assert "### Bug Fixes" in result- assert "- add feature (abc123)" in result- assert "- fix bug (def456)" in result-- def test_includes_scope_in_bullet(self) -> None:- commits = [- ParsedCommit(- type="feat", scope="core", breaking=False, message="add feature", hash="abc123"- )- ]- result = generate_changelog("0.6.0", commits)- assert "- **core**: add feature (abc123)" in result-- def test_breaking_change_section_when_present(self) -> None:- commits = [- ParsedCommit(- type="feat", scope="core", breaking=True, message="api changed", hash="abc123"- )- ]- result = generate_changelog("0.6.0", commits)- assert "### Breaking Changes" in result- assert "**core**" in result-- def test_no_breaking_change_section_when_none(self) -> None:- commits = [- ParsedCommit(- type="feat", scope=None, breaking=False, message="add feature", hash="abc123"- )- ]- result = generate_changelog("0.6.0", commits)- assert "Breaking Changes" not in result-- def test_includes_other_changes_section(self) -> None:- commits = [- ParsedCommit(- type="other",- scope=None,- breaking=False,- message="Add support for custom Anthropic API URL",- hash="abc123",- )- ]- result = generate_changelog("0.6.0", commits)- assert "### Other Changes" in result- assert "- Add support for custom Anthropic API URL (abc123)" in result---class TestIntegrationWithMock:- """Integration tests with mocked subprocess.run."""-- def test_full_flow_with_mocked_git(self) -> None:- log_output = (- make_log_entry("feat(core): add new feature", "abc1234")- + make_log_entry("fix(ui): fix bug", "def5678")- + make_log_entry("ci: update github actions", "xyz789")- + make_log_entry(- "feat(outer): breaking change", "bbb111", "BREAKING CHANGE: this is breaking"- )- + make_log_entry("chore: cleanup", "yyy999")- )- commits = parse_commits(log_output)-- assert len(commits) == 5- assert any(c.type == "feat" and c.scope == "core" for c in commits)- assert any(c.type == "fix" and c.scope == "ui" for c in commits)- assert any(c.type == "ci" for c in commits)- assert any(c.type == "feat" and c.breaking for c in commits)- assert any(c.type == "chore" for c in commits)-- changelog = generate_changelog("0.7.0", commits)- assert "## [0.7.0]" in changelog- assert "### Features" in changelog- assert "### Bug Fixes" in changelog- assert "### CI/CD" in changelog- assert "### Breaking Changes" in changelog---class TestCommitPattern:- """Tests for the commit regex pattern."""-- def test_feat_with_scope(self) -> None:- match = COMMIT_PATTERN.match("feat(core): add feature")- assert match is not None- assert match.group(1) == "feat"- assert match.group(2) == "(core)"- assert match.group(4) == "add feature"-- def test_fix_without_scope(self) -> None:- match = COMMIT_PATTERN.match("fix: fix bug")- assert match is not None- assert match.group(1) == "fix"- assert match.group(2) is None- assert match.group(4) == "fix bug"-- def test_with_exclamation(self) -> None:- match = COMMIT_PATTERN.match("feat(core)!: api changed")- assert match is not None- assert match.group(3) == "!"-- def test_without_exclamation(self) -> None:- match = COMMIT_PATTERN.match("feat(core): add feature")- assert match is not None- assert match.group(3) is None---if __name__ == "__main__":- pytest.main([__file__, "-v"])+"""Tests for changelog-gen.py."""++from __future__ import annotations++import importlib.util+from pathlib import Path++import pytest++ROOT = Path(__file__).resolve().parent.parent.parent++# Load changelog_gen module from scripts directory (filename has hyphen)+_spec = importlib.util.spec_from_file_location(+ "changelog_gen", ROOT / "scripts" / "changelog-gen.py"+)+if _spec is None:+ raise ImportError("Could not load changelog_gen module")+_changelog_gen = importlib.util.module_from_spec(_spec)+if _spec.loader is None:+ raise ImportError("Could not load changelog_gen module")+_spec.loader.exec_module(_changelog_gen)++COMMIT_PATTERN = _changelog_gen.COMMIT_PATTERN+BREAKING_CHANGE_PATTERN = _changelog_gen.BREAKING_CHANGE_PATTERN+FIELD_SEP = _changelog_gen.FIELD_SEP+RECORD_SEP = _changelog_gen.RECORD_SEP+ParsedCommit = _changelog_gen.ParsedCommit+generate_changelog = _changelog_gen.generate_changelog+iter_commit_entries = _changelog_gen.iter_commit_entries+parse_commits = _changelog_gen.parse_commits+++def make_log_entry(subject: str, commit_hash: str, body: str = "") -> str:+ return f"{subject}{FIELD_SEP}{body}{FIELD_SEP}{commit_hash}{RECORD_SEP}"+++class TestParseCommits:+ """Tests for parse_commits function."""++ def test_parses_feat_commit(self) -> None:+ log_output = make_log_entry("feat(core): add feature", "abc1234")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "feat"+ assert commits[0].scope == "core"+ assert commits[0].message == "add feature"+ assert commits[0].hash == "abc1234"+ assert commits[0].breaking is False++ def test_parses_fix_commit(self) -> None:+ log_output = make_log_entry("fix(ui): fix bug", "def5678")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "fix"+ assert commits[0].scope == "ui"+ assert commits[0].message == "fix bug"+ assert commits[0].hash == "def5678"++ def test_parses_ci_commit(self) -> None:+ log_output = make_log_entry("ci: update github actions", "xyz789")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "ci"+ assert commits[0].scope is None+ assert commits[0].message == "update github actions"+ assert commits[0].hash == "xyz789"++ def test_parses_chore_commit(self) -> None:+ log_output = make_log_entry("chore: cleanup", "xyz999")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "chore"+ assert commits[0].scope is None++ def test_parses_perf_commit(self) -> None:+ log_output = make_log_entry("perf(dashboard): improve performance", "abc111")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "perf"+ assert commits[0].scope == "dashboard"++ def test_parses_refactor_commit(self) -> None:+ log_output = make_log_entry("refactor(api): refactor endpoint", "abc222")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "refactor"+ assert commits[0].scope == "api"++ def test_parses_docs_commit(self) -> None:+ log_output = make_log_entry("docs: update readme", "abc333")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "docs"++ def test_parses_style_commit(self) -> None:+ log_output = make_log_entry("style: format code", "abc444")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "style"++ def test_parses_test_commit(self) -> None:+ log_output = make_log_entry("test: add tests for feature", "abc555")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "test"++ def test_detects_breaking_change_in_body(self) -> None:+ log_output = make_log_entry(+ "feat(core): add feature",+ "abc666",+ "BREAKING CHANGE: api changed",+ )+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].breaking is True++ def test_detects_breaking_change_exclamation(self) -> None:+ log_output = make_log_entry("feat(core)!: api changed", "abc777")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].breaking is True++ def test_no_scope_no_problem(self) -> None:+ log_output = make_log_entry("feat: simple feature", "abc888")+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].scope is None+ assert commits[0].message == "simple feature"++ def test_uses_pr_title_from_merge_commit_body(self) -> None:+ log_output = make_log_entry(+ "Merge pull request #173 from JerrettDavis/fix/pipeline-permissions-and-docs",+ "73f6673",+ "fix: repair release and docs pipelines",+ )+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "fix"+ assert commits[0].message == "repair release and docs pipelines"++ def test_falls_back_to_other_changes_for_non_conventional_merge(self) -> None:+ log_output = make_log_entry(+ "Merge pull request #186 from skorokithakis/patch-1",+ "1e80ee3",+ "Add support for custom Anthropic API URL",+ )+ commits = parse_commits(log_output)+ assert len(commits) == 1+ assert commits[0].type == "other"+ assert commits[0].message == "Add support for custom Anthropic API URL"++ def test_iter_commit_entries_parses_real_git_log_delimiters(self) -> None:+ log_output = make_log_entry(+ "fix: patch release flow", "abc1234", "BREAKING CHANGE: no"+ ) + make_log_entry("docs: update readme", "def5678")+ assert iter_commit_entries(log_output) == [+ ("fix: patch release flow", "BREAKING CHANGE: no", "abc1234"),+ ("docs: update readme", "", "def5678"),+ ]++ def test_iter_commit_entries_keeps_field_separator_inside_body(self) -> None:+ body = f"line one{FIELD_SEP}line two"+ log_output = make_log_entry("fix: patch release flow", "abc1234", body)+ assert iter_commit_entries(log_output) == [+ ("fix: patch release flow", body, "abc1234"),+ ]+++class TestGenerateChangelog:+ """Tests for generate_changelog function."""++ def test_generates_version_header(self) -> None:+ commits = [+ ParsedCommit(type="feat", scope=None, breaking=False, message="test", hash="abc123")+ ]+ result = generate_changelog("0.6.0", commits)+ assert "## [0.6.0]" in result++ def test_includes_date(self) -> None:+ commits = []+ result = generate_changelog("0.6.0", commits)+ import re++ date_match = re.search(r"\d{4}-\d{2}-\d{2}", result)+ assert date_match is not None++ def test_groups_by_type(self) -> None:+ commits = [+ ParsedCommit(+ type="feat", scope=None, breaking=False, message="add feature", hash="abc123"+ ),+ ParsedCommit(type="fix", scope=None, breaking=False, message="fix bug", hash="def456"),+ ]+ result = generate_changelog("0.6.0", commits)+ assert "### Features" in result+ assert "### Bug Fixes" in result+ assert "- add feature (abc123)" in result+ assert "- fix bug (def456)" in result++ def test_includes_scope_in_bullet(self) -> None:+ commits = [+ ParsedCommit(+ type="feat", scope="core", breaking=False, message="add feature", hash="abc123"+ )+ ]+ result = generate_changelog("0.6.0", commits)+ assert "- **core**: add feature (abc123)" in result++ def test_breaking_change_section_when_present(self) -> None:+ commits = [+ ParsedCommit(+ type="feat", scope="core", breaking=True, message="api changed", hash="abc123"+ )+ ]+ result = generate_changelog("0.6.0", commits)+ assert "### Breaking Changes" in result+ assert "**core**" in result++ def test_no_breaking_change_section_when_none(self) -> None:+ commits = [+ ParsedCommit(+ type="feat", scope=None, breaking=False, message="add feature", hash="abc123"+ )+ ]+ result = generate_changelog("0.6.0", commits)+ assert "Breaking Changes" not in result++ def test_includes_other_changes_section(self) -> None:+ commits = [+ ParsedCommit(+ type="other",+ scope=None,+ breaking=False,+ message="Add support for custom Anthropic API URL",+ hash="abc123",+ )+ ]+ result = generate_changelog("0.6.0", commits)+ assert "### Other Changes" in result+ assert "- Add support for custom Anthropic API URL (abc123)" in result+++class TestIntegrationWithMock:+ """Integration tests with mocked subprocess.run."""++ def test_full_flow_with_mocked_git(self) -> None:+ log_output = (+ make_log_entry("feat(core): add new feature", "abc1234")+ + make_log_entry("fix(ui): fix bug", "def5678")+ + make_log_entry("ci: update github actions", "xyz789")+ + make_log_entry(+ "feat(outer): breaking change", "bbb111", "BREAKING CHANGE: this is breaking"+ )+ + make_log_entry("chore: cleanup", "yyy999")+ )+ commits = parse_commits(log_output)++ assert len(commits) == 5+ assert any(c.type == "feat" and c.scope == "core" for c in commits)+ assert any(c.type == "fix" and c.scope == "ui" for c in commits)+ assert any(c.type == "ci" for c in commits)+ assert any(c.type == "feat" and c.breaking for c in commits)+ assert any(c.type == "chore" for c in commits)++ changelog = generate_changelog("0.7.0", commits)+ assert "## [0.7.0]" in changelog+ assert "### Features" in changelog+ assert "### Bug Fixes" in changelog+ assert "### CI/CD" in changelog+ assert "### Breaking Changes" in changelog+++class TestCommitPattern:+ """Tests for the commit regex pattern."""++ def test_feat_with_scope(self) -> None:+ match = COMMIT_PATTERN.match("feat(core): add feature")+ assert match is not None+ assert match.group(1) == "feat"+ assert match.group(2) == "(core)"+ assert match.group(4) == "add feature"++ def test_fix_without_scope(self) -> None:+ match = COMMIT_PATTERN.match("fix: fix bug")+ assert match is not None+ assert match.group(1) == "fix"+ assert match.group(2) is None+ assert match.group(4) == "fix bug"++ def test_with_exclamation(self) -> None:+ match = COMMIT_PATTERN.match("feat(core)!: api changed")+ assert match is not None+ assert match.group(3) == "!"++ def test_without_exclamation(self) -> None:+ match = COMMIT_PATTERN.match("feat(core): add feature")+ assert match is not None+ assert match.group(3) is None+++if __name__ == "__main__":+ pytest.main([__file__, "-v"])diff --git a/scripts/tests/test_sync_plugin_versions.py b/scripts/tests/test_sync_plugin_versions.pyindex 66c2361e5..5d1e6bff1 100644--- a/scripts/tests/test_sync_plugin_versions.py+++ b/scripts/tests/test_sync_plugin_versions.py@@ -1,68 +1,68 @@-"""Tests for sync-plugin-versions.py."""--from __future__ import annotations--import importlib.util-from pathlib import Path---def _load_module():- script = Path(__file__).parent.parent / "sync-plugin-versions.py"- spec = importlib.util.spec_from_file_location("sync_plugin_versions", script)- assert spec is not None- assert spec.loader is not None- module = importlib.util.module_from_spec(spec)- spec.loader.exec_module(module)- return module---def test_compute_repo_semver_uses_release_helpers(monkeypatch) -> None:- module = _load_module()- calls: dict[str, object] = {}-- monkeypatch.setattr(module, "list_release_tags", lambda root: ["v0.9.0"])- monkeypatch.setattr(module, "find_latest_release_tag", lambda tags: "v0.9.0")- monkeypatch.setattr(module, "list_release_commits", lambda root, tag: ["feat: add init"])- monkeypatch.setattr(module, "determine_bump_level", lambda commits: "minor")- monkeypatch.setattr(module, "get_canonical_version", lambda root: "0.5.25")-- def fake_compute_release_version(*, canonical_version: str, level: str, tags: list[str]):- calls["canonical_version"] = canonical_version- calls["level"] = level- calls["tags"] = tags- return type("Info", (), {"npm_version": "0.10.0"})()-- monkeypatch.setattr(module, "compute_release_version", fake_compute_release_version)-- assert module.compute_repo_semver(Path("repo")) == "0.10.0"- assert calls == {- "canonical_version": "0.5.25",- "level": "minor",- "tags": ["v0.9.0"],- }---def test_main_runs_plugin_only_version_sync(monkeypatch) -> None:- module = _load_module()- commands: list[list[str]] = []-- monkeypatch.setattr(module, "compute_repo_semver", lambda root: "0.10.0")- monkeypatch.setattr(- module.subprocess,- "run",- lambda command, cwd, check: commands.append(command),- )-- module.main()-- assert commands == [- [- module.sys.executable,- str(module.ROOT / "scripts" / "version-sync.py"),- "--root",- str(module.ROOT),- "--version",- "0.10.0",- "--plugin-manifests-only",- ]- ]+"""Tests for sync-plugin-versions.py."""++from __future__ import annotations++import importlib.util+from pathlib import Path+++def _load_module():+ script = Path(__file__).parent.parent / "sync-plugin-versions.py"+ spec = importlib.util.spec_from_file_location("sync_plugin_versions", script)+ assert spec is not None+ assert spec.loader is not None+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++def test_compute_repo_semver_uses_release_helpers(monkeypatch) -> None:+ module = _load_module()+ calls: dict[str, object] = {}++ monkeypatch.setattr(module, "list_release_tags", lambda root: ["v0.9.0"])+ monkeypatch.setattr(module, "find_latest_release_tag", lambda tags: "v0.9.0")+ monkeypatch.setattr(module, "list_release_commits", lambda root, tag: ["feat: add init"])+ monkeypatch.setattr(module, "determine_bump_level", lambda commits: "minor")+ monkeypatch.setattr(module, "get_canonical_version", lambda root: "0.5.25")++ def fake_compute_release_version(*, canonical_version: str, level: str, tags: list[str]):+ calls["canonical_version"] = canonical_version+ calls["level"] = level+ calls["tags"] = tags+ return type("Info", (), {"npm_version": "0.10.0"})()++ monkeypatch.setattr(module, "compute_release_version", fake_compute_release_version)++ assert module.compute_repo_semver(Path("repo")) == "0.10.0"+ assert calls == {+ "canonical_version": "0.5.25",+ "level": "minor",+ "tags": ["v0.9.0"],+ }+++def test_main_runs_plugin_only_version_sync(monkeypatch) -> None:+ module = _load_module()+ commands: list[list[str]] = []++ monkeypatch.setattr(module, "compute_repo_semver", lambda root: "0.10.0")+ monkeypatch.setattr(+ module.subprocess,+ "run",+ lambda command, cwd, check: commands.append(command),+ )++ module.main()++ assert commands == [+ [+ module.sys.executable,+ str(module.ROOT / "scripts" / "version-sync.py"),+ "--root",+ str(module.ROOT),+ "--version",+ "0.10.0",+ "--plugin-manifests-only",+ ]+ ]diff --git a/tests/test_backend_anyllm.py b/tests/test_backend_anyllm.pyindex b75aa66b5..584702d41 100644--- a/tests/test_backend_anyllm.py+++ b/tests/test_backend_anyllm.py@@ -1,384 +1,384 @@-from __future__ import annotations--from types import SimpleNamespace--import pytest--from headroom.backends import anyllm-from headroom.backends.base import BackendResponse, StreamEvent---class FakeAsyncStream:- def __init__(self, items) -> None: # noqa: ANN001- self._items = list(items)-- def __aiter__(self):- self._iter = iter(self._items)- return self-- async def __anext__(self):- try:- return next(self._iter)- except StopIteration as exc:- raise StopAsyncIteration from exc---class FakeAnyLLMInstance:- def __init__(self) -> None:- self.calls: list[dict[str, object]] = []- self.response = None- self.raise_error: Exception | None = None-- async def acompletion(self, **kwargs): # noqa: ANN003- self.calls.append(kwargs)- if self.raise_error is not None:- raise self.raise_error- return self.response---def make_backend(- monkeypatch: pytest.MonkeyPatch, provider: str = "groq"-) -> tuple[anyllm.AnyLLMBackend, FakeAnyLLMInstance]:- fake_instance = FakeAnyLLMInstance()-- class FakeAnyLLM:- @staticmethod- def create(requested_provider: str):- assert requested_provider == provider- return fake_instance-- monkeypatch.setattr(anyllm, "ANYLLM_AVAILABLE", True)- monkeypatch.setattr(anyllm, "AnyLLM", FakeAnyLLM)- return anyllm.AnyLLMBackend(provider=provider.upper()), fake_instance---def make_choice(- content: str = "hello", finish_reason: str = "stop", tool_calls=None, index: int = 0-):- return SimpleNamespace(- index=index,- finish_reason=finish_reason,- message=SimpleNamespace(role="assistant", content=content, tool_calls=tool_calls),- )---def make_response(*choices, usage=None):- return SimpleNamespace(- id="resp_123",- created=123456,- choices=list(choices),- usage=usage,- )---def make_tool_call(tool_id: str, name: str, arguments):- return SimpleNamespace(id=tool_id, function=SimpleNamespace(name=name, arguments=arguments))---def test_init_raises_without_anyllm() -> None:- original_available = anyllm.ANYLLM_AVAILABLE- try:- anyllm.ANYLLM_AVAILABLE = False- with pytest.raises(ImportError):- anyllm.AnyLLMBackend()- finally:- anyllm.ANYLLM_AVAILABLE = original_available---def test_init_name_and_basic_methods(monkeypatch: pytest.MonkeyPatch) -> None:- backend, instance = make_backend(monkeypatch, provider="groq")-- assert backend.provider == "groq"- assert backend.name == "anyllm-groq"- assert backend.map_model_id("claude-3-5") == "claude-3-5"- assert backend.supports_model("anything") is True- assert backend.llm is instance---def test_convert_content_blocks_and_messages(monkeypatch: pytest.MonkeyPatch) -> None:- backend, _instance = make_backend(monkeypatch)-- assert backend._convert_content_blocks([{"type": "text", "text": "hello"}]) == "hello"- assert backend._convert_content_blocks(- [- {"type": "text", "text": "caption"},- {- "type": "image",- "source": {"type": "base64", "media_type": "image/jpeg", "data": "abc"},- },- {"type": "image", "source": {"type": "url", "url": "https://example.com/img.png"}},- ]- ) == [- {"type": "text", "text": "caption"},- {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,abc"}},- {"type": "image_url", "image_url": {"url": "https://example.com/img.png"}},- ]- assert backend._convert_content_blocks([{"type": "tool_use", "id": "ignored"}]) == ""-- converted = backend._convert_messages(- [- {"role": "user", "content": "plain text"},- {- "role": "assistant",- "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],- },- {- "role": "user",- "content": [- {"type": "text", "text": "look"},- {"type": "image", "source": {"type": "url", "url": "https://example.com"}},- ],- },- {"role": "user", "content": 123},- ]- )-- assert converted == [- {"role": "user", "content": "plain text"},- {"role": "assistant", "content": "a\nb"},- {- "role": "user",- "content": [- {"type": "text", "text": "look"},- {"type": "image_url", "image_url": {"url": "https://example.com"}},- ],- },- ]---def test_to_anthropic_response_maps_tool_calls_and_usage(monkeypatch: pytest.MonkeyPatch) -> None:- backend, _instance = make_backend(monkeypatch)- response = make_response(- make_choice(- content="hello",- finish_reason="tool_calls",- tool_calls=[- make_tool_call("tc1", "memory_save", '{"content":"python"}'),- make_tool_call("tc2", "memory_search", {"query": "python"}),- ],- ),- usage=SimpleNamespace(prompt_tokens=12, completion_tokens=7),- )-- converted = backend._to_anthropic_response(response, "claude-sonnet")-- assert converted["type"] == "message"- assert converted["role"] == "assistant"- assert converted["model"] == "claude-sonnet"- assert converted["stop_reason"] == "tool_use"- assert converted["usage"] == {"input_tokens": 12, "output_tokens": 7}- assert converted["content"][0] == {"type": "text", "text": "hello"}- assert converted["content"][1]["input"] == {"content": "python"}- assert converted["content"][2]["input"] == {"query": "python"}---async def test_send_message_builds_anthropic_response(monkeypatch: pytest.MonkeyPatch) -> None:- backend, instance = make_backend(monkeypatch)- instance.response = make_response(- make_choice("done", "stop"),- usage=SimpleNamespace(prompt_tokens=4, completion_tokens=6),- )-- result = await backend.send_message(- {- "model": "claude-3-7-sonnet",- "messages": [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],- "system": [{"text": "system rule"}, "extra"],- "max_tokens": 200,- "temperature": 0.3,- "top_p": 0.8,- "stop_sequences": ["END"],- "tools": [{"name": "t"}],- "tool_choice": {"type": "auto"},- },- {},- )-- assert isinstance(result, BackendResponse)- assert result.status_code == 200- assert result.headers == {"content-type": "application/json"}- assert result.body["content"][0]["text"] == "done"- assert instance.calls[0]["messages"][0] == {"role": "system", "content": "system rule extra"}- assert instance.calls[0]["stop"] == ["END"]---async def test_send_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:- backend, instance = make_backend(monkeypatch)- instance.raise_error = RuntimeError("authentication api_key missing")-- result = await backend.send_message({"messages": []}, {})-- assert result.status_code == 401- assert result.body["error"]["type"] == "authentication_error"- assert result.error == "authentication api_key missing"---async def test_stream_message_yields_events_and_error(monkeypatch: pytest.MonkeyPatch) -> None:- backend, instance = make_backend(monkeypatch)- instance.response = FakeAsyncStream(- [- SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="hel"))]),- SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="lo"))]),- SimpleNamespace(choices=[]),- ]- )-- events = [- event- async for event in backend.stream_message(- {"model": "claude", "messages": [], "system": "sys"}, {}- )- ]-- assert [event.event_type for event in events] == [- "message_start",- "content_block_start",- "content_block_delta",- "content_block_delta",- "content_block_stop",- "message_delta",- "message_stop",- ]- assert events[0].data["message"]["model"] == "claude"- assert events[5].data["usage"] == {"output_tokens": 2}- assert instance.calls[0]["stream"] is True- assert instance.calls[0]["messages"][0] == {"role": "system", "content": "sys"}-- backend_error, instance_error = make_backend(monkeypatch, provider="openai")- instance_error.raise_error = RuntimeError("stream broke")- error_events = [event async for event in backend_error.stream_message({"messages": []}, {})]- assert error_events[-1].event_type == "error"- assert error_events[-1].data["error"]["message"] == "stream broke"---async def test_send_openai_message_maps_choices_and_tool_calls(- monkeypatch: pytest.MonkeyPatch,-) -> None:- backend, instance = make_backend(monkeypatch)- instance.response = make_response(- make_choice(- content="answer",- finish_reason="stop",- tool_calls=[- make_tool_call("tc1", "memory_search", '{"query":"python"}'),- SimpleNamespace(id="tc2", function=None),- ],- index=0,- ),- usage=SimpleNamespace(prompt_tokens=2, completion_tokens=3, total_tokens=5),- )-- result = await backend.send_openai_message(- {- "model": "gpt-4o",- "messages": [{"role": "user", "content": "hi"}],- "max_tokens": 50,- "temperature": 0.2,- "top_p": 0.9,- "stop": ["END"],- "tools": [{"name": "memory"}],- "tool_choice": "auto",- "response_format": {"type": "json_object"},- "seed": 1,- "n": 2,- },- {},- )-- assert result.status_code == 200- assert result.body["object"] == "chat.completion"- assert (- result.body["choices"][0]["message"]["tool_calls"][0]["function"]["name"] == "memory_search"- )- assert result.body["choices"][0]["message"]["tool_calls"][1] == {- "id": "tc2",- "type": "function",- }- assert result.body["usage"] == {"prompt_tokens": 2, "completion_tokens": 3, "total_tokens": 5}---async def test_send_openai_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:- backend, instance = make_backend(monkeypatch)- instance.raise_error = RuntimeError("model not found")-- result = await backend.send_openai_message({"messages": []}, {})-- assert result.status_code == 404- assert result.body["error"]["type"] == "model_not_found"---async def test_stream_openai_message_yields_sse_chunks_and_done(- monkeypatch: pytest.MonkeyPatch,-) -> None:- backend, instance = make_backend(monkeypatch)- instance.response = FakeAsyncStream(- [- SimpleNamespace(- model_dump=lambda **kwargs: {- "id": "chunk1",- "choices": [{"delta": {"content": "a"}}],- }- ),- SimpleNamespace(- model_dump=lambda **kwargs: {- "id": "chunk2",- "choices": [{"delta": {"content": "b"}}],- }- ),- ]- )-- chunks = [- chunk- async for chunk in backend.stream_openai_message(- {- "messages": [{"role": "user", "content": "hi"}],- "stream_options": {"include_usage": True},- },- {},- )- ]-- assert chunks[0].startswith("data: {")- assert chunks[-1] == "data: [DONE]\n\n"- assert instance.calls[0]["stream"] is True- assert instance.calls[0]["stream_options"] == {"include_usage": True}-- backend_error, instance_error = make_backend(monkeypatch, provider="anthropic")- instance_error.raise_error = RuntimeError("rate limit hit")- error_chunks = [- chunk async for chunk in backend_error.stream_openai_message({"messages": []}, {})- ]- assert '"backend_error"' in error_chunks[0]- assert error_chunks[-1] == "data: [DONE]\n\n"---def test_error_response_classifies_common_failures(monkeypatch: pytest.MonkeyPatch) -> None:- backend, _instance = make_backend(monkeypatch)-- auth = backend._error_response(RuntimeError("authentication api key missing"))- rate = backend._error_response(RuntimeError("rate limit exceeded"), openai_format=True)- model = backend._error_response(RuntimeError("model not found"), openai_format=True)- generic = backend._error_response(RuntimeError("other error"))-- assert auth.status_code == 401- assert auth.body["error"]["type"] == "authentication_error"- assert rate.status_code == 429- assert rate.body["error"]["type"] == "rate_limit_exceeded"- assert model.status_code == 404- assert model.body["error"]["type"] == "model_not_found"- assert generic.status_code == 500- assert generic.body["error"]["type"] == "api_error"---async def test_close_is_noop(monkeypatch: pytest.MonkeyPatch) -> None:- backend, _instance = make_backend(monkeypatch)- assert await backend.close() is None- assert isinstance(StreamEvent(event_type="message_start", data={}), StreamEvent)+from __future__ import annotations++from types import SimpleNamespace++import pytest++from headroom.backends import anyllm+from headroom.backends.base import BackendResponse, StreamEvent+++class FakeAsyncStream:+ def __init__(self, items) -> None: # noqa: ANN001+ self._items = list(items)++ def __aiter__(self):+ self._iter = iter(self._items)+ return self++ async def __anext__(self):+ try:+ return next(self._iter)+ except StopIteration as exc:+ raise StopAsyncIteration from exc+++class FakeAnyLLMInstance:+ def __init__(self) -> None:+ self.calls: list[dict[str, object]] = []+ self.response = None+ self.raise_error: Exception | None = None++ async def acompletion(self, **kwargs): # noqa: ANN003+ self.calls.append(kwargs)+ if self.raise_error is not None:+ raise self.raise_error+ return self.response+++def make_backend(+ monkeypatch: pytest.MonkeyPatch, provider: str = "groq"+) -> tuple[anyllm.AnyLLMBackend, FakeAnyLLMInstance]:+ fake_instance = FakeAnyLLMInstance()++ class FakeAnyLLM:+ @staticmethod+ def create(requested_provider: str):+ assert requested_provider == provider+ return fake_instance++ monkeypatch.setattr(anyllm, "ANYLLM_AVAILABLE", True)+ monkeypatch.setattr(anyllm, "AnyLLM", FakeAnyLLM)+ return anyllm.AnyLLMBackend(provider=provider.upper()), fake_instance+++def make_choice(+ content: str = "hello", finish_reason: str = "stop", tool_calls=None, index: int = 0+):+ return SimpleNamespace(+ index=index,+ finish_reason=finish_reason,+ message=SimpleNamespace(role="assistant", content=content, tool_calls=tool_calls),+ )+++def make_response(*choices, usage=None):+ return SimpleNamespace(+ id="resp_123",+ created=123456,+ choices=list(choices),+ usage=usage,+ )+++def make_tool_call(tool_id: str, name: str, arguments):+ return SimpleNamespace(id=tool_id, function=SimpleNamespace(name=name, arguments=arguments))+++def test_init_raises_without_anyllm() -> None:+ original_available = anyllm.ANYLLM_AVAILABLE+ try:+ anyllm.ANYLLM_AVAILABLE = False+ with pytest.raises(ImportError):+ anyllm.AnyLLMBackend()+ finally:+ anyllm.ANYLLM_AVAILABLE = original_available+++def test_init_name_and_basic_methods(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, instance = make_backend(monkeypatch, provider="groq")++ assert backend.provider == "groq"+ assert backend.name == "anyllm-groq"+ assert backend.map_model_id("claude-3-5") == "claude-3-5"+ assert backend.supports_model("anything") is True+ assert backend.llm is instance+++def test_convert_content_blocks_and_messages(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, _instance = make_backend(monkeypatch)++ assert backend._convert_content_blocks([{"type": "text", "text": "hello"}]) == "hello"+ assert backend._convert_content_blocks(+ [+ {"type": "text", "text": "caption"},+ {+ "type": "image",+ "source": {"type": "base64", "media_type": "image/jpeg", "data": "abc"},+ },+ {"type": "image", "source": {"type": "url", "url": "https://example.com/img.png"}},+ ]+ ) == [+ {"type": "text", "text": "caption"},+ {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,abc"}},+ {"type": "image_url", "image_url": {"url": "https://example.com/img.png"}},+ ]+ assert backend._convert_content_blocks([{"type": "tool_use", "id": "ignored"}]) == ""++ converted = backend._convert_messages(+ [+ {"role": "user", "content": "plain text"},+ {+ "role": "assistant",+ "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],+ },+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "look"},+ {"type": "image", "source": {"type": "url", "url": "https://example.com"}},+ ],+ },+ {"role": "user", "content": 123},+ ]+ )++ assert converted == [+ {"role": "user", "content": "plain text"},+ {"role": "assistant", "content": "a\nb"},+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "look"},+ {"type": "image_url", "image_url": {"url": "https://example.com"}},+ ],+ },+ ]+++def test_to_anthropic_response_maps_tool_calls_and_usage(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, _instance = make_backend(monkeypatch)+ response = make_response(+ make_choice(+ content="hello",+ finish_reason="tool_calls",+ tool_calls=[+ make_tool_call("tc1", "memory_save", '{"content":"python"}'),+ make_tool_call("tc2", "memory_search", {"query": "python"}),+ ],+ ),+ usage=SimpleNamespace(prompt_tokens=12, completion_tokens=7),+ )++ converted = backend._to_anthropic_response(response, "claude-sonnet")++ assert converted["type"] == "message"+ assert converted["role"] == "assistant"+ assert converted["model"] == "claude-sonnet"+ assert converted["stop_reason"] == "tool_use"+ assert converted["usage"] == {"input_tokens": 12, "output_tokens": 7}+ assert converted["content"][0] == {"type": "text", "text": "hello"}+ assert converted["content"][1]["input"] == {"content": "python"}+ assert converted["content"][2]["input"] == {"query": "python"}+++async def test_send_message_builds_anthropic_response(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, instance = make_backend(monkeypatch)+ instance.response = make_response(+ make_choice("done", "stop"),+ usage=SimpleNamespace(prompt_tokens=4, completion_tokens=6),+ )++ result = await backend.send_message(+ {+ "model": "claude-3-7-sonnet",+ "messages": [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],+ "system": [{"text": "system rule"}, "extra"],+ "max_tokens": 200,+ "temperature": 0.3,+ "top_p": 0.8,+ "stop_sequences": ["END"],+ "tools": [{"name": "t"}],+ "tool_choice": {"type": "auto"},+ },+ {},+ )++ assert isinstance(result, BackendResponse)+ assert result.status_code == 200+ assert result.headers == {"content-type": "application/json"}+ assert result.body["content"][0]["text"] == "done"+ assert instance.calls[0]["messages"][0] == {"role": "system", "content": "system rule extra"}+ assert instance.calls[0]["stop"] == ["END"]+++async def test_send_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, instance = make_backend(monkeypatch)+ instance.raise_error = RuntimeError("authentication api_key missing")++ result = await backend.send_message({"messages": []}, {})++ assert result.status_code == 401+ assert result.body["error"]["type"] == "authentication_error"+ assert result.error == "authentication api_key missing"+++async def test_stream_message_yields_events_and_error(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, instance = make_backend(monkeypatch)+ instance.response = FakeAsyncStream(+ [+ SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="hel"))]),+ SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="lo"))]),+ SimpleNamespace(choices=[]),+ ]+ )++ events = [+ event+ async for event in backend.stream_message(+ {"model": "claude", "messages": [], "system": "sys"}, {}+ )+ ]++ assert [event.event_type for event in events] == [+ "message_start",+ "content_block_start",+ "content_block_delta",+ "content_block_delta",+ "content_block_stop",+ "message_delta",+ "message_stop",+ ]+ assert events[0].data["message"]["model"] == "claude"+ assert events[5].data["usage"] == {"output_tokens": 2}+ assert instance.calls[0]["stream"] is True+ assert instance.calls[0]["messages"][0] == {"role": "system", "content": "sys"}++ backend_error, instance_error = make_backend(monkeypatch, provider="openai")+ instance_error.raise_error = RuntimeError("stream broke")+ error_events = [event async for event in backend_error.stream_message({"messages": []}, {})]+ assert error_events[-1].event_type == "error"+ assert error_events[-1].data["error"]["message"] == "stream broke"+++async def test_send_openai_message_maps_choices_and_tool_calls(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ backend, instance = make_backend(monkeypatch)+ instance.response = make_response(+ make_choice(+ content="answer",+ finish_reason="stop",+ tool_calls=[+ make_tool_call("tc1", "memory_search", '{"query":"python"}'),+ SimpleNamespace(id="tc2", function=None),+ ],+ index=0,+ ),+ usage=SimpleNamespace(prompt_tokens=2, completion_tokens=3, total_tokens=5),+ )++ result = await backend.send_openai_message(+ {+ "model": "gpt-4o",+ "messages": [{"role": "user", "content": "hi"}],+ "max_tokens": 50,+ "temperature": 0.2,+ "top_p": 0.9,+ "stop": ["END"],+ "tools": [{"name": "memory"}],+ "tool_choice": "auto",+ "response_format": {"type": "json_object"},+ "seed": 1,+ "n": 2,+ },+ {},+ )++ assert result.status_code == 200+ assert result.body["object"] == "chat.completion"+ assert (+ result.body["choices"][0]["message"]["tool_calls"][0]["function"]["name"] == "memory_search"+ )+ assert result.body["choices"][0]["message"]["tool_calls"][1] == {+ "id": "tc2",+ "type": "function",+ }+ assert result.body["usage"] == {"prompt_tokens": 2, "completion_tokens": 3, "total_tokens": 5}+++async def test_send_openai_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, instance = make_backend(monkeypatch)+ instance.raise_error = RuntimeError("model not found")++ result = await backend.send_openai_message({"messages": []}, {})++ assert result.status_code == 404+ assert result.body["error"]["type"] == "model_not_found"+++async def test_stream_openai_message_yields_sse_chunks_and_done(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ backend, instance = make_backend(monkeypatch)+ instance.response = FakeAsyncStream(+ [+ SimpleNamespace(+ model_dump=lambda **kwargs: {+ "id": "chunk1",+ "choices": [{"delta": {"content": "a"}}],+ }+ ),+ SimpleNamespace(+ model_dump=lambda **kwargs: {+ "id": "chunk2",+ "choices": [{"delta": {"content": "b"}}],+ }+ ),+ ]+ )++ chunks = [+ chunk+ async for chunk in backend.stream_openai_message(+ {+ "messages": [{"role": "user", "content": "hi"}],+ "stream_options": {"include_usage": True},+ },+ {},+ )+ ]++ assert chunks[0].startswith("data: {")+ assert chunks[-1] == "data: [DONE]\n\n"+ assert instance.calls[0]["stream"] is True+ assert instance.calls[0]["stream_options"] == {"include_usage": True}++ backend_error, instance_error = make_backend(monkeypatch, provider="anthropic")+ instance_error.raise_error = RuntimeError("rate limit hit")+ error_chunks = [+ chunk async for chunk in backend_error.stream_openai_message({"messages": []}, {})+ ]+ assert '"backend_error"' in error_chunks[0]+ assert error_chunks[-1] == "data: [DONE]\n\n"+++def test_error_response_classifies_common_failures(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, _instance = make_backend(monkeypatch)++ auth = backend._error_response(RuntimeError("authentication api key missing"))+ rate = backend._error_response(RuntimeError("rate limit exceeded"), openai_format=True)+ model = backend._error_response(RuntimeError("model not found"), openai_format=True)+ generic = backend._error_response(RuntimeError("other error"))++ assert auth.status_code == 401+ assert auth.body["error"]["type"] == "authentication_error"+ assert rate.status_code == 429+ assert rate.body["error"]["type"] == "rate_limit_exceeded"+ assert model.status_code == 404+ assert model.body["error"]["type"] == "model_not_found"+ assert generic.status_code == 500+ assert generic.body["error"]["type"] == "api_error"+++async def test_close_is_noop(monkeypatch: pytest.MonkeyPatch) -> None:+ backend, _instance = make_backend(monkeypatch)+ assert await backend.close() is None+ assert isinstance(StreamEvent(event_type="message_start", data={}), StreamEvent)diff --git a/tests/test_ccr_batch_store.py b/tests/test_ccr_batch_store.pyindex 04a31bbf0..a4ab6bbec 100644--- a/tests/test_ccr_batch_store.py+++ b/tests/test_ccr_batch_store.py@@ -1,126 +1,126 @@-from __future__ import annotations--import sys-from dataclasses import dataclass--from headroom.ccr.batch_store import (- BatchContext,- BatchContextStore,- BatchRequestContext,- get_batch_context_store,- reset_batch_context_store,-)---def test_batch_context_defaults_and_expiry(monkeypatch) -> None:- monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: 100.0)- context = BatchContext(batch_id="batch-1", provider="anthropic", created_at=100.0)- assert context.expires_at == 100.0 + 86400- assert context.is_expired is False-- request = BatchRequestContext(- custom_id="req-1",- messages=[{"role": "user", "content": "hello"}],- tools=[{"name": "tool"}],- model="gpt-4o",- system_instruction="system",- extras={"x": 1},- )- context.add_request(request)- assert context.get_request("req-1") is request- assert context.get_request("missing") is None-- monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: context.expires_at + 1)- assert context.is_expired is True---async def test_batch_context_store_core_operations(monkeypatch) -> None:- now = {"value": 100.0}- monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: now["value"])-- store = BatchContextStore(ttl=10, max_contexts=2)- first = BatchContext(batch_id="b1", provider="anthropic")- second = BatchContext(batch_id="b2", provider="google")- third = BatchContext(batch_id="b3", provider="openai")-- await store.store(first)- now["value"] = 101.0- await store.store(second)- assert (await store.get("b1")) is first-- now["value"] = 102.0- await store.store(third)- assert await store.get("b1") is None- assert await store.get("b2") is second- assert await store.get("b3") is third-- assert await store.remove("b2") is True- assert await store.remove("b2") is False---async def test_batch_context_store_cleanup_stats_and_memory_stats(monkeypatch) -> None:- now = {"value": 200.0}- monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: now["value"])- store = BatchContextStore(ttl=5, max_contexts=10)-- first = BatchContext(batch_id="b1", provider="anthropic")- first.add_request(- BatchRequestContext(custom_id="r1", messages=[{"content": "alpha"}], tools=[])- )- second = BatchContext(batch_id="b2", provider="google")- second.add_request(- BatchRequestContext(custom_id="r2", messages=[{"content": ["nested"]}], tools=[{}])- )-- await store.store(first)- await store.store(second)- assert await store.stats() == {- "total_contexts": 2,- "max_contexts": 10,- "ttl_seconds": 5,- "providers": {"anthropic": 1, "google": 1},- }-- now["value"] = 210.0- assert await store.cleanup_expired() == 2- assert (await store.stats())["total_contexts"] == 0-- @dataclass- class FakeComponentStats:- name: str- entry_count: int- size_bytes: int- budget_bytes: int | None- hits: int- misses: int- evictions: int-- monkeypatch.setitem(- sys.modules,- "headroom.memory.tracker",- type("TrackerModule", (), {"ComponentStats": FakeComponentStats}),- )-- now["value"] = 220.0- third = BatchContext(batch_id="b3", provider="openai")- third.add_request(- BatchRequestContext(- custom_id="r3", messages=[{"content": "payload"}], tools=[{"name": "t"}]- )- )- await store.store(third)- stats = store.get_memory_stats()- assert stats.name == "batch_context_store"- assert stats.entry_count == 1- assert stats.size_bytes > 0---def test_global_batch_context_store_reset() -> None:- reset_batch_context_store()- store_one = get_batch_context_store()- store_two = get_batch_context_store()- assert store_one is store_two-- reset_batch_context_store()- store_three = get_batch_context_store()- assert store_three is not store_one+from __future__ import annotations++import sys+from dataclasses import dataclass++from headroom.ccr.batch_store import (+ BatchContext,+ BatchContextStore,+ BatchRequestContext,+ get_batch_context_store,+ reset_batch_context_store,+)+++def test_batch_context_defaults_and_expiry(monkeypatch) -> None:+ monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: 100.0)+ context = BatchContext(batch_id="batch-1", provider="anthropic", created_at=100.0)+ assert context.expires_at == 100.0 + 86400+ assert context.is_expired is False++ request = BatchRequestContext(+ custom_id="req-1",+ messages=[{"role": "user", "content": "hello"}],+ tools=[{"name": "tool"}],+ model="gpt-4o",+ system_instruction="system",+ extras={"x": 1},+ )+ context.add_request(request)+ assert context.get_request("req-1") is request+ assert context.get_request("missing") is None++ monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: context.expires_at + 1)+ assert context.is_expired is True+++async def test_batch_context_store_core_operations(monkeypatch) -> None:+ now = {"value": 100.0}+ monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: now["value"])++ store = BatchContextStore(ttl=10, max_contexts=2)+ first = BatchContext(batch_id="b1", provider="anthropic")+ second = BatchContext(batch_id="b2", provider="google")+ third = BatchContext(batch_id="b3", provider="openai")++ await store.store(first)+ now["value"] = 101.0+ await store.store(second)+ assert (await store.get("b1")) is first++ now["value"] = 102.0+ await store.store(third)+ assert await store.get("b1") is None+ assert await store.get("b2") is second+ assert await store.get("b3") is third++ assert await store.remove("b2") is True+ assert await store.remove("b2") is False+++async def test_batch_context_store_cleanup_stats_and_memory_stats(monkeypatch) -> None:+ now = {"value": 200.0}+ monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: now["value"])+ store = BatchContextStore(ttl=5, max_contexts=10)++ first = BatchContext(batch_id="b1", provider="anthropic")+ first.add_request(+ BatchRequestContext(custom_id="r1", messages=[{"content": "alpha"}], tools=[])+ )+ second = BatchContext(batch_id="b2", provider="google")+ second.add_request(+ BatchRequestContext(custom_id="r2", messages=[{"content": ["nested"]}], tools=[{}])+ )++ await store.store(first)+ await store.store(second)+ assert await store.stats() == {+ "total_contexts": 2,+ "max_contexts": 10,+ "ttl_seconds": 5,+ "providers": {"anthropic": 1, "google": 1},+ }++ now["value"] = 210.0+ assert await store.cleanup_expired() == 2+ assert (await store.stats())["total_contexts"] == 0++ @dataclass+ class FakeComponentStats:+ name: str+ entry_count: int+ size_bytes: int+ budget_bytes: int | None+ hits: int+ misses: int+ evictions: int++ monkeypatch.setitem(+ sys.modules,+ "headroom.memory.tracker",+ type("TrackerModule", (), {"ComponentStats": FakeComponentStats}),+ )++ now["value"] = 220.0+ third = BatchContext(batch_id="b3", provider="openai")+ third.add_request(+ BatchRequestContext(+ custom_id="r3", messages=[{"content": "payload"}], tools=[{"name": "t"}]+ )+ )+ await store.store(third)+ stats = store.get_memory_stats()+ assert stats.name == "batch_context_store"+ assert stats.entry_count == 1+ assert stats.size_bytes > 0+++def test_global_batch_context_store_reset() -> None:+ reset_batch_context_store()+ store_one = get_batch_context_store()+ store_two = get_batch_context_store()+ assert store_one is store_two++ reset_batch_context_store()+ store_three = get_batch_context_store()+ assert store_three is not store_onediff --git a/tests/test_ccr_response_handler_extra.py b/tests/test_ccr_response_handler_extra.pyindex 9a8e9a0a3..93d79bb97 100644--- a/tests/test_ccr_response_handler_extra.py+++ b/tests/test_ccr_response_handler_extra.py@@ -1,372 +1,372 @@-from __future__ import annotations--import json-from typing import Any--import pytest--from headroom.ccr.response_handler import (- CCRResponseHandler,- CCRToolCall,- CCRToolResult,- StreamingCCRBuffer,- StreamingCCRHandler,-)-from headroom.ccr.tool_injection import CCR_TOOL_NAME---class FakeStore:- def __init__(- self, *, search_error: Exception | None = None, retrieve_error: Exception | None = None- ) -> None:- self.search_error = search_error- self.retrieve_error = retrieve_error-- def search(self, hash_key: str, query: str) -> list[dict[str, str]]:- if self.search_error:- raise self.search_error- return [{"id": "1", "text": query}]-- def retrieve(self, hash_key: str):- if self.retrieve_error:- raise self.retrieve_error- return {"unexpected": True}---async def _async_iter(items: list[bytes]):- for item in items:- yield item---def test_extract_tool_calls_google_and_invalid_shapes() -> None:- handler = CCRResponseHandler()- google_response = {- "candidates": [- {- "content": {- "parts": [- {"text": "hello"},- {"functionCall": {"name": CCR_TOOL_NAME, "args": {"hash": "abc"}}},- ]- }- }- ]- }- assert handler._extract_tool_calls(google_response, "google") == [- {"functionCall": {"name": CCR_TOOL_NAME, "args": {"hash": "abc"}}}- ]- assert handler._extract_tool_calls({"content": "bad"}, "anthropic") == []- with pytest.raises(IndexError):- handler._extract_tool_calls({"choices": []}, "openai")- assert handler._extract_tool_calls({"candidates": []}, "google") == []---def test_parse_ccr_tool_calls_google_and_other_calls() -> None:- handler = CCRResponseHandler()- response = {- "candidates": [- {- "content": {- "parts": [- {- "functionCall": {- "name": CCR_TOOL_NAME,- "args": {- "hash": "aaaaaaaaaaaaaaaaaaaaaaaa",- "query": "pizza",- },- }- },- {"functionCall": {"name": "other_tool", "args": {}}},- ]- }- }- ]- }- ccr_calls, other_calls = handler._parse_ccr_tool_calls(response, "google")- assert ccr_calls == [- CCRToolCall(- tool_call_id=CCR_TOOL_NAME,- hash_key="aaaaaaaaaaaaaaaaaaaaaaaa",- query="pizza",- )- ]- assert other_calls == [{"functionCall": {"name": "other_tool", "args": {}}}]---def test_execute_retrieval_error_paths(monkeypatch: pytest.MonkeyPatch) -> None:- handler = CCRResponseHandler()- monkeypatch.setattr(- "headroom.ccr.response_handler.get_compression_store",- lambda: FakeStore(search_error=RuntimeError("search boom")),- )- search_result = handler._execute_retrieval(- CCRToolCall(tool_call_id="t1", hash_key="abc", query="find")- )- assert search_result.success is False- assert "Retrieval failed: search boom" in search_result.content-- monkeypatch.setattr(- "headroom.ccr.response_handler.get_compression_store",- lambda: FakeStore(retrieve_error=RuntimeError("retrieve boom")),- )- retrieve_result = handler._execute_retrieval(CCRToolCall(tool_call_id="t2", hash_key="abc"))- assert retrieve_result.success is False- assert "Retrieval failed: retrieve boom" in retrieve_result.content---def test_create_tool_result_message_google_and_generic_formats() -> None:- handler = CCRResponseHandler()- results = [- CCRToolResult(tool_call_id="headroom_retrieve", content='{"count": 1}', success=True)- ]- google_message = handler._create_tool_result_message(results, "google")- assert google_message == {- "role": "user",- "parts": [{"functionResponse": {"name": "headroom_retrieve", "response": {"count": 1}}}],- }-- generic_message = handler._create_tool_result_message(- [CCRToolResult(tool_call_id="tool-1", content="not-json", success=False)],- "other",- )- assert generic_message["role"] == "tool"- assert json.loads(generic_message["content"]) == [- {"tool_call_id": "tool-1", "result": "not-json"}- ]-- invalid_google = handler._create_tool_result_message(- [CCRToolResult(tool_call_id="headroom_retrieve", content="not-json", success=True)],- "google",- )- assert invalid_google["parts"][0]["functionResponse"]["response"] == {"content": "not-json"}---def test_extract_assistant_message_google_and_generic() -> None:- handler = CCRResponseHandler()- google_message = handler._extract_assistant_message(- {"candidates": [{"content": {"parts": [{"text": "hello"}]}}]},- "google",- )- assert google_message == {"role": "model", "parts": [{"text": "hello"}]}-- assert handler._extract_assistant_message({}, "google") == {"role": "model", "parts": []}- assert handler._extract_assistant_message({"content": "plain"}, "other") == {- "role": "assistant",- "content": "plain",- }---async def test_handle_response_openai_success_and_failure(monkeypatch: pytest.MonkeyPatch) -> None:- handler = CCRResponseHandler()- initial_response = {- "choices": [- {- "message": {- "role": "assistant",- "content": None,- "tool_calls": [- {- "id": "call_1",- "type": "function",- "function": {- "name": CCR_TOOL_NAME,- "arguments": '{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}',- },- }- ],- }- }- ]- }- monkeypatch.setattr(- handler,- "_execute_retrieval",- lambda call: CCRToolResult(- tool_call_id=call.tool_call_id,- content='{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}',- success=True,- ),- )-- captured_messages: list[list[dict[str, Any]]] = []-- async def success_api_call(messages, tools):- captured_messages.append(messages)- return {"choices": [{"message": {"role": "assistant", "content": "done"}}]}-- result = await handler.handle_response(- initial_response, [{"role": "user", "content": "hi"}], [], success_api_call, "openai"- )- assert result == {"choices": [{"message": {"role": "assistant", "content": "done"}}]}- assert captured_messages[0][1]["role"] == "assistant"- assert captured_messages[0][2]["role"] == "tool"- assert handler.get_stats()["total_retrievals"] == 1-- async def failing_api_call(messages, tools):- raise RuntimeError("continuation failed")-- failed = await handler.handle_response(initial_response, [], [], failing_api_call, "openai")- assert failed == initial_response---def test_streaming_buffer_and_parse_sse_helpers() -> None:- buffer = StreamingCCRBuffer()- assert buffer.add_chunk(b"plain") is False- assert buffer.get_accumulated() == b"plain"-- handler = StreamingCCRHandler(CCRResponseHandler(), provider="anthropic")- anthropic_data = b"\n".join(- [- b'data: {"type":"content_block_start","content_block":{"type":"text","text":"Hel"}}',- b'data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"lo"}}',- b'data: {"type":"content_block_stop"}',- b'data: {"type":"content_block_start","content_block":{"type":"tool_use","id":"tool_1","name":"headroom_retrieve"}}',- b'data: {"type":"content_block_delta","delta":{"type":"input_json_delta","partial_json":"{\\"hash\\":\\"abc\\"}"}}',- b'data: {"type":"content_block_stop"}',- b'data: {"type":"message_delta","delta":{"stop_reason":"tool_use"}}',- b"data: [DONE]",- ]- )- parsed = handler._parse_sse_stream(anthropic_data)- assert parsed["content"][0] == {"type": "text", "text": "Hello"}- assert parsed["content"][1]["name"] == "headroom_retrieve"- assert parsed["content"][1]["input"] == {"hash": "abc"}- assert parsed["stop_reason"] == "tool_use"-- openai_handler = StreamingCCRHandler(CCRResponseHandler(), provider="openai")- parsed_openai = openai_handler._reconstruct_openai_response(- [- {"choices": [{"delta": {"content": "Hi"}}]},- {- "choices": [- {- "delta": {- "tool_calls": [- {- "index": 0,- "id": "call_1",- "function": {- "name": "headroom_retrieve",- "arguments": '{"hash":"aaaaaaaaaaaa',- },- }- ]- }- }- ]- },- {- "choices": [- {- "delta": {- "tool_calls": [- {- "index": 0,- "function": {"arguments": 'aaaaaaaaaaaa"}'},- }- ]- }- }- ]- },- ]- )- message = parsed_openai["choices"][0]["message"]- assert message["content"] == "Hi"- assert message["tool_calls"][0]["id"] == "call_1"- assert message["tool_calls"][0]["function"]["arguments"] == (- '{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}'- )---async def test_streaming_handler_process_stream_pass_through_and_ccr(- monkeypatch: pytest.MonkeyPatch,-) -> None:- response_handler = CCRResponseHandler()- handler = StreamingCCRHandler(response_handler, provider="anthropic")-- passthrough_chunks = [- b'data: {"type":"content_block_delta","delta":{"text":"hello"}}',- b'data: {"stop_reason":"end_turn"}',- ]- yielded = [- chunk- async for chunk in handler.process_stream(- _async_iter(passthrough_chunks), [], None, lambda m, t: None- )- ]- assert yielded == passthrough_chunks-- ccr_handler = StreamingCCRHandler(response_handler, provider="anthropic")- monkeypatch.setattr(- ccr_handler,- "_parse_sse_stream",- lambda data: {- "content": [- {- "type": "tool_use",- "id": "tool_1",- "name": CCR_TOOL_NAME,- "input": {"hash": "abc"},- }- ]- },- )-- async def fake_handle_response(response, messages, tools, api_call_fn, provider): # noqa: ANN001- return {"content": [{"type": "text", "text": "done"}]}-- async def fake_response_to_sse(response): # noqa: ANN001- yield b"event: message_start\n"- yield b"event: message_stop\n"-- monkeypatch.setattr(response_handler, "handle_response", fake_handle_response)- monkeypatch.setattr(ccr_handler, "_response_to_sse", fake_response_to_sse)-- ccr_chunks = [- b'{"type":"tool_use","name":"headroom_retrieve"',- b',"stop_reason":"tool_use"}',- b"tail",- ]- streamed = [- chunk- async for chunk in ccr_handler.process_stream(- _async_iter(ccr_chunks), [], None, lambda m, t: None- )- ]- assert streamed == [b"event: message_start\n", b"event: message_stop\n"]---async def test_streaming_handler_falls_back_to_buffer_on_processing_error(- monkeypatch: pytest.MonkeyPatch,-) -> None:- response_handler = CCRResponseHandler()- handler = StreamingCCRHandler(response_handler, provider="openai")- monkeypatch.setattr(- handler,- "_parse_sse_stream",- lambda data: (_ for _ in ()).throw(RuntimeError("parse failed")),- )-- chunks = [b'{"type":"tool_use","name":"headroom_retrieve"', b',"stop_reason":"tool_use"}']- streamed = [- chunk- async for chunk in handler.process_stream(_async_iter(chunks), [], None, lambda m, t: None)- ]- assert streamed == [b"".join(chunks)]---async def test_response_to_sse_formats() -> None:- anthropic = StreamingCCRHandler(CCRResponseHandler(), provider="anthropic")- anthropic_chunks = [chunk async for chunk in anthropic._response_to_sse({"content": []})]- assert anthropic_chunks[0] == b"event: message_start\n"- assert anthropic_chunks[-1] == b'data: {"type": "message_stop"}\n\n'-- openai = StreamingCCRHandler(CCRResponseHandler(), provider="openai")- openai_chunks = [chunk async for chunk in openai._response_to_sse({"choices": []})]- assert openai_chunks == [b'data: {"choices": []}\n\n', b"data: [DONE]\n\n"]+from __future__ import annotations++import json+from typing import Any++import pytest++from headroom.ccr.response_handler import (+ CCRResponseHandler,+ CCRToolCall,+ CCRToolResult,+ StreamingCCRBuffer,+ StreamingCCRHandler,+)+from headroom.ccr.tool_injection import CCR_TOOL_NAME+++class FakeStore:+ def __init__(+ self, *, search_error: Exception | None = None, retrieve_error: Exception | None = None+ ) -> None:+ self.search_error = search_error+ self.retrieve_error = retrieve_error++ def search(self, hash_key: str, query: str) -> list[dict[str, str]]:+ if self.search_error:+ raise self.search_error+ return [{"id": "1", "text": query}]++ def retrieve(self, hash_key: str):+ if self.retrieve_error:+ raise self.retrieve_error+ return {"unexpected": True}+++async def _async_iter(items: list[bytes]):+ for item in items:+ yield item+++def test_extract_tool_calls_google_and_invalid_shapes() -> None:+ handler = CCRResponseHandler()+ google_response = {+ "candidates": [+ {+ "content": {+ "parts": [+ {"text": "hello"},+ {"functionCall": {"name": CCR_TOOL_NAME, "args": {"hash": "abc"}}},+ ]+ }+ }+ ]+ }+ assert handler._extract_tool_calls(google_response, "google") == [+ {"functionCall": {"name": CCR_TOOL_NAME, "args": {"hash": "abc"}}}+ ]+ assert handler._extract_tool_calls({"content": "bad"}, "anthropic") == []+ with pytest.raises(IndexError):+ handler._extract_tool_calls({"choices": []}, "openai")+ assert handler._extract_tool_calls({"candidates": []}, "google") == []+++def test_parse_ccr_tool_calls_google_and_other_calls() -> None:+ handler = CCRResponseHandler()+ response = {+ "candidates": [+ {+ "content": {+ "parts": [+ {+ "functionCall": {+ "name": CCR_TOOL_NAME,+ "args": {+ "hash": "aaaaaaaaaaaaaaaaaaaaaaaa",+ "query": "pizza",+ },+ }+ },+ {"functionCall": {"name": "other_tool", "args": {}}},+ ]+ }+ }+ ]+ }+ ccr_calls, other_calls = handler._parse_ccr_tool_calls(response, "google")+ assert ccr_calls == [+ CCRToolCall(+ tool_call_id=CCR_TOOL_NAME,+ hash_key="aaaaaaaaaaaaaaaaaaaaaaaa",+ query="pizza",+ )+ ]+ assert other_calls == [{"functionCall": {"name": "other_tool", "args": {}}}]+++def test_execute_retrieval_error_paths(monkeypatch: pytest.MonkeyPatch) -> None:+ handler = CCRResponseHandler()+ monkeypatch.setattr(+ "headroom.ccr.response_handler.get_compression_store",+ lambda: FakeStore(search_error=RuntimeError("search boom")),+ )+ search_result = handler._execute_retrieval(+ CCRToolCall(tool_call_id="t1", hash_key="abc", query="find")+ )+ assert search_result.success is False+ assert "Retrieval failed: search boom" in search_result.content++ monkeypatch.setattr(+ "headroom.ccr.response_handler.get_compression_store",+ lambda: FakeStore(retrieve_error=RuntimeError("retrieve boom")),+ )+ retrieve_result = handler._execute_retrieval(CCRToolCall(tool_call_id="t2", hash_key="abc"))+ assert retrieve_result.success is False+ assert "Retrieval failed: retrieve boom" in retrieve_result.content+++def test_create_tool_result_message_google_and_generic_formats() -> None:+ handler = CCRResponseHandler()+ results = [+ CCRToolResult(tool_call_id="headroom_retrieve", content='{"count": 1}', success=True)+ ]+ google_message = handler._create_tool_result_message(results, "google")+ assert google_message == {+ "role": "user",+ "parts": [{"functionResponse": {"name": "headroom_retrieve", "response": {"count": 1}}}],+ }++ generic_message = handler._create_tool_result_message(+ [CCRToolResult(tool_call_id="tool-1", content="not-json", success=False)],+ "other",+ )+ assert generic_message["role"] == "tool"+ assert json.loads(generic_message["content"]) == [+ {"tool_call_id": "tool-1", "result": "not-json"}+ ]++ invalid_google = handler._create_tool_result_message(+ [CCRToolResult(tool_call_id="headroom_retrieve", content="not-json", success=True)],+ "google",+ )+ assert invalid_google["parts"][0]["functionResponse"]["response"] == {"content": "not-json"}+++def test_extract_assistant_message_google_and_generic() -> None:+ handler = CCRResponseHandler()+ google_message = handler._extract_assistant_message(+ {"candidates": [{"content": {"parts": [{"text": "hello"}]}}]},+ "google",+ )+ assert google_message == {"role": "model", "parts": [{"text": "hello"}]}++ assert handler._extract_assistant_message({}, "google") == {"role": "model", "parts": []}+ assert handler._extract_assistant_message({"content": "plain"}, "other") == {+ "role": "assistant",+ "content": "plain",+ }+++async def test_handle_response_openai_success_and_failure(monkeypatch: pytest.MonkeyPatch) -> None:+ handler = CCRResponseHandler()+ initial_response = {+ "choices": [+ {+ "message": {+ "role": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": CCR_TOOL_NAME,+ "arguments": '{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}',+ },+ }+ ],+ }+ }+ ]+ }+ monkeypatch.setattr(+ handler,+ "_execute_retrieval",+ lambda call: CCRToolResult(+ tool_call_id=call.tool_call_id,+ content='{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}',+ success=True,+ ),+ )++ captured_messages: list[list[dict[str, Any]]] = []++ async def success_api_call(messages, tools):+ captured_messages.append(messages)+ return {"choices": [{"message": {"role": "assistant", "content": "done"}}]}++ result = await handler.handle_response(+ initial_response, [{"role": "user", "content": "hi"}], [], success_api_call, "openai"+ )+ assert result == {"choices": [{"message": {"role": "assistant", "content": "done"}}]}+ assert captured_messages[0][1]["role"] == "assistant"+ assert captured_messages[0][2]["role"] == "tool"+ assert handler.get_stats()["total_retrievals"] == 1++ async def failing_api_call(messages, tools):+ raise RuntimeError("continuation failed")++ failed = await handler.handle_response(initial_response, [], [], failing_api_call, "openai")+ assert failed == initial_response+++def test_streaming_buffer_and_parse_sse_helpers() -> None:+ buffer = StreamingCCRBuffer()+ assert buffer.add_chunk(b"plain") is False+ assert buffer.get_accumulated() == b"plain"++ handler = StreamingCCRHandler(CCRResponseHandler(), provider="anthropic")+ anthropic_data = b"\n".join(+ [+ b'data: {"type":"content_block_start","content_block":{"type":"text","text":"Hel"}}',+ b'data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"lo"}}',+ b'data: {"type":"content_block_stop"}',+ b'data: {"type":"content_block_start","content_block":{"type":"tool_use","id":"tool_1","name":"headroom_retrieve"}}',+ b'data: {"type":"content_block_delta","delta":{"type":"input_json_delta","partial_json":"{\\"hash\\":\\"abc\\"}"}}',+ b'data: {"type":"content_block_stop"}',+ b'data: {"type":"message_delta","delta":{"stop_reason":"tool_use"}}',+ b"data: [DONE]",+ ]+ )+ parsed = handler._parse_sse_stream(anthropic_data)+ assert parsed["content"][0] == {"type": "text", "text": "Hello"}+ assert parsed["content"][1]["name"] == "headroom_retrieve"+ assert parsed["content"][1]["input"] == {"hash": "abc"}+ assert parsed["stop_reason"] == "tool_use"++ openai_handler = StreamingCCRHandler(CCRResponseHandler(), provider="openai")+ parsed_openai = openai_handler._reconstruct_openai_response(+ [+ {"choices": [{"delta": {"content": "Hi"}}]},+ {+ "choices": [+ {+ "delta": {+ "tool_calls": [+ {+ "index": 0,+ "id": "call_1",+ "function": {+ "name": "headroom_retrieve",+ "arguments": '{"hash":"aaaaaaaaaaaa',+ },+ }+ ]+ }+ }+ ]+ },+ {+ "choices": [+ {+ "delta": {+ "tool_calls": [+ {+ "index": 0,+ "function": {"arguments": 'aaaaaaaaaaaa"}'},+ }+ ]+ }+ }+ ]+ },+ ]+ )+ message = parsed_openai["choices"][0]["message"]+ assert message["content"] == "Hi"+ assert message["tool_calls"][0]["id"] == "call_1"+ assert message["tool_calls"][0]["function"]["arguments"] == (+ '{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}'+ )+++async def test_streaming_handler_process_stream_pass_through_and_ccr(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ response_handler = CCRResponseHandler()+ handler = StreamingCCRHandler(response_handler, provider="anthropic")++ passthrough_chunks = [+ b'data: {"type":"content_block_delta","delta":{"text":"hello"}}',+ b'data: {"stop_reason":"end_turn"}',+ ]+ yielded = [+ chunk+ async for chunk in handler.process_stream(+ _async_iter(passthrough_chunks), [], None, lambda m, t: None+ )+ ]+ assert yielded == passthrough_chunks++ ccr_handler = StreamingCCRHandler(response_handler, provider="anthropic")+ monkeypatch.setattr(+ ccr_handler,+ "_parse_sse_stream",+ lambda data: {+ "content": [+ {+ "type": "tool_use",+ "id": "tool_1",+ "name": CCR_TOOL_NAME,+ "input": {"hash": "abc"},+ }+ ]+ },+ )++ async def fake_handle_response(response, messages, tools, api_call_fn, provider): # noqa: ANN001+ return {"content": [{"type": "text", "text": "done"}]}++ async def fake_response_to_sse(response): # noqa: ANN001+ yield b"event: message_start\n"+ yield b"event: message_stop\n"++ monkeypatch.setattr(response_handler, "handle_response", fake_handle_response)+ monkeypatch.setattr(ccr_handler, "_response_to_sse", fake_response_to_sse)++ ccr_chunks = [+ b'{"type":"tool_use","name":"headroom_retrieve"',+ b',"stop_reason":"tool_use"}',+ b"tail",+ ]+ streamed = [+ chunk+ async for chunk in ccr_handler.process_stream(+ _async_iter(ccr_chunks), [], None, lambda m, t: None+ )+ ]+ assert streamed == [b"event: message_start\n", b"event: message_stop\n"]+++async def test_streaming_handler_falls_back_to_buffer_on_processing_error(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ response_handler = CCRResponseHandler()+ handler = StreamingCCRHandler(response_handler, provider="openai")+ monkeypatch.setattr(+ handler,+ "_parse_sse_stream",+ lambda data: (_ for _ in ()).throw(RuntimeError("parse failed")),+ )++ chunks = [b'{"type":"tool_use","name":"headroom_retrieve"', b',"stop_reason":"tool_use"}']+ streamed = [+ chunk+ async for chunk in handler.process_stream(_async_iter(chunks), [], None, lambda m, t: None)+ ]+ assert streamed == [b"".join(chunks)]+++async def test_response_to_sse_formats() -> None:+ anthropic = StreamingCCRHandler(CCRResponseHandler(), provider="anthropic")+ anthropic_chunks = [chunk async for chunk in anthropic._response_to_sse({"content": []})]+ assert anthropic_chunks[0] == b"event: message_start\n"+ assert anthropic_chunks[-1] == b'data: {"type": "message_stop"}\n\n'++ openai = StreamingCCRHandler(CCRResponseHandler(), provider="openai")+ openai_chunks = [chunk async for chunk in openai._response_to_sse({"choices": []})]+ assert openai_chunks == [b'data: {"choices": []}\n\n', b"data: [DONE]\n\n"]diff --git a/tests/test_cli/test_wrap_copilot.py b/tests/test_cli/test_wrap_copilot.pyindex 79ddbe342..84065b0f2 100644--- a/tests/test_cli/test_wrap_copilot.py+++ b/tests/test_cli/test_wrap_copilot.py@@ -1,335 +1,335 @@-"""Tests for `headroom wrap copilot` command."""--from __future__ import annotations--import importlib-import sys-import types-from pathlib import Path-from unittest.mock import patch--import click-import pytest-from click.testing import CliRunner--from headroom.copilot_auth import DEFAULT_API_URL---def runner() -> CliRunner:- return CliRunner()---def wrap_modules(monkeypatch: pytest.MonkeyPatch) -> tuple[types.ModuleType, click.Group]:- headroom_pkg = sys.modules.get("headroom")- saved_headroom_cli_attr = (- headroom_pkg.cli if headroom_pkg is not None and hasattr(headroom_pkg, "cli") else None- )- saved_modules = {- name: sys.modules.get(name)- for name in ("headroom.cli", "headroom.cli.main", "headroom.cli.wrap")- }-- fake_main_module = types.ModuleType("headroom.cli.main")- fake_main_module.main = click.Group()- sys.modules["headroom.cli.main"] = fake_main_module- sys.modules.pop("headroom.cli", None)- sys.modules.pop("headroom.cli.wrap", None)-- wrap_cli = importlib.import_module("headroom.cli.wrap")- monkeypatch.setattr(wrap_cli, "_check_proxy", lambda _port: False)-- try:- yield wrap_cli, fake_main_module.main- finally:- for name in ("headroom.cli.wrap", "headroom.cli.main", "headroom.cli"):- sys.modules.pop(name, None)- for name, module in saved_modules.items():- if module is not None:- sys.modules[name] = module- if saved_modules["headroom.cli"] is not None:- cli_pkg = saved_modules["headroom.cli"]- if saved_modules["headroom.cli.main"] is not None:- cli_pkg.main = saved_modules["headroom.cli.main"]- if saved_modules["headroom.cli.wrap"] is not None:- cli_pkg.wrap = saved_modules["headroom.cli.wrap"]- if headroom_pkg is not None:- if saved_headroom_cli_attr is None:- if hasattr(headroom_pkg, "cli"):- delattr(headroom_pkg, "cli")- else:- headroom_pkg.cli = saved_headroom_cli_attr---def test_wrap_copilot_auto_anthropic_injects_instructions(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],- tmp_path: Path,- monkeypatch: pytest.MonkeyPatch,-) -> None:- wrap_cli, main = wrap_modules- monkeypatch.chdir(tmp_path)- monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")- captured: dict[str, object] = {}-- def fake_launch_tool(**kwargs): # noqa: ANN003- captured.update(kwargs)-- with (- patch("headroom.cli.wrap.shutil.which", return_value="copilot"),- patch("headroom.cli.wrap.has_oauth_auth", return_value=False),- patch("headroom.cli.wrap._ensure_rtk_binary", return_value=Path("/tmp/rtk")),- patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),- ):- result = runner.invoke(- main,- ["wrap", "copilot", "--", "--model", "claude-sonnet-4-20250514"],- )-- assert result.exit_code == 0, result.output- instructions = tmp_path / ".github" / "copilot-instructions.md"- assert instructions.exists()- content = instructions.read_text()- assert wrap_cli._RTK_MARKER in content- assert "RTK (Rust Token Killer)" in content-- 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 "COPILOT_PROVIDER_WIRE_API" not in env- assert captured["agent_type"] == "copilot"- assert captured["tool_label"] == "COPILOT"- assert captured["args"] == ("--model", "claude-sonnet-4-20250514")---def test_wrap_copilot_openai_backend_sets_completions_env(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],- monkeypatch: pytest.MonkeyPatch,-) -> None:- _wrap_cli, main = wrap_modules- monkeypatch.setenv("OPENAI_API_KEY", "sk-test-dummy")- captured: dict[str, object] = {}-- def fake_launch_tool(**kwargs): # noqa: ANN003- captured.update(kwargs)-- with (- patch("headroom.cli.wrap.shutil.which", return_value="copilot"),- patch("headroom.cli.wrap.has_oauth_auth", return_value=False),- patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),- ):- result = runner.invoke(- main,- [- "wrap",- "copilot",- "--no-rtk",- "--backend",- "anyllm",- "--anyllm-provider",- "groq",- "--region",- "us-central1",- "--",- "--model",- "gpt-4o",- ],- )-- assert result.exit_code == 0, result.output-- 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_WIRE_API"] == "completions"- assert captured["backend"] == "anyllm"- assert captured["anyllm_provider"] == "groq"- assert captured["region"] == "us-central1"- assert captured["args"] == ("--model", "gpt-4o")---def test_wrap_copilot_auto_detects_running_proxy_backend(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],- monkeypatch: pytest.MonkeyPatch,-) -> None:- _wrap_cli, main = wrap_modules- monkeypatch.setenv("OPENAI_API_KEY", "sk-test-dummy")- captured: dict[str, object] = {}-- def fake_launch_tool(**kwargs): # noqa: ANN003- captured.update(kwargs)-- with (- patch("headroom.cli.wrap.shutil.which", return_value="copilot"),- patch("headroom.cli.wrap.has_oauth_auth", return_value=False),- patch("headroom.cli.wrap._check_proxy", return_value=True),- patch("headroom.cli.wrap._detect_running_proxy_backend", return_value="anyllm"),- patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),- ):- result = runner.invoke(- main,- ["wrap", "copilot", "--no-rtk", "--", "--model", "gpt-4o"],- )-- assert result.exit_code == 0, result.output- 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_WIRE_API"] == "completions"---def test_wrap_copilot_prefers_existing_oauth_session(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],- monkeypatch: pytest.MonkeyPatch,-) -> None:- _wrap_cli, main = wrap_modules- monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")- captured: dict[str, object] = {}-- def fake_launch_tool(**kwargs): # noqa: ANN003- captured.update(kwargs)-- with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):- with patch("headroom.cli.wrap.resolve_client_bearer_token", return_value="gho-existing"):- with patch("headroom.cli.wrap.has_oauth_auth", return_value=True):- with patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool):- result = runner.invoke(- main,- ["wrap", "copilot", "--no-rtk", "--", "--model", "claude-sonnet-4.6"],- )-- assert result.exit_code == 0, result.output- 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_WIRE_API"] == "completions"- assert env["COPILOT_PROVIDER_BEARER_TOKEN"] == "gho-existing"- assert "COPILOT_PROVIDER_API_KEY" not in env- assert captured["openai_api_url"] == DEFAULT_API_URL---def test_wrap_copilot_translated_backend_still_requires_byok(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],-) -> None:- _wrap_cli, main = wrap_modules- with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):- with patch("headroom.cli.wrap.has_oauth_auth", return_value=True):- result = runner.invoke(- main,- [- "wrap",- "copilot",- "--no-rtk",- "--backend",- "anyllm",- "--",- "--model",- "gpt-4o",- ],- )-- assert result.exit_code == 1- assert "Copilot BYOK mode requires a provider API key" in result.output---def test_wrap_copilot_rejects_wire_api_for_anthropic_provider(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],-) -> None:- _wrap_cli, main = wrap_modules- with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):- result = runner.invoke(- main,- [- "wrap",- "copilot",- "--wire-api",- "responses",- "--",- "--model",- "claude-sonnet-4-20250514",- ],- )-- assert result.exit_code != 0- assert "--wire-api is only valid" in result.output---def test_wrap_copilot_rejects_responses_for_translated_backends(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],-) -> None:- _wrap_cli, main = wrap_modules- with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):- result = runner.invoke(- main,- [- "wrap",- "copilot",- "--backend",- "anyllm",- "--wire-api",- "responses",- "--",- "--model",- "gpt-4o",- ],- )-- assert result.exit_code != 0- assert "not supported with translated backends" in result.output---def test_wrap_copilot_clears_stale_wire_api_in_anthropic_mode(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],- monkeypatch: pytest.MonkeyPatch,-) -> None:- _wrap_cli, main = wrap_modules- monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")- captured: dict[str, object] = {}-- def fake_launch_tool(**kwargs): # noqa: ANN003- captured.update(kwargs)-- with (- patch("headroom.cli.wrap.shutil.which", return_value="copilot"),- patch("headroom.cli.wrap.has_oauth_auth", return_value=False),- patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),- ):- result = runner.invoke(- main,- ["wrap", "copilot", "--no-rtk", "--", "--model", "claude-sonnet-4-20250514"],- env={- "COPILOT_PROVIDER_WIRE_API": "responses",- "ANTHROPIC_API_KEY": "sk-test-dummy",- },- )-- assert result.exit_code == 0, result.output- env = captured["env"]- assert isinstance(env, dict)- assert env["COPILOT_PROVIDER_TYPE"] == "anthropic"- assert "COPILOT_PROVIDER_WIRE_API" not in env---def test_wrap_copilot_fails_when_binary_missing(- runner: CliRunner,- wrap_modules: tuple[types.ModuleType, click.Group],-) -> None:- _wrap_cli, main = wrap_modules- with patch("headroom.cli.wrap.shutil.which", return_value=None):- result = runner.invoke(main, ["wrap", "copilot", "--", "--model", "gpt-4o"])-- assert result.exit_code == 1- assert "'copilot' not found in PATH" in result.output- assert "Install GitHub Copilot CLI" in result.output+"""Tests for `headroom wrap copilot` command."""++from __future__ import annotations++import importlib+import sys+import types+from pathlib import Path+from unittest.mock import patch++import click+import pytest+from click.testing import CliRunner++from headroom.copilot_auth import DEFAULT_API_URL+++def runner() -> CliRunner:+ return CliRunner()+++def wrap_modules(monkeypatch: pytest.MonkeyPatch) -> tuple[types.ModuleType, click.Group]:+ headroom_pkg = sys.modules.get("headroom")+ saved_headroom_cli_attr = (+ headroom_pkg.cli if headroom_pkg is not None and hasattr(headroom_pkg, "cli") else None+ )+ saved_modules = {+ name: sys.modules.get(name)+ for name in ("headroom.cli", "headroom.cli.main", "headroom.cli.wrap")+ }++ fake_main_module = types.ModuleType("headroom.cli.main")+ fake_main_module.main = click.Group()+ sys.modules["headroom.cli.main"] = fake_main_module+ sys.modules.pop("headroom.cli", None)+ sys.modules.pop("headroom.cli.wrap", None)++ wrap_cli = importlib.import_module("headroom.cli.wrap")+ monkeypatch.setattr(wrap_cli, "_check_proxy", lambda _port: False)++ try:+ yield wrap_cli, fake_main_module.main+ finally:+ for name in ("headroom.cli.wrap", "headroom.cli.main", "headroom.cli"):+ sys.modules.pop(name, None)+ for name, module in saved_modules.items():+ if module is not None:+ sys.modules[name] = module+ if saved_modules["headroom.cli"] is not None:+ cli_pkg = saved_modules["headroom.cli"]+ if saved_modules["headroom.cli.main"] is not None:+ cli_pkg.main = saved_modules["headroom.cli.main"]+ if saved_modules["headroom.cli.wrap"] is not None:+ cli_pkg.wrap = saved_modules["headroom.cli.wrap"]+ if headroom_pkg is not None:+ if saved_headroom_cli_attr is None:+ if hasattr(headroom_pkg, "cli"):+ delattr(headroom_pkg, "cli")+ else:+ headroom_pkg.cli = saved_headroom_cli_attr+++def test_wrap_copilot_auto_anthropic_injects_instructions(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ wrap_cli, main = wrap_modules+ monkeypatch.chdir(tmp_path)+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")+ captured: dict[str, object] = {}++ def fake_launch_tool(**kwargs): # noqa: ANN003+ captured.update(kwargs)++ with (+ patch("headroom.cli.wrap.shutil.which", return_value="copilot"),+ patch("headroom.cli.wrap.has_oauth_auth", return_value=False),+ patch("headroom.cli.wrap._ensure_rtk_binary", return_value=Path("/tmp/rtk")),+ patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),+ ):+ result = runner.invoke(+ main,+ ["wrap", "copilot", "--", "--model", "claude-sonnet-4-20250514"],+ )++ assert result.exit_code == 0, result.output+ instructions = tmp_path / ".github" / "copilot-instructions.md"+ assert instructions.exists()+ content = instructions.read_text()+ assert wrap_cli._RTK_MARKER in content+ assert "RTK (Rust Token Killer)" in content++ 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 "COPILOT_PROVIDER_WIRE_API" not in env+ assert captured["agent_type"] == "copilot"+ assert captured["tool_label"] == "COPILOT"+ assert captured["args"] == ("--model", "claude-sonnet-4-20250514")+++def test_wrap_copilot_openai_backend_sets_completions_env(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _wrap_cli, main = wrap_modules+ monkeypatch.setenv("OPENAI_API_KEY", "sk-test-dummy")+ captured: dict[str, object] = {}++ def fake_launch_tool(**kwargs): # noqa: ANN003+ captured.update(kwargs)++ with (+ patch("headroom.cli.wrap.shutil.which", return_value="copilot"),+ patch("headroom.cli.wrap.has_oauth_auth", return_value=False),+ patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),+ ):+ result = runner.invoke(+ main,+ [+ "wrap",+ "copilot",+ "--no-rtk",+ "--backend",+ "anyllm",+ "--anyllm-provider",+ "groq",+ "--region",+ "us-central1",+ "--",+ "--model",+ "gpt-4o",+ ],+ )++ assert result.exit_code == 0, result.output++ 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_WIRE_API"] == "completions"+ assert captured["backend"] == "anyllm"+ assert captured["anyllm_provider"] == "groq"+ assert captured["region"] == "us-central1"+ assert captured["args"] == ("--model", "gpt-4o")+++def test_wrap_copilot_auto_detects_running_proxy_backend(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _wrap_cli, main = wrap_modules+ monkeypatch.setenv("OPENAI_API_KEY", "sk-test-dummy")+ captured: dict[str, object] = {}++ def fake_launch_tool(**kwargs): # noqa: ANN003+ captured.update(kwargs)++ with (+ patch("headroom.cli.wrap.shutil.which", return_value="copilot"),+ patch("headroom.cli.wrap.has_oauth_auth", return_value=False),+ patch("headroom.cli.wrap._check_proxy", return_value=True),+ patch("headroom.cli.wrap._detect_running_proxy_backend", return_value="anyllm"),+ patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),+ ):+ result = runner.invoke(+ main,+ ["wrap", "copilot", "--no-rtk", "--", "--model", "gpt-4o"],+ )++ assert result.exit_code == 0, result.output+ 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_WIRE_API"] == "completions"+++def test_wrap_copilot_prefers_existing_oauth_session(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _wrap_cli, main = wrap_modules+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")+ captured: dict[str, object] = {}++ def fake_launch_tool(**kwargs): # noqa: ANN003+ captured.update(kwargs)++ with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):+ with patch("headroom.cli.wrap.resolve_client_bearer_token", return_value="gho-existing"):+ with patch("headroom.cli.wrap.has_oauth_auth", return_value=True):+ with patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool):+ result = runner.invoke(+ main,+ ["wrap", "copilot", "--no-rtk", "--", "--model", "claude-sonnet-4.6"],+ )++ assert result.exit_code == 0, result.output+ 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_WIRE_API"] == "completions"+ assert env["COPILOT_PROVIDER_BEARER_TOKEN"] == "gho-existing"+ assert "COPILOT_PROVIDER_API_KEY" not in env+ assert captured["openai_api_url"] == DEFAULT_API_URL+++def test_wrap_copilot_translated_backend_still_requires_byok(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+) -> None:+ _wrap_cli, main = wrap_modules+ with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):+ with patch("headroom.cli.wrap.has_oauth_auth", return_value=True):+ result = runner.invoke(+ main,+ [+ "wrap",+ "copilot",+ "--no-rtk",+ "--backend",+ "anyllm",+ "--",+ "--model",+ "gpt-4o",+ ],+ )++ assert result.exit_code == 1+ assert "Copilot BYOK mode requires a provider API key" in result.output+++def test_wrap_copilot_rejects_wire_api_for_anthropic_provider(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+) -> None:+ _wrap_cli, main = wrap_modules+ with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):+ result = runner.invoke(+ main,+ [+ "wrap",+ "copilot",+ "--wire-api",+ "responses",+ "--",+ "--model",+ "claude-sonnet-4-20250514",+ ],+ )++ assert result.exit_code != 0+ assert "--wire-api is only valid" in result.output+++def test_wrap_copilot_rejects_responses_for_translated_backends(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+) -> None:+ _wrap_cli, main = wrap_modules+ with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):+ result = runner.invoke(+ main,+ [+ "wrap",+ "copilot",+ "--backend",+ "anyllm",+ "--wire-api",+ "responses",+ "--",+ "--model",+ "gpt-4o",+ ],+ )++ assert result.exit_code != 0+ assert "not supported with translated backends" in result.output+++def test_wrap_copilot_clears_stale_wire_api_in_anthropic_mode(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _wrap_cli, main = wrap_modules+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")+ captured: dict[str, object] = {}++ def fake_launch_tool(**kwargs): # noqa: ANN003+ captured.update(kwargs)++ with (+ patch("headroom.cli.wrap.shutil.which", return_value="copilot"),+ patch("headroom.cli.wrap.has_oauth_auth", return_value=False),+ patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),+ ):+ result = runner.invoke(+ main,+ ["wrap", "copilot", "--no-rtk", "--", "--model", "claude-sonnet-4-20250514"],+ env={+ "COPILOT_PROVIDER_WIRE_API": "responses",+ "ANTHROPIC_API_KEY": "sk-test-dummy",+ },+ )++ assert result.exit_code == 0, result.output+ env = captured["env"]+ assert isinstance(env, dict)+ assert env["COPILOT_PROVIDER_TYPE"] == "anthropic"+ assert "COPILOT_PROVIDER_WIRE_API" not in env+++def test_wrap_copilot_fails_when_binary_missing(+ runner: CliRunner,+ wrap_modules: tuple[types.ModuleType, click.Group],+) -> None:+ _wrap_cli, main = wrap_modules+ with patch("headroom.cli.wrap.shutil.which", return_value=None):+ result = runner.invoke(main, ["wrap", "copilot", "--", "--model", "gpt-4o"])++ assert result.exit_code == 1+ assert "'copilot' not found in PATH" in result.output+ assert "Install GitHub Copilot CLI" in result.outputdiff --git a/tests/test_cli_learn.py b/tests/test_cli_learn.pyindex 875a44540..33a64d82d 100644--- a/tests/test_cli_learn.py+++ b/tests/test_cli_learn.py@@ -1,266 +1,266 @@-from __future__ import annotations--from pathlib import Path-from types import SimpleNamespace--import click-import click.shell_completion as click_shell_completion-import pytest-from click.testing import CliRunner--from headroom.cli.learn import _AgentChoice-from headroom.cli.main import main---def runner() -> CliRunner:- return CliRunner()---class FakeWriter:- def __init__(self) -> None:- self.calls: list[tuple[list[object], object, bool]] = []-- def write(self, recommendations, project, dry_run: bool): # noqa: ANN001, ANN201- self.calls.append((recommendations, project, dry_run))- return SimpleNamespace(- dry_run=dry_run,- content_by_file={- Path(project.project_path) / "AGENTS.md": "<!-- headroom -->\nRule 1\nRule 2"- },- )---class FakePlugin:- def __init__(self, name: str, display_name: str, projects: list[object]) -> None:- self.name = name- self.display_name = display_name- self._projects = projects- self.writer = FakeWriter()- self.scan_calls: list[tuple[object, int]] = []-- def detect(self) -> bool:- return True-- def create_writer(self) -> FakeWriter:- return self.writer-- def discover_projects(self) -> list[object]:- return self._projects-- def scan_project(self, project, max_workers: int = 1): # noqa: ANN001, ANN201- self.scan_calls.append((project, max_workers))- return [SimpleNamespace(events=["event"], tool_calls=[], failure_count=0)]---class FakeAnalyzer:- def __init__(self, model: str | None = None) -> None:- self.model = model- self.calls: list[tuple[object, list[object]]] = []-- def analyze(self, project, sessions): # noqa: ANN001, ANN201- self.calls.append((project, sessions))- return SimpleNamespace(- total_sessions=len(sessions),- total_calls=3,- total_failures=1,- failure_rate=1 / 3,- recommendations=[SimpleNamespace(section="Rules")],- )---def test_agent_choice_convert_and_shell_complete(monkeypatch: pytest.MonkeyPatch) -> None:- choice = _AgentChoice()- monkeypatch.setattr(click, "shell_completion", click_shell_completion)- monkeypatch.setattr(- "headroom.learn.registry.get_registry",- lambda: {"codex": object(), "claude": object()},- )- monkeypatch.setattr(- "headroom.learn.registry.available_agent_names",- lambda: ["claude", "codex"],- )-- assert choice.convert("auto", None, None) == "auto"- assert choice.convert("CODEX", None, None) == "codex"- with pytest.raises(Exception, match="Unknown agent: bad"):- choice.convert("bad", None, None)-- completions = choice.shell_complete(None, None, "c") # type: ignore[arg-type]- assert [item.value for item in completions] == ["claude", "codex"]- assert choice.get_metavar(None) == "[auto|<agent>]" # type: ignore[arg-type]---def test_learn_exits_cleanly_when_model_detection_fails(- monkeypatch: pytest.MonkeyPatch, runner: CliRunner-) -> None:- monkeypatch.setattr(- "headroom.learn.analyzer._detect_default_model",- lambda: (_ for _ in ()).throw(RuntimeError("no model")),- )-- result = runner.invoke(main, ["learn"], catch_exceptions=False)-- assert result.exit_code == 1- assert "Error: no model" in result.output---def test_learn_auto_agent_reports_no_detected_plugins(- monkeypatch: pytest.MonkeyPatch, runner: CliRunner-) -> None:- monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")- monkeypatch.setattr("headroom.learn.registry.auto_detect_plugins", lambda: [])- monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)-- result = runner.invoke(main, ["learn"], catch_exceptions=False)-- assert result.exit_code == 0- assert "No coding agent data found." in result.output---def test_learn_single_agent_shows_available_projects_when_cwd_missing(- monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path-) -> None:- project = SimpleNamespace(name="demo", project_path=tmp_path / "demo")- plugin = FakePlugin("codex", "Codex", [project])-- monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")- monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)- monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)-- with runner.isolated_filesystem(temp_dir=tmp_path):- result = runner.invoke(main, ["learn", "--agent", "codex"], catch_exceptions=False)-- assert result.exit_code == 0- assert "No codex project data found for" in result.output- assert "Available codex projects:" in result.output- assert "demo" in result.output---def test_learn_project_lookup_and_apply_flow(- monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path-) -> None:- project_path = tmp_path / "project-a"- project_path.mkdir()- matched = SimpleNamespace(name="project-a", project_path=project_path)- unmatched = SimpleNamespace(name="project-b", project_path=tmp_path / "project-b")- plugin = FakePlugin("codex", "Codex", [matched, unmatched])- analyzer = FakeAnalyzer()-- monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")- monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)- monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)-- result = runner.invoke(- main,- ["learn", "--agent", "codex", "--project", str(project_path), "--apply", "--workers", "4"],- catch_exceptions=False,- )-- assert result.exit_code == 0, result.output- assert "Path: " in result.output- assert "Analyzing with gpt-4o..." in result.output- assert "Recommendations: 1" in result.output- assert "[WROTE]" in result.output- assert "Rule 1" in result.output- assert plugin.scan_calls == [(matched, 4)]- assert analyzer.calls[0][0] is matched- assert plugin.writer.calls[0][2] is False---def test_learn_reports_missing_requested_project_and_lists_discovered(- monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path-) -> None:- requested = tmp_path / "missing"- requested.mkdir()- discovered = SimpleNamespace(name="project-a", project_path=tmp_path / "project-a")- plugin = FakePlugin("claude", "Claude Code", [discovered])-- monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")- monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)- monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)-- result = runner.invoke(- main,- ["learn", "--agent", "claude", "--project", str(requested)],- catch_exceptions=False,- )-- assert result.exit_code == 0- assert f"No project data found for {requested.resolve()}" in result.output- assert "Available discovered projects:" in result.output- assert "[claude]" in result.output---def test_learn_analyze_all_uses_default_workers_and_prints_summary(- monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path-) -> None:- projects_a = [SimpleNamespace(name="a", project_path=tmp_path / "a")]- projects_b = [SimpleNamespace(name="b", project_path=tmp_path / "b")]- plugin_a = FakePlugin("codex", "Codex", projects_a)- plugin_b = FakePlugin("claude", "Claude Code", projects_b)- analyzer = FakeAnalyzer()-- monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")- monkeypatch.setattr(- "headroom.learn.registry.auto_detect_plugins",- lambda: [plugin_a, plugin_b],- )- monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)- monkeypatch.setattr("os.cpu_count", lambda: 12)-- result = runner.invoke(main, ["learn", "--all"], catch_exceptions=False)-- assert result.exit_code == 0, result.output- assert "Detected agents: Codex, Claude Code" in result.output- assert "Total: 2 projects, 2 failures, 2 recommendations" in result.output- assert plugin_a.scan_calls == [(projects_a[0], 8)]- assert plugin_b.scan_calls == [(projects_b[0], 8)]---def test_learn_handles_empty_sessions_and_no_pattern_outputs(- monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path-) -> None:- no_sessions = SimpleNamespace(name="empty", project_path=tmp_path / "empty")- no_failures = SimpleNamespace(name="clean", project_path=tmp_path / "clean")- no_actions = SimpleNamespace(name="no-actions", project_path=tmp_path / "no-actions")-- class BranchingPlugin(FakePlugin):- def scan_project(self, project, max_workers: int = 1): # noqa: ANN001, ANN201- self.scan_calls.append((project, max_workers))- if project is no_sessions:- return []- return [SimpleNamespace(events=["event"], tool_calls=[], failure_count=0)]-- class BranchingAnalyzer(FakeAnalyzer):- def analyze(self, project, sessions): # noqa: ANN001, ANN201- self.calls.append((project, sessions))- if project is no_failures:- return SimpleNamespace(- total_sessions=1,- total_calls=2,- total_failures=0,- failure_rate=0.0,- recommendations=[],- )- return SimpleNamespace(- total_sessions=1,- total_calls=2,- total_failures=1,- failure_rate=0.5,- recommendations=[],- )-- plugin = BranchingPlugin("codex", "Codex", [no_sessions, no_failures, no_actions])- analyzer = BranchingAnalyzer()-- monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")- monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)- monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)-- result = runner.invoke(main, ["learn", "--agent", "codex", "--all"], catch_exceptions=False)-- assert result.exit_code == 0, result.output- assert "No conversation data found." in result.output- assert "No failures or patterns found." in result.output- assert "No actionable patterns found." in result.output+from __future__ import annotations++from pathlib import Path+from types import SimpleNamespace++import click+import click.shell_completion as click_shell_completion+import pytest+from click.testing import CliRunner++from headroom.cli.learn import _AgentChoice+from headroom.cli.main import main+++def runner() -> CliRunner:+ return CliRunner()+++class FakeWriter:+ def __init__(self) -> None:+ self.calls: list[tuple[list[object], object, bool]] = []++ def write(self, recommendations, project, dry_run: bool): # noqa: ANN001, ANN201+ self.calls.append((recommendations, project, dry_run))+ return SimpleNamespace(+ dry_run=dry_run,+ content_by_file={+ Path(project.project_path) / "AGENTS.md": "<!-- headroom -->\nRule 1\nRule 2"+ },+ )+++class FakePlugin:+ def __init__(self, name: str, display_name: str, projects: list[object]) -> None:+ self.name = name+ self.display_name = display_name+ self._projects = projects+ self.writer = FakeWriter()+ self.scan_calls: list[tuple[object, int]] = []++ def detect(self) -> bool:+ return True++ def create_writer(self) -> FakeWriter:+ return self.writer++ def discover_projects(self) -> list[object]:+ return self._projects++ def scan_project(self, project, max_workers: int = 1): # noqa: ANN001, ANN201+ self.scan_calls.append((project, max_workers))+ return [SimpleNamespace(events=["event"], tool_calls=[], failure_count=0)]+++class FakeAnalyzer:+ def __init__(self, model: str | None = None) -> None:+ self.model = model+ self.calls: list[tuple[object, list[object]]] = []++ def analyze(self, project, sessions): # noqa: ANN001, ANN201+ self.calls.append((project, sessions))+ return SimpleNamespace(+ total_sessions=len(sessions),+ total_calls=3,+ total_failures=1,+ failure_rate=1 / 3,+ recommendations=[SimpleNamespace(section="Rules")],+ )+++def test_agent_choice_convert_and_shell_complete(monkeypatch: pytest.MonkeyPatch) -> None:+ choice = _AgentChoice()+ monkeypatch.setattr(click, "shell_completion", click_shell_completion)+ monkeypatch.setattr(+ "headroom.learn.registry.get_registry",+ lambda: {"codex": object(), "claude": object()},+ )+ monkeypatch.setattr(+ "headroom.learn.registry.available_agent_names",+ lambda: ["claude", "codex"],+ )++ assert choice.convert("auto", None, None) == "auto"+ assert choice.convert("CODEX", None, None) == "codex"+ with pytest.raises(Exception, match="Unknown agent: bad"):+ choice.convert("bad", None, None)++ completions = choice.shell_complete(None, None, "c") # type: ignore[arg-type]+ assert [item.value for item in completions] == ["claude", "codex"]+ assert choice.get_metavar(None) == "[auto|<agent>]" # type: ignore[arg-type]+++def test_learn_exits_cleanly_when_model_detection_fails(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner+) -> None:+ monkeypatch.setattr(+ "headroom.learn.analyzer._detect_default_model",+ lambda: (_ for _ in ()).throw(RuntimeError("no model")),+ )++ result = runner.invoke(main, ["learn"], catch_exceptions=False)++ assert result.exit_code == 1+ assert "Error: no model" in result.output+++def test_learn_auto_agent_reports_no_detected_plugins(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner+) -> None:+ monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")+ monkeypatch.setattr("headroom.learn.registry.auto_detect_plugins", lambda: [])+ monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)++ result = runner.invoke(main, ["learn"], catch_exceptions=False)++ assert result.exit_code == 0+ assert "No coding agent data found." in result.output+++def test_learn_single_agent_shows_available_projects_when_cwd_missing(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path+) -> None:+ project = SimpleNamespace(name="demo", project_path=tmp_path / "demo")+ plugin = FakePlugin("codex", "Codex", [project])++ monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")+ monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)+ monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)++ with runner.isolated_filesystem(temp_dir=tmp_path):+ result = runner.invoke(main, ["learn", "--agent", "codex"], catch_exceptions=False)++ assert result.exit_code == 0+ assert "No codex project data found for" in result.output+ assert "Available codex projects:" in result.output+ assert "demo" in result.output+++def test_learn_project_lookup_and_apply_flow(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path+) -> None:+ project_path = tmp_path / "project-a"+ project_path.mkdir()+ matched = SimpleNamespace(name="project-a", project_path=project_path)+ unmatched = SimpleNamespace(name="project-b", project_path=tmp_path / "project-b")+ plugin = FakePlugin("codex", "Codex", [matched, unmatched])+ analyzer = FakeAnalyzer()++ monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")+ monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)+ monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)++ result = runner.invoke(+ main,+ ["learn", "--agent", "codex", "--project", str(project_path), "--apply", "--workers", "4"],+ catch_exceptions=False,+ )++ assert result.exit_code == 0, result.output+ assert "Path: " in result.output+ assert "Analyzing with gpt-4o..." in result.output+ assert "Recommendations: 1" in result.output+ assert "[WROTE]" in result.output+ assert "Rule 1" in result.output+ assert plugin.scan_calls == [(matched, 4)]+ assert analyzer.calls[0][0] is matched+ assert plugin.writer.calls[0][2] is False+++def test_learn_reports_missing_requested_project_and_lists_discovered(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path+) -> None:+ requested = tmp_path / "missing"+ requested.mkdir()+ discovered = SimpleNamespace(name="project-a", project_path=tmp_path / "project-a")+ plugin = FakePlugin("claude", "Claude Code", [discovered])++ monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")+ monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)+ monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)++ result = runner.invoke(+ main,+ ["learn", "--agent", "claude", "--project", str(requested)],+ catch_exceptions=False,+ )++ assert result.exit_code == 0+ assert f"No project data found for {requested.resolve()}" in result.output+ assert "Available discovered projects:" in result.output+ assert "[claude]" in result.output+++def test_learn_analyze_all_uses_default_workers_and_prints_summary(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path+) -> None:+ projects_a = [SimpleNamespace(name="a", project_path=tmp_path / "a")]+ projects_b = [SimpleNamespace(name="b", project_path=tmp_path / "b")]+ plugin_a = FakePlugin("codex", "Codex", projects_a)+ plugin_b = FakePlugin("claude", "Claude Code", projects_b)+ analyzer = FakeAnalyzer()++ monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")+ monkeypatch.setattr(+ "headroom.learn.registry.auto_detect_plugins",+ lambda: [plugin_a, plugin_b],+ )+ monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)+ monkeypatch.setattr("os.cpu_count", lambda: 12)++ result = runner.invoke(main, ["learn", "--all"], catch_exceptions=False)++ assert result.exit_code == 0, result.output+ assert "Detected agents: Codex, Claude Code" in result.output+ assert "Total: 2 projects, 2 failures, 2 recommendations" in result.output+ assert plugin_a.scan_calls == [(projects_a[0], 8)]+ assert plugin_b.scan_calls == [(projects_b[0], 8)]+++def test_learn_handles_empty_sessions_and_no_pattern_outputs(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path+) -> None:+ no_sessions = SimpleNamespace(name="empty", project_path=tmp_path / "empty")+ no_failures = SimpleNamespace(name="clean", project_path=tmp_path / "clean")+ no_actions = SimpleNamespace(name="no-actions", project_path=tmp_path / "no-actions")++ class BranchingPlugin(FakePlugin):+ def scan_project(self, project, max_workers: int = 1): # noqa: ANN001, ANN201+ self.scan_calls.append((project, max_workers))+ if project is no_sessions:+ return []+ return [SimpleNamespace(events=["event"], tool_calls=[], failure_count=0)]++ class BranchingAnalyzer(FakeAnalyzer):+ def analyze(self, project, sessions): # noqa: ANN001, ANN201+ self.calls.append((project, sessions))+ if project is no_failures:+ return SimpleNamespace(+ total_sessions=1,+ total_calls=2,+ total_failures=0,+ failure_rate=0.0,+ recommendations=[],+ )+ return SimpleNamespace(+ total_sessions=1,+ total_calls=2,+ total_failures=1,+ failure_rate=0.5,+ recommendations=[],+ )++ plugin = BranchingPlugin("codex", "Codex", [no_sessions, no_failures, no_actions])+ analyzer = BranchingAnalyzer()++ monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")+ monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)+ monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)++ result = runner.invoke(main, ["learn", "--agent", "codex", "--all"], catch_exceptions=False)++ assert result.exit_code == 0, result.output+ assert "No conversation data found." in result.output+ assert "No failures or patterns found." in result.output+ assert "No actionable patterns found." in result.outputdiff --git a/tests/test_codex_rate_limits.py b/tests/test_codex_rate_limits.pyindex 58586e533..3da06d12b 100644--- a/tests/test_codex_rate_limits.py+++ b/tests/test_codex_rate_limits.py@@ -1,227 +1,227 @@-"""Unit tests for headroom.subscription.codex_rate_limits."""--from __future__ import annotations--import time--from headroom.subscription.codex_rate_limits import (- CodexRateLimitState,- CodexRateLimitWindow,- parse_codex_rate_limits,-)--# ----------------------------------------------------------------------------# CodexRateLimitWindow helpers-# ------------------------------------------------------------------------------class TestCodexRateLimitWindow:- def test_window_label_minutes(self):- w = CodexRateLimitWindow(used_percent=10.0, window_minutes=45)- assert w.window_label == "45m"-- def test_window_label_hours(self):- w = CodexRateLimitWindow(used_percent=10.0, window_minutes=60)- assert w.window_label == "1h"-- def test_window_label_hours_with_minutes(self):- w = CodexRateLimitWindow(used_percent=10.0, window_minutes=90)- assert w.window_label == "1h30m"-- def test_window_label_unknown(self):- w = CodexRateLimitWindow(used_percent=10.0, window_minutes=None)- assert w.window_label == "unknown"-- def test_seconds_until_reset_future(self):- future = int(time.time()) + 3600- w = CodexRateLimitWindow(used_percent=10.0, resets_at=future)- secs = w.seconds_until_reset- assert secs is not None- assert 3590 <= secs <= 3600-- def test_seconds_until_reset_past(self):- past = int(time.time()) - 100- w = CodexRateLimitWindow(used_percent=10.0, resets_at=past)- assert w.seconds_until_reset == 0-- def test_seconds_until_reset_none(self):- w = CodexRateLimitWindow(used_percent=10.0, resets_at=None)- assert w.seconds_until_reset is None-- def test_to_dict_keys(self):- w = CodexRateLimitWindow(used_percent=42.5, window_minutes=60, resets_at=9999999)- d = w.to_dict()- assert set(d.keys()) == {- "used_percent",- "window_minutes",- "window_label",- "resets_at",- "seconds_until_reset",- }- assert d["used_percent"] == 42.5- assert d["window_label"] == "1h"---# ----------------------------------------------------------------------------# parse_codex_rate_limits-# ------------------------------------------------------------------------------class TestParseCodexRateLimits:- def test_returns_none_for_empty_headers(self):- assert parse_codex_rate_limits({}) is None-- def test_returns_none_for_non_codex_headers(self):- headers = {"content-type": "application/json", "x-request-id": "abc"}- assert parse_codex_rate_limits(headers) is None-- def test_parses_primary_window(self):- headers = {- "x-codex-primary-used-percent": "35.5",- "x-codex-primary-window-minutes": "60",- "x-codex-primary-reset-at": "1704069000",- }- snap = parse_codex_rate_limits(headers)- assert snap is not None- assert snap.limit_id == "codex"- assert snap.primary is not None- assert snap.primary.used_percent == 35.5- assert snap.primary.window_minutes == 60- assert snap.primary.resets_at == 1704069000- assert snap.secondary is None-- def test_parses_secondary_window(self):- headers = {- "x-codex-primary-used-percent": "10.0",- "x-codex-secondary-used-percent": "80.0",- "x-codex-secondary-window-minutes": "1440",- "x-codex-secondary-reset-at": "1704100000",- }- snap = parse_codex_rate_limits(headers)- assert snap is not None- assert snap.secondary is not None- assert snap.secondary.used_percent == 80.0- assert snap.secondary.window_minutes == 1440-- def test_parses_credits(self):- headers = {- "x-codex-primary-used-percent": "5.0",- "x-codex-credits-has-credits": "true",- "x-codex-credits-unlimited": "false",- "x-codex-credits-balance": "$12.50",- }- snap = parse_codex_rate_limits(headers)- assert snap is not None- assert snap.credits is not None- assert snap.credits.has_credits is True- assert snap.credits.unlimited is False- assert snap.credits.balance == "$12.50"-- def test_parses_unlimited_credits(self):- headers = {- "x-codex-primary-used-percent": "0.0",- "x-codex-credits-has-credits": "true",- "x-codex-credits-unlimited": "true",- }- snap = parse_codex_rate_limits(headers)- assert snap is not None- assert snap.credits is not None- assert snap.credits.unlimited is True- assert snap.credits.balance is None-- def test_parses_limit_name(self):- headers = {- "x-codex-primary-used-percent": "20.0",- "x-codex-limit-name": "gpt-5.2-codex-sonic",- }- snap = parse_codex_rate_limits(headers)- assert snap is not None- assert snap.limit_name == "gpt-5.2-codex-sonic"-- def test_parses_promo_message(self):- headers = {- "x-codex-primary-used-percent": "50.0",- "x-codex-promo-message": "Try our new model!",- }- snap = parse_codex_rate_limits(headers)- assert snap is not None- assert snap.promo_message == "Try our new model!"-- def test_only_credits_header_triggers_parse(self):- headers = {- "x-codex-credits-has-credits": "true",- "x-codex-credits-unlimited": "false",- }- snap = parse_codex_rate_limits(headers)- assert snap is not None- assert snap.primary is None- assert snap.credits is not None-- def test_invalid_float_ignored(self):- headers = {"x-codex-primary-used-percent": "not_a_number"}- assert parse_codex_rate_limits(headers) is None-- def test_to_dict_structure(self):- headers = {- "x-codex-primary-used-percent": "42.0",- "x-codex-primary-window-minutes": "60",- }- snap = parse_codex_rate_limits(headers)- assert snap is not None- d = snap.to_dict()- assert "limit_id" in d- assert "primary" in d- assert "secondary" in d- assert "credits" in d- assert "captured_at" in d---# ----------------------------------------------------------------------------# CodexRateLimitState-# ------------------------------------------------------------------------------class TestCodexRateLimitState:- def test_initial_state_is_none(self):- state = CodexRateLimitState()- assert state.latest is None- assert state.get_stats() is None-- def test_update_from_headers_stores_snapshot(self):- state = CodexRateLimitState()- headers = {- "x-codex-primary-used-percent": "55.0",- "x-codex-primary-window-minutes": "60",- }- state.update_from_headers(headers)- snap = state.latest- assert snap is not None- assert snap.primary is not None- assert snap.primary.used_percent == 55.0-- def test_update_from_empty_headers_is_noop(self):- state = CodexRateLimitState()- state.update_from_headers({})- assert state.latest is None-- def test_update_from_non_codex_headers_is_noop(self):- state = CodexRateLimitState()- state.update_from_headers({"content-type": "application/json"})- assert state.latest is None-- def test_get_stats_returns_dict_when_data_present(self):- state = CodexRateLimitState()- state.update_from_headers({"x-codex-primary-used-percent": "10.0"})- stats = state.get_stats()- assert stats is not None- assert isinstance(stats, dict)- assert stats["limit_id"] == "codex"-- def test_update_overwrites_previous_snapshot(self):- state = CodexRateLimitState()- state.update_from_headers({"x-codex-primary-used-percent": "10.0"})- state.update_from_headers({"x-codex-primary-used-percent": "90.0"})- snap = state.latest- assert snap is not None- assert snap.primary is not None- assert snap.primary.used_percent == 90.0+"""Unit tests for headroom.subscription.codex_rate_limits."""++from __future__ import annotations++import time++from headroom.subscription.codex_rate_limits import (+ CodexRateLimitState,+ CodexRateLimitWindow,+ parse_codex_rate_limits,+)++# ---------------------------------------------------------------------------+# CodexRateLimitWindow helpers+# ---------------------------------------------------------------------------+++class TestCodexRateLimitWindow:+ def test_window_label_minutes(self):+ w = CodexRateLimitWindow(used_percent=10.0, window_minutes=45)+ assert w.window_label == "45m"++ def test_window_label_hours(self):+ w = CodexRateLimitWindow(used_percent=10.0, window_minutes=60)+ assert w.window_label == "1h"++ def test_window_label_hours_with_minutes(self):+ w = CodexRateLimitWindow(used_percent=10.0, window_minutes=90)+ assert w.window_label == "1h30m"++ def test_window_label_unknown(self):+ w = CodexRateLimitWindow(used_percent=10.0, window_minutes=None)+ assert w.window_label == "unknown"++ def test_seconds_until_reset_future(self):+ future = int(time.time()) + 3600+ w = CodexRateLimitWindow(used_percent=10.0, resets_at=future)+ secs = w.seconds_until_reset+ assert secs is not None+ assert 3590 <= secs <= 3600++ def test_seconds_until_reset_past(self):+ past = int(time.time()) - 100+ w = CodexRateLimitWindow(used_percent=10.0, resets_at=past)+ assert w.seconds_until_reset == 0++ def test_seconds_until_reset_none(self):+ w = CodexRateLimitWindow(used_percent=10.0, resets_at=None)+ assert w.seconds_until_reset is None++ def test_to_dict_keys(self):+ w = CodexRateLimitWindow(used_percent=42.5, window_minutes=60, resets_at=9999999)+ d = w.to_dict()+ assert set(d.keys()) == {+ "used_percent",+ "window_minutes",+ "window_label",+ "resets_at",+ "seconds_until_reset",+ }+ assert d["used_percent"] == 42.5+ assert d["window_label"] == "1h"+++# ---------------------------------------------------------------------------+# parse_codex_rate_limits+# ---------------------------------------------------------------------------+++class TestParseCodexRateLimits:+ def test_returns_none_for_empty_headers(self):+ assert parse_codex_rate_limits({}) is None++ def test_returns_none_for_non_codex_headers(self):+ headers = {"content-type": "application/json", "x-request-id": "abc"}+ assert parse_codex_rate_limits(headers) is None++ def test_parses_primary_window(self):+ headers = {+ "x-codex-primary-used-percent": "35.5",+ "x-codex-primary-window-minutes": "60",+ "x-codex-primary-reset-at": "1704069000",+ }+ snap = parse_codex_rate_limits(headers)+ assert snap is not None+ assert snap.limit_id == "codex"+ assert snap.primary is not None+ assert snap.primary.used_percent == 35.5+ assert snap.primary.window_minutes == 60+ assert snap.primary.resets_at == 1704069000+ assert snap.secondary is None++ def test_parses_secondary_window(self):+ headers = {+ "x-codex-primary-used-percent": "10.0",+ "x-codex-secondary-used-percent": "80.0",+ "x-codex-secondary-window-minutes": "1440",+ "x-codex-secondary-reset-at": "1704100000",+ }+ snap = parse_codex_rate_limits(headers)+ assert snap is not None+ assert snap.secondary is not None+ assert snap.secondary.used_percent == 80.0+ assert snap.secondary.window_minutes == 1440++ def test_parses_credits(self):+ headers = {+ "x-codex-primary-used-percent": "5.0",+ "x-codex-credits-has-credits": "true",+ "x-codex-credits-unlimited": "false",+ "x-codex-credits-balance": "$12.50",+ }+ snap = parse_codex_rate_limits(headers)+ assert snap is not None+ assert snap.credits is not None+ assert snap.credits.has_credits is True+ assert snap.credits.unlimited is False+ assert snap.credits.balance == "$12.50"++ def test_parses_unlimited_credits(self):+ headers = {+ "x-codex-primary-used-percent": "0.0",+ "x-codex-credits-has-credits": "true",+ "x-codex-credits-unlimited": "true",+ }+ snap = parse_codex_rate_limits(headers)+ assert snap is not None+ assert snap.credits is not None+ assert snap.credits.unlimited is True+ assert snap.credits.balance is None++ def test_parses_limit_name(self):+ headers = {+ "x-codex-primary-used-percent": "20.0",+ "x-codex-limit-name": "gpt-5.2-codex-sonic",+ }+ snap = parse_codex_rate_limits(headers)+ assert snap is not None+ assert snap.limit_name == "gpt-5.2-codex-sonic"++ def test_parses_promo_message(self):+ headers = {+ "x-codex-primary-used-percent": "50.0",+ "x-codex-promo-message": "Try our new model!",+ }+ snap = parse_codex_rate_limits(headers)+ assert snap is not None+ assert snap.promo_message == "Try our new model!"++ def test_only_credits_header_triggers_parse(self):+ headers = {+ "x-codex-credits-has-credits": "true",+ "x-codex-credits-unlimited": "false",+ }+ snap = parse_codex_rate_limits(headers)+ assert snap is not None+ assert snap.primary is None+ assert snap.credits is not None++ def test_invalid_float_ignored(self):+ headers = {"x-codex-primary-used-percent": "not_a_number"}+ assert parse_codex_rate_limits(headers) is None++ def test_to_dict_structure(self):+ headers = {+ "x-codex-primary-used-percent": "42.0",+ "x-codex-primary-window-minutes": "60",+ }+ snap = parse_codex_rate_limits(headers)+ assert snap is not None+ d = snap.to_dict()+ assert "limit_id" in d+ assert "primary" in d+ assert "secondary" in d+ assert "credits" in d+ assert "captured_at" in d+++# ---------------------------------------------------------------------------+# CodexRateLimitState+# ---------------------------------------------------------------------------+++class TestCodexRateLimitState:+ def test_initial_state_is_none(self):+ state = CodexRateLimitState()+ assert state.latest is None+ assert state.get_stats() is None++ def test_update_from_headers_stores_snapshot(self):+ state = CodexRateLimitState()+ headers = {+ "x-codex-primary-used-percent": "55.0",+ "x-codex-primary-window-minutes": "60",+ }+ state.update_from_headers(headers)+ snap = state.latest+ assert snap is not None+ assert snap.primary is not None+ assert snap.primary.used_percent == 55.0++ def test_update_from_empty_headers_is_noop(self):+ state = CodexRateLimitState()+ state.update_from_headers({})+ assert state.latest is None++ def test_update_from_non_codex_headers_is_noop(self):+ state = CodexRateLimitState()+ state.update_from_headers({"content-type": "application/json"})+ assert state.latest is None++ def test_get_stats_returns_dict_when_data_present(self):+ state = CodexRateLimitState()+ state.update_from_headers({"x-codex-primary-used-percent": "10.0"})+ stats = state.get_stats()+ assert stats is not None+ assert isinstance(stats, dict)+ assert stats["limit_id"] == "codex"++ def test_update_overwrites_previous_snapshot(self):+ state = CodexRateLimitState()+ state.update_from_headers({"x-codex-primary-used-percent": "10.0"})+ state.update_from_headers({"x-codex-primary-used-percent": "90.0"})+ snap = state.latest+ assert snap is not None+ assert snap.primary is not None+ assert snap.primary.used_percent == 90.0diff --git a/tests/test_compress_api.py b/tests/test_compress_api.pyindex 0ce844243..7f9956b53 100644--- a/tests/test_compress_api.py+++ b/tests/test_compress_api.py@@ -1,274 +1,274 @@-"""Tests for the one-function compress() API and integrations."""--import json--import pytest--from headroom.compress import CompressResult, compress-from headroom.hooks import CompressionHooks--try:- from starlette.applications import Starlette- from starlette.requests import Request- from starlette.responses import JSONResponse- from starlette.routing import Route- from starlette.testclient import TestClient-- from headroom.integrations.asgi import CompressionMiddleware-- HAS_STARLETTE = True-except ImportError:- HAS_STARLETTE = False---# =============================================================================-# Tests: compress() function-# =============================================================================---class TestCompressFunction:- def test_empty_messages(self):- result = compress([], model="test")- assert result.messages == []- assert result.tokens_saved == 0-- def test_small_messages_passthrough(self):- """Small messages below compression threshold pass through unchanged."""- messages = [{"role": "user", "content": "hello"}]- result = compress(messages, model="gpt-4o")- assert result.messages[0]["content"] == "hello"- assert result.tokens_saved == 0-- def test_returns_compress_result(self):- result = compress([{"role": "user", "content": "hi"}])- assert isinstance(result, CompressResult)- assert hasattr(result, "messages")- assert hasattr(result, "tokens_saved")- assert hasattr(result, "compression_ratio")- assert hasattr(result, "transforms_applied")-- def test_large_tool_output_compressed(self):- """Large JSON tool output should be compressed."""- big_data = json.dumps(- [- {"id": i, "status": "active", "name": f"item_{i}", "value": i * 17}- for i in range(200)- ]- )- messages = [- {"role": "user", "content": "What are the top items?"},- {"role": "tool", "content": big_data, "tool_call_id": "call_1"},- ]- result = compress(messages, model="gpt-4o")- assert result.tokens_after <= result.tokens_before- assert len(result.messages) == 2-- def test_compact_json_counts_tokens_not_whitespace(self):- """Compact JSON arrays should still compress under token thresholds."""- numbers = [42.0 + i * 0.1 for i in range(200)]- messages = [- {"role": "system", "content": "You are helpful."},- {"role": "user", "content": "Show metrics"},- {- "role": "assistant",- "content": None,- "tool_calls": [- {- "id": "call_1",- "type": "function",- "function": {"name": "get_metrics", "arguments": "{}"},- }- ],- },- {"role": "tool", "tool_call_id": "call_1", "content": json.dumps(numbers)},- ]-- result = compress(messages, min_tokens_to_compress=250)-- assert result.tokens_saved > 0- assert any(- transform.startswith("router:smart_crusher") for transform in result.transforms_applied- )-- def test_optimize_false_passthrough(self):- """optimize=False returns messages unchanged."""- messages = [{"role": "user", "content": "hello world " * 100}]- result = compress(messages, optimize=False)- assert result.messages is messages- assert result.tokens_saved == 0-- def test_with_custom_hooks(self):- """Hooks are called when provided."""- calls = []-- class TrackingHooks(CompressionHooks):- def pre_compress(self, messages, ctx):- calls.append(("pre", len(messages)))- return messages-- def compute_biases(self, messages, ctx):- calls.append(("biases", len(messages)))- return {}-- def post_compress(self, event):- calls.append(("post", event.tokens_saved))-- big_data = json.dumps([{"id": i, "status": "active"} for i in range(100)])- messages = [- {"role": "user", "content": "analyze"},- {"role": "tool", "content": big_data, "tool_call_id": "c1"},- ]- compress(messages, hooks=TrackingHooks())-- assert any(c[0] == "pre" for c in calls)- assert any(c[0] == "biases" for c in calls)---class TestCompressResultFields:- def test_fields_populated(self):- big_data = json.dumps([{"id": i, "type": "log"} for i in range(100)])- messages = [- {"role": "user", "content": "summarize"},- {"role": "tool", "content": big_data, "tool_call_id": "c1"},- ]- result = compress(messages, model="claude-sonnet-4-5-20250929")- assert result.tokens_before > 0- assert result.tokens_after >= 0- assert result.tokens_saved >= 0- assert 0.0 <= result.compression_ratio <= 1.0---# =============================================================================-# Tests: ASGI CompressionMiddleware (requires starlette)-# =============================================================================---def _make_asgi_app(middleware_kwargs=None):- """Create a test ASGI app with CompressionMiddleware."""-- async def chat_endpoint(request: Request) -> JSONResponse:- body = await request.json()- return JSONResponse(- {- "model": "gpt-4o",- "choices": [{"message": {"content": "response"}}],- "usage": {"prompt_tokens": 10, "completion_tokens": 5},- "_message_count": len(body.get("messages", [])),- }- )-- async def health(request: Request) -> JSONResponse:- return JSONResponse({"status": "ok"})-- app = Starlette(- routes=[- Route("/health", health),- Route("/v1/chat/completions", chat_endpoint, methods=["POST"]),- Route("/v1/messages", chat_endpoint, methods=["POST"]),- ]- )- app.add_middleware(CompressionMiddleware, **(middleware_kwargs or {}))- return app--[email protected](not HAS_STARLETTE, reason="starlette not installed")-class TestASGIMiddleware:- def test_non_llm_paths_passthrough(self):- app = _make_asgi_app()- client = TestClient(app)- resp = client.get("/health")- assert resp.status_code == 200- assert resp.json()["status"] == "ok"-- def test_small_messages_passthrough(self):- app = _make_asgi_app()- client = TestClient(app)- resp = client.post(- "/v1/chat/completions",- json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},- )- assert resp.status_code == 200-- def test_large_messages_compressed(self):- """Large tool output should be compressed by middleware."""- app = _make_asgi_app()- client = TestClient(app)-- big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])- resp = client.post(- "/v1/chat/completions",- json={- "model": "gpt-4o",- "messages": [- {"role": "user", "content": "analyze"},- {"role": "tool", "content": big_data, "tool_call_id": "c1"},- ],- },- )- assert resp.status_code == 200-- def test_anthropic_path(self):- """Works with Anthropic /v1/messages path."""- app = _make_asgi_app()- client = TestClient(app)- resp = client.post(- "/v1/messages",- json={- "model": "claude-sonnet-4-5-20250929",- "messages": [{"role": "user", "content": "hello"}],- },- )- assert resp.status_code == 200-- def test_get_requests_passthrough(self):- """GET requests to LLM paths pass through."""- app = _make_asgi_app()- client = TestClient(app)- resp = client.get("/v1/chat/completions")- assert resp.status_code in (200, 405)---# =============================================================================-# Tests: LiteLLM Callback-# =============================================================================---class TestLiteLLMCallback:- def test_callback_imports(self):- """Verify the callback can be imported."""- from headroom.integrations.litellm_callback import HeadroomCallback-- callback = HeadroomCallback()- assert callback.total_tokens_saved == 0-- def test_callback_compresses_messages(self):- """Callback compresses messages in pre_call_hook."""- import asyncio-- from headroom.integrations.litellm_callback import HeadroomCallback-- callback = HeadroomCallback()-- big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])- data = {- "model": "gpt-4o",- "messages": [- {"role": "user", "content": "analyze"},- {"role": "tool", "content": big_data, "tool_call_id": "c1"},- ],- }-- result = asyncio.run(callback.async_pre_call_hook("key", data, "completion"))- assert result is data-- def test_callback_ignores_non_completion(self):- """Non-completion calls are passed through."""- import asyncio-- from headroom.integrations.litellm_callback import HeadroomCallback-- callback = HeadroomCallback()- data = {"messages": [{"role": "user", "content": "hi"}]}-- result = asyncio.run(callback.async_pre_call_hook("key", data, "embedding"))- assert result is data+"""Tests for the one-function compress() API and integrations."""++import json++import pytest++from headroom.compress import CompressResult, compress+from headroom.hooks import CompressionHooks++try:+ from starlette.applications import Starlette+ from starlette.requests import Request+ from starlette.responses import JSONResponse+ from starlette.routing import Route+ from starlette.testclient import TestClient++ from headroom.integrations.asgi import CompressionMiddleware++ HAS_STARLETTE = True+except ImportError:+ HAS_STARLETTE = False+++# =============================================================================+# Tests: compress() function+# =============================================================================+++class TestCompressFunction:+ def test_empty_messages(self):+ result = compress([], model="test")+ assert result.messages == []+ assert result.tokens_saved == 0++ def test_small_messages_passthrough(self):+ """Small messages below compression threshold pass through unchanged."""+ messages = [{"role": "user", "content": "hello"}]+ result = compress(messages, model="gpt-4o")+ assert result.messages[0]["content"] == "hello"+ assert result.tokens_saved == 0++ def test_returns_compress_result(self):+ result = compress([{"role": "user", "content": "hi"}])+ assert isinstance(result, CompressResult)+ assert hasattr(result, "messages")+ assert hasattr(result, "tokens_saved")+ assert hasattr(result, "compression_ratio")+ assert hasattr(result, "transforms_applied")++ def test_large_tool_output_compressed(self):+ """Large JSON tool output should be compressed."""+ big_data = json.dumps(+ [+ {"id": i, "status": "active", "name": f"item_{i}", "value": i * 17}+ for i in range(200)+ ]+ )+ messages = [+ {"role": "user", "content": "What are the top items?"},+ {"role": "tool", "content": big_data, "tool_call_id": "call_1"},+ ]+ result = compress(messages, model="gpt-4o")+ assert result.tokens_after <= result.tokens_before+ assert len(result.messages) == 2++ def test_compact_json_counts_tokens_not_whitespace(self):+ """Compact JSON arrays should still compress under token thresholds."""+ numbers = [42.0 + i * 0.1 for i in range(200)]+ messages = [+ {"role": "system", "content": "You are helpful."},+ {"role": "user", "content": "Show metrics"},+ {+ "role": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {"name": "get_metrics", "arguments": "{}"},+ }+ ],+ },+ {"role": "tool", "tool_call_id": "call_1", "content": json.dumps(numbers)},+ ]++ result = compress(messages, min_tokens_to_compress=250)++ assert result.tokens_saved > 0+ assert any(+ transform.startswith("router:smart_crusher") for transform in result.transforms_applied+ )++ def test_optimize_false_passthrough(self):+ """optimize=False returns messages unchanged."""+ messages = [{"role": "user", "content": "hello world " * 100}]+ result = compress(messages, optimize=False)+ assert result.messages is messages+ assert result.tokens_saved == 0++ def test_with_custom_hooks(self):+ """Hooks are called when provided."""+ calls = []++ class TrackingHooks(CompressionHooks):+ def pre_compress(self, messages, ctx):+ calls.append(("pre", len(messages)))+ return messages++ def compute_biases(self, messages, ctx):+ calls.append(("biases", len(messages)))+ return {}++ def post_compress(self, event):+ calls.append(("post", event.tokens_saved))++ big_data = json.dumps([{"id": i, "status": "active"} for i in range(100)])+ messages = [+ {"role": "user", "content": "analyze"},+ {"role": "tool", "content": big_data, "tool_call_id": "c1"},+ ]+ compress(messages, hooks=TrackingHooks())++ assert any(c[0] == "pre" for c in calls)+ assert any(c[0] == "biases" for c in calls)+++class TestCompressResultFields:+ def test_fields_populated(self):+ big_data = json.dumps([{"id": i, "type": "log"} for i in range(100)])+ messages = [+ {"role": "user", "content": "summarize"},+ {"role": "tool", "content": big_data, "tool_call_id": "c1"},+ ]+ result = compress(messages, model="claude-sonnet-4-5-20250929")+ assert result.tokens_before > 0+ assert result.tokens_after >= 0+ assert result.tokens_saved >= 0+ assert 0.0 <= result.compression_ratio <= 1.0+++# =============================================================================+# Tests: ASGI CompressionMiddleware (requires starlette)+# =============================================================================+++def _make_asgi_app(middleware_kwargs=None):+ """Create a test ASGI app with CompressionMiddleware."""++ async def chat_endpoint(request: Request) -> JSONResponse:+ body = await request.json()+ return JSONResponse(+ {+ "model": "gpt-4o",+ "choices": [{"message": {"content": "response"}}],+ "usage": {"prompt_tokens": 10, "completion_tokens": 5},+ "_message_count": len(body.get("messages", [])),+ }+ )++ async def health(request: Request) -> JSONResponse:+ return JSONResponse({"status": "ok"})++ app = Starlette(+ routes=[+ Route("/health", health),+ Route("/v1/chat/completions", chat_endpoint, methods=["POST"]),+ Route("/v1/messages", chat_endpoint, methods=["POST"]),+ ]+ )+ app.add_middleware(CompressionMiddleware, **(middleware_kwargs or {}))+ return app++[email protected](not HAS_STARLETTE, reason="starlette not installed")+class TestASGIMiddleware:+ def test_non_llm_paths_passthrough(self):+ app = _make_asgi_app()+ client = TestClient(app)+ resp = client.get("/health")+ assert resp.status_code == 200+ assert resp.json()["status"] == "ok"++ def test_small_messages_passthrough(self):+ app = _make_asgi_app()+ client = TestClient(app)+ resp = client.post(+ "/v1/chat/completions",+ json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},+ )+ assert resp.status_code == 200++ def test_large_messages_compressed(self):+ """Large tool output should be compressed by middleware."""+ app = _make_asgi_app()+ client = TestClient(app)++ big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])+ resp = client.post(+ "/v1/chat/completions",+ json={+ "model": "gpt-4o",+ "messages": [+ {"role": "user", "content": "analyze"},+ {"role": "tool", "content": big_data, "tool_call_id": "c1"},+ ],+ },+ )+ assert resp.status_code == 200++ def test_anthropic_path(self):+ """Works with Anthropic /v1/messages path."""+ app = _make_asgi_app()+ client = TestClient(app)+ resp = client.post(+ "/v1/messages",+ json={+ "model": "claude-sonnet-4-5-20250929",+ "messages": [{"role": "user", "content": "hello"}],+ },+ )+ assert resp.status_code == 200++ def test_get_requests_passthrough(self):+ """GET requests to LLM paths pass through."""+ app = _make_asgi_app()+ client = TestClient(app)+ resp = client.get("/v1/chat/completions")+ assert resp.status_code in (200, 405)+++# =============================================================================+# Tests: LiteLLM Callback+# =============================================================================+++class TestLiteLLMCallback:+ def test_callback_imports(self):+ """Verify the callback can be imported."""+ from headroom.integrations.litellm_callback import HeadroomCallback++ callback = HeadroomCallback()+ assert callback.total_tokens_saved == 0++ def test_callback_compresses_messages(self):+ """Callback compresses messages in pre_call_hook."""+ import asyncio++ from headroom.integrations.litellm_callback import HeadroomCallback++ callback = HeadroomCallback()++ big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])+ data = {+ "model": "gpt-4o",+ "messages": [+ {"role": "user", "content": "analyze"},+ {"role": "tool", "content": big_data, "tool_call_id": "c1"},+ ],+ }++ result = asyncio.run(callback.async_pre_call_hook("key", data, "completion"))+ assert result is data++ def test_callback_ignores_non_completion(self):+ """Non-completion calls are passed through."""+ import asyncio++ from headroom.integrations.litellm_callback import HeadroomCallback++ callback = HeadroomCallback()+ data = {"messages": [{"role": "user", "content": "hi"}]}++ result = asyncio.run(callback.async_pre_call_hook("key", data, "embedding"))+ assert result is datadiff --git a/tests/test_compress_failure.py b/tests/test_compress_failure.pyindex 985bfddbd..be510c987 100644--- a/tests/test_compress_failure.py+++ b/tests/test_compress_failure.py@@ -1,39 +1,39 @@-from __future__ import annotations--import importlib-from types import SimpleNamespace--from headroom.compress import compress---class _FailingPipeline:- def apply(self, **kwargs): # noqa: ANN003, ANN201- raise RuntimeError("boom")---def test_compress_returns_original_messages_when_pipeline_fails(monkeypatch) -> None:- metrics: list[dict[str, str]] = []- compress_module = importlib.import_module("headroom.compress")- monkeypatch.setattr(compress_module, "_get_pipeline", lambda: _FailingPipeline())- monkeypatch.setattr(- compress_module,- "get_otel_metrics",- lambda: SimpleNamespace(- record_compression_failure=lambda **kwargs: metrics.append(kwargs),- ),- )-- messages = [{"role": "user", "content": "hello world " * 100}]- result = compress(messages, model="gpt-4o")-- assert result.messages == messages- assert result.tokens_before == 0- assert result.tokens_after == 0- assert result.tokens_saved == 0- assert metrics == [- {- "model": "gpt-4o",- "operation": "compress",- "error_type": "RuntimeError",- }- ]+from __future__ import annotations++import importlib+from types import SimpleNamespace++from headroom.compress import compress+++class _FailingPipeline:+ def apply(self, **kwargs): # noqa: ANN003, ANN201+ raise RuntimeError("boom")+++def test_compress_returns_original_messages_when_pipeline_fails(monkeypatch) -> None:+ metrics: list[dict[str, str]] = []+ compress_module = importlib.import_module("headroom.compress")+ monkeypatch.setattr(compress_module, "_get_pipeline", lambda: _FailingPipeline())+ monkeypatch.setattr(+ compress_module,+ "get_otel_metrics",+ lambda: SimpleNamespace(+ record_compression_failure=lambda **kwargs: metrics.append(kwargs),+ ),+ )++ messages = [{"role": "user", "content": "hello world " * 100}]+ result = compress(messages, model="gpt-4o")++ assert result.messages == messages+ assert result.tokens_before == 0+ assert result.tokens_after == 0+ assert result.tokens_saved == 0+ assert metrics == [+ {+ "model": "gpt-4o",+ "operation": "compress",+ "error_type": "RuntimeError",+ }+ ]diff --git a/tests/test_copilot_quota.py b/tests/test_copilot_quota.pyindex 7ec51ab8a..09c97420b 100644--- a/tests/test_copilot_quota.py+++ b/tests/test_copilot_quota.py@@ -1,331 +1,331 @@-"""Unit tests for headroom.subscription.copilot_quota."""--from __future__ import annotations--import time--import pytest--from headroom.subscription.copilot_quota import (- CopilotQuotaCategory,- CopilotQuotaSnapshot,- discover_github_token,- parse_copilot_quota,-)--# ----------------------------------------------------------------------------# CopilotQuotaCategory helpers-# ------------------------------------------------------------------------------class TestCopilotQuotaCategory:- def test_used_computed_from_entitlement_and_remaining(self):- cat = CopilotQuotaCategory(name="chat", entitlement=300, remaining=120)- assert cat.used == 180-- def test_used_percent_computed(self):- cat = CopilotQuotaCategory(name="chat", entitlement=100, remaining=25)- assert cat.used_percent == pytest.approx(75.0)-- def test_used_percent_from_percent_remaining(self):- cat = CopilotQuotaCategory(name="completions", percent_remaining=40.0)- assert cat.used_percent == pytest.approx(60.0)-- def test_unlimited_used_percent_is_zero(self):- cat = CopilotQuotaCategory(name="premium_interactions", unlimited=True)- assert cat.used_percent == 0.0-- def test_used_none_when_entitlement_missing(self):- cat = CopilotQuotaCategory(name="chat", remaining=50)- assert cat.used is None-- def test_to_dict_keys(self):- cat = CopilotQuotaCategory(- name="chat",- entitlement=100,- remaining=60,- percent_remaining=60.0,- overage_count=2,- overage_permitted=True,- unlimited=False,- timestamp_utc="2025-01-01T00:00:00Z",- )- d = cat.to_dict()- assert d["name"] == "chat"- assert d["entitlement"] == 100- assert d["remaining"] == 60- assert d["used"] == 40- assert d["used_percent"] == pytest.approx(40.0)- assert d["overage_count"] == 2- assert d["overage_permitted"] is True- assert d["unlimited"] is False-- def test_used_percent_clipped_at_zero(self):- # percent_remaining > 100 should not produce negative used_percent- cat = CopilotQuotaCategory(name="chat", percent_remaining=110.0)- assert cat.used_percent == pytest.approx(0.0)---# ----------------------------------------------------------------------------# parse_copilot_quota-# ------------------------------------------------------------------------------_SAMPLE_RESPONSE = {- "login": "octocat",- "copilot_plan": "individual",- "access_type_sku": "copilot_for_individuals",- "quota_reset_date_utc": "2025-02-01",- "quota_snapshots": {- "chat": {- "entitlement": 50,- "remaining": 30,- "quota_remaining": 30,- "percent_remaining": 60.0,- "overage_count": 0,- "overage_permitted": False,- "unlimited": False,- "timestamp_utc": "2025-01-15T10:00:00Z",- },- "completions": {- "entitlement": 2000,- "remaining": 1500,- "percent_remaining": 75.0,- "overage_count": 0,- "overage_permitted": True,- "unlimited": False,- "timestamp_utc": "2025-01-15T10:00:00Z",- },- "premium_interactions": {- "entitlement": 300,- "remaining": 298,- "percent_remaining": 99.3,- "overage_count": 2,- "overage_permitted": True,- "unlimited": False,- "timestamp_utc": "2025-01-15T10:00:00Z",- },- },-}---class TestParseCopilotQuota:- def test_basic_fields(self):- snap = parse_copilot_quota(_SAMPLE_RESPONSE)- assert snap.login == "octocat"- assert snap.copilot_plan == "individual"- assert snap.access_type_sku == "copilot_for_individuals"- assert snap.quota_reset_date_utc == "2025-02-01"-- def test_all_categories_parsed(self):- snap = parse_copilot_quota(_SAMPLE_RESPONSE)- assert set(snap.categories.keys()) == {"chat", "completions", "premium_interactions"}-- def test_chat_category(self):- snap = parse_copilot_quota(_SAMPLE_RESPONSE)- chat = snap.categories["chat"]- assert chat.entitlement == 50- assert chat.remaining == 30- assert chat.percent_remaining == pytest.approx(60.0)- assert chat.unlimited is False- assert chat.overage_count == 0-- def test_premium_interactions_overage(self):- snap = parse_copilot_quota(_SAMPLE_RESPONSE)- prem = snap.categories["premium_interactions"]- assert prem.overage_count == 2- assert prem.overage_permitted is True-- def test_quota_remaining_alias(self):- """quota_remaining should be used when remaining is absent."""- data = {- "quota_snapshots": {- "chat": {- "entitlement": 100,- "quota_remaining": 75,- }- }- }- snap = parse_copilot_quota(data)- assert snap.categories["chat"].remaining == 75-- def test_unlimited_category(self):- data = {"quota_snapshots": {"completions": {"unlimited": True}}}- snap = parse_copilot_quota(data)- assert snap.categories["completions"].unlimited is True-- def test_empty_quota_snapshots(self):- snap = parse_copilot_quota({"login": "ghost"})- assert snap.login == "ghost"- assert snap.categories == {}-- def test_quota_reset_date_fallback(self):- data = {"quota_reset_date": "2025-03-01"}- snap = parse_copilot_quota(data)- assert snap.quota_reset_date_utc == "2025-03-01"-- def test_fetched_at_is_recent(self):- before = time.time()- snap = parse_copilot_quota({})- after = time.time()- assert before <= snap.fetched_at <= after-- def test_to_dict_structure(self):- snap = parse_copilot_quota(_SAMPLE_RESPONSE)- d = snap.to_dict()- assert "login" in d- assert "categories" in d- assert "chat" in d["categories"]- assert "used_percent" in d["categories"]["chat"]-- def test_missing_categories_skipped(self):- data = {- "quota_snapshots": {- "chat": {"remaining": 10},- # completions and premium_interactions absent- }- }- snap = parse_copilot_quota(data)- assert "chat" in snap.categories- assert "completions" not in snap.categories- assert "premium_interactions" not in snap.categories-- def test_free_plan(self):- data = {"copilot_plan": "free", "quota_snapshots": {}}- snap = parse_copilot_quota(data)- assert snap.copilot_plan == "free"---# ----------------------------------------------------------------------------# discover_github_token-# ------------------------------------------------------------------------------class TestDiscoverGithubToken:- def test_returns_none_when_no_env_vars(self, monkeypatch):- for var in [- "GITHUB_COPILOT_GITHUB_TOKEN",- "GITHUB_TOKEN",- "COPILOT_GITHUB_TOKEN",- "GITHUB_COPILOT_API_TOKEN",- ]:- monkeypatch.delenv(var, raising=False)- assert discover_github_token() is None-- def test_picks_up_github_token(self, monkeypatch):- for var in [- "GITHUB_COPILOT_GITHUB_TOKEN",- "GITHUB_TOKEN",- "COPILOT_GITHUB_TOKEN",- "GITHUB_COPILOT_API_TOKEN",- ]:- monkeypatch.delenv(var, raising=False)- monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken123")- assert discover_github_token() == "ghp_testtoken123"-- def test_prefers_copilot_specific_token(self, monkeypatch):- for var in [- "GITHUB_COPILOT_GITHUB_TOKEN",- "GITHUB_TOKEN",- "COPILOT_GITHUB_TOKEN",- "GITHUB_COPILOT_API_TOKEN",- ]:- monkeypatch.delenv(var, raising=False)- monkeypatch.setenv("GITHUB_COPILOT_GITHUB_TOKEN", "ghp_copilot_specific")- monkeypatch.setenv("GITHUB_TOKEN", "ghp_generic")- assert discover_github_token() == "ghp_copilot_specific"-- def test_falls_through_to_next_env_var(self, monkeypatch):- for var in [- "GITHUB_COPILOT_GITHUB_TOKEN",- "GITHUB_TOKEN",- "COPILOT_GITHUB_TOKEN",- "GITHUB_COPILOT_API_TOKEN",- ]:- monkeypatch.delenv(var, raising=False)- monkeypatch.setenv("COPILOT_GITHUB_TOKEN", "ghp_copilot")- assert discover_github_token() == "ghp_copilot"-- def test_ignores_empty_strings(self, monkeypatch):- for var in [- "GITHUB_COPILOT_GITHUB_TOKEN",- "GITHUB_TOKEN",- "COPILOT_GITHUB_TOKEN",- "GITHUB_COPILOT_API_TOKEN",- ]:- monkeypatch.delenv(var, raising=False)- monkeypatch.setenv("GITHUB_COPILOT_GITHUB_TOKEN", "")- monkeypatch.setenv("GITHUB_TOKEN", "ghp_valid")- assert discover_github_token() == "ghp_valid"---# ----------------------------------------------------------------------------# CopilotQuotaSnapshot.to_dict-# ------------------------------------------------------------------------------class TestCopilotQuotaSnapshot:- def test_to_dict_complete(self):- snap = CopilotQuotaSnapshot(- login="user1",- copilot_plan="business",- access_type_sku="copilot_enterprise",- quota_reset_date_utc="2025-02-01",- )- snap.categories["chat"] = CopilotQuotaCategory(name="chat", entitlement=50, remaining=25)- d = snap.to_dict()- assert d["login"] == "user1"- assert d["copilot_plan"] == "business"- assert "chat" in d["categories"]- assert d["categories"]["chat"]["entitlement"] == 50---# ----------------------------------------------------------------------------# Poll-loop task-leak regression-# ------------------------------------------------------------------------------class TestCopilotQuotaPollLoopLeak:- @pytest.mark.asyncio- async def test_poll_loop_does_not_leak_event_wait_tasks(self, monkeypatch):- """Regression for the ``asyncio.shield(event.wait())`` pattern.-- Matches the equivalent guard in ``tests/test_subscription_tracker.py``:- every poll interval the loop previously leaked one Event.wait- waiter because ``asyncio.shield`` prevented ``wait_for`` from- cancelling the inner wait on timeout.- """- import asyncio-- from headroom.subscription.copilot_quota import _CopilotQuotaTracker-- # No token configured → _maybe_poll returns immediately each cycle.- for var in ("GITHUB_COPILOT_GITHUB_TOKEN", "GITHUB_TOKEN"):- monkeypatch.delenv(var, raising=False)-- tracker = _CopilotQuotaTracker(poll_interval_s=0.05)-- def _count_event_wait() -> int:- return sum(- 1- for t in asyncio.all_tasks()- if (t.get_coro().__qualname__ if t.get_coro() else "") == "Event.wait"- )-- baseline = _count_event_wait()- await tracker.start()- try:- await asyncio.sleep(0.3) # ~6 poll cycles- peak = _count_event_wait()- finally:- await tracker.stop()-- await asyncio.sleep(0.05)- residual = _count_event_wait()-- assert peak - baseline <= 1, (- f"CopilotQuotaTracker leaked Event.wait: baseline={baseline} peak={peak}"- )- assert residual <= baseline, (- f"CopilotQuotaTracker left residual Event.wait: baseline={baseline} residual={residual}"- )+"""Unit tests for headroom.subscription.copilot_quota."""++from __future__ import annotations++import time++import pytest++from headroom.subscription.copilot_quota import (+ CopilotQuotaCategory,+ CopilotQuotaSnapshot,+ discover_github_token,+ parse_copilot_quota,+)++# ---------------------------------------------------------------------------+# CopilotQuotaCategory helpers+# ---------------------------------------------------------------------------+++class TestCopilotQuotaCategory:+ def test_used_computed_from_entitlement_and_remaining(self):+ cat = CopilotQuotaCategory(name="chat", entitlement=300, remaining=120)+ assert cat.used == 180++ def test_used_percent_computed(self):+ cat = CopilotQuotaCategory(name="chat", entitlement=100, remaining=25)+ assert cat.used_percent == pytest.approx(75.0)++ def test_used_percent_from_percent_remaining(self):+ cat = CopilotQuotaCategory(name="completions", percent_remaining=40.0)+ assert cat.used_percent == pytest.approx(60.0)++ def test_unlimited_used_percent_is_zero(self):+ cat = CopilotQuotaCategory(name="premium_interactions", unlimited=True)+ assert cat.used_percent == 0.0++ def test_used_none_when_entitlement_missing(self):+ cat = CopilotQuotaCategory(name="chat", remaining=50)+ assert cat.used is None++ def test_to_dict_keys(self):+ cat = CopilotQuotaCategory(+ name="chat",+ entitlement=100,+ remaining=60,+ percent_remaining=60.0,+ overage_count=2,+ overage_permitted=True,+ unlimited=False,+ timestamp_utc="2025-01-01T00:00:00Z",+ )+ d = cat.to_dict()+ assert d["name"] == "chat"+ assert d["entitlement"] == 100+ assert d["remaining"] == 60+ assert d["used"] == 40+ assert d["used_percent"] == pytest.approx(40.0)+ assert d["overage_count"] == 2+ assert d["overage_permitted"] is True+ assert d["unlimited"] is False++ def test_used_percent_clipped_at_zero(self):+ # percent_remaining > 100 should not produce negative used_percent+ cat = CopilotQuotaCategory(name="chat", percent_remaining=110.0)+ assert cat.used_percent == pytest.approx(0.0)+++# ---------------------------------------------------------------------------+# parse_copilot_quota+# ---------------------------------------------------------------------------+++_SAMPLE_RESPONSE = {+ "login": "octocat",+ "copilot_plan": "individual",+ "access_type_sku": "copilot_for_individuals",+ "quota_reset_date_utc": "2025-02-01",+ "quota_snapshots": {+ "chat": {+ "entitlement": 50,+ "remaining": 30,+ "quota_remaining": 30,+ "percent_remaining": 60.0,+ "overage_count": 0,+ "overage_permitted": False,+ "unlimited": False,+ "timestamp_utc": "2025-01-15T10:00:00Z",+ },+ "completions": {+ "entitlement": 2000,+ "remaining": 1500,+ "percent_remaining": 75.0,+ "overage_count": 0,+ "overage_permitted": True,+ "unlimited": False,+ "timestamp_utc": "2025-01-15T10:00:00Z",+ },+ "premium_interactions": {+ "entitlement": 300,+ "remaining": 298,+ "percent_remaining": 99.3,+ "overage_count": 2,+ "overage_permitted": True,+ "unlimited": False,+ "timestamp_utc": "2025-01-15T10:00:00Z",+ },+ },+}+++class TestParseCopilotQuota:+ def test_basic_fields(self):+ snap = parse_copilot_quota(_SAMPLE_RESPONSE)+ assert snap.login == "octocat"+ assert snap.copilot_plan == "individual"+ assert snap.access_type_sku == "copilot_for_individuals"+ assert snap.quota_reset_date_utc == "2025-02-01"++ def test_all_categories_parsed(self):+ snap = parse_copilot_quota(_SAMPLE_RESPONSE)+ assert set(snap.categories.keys()) == {"chat", "completions", "premium_interactions"}++ def test_chat_category(self):+ snap = parse_copilot_quota(_SAMPLE_RESPONSE)+ chat = snap.categories["chat"]+ assert chat.entitlement == 50+ assert chat.remaining == 30+ assert chat.percent_remaining == pytest.approx(60.0)+ assert chat.unlimited is False+ assert chat.overage_count == 0++ def test_premium_interactions_overage(self):+ snap = parse_copilot_quota(_SAMPLE_RESPONSE)+ prem = snap.categories["premium_interactions"]+ assert prem.overage_count == 2+ assert prem.overage_permitted is True++ def test_quota_remaining_alias(self):+ """quota_remaining should be used when remaining is absent."""+ data = {+ "quota_snapshots": {+ "chat": {+ "entitlement": 100,+ "quota_remaining": 75,+ }+ }+ }+ snap = parse_copilot_quota(data)+ assert snap.categories["chat"].remaining == 75++ def test_unlimited_category(self):+ data = {"quota_snapshots": {"completions": {"unlimited": True}}}+ snap = parse_copilot_quota(data)+ assert snap.categories["completions"].unlimited is True++ def test_empty_quota_snapshots(self):+ snap = parse_copilot_quota({"login": "ghost"})+ assert snap.login == "ghost"+ assert snap.categories == {}++ def test_quota_reset_date_fallback(self):+ data = {"quota_reset_date": "2025-03-01"}+ snap = parse_copilot_quota(data)+ assert snap.quota_reset_date_utc == "2025-03-01"++ def test_fetched_at_is_recent(self):+ before = time.time()+ snap = parse_copilot_quota({})+ after = time.time()+ assert before <= snap.fetched_at <= after++ def test_to_dict_structure(self):+ snap = parse_copilot_quota(_SAMPLE_RESPONSE)+ d = snap.to_dict()+ assert "login" in d+ assert "categories" in d+ assert "chat" in d["categories"]+ assert "used_percent" in d["categories"]["chat"]++ def test_missing_categories_skipped(self):+ data = {+ "quota_snapshots": {+ "chat": {"remaining": 10},+ # completions and premium_interactions absent+ }+ }+ snap = parse_copilot_quota(data)+ assert "chat" in snap.categories+ assert "completions" not in snap.categories+ assert "premium_interactions" not in snap.categories++ def test_free_plan(self):+ data = {"copilot_plan": "free", "quota_snapshots": {}}+ snap = parse_copilot_quota(data)+ assert snap.copilot_plan == "free"+++# ---------------------------------------------------------------------------+# discover_github_token+# ---------------------------------------------------------------------------+++class TestDiscoverGithubToken:+ def test_returns_none_when_no_env_vars(self, monkeypatch):+ for var in [+ "GITHUB_COPILOT_GITHUB_TOKEN",+ "GITHUB_TOKEN",+ "COPILOT_GITHUB_TOKEN",+ "GITHUB_COPILOT_API_TOKEN",+ ]:+ monkeypatch.delenv(var, raising=False)+ assert discover_github_token() is None++ def test_picks_up_github_token(self, monkeypatch):+ for var in [+ "GITHUB_COPILOT_GITHUB_TOKEN",+ "GITHUB_TOKEN",+ "COPILOT_GITHUB_TOKEN",+ "GITHUB_COPILOT_API_TOKEN",+ ]:+ monkeypatch.delenv(var, raising=False)+ monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken123")+ assert discover_github_token() == "ghp_testtoken123"++ def test_prefers_copilot_specific_token(self, monkeypatch):+ for var in [+ "GITHUB_COPILOT_GITHUB_TOKEN",+ "GITHUB_TOKEN",+ "COPILOT_GITHUB_TOKEN",+ "GITHUB_COPILOT_API_TOKEN",+ ]:+ monkeypatch.delenv(var, raising=False)+ monkeypatch.setenv("GITHUB_COPILOT_GITHUB_TOKEN", "ghp_copilot_specific")+ monkeypatch.setenv("GITHUB_TOKEN", "ghp_generic")+ assert discover_github_token() == "ghp_copilot_specific"++ def test_falls_through_to_next_env_var(self, monkeypatch):+ for var in [+ "GITHUB_COPILOT_GITHUB_TOKEN",+ "GITHUB_TOKEN",+ "COPILOT_GITHUB_TOKEN",+ "GITHUB_COPILOT_API_TOKEN",+ ]:+ monkeypatch.delenv(var, raising=False)+ monkeypatch.setenv("COPILOT_GITHUB_TOKEN", "ghp_copilot")+ assert discover_github_token() == "ghp_copilot"++ def test_ignores_empty_strings(self, monkeypatch):+ for var in [+ "GITHUB_COPILOT_GITHUB_TOKEN",+ "GITHUB_TOKEN",+ "COPILOT_GITHUB_TOKEN",+ "GITHUB_COPILOT_API_TOKEN",+ ]:+ monkeypatch.delenv(var, raising=False)+ monkeypatch.setenv("GITHUB_COPILOT_GITHUB_TOKEN", "")+ monkeypatch.setenv("GITHUB_TOKEN", "ghp_valid")+ assert discover_github_token() == "ghp_valid"+++# ---------------------------------------------------------------------------+# CopilotQuotaSnapshot.to_dict+# ---------------------------------------------------------------------------+++class TestCopilotQuotaSnapshot:+ def test_to_dict_complete(self):+ snap = CopilotQuotaSnapshot(+ login="user1",+ copilot_plan="business",+ access_type_sku="copilot_enterprise",+ quota_reset_date_utc="2025-02-01",+ )+ snap.categories["chat"] = CopilotQuotaCategory(name="chat", entitlement=50, remaining=25)+ d = snap.to_dict()+ assert d["login"] == "user1"+ assert d["copilot_plan"] == "business"+ assert "chat" in d["categories"]+ assert d["categories"]["chat"]["entitlement"] == 50+++# ---------------------------------------------------------------------------+# Poll-loop task-leak regression+# ---------------------------------------------------------------------------+++class TestCopilotQuotaPollLoopLeak:+ @pytest.mark.asyncio+ async def test_poll_loop_does_not_leak_event_wait_tasks(self, monkeypatch):+ """Regression for the ``asyncio.shield(event.wait())`` pattern.++ Matches the equivalent guard in ``tests/test_subscription_tracker.py``:+ every poll interval the loop previously leaked one Event.wait+ waiter because ``asyncio.shield`` prevented ``wait_for`` from+ cancelling the inner wait on timeout.+ """+ import asyncio++ from headroom.subscription.copilot_quota import _CopilotQuotaTracker++ # No token configured → _maybe_poll returns immediately each cycle.+ for var in ("GITHUB_COPILOT_GITHUB_TOKEN", "GITHUB_TOKEN"):+ monkeypatch.delenv(var, raising=False)++ tracker = _CopilotQuotaTracker(poll_interval_s=0.05)++ def _count_event_wait() -> int:+ return sum(+ 1+ for t in asyncio.all_tasks()+ if (t.get_coro().__qualname__ if t.get_coro() else "") == "Event.wait"+ )++ baseline = _count_event_wait()+ await tracker.start()+ try:+ await asyncio.sleep(0.3) # ~6 poll cycles+ peak = _count_event_wait()+ finally:+ await tracker.stop()++ await asyncio.sleep(0.05)+ residual = _count_event_wait()++ assert peak - baseline <= 1, (+ f"CopilotQuotaTracker leaked Event.wait: baseline={baseline} peak={peak}"+ )+ assert residual <= baseline, (+ f"CopilotQuotaTracker left residual Event.wait: baseline={baseline} residual={residual}"+ )diff --git a/tests/test_evals_datasets.py b/tests/test_evals_datasets.pyindex 74dbfd849..9f116f365 100644--- a/tests/test_evals_datasets.py+++ b/tests/test_evals_datasets.py@@ -1,538 +1,538 @@-from __future__ import annotations--import json-import sys-import urllib.request-from types import SimpleNamespace-from urllib.error import URLError--import pytest--from headroom.evals import datasets---def install_fake_datasets(- monkeypatch: pytest.MonkeyPatch,- mapping: dict[tuple[str, str | None, str | None], list[dict[str, object]]],-) -> list[tuple[str, str | None, str | None]]:- calls: list[tuple[str, str | None, str | None]] = []-- def fake_load_dataset(name: str, subset: str | None = None, split: str | None = None):- key = (name, subset, split)- calls.append(key)- return mapping[key]-- monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))- return calls---def test_check_datasets_installed_errors_without_dependency(- monkeypatch: pytest.MonkeyPatch,-) -> None:- monkeypatch.delitem(sys.modules, "datasets", raising=False)-- import builtins-- real_import = builtins.__import__-- def fake_import(name, globals=None, locals=None, fromlist=(), level=0): # noqa: ANN001- if name == "datasets":- raise ImportError("missing")- return real_import(name, globals, locals, fromlist, level)-- monkeypatch.setattr(builtins, "__import__", fake_import)-- with pytest.raises(ImportError, match="HuggingFace datasets required"):- datasets._check_datasets_installed()---def test_load_hotpotqa_and_natural_questions(monkeypatch: pytest.MonkeyPatch) -> None:- calls = install_fake_datasets(- monkeypatch,- {- ("hotpotqa/hotpot_qa", "fullwiki", "validation"): [- {- "context": {"title": ["Page A"], "sentences": [["Line 1", "Line 2"]]},- "question": "Who?",- "answer": "Alice",- "type": "bridge",- "level": "easy",- }- ],- ("google-research-datasets/natural_questions", "default", "validation"): [- {"document": {}, "question": {"text": "skip me"}},- {- "document": {- "tokens": {- "token": ["<p>", "Ada", "Lovelace", "wrote", "notes"],- "is_html": [True, False, False, False, False],- }- },- "question": {"text": "Who wrote notes?"},- "annotations": {"short_answers": [[{"start_token": 1, "end_token": 3}]]},- },- ],- },- )-- hotpot = datasets.load_hotpotqa(n=1)- natural = datasets.load_natural_questions(n=1)-- assert calls == [- ("hotpotqa/hotpot_qa", "fullwiki", "validation"),- ("google-research-datasets/natural_questions", "default", "validation"),- ]- assert hotpot.name == "HotpotQA"- assert hotpot.cases[0].context == "## Page A\nLine 1\nLine 2"- assert hotpot.cases[0].metadata["type"] == "bridge"- assert natural.name == "Natural_Questions"- assert natural.cases[0].context == "Ada Lovelace wrote notes"- assert natural.cases[0].ground_truth == "Ada Lovelace"---def test_load_triviaqa_msmarco_and_squad(monkeypatch: pytest.MonkeyPatch) -> None:- install_fake_datasets(- monkeypatch,- {- ("trivia_qa", "rc", "validation"): [- {"question": "", "search_results": {"search_context": ["unused"]}},- {- "question": "Question 1",- "search_results": {"search_context": ["A", "B"]},- "answer": {"value": "Answer", "aliases": ["Alias"]},- },- {- "question": "Question 2",- "search_results": {"search_context": []},- "entity_pages": {"wiki_context": ["Wiki 1", "Wiki 2"]},- "answer": {"normalized_value": "Normalized"},- },- ],- ("microsoft/ms_marco", "v2.1", "validation"): [- {"query": "", "passages": {"passage_text": ["skip"], "is_selected": [True]}},- {- "query": "Find docs",- "passages": {"passage_text": ["Doc 1", "Doc 2"], "is_selected": [True, False]},- "answers": ["Primary answer"],- "query_type": "description",- },- ],- ("rajpurkar/squad_v2", None, "validation"): [- {"answers": {"text": []}, "context": "skip", "question": "skip"},- {- "context": "Context",- "question": "Question",- "answers": {"text": ["First answer"]},- "title": "Title",- },- ],- },- )-- trivia = datasets.load_triviaqa(n=2)- msmarco = datasets.load_msmarco(n=1)- squad = datasets.load_squad(n=1)-- assert len(trivia.cases) == 2- assert trivia.cases[0].context == "A\n\nB"- assert trivia.cases[1].ground_truth == "Normalized"- assert trivia.cases[1].metadata["aliases"] == []- assert msmarco.cases[0].context.startswith("[RELEVANT] Passage 1: Doc 1")- assert msmarco.cases[0].metadata["num_passages"] == 2- assert squad.cases[0].ground_truth == "First answer"- assert squad.cases[0].metadata["title"] == "Title"---def test_load_longbench_narrativeqa_toolbench_codesearchnet_and_humaneval(- monkeypatch: pytest.MonkeyPatch,-) -> None:- install_fake_datasets(- monkeypatch,- {- ("THUDM/LongBench", "qasper", "test"): [- {"context": "", "input": "skip"},- {"context": "Long context", "input": "Question", "answers": ["Truth"]},- ],- ("deepmind/narrativeqa", None, "test"): [- {- "document": {"summary": {"text": "Story summary"}, "kind": "movie"},- "question": {"text": "What happened?"},- "answers": [{"text": "A"}, {"text": "B"}],- }- ],- ("ToolBench/ToolBench", "G1", "test"): [- {"api_list": [], "query": "skip"},- {- "api_list": [- {- "api_name": "weather",- "api_description": "Get weather",- "required_parameters": [{"name": "city"}],- "optional_parameters": [{"name": "unit"}],- }- ],- "query": "Weather in SF?",- "answer": "Call weather",- },- ],- ("code_search_net", "python", "test"): [- {"func_code_string": "", "func_documentation_string": "skip"},- {- "func_code_string": "def add(a, b): return a + b",- "func_documentation_string": "Add two numbers.",- "func_name": "add",- "repository_name": "repo",- },- ],- ("openai_humaneval", None, "test"): [- {"prompt": "", "canonical_solution": "skip"},- {- "task_id": "HumanEval/1",- "prompt": "def solve(x):",- "canonical_solution": "return x",- "entry_point": "solve",- "test": "assert solve(1) == 1",- },- ],- },- )-- longbench = datasets.load_longbench(n=2, task="qasper")- narrative = datasets.load_narrativeqa(n=1)- toolbench = datasets.load_toolbench(n=1, category="G1")- codesearchnet = datasets.load_codesearchnet(n=1, language="python")- humaneval = datasets.load_humaneval(n=2)-- assert longbench.name == "LongBench_qasper"- assert longbench.cases[0].metadata["context_length"] == len("Long context")- assert narrative.cases[0].metadata["all_answers"] == ["A", "B"]- assert toolbench.cases[0].metadata["num_tools"] == 1- assert '"name": "weather"' in toolbench.cases[0].context- assert codesearchnet.cases[0].ground_truth == "Add two numbers."- assert humaneval.cases[0].id == "humaneval_HumanEval/1"- assert humaneval.cases[0].metadata["entry_point"] == "solve"---def test_load_longbench_toolbench_and_codesearchnet_wrap_loader_errors(- monkeypatch: pytest.MonkeyPatch,-) -> None:- def fake_load_dataset(name: str, subset: str | None = None, split: str | None = None): # noqa: ANN001- raise RuntimeError(f"broken {name}:{subset}:{split}")-- monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))-- with pytest.raises(ValueError, match="Failed to load LongBench task 'gov_report'"):- datasets.load_longbench(task="gov_report")- with pytest.raises(ValueError, match="Failed to load ToolBench category 'G2'"):- datasets.load_toolbench(category="G2")- with pytest.raises(ValueError, match="Failed to load CodeSearchNet for 'go'"):- datasets.load_codesearchnet(language="go")---def test_load_bfcl_success_and_download_failure(monkeypatch: pytest.MonkeyPatch) -> None:- data_lines = "\n".join(- [- json.dumps(- {- "id": "case-1",- "question": [[{"role": "user", "content": "How is the weather?"}]],- "function": [{"name": "weather"}],- }- ),- json.dumps({"question": [123], "function": []}),- ]- )- gt_lines = json.dumps({"id": "case-1", "ground_truth": [{"name": "weather"}]})-- def fake_urlopen(url: str): # noqa: ANN001- if "possible_answer/BFCL_v3_simple.json" in url:- return SimpleNamespace(read=lambda: gt_lines.encode("utf-8"))- if "BFCL_v3_simple.json" in url:- return SimpleNamespace(read=lambda: data_lines.encode("utf-8"))- raise URLError("missing")-- monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)-- suite = datasets.load_bfcl(n=2, category="simple")- assert suite.name == "BFCL_simple"- assert suite.cases[0].query == "How is the weather?"- assert suite.cases[0].ground_truth == '[{"name": "weather"}]'- assert suite.cases[0].metadata["num_functions"] == 1-- def failing_urlopen(url: str): # noqa: ANN001- raise URLError("offline")-- monkeypatch.setattr(urllib.request, "urlopen", failing_urlopen)- with pytest.raises(ValueError, match="Failed to download BFCL dataset 'BFCL_v3_parallel.json'"):- datasets.load_bfcl(category="parallel")---def test_tool_output_samples_custom_dataset_and_probe_generation(tmp_path) -> None:- tool_outputs = datasets.load_tool_output_samples()- assert tool_outputs.name == "ToolOutputSamples"- assert len(tool_outputs.cases) >= 8- assert tool_outputs.cases[0].ground_truth == "prompt-optimizer"-- custom_path = tmp_path / "custom.jsonl"- custom_path.write_text(- json.dumps(- {"id": "case1", "context": "Context", "query": "Question", "ground_truth": "Answer"}- )- + "\n",- encoding="utf-8",- )- custom_suite = datasets.load_custom_dataset(custom_path)- assert custom_suite.cases[0].id == "case1"-- probes = datasets.generate_retrieval_probes(- 'Alice Smith deployed API on 2024-01-15 at 99.9% confidence for "Launch Ready" and build_id',- n_probes=5,- )- assert "Alice Smith" in probes- assert "2024-01-15" in probes- assert "API" in probes- assert "99.9" in probes- assert "Launch Ready" in probes---def test_dataset_registry_helpers(monkeypatch: pytest.MonkeyPatch) -> None:- categories = datasets.list_available_datasets()- assert "hotpotqa" in categories["rag"]- assert "tool_outputs" in categories["tool_use"]-- seen: list[tuple[str, dict[str, object]]] = []-- def fake_loader(*, n: int = 0, **kwargs): # noqa: ANN003- seen.append(("with-n", {"n": n, **kwargs}))- return "with-n-result"-- def fixed_loader(**kwargs): # noqa: ANN003- seen.append(("fixed", kwargs))- return "fixed-result"-- original_registry = dict(datasets.DATASET_REGISTRY)- monkeypatch.setattr(- datasets,- "DATASET_REGISTRY",- {- **original_registry,- "fake_n": {"loader": fake_loader, "category": "x", "description": "", "default_n": 3},- "fake_fixed": {- "loader": fixed_loader,- "category": "x",- "description": "",- "default_n": None,- },- },- )-- assert datasets.load_dataset_by_name("fake_n") == "with-n-result"- assert datasets.load_dataset_by_name("fake_n", n=7, split="test") == "with-n-result"- assert datasets.load_dataset_by_name("fake_fixed", path="x") == "fixed-result"- assert seen == [- ("with-n", {"n": 3}),- ("with-n", {"n": 7, "split": "test"}),- ("fixed", {"path": "x"}),- ]-- with pytest.raises(ValueError, match="Unknown dataset 'missing'"):- datasets.load_dataset_by_name("missing")---def test_dataset_loaders_cover_skip_and_limit_branches(monkeypatch: pytest.MonkeyPatch) -> None:- install_fake_datasets(- monkeypatch,- {- ("hotpotqa/hotpot_qa", "fullwiki", "validation"): [- {- "context": {"title": ["Page A"], "sentences": [["Line 1"]]},- "question": "Q1",- "answer": "A1",- },- {- "context": {"title": ["Page B"], "sentences": [["Line 2"]]},- "question": "Q2",- "answer": "A2",- },- ],- ("google-research-datasets/natural_questions", "default", "validation"): [- {- "document": {"tokens": {"token": ["x"], "is_html": [False]}},- "question": {"text": ""},- },- {- "document": {"tokens": {"token": ["<b>"], "is_html": [True]}},- "question": {"text": "blank context"},- },- {- "document": {"tokens": {"token": ["Ada", "wrote"], "is_html": [False, False]}},- "question": {"text": "Who?"},- "annotations": {"short_answers": [[{"start_token": 1, "end_token": 1}]]},- },- {- "document": {"tokens": {"token": ["Grace"], "is_html": [False]}},- "question": {"text": "Ignored by limit"},- },- ],- ("trivia_qa", "rc", "validation"): [- {"question": "skip", "search_results": {"search_context": []}, "entity_pages": {}},- {"question": "blank", "search_results": {"search_context": [""]}},- {- "question": "Good 1",- "search_results": {"search_context": ["Context 1"]},- "answer": {"value": "A1"},- },- {- "question": "Good 2",- "search_results": {"search_context": ["Context 2"]},- "answer": {"value": "A2"},- },- ],- ("microsoft/ms_marco", "v2.1", "validation"): [- {"query": "skip", "passages": {"passage_text": [], "is_selected": []}},- {- "query": "Find one",- "passages": {"passage_text": ["Doc 1"], "is_selected": [False]},- "answers": [],- },- {- "query": "Find two",- "passages": {"passage_text": ["Doc 2"], "is_selected": [True]},- "answers": ["A2"],- },- ],- ("rajpurkar/squad_v2", None, "validation"): [- {- "context": "Context 1",- "question": "Q1",- "answers": {"text": ["A1"]},- },- {- "context": "Context 2",- "question": "Q2",- "answers": {"text": ["A2"]},- },- ],- ("THUDM/LongBench", "qasper", "test"): [- {"context": "Context 1", "input": "Q1", "answers": ["A1"]},- {"context": "Has context", "input": ""},- {"context": "Context 2", "input": "Q2", "answers": ["A2"]},- ],- ("deepmind/narrativeqa", None, "test"): [- {"document": {"summary": {"text": ""}}, "question": {"text": "skip"}},- {"document": {"summary": {"text": "Story"}}, "question": {"text": ""}},- {- "document": {"summary": {"text": "Story 1"}, "kind": "book"},- "question": {"text": "Q1"},- "answers": [{"text": "A1"}],- },- {- "document": {"summary": {"text": "Story 2"}, "kind": "movie"},- "question": {"text": "Q2"},- "answers": [{"text": "A2"}],- },- ],- ("ToolBench/ToolBench", "G1", "test"): [- {"api_list": [], "query": "skip"},- {- "api_list": [- {- "api_name": "weather",- "required_parameters": [],- "optional_parameters": [],- }- ],- "query": "",- },- {- "api_list": [- {"api_name": "calc", "required_parameters": [], "optional_parameters": []}- ],- "query": "Good",- },- ],- ("code_search_net", "python", "test"): [- {- "func_code_string": "",- "whole_func_string": "",- "func_documentation_string": "skip",- },- {"whole_func_string": "def alt(): pass", "func_documentation_string": ""},- {- "whole_func_string": "def good(): pass",- "func_documentation_string": "Good doc",- "func_name": "good",- "repository_name": "repo",- },- {- "whole_func_string": "def ignored(): pass",- "func_documentation_string": "Ignored by limit",- },- ],- ("openai_humaneval", None, "test"): [- {- "task_id": "Task/1",- "prompt": "def solve():",- "canonical_solution": "return 1",- "test": "assert solve() == 1",- },- {- "task_id": "Task/2",- "prompt": "def other():",- "canonical_solution": "return 2",- "test": "assert other() == 2",- },- ],- },- )-- assert len(datasets.load_hotpotqa(n=1).cases) == 1- natural = datasets.load_natural_questions(n=1)- assert len(natural.cases) == 1- assert natural.cases[0].ground_truth is None- assert len(datasets.load_triviaqa(n=1).cases) == 1- msmarco = datasets.load_msmarco(n=1)- assert len(msmarco.cases) == 1- assert msmarco.cases[0].ground_truth is None- assert len(datasets.load_squad(n=1).cases) == 1- assert len(datasets.load_longbench(n=2, task="qasper").cases) == 1- assert len(datasets.load_narrativeqa(n=1).cases) == 1- assert len(datasets.load_toolbench(n=1, category="G1").cases) == 1- assert len(datasets.load_codesearchnet(n=1, language="python").cases) == 1- assert len(datasets.load_humaneval(n=1).cases) == 1---def test_load_bfcl_handles_optional_ground_truth_and_question_fallback(- monkeypatch: pytest.MonkeyPatch,-) -> None:- data_lines = "\n".join(- [- json.dumps(- {- "id": "case-1",- "question": [123],- "function": [{"name": "weather"}],- }- ),- json.dumps({"id": "skip", "function": []}),- json.dumps(- {- "id": "case-2",- "question": [[{"role": "user", "content": "Ignored by limit"}]],- "function": [{"name": "time"}],- }- ),- ]- )-- def fake_urlopen(url: str): # noqa: ANN001- if "possible_answer" in url:- raise URLError("missing ground truth")- return SimpleNamespace(read=lambda: data_lines.encode("utf-8"))-- monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)-- suite = datasets.load_bfcl(n=2, category="simple")- assert len(suite.cases) == 1- assert suite.cases[0].query == "[123]"- assert suite.cases[0].ground_truth is None+from __future__ import annotations++import json+import sys+import urllib.request+from types import SimpleNamespace+from urllib.error import URLError++import pytest++from headroom.evals import datasets+++def install_fake_datasets(+ monkeypatch: pytest.MonkeyPatch,+ mapping: dict[tuple[str, str | None, str | None], list[dict[str, object]]],+) -> list[tuple[str, str | None, str | None]]:+ calls: list[tuple[str, str | None, str | None]] = []++ def fake_load_dataset(name: str, subset: str | None = None, split: str | None = None):+ key = (name, subset, split)+ calls.append(key)+ return mapping[key]++ monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))+ return calls+++def test_check_datasets_installed_errors_without_dependency(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.delitem(sys.modules, "datasets", raising=False)++ import builtins++ real_import = builtins.__import__++ def fake_import(name, globals=None, locals=None, fromlist=(), level=0): # noqa: ANN001+ if name == "datasets":+ raise ImportError("missing")+ return real_import(name, globals, locals, fromlist, level)++ monkeypatch.setattr(builtins, "__import__", fake_import)++ with pytest.raises(ImportError, match="HuggingFace datasets required"):+ datasets._check_datasets_installed()+++def test_load_hotpotqa_and_natural_questions(monkeypatch: pytest.MonkeyPatch) -> None:+ calls = install_fake_datasets(+ monkeypatch,+ {+ ("hotpotqa/hotpot_qa", "fullwiki", "validation"): [+ {+ "context": {"title": ["Page A"], "sentences": [["Line 1", "Line 2"]]},+ "question": "Who?",+ "answer": "Alice",+ "type": "bridge",+ "level": "easy",+ }+ ],+ ("google-research-datasets/natural_questions", "default", "validation"): [+ {"document": {}, "question": {"text": "skip me"}},+ {+ "document": {+ "tokens": {+ "token": ["<p>", "Ada", "Lovelace", "wrote", "notes"],+ "is_html": [True, False, False, False, False],+ }+ },+ "question": {"text": "Who wrote notes?"},+ "annotations": {"short_answers": [[{"start_token": 1, "end_token": 3}]]},+ },+ ],+ },+ )++ hotpot = datasets.load_hotpotqa(n=1)+ natural = datasets.load_natural_questions(n=1)++ assert calls == [+ ("hotpotqa/hotpot_qa", "fullwiki", "validation"),+ ("google-research-datasets/natural_questions", "default", "validation"),+ ]+ assert hotpot.name == "HotpotQA"+ assert hotpot.cases[0].context == "## Page A\nLine 1\nLine 2"+ assert hotpot.cases[0].metadata["type"] == "bridge"+ assert natural.name == "Natural_Questions"+ assert natural.cases[0].context == "Ada Lovelace wrote notes"+ assert natural.cases[0].ground_truth == "Ada Lovelace"+++def test_load_triviaqa_msmarco_and_squad(monkeypatch: pytest.MonkeyPatch) -> None:+ install_fake_datasets(+ monkeypatch,+ {+ ("trivia_qa", "rc", "validation"): [+ {"question": "", "search_results": {"search_context": ["unused"]}},+ {+ "question": "Question 1",+ "search_results": {"search_context": ["A", "B"]},+ "answer": {"value": "Answer", "aliases": ["Alias"]},+ },+ {+ "question": "Question 2",+ "search_results": {"search_context": []},+ "entity_pages": {"wiki_context": ["Wiki 1", "Wiki 2"]},+ "answer": {"normalized_value": "Normalized"},+ },+ ],+ ("microsoft/ms_marco", "v2.1", "validation"): [+ {"query": "", "passages": {"passage_text": ["skip"], "is_selected": [True]}},+ {+ "query": "Find docs",+ "passages": {"passage_text": ["Doc 1", "Doc 2"], "is_selected": [True, False]},+ "answers": ["Primary answer"],+ "query_type": "description",+ },+ ],+ ("rajpurkar/squad_v2", None, "validation"): [+ {"answers": {"text": []}, "context": "skip", "question": "skip"},+ {+ "context": "Context",+ "question": "Question",+ "answers": {"text": ["First answer"]},+ "title": "Title",+ },+ ],+ },+ )++ trivia = datasets.load_triviaqa(n=2)+ msmarco = datasets.load_msmarco(n=1)+ squad = datasets.load_squad(n=1)++ assert len(trivia.cases) == 2+ assert trivia.cases[0].context == "A\n\nB"+ assert trivia.cases[1].ground_truth == "Normalized"+ assert trivia.cases[1].metadata["aliases"] == []+ assert msmarco.cases[0].context.startswith("[RELEVANT] Passage 1: Doc 1")+ assert msmarco.cases[0].metadata["num_passages"] == 2+ assert squad.cases[0].ground_truth == "First answer"+ assert squad.cases[0].metadata["title"] == "Title"+++def test_load_longbench_narrativeqa_toolbench_codesearchnet_and_humaneval(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ install_fake_datasets(+ monkeypatch,+ {+ ("THUDM/LongBench", "qasper", "test"): [+ {"context": "", "input": "skip"},+ {"context": "Long context", "input": "Question", "answers": ["Truth"]},+ ],+ ("deepmind/narrativeqa", None, "test"): [+ {+ "document": {"summary": {"text": "Story summary"}, "kind": "movie"},+ "question": {"text": "What happened?"},+ "answers": [{"text": "A"}, {"text": "B"}],+ }+ ],+ ("ToolBench/ToolBench", "G1", "test"): [+ {"api_list": [], "query": "skip"},+ {+ "api_list": [+ {+ "api_name": "weather",+ "api_description": "Get weather",+ "required_parameters": [{"name": "city"}],+ "optional_parameters": [{"name": "unit"}],+ }+ ],+ "query": "Weather in SF?",+ "answer": "Call weather",+ },+ ],+ ("code_search_net", "python", "test"): [+ {"func_code_string": "", "func_documentation_string": "skip"},+ {+ "func_code_string": "def add(a, b): return a + b",+ "func_documentation_string": "Add two numbers.",+ "func_name": "add",+ "repository_name": "repo",+ },+ ],+ ("openai_humaneval", None, "test"): [+ {"prompt": "", "canonical_solution": "skip"},+ {+ "task_id": "HumanEval/1",+ "prompt": "def solve(x):",+ "canonical_solution": "return x",+ "entry_point": "solve",+ "test": "assert solve(1) == 1",+ },+ ],+ },+ )++ longbench = datasets.load_longbench(n=2, task="qasper")+ narrative = datasets.load_narrativeqa(n=1)+ toolbench = datasets.load_toolbench(n=1, category="G1")+ codesearchnet = datasets.load_codesearchnet(n=1, language="python")+ humaneval = datasets.load_humaneval(n=2)++ assert longbench.name == "LongBench_qasper"+ assert longbench.cases[0].metadata["context_length"] == len("Long context")+ assert narrative.cases[0].metadata["all_answers"] == ["A", "B"]+ assert toolbench.cases[0].metadata["num_tools"] == 1+ assert '"name": "weather"' in toolbench.cases[0].context+ assert codesearchnet.cases[0].ground_truth == "Add two numbers."+ assert humaneval.cases[0].id == "humaneval_HumanEval/1"+ assert humaneval.cases[0].metadata["entry_point"] == "solve"+++def test_load_longbench_toolbench_and_codesearchnet_wrap_loader_errors(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ def fake_load_dataset(name: str, subset: str | None = None, split: str | None = None): # noqa: ANN001+ raise RuntimeError(f"broken {name}:{subset}:{split}")++ monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))++ with pytest.raises(ValueError, match="Failed to load LongBench task 'gov_report'"):+ datasets.load_longbench(task="gov_report")+ with pytest.raises(ValueError, match="Failed to load ToolBench category 'G2'"):+ datasets.load_toolbench(category="G2")+ with pytest.raises(ValueError, match="Failed to load CodeSearchNet for 'go'"):+ datasets.load_codesearchnet(language="go")+++def test_load_bfcl_success_and_download_failure(monkeypatch: pytest.MonkeyPatch) -> None:+ data_lines = "\n".join(+ [+ json.dumps(+ {+ "id": "case-1",+ "question": [[{"role": "user", "content": "How is the weather?"}]],+ "function": [{"name": "weather"}],+ }+ ),+ json.dumps({"question": [123], "function": []}),+ ]+ )+ gt_lines = json.dumps({"id": "case-1", "ground_truth": [{"name": "weather"}]})++ def fake_urlopen(url: str): # noqa: ANN001+ if "possible_answer/BFCL_v3_simple.json" in url:+ return SimpleNamespace(read=lambda: gt_lines.encode("utf-8"))+ if "BFCL_v3_simple.json" in url:+ return SimpleNamespace(read=lambda: data_lines.encode("utf-8"))+ raise URLError("missing")++ monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)++ suite = datasets.load_bfcl(n=2, category="simple")+ assert suite.name == "BFCL_simple"+ assert suite.cases[0].query == "How is the weather?"+ assert suite.cases[0].ground_truth == '[{"name": "weather"}]'+ assert suite.cases[0].metadata["num_functions"] == 1++ def failing_urlopen(url: str): # noqa: ANN001+ raise URLError("offline")++ monkeypatch.setattr(urllib.request, "urlopen", failing_urlopen)+ with pytest.raises(ValueError, match="Failed to download BFCL dataset 'BFCL_v3_parallel.json'"):+ datasets.load_bfcl(category="parallel")+++def test_tool_output_samples_custom_dataset_and_probe_generation(tmp_path) -> None:+ tool_outputs = datasets.load_tool_output_samples()+ assert tool_outputs.name == "ToolOutputSamples"+ assert len(tool_outputs.cases) >= 8+ assert tool_outputs.cases[0].ground_truth == "prompt-optimizer"++ custom_path = tmp_path / "custom.jsonl"+ custom_path.write_text(+ json.dumps(+ {"id": "case1", "context": "Context", "query": "Question", "ground_truth": "Answer"}+ )+ + "\n",+ encoding="utf-8",+ )+ custom_suite = datasets.load_custom_dataset(custom_path)+ assert custom_suite.cases[0].id == "case1"++ probes = datasets.generate_retrieval_probes(+ 'Alice Smith deployed API on 2024-01-15 at 99.9% confidence for "Launch Ready" and build_id',+ n_probes=5,+ )+ assert "Alice Smith" in probes+ assert "2024-01-15" in probes+ assert "API" in probes+ assert "99.9" in probes+ assert "Launch Ready" in probes+++def test_dataset_registry_helpers(monkeypatch: pytest.MonkeyPatch) -> None:+ categories = datasets.list_available_datasets()+ assert "hotpotqa" in categories["rag"]+ assert "tool_outputs" in categories["tool_use"]++ seen: list[tuple[str, dict[str, object]]] = []++ def fake_loader(*, n: int = 0, **kwargs): # noqa: ANN003+ seen.append(("with-n", {"n": n, **kwargs}))+ return "with-n-result"++ def fixed_loader(**kwargs): # noqa: ANN003+ seen.append(("fixed", kwargs))+ return "fixed-result"++ original_registry = dict(datasets.DATASET_REGISTRY)+ monkeypatch.setattr(+ datasets,+ "DATASET_REGISTRY",+ {+ **original_registry,+ "fake_n": {"loader": fake_loader, "category": "x", "description": "", "default_n": 3},+ "fake_fixed": {+ "loader": fixed_loader,+ "category": "x",+ "description": "",+ "default_n": None,+ },+ },+ )++ assert datasets.load_dataset_by_name("fake_n") == "with-n-result"+ assert datasets.load_dataset_by_name("fake_n", n=7, split="test") == "with-n-result"+ assert datasets.load_dataset_by_name("fake_fixed", path="x") == "fixed-result"+ assert seen == [+ ("with-n", {"n": 3}),+ ("with-n", {"n": 7, "split": "test"}),+ ("fixed", {"path": "x"}),+ ]++ with pytest.raises(ValueError, match="Unknown dataset 'missing'"):+ datasets.load_dataset_by_name("missing")+++def test_dataset_loaders_cover_skip_and_limit_branches(monkeypatch: pytest.MonkeyPatch) -> None:+ install_fake_datasets(+ monkeypatch,+ {+ ("hotpotqa/hotpot_qa", "fullwiki", "validation"): [+ {+ "context": {"title": ["Page A"], "sentences": [["Line 1"]]},+ "question": "Q1",+ "answer": "A1",+ },+ {+ "context": {"title": ["Page B"], "sentences": [["Line 2"]]},+ "question": "Q2",+ "answer": "A2",+ },+ ],+ ("google-research-datasets/natural_questions", "default", "validation"): [+ {+ "document": {"tokens": {"token": ["x"], "is_html": [False]}},+ "question": {"text": ""},+ },+ {+ "document": {"tokens": {"token": ["<b>"], "is_html": [True]}},+ "question": {"text": "blank context"},+ },+ {+ "document": {"tokens": {"token": ["Ada", "wrote"], "is_html": [False, False]}},+ "question": {"text": "Who?"},+ "annotations": {"short_answers": [[{"start_token": 1, "end_token": 1}]]},+ },+ {+ "document": {"tokens": {"token": ["Grace"], "is_html": [False]}},+ "question": {"text": "Ignored by limit"},+ },+ ],+ ("trivia_qa", "rc", "validation"): [+ {"question": "skip", "search_results": {"search_context": []}, "entity_pages": {}},+ {"question": "blank", "search_results": {"search_context": [""]}},+ {+ "question": "Good 1",+ "search_results": {"search_context": ["Context 1"]},+ "answer": {"value": "A1"},+ },+ {+ "question": "Good 2",+ "search_results": {"search_context": ["Context 2"]},+ "answer": {"value": "A2"},+ },+ ],+ ("microsoft/ms_marco", "v2.1", "validation"): [+ {"query": "skip", "passages": {"passage_text": [], "is_selected": []}},+ {+ "query": "Find one",+ "passages": {"passage_text": ["Doc 1"], "is_selected": [False]},+ "answers": [],+ },+ {+ "query": "Find two",+ "passages": {"passage_text": ["Doc 2"], "is_selected": [True]},+ "answers": ["A2"],+ },+ ],+ ("rajpurkar/squad_v2", None, "validation"): [+ {+ "context": "Context 1",+ "question": "Q1",+ "answers": {"text": ["A1"]},+ },+ {+ "context": "Context 2",+ "question": "Q2",+ "answers": {"text": ["A2"]},+ },+ ],+ ("THUDM/LongBench", "qasper", "test"): [+ {"context": "Context 1", "input": "Q1", "answers": ["A1"]},+ {"context": "Has context", "input": ""},+ {"context": "Context 2", "input": "Q2", "answers": ["A2"]},+ ],+ ("deepmind/narrativeqa", None, "test"): [+ {"document": {"summary": {"text": ""}}, "question": {"text": "skip"}},+ {"document": {"summary": {"text": "Story"}}, "question": {"text": ""}},+ {+ "document": {"summary": {"text": "Story 1"}, "kind": "book"},+ "question": {"text": "Q1"},+ "answers": [{"text": "A1"}],+ },+ {+ "document": {"summary": {"text": "Story 2"}, "kind": "movie"},+ "question": {"text": "Q2"},+ "answers": [{"text": "A2"}],+ },+ ],+ ("ToolBench/ToolBench", "G1", "test"): [+ {"api_list": [], "query": "skip"},+ {+ "api_list": [+ {+ "api_name": "weather",+ "required_parameters": [],+ "optional_parameters": [],+ }+ ],+ "query": "",+ },+ {+ "api_list": [+ {"api_name": "calc", "required_parameters": [], "optional_parameters": []}+ ],+ "query": "Good",+ },+ ],+ ("code_search_net", "python", "test"): [+ {+ "func_code_string": "",+ "whole_func_string": "",+ "func_documentation_string": "skip",+ },+ {"whole_func_string": "def alt(): pass", "func_documentation_string": ""},+ {+ "whole_func_string": "def good(): pass",+ "func_documentation_string": "Good doc",+ "func_name": "good",+ "repository_name": "repo",+ },+ {+ "whole_func_string": "def ignored(): pass",+ "func_documentation_string": "Ignored by limit",+ },+ ],+ ("openai_humaneval", None, "test"): [+ {+ "task_id": "Task/1",+ "prompt": "def solve():",+ "canonical_solution": "return 1",+ "test": "assert solve() == 1",+ },+ {+ "task_id": "Task/2",+ "prompt": "def other():",+ "canonical_solution": "return 2",+ "test": "assert other() == 2",+ },+ ],+ },+ )++ assert len(datasets.load_hotpotqa(n=1).cases) == 1+ natural = datasets.load_natural_questions(n=1)+ assert len(natural.cases) == 1+ assert natural.cases[0].ground_truth is None+ assert len(datasets.load_triviaqa(n=1).cases) == 1+ msmarco = datasets.load_msmarco(n=1)+ assert len(msmarco.cases) == 1+ assert msmarco.cases[0].ground_truth is None+ assert len(datasets.load_squad(n=1).cases) == 1+ assert len(datasets.load_longbench(n=2, task="qasper").cases) == 1+ assert len(datasets.load_narrativeqa(n=1).cases) == 1+ assert len(datasets.load_toolbench(n=1, category="G1").cases) == 1+ assert len(datasets.load_codesearchnet(n=1, language="python").cases) == 1+ assert len(datasets.load_humaneval(n=1).cases) == 1+++def test_load_bfcl_handles_optional_ground_truth_and_question_fallback(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ data_lines = "\n".join(+ [+ json.dumps(+ {+ "id": "case-1",+ "question": [123],+ "function": [{"name": "weather"}],+ }+ ),+ json.dumps({"id": "skip", "function": []}),+ json.dumps(+ {+ "id": "case-2",+ "question": [[{"role": "user", "content": "Ignored by limit"}]],+ "function": [{"name": "time"}],+ }+ ),+ ]+ )++ def fake_urlopen(url: str): # noqa: ANN001+ if "possible_answer" in url:+ raise URLError("missing ground truth")+ return SimpleNamespace(read=lambda: data_lines.encode("utf-8"))++ monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)++ suite = datasets.load_bfcl(n=2, category="simple")+ assert len(suite.cases) == 1+ assert suite.cases[0].query == "[123]"+ assert suite.cases[0].ground_truth is Nonediff --git a/tests/test_evals_metrics.py b/tests/test_evals_metrics.pyindex 8406be8ee..371e36951 100644--- a/tests/test_evals_metrics.py+++ b/tests/test_evals_metrics.py@@ -1,132 +1,132 @@-from __future__ import annotations--import math-import sys-from types import SimpleNamespace--import pytest--from headroom.evals import metrics---def test_normalize_tokenize_and_exact_match() -> None:- assert metrics.normalize_text(" Hello,\nWORLD ") == "hello, world"- assert metrics.tokenize("Hello, world! API_v2") == ["hello", "world", "api_v2"]- assert metrics.compute_exact_match(" Hello World ", "hello\nworld") is True- assert metrics.compute_exact_match("hello", "world") is False---def test_f1_bleu_and_rouge_cover_edge_cases() -> None:- assert metrics.compute_f1("", "value") == 0.0- assert metrics.compute_f1("alpha beta", "gamma delta") == 0.0- assert metrics.compute_f1("alpha beta gamma", "alpha gamma") == pytest.approx(0.8)-- assert metrics.compute_bleu("", "value") == 0.0- assert metrics.compute_bleu("one", "one") == pytest.approx(1.0)- assert metrics.compute_bleu("alpha beta", "gamma delta") == 0.0- assert metrics.compute_bleu("alpha beta", "alpha beta gamma", max_n=4) == pytest.approx(1.0)-- assert metrics.compute_rouge_l("", "value") == 0.0- assert metrics.compute_rouge_l("alpha beta", "gamma delta") == 0.0- assert metrics.compute_rouge_l("alpha beta gamma", "alpha gamma") == pytest.approx(0.8)---def test_compute_semantic_similarity_and_zero_norm(monkeypatch: pytest.MonkeyPatch) -> None:- fake_numpy = SimpleNamespace(- dot=lambda a, b: sum(x * y for x, y in zip(a, b)),- linalg=SimpleNamespace(norm=lambda a: math.sqrt(sum(x * x for x in a))),- )- monkeypatch.setitem(sys.modules, "numpy", fake_numpy)-- class FakeModel:- def __init__(self, embeddings: list[list[float]]) -> None:- self.embeddings = embeddings-- def encode(self, values: list[str]) -> list[list[float]]:- assert values == ["first", "second"]- return self.embeddings-- monkeypatch.setattr(- "headroom.models.ml_models.MLModelRegistry.get_sentence_transformer",- lambda model_name=None: FakeModel([[1.0, 0.0], [1.0, 0.0]]),- )- assert metrics.compute_semantic_similarity("first", "second") == 1.0-- monkeypatch.setattr(- "headroom.models.ml_models.MLModelRegistry.get_sentence_transformer",- lambda model_name=None: FakeModel([[0.0, 0.0], [1.0, 0.0]]),- )- assert metrics.compute_semantic_similarity("first", "second") == 0.0---def test_compute_answer_equivalence_uses_multiple_paths(monkeypatch: pytest.MonkeyPatch) -> None:- monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.2)- exact = metrics.compute_answer_equivalence("Answer", "answer", ground_truth="missing")- assert exact["exact_match"] is True- assert exact["equivalent"] is True- assert exact["ground_truth_in_a"] is False- assert exact["ground_truth_in_b"] is False-- monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.1)- high_f1 = metrics.compute_answer_equivalence(- "alpha beta gamma",- "alpha gamma",- semantic_threshold=0.95,- f1_threshold=0.75,- )- assert high_f1["equivalent"] is True- assert high_f1["semantic_similarity"] == 0.1-- monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.95)- semantic = metrics.compute_answer_equivalence(- "completely different",- "nothing in common",- semantic_threshold=0.9,- f1_threshold=0.99,- )- assert semantic["equivalent"] is True- assert semantic["semantic_similarity"] == 0.95-- def raise_import_error(a: str, b: str) -> float:- raise ImportError("missing dependency")-- monkeypatch.setattr(metrics, "compute_semantic_similarity", raise_import_error)- ground_truth = metrics.compute_answer_equivalence(- "The capital is Paris.",- "Paris is definitely the capital city.",- ground_truth="paris",- semantic_threshold=0.99,- f1_threshold=0.99,- )- assert ground_truth["semantic_similarity"] is None- assert ground_truth["ground_truth_in_a"] is True- assert ground_truth["ground_truth_in_b"] is True- assert ground_truth["equivalent"] is True-- not_equivalent = metrics.compute_answer_equivalence(- "alpha beta",- "gamma delta",- ground_truth="omega",- semantic_threshold=0.99,- f1_threshold=0.99,- )- assert not_equivalent["equivalent"] is False---def test_information_recall_reports_preserved_and_missing_facts() -> None:- result = metrics.compute_information_recall(- "Alice likes pizza and Bob likes ramen.",- "Alice likes pizza.",- ["Alice", "Bob", "ramen", "Carol"],- )- assert result == {- "total_probes": 4,- "facts_in_original": 3,- "facts_preserved": 1,- "facts_lost": ["Bob", "ramen"],- "recall": pytest.approx(1 / 3),- }-- empty_original = metrics.compute_information_recall("No facts here", "Still none", ["Alice"])- assert empty_original["facts_in_original"] == 0- assert empty_original["recall"] == 1.0+from __future__ import annotations++import math+import sys+from types import SimpleNamespace++import pytest++from headroom.evals import metrics+++def test_normalize_tokenize_and_exact_match() -> None:+ assert metrics.normalize_text(" Hello,\nWORLD ") == "hello, world"+ assert metrics.tokenize("Hello, world! API_v2") == ["hello", "world", "api_v2"]+ assert metrics.compute_exact_match(" Hello World ", "hello\nworld") is True+ assert metrics.compute_exact_match("hello", "world") is False+++def test_f1_bleu_and_rouge_cover_edge_cases() -> None:+ assert metrics.compute_f1("", "value") == 0.0+ assert metrics.compute_f1("alpha beta", "gamma delta") == 0.0+ assert metrics.compute_f1("alpha beta gamma", "alpha gamma") == pytest.approx(0.8)++ assert metrics.compute_bleu("", "value") == 0.0+ assert metrics.compute_bleu("one", "one") == pytest.approx(1.0)+ assert metrics.compute_bleu("alpha beta", "gamma delta") == 0.0+ assert metrics.compute_bleu("alpha beta", "alpha beta gamma", max_n=4) == pytest.approx(1.0)++ assert metrics.compute_rouge_l("", "value") == 0.0+ assert metrics.compute_rouge_l("alpha beta", "gamma delta") == 0.0+ assert metrics.compute_rouge_l("alpha beta gamma", "alpha gamma") == pytest.approx(0.8)+++def test_compute_semantic_similarity_and_zero_norm(monkeypatch: pytest.MonkeyPatch) -> None:+ fake_numpy = SimpleNamespace(+ dot=lambda a, b: sum(x * y for x, y in zip(a, b)),+ linalg=SimpleNamespace(norm=lambda a: math.sqrt(sum(x * x for x in a))),+ )+ monkeypatch.setitem(sys.modules, "numpy", fake_numpy)++ class FakeModel:+ def __init__(self, embeddings: list[list[float]]) -> None:+ self.embeddings = embeddings++ def encode(self, values: list[str]) -> list[list[float]]:+ assert values == ["first", "second"]+ return self.embeddings++ monkeypatch.setattr(+ "headroom.models.ml_models.MLModelRegistry.get_sentence_transformer",+ lambda model_name=None: FakeModel([[1.0, 0.0], [1.0, 0.0]]),+ )+ assert metrics.compute_semantic_similarity("first", "second") == 1.0++ monkeypatch.setattr(+ "headroom.models.ml_models.MLModelRegistry.get_sentence_transformer",+ lambda model_name=None: FakeModel([[0.0, 0.0], [1.0, 0.0]]),+ )+ assert metrics.compute_semantic_similarity("first", "second") == 0.0+++def test_compute_answer_equivalence_uses_multiple_paths(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.2)+ exact = metrics.compute_answer_equivalence("Answer", "answer", ground_truth="missing")+ assert exact["exact_match"] is True+ assert exact["equivalent"] is True+ assert exact["ground_truth_in_a"] is False+ assert exact["ground_truth_in_b"] is False++ monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.1)+ high_f1 = metrics.compute_answer_equivalence(+ "alpha beta gamma",+ "alpha gamma",+ semantic_threshold=0.95,+ f1_threshold=0.75,+ )+ assert high_f1["equivalent"] is True+ assert high_f1["semantic_similarity"] == 0.1++ monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.95)+ semantic = metrics.compute_answer_equivalence(+ "completely different",+ "nothing in common",+ semantic_threshold=0.9,+ f1_threshold=0.99,+ )+ assert semantic["equivalent"] is True+ assert semantic["semantic_similarity"] == 0.95++ def raise_import_error(a: str, b: str) -> float:+ raise ImportError("missing dependency")++ monkeypatch.setattr(metrics, "compute_semantic_similarity", raise_import_error)+ ground_truth = metrics.compute_answer_equivalence(+ "The capital is Paris.",+ "Paris is definitely the capital city.",+ ground_truth="paris",+ semantic_threshold=0.99,+ f1_threshold=0.99,+ )+ assert ground_truth["semantic_similarity"] is None+ assert ground_truth["ground_truth_in_a"] is True+ assert ground_truth["ground_truth_in_b"] is True+ assert ground_truth["equivalent"] is True++ not_equivalent = metrics.compute_answer_equivalence(+ "alpha beta",+ "gamma delta",+ ground_truth="omega",+ semantic_threshold=0.99,+ f1_threshold=0.99,+ )+ assert not_equivalent["equivalent"] is False+++def test_information_recall_reports_preserved_and_missing_facts() -> None:+ result = metrics.compute_information_recall(+ "Alice likes pizza and Bob likes ramen.",+ "Alice likes pizza.",+ ["Alice", "Bob", "ramen", "Carol"],+ )+ assert result == {+ "total_probes": 4,+ "facts_in_original": 3,+ "facts_preserved": 1,+ "facts_lost": ["Bob", "ramen"],+ "recall": pytest.approx(1 / 3),+ }++ empty_original = metrics.compute_information_recall("No facts here", "Still none", ["Alice"])+ assert empty_original["facts_in_original"] == 0+ assert empty_original["recall"] == 1.0diff --git a/tests/test_exceptions.py b/tests/test_exceptions.pyindex 938cb219f..5061ea2d6 100644--- a/tests/test_exceptions.py+++ b/tests/test_exceptions.py@@ -1,40 +1,40 @@-from __future__ import annotations--from headroom.exceptions import (- CacheError,- CompressionError,- ConfigurationError,- HeadroomError,- ProviderError,- StorageError,- TokenizationError,- TransformError,- ValidationError,-)---def test_headroom_error_formats_details() -> None:- err = HeadroomError("bad config", details={"mode": "foo", "valid": "bar"})- assert err.message == "bad config"- assert err.details == {"mode": "foo", "valid": "bar"}- assert str(err) == "bad config (mode=foo, valid=bar)"-- plain = HeadroomError("just bad")- assert plain.details == {}- assert str(plain) == "just bad"---def test_specialized_exceptions_inherit_headroom_error() -> None:- for exc_type in (- ConfigurationError,- ProviderError,- StorageError,- CompressionError,- TokenizationError,- CacheError,- ValidationError,- TransformError,- ):- err = exc_type("problem", details={"kind": exc_type.__name__})- assert isinstance(err, HeadroomError)- assert str(err) == f"problem (kind={exc_type.__name__})"+from __future__ import annotations++from headroom.exceptions import (+ CacheError,+ CompressionError,+ ConfigurationError,+ HeadroomError,+ ProviderError,+ StorageError,+ TokenizationError,+ TransformError,+ ValidationError,+)+++def test_headroom_error_formats_details() -> None:+ err = HeadroomError("bad config", details={"mode": "foo", "valid": "bar"})+ assert err.message == "bad config"+ assert err.details == {"mode": "foo", "valid": "bar"}+ assert str(err) == "bad config (mode=foo, valid=bar)"++ plain = HeadroomError("just bad")+ assert plain.details == {}+ assert str(plain) == "just bad"+++def test_specialized_exceptions_inherit_headroom_error() -> None:+ for exc_type in (+ ConfigurationError,+ ProviderError,+ StorageError,+ CompressionError,+ TokenizationError,+ CacheError,+ ValidationError,+ TransformError,+ ):+ err = exc_type("problem", details={"kind": exc_type.__name__})+ assert isinstance(err, HeadroomError)+ assert str(err) == f"problem (kind={exc_type.__name__})"diff --git a/tests/test_graph.py b/tests/test_graph.pyindex 693f7dd13..4eca7c4f5 100644--- a/tests/test_graph.py+++ b/tests/test_graph.py@@ -1,352 +1,352 @@-from __future__ import annotations--import io-import json-import subprocess-import tarfile-from pathlib import Path-from types import ModuleType, SimpleNamespace--import pytest--from headroom.graph import installer, watcher---def _build_archive(member_name: str = installer.CBM_BIN_NAME) -> bytes:- payload = io.BytesIO()- with tarfile.open(fileobj=payload, mode="w:gz") as tar:- data = b"#!/bin/sh\necho version\n"- info = tarfile.TarInfo(name=member_name)- info.size = len(data)- tar.addfile(info, io.BytesIO(data))- return payload.getvalue()---class FakeResponse:- def __init__(self, data: bytes) -> None:- self._data = data-- def __enter__(self):- return self-- def __exit__(self, exc_type, exc, tb) -> None:- return None-- def read(self) -> bytes:- return self._data--- ("system", "machine", "expected"),- [- ("Darwin", "arm64", "darwin-arm64"),- ("Darwin", "x86_64", "darwin-amd64"),- ("Linux", "aarch64", "linux-arm64"),- ("Linux", "arm64", "linux-arm64"),- ("Linux", "x86_64", "linux-amd64"),- ("Windows", "AMD64", "windows-amd64"),- ],-)-def test_detect_platform_variants(monkeypatch, system: str, machine: str, expected: str) -> None:- monkeypatch.setattr(installer.platform, "system", lambda: system)- monkeypatch.setattr(installer.platform, "machine", lambda: machine)- assert installer._detect_platform() == expected---def test_detect_platform_rejects_unknown_system(monkeypatch) -> None:- monkeypatch.setattr(installer.platform, "system", lambda: "Solaris")- monkeypatch.setattr(installer.platform, "machine", lambda: "sparc")- with pytest.raises(RuntimeError, match="Unsupported platform"):- installer._detect_platform()---def test_get_cbm_path_prefers_path_then_install_dir(monkeypatch, tmp_path: Path) -> None:- on_path = tmp_path / "on-path"- installed = tmp_path / installer.CBM_BIN_NAME- installed.write_text("bin")- monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)- monkeypatch.setattr(installer.shutil, "which", lambda name: str(on_path))- assert installer.get_cbm_path() == on_path-- monkeypatch.setattr(installer.shutil, "which", lambda name: None)- assert installer.get_cbm_path() == installed-- installed.unlink()- assert installer.get_cbm_path() is None---def test_download_cbm_success_and_verification_paths(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)- monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")- monkeypatch.setattr(- installer, "urlopen", lambda url, timeout=60: FakeResponse(_build_archive())- )-- run_calls: list[list[str]] = []-- def fake_run(command, **kwargs):- run_calls.append(command)- return SimpleNamespace(returncode=1, stdout="")-- monkeypatch.setattr("subprocess.run", fake_run)- path = installer.download_cbm(version="v1.2.3")- assert path == tmp_path / installer.CBM_BIN_NAME- assert path.exists()- assert run_calls == [[str(path), "--version"]]-- monkeypatch.setattr(- "subprocess.run", lambda *args, **kwargs: (_ for _ in ()).throw(RuntimeError("boom"))- )- assert installer.download_cbm(version="v1.2.3") == path-- monkeypatch.setattr(- "subprocess.run",- lambda *args, **kwargs: SimpleNamespace(returncode=0, stdout="cbm v1.2.3\n"),- )- assert installer.download_cbm(version="v1.2.3") == path---def test_download_cbm_invalid_url_download_failure_and_extract_errors(- monkeypatch, tmp_path: Path-) -> None:- monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)- monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")-- monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "ftp://example.test/releases")- with pytest.raises(RuntimeError, match="Invalid URL"):- installer.download_cbm()-- monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "https://example.test/releases")- monkeypatch.setattr(- installer,- "urlopen",- lambda url, timeout=60: (_ for _ in ()).throw(OSError("network down")),- )- with pytest.raises(RuntimeError, match="Failed to download codebase-memory-mcp"):- installer.download_cbm()-- monkeypatch.setattr(- installer,- "urlopen",- lambda url, timeout=60: FakeResponse(_build_archive("some/other-binary")),- )- with pytest.raises(RuntimeError, match="binary not found in archive"):- installer.download_cbm()-- monkeypatch.setattr(installer, "urlopen", lambda url, timeout=60: FakeResponse(b"not a tar"))- with pytest.raises(RuntimeError, match="Failed to extract archive"):- installer.download_cbm()---def test_ensure_cbm_uses_existing_or_returns_none_on_failure(monkeypatch, tmp_path: Path) -> None:- existing = tmp_path / installer.CBM_BIN_NAME- monkeypatch.setattr(installer, "get_cbm_path", lambda: existing)- assert installer.ensure_cbm() == existing-- monkeypatch.setattr(installer, "get_cbm_path", lambda: None)- monkeypatch.setattr(- installer, "download_cbm", lambda: (_ for _ in ()).throw(RuntimeError("nope"))- )- assert installer.ensure_cbm() is None---def test_code_graph_watcher_init_start_stop_and_event_filtering(- monkeypatch, tmp_path: Path-) -> None:- monkeypatch.setattr("headroom.graph.installer.get_cbm_path", lambda: tmp_path / "cbm")- graph_watcher = watcher.CodeGraphWatcher(tmp_path)- assert graph_watcher.cbm_binary == str(tmp_path / "cbm")-- explicit = watcher.CodeGraphWatcher(tmp_path, cbm_binary="explicit-cbm")- assert explicit.cbm_binary == "explicit-cbm"-- missing = watcher.CodeGraphWatcher(tmp_path, cbm_binary=None)- missing.cbm_binary = None- assert missing.start() is False-- watchdog_mod = ModuleType("watchdog")- events_mod = ModuleType("watchdog.events")- observers_mod = ModuleType("watchdog.observers")-- class FileSystemEventHandler:- pass-- class FakeObserver:- def __init__(self) -> None:- self.scheduled = None- self.daemon = False- self.started = False- self.stopped = False- self.join_timeout = None-- def schedule(self, handler, project_dir, recursive=True) -> None:- self.scheduled = (handler, project_dir, recursive)-- def start(self) -> None:- self.started = True-- def stop(self) -> None:- self.stopped = True-- def join(self, timeout=None) -> None:- self.join_timeout = timeout-- events_mod.FileSystemEventHandler = FileSystemEventHandler- observers_mod.Observer = FakeObserver- monkeypatch.setitem(__import__("sys").modules, "watchdog", watchdog_mod)- monkeypatch.setitem(__import__("sys").modules, "watchdog.events", events_mod)- monkeypatch.setitem(__import__("sys").modules, "watchdog.observers", observers_mod)-- scheduled: list[str] = []- monkeypatch.setattr(graph_watcher, "_schedule_reindex", lambda: scheduled.append("reindex"))-- assert graph_watcher.start() is True- handler, project_dir, recursive = graph_watcher._observer.scheduled- assert project_dir == str(tmp_path)- assert recursive is True-- handler.on_any_event(SimpleNamespace(src_path=""))- handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / ".git" / "config")))- handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "notes.txt")))- handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / ".temp.py")))- handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "main.py~")))- handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "main.py")))- assert scheduled == ["reindex"]-- class FakeTimer:- def __init__(self) -> None:- self.cancelled = False-- def cancel(self) -> None:- self.cancelled = True-- timer = FakeTimer()- graph_watcher._debounce_timer = timer- graph_watcher._reindex_count = 1- graph_watcher.stop()- assert timer.cancelled is True- assert graph_watcher._observer is None---def test_code_graph_watcher_start_returns_false_without_watchdog(- monkeypatch, tmp_path: Path-) -> None:- graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")-- import builtins-- real_import = builtins.__import__-- def fake_import(name, globals=None, locals=None, fromlist=(), level=0):- if name.startswith("watchdog"):- raise ImportError("missing watchdog")- return real_import(name, globals, locals, fromlist, level)-- monkeypatch.setattr(builtins, "__import__", fake_import)- assert graph_watcher.start() is False---def test_code_graph_watcher_stop_handles_missing_timer_and_observer_methods(tmp_path: Path) -> None:- graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")- graph_watcher._observer = object()- graph_watcher.stop()- assert graph_watcher._observer is None-- graph_watcher.stop()---def test_schedule_reindex_replaces_existing_timer(monkeypatch, tmp_path: Path) -> None:- graph_watcher = watcher.CodeGraphWatcher(tmp_path, debounce_seconds=3.5, cbm_binary="cbm")- timers: list[FakeTimer] = []-- class FakeTimer:- def __init__(self, interval, callback) -> None:- self.interval = interval- self.callback = callback- self.daemon = False- self.started = False- self.cancelled = False- timers.append(self)-- def start(self) -> None:- self.started = True-- def cancel(self) -> None:- self.cancelled = True-- monkeypatch.setattr(watcher.threading, "Timer", FakeTimer)- graph_watcher._schedule_reindex()- graph_watcher._schedule_reindex()-- assert len(timers) == 2- assert timers[0].cancelled is True- assert timers[1].started is True- assert timers[1].daemon is True- assert timers[1].interval == 3.5---def test_do_reindex_success_failure_timeout_and_stats(monkeypatch, tmp_path: Path) -> None:- graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")- graph_watcher._running = True-- monotonic_values = iter([10.0, 10.4, 20.0, 20.5, 30.0, 30.5, 40.0, 40.5])- monkeypatch.setattr(watcher.time, "monotonic", lambda: next(monotonic_values))- monkeypatch.setattr(watcher.time, "time", lambda: 1234.0)-- run_calls: list[list[str]] = []-- def success_run(command, **kwargs):- run_calls.append(command)- return SimpleNamespace(returncode=0, stderr="indexed\nchanged=7 files\n")-- monkeypatch.setattr(watcher.subprocess, "run", success_run)- graph_watcher._do_reindex()- assert graph_watcher.stats == {- "running": True,- "project_dir": str(tmp_path),- "reindex_count": 1,- "last_reindex": 1234.0,- "debounce_seconds": 2.0,- }- assert run_calls == [- ["cbm", "cli", "index_repository", json.dumps({"repo_path": str(tmp_path), "mode": "fast"})]- ]-- monkeypatch.setattr(- watcher.subprocess,- "run",- lambda command, **kwargs: SimpleNamespace(returncode=1, stderr="failed"),- )- graph_watcher._do_reindex()- assert graph_watcher._reindex_count == 2-- monkeypatch.setattr(- watcher.subprocess,- "run",- lambda command, **kwargs: SimpleNamespace(- returncode=0, stderr="indexed\nchanged=oops\nstill running\n"- ),- )- graph_watcher._do_reindex()- assert graph_watcher._reindex_count == 3-- monkeypatch.setattr(- watcher.subprocess,- "run",- lambda command, **kwargs: (_ for _ in ()).throw(subprocess.TimeoutExpired(command, 30)),- )- graph_watcher._do_reindex()-- monkeypatch.setattr(- watcher.subprocess,- "run",- lambda command, **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),- )- graph_watcher._do_reindex()-- graph_watcher._running = False- graph_watcher._do_reindex()-- graph_watcher._running = True- graph_watcher.cbm_binary = None- graph_watcher._do_reindex()+from __future__ import annotations++import io+import json+import subprocess+import tarfile+from pathlib import Path+from types import ModuleType, SimpleNamespace++import pytest++from headroom.graph import installer, watcher+++def _build_archive(member_name: str = installer.CBM_BIN_NAME) -> bytes:+ payload = io.BytesIO()+ with tarfile.open(fileobj=payload, mode="w:gz") as tar:+ data = b"#!/bin/sh\necho version\n"+ info = tarfile.TarInfo(name=member_name)+ info.size = len(data)+ tar.addfile(info, io.BytesIO(data))+ return payload.getvalue()+++class FakeResponse:+ def __init__(self, data: bytes) -> None:+ self._data = data++ def __enter__(self):+ return self++ def __exit__(self, exc_type, exc, tb) -> None:+ return None++ def read(self) -> bytes:+ return self._data+++ ("system", "machine", "expected"),+ [+ ("Darwin", "arm64", "darwin-arm64"),+ ("Darwin", "x86_64", "darwin-amd64"),+ ("Linux", "aarch64", "linux-arm64"),+ ("Linux", "arm64", "linux-arm64"),+ ("Linux", "x86_64", "linux-amd64"),+ ("Windows", "AMD64", "windows-amd64"),+ ],+)+def test_detect_platform_variants(monkeypatch, system: str, machine: str, expected: str) -> None:+ monkeypatch.setattr(installer.platform, "system", lambda: system)+ monkeypatch.setattr(installer.platform, "machine", lambda: machine)+ assert installer._detect_platform() == expected+++def test_detect_platform_rejects_unknown_system(monkeypatch) -> None:+ monkeypatch.setattr(installer.platform, "system", lambda: "Solaris")+ monkeypatch.setattr(installer.platform, "machine", lambda: "sparc")+ with pytest.raises(RuntimeError, match="Unsupported platform"):+ installer._detect_platform()+++def test_get_cbm_path_prefers_path_then_install_dir(monkeypatch, tmp_path: Path) -> None:+ on_path = tmp_path / "on-path"+ installed = tmp_path / installer.CBM_BIN_NAME+ installed.write_text("bin")+ monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)+ monkeypatch.setattr(installer.shutil, "which", lambda name: str(on_path))+ assert installer.get_cbm_path() == on_path++ monkeypatch.setattr(installer.shutil, "which", lambda name: None)+ assert installer.get_cbm_path() == installed++ installed.unlink()+ assert installer.get_cbm_path() is None+++def test_download_cbm_success_and_verification_paths(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)+ monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")+ monkeypatch.setattr(+ installer, "urlopen", lambda url, timeout=60: FakeResponse(_build_archive())+ )++ run_calls: list[list[str]] = []++ def fake_run(command, **kwargs):+ run_calls.append(command)+ return SimpleNamespace(returncode=1, stdout="")++ monkeypatch.setattr("subprocess.run", fake_run)+ path = installer.download_cbm(version="v1.2.3")+ assert path == tmp_path / installer.CBM_BIN_NAME+ assert path.exists()+ assert run_calls == [[str(path), "--version"]]++ monkeypatch.setattr(+ "subprocess.run", lambda *args, **kwargs: (_ for _ in ()).throw(RuntimeError("boom"))+ )+ assert installer.download_cbm(version="v1.2.3") == path++ monkeypatch.setattr(+ "subprocess.run",+ lambda *args, **kwargs: SimpleNamespace(returncode=0, stdout="cbm v1.2.3\n"),+ )+ assert installer.download_cbm(version="v1.2.3") == path+++def test_download_cbm_invalid_url_download_failure_and_extract_errors(+ monkeypatch, tmp_path: Path+) -> None:+ monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)+ monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")++ monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "ftp://example.test/releases")+ with pytest.raises(RuntimeError, match="Invalid URL"):+ installer.download_cbm()++ monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "https://example.test/releases")+ monkeypatch.setattr(+ installer,+ "urlopen",+ lambda url, timeout=60: (_ for _ in ()).throw(OSError("network down")),+ )+ with pytest.raises(RuntimeError, match="Failed to download codebase-memory-mcp"):+ installer.download_cbm()++ monkeypatch.setattr(+ installer,+ "urlopen",+ lambda url, timeout=60: FakeResponse(_build_archive("some/other-binary")),+ )+ with pytest.raises(RuntimeError, match="binary not found in archive"):+ installer.download_cbm()++ monkeypatch.setattr(installer, "urlopen", lambda url, timeout=60: FakeResponse(b"not a tar"))+ with pytest.raises(RuntimeError, match="Failed to extract archive"):+ installer.download_cbm()+++def test_ensure_cbm_uses_existing_or_returns_none_on_failure(monkeypatch, tmp_path: Path) -> None:+ existing = tmp_path / installer.CBM_BIN_NAME+ monkeypatch.setattr(installer, "get_cbm_path", lambda: existing)+ assert installer.ensure_cbm() == existing++ monkeypatch.setattr(installer, "get_cbm_path", lambda: None)+ monkeypatch.setattr(+ installer, "download_cbm", lambda: (_ for _ in ()).throw(RuntimeError("nope"))+ )+ assert installer.ensure_cbm() is None+++def test_code_graph_watcher_init_start_stop_and_event_filtering(+ monkeypatch, tmp_path: Path+) -> None:+ monkeypatch.setattr("headroom.graph.installer.get_cbm_path", lambda: tmp_path / "cbm")+ graph_watcher = watcher.CodeGraphWatcher(tmp_path)+ assert graph_watcher.cbm_binary == str(tmp_path / "cbm")++ explicit = watcher.CodeGraphWatcher(tmp_path, cbm_binary="explicit-cbm")+ assert explicit.cbm_binary == "explicit-cbm"++ missing = watcher.CodeGraphWatcher(tmp_path, cbm_binary=None)+ missing.cbm_binary = None+ assert missing.start() is False++ watchdog_mod = ModuleType("watchdog")+ events_mod = ModuleType("watchdog.events")+ observers_mod = ModuleType("watchdog.observers")++ class FileSystemEventHandler:+ pass++ class FakeObserver:+ def __init__(self) -> None:+ self.scheduled = None+ self.daemon = False+ self.started = False+ self.stopped = False+ self.join_timeout = None++ def schedule(self, handler, project_dir, recursive=True) -> None:+ self.scheduled = (handler, project_dir, recursive)++ def start(self) -> None:+ self.started = True++ def stop(self) -> None:+ self.stopped = True++ def join(self, timeout=None) -> None:+ self.join_timeout = timeout++ events_mod.FileSystemEventHandler = FileSystemEventHandler+ observers_mod.Observer = FakeObserver+ monkeypatch.setitem(__import__("sys").modules, "watchdog", watchdog_mod)+ monkeypatch.setitem(__import__("sys").modules, "watchdog.events", events_mod)+ monkeypatch.setitem(__import__("sys").modules, "watchdog.observers", observers_mod)++ scheduled: list[str] = []+ monkeypatch.setattr(graph_watcher, "_schedule_reindex", lambda: scheduled.append("reindex"))++ assert graph_watcher.start() is True+ handler, project_dir, recursive = graph_watcher._observer.scheduled+ assert project_dir == str(tmp_path)+ assert recursive is True++ handler.on_any_event(SimpleNamespace(src_path=""))+ handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / ".git" / "config")))+ handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "notes.txt")))+ handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / ".temp.py")))+ handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "main.py~")))+ handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "main.py")))+ assert scheduled == ["reindex"]++ class FakeTimer:+ def __init__(self) -> None:+ self.cancelled = False++ def cancel(self) -> None:+ self.cancelled = True++ timer = FakeTimer()+ graph_watcher._debounce_timer = timer+ graph_watcher._reindex_count = 1+ graph_watcher.stop()+ assert timer.cancelled is True+ assert graph_watcher._observer is None+++def test_code_graph_watcher_start_returns_false_without_watchdog(+ monkeypatch, tmp_path: Path+) -> None:+ graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")++ import builtins++ real_import = builtins.__import__++ def fake_import(name, globals=None, locals=None, fromlist=(), level=0):+ if name.startswith("watchdog"):+ raise ImportError("missing watchdog")+ return real_import(name, globals, locals, fromlist, level)++ monkeypatch.setattr(builtins, "__import__", fake_import)+ assert graph_watcher.start() is False+++def test_code_graph_watcher_stop_handles_missing_timer_and_observer_methods(tmp_path: Path) -> None:+ graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")+ graph_watcher._observer = object()+ graph_watcher.stop()+ assert graph_watcher._observer is None++ graph_watcher.stop()+++def test_schedule_reindex_replaces_existing_timer(monkeypatch, tmp_path: Path) -> None:+ graph_watcher = watcher.CodeGraphWatcher(tmp_path, debounce_seconds=3.5, cbm_binary="cbm")+ timers: list[FakeTimer] = []++ class FakeTimer:+ def __init__(self, interval, callback) -> None:+ self.interval = interval+ self.callback = callback+ self.daemon = False+ self.started = False+ self.cancelled = False+ timers.append(self)++ def start(self) -> None:+ self.started = True++ def cancel(self) -> None:+ self.cancelled = True++ monkeypatch.setattr(watcher.threading, "Timer", FakeTimer)+ graph_watcher._schedule_reindex()+ graph_watcher._schedule_reindex()++ assert len(timers) == 2+ assert timers[0].cancelled is True+ assert timers[1].started is True+ assert timers[1].daemon is True+ assert timers[1].interval == 3.5+++def test_do_reindex_success_failure_timeout_and_stats(monkeypatch, tmp_path: Path) -> None:+ graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")+ graph_watcher._running = True++ monotonic_values = iter([10.0, 10.4, 20.0, 20.5, 30.0, 30.5, 40.0, 40.5])+ monkeypatch.setattr(watcher.time, "monotonic", lambda: next(monotonic_values))+ monkeypatch.setattr(watcher.time, "time", lambda: 1234.0)++ run_calls: list[list[str]] = []++ def success_run(command, **kwargs):+ run_calls.append(command)+ return SimpleNamespace(returncode=0, stderr="indexed\nchanged=7 files\n")++ monkeypatch.setattr(watcher.subprocess, "run", success_run)+ graph_watcher._do_reindex()+ assert graph_watcher.stats == {+ "running": True,+ "project_dir": str(tmp_path),+ "reindex_count": 1,+ "last_reindex": 1234.0,+ "debounce_seconds": 2.0,+ }+ assert run_calls == [+ ["cbm", "cli", "index_repository", json.dumps({"repo_path": str(tmp_path), "mode": "fast"})]+ ]++ monkeypatch.setattr(+ watcher.subprocess,+ "run",+ lambda command, **kwargs: SimpleNamespace(returncode=1, stderr="failed"),+ )+ graph_watcher._do_reindex()+ assert graph_watcher._reindex_count == 2++ monkeypatch.setattr(+ watcher.subprocess,+ "run",+ lambda command, **kwargs: SimpleNamespace(+ returncode=0, stderr="indexed\nchanged=oops\nstill running\n"+ ),+ )+ graph_watcher._do_reindex()+ assert graph_watcher._reindex_count == 3++ monkeypatch.setattr(+ watcher.subprocess,+ "run",+ lambda command, **kwargs: (_ for _ in ()).throw(subprocess.TimeoutExpired(command, 30)),+ )+ graph_watcher._do_reindex()++ monkeypatch.setattr(+ watcher.subprocess,+ "run",+ lambda command, **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),+ )+ graph_watcher._do_reindex()++ graph_watcher._running = False+ graph_watcher._do_reindex()++ graph_watcher._running = True+ graph_watcher.cbm_binary = None+ graph_watcher._do_reindex()diff --git a/tests/test_install/test_paths.py b/tests/test_install/test_paths.pyindex 0d44734f2..821dfc15a 100644--- a/tests/test_install/test_paths.py+++ b/tests/test_install/test_paths.py@@ -1,68 +1,68 @@-from __future__ import annotations--from pathlib import Path--import click-import pytest--from headroom.install import paths as install_paths---def test_validate_profile_name_accepts_and_rejects_values() -> None:- assert install_paths.validate_profile_name("good.profile-1_2") == "good.profile-1_2"-- for value in (".", "..", "bad/name", "bad space", ""):- with pytest.raises(click.ClickException, match="Invalid profile name"):- install_paths.validate_profile_name(value)---def test_profile_and_artifact_paths(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr("headroom.install.paths._paths.deploy_root", lambda: tmp_path / "deploy")-- assert install_paths.deploy_root() == tmp_path / "deploy"- assert install_paths.profile_root("demo") == tmp_path / "deploy" / "demo"- assert install_paths.manifest_path("demo") == tmp_path / "deploy" / "demo" / "manifest.json"- assert install_paths.log_path("demo") == tmp_path / "deploy" / "demo" / "runner.log"- assert install_paths.pid_path("demo") == tmp_path / "deploy" / "demo" / "runner.pid"- assert (- install_paths.unix_run_script_path("demo")- == tmp_path / "deploy" / "demo" / "run-headroom.sh"- )- assert install_paths.unix_ensure_script_path("demo") == (- tmp_path / "deploy" / "demo" / "ensure-headroom.sh"- )- assert install_paths.windows_run_script_path("demo") == (- tmp_path / "deploy" / "demo" / "run-headroom.ps1"- )- assert install_paths.windows_run_cmd_path("demo") == (- tmp_path / "deploy" / "demo" / "run-headroom.cmd"- )- assert install_paths.windows_ensure_script_path("demo") == (- tmp_path / "deploy" / "demo" / "ensure-headroom.ps1"- )- assert install_paths.windows_ensure_cmd_path("demo") == (- tmp_path / "deploy" / "demo" / "ensure-headroom.cmd"- )---def test_env_target_and_config_paths(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr(Path, "home", lambda: tmp_path)- monkeypatch.setattr("headroom.install.paths.sys.platform", "linux")-- assert install_paths.unix_user_env_targets() == [- tmp_path / ".bashrc",- tmp_path / ".zshrc",- tmp_path / ".profile",- ]- assert install_paths.unix_system_env_targets() == [Path("/etc/profile.d/headroom.sh")]-- monkeypatch.setattr("headroom.install.paths.sys.platform", "darwin")- assert install_paths.unix_system_env_targets() == [- Path("/etc/profile"),- Path("/etc/zprofile"),- Path("/etc/bashrc"),- ]-- assert install_paths.claude_settings_path() == tmp_path / ".claude" / "settings.json"- assert install_paths.codex_config_path() == tmp_path / ".codex" / "config.toml"- assert install_paths.openclaw_config_path() == tmp_path / ".openclaw" / "openclaw.json"+from __future__ import annotations++from pathlib import Path++import click+import pytest++from headroom.install import paths as install_paths+++def test_validate_profile_name_accepts_and_rejects_values() -> None:+ assert install_paths.validate_profile_name("good.profile-1_2") == "good.profile-1_2"++ for value in (".", "..", "bad/name", "bad space", ""):+ with pytest.raises(click.ClickException, match="Invalid profile name"):+ install_paths.validate_profile_name(value)+++def test_profile_and_artifact_paths(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr("headroom.install.paths._paths.deploy_root", lambda: tmp_path / "deploy")++ assert install_paths.deploy_root() == tmp_path / "deploy"+ assert install_paths.profile_root("demo") == tmp_path / "deploy" / "demo"+ assert install_paths.manifest_path("demo") == tmp_path / "deploy" / "demo" / "manifest.json"+ assert install_paths.log_path("demo") == tmp_path / "deploy" / "demo" / "runner.log"+ assert install_paths.pid_path("demo") == tmp_path / "deploy" / "demo" / "runner.pid"+ assert (+ install_paths.unix_run_script_path("demo")+ == tmp_path / "deploy" / "demo" / "run-headroom.sh"+ )+ assert install_paths.unix_ensure_script_path("demo") == (+ tmp_path / "deploy" / "demo" / "ensure-headroom.sh"+ )+ assert install_paths.windows_run_script_path("demo") == (+ tmp_path / "deploy" / "demo" / "run-headroom.ps1"+ )+ assert install_paths.windows_run_cmd_path("demo") == (+ tmp_path / "deploy" / "demo" / "run-headroom.cmd"+ )+ assert install_paths.windows_ensure_script_path("demo") == (+ tmp_path / "deploy" / "demo" / "ensure-headroom.ps1"+ )+ assert install_paths.windows_ensure_cmd_path("demo") == (+ tmp_path / "deploy" / "demo" / "ensure-headroom.cmd"+ )+++def test_env_target_and_config_paths(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ monkeypatch.setattr("headroom.install.paths.sys.platform", "linux")++ assert install_paths.unix_user_env_targets() == [+ tmp_path / ".bashrc",+ tmp_path / ".zshrc",+ tmp_path / ".profile",+ ]+ assert install_paths.unix_system_env_targets() == [Path("/etc/profile.d/headroom.sh")]++ monkeypatch.setattr("headroom.install.paths.sys.platform", "darwin")+ assert install_paths.unix_system_env_targets() == [+ Path("/etc/profile"),+ Path("/etc/zprofile"),+ Path("/etc/bashrc"),+ ]++ assert install_paths.claude_settings_path() == tmp_path / ".claude" / "settings.json"+ assert install_paths.codex_config_path() == tmp_path / ".codex" / "config.toml"+ assert install_paths.openclaw_config_path() == tmp_path / ".openclaw" / "openclaw.json"diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.pyindex 481c63265..e50cf29b0 100644--- a/tests/test_install/test_runtime.py+++ b/tests/test_install/test_runtime.py@@ -1,468 +1,468 @@-from __future__ import annotations--import signal-from pathlib import Path--from headroom.install.models import DeploymentManifest, InstallPreset-from headroom.install.runtime import (- _clear_pid,- _deployment_env,- _mount_source,- _read_pid,- _runtime_env,- _write_pid,- build_runtime_command,- resolve_headroom_command,- run_foreground,- runtime_status,- start_detached_agent,- start_persistent_docker,- stop_runtime,- wait_ready,-)---def test_build_runtime_command_for_docker_includes_deployment_env(- monkeypatch, tmp_path: Path-) -> None:- monkeypatch.setattr(Path, "home", lambda: tmp_path)- manifest = DeploymentManifest(- profile="default",- preset="persistent-docker",- runtime_kind="docker",- supervisor_kind="none",- scope="user",- provider_mode="manual",- targets=["claude"],- port=8787,- host="127.0.0.1",- backend="anthropic",- image="ghcr.io/chopratejas/headroom:latest",- base_env={"HEADROOM_PORT": "8787"},- proxy_args=["--host", "127.0.0.1", "--port", "8787"],- )-- command = build_runtime_command(manifest)-- joined = " ".join(command)- assert command[:3] == ["docker", "run", "--rm"]- assert "HEADROOM_DEPLOYMENT_PROFILE=default" in joined- assert "HEADROOM_DEPLOYMENT_PRESET=persistent-docker" in joined- assert "127.0.0.1:8787:8787" in joined- assert "ghcr.io/chopratejas/headroom:latest" in command- # Canonical Headroom filesystem contract (issue #175) forwarded into- # the container.- assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in command- assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in command---def test_build_runtime_command_for_docker_matches_wrapper_parity(- monkeypatch, tmp_path: Path-) -> None:- monkeypatch.setattr(Path, "home", lambda: tmp_path)- monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")- monkeypatch.setenv("OPENAI_API_KEY", "test-openai")- manifest = DeploymentManifest(- profile="default",- preset="persistent-docker",- runtime_kind="docker",- supervisor_kind="none",- scope="user",- provider_mode="manual",- targets=["claude"],- port=8787,- host="127.0.0.1",- backend="anthropic",- image="ghcr.io/chopratejas/headroom:latest",- base_env={"HEADROOM_PORT": "8787"},- proxy_args=["--host", "127.0.0.1", "--port", "8787"],- )-- command = build_runtime_command(manifest)-- assert (tmp_path / ".headroom").is_dir()- assert (tmp_path / ".claude").is_dir()- assert (tmp_path / ".codex").is_dir()- assert (tmp_path / ".gemini").is_dir()- assert "--env" in command- joined = " ".join(command)- assert "ANTHROPIC_API_KEY" in joined- assert "OPENAI_API_KEY" in joined---def test_resolve_headroom_command_prefers_headroom_binary(monkeypatch) -> None:- monkeypatch.setattr(- "shutil.which", lambda name: "/usr/bin/headroom" if name == "headroom" else None- )-- assert resolve_headroom_command() == ["/usr/bin/headroom"]---def test_resolve_headroom_command_falls_back_to_python_module(monkeypatch) -> None:- monkeypatch.setattr("shutil.which", lambda name: None)- monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")- assert resolve_headroom_command() == ["/usr/bin/python", "-m", "headroom.cli"]---def test_runtime_env_and_mount_source(monkeypatch) -> None:- manifest = DeploymentManifest(- profile="default",- preset="persistent-service",- runtime_kind="python",- supervisor_kind="service",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- base_env={"EXTRA": "1"},- )- monkeypatch.setattr("headroom.install.runtime.os.environ", {"BASE": "x"})-- assert _deployment_env(manifest) == {- "HEADROOM_DEPLOYMENT_PROFILE": "default",- "HEADROOM_DEPLOYMENT_PRESET": "persistent-service",- "HEADROOM_DEPLOYMENT_RUNTIME": "python",- "HEADROOM_DEPLOYMENT_SUPERVISOR": "service",- "HEADROOM_DEPLOYMENT_SCOPE": "user",- }- assert _runtime_env(manifest)["BASE"] == "x"- assert _runtime_env(manifest)["EXTRA"] == "1"- assert _runtime_env(manifest)["HEADROOM_DEPLOYMENT_PROFILE"] == "default"-- monkeypatch.setattr("headroom.install.runtime.sys.platform", "win32")- assert _mount_source("C:\\Users\\me", ".headroom") == "C:\\Users\\me\\.headroom"- monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")- assert _mount_source("/home/me", ".headroom") == "/home/me/.headroom"---def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")- manifest = DeploymentManifest(- profile="default",- preset="persistent-service",- runtime_kind="python",- supervisor_kind="service",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- proxy_args=["--host", "127.0.0.1", "--port", "8787"],- )- assert build_runtime_command(manifest) == [- "/usr/bin/python",- "-m",- "headroom.cli",- "proxy",- "--host",- "127.0.0.1",- "--port",- "8787",- ]-- monkeypatch.setattr(Path, "home", lambda: tmp_path)- monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")- monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False)- monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False)- docker_manifest = DeploymentManifest(- profile="default",- preset="persistent-docker",- runtime_kind="docker",- supervisor_kind="none",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- image="ghcr.io/chopratejas/headroom:latest",- base_env={"HEADROOM_PORT": "8787"},- proxy_args=["--host", "127.0.0.1", "--port", "8787"],- )- command = build_runtime_command(docker_manifest)- assert "--user" in command- assert "1000:1001" in command---def test_read_pid_handles_invalid_content(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr(Path, "home", lambda: tmp_path)- pid_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.pid"- pid_file.parent.mkdir(parents=True)- pid_file.write_text("not-a-pid", encoding="utf-8")-- assert _read_pid("default") is None- _clear_pid("default")- assert not pid_file.exists()---def test_write_read_and_clear_pid(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr(Path, "home", lambda: tmp_path)- _write_pid("default", 456)- assert _read_pid("default") == 456- _clear_pid("default")- assert _read_pid("default") is None---def test_run_foreground_and_detached_helpers(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr(Path, "home", lambda: tmp_path)- monkeypatch.setattr(- "headroom.install.runtime.build_runtime_command", lambda manifest: ["headroom", "proxy"]- )- monkeypatch.setattr("headroom.install.runtime._runtime_env", lambda manifest: {"ENV": "1"})- signal_calls: list[int] = []- monkeypatch.setattr(- "headroom.install.runtime.signal.signal", lambda sig, fn: signal_calls.append(sig)- )-- class FakeProc:- def __init__(self, returncode: int = 0, pid: int = 321) -> None:- self.returncode = returncode- self.pid = pid- self.terminated = False- self.killed = False-- def wait(self, timeout: int | None = None) -> int:- return self.returncode-- def poll(self):- return None if not self.terminated else self.returncode-- def terminate(self) -> None:- self.terminated = True-- def kill(self) -> None:- self.killed = True-- fake_proc = FakeProc(returncode=7)- popen_calls: list[tuple[list[str], dict]] = []-- def fake_popen(command: list[str], **kwargs):- popen_calls.append((command, kwargs))- return fake_proc-- monkeypatch.setattr("headroom.install.runtime.subprocess.Popen", fake_popen)- manifest = DeploymentManifest(- profile="default",- preset="persistent-service",- runtime_kind="python",- supervisor_kind="service",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- )- assert run_foreground(manifest) == 7- assert popen_calls[0][0] == ["headroom", "proxy"]- assert signal.SIGINT in signal_calls- assert signal.SIGTERM in signal_calls- assert _read_pid("default") is None-- monkeypatch.setattr("headroom.install.runtime.resolve_headroom_command", lambda: ["headroom"])- monkeypatch.setattr("headroom.install.runtime.sys.platform", "win32")- monkeypatch.setattr("headroom.install.runtime.subprocess.DETACHED_PROCESS", 1, raising=False)- monkeypatch.setattr(- "headroom.install.runtime.subprocess.CREATE_NEW_PROCESS_GROUP", 2, raising=False- )- fake_proc_nt = FakeProc()- monkeypatch.setattr(- "headroom.install.runtime.subprocess.Popen", lambda command, **kwargs: fake_proc_nt- )- assert start_detached_agent("demo") is fake_proc_nt-- monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")- fake_proc_posix = FakeProc()- monkeypatch.setattr(- "headroom.install.runtime.subprocess.Popen", lambda command, **kwargs: fake_proc_posix- )- assert start_detached_agent("demo") is fake_proc_posix---def test_start_stop_wait_and_runtime_status_branches(monkeypatch, tmp_path: Path) -> None:- calls: list[list[str]] = []- monkeypatch.setattr(- "headroom.install.runtime.subprocess.run",- lambda command, **kwargs: calls.append(command) or type("Result", (), {"stdout": ""})(),- )- monkeypatch.setattr(- "headroom.install.runtime.build_runtime_command",- lambda manifest: [- "docker",- "run",- "--rm",- "--name",- "demo",- "-p",- "127.0.0.1:8787:8787",- "image",- ],- )- manifest = DeploymentManifest(- profile="default",- preset=InstallPreset.PERSISTENT_DOCKER.value,- runtime_kind="docker",- supervisor_kind="none",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- container_name="headroom-default",- )- start_persistent_docker(manifest)- assert calls == [- ["docker", "rm", "-f", "headroom-default"],- [- "docker",- "run",- "-d",- "--restart",- "unless-stopped",- "--name",- "headroom-default",- "-p",- "127.0.0.1:8787:8787",- "image",- ],- ]-- monkeypatch.setattr(Path, "home", lambda: tmp_path)- python_manifest = DeploymentManifest(- profile="default",- preset="persistent-service",- runtime_kind="python",- supervisor_kind="service",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- health_url="http://127.0.0.1:8787/health",- )- _write_pid("default", 123)- killed: list[tuple[int, int]] = []- monkeypatch.setattr(- "headroom.install.runtime.os.kill", lambda pid, sig: killed.append((pid, sig))- )- stop_runtime(python_manifest)- assert killed == [(123, signal.SIGTERM)]- assert _read_pid("default") is None-- _write_pid("default", 124)- monkeypatch.setattr(- "headroom.install.runtime.os.kill",- lambda pid, sig: (_ for _ in ()).throw(OSError("gone")),- )- stop_runtime(python_manifest)- assert _read_pid("default") is None-- probe_results = iter([False, False, True])- sleeps: list[int] = []- monkeypatch.setattr("headroom.install.runtime.probe_ready", lambda url: next(probe_results))- monkeypatch.setattr(- "headroom.install.runtime.time.sleep", lambda seconds: sleeps.append(seconds)- )- assert wait_ready(python_manifest, timeout_seconds=3) is True- assert sleeps == [1, 1]-- monkeypatch.setattr("headroom.install.runtime.probe_ready", lambda url: False)- sleeps.clear()- assert wait_ready(python_manifest, timeout_seconds=2) is False- assert sleeps == [1, 1]-- class Result:- def __init__(self, stdout: str = "") -> None:- self.stdout = stdout-- monkeypatch.setattr(- "headroom.install.runtime.subprocess.run",- lambda command, **kwargs: Result(stdout=""),- )- assert runtime_status(manifest) == "stopped"- assert runtime_status(python_manifest) == "stopped"-- _write_pid("default", 125)- monkeypatch.setattr(- "headroom.install.runtime.os.kill", lambda pid, sig: (_ for _ in ()).throw(OSError())- )- assert runtime_status(python_manifest) == "stopped"---def test_stop_runtime_for_docker_stops_and_removes_container(monkeypatch) -> None:- calls: list[list[str]] = []- manifest = DeploymentManifest(- profile="default",- preset="persistent-docker",- runtime_kind="docker",- supervisor_kind="none",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- container_name="headroom-default",- )-- monkeypatch.setattr(- "headroom.install.runtime.subprocess.run",- lambda command, **kwargs: calls.append(command),- )-- stop_runtime(manifest)-- assert calls == [- ["docker", "stop", "headroom-default"],- ["docker", "rm", "-f", "headroom-default"],- ]---def test_runtime_status_reads_container_and_pid_state(monkeypatch, tmp_path: Path) -> None:- docker_manifest = DeploymentManifest(- profile="default",- preset="persistent-docker",- runtime_kind="docker",- supervisor_kind="none",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- container_name="headroom-default",- )-- class Result:- def __init__(self, stdout: str = "") -> None:- self.stdout = stdout-- monkeypatch.setattr(- "headroom.install.runtime.subprocess.run",- lambda command, **kwargs: Result(stdout="headroom-default\n"),- )- assert runtime_status(docker_manifest) == "running"-- monkeypatch.setattr(Path, "home", lambda: tmp_path)- pid_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.pid"- pid_file.parent.mkdir(parents=True)- pid_file.write_text("123", encoding="utf-8")- monkeypatch.setattr("headroom.install.runtime.os.kill", lambda pid, sig: None)- python_manifest = DeploymentManifest(- profile="default",- preset="persistent-service",- runtime_kind="python",- supervisor_kind="service",- scope="user",- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- )- assert runtime_status(python_manifest) == "running"+from __future__ import annotations++import signal+from pathlib import Path++from headroom.install.models import DeploymentManifest, InstallPreset+from headroom.install.runtime import (+ _clear_pid,+ _deployment_env,+ _mount_source,+ _read_pid,+ _runtime_env,+ _write_pid,+ build_runtime_command,+ resolve_headroom_command,+ run_foreground,+ runtime_status,+ start_detached_agent,+ start_persistent_docker,+ stop_runtime,+ wait_ready,+)+++def test_build_runtime_command_for_docker_includes_deployment_env(+ monkeypatch, tmp_path: Path+) -> None:+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ manifest = DeploymentManifest(+ profile="default",+ preset="persistent-docker",+ runtime_kind="docker",+ supervisor_kind="none",+ scope="user",+ provider_mode="manual",+ targets=["claude"],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ image="ghcr.io/chopratejas/headroom:latest",+ base_env={"HEADROOM_PORT": "8787"},+ proxy_args=["--host", "127.0.0.1", "--port", "8787"],+ )++ command = build_runtime_command(manifest)++ joined = " ".join(command)+ assert command[:3] == ["docker", "run", "--rm"]+ assert "HEADROOM_DEPLOYMENT_PROFILE=default" in joined+ assert "HEADROOM_DEPLOYMENT_PRESET=persistent-docker" in joined+ assert "127.0.0.1:8787:8787" in joined+ assert "ghcr.io/chopratejas/headroom:latest" in command+ # Canonical Headroom filesystem contract (issue #175) forwarded into+ # the container.+ assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in command+ assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in command+++def test_build_runtime_command_for_docker_matches_wrapper_parity(+ monkeypatch, tmp_path: Path+) -> None:+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")+ monkeypatch.setenv("OPENAI_API_KEY", "test-openai")+ manifest = DeploymentManifest(+ profile="default",+ preset="persistent-docker",+ runtime_kind="docker",+ supervisor_kind="none",+ scope="user",+ provider_mode="manual",+ targets=["claude"],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ image="ghcr.io/chopratejas/headroom:latest",+ base_env={"HEADROOM_PORT": "8787"},+ proxy_args=["--host", "127.0.0.1", "--port", "8787"],+ )++ command = build_runtime_command(manifest)++ assert (tmp_path / ".headroom").is_dir()+ assert (tmp_path / ".claude").is_dir()+ assert (tmp_path / ".codex").is_dir()+ assert (tmp_path / ".gemini").is_dir()+ assert "--env" in command+ joined = " ".join(command)+ assert "ANTHROPIC_API_KEY" in joined+ assert "OPENAI_API_KEY" in joined+++def test_resolve_headroom_command_prefers_headroom_binary(monkeypatch) -> None:+ monkeypatch.setattr(+ "shutil.which", lambda name: "/usr/bin/headroom" if name == "headroom" else None+ )++ assert resolve_headroom_command() == ["/usr/bin/headroom"]+++def test_resolve_headroom_command_falls_back_to_python_module(monkeypatch) -> None:+ monkeypatch.setattr("shutil.which", lambda name: None)+ monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")+ assert resolve_headroom_command() == ["/usr/bin/python", "-m", "headroom.cli"]+++def test_runtime_env_and_mount_source(monkeypatch) -> None:+ manifest = DeploymentManifest(+ profile="default",+ preset="persistent-service",+ runtime_kind="python",+ supervisor_kind="service",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ base_env={"EXTRA": "1"},+ )+ monkeypatch.setattr("headroom.install.runtime.os.environ", {"BASE": "x"})++ assert _deployment_env(manifest) == {+ "HEADROOM_DEPLOYMENT_PROFILE": "default",+ "HEADROOM_DEPLOYMENT_PRESET": "persistent-service",+ "HEADROOM_DEPLOYMENT_RUNTIME": "python",+ "HEADROOM_DEPLOYMENT_SUPERVISOR": "service",+ "HEADROOM_DEPLOYMENT_SCOPE": "user",+ }+ assert _runtime_env(manifest)["BASE"] == "x"+ assert _runtime_env(manifest)["EXTRA"] == "1"+ assert _runtime_env(manifest)["HEADROOM_DEPLOYMENT_PROFILE"] == "default"++ monkeypatch.setattr("headroom.install.runtime.sys.platform", "win32")+ assert _mount_source("C:\\Users\\me", ".headroom") == "C:\\Users\\me\\.headroom"+ monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")+ assert _mount_source("/home/me", ".headroom") == "/home/me/.headroom"+++def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")+ manifest = DeploymentManifest(+ profile="default",+ preset="persistent-service",+ runtime_kind="python",+ supervisor_kind="service",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ proxy_args=["--host", "127.0.0.1", "--port", "8787"],+ )+ assert build_runtime_command(manifest) == [+ "/usr/bin/python",+ "-m",+ "headroom.cli",+ "proxy",+ "--host",+ "127.0.0.1",+ "--port",+ "8787",+ ]++ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")+ monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False)+ monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False)+ docker_manifest = DeploymentManifest(+ profile="default",+ preset="persistent-docker",+ runtime_kind="docker",+ supervisor_kind="none",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ image="ghcr.io/chopratejas/headroom:latest",+ base_env={"HEADROOM_PORT": "8787"},+ proxy_args=["--host", "127.0.0.1", "--port", "8787"],+ )+ command = build_runtime_command(docker_manifest)+ assert "--user" in command+ assert "1000:1001" in command+++def test_read_pid_handles_invalid_content(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ pid_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.pid"+ pid_file.parent.mkdir(parents=True)+ pid_file.write_text("not-a-pid", encoding="utf-8")++ assert _read_pid("default") is None+ _clear_pid("default")+ assert not pid_file.exists()+++def test_write_read_and_clear_pid(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ _write_pid("default", 456)+ assert _read_pid("default") == 456+ _clear_pid("default")+ assert _read_pid("default") is None+++def test_run_foreground_and_detached_helpers(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ monkeypatch.setattr(+ "headroom.install.runtime.build_runtime_command", lambda manifest: ["headroom", "proxy"]+ )+ monkeypatch.setattr("headroom.install.runtime._runtime_env", lambda manifest: {"ENV": "1"})+ signal_calls: list[int] = []+ monkeypatch.setattr(+ "headroom.install.runtime.signal.signal", lambda sig, fn: signal_calls.append(sig)+ )++ class FakeProc:+ def __init__(self, returncode: int = 0, pid: int = 321) -> None:+ self.returncode = returncode+ self.pid = pid+ self.terminated = False+ self.killed = False++ def wait(self, timeout: int | None = None) -> int:+ return self.returncode++ def poll(self):+ return None if not self.terminated else self.returncode++ def terminate(self) -> None:+ self.terminated = True++ def kill(self) -> None:+ self.killed = True++ fake_proc = FakeProc(returncode=7)+ popen_calls: list[tuple[list[str], dict]] = []++ def fake_popen(command: list[str], **kwargs):+ popen_calls.append((command, kwargs))+ return fake_proc++ monkeypatch.setattr("headroom.install.runtime.subprocess.Popen", fake_popen)+ manifest = DeploymentManifest(+ profile="default",+ preset="persistent-service",+ runtime_kind="python",+ supervisor_kind="service",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ )+ assert run_foreground(manifest) == 7+ assert popen_calls[0][0] == ["headroom", "proxy"]+ assert signal.SIGINT in signal_calls+ assert signal.SIGTERM in signal_calls+ assert _read_pid("default") is None++ monkeypatch.setattr("headroom.install.runtime.resolve_headroom_command", lambda: ["headroom"])+ monkeypatch.setattr("headroom.install.runtime.sys.platform", "win32")+ monkeypatch.setattr("headroom.install.runtime.subprocess.DETACHED_PROCESS", 1, raising=False)+ monkeypatch.setattr(+ "headroom.install.runtime.subprocess.CREATE_NEW_PROCESS_GROUP", 2, raising=False+ )+ fake_proc_nt = FakeProc()+ monkeypatch.setattr(+ "headroom.install.runtime.subprocess.Popen", lambda command, **kwargs: fake_proc_nt+ )+ assert start_detached_agent("demo") is fake_proc_nt++ monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")+ fake_proc_posix = FakeProc()+ monkeypatch.setattr(+ "headroom.install.runtime.subprocess.Popen", lambda command, **kwargs: fake_proc_posix+ )+ assert start_detached_agent("demo") is fake_proc_posix+++def test_start_stop_wait_and_runtime_status_branches(monkeypatch, tmp_path: Path) -> None:+ calls: list[list[str]] = []+ monkeypatch.setattr(+ "headroom.install.runtime.subprocess.run",+ lambda command, **kwargs: calls.append(command) or type("Result", (), {"stdout": ""})(),+ )+ monkeypatch.setattr(+ "headroom.install.runtime.build_runtime_command",+ lambda manifest: [+ "docker",+ "run",+ "--rm",+ "--name",+ "demo",+ "-p",+ "127.0.0.1:8787:8787",+ "image",+ ],+ )+ manifest = DeploymentManifest(+ profile="default",+ preset=InstallPreset.PERSISTENT_DOCKER.value,+ runtime_kind="docker",+ supervisor_kind="none",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ container_name="headroom-default",+ )+ start_persistent_docker(manifest)+ assert calls == [+ ["docker", "rm", "-f", "headroom-default"],+ [+ "docker",+ "run",+ "-d",+ "--restart",+ "unless-stopped",+ "--name",+ "headroom-default",+ "-p",+ "127.0.0.1:8787:8787",+ "image",+ ],+ ]++ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ python_manifest = DeploymentManifest(+ profile="default",+ preset="persistent-service",+ runtime_kind="python",+ supervisor_kind="service",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ health_url="http://127.0.0.1:8787/health",+ )+ _write_pid("default", 123)+ killed: list[tuple[int, int]] = []+ monkeypatch.setattr(+ "headroom.install.runtime.os.kill", lambda pid, sig: killed.append((pid, sig))+ )+ stop_runtime(python_manifest)+ assert killed == [(123, signal.SIGTERM)]+ assert _read_pid("default") is None++ _write_pid("default", 124)+ monkeypatch.setattr(+ "headroom.install.runtime.os.kill",+ lambda pid, sig: (_ for _ in ()).throw(OSError("gone")),+ )+ stop_runtime(python_manifest)+ assert _read_pid("default") is None++ probe_results = iter([False, False, True])+ sleeps: list[int] = []+ monkeypatch.setattr("headroom.install.runtime.probe_ready", lambda url: next(probe_results))+ monkeypatch.setattr(+ "headroom.install.runtime.time.sleep", lambda seconds: sleeps.append(seconds)+ )+ assert wait_ready(python_manifest, timeout_seconds=3) is True+ assert sleeps == [1, 1]++ monkeypatch.setattr("headroom.install.runtime.probe_ready", lambda url: False)+ sleeps.clear()+ assert wait_ready(python_manifest, timeout_seconds=2) is False+ assert sleeps == [1, 1]++ class Result:+ def __init__(self, stdout: str = "") -> None:+ self.stdout = stdout++ monkeypatch.setattr(+ "headroom.install.runtime.subprocess.run",+ lambda command, **kwargs: Result(stdout=""),+ )+ assert runtime_status(manifest) == "stopped"+ assert runtime_status(python_manifest) == "stopped"++ _write_pid("default", 125)+ monkeypatch.setattr(+ "headroom.install.runtime.os.kill", lambda pid, sig: (_ for _ in ()).throw(OSError())+ )+ assert runtime_status(python_manifest) == "stopped"+++def test_stop_runtime_for_docker_stops_and_removes_container(monkeypatch) -> None:+ calls: list[list[str]] = []+ manifest = DeploymentManifest(+ profile="default",+ preset="persistent-docker",+ runtime_kind="docker",+ supervisor_kind="none",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ container_name="headroom-default",+ )++ monkeypatch.setattr(+ "headroom.install.runtime.subprocess.run",+ lambda command, **kwargs: calls.append(command),+ )++ stop_runtime(manifest)++ assert calls == [+ ["docker", "stop", "headroom-default"],+ ["docker", "rm", "-f", "headroom-default"],+ ]+++def test_runtime_status_reads_container_and_pid_state(monkeypatch, tmp_path: Path) -> None:+ docker_manifest = DeploymentManifest(+ profile="default",+ preset="persistent-docker",+ runtime_kind="docker",+ supervisor_kind="none",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ container_name="headroom-default",+ )++ class Result:+ def __init__(self, stdout: str = "") -> None:+ self.stdout = stdout++ monkeypatch.setattr(+ "headroom.install.runtime.subprocess.run",+ lambda command, **kwargs: Result(stdout="headroom-default\n"),+ )+ assert runtime_status(docker_manifest) == "running"++ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ pid_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.pid"+ pid_file.parent.mkdir(parents=True)+ pid_file.write_text("123", encoding="utf-8")+ monkeypatch.setattr("headroom.install.runtime.os.kill", lambda pid, sig: None)+ python_manifest = DeploymentManifest(+ profile="default",+ preset="persistent-service",+ runtime_kind="python",+ supervisor_kind="service",+ scope="user",+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ )+ assert runtime_status(python_manifest) == "running"diff --git a/tests/test_install/test_supervisors.py b/tests/test_install/test_supervisors.pyindex 80af6c957..c77c9b2d6 100644--- a/tests/test_install/test_supervisors.py+++ b/tests/test_install/test_supervisors.py@@ -1,471 +1,471 @@-from __future__ import annotations--from pathlib import Path--import click-import pytest--from headroom.install.models import DeploymentManifest, SupervisorKind-from headroom.install.supervisors import (- _command_for_script,- _linux_service_unit,- _linux_task_spec,- _macos_launchd_plist,- _render_unix_runner,- _render_windows_runner,- install_supervisor,- remove_supervisor,- render_runner_scripts,- start_supervisor,- stop_supervisor,-)---def _manifest(- *, profile: str = "default", scope: str = "user", supervisor: str = "service"-) -> DeploymentManifest:- return DeploymentManifest(- profile=profile,- preset="persistent-service",- runtime_kind="python",- supervisor_kind=supervisor,- scope=scope,- provider_mode="manual",- targets=[],- port=8787,- host="127.0.0.1",- backend="anthropic",- service_name=f"headroom-{profile}",- )---def test_linux_service_unit_uses_user_systemd_path(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr(Path, "home", lambda: tmp_path)- manifest = _manifest()-- unit_path, content = _linux_service_unit(manifest, tmp_path / "run-headroom.sh")-- assert unit_path == tmp_path / ".config" / "systemd" / "user" / "headroom-default.service"- assert "ExecStart=" + str(tmp_path / "run-headroom.sh") in content- assert "Restart=on-failure" in content---def test_command_for_script_and_unix_runner(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr(- "headroom.install.supervisors.resolve_headroom_command",- lambda: ["python", "-m", "headroom"],- )-- assert _command_for_script("install", "agent", "run") == [- "python",- "-m",- "headroom",- "install",- "agent",- "run",- ]-- record = _render_unix_runner(- tmp_path / "scripts" / "run-headroom.sh", ["headroom", "run", "--flag"]- )- assert record.kind == "script"- content = Path(record.path).read_text(encoding="utf-8")- assert content.startswith("#!/usr/bin/env bash")- assert "exec headroom run --flag" in content---def test_linux_task_spec_for_user_scope_includes_crontab_markers(tmp_path: Path) -> None:- manifest = _manifest(profile="smoke", supervisor=SupervisorKind.TASK.value)-- cron_path, content = _linux_task_spec(manifest, tmp_path / "ensure-headroom.sh")-- assert cron_path is None- assert "# >>> headroom smoke >>>" in content- assert "# <<< headroom smoke <<<" in content- assert "@reboot" in content- assert "*/5 * * * *" in content---def test_macos_launchd_plist_switches_between_keepalive_and_interval(- monkeypatch, tmp_path: Path-) -> None:- monkeypatch.setattr(Path, "home", lambda: tmp_path)-- service_manifest = _manifest(supervisor=SupervisorKind.SERVICE.value)- service_path, service_content = _macos_launchd_plist(- service_manifest, tmp_path / "run-headroom.sh"- )- assert service_path == tmp_path / "Library" / "LaunchAgents" / "com.headroom.default.plist"- assert "<key>KeepAlive</key>" in service_content- assert "<key>StartInterval</key>" not in service_content-- task_manifest = _manifest(profile="tasky", supervisor=SupervisorKind.TASK.value)- task_path, task_content = _macos_launchd_plist(- task_manifest, tmp_path / "ensure-headroom.sh", interval=300- )- assert task_path == tmp_path / "Library" / "LaunchAgents" / "com.headroom.tasky.plist"- assert "<key>StartInterval</key>" in task_content- assert "<integer>300</integer>" in task_content---def test_render_windows_runner_writes_ps1_and_cmd_wrappers(tmp_path: Path) -> None:- ps1_path = tmp_path / "run-headroom.ps1"- cmd_path = tmp_path / "run-headroom.cmd"-- records = _render_windows_runner(- ps1_path,- cmd_path,- ["C:\\Program Files\\Python\\python.exe", "headroom", "install", "agent", "run"],- )-- assert [record.path for record in records] == [str(ps1_path), str(cmd_path)]- ps1_content = ps1_path.read_text(encoding="utf-8")- cmd_content = cmd_path.read_text(encoding="utf-8")- assert '& "C:\\Program Files\\Python\\python.exe" headroom install agent run' in ps1_content- assert (- 'powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0run-headroom.ps1" %*'- in cmd_content- )---def test_render_runner_scripts_writes_unix_scripts(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")- monkeypatch.setattr(- "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]- )- monkeypatch.setattr(Path, "home", lambda: tmp_path)- manifest = _manifest()-- records = render_runner_scripts(manifest)-- assert {record.path.split("\\")[-1].split("/")[-1] for record in records} == {- "run-headroom.sh",- "ensure-headroom.sh",- }---def test_render_runner_scripts_writes_windows_scripts(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")- monkeypatch.setattr(- "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom.exe"]- )- monkeypatch.setattr(- "headroom.install.supervisors.windows_run_script_path",- lambda profile: tmp_path / "run-headroom.ps1",- )- monkeypatch.setattr(- "headroom.install.supervisors.windows_run_cmd_path",- lambda profile: tmp_path / "run-headroom.cmd",- )- monkeypatch.setattr(- "headroom.install.supervisors.windows_ensure_script_path",- lambda profile: tmp_path / "ensure-headroom.ps1",- )- monkeypatch.setattr(- "headroom.install.supervisors.windows_ensure_cmd_path",- lambda profile: tmp_path / "ensure-headroom.cmd",- )-- records = render_runner_scripts(_manifest(profile="win"))-- assert [Path(record.path).name for record in records] == [- "run-headroom.ps1",- "run-headroom.cmd",- "ensure-headroom.ps1",- "ensure-headroom.cmd",- ]---def test_install_supervisor_none_returns_runner_records(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")- monkeypatch.setattr(- "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]- )- monkeypatch.setattr(Path, "home", lambda: tmp_path)- manifest = _manifest(supervisor=SupervisorKind.NONE.value)-- records = install_supervisor(manifest)-- assert len(records) == 2- assert all(record.kind == "script" for record in records)---def test_start_and_stop_supervisor_use_linux_systemctl(monkeypatch) -> None:- calls: list[list[str]] = []- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")- monkeypatch.setattr(- "headroom.install.supervisors.subprocess.run",- lambda command, **kwargs: calls.append(command),- )- manifest = _manifest()-- start_supervisor(manifest)- stop_supervisor(manifest)-- assert calls == [- ["systemctl", "--user", "restart", "headroom-default"],- ["systemctl", "--user", "stop", "headroom-default"],- ]---def test_install_supervisor_linux_service_and_tasks(monkeypatch, tmp_path: Path) -> None:- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")- run_script = tmp_path / "run-headroom.sh"- ensure_script = tmp_path / "ensure-headroom.sh"- monkeypatch.setattr(- "headroom.install.supervisors.render_runner_scripts",- lambda manifest: [- type("Record", (), {"kind": "script", "path": run_script.as_posix()})(),- type("Record", (), {"kind": "script", "path": ensure_script.as_posix()})(),- ],- )- unit_path = tmp_path / "headroom-default.service"- monkeypatch.setattr(- "headroom.install.supervisors._linux_service_unit",- lambda manifest, script: (unit_path, "UNIT"),- )- calls: list[tuple[list[str], dict]] = []-- def fake_run(command: list[str], **kwargs):- calls.append((command, kwargs))- return type("Result", (), {"returncode": 0, "stdout": "# old cron\n"})()-- monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)-- service_records = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- assert unit_path.read_text(encoding="utf-8") == "UNIT"- assert ["systemctl", "--user", "daemon-reload"] in [call[0] for call in calls]- assert ["systemctl", "--user", "enable", "headroom-default"] in [call[0] for call in calls]- assert service_records[-1].kind == "service-unit"-- cron_path = tmp_path / "headroom-system"- monkeypatch.setattr(- "headroom.install.supervisors._linux_task_spec",- lambda manifest, script: (cron_path, "@reboot root ensure\n"),- )- system_task_records = install_supervisor(- _manifest(profile="system-task", scope="system", supervisor=SupervisorKind.TASK.value)- )- assert cron_path.read_text(encoding="utf-8") == "@reboot root ensure\n"- assert system_task_records[-1].kind == "cron"-- monkeypatch.setattr(- "headroom.install.supervisors._linux_task_spec",- lambda manifest, script: (- None,- "# >>> headroom default >>>\n@reboot ensure\n# <<< headroom default <<<\n",- ),- )- user_task_records = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))- assert user_task_records[-1].kind == "crontab"- assert calls[-1][0] == ["crontab", "-"]- assert "@reboot ensure" in calls[-1][1]["input"]---def test_install_supervisor_darwin_windows_and_unsupported(monkeypatch, tmp_path: Path) -> None:- run_script = tmp_path / "run-headroom.sh"- ensure_script = tmp_path / "ensure-headroom.sh"- monkeypatch.setattr(- "headroom.install.supervisors.render_runner_scripts",- lambda manifest: [- type("Record", (), {"kind": "script", "path": run_script.as_posix()})(),- type("Record", (), {"kind": "script", "path": ensure_script.as_posix()})(),- ],- )- calls: list[list[str]] = []- monkeypatch.setattr(- "headroom.install.supervisors.subprocess.run",- lambda command, **kwargs: calls.append(command),- )- monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 123, raising=False)-- plist_path = tmp_path / "com.headroom.default.plist"- monkeypatch.setattr(- "headroom.install.supervisors._macos_launchd_plist",- lambda manifest, script, interval=None: (plist_path, f"plist-{interval}"),- )- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")- service_records = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- task_records = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))- assert plist_path.read_text(encoding="utf-8") == "plist-300"- assert service_records[-1].kind == "plist"- assert task_records[-1].kind == "plist"- assert ["launchctl", "bootstrap", "gui/123", str(plist_path)] in calls-- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")- monkeypatch.setattr(- "headroom.install.supervisors.windows_run_cmd_path",- lambda profile: Path(f"C:\\tmp\\{profile}\\run-headroom.cmd"),- )- monkeypatch.setattr(- "headroom.install.supervisors.windows_ensure_cmd_path",- lambda profile: Path(f"C:\\tmp\\{profile}\\ensure-headroom.cmd"),- )- win_service = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- win_task = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))- assert win_service[-1].kind == "windows-service"- assert win_task[-2].path.endswith("-startup")- assert [- "sc.exe",- "create",- "headroom-default",- 'binPath= cmd.exe /c "C:\\tmp\\default\\run-headroom.cmd"',- "start= auto",- ] in calls- assert [- "schtasks",- "/Create",- "/TN",- "headroom-default-health",- "/TR",- "C:\\tmp\\default\\ensure-headroom.cmd",- "/SC",- "MINUTE",- "/MO",- "5",- "/F",- ] in calls-- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")- with pytest.raises(click.ClickException, match="not supported"):- install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))---def test_start_and_stop_supervisor_darwin_windows_and_none(monkeypatch) -> None:- calls: list[list[str]] = []- monkeypatch.setattr(- "headroom.install.supervisors.subprocess.run",- lambda command, **kwargs: calls.append(command),- )- monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 77, raising=False)-- start_supervisor(_manifest(supervisor=SupervisorKind.NONE.value))- stop_supervisor(_manifest(supervisor=SupervisorKind.NONE.value))- assert calls == []-- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")- start_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- assert calls == [- ["launchctl", "kickstart", "-k", "gui/77/com.headroom.default"],- ["launchctl", "bootout", "gui/77/com.headroom.default"],- ]-- calls.clear()- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")- start_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- assert calls == [- ["sc.exe", "start", "headroom-default"],- ["sc.exe", "stop", "headroom-default"],- ]---def test_remove_supervisor_removes_user_crontab_block(monkeypatch) -> None:- calls: list[tuple[list[str], str | None]] = []- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")-- class Result:- def __init__(self, returncode: int = 0, stdout: str = "") -> None:- self.returncode = returncode- self.stdout = stdout-- def fake_run(command: list[str], **kwargs):- calls.append((command, kwargs.get("input")))- if command == ["crontab", "-l"]:- return Result(- stdout="# >>> headroom default >>>\n@reboot /tmp/ensure\n# <<< headroom default <<<\n"- )- return Result()-- monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)- manifest = _manifest(supervisor=SupervisorKind.TASK.value)-- remove_supervisor(manifest)-- assert calls[0][0] == ["crontab", "-l"]- assert calls[1][0] == ["crontab", "-"]---def test_remove_supervisor_linux_service_cron_path_and_missing_crontab(- monkeypatch, tmp_path: Path-) -> None:- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")- calls: list[list[str]] = []-- def fake_run(command: list[str], **kwargs):- calls.append(command)- return type("Result", (), {"returncode": 1, "stdout": ""})()-- monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)- unit_path = tmp_path / "headroom-default.service"- unit_path.write_text("unit", encoding="utf-8")- monkeypatch.setattr(- "headroom.install.supervisors._linux_service_unit",- lambda manifest, script: (unit_path, "unit"),- )- remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- assert not unit_path.exists()- assert ["systemctl", "--user", "disable", "--now", "headroom-default"] in calls- assert ["systemctl", "--user", "daemon-reload"] in calls-- cron_path = tmp_path / "headroom-task"- cron_path.write_text("cron", encoding="utf-8")- monkeypatch.setattr(- "headroom.install.supervisors._linux_task_spec",- lambda manifest, script: (cron_path, "cron"),- )- remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))- assert not cron_path.exists()-- monkeypatch.setattr(- "headroom.install.supervisors._linux_task_spec",- lambda manifest, script: (None, "cron"),- )- remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))- assert calls[-1] == ["crontab", "-l"]---def test_remove_supervisor_darwin_and_windows(monkeypatch, tmp_path: Path) -> None:- calls: list[list[str]] = []- monkeypatch.setattr(- "headroom.install.supervisors.subprocess.run",- lambda command, **kwargs: calls.append(command),- )- monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 55, raising=False)-- plist_path = tmp_path / "com.headroom.default.plist"- plist_path.write_text("plist", encoding="utf-8")- monkeypatch.setattr(- "headroom.install.supervisors.unix_run_script_path",- lambda profile: tmp_path / "run-headroom.sh",- )- monkeypatch.setattr(- "headroom.install.supervisors.unix_ensure_script_path",- lambda profile: tmp_path / "ensure-headroom.sh",- )- monkeypatch.setattr(- "headroom.install.supervisors._macos_launchd_plist",- lambda manifest, script, interval=None: (plist_path, "plist"),- )- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")- remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- assert not plist_path.exists()- assert calls[0] == ["launchctl", "bootout", "gui/55/com.headroom.default"]-- calls.clear()- monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")- remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))- remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))- assert calls == [- ["sc.exe", "stop", "headroom-default"],- ["sc.exe", "delete", "headroom-default"],- ["schtasks", "/Delete", "/TN", "headroom-default-startup", "/F"],- ["schtasks", "/Delete", "/TN", "headroom-default-health", "/F"],- ]+from __future__ import annotations++from pathlib import Path++import click+import pytest++from headroom.install.models import DeploymentManifest, SupervisorKind+from headroom.install.supervisors import (+ _command_for_script,+ _linux_service_unit,+ _linux_task_spec,+ _macos_launchd_plist,+ _render_unix_runner,+ _render_windows_runner,+ install_supervisor,+ remove_supervisor,+ render_runner_scripts,+ start_supervisor,+ stop_supervisor,+)+++def _manifest(+ *, profile: str = "default", scope: str = "user", supervisor: str = "service"+) -> DeploymentManifest:+ return DeploymentManifest(+ profile=profile,+ preset="persistent-service",+ runtime_kind="python",+ supervisor_kind=supervisor,+ scope=scope,+ provider_mode="manual",+ targets=[],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ service_name=f"headroom-{profile}",+ )+++def test_linux_service_unit_uses_user_systemd_path(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ manifest = _manifest()++ unit_path, content = _linux_service_unit(manifest, tmp_path / "run-headroom.sh")++ assert unit_path == tmp_path / ".config" / "systemd" / "user" / "headroom-default.service"+ assert "ExecStart=" + str(tmp_path / "run-headroom.sh") in content+ assert "Restart=on-failure" in content+++def test_command_for_script_and_unix_runner(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr(+ "headroom.install.supervisors.resolve_headroom_command",+ lambda: ["python", "-m", "headroom"],+ )++ assert _command_for_script("install", "agent", "run") == [+ "python",+ "-m",+ "headroom",+ "install",+ "agent",+ "run",+ ]++ record = _render_unix_runner(+ tmp_path / "scripts" / "run-headroom.sh", ["headroom", "run", "--flag"]+ )+ assert record.kind == "script"+ content = Path(record.path).read_text(encoding="utf-8")+ assert content.startswith("#!/usr/bin/env bash")+ assert "exec headroom run --flag" in content+++def test_linux_task_spec_for_user_scope_includes_crontab_markers(tmp_path: Path) -> None:+ manifest = _manifest(profile="smoke", supervisor=SupervisorKind.TASK.value)++ cron_path, content = _linux_task_spec(manifest, tmp_path / "ensure-headroom.sh")++ assert cron_path is None+ assert "# >>> headroom smoke >>>" in content+ assert "# <<< headroom smoke <<<" in content+ assert "@reboot" in content+ assert "*/5 * * * *" in content+++def test_macos_launchd_plist_switches_between_keepalive_and_interval(+ monkeypatch, tmp_path: Path+) -> None:+ monkeypatch.setattr(Path, "home", lambda: tmp_path)++ service_manifest = _manifest(supervisor=SupervisorKind.SERVICE.value)+ service_path, service_content = _macos_launchd_plist(+ service_manifest, tmp_path / "run-headroom.sh"+ )+ assert service_path == tmp_path / "Library" / "LaunchAgents" / "com.headroom.default.plist"+ assert "<key>KeepAlive</key>" in service_content+ assert "<key>StartInterval</key>" not in service_content++ task_manifest = _manifest(profile="tasky", supervisor=SupervisorKind.TASK.value)+ task_path, task_content = _macos_launchd_plist(+ task_manifest, tmp_path / "ensure-headroom.sh", interval=300+ )+ assert task_path == tmp_path / "Library" / "LaunchAgents" / "com.headroom.tasky.plist"+ assert "<key>StartInterval</key>" in task_content+ assert "<integer>300</integer>" in task_content+++def test_render_windows_runner_writes_ps1_and_cmd_wrappers(tmp_path: Path) -> None:+ ps1_path = tmp_path / "run-headroom.ps1"+ cmd_path = tmp_path / "run-headroom.cmd"++ records = _render_windows_runner(+ ps1_path,+ cmd_path,+ ["C:\\Program Files\\Python\\python.exe", "headroom", "install", "agent", "run"],+ )++ assert [record.path for record in records] == [str(ps1_path), str(cmd_path)]+ ps1_content = ps1_path.read_text(encoding="utf-8")+ cmd_content = cmd_path.read_text(encoding="utf-8")+ assert '& "C:\\Program Files\\Python\\python.exe" headroom install agent run' in ps1_content+ assert (+ 'powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0run-headroom.ps1" %*'+ in cmd_content+ )+++def test_render_runner_scripts_writes_unix_scripts(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")+ monkeypatch.setattr(+ "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]+ )+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ manifest = _manifest()++ records = render_runner_scripts(manifest)++ assert {record.path.split("\\")[-1].split("/")[-1] for record in records} == {+ "run-headroom.sh",+ "ensure-headroom.sh",+ }+++def test_render_runner_scripts_writes_windows_scripts(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")+ monkeypatch.setattr(+ "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom.exe"]+ )+ monkeypatch.setattr(+ "headroom.install.supervisors.windows_run_script_path",+ lambda profile: tmp_path / "run-headroom.ps1",+ )+ monkeypatch.setattr(+ "headroom.install.supervisors.windows_run_cmd_path",+ lambda profile: tmp_path / "run-headroom.cmd",+ )+ monkeypatch.setattr(+ "headroom.install.supervisors.windows_ensure_script_path",+ lambda profile: tmp_path / "ensure-headroom.ps1",+ )+ monkeypatch.setattr(+ "headroom.install.supervisors.windows_ensure_cmd_path",+ lambda profile: tmp_path / "ensure-headroom.cmd",+ )++ records = render_runner_scripts(_manifest(profile="win"))++ assert [Path(record.path).name for record in records] == [+ "run-headroom.ps1",+ "run-headroom.cmd",+ "ensure-headroom.ps1",+ "ensure-headroom.cmd",+ ]+++def test_install_supervisor_none_returns_runner_records(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")+ monkeypatch.setattr(+ "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]+ )+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ manifest = _manifest(supervisor=SupervisorKind.NONE.value)++ records = install_supervisor(manifest)++ assert len(records) == 2+ assert all(record.kind == "script" for record in records)+++def test_start_and_stop_supervisor_use_linux_systemctl(monkeypatch) -> None:+ calls: list[list[str]] = []+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")+ monkeypatch.setattr(+ "headroom.install.supervisors.subprocess.run",+ lambda command, **kwargs: calls.append(command),+ )+ manifest = _manifest()++ start_supervisor(manifest)+ stop_supervisor(manifest)++ assert calls == [+ ["systemctl", "--user", "restart", "headroom-default"],+ ["systemctl", "--user", "stop", "headroom-default"],+ ]+++def test_install_supervisor_linux_service_and_tasks(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")+ run_script = tmp_path / "run-headroom.sh"+ ensure_script = tmp_path / "ensure-headroom.sh"+ monkeypatch.setattr(+ "headroom.install.supervisors.render_runner_scripts",+ lambda manifest: [+ type("Record", (), {"kind": "script", "path": run_script.as_posix()})(),+ type("Record", (), {"kind": "script", "path": ensure_script.as_posix()})(),+ ],+ )+ unit_path = tmp_path / "headroom-default.service"+ monkeypatch.setattr(+ "headroom.install.supervisors._linux_service_unit",+ lambda manifest, script: (unit_path, "UNIT"),+ )+ calls: list[tuple[list[str], dict]] = []++ def fake_run(command: list[str], **kwargs):+ calls.append((command, kwargs))+ return type("Result", (), {"returncode": 0, "stdout": "# old cron\n"})()++ monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)++ service_records = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ assert unit_path.read_text(encoding="utf-8") == "UNIT"+ assert ["systemctl", "--user", "daemon-reload"] in [call[0] for call in calls]+ assert ["systemctl", "--user", "enable", "headroom-default"] in [call[0] for call in calls]+ assert service_records[-1].kind == "service-unit"++ cron_path = tmp_path / "headroom-system"+ monkeypatch.setattr(+ "headroom.install.supervisors._linux_task_spec",+ lambda manifest, script: (cron_path, "@reboot root ensure\n"),+ )+ system_task_records = install_supervisor(+ _manifest(profile="system-task", scope="system", supervisor=SupervisorKind.TASK.value)+ )+ assert cron_path.read_text(encoding="utf-8") == "@reboot root ensure\n"+ assert system_task_records[-1].kind == "cron"++ monkeypatch.setattr(+ "headroom.install.supervisors._linux_task_spec",+ lambda manifest, script: (+ None,+ "# >>> headroom default >>>\n@reboot ensure\n# <<< headroom default <<<\n",+ ),+ )+ user_task_records = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))+ assert user_task_records[-1].kind == "crontab"+ assert calls[-1][0] == ["crontab", "-"]+ assert "@reboot ensure" in calls[-1][1]["input"]+++def test_install_supervisor_darwin_windows_and_unsupported(monkeypatch, tmp_path: Path) -> None:+ run_script = tmp_path / "run-headroom.sh"+ ensure_script = tmp_path / "ensure-headroom.sh"+ monkeypatch.setattr(+ "headroom.install.supervisors.render_runner_scripts",+ lambda manifest: [+ type("Record", (), {"kind": "script", "path": run_script.as_posix()})(),+ type("Record", (), {"kind": "script", "path": ensure_script.as_posix()})(),+ ],+ )+ calls: list[list[str]] = []+ monkeypatch.setattr(+ "headroom.install.supervisors.subprocess.run",+ lambda command, **kwargs: calls.append(command),+ )+ monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 123, raising=False)++ plist_path = tmp_path / "com.headroom.default.plist"+ monkeypatch.setattr(+ "headroom.install.supervisors._macos_launchd_plist",+ lambda manifest, script, interval=None: (plist_path, f"plist-{interval}"),+ )+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")+ service_records = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ task_records = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))+ assert plist_path.read_text(encoding="utf-8") == "plist-300"+ assert service_records[-1].kind == "plist"+ assert task_records[-1].kind == "plist"+ assert ["launchctl", "bootstrap", "gui/123", str(plist_path)] in calls++ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")+ monkeypatch.setattr(+ "headroom.install.supervisors.windows_run_cmd_path",+ lambda profile: Path(f"C:\\tmp\\{profile}\\run-headroom.cmd"),+ )+ monkeypatch.setattr(+ "headroom.install.supervisors.windows_ensure_cmd_path",+ lambda profile: Path(f"C:\\tmp\\{profile}\\ensure-headroom.cmd"),+ )+ win_service = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ win_task = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))+ assert win_service[-1].kind == "windows-service"+ assert win_task[-2].path.endswith("-startup")+ assert [+ "sc.exe",+ "create",+ "headroom-default",+ 'binPath= cmd.exe /c "C:\\tmp\\default\\run-headroom.cmd"',+ "start= auto",+ ] in calls+ assert [+ "schtasks",+ "/Create",+ "/TN",+ "headroom-default-health",+ "/TR",+ "C:\\tmp\\default\\ensure-headroom.cmd",+ "/SC",+ "MINUTE",+ "/MO",+ "5",+ "/F",+ ] in calls++ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")+ with pytest.raises(click.ClickException, match="not supported"):+ install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+++def test_start_and_stop_supervisor_darwin_windows_and_none(monkeypatch) -> None:+ calls: list[list[str]] = []+ monkeypatch.setattr(+ "headroom.install.supervisors.subprocess.run",+ lambda command, **kwargs: calls.append(command),+ )+ monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 77, raising=False)++ start_supervisor(_manifest(supervisor=SupervisorKind.NONE.value))+ stop_supervisor(_manifest(supervisor=SupervisorKind.NONE.value))+ assert calls == []++ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")+ start_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ assert calls == [+ ["launchctl", "kickstart", "-k", "gui/77/com.headroom.default"],+ ["launchctl", "bootout", "gui/77/com.headroom.default"],+ ]++ calls.clear()+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")+ start_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ assert calls == [+ ["sc.exe", "start", "headroom-default"],+ ["sc.exe", "stop", "headroom-default"],+ ]+++def test_remove_supervisor_removes_user_crontab_block(monkeypatch) -> None:+ calls: list[tuple[list[str], str | None]] = []+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")++ class Result:+ def __init__(self, returncode: int = 0, stdout: str = "") -> None:+ self.returncode = returncode+ self.stdout = stdout++ def fake_run(command: list[str], **kwargs):+ calls.append((command, kwargs.get("input")))+ if command == ["crontab", "-l"]:+ return Result(+ stdout="# >>> headroom default >>>\n@reboot /tmp/ensure\n# <<< headroom default <<<\n"+ )+ return Result()++ monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)+ manifest = _manifest(supervisor=SupervisorKind.TASK.value)++ remove_supervisor(manifest)++ assert calls[0][0] == ["crontab", "-l"]+ assert calls[1][0] == ["crontab", "-"]+++def test_remove_supervisor_linux_service_cron_path_and_missing_crontab(+ monkeypatch, tmp_path: Path+) -> None:+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")+ calls: list[list[str]] = []++ def fake_run(command: list[str], **kwargs):+ calls.append(command)+ return type("Result", (), {"returncode": 1, "stdout": ""})()++ monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)+ unit_path = tmp_path / "headroom-default.service"+ unit_path.write_text("unit", encoding="utf-8")+ monkeypatch.setattr(+ "headroom.install.supervisors._linux_service_unit",+ lambda manifest, script: (unit_path, "unit"),+ )+ remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ assert not unit_path.exists()+ assert ["systemctl", "--user", "disable", "--now", "headroom-default"] in calls+ assert ["systemctl", "--user", "daemon-reload"] in calls++ cron_path = tmp_path / "headroom-task"+ cron_path.write_text("cron", encoding="utf-8")+ monkeypatch.setattr(+ "headroom.install.supervisors._linux_task_spec",+ lambda manifest, script: (cron_path, "cron"),+ )+ remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))+ assert not cron_path.exists()++ monkeypatch.setattr(+ "headroom.install.supervisors._linux_task_spec",+ lambda manifest, script: (None, "cron"),+ )+ remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))+ assert calls[-1] == ["crontab", "-l"]+++def test_remove_supervisor_darwin_and_windows(monkeypatch, tmp_path: Path) -> None:+ calls: list[list[str]] = []+ monkeypatch.setattr(+ "headroom.install.supervisors.subprocess.run",+ lambda command, **kwargs: calls.append(command),+ )+ monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 55, raising=False)++ plist_path = tmp_path / "com.headroom.default.plist"+ plist_path.write_text("plist", encoding="utf-8")+ monkeypatch.setattr(+ "headroom.install.supervisors.unix_run_script_path",+ lambda profile: tmp_path / "run-headroom.sh",+ )+ monkeypatch.setattr(+ "headroom.install.supervisors.unix_ensure_script_path",+ lambda profile: tmp_path / "ensure-headroom.sh",+ )+ monkeypatch.setattr(+ "headroom.install.supervisors._macos_launchd_plist",+ lambda manifest, script, interval=None: (plist_path, "plist"),+ )+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")+ remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ assert not plist_path.exists()+ assert calls[0] == ["launchctl", "bootout", "gui/55/com.headroom.default"]++ calls.clear()+ monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")+ remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))+ remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))+ assert calls == [+ ["sc.exe", "stop", "headroom-default"],+ ["sc.exe", "delete", "headroom-default"],+ ["schtasks", "/Delete", "/TN", "headroom-default-startup", "/F"],+ ["schtasks", "/Delete", "/TN", "headroom-default-health", "/F"],+ ]diff --git a/tests/test_plugin_manifests.py b/tests/test_plugin_manifests.pyindex 1a80c45d2..578f4f279 100644--- a/tests/test_plugin_manifests.py+++ b/tests/test_plugin_manifests.py@@ -1,55 +1,55 @@-from __future__ import annotations--import json-from pathlib import Path--REPO_ROOT = Path(__file__).resolve().parents[1]---def _load_json(relative_path: str) -> object:- return json.loads((REPO_ROOT / relative_path).read_text(encoding="utf-8"))---def test_marketplace_manifests_match() -> None:- assert _load_json(".claude-plugin/marketplace.json") == _load_json(- ".github/plugin/marketplace.json"- )---def test_plugin_manifests_share_core_metadata() -> None:- claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")- copilot = _load_json("plugins/headroom-agent-hooks/.github/plugin/plugin.json")- assert isinstance(claude, dict)- assert isinstance(copilot, dict)- for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):- assert claude[key] == copilot[key]- assert "hooks" not in claude- assert copilot["hooks"] == "./hooks"---def test_marketplace_entry_points_to_plugin_root() -> None:- marketplace = _load_json(".claude-plugin/marketplace.json")- assert isinstance(marketplace, dict)- plugins = marketplace["plugins"]- assert isinstance(plugins, list)- plugin = plugins[0]- assert plugin["name"] == "headroom"- plugin_root = (REPO_ROOT / plugin["source"]).resolve()- assert plugin_root.is_dir()- assert (plugin_root / ".claude-plugin" / "plugin.json").is_file()- assert (plugin_root / "hooks" / "hooks.json").is_file()---def test_plugin_metadata_points_to_upstream_repo() -> None:- expected_repo = "https://github.com/chopratejas/headroom"- marketplace = _load_json(".claude-plugin/marketplace.json")- claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")- assert isinstance(marketplace, dict)- assert isinstance(claude, dict)- plugin = marketplace["plugins"][0]- assert plugin["author"]["url"] == expected_repo- assert plugin["homepage"] == expected_repo- assert plugin["repository"] == expected_repo- assert claude["author"]["url"] == expected_repo- assert claude["homepage"] == expected_repo- assert claude["repository"] == expected_repo+from __future__ import annotations++import json+from pathlib import Path++REPO_ROOT = Path(__file__).resolve().parents[1]+++def _load_json(relative_path: str) -> object:+ return json.loads((REPO_ROOT / relative_path).read_text(encoding="utf-8"))+++def test_marketplace_manifests_match() -> None:+ assert _load_json(".claude-plugin/marketplace.json") == _load_json(+ ".github/plugin/marketplace.json"+ )+++def test_plugin_manifests_share_core_metadata() -> None:+ claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")+ copilot = _load_json("plugins/headroom-agent-hooks/.github/plugin/plugin.json")+ assert isinstance(claude, dict)+ assert isinstance(copilot, dict)+ for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):+ assert claude[key] == copilot[key]+ assert "hooks" not in claude+ assert copilot["hooks"] == "./hooks"+++def test_marketplace_entry_points_to_plugin_root() -> None:+ marketplace = _load_json(".claude-plugin/marketplace.json")+ assert isinstance(marketplace, dict)+ plugins = marketplace["plugins"]+ assert isinstance(plugins, list)+ plugin = plugins[0]+ assert plugin["name"] == "headroom"+ plugin_root = (REPO_ROOT / plugin["source"]).resolve()+ assert plugin_root.is_dir()+ assert (plugin_root / ".claude-plugin" / "plugin.json").is_file()+ assert (plugin_root / "hooks" / "hooks.json").is_file()+++def test_plugin_metadata_points_to_upstream_repo() -> None:+ expected_repo = "https://github.com/chopratejas/headroom"+ marketplace = _load_json(".claude-plugin/marketplace.json")+ claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")+ assert isinstance(marketplace, dict)+ assert isinstance(claude, dict)+ plugin = marketplace["plugins"][0]+ assert plugin["author"]["url"] == expected_repo+ assert plugin["homepage"] == expected_repo+ assert plugin["repository"] == expected_repo+ assert claude["author"]["url"] == expected_repo+ assert claude["homepage"] == expected_repo+ assert claude["repository"] == expected_repodiff --git a/tests/test_pricing.py b/tests/test_pricing.pyindex b3b94d3d1..616650cd6 100644--- a/tests/test_pricing.py+++ b/tests/test_pricing.py@@ -1,130 +1,130 @@-from __future__ import annotations--from dataclasses import FrozenInstanceError-from datetime import date, timedelta--import pytest--import headroom.pricing as pricing-from headroom.pricing.anthropic_prices import ANTHROPIC_PRICES, get_anthropic_registry-from headroom.pricing.openai_prices import OPENAI_PRICES, get_openai_registry-from headroom.pricing.registry import ModelPricing, PricingRegistry---def test_pricing_public_exports_and_provider_registries() -> None:- assert pricing.ModelPricing is ModelPricing- assert pricing.PricingRegistry is PricingRegistry- assert "get_openai_registry" in pricing.__all__- assert "get_anthropic_registry" in pricing.__all__- assert "estimate_cost" in pricing.__all__-- openai_registry = get_openai_registry()- anthropic_registry = get_anthropic_registry()- assert openai_registry.source_url == "https://openai.com/api/pricing/"- assert anthropic_registry.source_url == "https://www.anthropic.com/pricing"- assert openai_registry.prices["gpt-4o"] == OPENAI_PRICES["gpt-4o"]- assert (- anthropic_registry.prices["claude-3-5-sonnet-20241022"]- == ANTHROPIC_PRICES["claude-3-5-sonnet-20241022"]- )-- openai_registry.prices.pop("gpt-4o")- anthropic_registry.prices.pop("claude-3-5-sonnet-20241022")- assert "gpt-4o" in OPENAI_PRICES- assert "claude-3-5-sonnet-20241022" in ANTHROPIC_PRICES---def test_model_pricing_is_frozen() -> None:- model = ModelPricing(model="demo", provider="test", input_per_1m=1.5, output_per_1m=2.5)- with pytest.raises(FrozenInstanceError):- model.model = "other" # type: ignore[misc]---def test_registry_staleness_and_warning() -> None:- fresh = PricingRegistry(last_updated=date.today() - timedelta(days=30))- assert fresh.is_stale() is False- assert fresh.staleness_warning() is None-- stale = PricingRegistry(- last_updated=date.today() - timedelta(days=31),- source_url="https://example.test/pricing",- )- assert stale.is_stale() is True- assert stale.staleness_warning() == (- f"Pricing data is 31 days old (last updated: {stale.last_updated})."- " Please verify at: https://example.test/pricing"- )---def test_registry_estimate_cost_with_all_token_types() -> None:- registry = PricingRegistry(- last_updated=date.today() - timedelta(days=31),- prices={- "demo": ModelPricing(- model="demo",- provider="test",- input_per_1m=2.0,- output_per_1m=4.0,- cached_input_per_1m=1.0,- batch_input_per_1m=0.5,- batch_output_per_1m=0.25,- )- },- )-- estimate = registry.estimate_cost(- "demo",- input_tokens=1_000_000,- output_tokens=500_000,- cached_input_tokens=250_000,- batch_input_tokens=200_000,- batch_output_tokens=100_000,- )-- assert estimate.cost_usd == pytest.approx(4.375)- assert estimate.breakdown == {- "input": {"tokens": 1_000_000, "rate_per_1m": 2.0, "cost_usd": 2.0},- "output": {"tokens": 500_000, "rate_per_1m": 4.0, "cost_usd": 2.0},- "cached_input": {"tokens": 250_000, "rate_per_1m": 1.0, "cost_usd": 0.25},- "batch_input": {"tokens": 200_000, "rate_per_1m": 0.5, "cost_usd": 0.1},- "batch_output": {"tokens": 100_000, "rate_per_1m": 0.25, "cost_usd": 0.025},- }- assert estimate.pricing_date == registry.last_updated- assert estimate.is_stale is True- assert estimate.warning == (- f"Pricing data is 31 days old (last updated: {registry.last_updated})."- )---def test_registry_estimate_cost_zero_usage_returns_empty_breakdown() -> None:- registry = PricingRegistry(- last_updated=date.today(),- prices={- "demo": ModelPricing(model="demo", provider="test", input_per_1m=1.0, output_per_1m=2.0)- },- )- estimate = registry.estimate_cost("demo")- assert estimate.cost_usd == 0.0- assert estimate.breakdown == {}- assert estimate.is_stale is False- assert estimate.warning is None--- ("kwargs", "message"),- [- ({}, "Model 'missing' not found in registry"),- ({"cached_input_tokens": 1}, "Model 'demo' does not have cached input pricing"),- ({"batch_input_tokens": 1}, "Model 'demo' does not have batch input pricing"),- ({"batch_output_tokens": 1}, "Model 'demo' does not have batch output pricing"),- ],-)-def test_registry_estimate_cost_error_paths(kwargs: dict[str, int], message: str) -> None:- registry = PricingRegistry(- last_updated=date.today(),- prices={- "demo": ModelPricing(model="demo", provider="test", input_per_1m=1.0, output_per_1m=2.0)- },- )- with pytest.raises(ValueError, match=message):- registry.estimate_cost("missing" if not kwargs else "demo", **kwargs)+from __future__ import annotations++from dataclasses import FrozenInstanceError+from datetime import date, timedelta++import pytest++import headroom.pricing as pricing+from headroom.pricing.anthropic_prices import ANTHROPIC_PRICES, get_anthropic_registry+from headroom.pricing.openai_prices import OPENAI_PRICES, get_openai_registry+from headroom.pricing.registry import ModelPricing, PricingRegistry+++def test_pricing_public_exports_and_provider_registries() -> None:+ assert pricing.ModelPricing is ModelPricing+ assert pricing.PricingRegistry is PricingRegistry+ assert "get_openai_registry" in pricing.__all__+ assert "get_anthropic_registry" in pricing.__all__+ assert "estimate_cost" in pricing.__all__++ openai_registry = get_openai_registry()+ anthropic_registry = get_anthropic_registry()+ assert openai_registry.source_url == "https://openai.com/api/pricing/"+ assert anthropic_registry.source_url == "https://www.anthropic.com/pricing"+ assert openai_registry.prices["gpt-4o"] == OPENAI_PRICES["gpt-4o"]+ assert (+ anthropic_registry.prices["claude-3-5-sonnet-20241022"]+ == ANTHROPIC_PRICES["claude-3-5-sonnet-20241022"]+ )++ openai_registry.prices.pop("gpt-4o")+ anthropic_registry.prices.pop("claude-3-5-sonnet-20241022")+ assert "gpt-4o" in OPENAI_PRICES+ assert "claude-3-5-sonnet-20241022" in ANTHROPIC_PRICES+++def test_model_pricing_is_frozen() -> None:+ model = ModelPricing(model="demo", provider="test", input_per_1m=1.5, output_per_1m=2.5)+ with pytest.raises(FrozenInstanceError):+ model.model = "other" # type: ignore[misc]+++def test_registry_staleness_and_warning() -> None:+ fresh = PricingRegistry(last_updated=date.today() - timedelta(days=30))+ assert fresh.is_stale() is False+ assert fresh.staleness_warning() is None++ stale = PricingRegistry(+ last_updated=date.today() - timedelta(days=31),+ source_url="https://example.test/pricing",+ )+ assert stale.is_stale() is True+ assert stale.staleness_warning() == (+ f"Pricing data is 31 days old (last updated: {stale.last_updated})."+ " Please verify at: https://example.test/pricing"+ )+++def test_registry_estimate_cost_with_all_token_types() -> None:+ registry = PricingRegistry(+ last_updated=date.today() - timedelta(days=31),+ prices={+ "demo": ModelPricing(+ model="demo",+ provider="test",+ input_per_1m=2.0,+ output_per_1m=4.0,+ cached_input_per_1m=1.0,+ batch_input_per_1m=0.5,+ batch_output_per_1m=0.25,+ )+ },+ )++ estimate = registry.estimate_cost(+ "demo",+ input_tokens=1_000_000,+ output_tokens=500_000,+ cached_input_tokens=250_000,+ batch_input_tokens=200_000,+ batch_output_tokens=100_000,+ )++ assert estimate.cost_usd == pytest.approx(4.375)+ assert estimate.breakdown == {+ "input": {"tokens": 1_000_000, "rate_per_1m": 2.0, "cost_usd": 2.0},+ "output": {"tokens": 500_000, "rate_per_1m": 4.0, "cost_usd": 2.0},+ "cached_input": {"tokens": 250_000, "rate_per_1m": 1.0, "cost_usd": 0.25},+ "batch_input": {"tokens": 200_000, "rate_per_1m": 0.5, "cost_usd": 0.1},+ "batch_output": {"tokens": 100_000, "rate_per_1m": 0.25, "cost_usd": 0.025},+ }+ assert estimate.pricing_date == registry.last_updated+ assert estimate.is_stale is True+ assert estimate.warning == (+ f"Pricing data is 31 days old (last updated: {registry.last_updated})."+ )+++def test_registry_estimate_cost_zero_usage_returns_empty_breakdown() -> None:+ registry = PricingRegistry(+ last_updated=date.today(),+ prices={+ "demo": ModelPricing(model="demo", provider="test", input_per_1m=1.0, output_per_1m=2.0)+ },+ )+ estimate = registry.estimate_cost("demo")+ assert estimate.cost_usd == 0.0+ assert estimate.breakdown == {}+ assert estimate.is_stale is False+ assert estimate.warning is None+++ ("kwargs", "message"),+ [+ ({}, "Model 'missing' not found in registry"),+ ({"cached_input_tokens": 1}, "Model 'demo' does not have cached input pricing"),+ ({"batch_input_tokens": 1}, "Model 'demo' does not have batch input pricing"),+ ({"batch_output_tokens": 1}, "Model 'demo' does not have batch output pricing"),+ ],+)+def test_registry_estimate_cost_error_paths(kwargs: dict[str, int], message: str) -> None:+ registry = PricingRegistry(+ last_updated=date.today(),+ prices={+ "demo": ModelPricing(model="demo", provider="test", input_per_1m=1.0, output_per_1m=2.0)+ },+ )+ with pytest.raises(ValueError, match=message):+ registry.estimate_cost("missing" if not kwargs else "demo", **kwargs)diff --git a/tests/test_pricing_litellm.py b/tests/test_pricing_litellm.pyindex 1abde321d..19b0646f7 100644--- a/tests/test_pricing_litellm.py+++ b/tests/test_pricing_litellm.py@@ -1,97 +1,97 @@-from __future__ import annotations--from types import SimpleNamespace--from headroom.pricing import litellm_pricing---def test_litellm_helpers_when_dependency_is_unavailable(monkeypatch) -> None:- monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", False)- monkeypatch.setattr(litellm_pricing, "litellm", None)-- assert litellm_pricing.get_litellm_model_cost() == {}- assert litellm_pricing.get_model_pricing("gpt-4o") is None- assert litellm_pricing.estimate_cost("gpt-4o", input_tokens=1, output_tokens=1) is None- assert litellm_pricing.list_available_models() == []---def test_litellm_model_pricing_exact_match_and_defaults(monkeypatch) -> None:- fake_litellm = SimpleNamespace(- model_cost={- "gpt-4o": {- "input_cost_per_token": 0.0000025,- "output_cost_per_token": 0.00001,- "max_tokens": 128000,- }- }- )- monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)- monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)-- assert litellm_pricing.get_litellm_model_cost() == fake_litellm.model_cost- pricing = litellm_pricing.get_model_pricing("gpt-4o")- assert pricing is not None- assert pricing.model == "gpt-4o"- assert pricing.input_cost_per_1m == 2.5- assert pricing.output_cost_per_1m == 10.0- assert pricing.max_tokens == 128000- assert pricing.max_input_tokens is None- assert pricing.max_output_tokens is None- assert pricing.supports_vision is False- assert pricing.supports_function_calling is False- assert (- litellm_pricing.estimate_cost("gpt-4o", input_tokens=200_000, output_tokens=300_000) == 3.5- )- assert litellm_pricing.list_available_models() == ["gpt-4o"]---def test_litellm_model_pricing_uses_provider_prefixes(monkeypatch) -> None:- fake_litellm = SimpleNamespace(- model_cost={- "openai/gpt-4o-mini": {- "input_cost_per_token": 0.00000015,- "output_cost_per_token": 0.0000006,- "supports_vision": True,- "supports_function_calling": True,- "max_input_tokens": 64000,- "max_output_tokens": 16000,- }- }- )- monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)- monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)-- pricing = litellm_pricing.get_model_pricing("gpt-4o-mini")- assert pricing is not None- assert pricing.input_cost_per_1m == 0.15- assert pricing.output_cost_per_1m == 0.6- assert pricing.max_input_tokens == 64000- assert pricing.max_output_tokens == 16000- assert pricing.supports_vision is True- assert pricing.supports_function_calling is True---def test_litellm_model_pricing_uses_aliases_and_zero_cost_defaults(monkeypatch) -> None:- fake_litellm = SimpleNamespace(- model_cost={- "claude-sonnet-4-20250514": {- "input_cost_per_token": None,- "output_cost_per_token": None,- }- }- )- monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)- monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)-- pricing = litellm_pricing.get_model_pricing("claude-3-5-sonnet-20241022")- assert pricing is not None- assert pricing.model == "claude-3-5-sonnet-20241022"- assert pricing.input_cost_per_1m == 0- assert pricing.output_cost_per_1m == 0- assert litellm_pricing.estimate_cost("claude-3-5-sonnet-20241022", input_tokens=1) == 0---def test_litellm_model_pricing_returns_none_for_unknown_models(monkeypatch) -> None:- monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)- monkeypatch.setattr(litellm_pricing, "litellm", SimpleNamespace(model_cost={}))- assert litellm_pricing.get_model_pricing("missing") is None+from __future__ import annotations++from types import SimpleNamespace++from headroom.pricing import litellm_pricing+++def test_litellm_helpers_when_dependency_is_unavailable(monkeypatch) -> None:+ monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", False)+ monkeypatch.setattr(litellm_pricing, "litellm", None)++ assert litellm_pricing.get_litellm_model_cost() == {}+ assert litellm_pricing.get_model_pricing("gpt-4o") is None+ assert litellm_pricing.estimate_cost("gpt-4o", input_tokens=1, output_tokens=1) is None+ assert litellm_pricing.list_available_models() == []+++def test_litellm_model_pricing_exact_match_and_defaults(monkeypatch) -> None:+ fake_litellm = SimpleNamespace(+ model_cost={+ "gpt-4o": {+ "input_cost_per_token": 0.0000025,+ "output_cost_per_token": 0.00001,+ "max_tokens": 128000,+ }+ }+ )+ monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)+ monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)++ assert litellm_pricing.get_litellm_model_cost() == fake_litellm.model_cost+ pricing = litellm_pricing.get_model_pricing("gpt-4o")+ assert pricing is not None+ assert pricing.model == "gpt-4o"+ assert pricing.input_cost_per_1m == 2.5+ assert pricing.output_cost_per_1m == 10.0+ assert pricing.max_tokens == 128000+ assert pricing.max_input_tokens is None+ assert pricing.max_output_tokens is None+ assert pricing.supports_vision is False+ assert pricing.supports_function_calling is False+ assert (+ litellm_pricing.estimate_cost("gpt-4o", input_tokens=200_000, output_tokens=300_000) == 3.5+ )+ assert litellm_pricing.list_available_models() == ["gpt-4o"]+++def test_litellm_model_pricing_uses_provider_prefixes(monkeypatch) -> None:+ fake_litellm = SimpleNamespace(+ model_cost={+ "openai/gpt-4o-mini": {+ "input_cost_per_token": 0.00000015,+ "output_cost_per_token": 0.0000006,+ "supports_vision": True,+ "supports_function_calling": True,+ "max_input_tokens": 64000,+ "max_output_tokens": 16000,+ }+ }+ )+ monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)+ monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)++ pricing = litellm_pricing.get_model_pricing("gpt-4o-mini")+ assert pricing is not None+ assert pricing.input_cost_per_1m == 0.15+ assert pricing.output_cost_per_1m == 0.6+ assert pricing.max_input_tokens == 64000+ assert pricing.max_output_tokens == 16000+ assert pricing.supports_vision is True+ assert pricing.supports_function_calling is True+++def test_litellm_model_pricing_uses_aliases_and_zero_cost_defaults(monkeypatch) -> None:+ fake_litellm = SimpleNamespace(+ model_cost={+ "claude-sonnet-4-20250514": {+ "input_cost_per_token": None,+ "output_cost_per_token": None,+ }+ }+ )+ monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)+ monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)++ pricing = litellm_pricing.get_model_pricing("claude-3-5-sonnet-20241022")+ assert pricing is not None+ assert pricing.model == "claude-3-5-sonnet-20241022"+ assert pricing.input_cost_per_1m == 0+ assert pricing.output_cost_per_1m == 0+ assert litellm_pricing.estimate_cost("claude-3-5-sonnet-20241022", input_tokens=1) == 0+++def test_litellm_model_pricing_returns_none_for_unknown_models(monkeypatch) -> None:+ monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)+ monkeypatch.setattr(litellm_pricing, "litellm", SimpleNamespace(model_cost={}))+ assert litellm_pricing.get_model_pricing("missing") is Nonediff --git a/tests/test_provider_aider.py b/tests/test_provider_aider.pyindex 80626ccff..542edab62 100644--- a/tests/test_provider_aider.py+++ b/tests/test_provider_aider.py@@ -1,33 +1,33 @@-from __future__ import annotations--from headroom.providers.aider.install import build_install_env-from headroom.providers.aider.runtime import build_launch_env---def test_aider_build_launch_env_sets_proxy_urls_without_mutating_input() -> None:- # Arrange- source_env = {"EXISTING": "value"}-- # Act- env, lines = build_launch_env(port=9999, environ=source_env)-- # Assert- assert source_env == {"EXISTING": "value"}- assert env["EXISTING"] == "value"- assert env["OPENAI_API_BASE"] == "http://127.0.0.1:9999/v1"- assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999"- assert lines == [- "OPENAI_API_BASE=http://127.0.0.1:9999/v1",- "ANTHROPIC_BASE_URL=http://127.0.0.1:9999",- ]---def test_aider_build_install_env_returns_only_persistent_proxy_variables() -> None:- # Arrange / Act- env = build_install_env(port=8787, backend="ignored")-- # Assert- assert env == {- "OPENAI_API_BASE": "http://127.0.0.1:8787/v1",- "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",- }+from __future__ import annotations++from headroom.providers.aider.install import build_install_env+from headroom.providers.aider.runtime import build_launch_env+++def test_aider_build_launch_env_sets_proxy_urls_without_mutating_input() -> None:+ # Arrange+ source_env = {"EXISTING": "value"}++ # Act+ env, lines = build_launch_env(port=9999, environ=source_env)++ # Assert+ assert source_env == {"EXISTING": "value"}+ assert env["EXISTING"] == "value"+ assert env["OPENAI_API_BASE"] == "http://127.0.0.1:9999/v1"+ assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999"+ assert lines == [+ "OPENAI_API_BASE=http://127.0.0.1:9999/v1",+ "ANTHROPIC_BASE_URL=http://127.0.0.1:9999",+ ]+++def test_aider_build_install_env_returns_only_persistent_proxy_variables() -> None:+ # Arrange / Act+ env = build_install_env(port=8787, backend="ignored")++ # Assert+ assert env == {+ "OPENAI_API_BASE": "http://127.0.0.1:8787/v1",+ "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",+ }diff --git a/tests/test_provider_claude.py b/tests/test_provider_claude.pyindex 8dab41989..14ed3f55d 100644--- a/tests/test_provider_claude.py+++ b/tests/test_provider_claude.py@@ -1,9 +1,9 @@-from __future__ import annotations--from headroom.providers.claude import DEFAULT_API_URL, proxy_base_url---def test_claude_runtime_exposes_default_api_and_local_proxy_url() -> None:- # Arrange / Act / Assert- assert DEFAULT_API_URL == "https://api.anthropic.com"- assert proxy_base_url(4321) == "http://127.0.0.1:4321"+from __future__ import annotations++from headroom.providers.claude import DEFAULT_API_URL, proxy_base_url+++def test_claude_runtime_exposes_default_api_and_local_proxy_url() -> None:+ # Arrange / Act / Assert+ assert DEFAULT_API_URL == "https://api.anthropic.com"+ assert proxy_base_url(4321) == "http://127.0.0.1:4321"diff --git a/tests/test_provider_codex_runtime.py b/tests/test_provider_codex_runtime.pyindex fb41d1ba6..1c3859e74 100644--- a/tests/test_provider_codex_runtime.py+++ b/tests/test_provider_codex_runtime.py@@ -1,12 +1,12 @@-from __future__ import annotations--from headroom.providers.codex import build_launch_env, proxy_base_url---def test_codex_proxy_base_url_and_launch_env() -> None:- env, lines = build_launch_env(9999, {"OPENAI_API_KEY": "sk-test"})-- assert proxy_base_url(9999) == "http://127.0.0.1:9999/v1"- assert env["OPENAI_API_KEY"] == "sk-test"- assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/v1"- assert lines == ["OPENAI_BASE_URL=http://127.0.0.1:9999/v1"]+from __future__ import annotations++from headroom.providers.codex import build_launch_env, proxy_base_url+++def test_codex_proxy_base_url_and_launch_env() -> None:+ env, lines = build_launch_env(9999, {"OPENAI_API_KEY": "sk-test"})++ assert proxy_base_url(9999) == "http://127.0.0.1:9999/v1"+ assert env["OPENAI_API_KEY"] == "sk-test"+ assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/v1"+ assert lines == ["OPENAI_BASE_URL=http://127.0.0.1:9999/v1"]diff --git a/tests/test_provider_copilot_wrap.py b/tests/test_provider_copilot_wrap.pyindex ff0707ab3..5895ab0ac 100644--- a/tests/test_provider_copilot_wrap.py+++ b/tests/test_provider_copilot_wrap.py@@ -1,124 +1,124 @@-from __future__ import annotations--import io-import json-import urllib.error-from unittest.mock import patch--import click-import pytest--from headroom.providers.copilot.wrap import (- build_launch_env,- detect_running_proxy_backend,- model_configured,- provider_key_source,- query_proxy_config,- resolve_provider_type,- validate_configuration,-)---def test_query_proxy_config_handles_success_and_invalid_payload() -> None:- payload = io.BytesIO(json.dumps({"config": {"backend": "anyllm"}}).encode("utf-8"))- payload_missing = io.BytesIO(json.dumps({"status": "ok"}).encode("utf-8"))-- with patch("urllib.request.urlopen", return_value=payload):- assert query_proxy_config(8787) == {"backend": "anyllm"}- with patch("urllib.request.urlopen", return_value=payload_missing):- assert query_proxy_config(8787) is None- with patch("urllib.request.urlopen", side_effect=urllib.error.URLError("down")):- assert query_proxy_config(8787) is None---def test_detect_running_proxy_backend_requires_string_backend(monkeypatch) -> None:- monkeypatch.setattr(- "headroom.providers.copilot.wrap.query_proxy_config",- lambda port: {"backend": 123} if port == 8787 else None,- )-- assert detect_running_proxy_backend(8787) is None- assert detect_running_proxy_backend(9999) is None---def test_resolve_provider_type_prefers_explicit_and_env() -> None:- assert resolve_provider_type("anthropic", "openai") == "openai"- assert resolve_provider_type(None, "auto", {"HEADROOM_BACKEND": "anthropic"}) == "anthropic"- assert resolve_provider_type(None, "auto", {"HEADROOM_BACKEND": "anyllm"}) == "openai"---def test_validate_configuration_accepts_supported_combinations() -> None:- validate_configuration(provider_type="openai", wire_api="responses", backend=None)- validate_configuration(provider_type="openai", wire_api="completions", backend="anyllm")---def test_validate_configuration_rejects_invalid_combinations() -> None:- with pytest.raises(click.ClickException, match="--wire-api is only valid"):- validate_configuration(provider_type="anthropic", wire_api="responses", backend=None)-- with pytest.raises(click.ClickException, match="not supported with translated backends"):- validate_configuration(provider_type="openai", wire_api="responses", backend="anyllm")---def test_provider_key_source_and_build_launch_env_cover_anthropic_and_openai() -> None:- assert provider_key_source("anthropic") == "ANTHROPIC_API_KEY"- assert provider_key_source("openai") == "OPENAI_API_KEY"-- anthropic_env, anthropic_lines = build_launch_env(- port=8787,- provider_type="anthropic",- wire_api="responses",- environ={- "ANTHROPIC_API_KEY": "sk-ant-test",- "COPILOT_PROVIDER_WIRE_API": "stale",- },- )- openai_env, openai_lines = build_launch_env(- port=8787,- provider_type="openai",- wire_api=None,- environ={"OPENAI_API_KEY": "sk-proj-test"},- )-- assert anthropic_env["COPILOT_PROVIDER_TYPE"] == "anthropic"- assert anthropic_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787"- assert anthropic_env["COPILOT_PROVIDER_API_KEY"] == "sk-ant-test"- assert "COPILOT_PROVIDER_WIRE_API" not in anthropic_env- assert anthropic_lines == [- "COPILOT_PROVIDER_TYPE=anthropic",- "COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:8787",- ]-- assert openai_env["COPILOT_PROVIDER_TYPE"] == "openai"- assert openai_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"- assert openai_env["COPILOT_PROVIDER_WIRE_API"] == "completions"- assert openai_env["COPILOT_PROVIDER_API_KEY"] == "sk-proj-test"- assert openai_lines[-1] == "COPILOT_PROVIDER_WIRE_API=completions"---def test_build_launch_env_keeps_existing_provider_key_and_allows_missing_source_key() -> None:- existing_env, _existing_lines = build_launch_env(- port=8787,- provider_type="openai",- wire_api="responses",- environ={- "COPILOT_PROVIDER_API_KEY": "existing-provider-key",- "OPENAI_API_KEY": "sk-proj-test",- },- )- missing_env, _missing_lines = build_launch_env(- port=8787,- provider_type="openai",- wire_api="responses",- environ={},- )-- assert existing_env["COPILOT_PROVIDER_API_KEY"] == "existing-provider-key"- assert "COPILOT_PROVIDER_API_KEY" not in missing_env---def test_model_configured_detects_env_and_cli_variants() -> None:- assert model_configured((), {"COPILOT_MODEL": "gpt-4o"}) is True- assert model_configured(("--model", "gpt-4o"), {}) is True- assert model_configured(("--model=gpt-4o",), {}) is True- assert model_configured(("--other", "value"), {}) is False+from __future__ import annotations++import io+import json+import urllib.error+from unittest.mock import patch++import click+import pytest++from headroom.providers.copilot.wrap import (+ build_launch_env,+ detect_running_proxy_backend,+ model_configured,+ provider_key_source,+ query_proxy_config,+ resolve_provider_type,+ validate_configuration,+)+++def test_query_proxy_config_handles_success_and_invalid_payload() -> None:+ payload = io.BytesIO(json.dumps({"config": {"backend": "anyllm"}}).encode("utf-8"))+ payload_missing = io.BytesIO(json.dumps({"status": "ok"}).encode("utf-8"))++ with patch("urllib.request.urlopen", return_value=payload):+ assert query_proxy_config(8787) == {"backend": "anyllm"}+ with patch("urllib.request.urlopen", return_value=payload_missing):+ assert query_proxy_config(8787) is None+ with patch("urllib.request.urlopen", side_effect=urllib.error.URLError("down")):+ assert query_proxy_config(8787) is None+++def test_detect_running_proxy_backend_requires_string_backend(monkeypatch) -> None:+ monkeypatch.setattr(+ "headroom.providers.copilot.wrap.query_proxy_config",+ lambda port: {"backend": 123} if port == 8787 else None,+ )++ assert detect_running_proxy_backend(8787) is None+ assert detect_running_proxy_backend(9999) is None+++def test_resolve_provider_type_prefers_explicit_and_env() -> None:+ assert resolve_provider_type("anthropic", "openai") == "openai"+ assert resolve_provider_type(None, "auto", {"HEADROOM_BACKEND": "anthropic"}) == "anthropic"+ assert resolve_provider_type(None, "auto", {"HEADROOM_BACKEND": "anyllm"}) == "openai"+++def test_validate_configuration_accepts_supported_combinations() -> None:+ validate_configuration(provider_type="openai", wire_api="responses", backend=None)+ validate_configuration(provider_type="openai", wire_api="completions", backend="anyllm")+++def test_validate_configuration_rejects_invalid_combinations() -> None:+ with pytest.raises(click.ClickException, match="--wire-api is only valid"):+ validate_configuration(provider_type="anthropic", wire_api="responses", backend=None)++ with pytest.raises(click.ClickException, match="not supported with translated backends"):+ validate_configuration(provider_type="openai", wire_api="responses", backend="anyllm")+++def test_provider_key_source_and_build_launch_env_cover_anthropic_and_openai() -> None:+ assert provider_key_source("anthropic") == "ANTHROPIC_API_KEY"+ assert provider_key_source("openai") == "OPENAI_API_KEY"++ anthropic_env, anthropic_lines = build_launch_env(+ port=8787,+ provider_type="anthropic",+ wire_api="responses",+ environ={+ "ANTHROPIC_API_KEY": "sk-ant-test",+ "COPILOT_PROVIDER_WIRE_API": "stale",+ },+ )+ openai_env, openai_lines = build_launch_env(+ port=8787,+ provider_type="openai",+ wire_api=None,+ environ={"OPENAI_API_KEY": "sk-proj-test"},+ )++ assert anthropic_env["COPILOT_PROVIDER_TYPE"] == "anthropic"+ assert anthropic_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787"+ assert anthropic_env["COPILOT_PROVIDER_API_KEY"] == "sk-ant-test"+ assert "COPILOT_PROVIDER_WIRE_API" not in anthropic_env+ assert anthropic_lines == [+ "COPILOT_PROVIDER_TYPE=anthropic",+ "COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:8787",+ ]++ assert openai_env["COPILOT_PROVIDER_TYPE"] == "openai"+ assert openai_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"+ assert openai_env["COPILOT_PROVIDER_WIRE_API"] == "completions"+ assert openai_env["COPILOT_PROVIDER_API_KEY"] == "sk-proj-test"+ assert openai_lines[-1] == "COPILOT_PROVIDER_WIRE_API=completions"+++def test_build_launch_env_keeps_existing_provider_key_and_allows_missing_source_key() -> None:+ existing_env, _existing_lines = build_launch_env(+ port=8787,+ provider_type="openai",+ wire_api="responses",+ environ={+ "COPILOT_PROVIDER_API_KEY": "existing-provider-key",+ "OPENAI_API_KEY": "sk-proj-test",+ },+ )+ missing_env, _missing_lines = build_launch_env(+ port=8787,+ provider_type="openai",+ wire_api="responses",+ environ={},+ )++ assert existing_env["COPILOT_PROVIDER_API_KEY"] == "existing-provider-key"+ assert "COPILOT_PROVIDER_API_KEY" not in missing_env+++def test_model_configured_detects_env_and_cli_variants() -> None:+ assert model_configured((), {"COPILOT_MODEL": "gpt-4o"}) is True+ assert model_configured(("--model", "gpt-4o"), {}) is True+ assert model_configured(("--model=gpt-4o",), {}) is True+ assert model_configured(("--other", "value"), {}) is Falsediff --git a/tests/test_provider_openclaw_wrap.py b/tests/test_provider_openclaw_wrap.pyindex 2de40eba0..5025aa6e0 100644--- a/tests/test_provider_openclaw_wrap.py+++ b/tests/test_provider_openclaw_wrap.py@@ -1,119 +1,119 @@-from __future__ import annotations--from headroom.providers.openclaw.wrap import (- DEFAULT_GATEWAY_PROVIDER_IDS,- build_plugin_entry,- build_unwrap_entry,- decode_entry_json,- normalize_gateway_provider_ids,-)---def test_normalize_gateway_provider_ids_trims_deduplicates_and_defaults() -> None:- # Arrange / Act / Assert- assert normalize_gateway_provider_ids((" openai-codex ", "anthropic", "anthropic", "")) == [- "openai-codex",- "anthropic",- ]- assert normalize_gateway_provider_ids(None) == DEFAULT_GATEWAY_PROVIDER_IDS---def test_decode_entry_json_handles_empty_valid_and_invalid_payloads() -> None:- # Arrange / Act / Assert- assert decode_entry_json(None) is None- assert decode_entry_json("") is None- assert decode_entry_json('{"enabled": true}') == {"enabled": True}- assert decode_entry_json("{not-json}") == "{not-json}"---def test_build_plugin_entry_preserves_unmanaged_values_and_removes_empty_python_path() -> None:- # Arrange- existing_entry = {- "enabled": False,- "name": "headroom",- "config": {- "keep": "value",- "proxyUrl": "https://user.example",- "pythonPath": "/old/python",- },- }-- # Act- entry = build_plugin_entry(- existing_entry=existing_entry,- proxy_port=8787,- startup_timeout_ms=1500,- python_path=None,- no_auto_start=True,- gateway_provider_ids=(" openai-codex ", "anthropic", "anthropic"),- enabled=True,- )-- # Assert- assert entry["enabled"] is True- assert entry["name"] == "headroom"- assert entry["config"] == {- "keep": "value",- "proxyUrl": "https://user.example",- "proxyPort": 8787,- "autoStart": False,- "startupTimeoutMs": 1500,- "gatewayProviderIds": ["openai-codex", "anthropic"],- }---def test_build_plugin_entry_creates_managed_defaults_for_non_mapping_input() -> None:- # Arrange / Act- entry = build_plugin_entry(- existing_entry="not-a-dict",- proxy_port=9000,- startup_timeout_ms=2500,- python_path="/usr/bin/python",- no_auto_start=False,- gateway_provider_ids=None,- enabled=False,- )-- # Assert- assert entry == {- "enabled": False,- "config": {- "proxyPort": 9000,- "autoStart": True,- "startupTimeoutMs": 2500,- "gatewayProviderIds": ["openai-codex"],- "pythonPath": "/usr/bin/python",- },- }---def test_build_unwrap_entry_disables_plugin_and_removes_managed_keys_only() -> None:- # Arrange- existing_entry = {- "enabled": True,- "name": "headroom",- "config": {- "keep": "value",- "gatewayProviderIds": ["openai-codex"],- "proxyUrl": "https://managed.example",- "proxyPort": 8787,- "autoStart": True,- "startupTimeoutMs": 1000,- "pythonPath": "/usr/bin/python",- },- }-- # Act- entry = build_unwrap_entry(existing_entry)-- # Assert- assert entry == {- "enabled": False,- "name": "headroom",- "config": {"keep": "value"},- }---def test_build_unwrap_entry_handles_non_mapping_input() -> None:- # Arrange / Act / Assert- assert build_unwrap_entry("not-a-dict") == {"enabled": False, "config": {}}+from __future__ import annotations++from headroom.providers.openclaw.wrap import (+ DEFAULT_GATEWAY_PROVIDER_IDS,+ build_plugin_entry,+ build_unwrap_entry,+ decode_entry_json,+ normalize_gateway_provider_ids,+)+++def test_normalize_gateway_provider_ids_trims_deduplicates_and_defaults() -> None:+ # Arrange / Act / Assert+ assert normalize_gateway_provider_ids((" openai-codex ", "anthropic", "anthropic", "")) == [+ "openai-codex",+ "anthropic",+ ]+ assert normalize_gateway_provider_ids(None) == DEFAULT_GATEWAY_PROVIDER_IDS+++def test_decode_entry_json_handles_empty_valid_and_invalid_payloads() -> None:+ # Arrange / Act / Assert+ assert decode_entry_json(None) is None+ assert decode_entry_json("") is None+ assert decode_entry_json('{"enabled": true}') == {"enabled": True}+ assert decode_entry_json("{not-json}") == "{not-json}"+++def test_build_plugin_entry_preserves_unmanaged_values_and_removes_empty_python_path() -> None:+ # Arrange+ existing_entry = {+ "enabled": False,+ "name": "headroom",+ "config": {+ "keep": "value",+ "proxyUrl": "https://user.example",+ "pythonPath": "/old/python",+ },+ }++ # Act+ entry = build_plugin_entry(+ existing_entry=existing_entry,+ proxy_port=8787,+ startup_timeout_ms=1500,+ python_path=None,+ no_auto_start=True,+ gateway_provider_ids=(" openai-codex ", "anthropic", "anthropic"),+ enabled=True,+ )++ # Assert+ assert entry["enabled"] is True+ assert entry["name"] == "headroom"+ assert entry["config"] == {+ "keep": "value",+ "proxyUrl": "https://user.example",+ "proxyPort": 8787,+ "autoStart": False,+ "startupTimeoutMs": 1500,+ "gatewayProviderIds": ["openai-codex", "anthropic"],+ }+++def test_build_plugin_entry_creates_managed_defaults_for_non_mapping_input() -> None:+ # Arrange / Act+ entry = build_plugin_entry(+ existing_entry="not-a-dict",+ proxy_port=9000,+ startup_timeout_ms=2500,+ python_path="/usr/bin/python",+ no_auto_start=False,+ gateway_provider_ids=None,+ enabled=False,+ )++ # Assert+ assert entry == {+ "enabled": False,+ "config": {+ "proxyPort": 9000,+ "autoStart": True,+ "startupTimeoutMs": 2500,+ "gatewayProviderIds": ["openai-codex"],+ "pythonPath": "/usr/bin/python",+ },+ }+++def test_build_unwrap_entry_disables_plugin_and_removes_managed_keys_only() -> None:+ # Arrange+ existing_entry = {+ "enabled": True,+ "name": "headroom",+ "config": {+ "keep": "value",+ "gatewayProviderIds": ["openai-codex"],+ "proxyUrl": "https://managed.example",+ "proxyPort": 8787,+ "autoStart": True,+ "startupTimeoutMs": 1000,+ "pythonPath": "/usr/bin/python",+ },+ }++ # Act+ entry = build_unwrap_entry(existing_entry)++ # Assert+ assert entry == {+ "enabled": False,+ "name": "headroom",+ "config": {"keep": "value"},+ }+++def test_build_unwrap_entry_handles_non_mapping_input() -> None:+ # Arrange / Act / Assert+ assert build_unwrap_entry("not-a-dict") == {"enabled": False, "config": {}}diff --git a/tests/test_provider_package_init.py b/tests/test_provider_package_init.pyindex d1f32b4f8..f6cb294b6 100644--- a/tests/test_provider_package_init.py+++ b/tests/test_provider_package_init.py@@ -1,111 +1,111 @@-from __future__ import annotations--import importlib-import types--import pytest--import headroom.providers as providers-from headroom.install.models import ManagedMutation-from headroom.providers import install_registry---def test_providers_package_resolves_exports_lazily_and_caches_them(monkeypatch) -> None:- module = importlib.reload(providers)- module.__dict__.pop("OpenAIProvider", None)- sentinel = object()- import_calls: list[str] = []-- def fake_import_module(name: str):- import_calls.append(name)- return types.SimpleNamespace(OpenAIProvider=sentinel)-- monkeypatch.setattr(module, "import_module", fake_import_module)-- try:- assert module.OpenAIProvider is sentinel- assert module.OpenAIProvider is sentinel- assert import_calls == ["headroom.providers.openai"]- assert "OpenAIProvider" in module.__dir__()- finally:- module.__dict__.pop("OpenAIProvider", None)---def test_providers_package_rejects_missing_and_dunder_path_attributes() -> None:- module = importlib.reload(providers)-- with pytest.raises(AttributeError, match="__path__"):- module.__getattr__("__path__")-- with pytest.raises(AttributeError, match="does_not_exist"):- module.__getattribute__("does_not_exist")---def test_install_registry_build_install_target_envs_uses_known_targets_only(monkeypatch) -> None:- monkeypatch.setattr(- install_registry,- "_ENV_BUILDERS",- {- "claude": lambda *, port, backend: {"CLAUDE_PORT": f"{port}:{backend}"},- "cursor": lambda *, port, backend: {"CURSOR_PORT": f"{port}:{backend}"},- },- )-- envs = install_registry.build_install_target_envs(- port=8787,- backend="anthropic",- targets=["claude", "unknown", "cursor"],- )-- assert envs == {- "claude": {"CLAUDE_PORT": "8787:anthropic"},- "cursor": {"CURSOR_PORT": "8787:anthropic"},- }---def test_install_registry_apply_provider_scope_mutations_skips_missing_and_none(- monkeypatch,-) -> None:- manifest = types.SimpleNamespace(targets=["claude", "codex", "unknown"])- codex_mutation = ManagedMutation(target="codex", kind="toml-block")-- monkeypatch.setattr(- install_registry,- "_PROVIDER_SCOPE_HANDLERS",- {- "claude": (lambda _manifest: None, lambda mutation, manifest: None),- "codex": (lambda _manifest: codex_mutation, lambda mutation, manifest: None),- },- )-- mutations = install_registry.apply_provider_scope_mutations(manifest)-- assert mutations == [codex_mutation]---def test_install_registry_revert_provider_scope_mutation_dispatches_known_targets(- monkeypatch,-) -> None:- manifest = types.SimpleNamespace()- mutation = ManagedMutation(target="codex", kind="toml-block")- recorded: list[tuple[ManagedMutation, object]] = []-- monkeypatch.setattr(- install_registry,- "_PROVIDER_SCOPE_HANDLERS",- {- "codex": (- lambda _manifest: None,- lambda incoming_mutation, incoming_manifest: recorded.append(- (incoming_mutation, incoming_manifest)- ),- )- },- )-- install_registry.revert_provider_scope_mutation(manifest, mutation)- install_registry.revert_provider_scope_mutation(- manifest, ManagedMutation(target="unknown", kind="noop")- )-- assert recorded == [(mutation, manifest)]+from __future__ import annotations++import importlib+import types++import pytest++import headroom.providers as providers+from headroom.install.models import ManagedMutation+from headroom.providers import install_registry+++def test_providers_package_resolves_exports_lazily_and_caches_them(monkeypatch) -> None:+ module = importlib.reload(providers)+ module.__dict__.pop("OpenAIProvider", None)+ sentinel = object()+ import_calls: list[str] = []++ def fake_import_module(name: str):+ import_calls.append(name)+ return types.SimpleNamespace(OpenAIProvider=sentinel)++ monkeypatch.setattr(module, "import_module", fake_import_module)++ try:+ assert module.OpenAIProvider is sentinel+ assert module.OpenAIProvider is sentinel+ assert import_calls == ["headroom.providers.openai"]+ assert "OpenAIProvider" in module.__dir__()+ finally:+ module.__dict__.pop("OpenAIProvider", None)+++def test_providers_package_rejects_missing_and_dunder_path_attributes() -> None:+ module = importlib.reload(providers)++ with pytest.raises(AttributeError, match="__path__"):+ module.__getattr__("__path__")++ with pytest.raises(AttributeError, match="does_not_exist"):+ module.__getattribute__("does_not_exist")+++def test_install_registry_build_install_target_envs_uses_known_targets_only(monkeypatch) -> None:+ monkeypatch.setattr(+ install_registry,+ "_ENV_BUILDERS",+ {+ "claude": lambda *, port, backend: {"CLAUDE_PORT": f"{port}:{backend}"},+ "cursor": lambda *, port, backend: {"CURSOR_PORT": f"{port}:{backend}"},+ },+ )++ envs = install_registry.build_install_target_envs(+ port=8787,+ backend="anthropic",+ targets=["claude", "unknown", "cursor"],+ )++ assert envs == {+ "claude": {"CLAUDE_PORT": "8787:anthropic"},+ "cursor": {"CURSOR_PORT": "8787:anthropic"},+ }+++def test_install_registry_apply_provider_scope_mutations_skips_missing_and_none(+ monkeypatch,+) -> None:+ manifest = types.SimpleNamespace(targets=["claude", "codex", "unknown"])+ codex_mutation = ManagedMutation(target="codex", kind="toml-block")++ monkeypatch.setattr(+ install_registry,+ "_PROVIDER_SCOPE_HANDLERS",+ {+ "claude": (lambda _manifest: None, lambda mutation, manifest: None),+ "codex": (lambda _manifest: codex_mutation, lambda mutation, manifest: None),+ },+ )++ mutations = install_registry.apply_provider_scope_mutations(manifest)++ assert mutations == [codex_mutation]+++def test_install_registry_revert_provider_scope_mutation_dispatches_known_targets(+ monkeypatch,+) -> None:+ manifest = types.SimpleNamespace()+ mutation = ManagedMutation(target="codex", kind="toml-block")+ recorded: list[tuple[ManagedMutation, object]] = []++ monkeypatch.setattr(+ install_registry,+ "_PROVIDER_SCOPE_HANDLERS",+ {+ "codex": (+ lambda _manifest: None,+ lambda incoming_mutation, incoming_manifest: recorded.append(+ (incoming_mutation, incoming_manifest)+ ),+ )+ },+ )++ install_registry.revert_provider_scope_mutation(manifest, mutation)+ install_registry.revert_provider_scope_mutation(+ manifest, ManagedMutation(target="unknown", kind="noop")+ )++ assert recorded == [(mutation, manifest)]diff --git a/tests/test_provider_proxy_routes.py b/tests/test_provider_proxy_routes.pyindex 6e90ca5e8..3f4b7fae6 100644--- a/tests/test_provider_proxy_routes.py+++ b/tests/test_provider_proxy_routes.py@@ -1,340 +1,340 @@-from __future__ import annotations--import importlib-from typing import Any--import httpx-from fastapi.responses import JSONResponse-from fastapi.testclient import TestClient--from headroom.proxy.server import HeadroomProxy, ProxyConfig, create_app---def _app() -> Any:- return create_app(- ProxyConfig(- optimize=False,- cache_enabled=False,- rate_limit_enabled=False,- anthropic_api_url="https://api.anthropic.test",- openai_api_url="https://api.openai.test",- gemini_api_url="https://api.gemini.test",- cloudcode_api_url="https://cloudcode.test",- )- )---def test_provider_passthrough_routes_forward_expected_targets(monkeypatch) -> None:- calls: list[tuple[str, str, str, str]] = []-- async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""): # type: ignore[no-untyped-def]- calls.append((request.method, request.url.path, base_url, provider_name))- return JSONResponse(- {- "method": request.method,- "path": request.url.path,- "base_url": base_url,- "sub_path": sub_path,- "provider": provider_name,- }- )-- monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)-- with TestClient(_app()) as client:- assert client.post("/v1/messages/count_tokens").json()["base_url"] == (- "https://api.anthropic.test"- )- assert client.get("/v1/models", headers={"x-goog-api-key": "test"}).json()["base_url"] == (- "https://api.openai.test"- )- assert client.get("/v1/models/demo").json()["sub_path"] == "models"- assert (- client.get(- "/azure/models",- headers={- "api-key": "azure-key",- "x-headroom-base-url": "https://azure.example/openai/",- },- ).json()["base_url"]- == "https://azure.example/openai"- )- assert client.post("/v1/embeddings").json()["provider"] == "openai"- assert client.post("/v1/moderations").json()["sub_path"] == "moderations"- assert client.post("/v1/images/generations").json()["sub_path"] == "images/generations"- assert client.post("/v1/audio/transcriptions").json()["sub_path"] == "audio/transcriptions"- assert client.post("/v1/audio/speech").json()["sub_path"] == "audio/speech"- assert client.get("/v1beta/models").json()["provider"] == "gemini"- assert client.get("/v1beta/models/demo").json()["sub_path"] == "models"- assert client.post("/v1beta/models/demo:embedContent").json()["sub_path"] == "embedContent"- assert client.post("/v1beta/cachedContents").json()["sub_path"] == "cachedContents"- assert client.get("/v1beta/cachedContents").json()["sub_path"] == "cachedContents"- assert client.get("/v1beta/cachedContents/cache-1").json()["sub_path"] == "cachedContents"- assert client.delete("/v1beta/cachedContents/cache-1").json()["sub_path"] == (- "cachedContents"- )- assert (- client.get(- "/unhandled/path",- headers={"x-headroom-base-url": "https://custom.example/base/"},- ).json()["base_url"]- == "https://custom.example/base"- )- assert client.get("/another/path", headers={"x-goog-api-key": "test"}).json()[- "base_url"- ] == ("https://api.gemini.test")-- assert len(calls) >= 16---def test_proxy_route_helpers_prefer_legacy_targets_and_gemini_passthrough() -> None:- proxy_routes = importlib.import_module("headroom.providers.proxy_routes")- proxy = type(- "Proxy",- (),- {- "ANTHROPIC_API_URL": "https://legacy.anthropic.test",- "OPENAI_API_URL": "https://legacy.openai.test",- "GEMINI_API_URL": "https://legacy.gemini.test",- "provider_runtime": type(- "Runtime",- (),- {- "api_target": staticmethod(lambda provider: f"https://runtime.{provider}.test"),- "model_metadata_provider": staticmethod(lambda headers: "anthropic"),- },- )(),- },- )()-- assert proxy_routes._api_target(proxy, "anthropic") == "https://legacy.anthropic.test"- assert proxy_routes._select_passthrough_base_url(proxy, {"x-goog-api-key": "test"}) == (- "https://legacy.gemini.test"- )- assert (- proxy_routes._select_passthrough_base_url(- proxy, {"api-key": "azure", "x-headroom-base-url": "https://azure.example/base/"}- )- == "https://azure.example/base"- )- assert proxy_routes._select_passthrough_base_url(proxy, {"api-key": "azure"}) == (- "https://legacy.anthropic.test"- )- assert proxy_routes._select_passthrough_base_url(proxy, {}) == "https://legacy.anthropic.test"---def test_provider_specific_routes_delegate_to_expected_proxy_handlers(monkeypatch) -> None:- delegated: list[tuple[str, str, tuple[str, ...]]] = []-- def install(name: str) -> None:- async def fake(self, request, *args): # type: ignore[no-untyped-def]- delegated.append((name, request.url.path, tuple(str(arg) for arg in args)))- return JSONResponse({"handler": name, "path": request.url.path, "args": list(args)})-- monkeypatch.setattr(HeadroomProxy, name, fake)-- for handler_name in (- "handle_anthropic_messages",- "handle_anthropic_batch_create",- "handle_anthropic_batch_passthrough",- "handle_anthropic_batch_results",- "handle_openai_chat",- "handle_openai_responses",- "handle_batch_create",- "handle_batch_list",- "handle_batch_get",- "handle_batch_cancel",- "handle_gemini_generate_content",- "handle_gemini_stream_generate_content",- "handle_gemini_count_tokens",- "handle_google_cloudcode_stream",- "handle_databricks_invocations",- "handle_google_batch_create",- "handle_google_batch_results",- "handle_google_batch_passthrough",- ):- install(handler_name)-- with TestClient(_app()) as client:- assert client.post("/v1/messages").json()["handler"] == "handle_anthropic_messages"- assert (- client.post("/v1/messages/batches").json()["handler"] == "handle_anthropic_batch_create"- )- assert client.get("/v1/messages/batches").json()["handler"] == (- "handle_anthropic_batch_passthrough"- )- assert client.get("/v1/messages/batches/b1").json()["args"] == ["b1"]- assert client.get("/v1/messages/batches/b1/results").json()["handler"] == (- "handle_anthropic_batch_results"- )- assert client.post("/v1/messages/batches/b1/cancel").json()["handler"] == (- "handle_anthropic_batch_passthrough"- )- assert client.post("/v1/chat/completions").json()["handler"] == "handle_openai_chat"- assert client.post("/v1/responses").json()["handler"] == "handle_openai_responses"- assert client.post("/v1/codex/responses").json()["handler"] == "handle_openai_responses"- assert client.post("/backend-api/responses").json()["handler"] == "handle_openai_responses"- assert client.post("/backend-api/codex/responses").json()["handler"] == (- "handle_openai_responses"- )- assert client.post("/v1/batches").json()["handler"] == "handle_batch_create"- assert client.get("/v1/batches").json()["handler"] == "handle_batch_list"- assert client.get("/v1/batches/b1").json()["handler"] == "handle_batch_get"- assert client.post("/v1/batches/b1/cancel").json()["handler"] == "handle_batch_cancel"- assert client.post("/v1beta/models/demo:generateContent").json()["handler"] == (- "handle_gemini_generate_content"- )- assert client.post("/v1beta/models/demo:streamGenerateContent").json()["handler"] == (- "handle_gemini_stream_generate_content"- )- assert client.post("/v1beta/models/demo:countTokens").json()["handler"] == (- "handle_gemini_count_tokens"- )- assert client.post("/v1internal:streamGenerateContent").json()["handler"] == (- "handle_google_cloudcode_stream"- )- assert client.post("/v1/v1internal:streamGenerateContent").json()["handler"] == (- "handle_google_cloudcode_stream"- )- assert client.post("/serving-endpoints/demo/invocations").json()["handler"] == (- "handle_databricks_invocations"- )- assert client.post("/v1beta/models/demo:batchGenerateContent").json()["handler"] == (- "handle_google_batch_create"- )- assert client.get("/v1beta/batches/b1").json()["handler"] == "handle_google_batch_results"- assert client.post("/v1beta/batches/b1:cancel").json()["handler"] == (- "handle_google_batch_passthrough"- )- assert client.delete("/v1beta/batches/b1").json()["handler"] == (- "handle_google_batch_passthrough"- )-- assert len(delegated) >= 24---def test_openai_response_websocket_aliases_delegate_to_openai_ws_handler(monkeypatch) -> None:- seen_paths: list[str] = []-- async def fake_ws(self, websocket): # type: ignore[no-untyped-def]- seen_paths.append(websocket.url.path)- await websocket.accept()- await websocket.send_json({"path": websocket.url.path})- await websocket.close()-- monkeypatch.setattr(HeadroomProxy, "handle_openai_responses_ws", fake_ws)-- with TestClient(_app()) as client:- for path in (- "/v1/responses",- "/v1/codex/responses",- "/backend-api/responses",- "/backend-api/codex/responses",- ):- with client.websocket_connect(path) as websocket:- assert websocket.receive_json() == {"path": path}-- assert seen_paths == [- "/v1/responses",- "/v1/codex/responses",- "/backend-api/responses",- "/backend-api/codex/responses",- ]---def test_openai_response_subpath_passthrough_returns_502_on_http_failure() -> None:- class FailingAsyncClient:- async def request(self, method, url, **kwargs): # type: ignore[no-untyped-def]- raise RuntimeError(f"boom: {method} {url}")-- async def aclose(self) -> None:- return None-- with TestClient(_app()) as client:- client.app.state.proxy.http_client = FailingAsyncClient()- response = client.post("/v1/responses/compact?trace=1", json={"model": "gpt-4o"})-- assert response.status_code == 502- assert "boom: POST https://api.openai.test/v1/responses/compact?trace=1" in response.text---def test_openai_response_subpath_passthrough_uses_openai_target() -> None:- class FakeAsyncClient:- def __init__(self) -> None:- self.calls: list[tuple[str, str, dict[str, str]]] = []-- async def request(self, method, url, **kwargs): # type: ignore[no-untyped-def]- self.calls.append((method, url, dict(kwargs.get("headers", {}))))- return httpx.Response(200, json={"url": url})-- async def aclose(self) -> None:- return None-- with TestClient(_app()) as client:- fake = FakeAsyncClient()- client.app.state.proxy.http_client = fake- response = client.delete(- "/v1/responses/items/resp_123?trace=7",- headers={"Authorization": "Bearer sk-proj-test"},- )-- assert response.status_code == 200- assert len(fake.calls) == 1- method, url, headers = fake.calls[0]- assert method == "DELETE"- assert url == "https://api.openai.test/v1/responses/items/resp_123?trace=7"- assert headers["authorization"] == "Bearer sk-proj-test"---def test_openai_response_subpath_aliases_and_chatgpt_auth_use_expected_targets(monkeypatch) -> None:- monkeypatch.setattr(- "headroom.providers.proxy_routes._resolve_codex_routing_headers",- lambda headers: (headers, True),- )-- class FakeAsyncClient:- def __init__(self) -> None:- self.calls: list[tuple[str, str]] = []-- async def request(self, method, url, **kwargs): # type: ignore[no-untyped-def]- self.calls.append((method, url))- return httpx.Response(200, json={"url": url})-- async def aclose(self) -> None:- return None-- with TestClient(_app()) as client:- fake = FakeAsyncClient()- client.app.state.proxy.http_client = fake- assert client.get("/v1/codex/responses/items/resp_1").status_code == 200- assert client.post("/backend-api/responses/items/resp_2").status_code == 200- assert client.delete("/backend-api/codex/responses/items/resp_3").status_code == 200-- assert fake.calls == [- ("GET", "https://chatgpt.com/backend-api/codex/responses/items/resp_1"),- ("POST", "https://chatgpt.com/backend-api/codex/responses/items/resp_2"),- ("DELETE", "https://chatgpt.com/backend-api/codex/responses/items/resp_3"),- ]---def test_gemini_batch_embed_contents_passthrough_uses_gemini_target(monkeypatch) -> None:- calls: list[tuple[str, str, str]] = []-- async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""): # type: ignore[no-untyped-def]- calls.append((request.url.path, base_url, sub_path))- return JSONResponse({"base_url": base_url, "sub_path": sub_path, "provider": provider_name})-- monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)-- with TestClient(_app()) as client:- response = client.post("/v1beta/models/demo:batchEmbedContents")-- assert response.status_code == 200- assert response.json() == {- "base_url": "https://api.gemini.test",- "sub_path": "batchEmbedContents",- "provider": "gemini",- }- assert calls == [- ("/v1beta/models/demo:batchEmbedContents", "https://api.gemini.test", "batchEmbedContents")- ]+from __future__ import annotations++import importlib+from typing import Any++import httpx+from fastapi.responses import JSONResponse+from fastapi.testclient import TestClient++from headroom.proxy.server import HeadroomProxy, ProxyConfig, create_app+++def _app() -> Any:+ return create_app(+ ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ anthropic_api_url="https://api.anthropic.test",+ openai_api_url="https://api.openai.test",+ gemini_api_url="https://api.gemini.test",+ cloudcode_api_url="https://cloudcode.test",+ )+ )+++def test_provider_passthrough_routes_forward_expected_targets(monkeypatch) -> None:+ calls: list[tuple[str, str, str, str]] = []++ async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""): # type: ignore[no-untyped-def]+ calls.append((request.method, request.url.path, base_url, provider_name))+ return JSONResponse(+ {+ "method": request.method,+ "path": request.url.path,+ "base_url": base_url,+ "sub_path": sub_path,+ "provider": provider_name,+ }+ )++ monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)++ with TestClient(_app()) as client:+ assert client.post("/v1/messages/count_tokens").json()["base_url"] == (+ "https://api.anthropic.test"+ )+ assert client.get("/v1/models", headers={"x-goog-api-key": "test"}).json()["base_url"] == (+ "https://api.openai.test"+ )+ assert client.get("/v1/models/demo").json()["sub_path"] == "models"+ assert (+ client.get(+ "/azure/models",+ headers={+ "api-key": "azure-key",+ "x-headroom-base-url": "https://azure.example/openai/",+ },+ ).json()["base_url"]+ == "https://azure.example/openai"+ )+ assert client.post("/v1/embeddings").json()["provider"] == "openai"+ assert client.post("/v1/moderations").json()["sub_path"] == "moderations"+ assert client.post("/v1/images/generations").json()["sub_path"] == "images/generations"+ assert client.post("/v1/audio/transcriptions").json()["sub_path"] == "audio/transcriptions"+ assert client.post("/v1/audio/speech").json()["sub_path"] == "audio/speech"+ assert client.get("/v1beta/models").json()["provider"] == "gemini"+ assert client.get("/v1beta/models/demo").json()["sub_path"] == "models"+ assert client.post("/v1beta/models/demo:embedContent").json()["sub_path"] == "embedContent"+ assert client.post("/v1beta/cachedContents").json()["sub_path"] == "cachedContents"+ assert client.get("/v1beta/cachedContents").json()["sub_path"] == "cachedContents"+ assert client.get("/v1beta/cachedContents/cache-1").json()["sub_path"] == "cachedContents"+ assert client.delete("/v1beta/cachedContents/cache-1").json()["sub_path"] == (+ "cachedContents"+ )+ assert (+ client.get(+ "/unhandled/path",+ headers={"x-headroom-base-url": "https://custom.example/base/"},+ ).json()["base_url"]+ == "https://custom.example/base"+ )+ assert client.get("/another/path", headers={"x-goog-api-key": "test"}).json()[+ "base_url"+ ] == ("https://api.gemini.test")++ assert len(calls) >= 16+++def test_proxy_route_helpers_prefer_legacy_targets_and_gemini_passthrough() -> None:+ proxy_routes = importlib.import_module("headroom.providers.proxy_routes")+ proxy = type(+ "Proxy",+ (),+ {+ "ANTHROPIC_API_URL": "https://legacy.anthropic.test",+ "OPENAI_API_URL": "https://legacy.openai.test",+ "GEMINI_API_URL": "https://legacy.gemini.test",+ "provider_runtime": type(+ "Runtime",+ (),+ {+ "api_target": staticmethod(lambda provider: f"https://runtime.{provider}.test"),+ "model_metadata_provider": staticmethod(lambda headers: "anthropic"),+ },+ )(),+ },+ )()++ assert proxy_routes._api_target(proxy, "anthropic") == "https://legacy.anthropic.test"+ assert proxy_routes._select_passthrough_base_url(proxy, {"x-goog-api-key": "test"}) == (+ "https://legacy.gemini.test"+ )+ assert (+ proxy_routes._select_passthrough_base_url(+ proxy, {"api-key": "azure", "x-headroom-base-url": "https://azure.example/base/"}+ )+ == "https://azure.example/base"+ )+ assert proxy_routes._select_passthrough_base_url(proxy, {"api-key": "azure"}) == (+ "https://legacy.anthropic.test"+ )+ assert proxy_routes._select_passthrough_base_url(proxy, {}) == "https://legacy.anthropic.test"+++def test_provider_specific_routes_delegate_to_expected_proxy_handlers(monkeypatch) -> None:+ delegated: list[tuple[str, str, tuple[str, ...]]] = []++ def install(name: str) -> None:+ async def fake(self, request, *args): # type: ignore[no-untyped-def]+ delegated.append((name, request.url.path, tuple(str(arg) for arg in args)))+ return JSONResponse({"handler": name, "path": request.url.path, "args": list(args)})++ monkeypatch.setattr(HeadroomProxy, name, fake)++ for handler_name in (+ "handle_anthropic_messages",+ "handle_anthropic_batch_create",+ "handle_anthropic_batch_passthrough",+ "handle_anthropic_batch_results",+ "handle_openai_chat",+ "handle_openai_responses",+ "handle_batch_create",+ "handle_batch_list",+ "handle_batch_get",+ "handle_batch_cancel",+ "handle_gemini_generate_content",+ "handle_gemini_stream_generate_content",+ "handle_gemini_count_tokens",+ "handle_google_cloudcode_stream",+ "handle_databricks_invocations",+ "handle_google_batch_create",+ "handle_google_batch_results",+ "handle_google_batch_passthrough",+ ):+ install(handler_name)++ with TestClient(_app()) as client:+ assert client.post("/v1/messages").json()["handler"] == "handle_anthropic_messages"+ assert (+ client.post("/v1/messages/batches").json()["handler"] == "handle_anthropic_batch_create"+ )+ assert client.get("/v1/messages/batches").json()["handler"] == (+ "handle_anthropic_batch_passthrough"+ )+ assert client.get("/v1/messages/batches/b1").json()["args"] == ["b1"]+ assert client.get("/v1/messages/batches/b1/results").json()["handler"] == (+ "handle_anthropic_batch_results"+ )+ assert client.post("/v1/messages/batches/b1/cancel").json()["handler"] == (+ "handle_anthropic_batch_passthrough"+ )+ assert client.post("/v1/chat/completions").json()["handler"] == "handle_openai_chat"+ assert client.post("/v1/responses").json()["handler"] == "handle_openai_responses"+ assert client.post("/v1/codex/responses").json()["handler"] == "handle_openai_responses"+ assert client.post("/backend-api/responses").json()["handler"] == "handle_openai_responses"+ assert client.post("/backend-api/codex/responses").json()["handler"] == (+ "handle_openai_responses"+ )+ assert client.post("/v1/batches").json()["handler"] == "handle_batch_create"+ assert client.get("/v1/batches").json()["handler"] == "handle_batch_list"+ assert client.get("/v1/batches/b1").json()["handler"] == "handle_batch_get"+ assert client.post("/v1/batches/b1/cancel").json()["handler"] == "handle_batch_cancel"+ assert client.post("/v1beta/models/demo:generateContent").json()["handler"] == (+ "handle_gemini_generate_content"+ )+ assert client.post("/v1beta/models/demo:streamGenerateContent").json()["handler"] == (+ "handle_gemini_stream_generate_content"+ )+ assert client.post("/v1beta/models/demo:countTokens").json()["handler"] == (+ "handle_gemini_count_tokens"+ )+ assert client.post("/v1internal:streamGenerateContent").json()["handler"] == (+ "handle_google_cloudcode_stream"+ )+ assert client.post("/v1/v1internal:streamGenerateContent").json()["handler"] == (+ "handle_google_cloudcode_stream"+ )+ assert client.post("/serving-endpoints/demo/invocations").json()["handler"] == (+ "handle_databricks_invocations"+ )+ assert client.post("/v1beta/models/demo:batchGenerateContent").json()["handler"] == (+ "handle_google_batch_create"+ )+ assert client.get("/v1beta/batches/b1").json()["handler"] == "handle_google_batch_results"+ assert client.post("/v1beta/batches/b1:cancel").json()["handler"] == (+ "handle_google_batch_passthrough"+ )+ assert client.delete("/v1beta/batches/b1").json()["handler"] == (+ "handle_google_batch_passthrough"+ )++ assert len(delegated) >= 24+++def test_openai_response_websocket_aliases_delegate_to_openai_ws_handler(monkeypatch) -> None:+ seen_paths: list[str] = []++ async def fake_ws(self, websocket): # type: ignore[no-untyped-def]+ seen_paths.append(websocket.url.path)+ await websocket.accept()+ await websocket.send_json({"path": websocket.url.path})+ await websocket.close()++ monkeypatch.setattr(HeadroomProxy, "handle_openai_responses_ws", fake_ws)++ with TestClient(_app()) as client:+ for path in (+ "/v1/responses",+ "/v1/codex/responses",+ "/backend-api/responses",+ "/backend-api/codex/responses",+ ):+ with client.websocket_connect(path) as websocket:+ assert websocket.receive_json() == {"path": path}++ assert seen_paths == [+ "/v1/responses",+ "/v1/codex/responses",+ "/backend-api/responses",+ "/backend-api/codex/responses",+ ]+++def test_openai_response_subpath_passthrough_returns_502_on_http_failure() -> None:+ class FailingAsyncClient:+ async def request(self, method, url, **kwargs): # type: ignore[no-untyped-def]+ raise RuntimeError(f"boom: {method} {url}")++ async def aclose(self) -> None:+ return None++ with TestClient(_app()) as client:+ client.app.state.proxy.http_client = FailingAsyncClient()+ response = client.post("/v1/responses/compact?trace=1", json={"model": "gpt-4o"})++ assert response.status_code == 502+ assert "boom: POST https://api.openai.test/v1/responses/compact?trace=1" in response.text+++def test_openai_response_subpath_passthrough_uses_openai_target() -> None:+ class FakeAsyncClient:+ def __init__(self) -> None:+ self.calls: list[tuple[str, str, dict[str, str]]] = []++ async def request(self, method, url, **kwargs): # type: ignore[no-untyped-def]+ self.calls.append((method, url, dict(kwargs.get("headers", {}))))+ return httpx.Response(200, json={"url": url})++ async def aclose(self) -> None:+ return None++ with TestClient(_app()) as client:+ fake = FakeAsyncClient()+ client.app.state.proxy.http_client = fake+ response = client.delete(+ "/v1/responses/items/resp_123?trace=7",+ headers={"Authorization": "Bearer sk-proj-test"},+ )++ assert response.status_code == 200+ assert len(fake.calls) == 1+ method, url, headers = fake.calls[0]+ assert method == "DELETE"+ assert url == "https://api.openai.test/v1/responses/items/resp_123?trace=7"+ assert headers["authorization"] == "Bearer sk-proj-test"+++def test_openai_response_subpath_aliases_and_chatgpt_auth_use_expected_targets(monkeypatch) -> None:+ monkeypatch.setattr(+ "headroom.providers.proxy_routes._resolve_codex_routing_headers",+ lambda headers: (headers, True),+ )++ class FakeAsyncClient:+ def __init__(self) -> None:+ self.calls: list[tuple[str, str]] = []++ async def request(self, method, url, **kwargs): # type: ignore[no-untyped-def]+ self.calls.append((method, url))+ return httpx.Response(200, json={"url": url})++ async def aclose(self) -> None:+ return None++ with TestClient(_app()) as client:+ fake = FakeAsyncClient()+ client.app.state.proxy.http_client = fake+ assert client.get("/v1/codex/responses/items/resp_1").status_code == 200+ assert client.post("/backend-api/responses/items/resp_2").status_code == 200+ assert client.delete("/backend-api/codex/responses/items/resp_3").status_code == 200++ assert fake.calls == [+ ("GET", "https://chatgpt.com/backend-api/codex/responses/items/resp_1"),+ ("POST", "https://chatgpt.com/backend-api/codex/responses/items/resp_2"),+ ("DELETE", "https://chatgpt.com/backend-api/codex/responses/items/resp_3"),+ ]+++def test_gemini_batch_embed_contents_passthrough_uses_gemini_target(monkeypatch) -> None:+ calls: list[tuple[str, str, str]] = []++ async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""): # type: ignore[no-untyped-def]+ calls.append((request.url.path, base_url, sub_path))+ return JSONResponse({"base_url": base_url, "sub_path": sub_path, "provider": provider_name})++ monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)++ with TestClient(_app()) as client:+ response = client.post("/v1beta/models/demo:batchEmbedContents")++ assert response.status_code == 200+ assert response.json() == {+ "base_url": "https://api.gemini.test",+ "sub_path": "batchEmbedContents",+ "provider": "gemini",+ }+ assert calls == [+ ("/v1beta/models/demo:batchEmbedContents", "https://api.gemini.test", "batchEmbedContents")+ ]diff --git a/tests/test_provider_registry_extended.py b/tests/test_provider_registry_extended.pyindex d584d9cae..97f50ab28 100644--- a/tests/test_provider_registry_extended.py+++ b/tests/test_provider_registry_extended.py@@ -1,239 +1,239 @@-from __future__ import annotations--import logging-from types import SimpleNamespace-from typing import Any--import pytest--from headroom.providers.registry import (- ProviderApiTargets,- ProxyProviderRuntime,- call_client_transport,- create_proxy_backend,- format_backend_status,-)---class DummyStorage:- def __init__(self) -> None:- self.saved: list[Any] = []-- def save(self, metrics: Any) -> None:- self.saved.append(metrics)---class DummyClient:- def __init__(self) -> None:- self._storage = DummyStorage()- self._wrapped_stream: tuple[Any, Any] | None = None- self._original = SimpleNamespace(- chat=SimpleNamespace(completions=SimpleNamespace(create=self._openai_create)),- messages=SimpleNamespace(create=self._anthropic_create, stream=self._anthropic_stream),- )- self.openai_calls: list[dict[str, Any]] = []- self.anthropic_calls: list[dict[str, Any]] = []-- def _openai_create(self, **kwargs: Any) -> Any:- self.openai_calls.append(kwargs)- if kwargs["stream"]:- return iter(["chunk-1", "chunk-2"])- return SimpleNamespace(- usage=SimpleNamespace(- completion_tokens=7,- prompt_tokens_details=SimpleNamespace(cached_tokens=3),- )- )-- def _anthropic_create(self, **kwargs: Any) -> Any:- self.anthropic_calls.append(kwargs)- return SimpleNamespace(- usage=SimpleNamespace(- output_tokens=5,- cache_read_input_tokens=2,- )- )-- def _anthropic_stream(self, **kwargs: Any) -> Any:- self.anthropic_calls.append(kwargs)- return "anthropic-stream"-- def _wrap_stream(self, stream: Any, metrics: Any) -> Any:- self._wrapped_stream = (stream, metrics)- return ("wrapped", stream)---def test_proxy_provider_runtime_selects_targets_and_providers() -> None:- runtime = ProxyProviderRuntime(- api_targets=ProviderApiTargets(- anthropic="https://anthropic.example",- openai="https://openai.example",- gemini="https://gemini.example",- cloudcode="https://cloudcode.example",- ),- pipeline_providers={- "anthropic": SimpleNamespace(name="anthropic"),- "openai": SimpleNamespace(name="openai"),- },- )-- assert runtime.api_target("anthropic") == "https://anthropic.example"- assert runtime.pipeline_provider("openai").name == "openai"- assert runtime.model_metadata_provider({"Authorization": "Bearer sk-ant-api03-test"}) == (- "anthropic"- )- assert runtime.select_passthrough_base_url({"x-goog-api-key": "test"}) == (- "https://gemini.example"- )- assert (- runtime.select_passthrough_base_url(- {"api-key": "azure-key", "x-headroom-base-url": "https://azure.example/openai/"}- )- == "https://azure.example/openai"- )- assert runtime.select_passthrough_base_url({}) == "https://openai.example"---def test_create_proxy_backend_uses_injected_backend_types() -> None:- logger = logging.getLogger("test")-- anyllm = create_proxy_backend(- backend="anyllm",- anyllm_provider="groq",- bedrock_region=None,- logger=logger,- anyllm_backend_cls=lambda provider: {"kind": "anyllm", "provider": provider},- )- litellm = create_proxy_backend(- backend="bedrock",- anyllm_provider="ignored",- bedrock_region="us-east-1",- logger=logger,- litellm_backend_cls=lambda provider, region: {- "kind": "litellm",- "provider": provider,- "region": region,- },- )-- assert anyllm == {"kind": "anyllm", "provider": "groq"}- assert litellm == {"kind": "litellm", "provider": "bedrock", "region": "us-east-1"}---def test_create_proxy_backend_handles_missing_or_direct_backends(- caplog: pytest.LogCaptureFixture,-) -> None:- logger = logging.getLogger("test")-- direct = create_proxy_backend(- backend="anthropic",- anyllm_provider="ignored",- bedrock_region=None,- logger=logger,- )-- with caplog.at_level(logging.WARNING):- missing = create_proxy_backend(- backend="anyllm",- anyllm_provider="groq",- bedrock_region=None,- logger=logger,- anyllm_backend_cls=lambda provider: (_ for _ in ()).throw(ImportError("missing")),- )-- assert direct is None- assert missing is None- assert "any-llm backend not available" in caplog.text---def test_format_backend_status_uses_litellm_provider_metadata(- monkeypatch: pytest.MonkeyPatch,-) -> None:- monkeypatch.setattr(- "headroom.backends.litellm.get_provider_config",- lambda provider: SimpleNamespace(- display_name=provider.upper(),- uses_region=(provider == "bedrock"),- ),- )-- assert (- format_backend_status(- backend="litellm-bedrock",- anyllm_provider="ignored",- bedrock_region="us-west-2",- )- == "BEDROCK via LiteLLM (region=us-west-2)"- )- assert (- format_backend_status(- backend="litellm-openai",- anyllm_provider="ignored",- bedrock_region=None,- )- == "OPENAI via LiteLLM"- )---def test_call_client_transport_covers_openai_and_anthropic_paths() -> None:- client = DummyClient()- openai_metrics = SimpleNamespace(tokens_output=0, cached_tokens=0)- anthropic_metrics = SimpleNamespace(tokens_output=0, cached_tokens=0)-- openai_response = call_client_transport(- "openai",- client,- model="gpt-4o",- messages=[{"role": "user", "content": "hello"}],- stream=False,- metrics=openai_metrics,- temperature=0,- )- openai_stream = call_client_transport(- "openai",- client,- model="gpt-4o",- messages=[{"role": "user", "content": "hello"}],- stream=True,- metrics=openai_metrics,- )- anthropic_response = call_client_transport(- "anthropic",- client,- model="claude-sonnet",- messages=[{"role": "user", "content": "hello"}],- stream=False,- metrics=anthropic_metrics,- max_tokens=32,- )- anthropic_stream = call_client_transport(- "anthropic",- client,- model="claude-sonnet",- messages=[{"role": "user", "content": "hello"}],- stream=True,- metrics=anthropic_metrics,- max_tokens=32,- )-- assert openai_response.usage.completion_tokens == 7- assert openai_metrics.tokens_output == 7- assert openai_metrics.cached_tokens == 3- assert openai_stream == ("wrapped", client._wrapped_stream[0])- assert anthropic_response.usage.output_tokens == 5- assert anthropic_metrics.tokens_output == 5- assert anthropic_metrics.cached_tokens == 2- assert anthropic_stream == "anthropic-stream"- assert len(client._storage.saved) == 3---def test_call_client_transport_rejects_unknown_api_style() -> None:- with pytest.raises(ValueError, match="Unsupported api_style"):- call_client_transport(- "unknown",- DummyClient(),- model="gpt-4o",- messages=[],- stream=False,- metrics=SimpleNamespace(),- )+from __future__ import annotations++import logging+from types import SimpleNamespace+from typing import Any++import pytest++from headroom.providers.registry import (+ ProviderApiTargets,+ ProxyProviderRuntime,+ call_client_transport,+ create_proxy_backend,+ format_backend_status,+)+++class DummyStorage:+ def __init__(self) -> None:+ self.saved: list[Any] = []++ def save(self, metrics: Any) -> None:+ self.saved.append(metrics)+++class DummyClient:+ def __init__(self) -> None:+ self._storage = DummyStorage()+ self._wrapped_stream: tuple[Any, Any] | None = None+ self._original = SimpleNamespace(+ chat=SimpleNamespace(completions=SimpleNamespace(create=self._openai_create)),+ messages=SimpleNamespace(create=self._anthropic_create, stream=self._anthropic_stream),+ )+ self.openai_calls: list[dict[str, Any]] = []+ self.anthropic_calls: list[dict[str, Any]] = []++ def _openai_create(self, **kwargs: Any) -> Any:+ self.openai_calls.append(kwargs)+ if kwargs["stream"]:+ return iter(["chunk-1", "chunk-2"])+ return SimpleNamespace(+ usage=SimpleNamespace(+ completion_tokens=7,+ prompt_tokens_details=SimpleNamespace(cached_tokens=3),+ )+ )++ def _anthropic_create(self, **kwargs: Any) -> Any:+ self.anthropic_calls.append(kwargs)+ return SimpleNamespace(+ usage=SimpleNamespace(+ output_tokens=5,+ cache_read_input_tokens=2,+ )+ )++ def _anthropic_stream(self, **kwargs: Any) -> Any:+ self.anthropic_calls.append(kwargs)+ return "anthropic-stream"++ def _wrap_stream(self, stream: Any, metrics: Any) -> Any:+ self._wrapped_stream = (stream, metrics)+ return ("wrapped", stream)+++def test_proxy_provider_runtime_selects_targets_and_providers() -> None:+ runtime = ProxyProviderRuntime(+ api_targets=ProviderApiTargets(+ anthropic="https://anthropic.example",+ openai="https://openai.example",+ gemini="https://gemini.example",+ cloudcode="https://cloudcode.example",+ ),+ pipeline_providers={+ "anthropic": SimpleNamespace(name="anthropic"),+ "openai": SimpleNamespace(name="openai"),+ },+ )++ assert runtime.api_target("anthropic") == "https://anthropic.example"+ assert runtime.pipeline_provider("openai").name == "openai"+ assert runtime.model_metadata_provider({"Authorization": "Bearer sk-ant-api03-test"}) == (+ "anthropic"+ )+ assert runtime.select_passthrough_base_url({"x-goog-api-key": "test"}) == (+ "https://gemini.example"+ )+ assert (+ runtime.select_passthrough_base_url(+ {"api-key": "azure-key", "x-headroom-base-url": "https://azure.example/openai/"}+ )+ == "https://azure.example/openai"+ )+ assert runtime.select_passthrough_base_url({}) == "https://openai.example"+++def test_create_proxy_backend_uses_injected_backend_types() -> None:+ logger = logging.getLogger("test")++ anyllm = create_proxy_backend(+ backend="anyllm",+ anyllm_provider="groq",+ bedrock_region=None,+ logger=logger,+ anyllm_backend_cls=lambda provider: {"kind": "anyllm", "provider": provider},+ )+ litellm = create_proxy_backend(+ backend="bedrock",+ anyllm_provider="ignored",+ bedrock_region="us-east-1",+ logger=logger,+ litellm_backend_cls=lambda provider, region: {+ "kind": "litellm",+ "provider": provider,+ "region": region,+ },+ )++ assert anyllm == {"kind": "anyllm", "provider": "groq"}+ assert litellm == {"kind": "litellm", "provider": "bedrock", "region": "us-east-1"}+++def test_create_proxy_backend_handles_missing_or_direct_backends(+ caplog: pytest.LogCaptureFixture,+) -> None:+ logger = logging.getLogger("test")++ direct = create_proxy_backend(+ backend="anthropic",+ anyllm_provider="ignored",+ bedrock_region=None,+ logger=logger,+ )++ with caplog.at_level(logging.WARNING):+ missing = create_proxy_backend(+ backend="anyllm",+ anyllm_provider="groq",+ bedrock_region=None,+ logger=logger,+ anyllm_backend_cls=lambda provider: (_ for _ in ()).throw(ImportError("missing")),+ )++ assert direct is None+ assert missing is None+ assert "any-llm backend not available" in caplog.text+++def test_format_backend_status_uses_litellm_provider_metadata(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setattr(+ "headroom.backends.litellm.get_provider_config",+ lambda provider: SimpleNamespace(+ display_name=provider.upper(),+ uses_region=(provider == "bedrock"),+ ),+ )++ assert (+ format_backend_status(+ backend="litellm-bedrock",+ anyllm_provider="ignored",+ bedrock_region="us-west-2",+ )+ == "BEDROCK via LiteLLM (region=us-west-2)"+ )+ assert (+ format_backend_status(+ backend="litellm-openai",+ anyllm_provider="ignored",+ bedrock_region=None,+ )+ == "OPENAI via LiteLLM"+ )+++def test_call_client_transport_covers_openai_and_anthropic_paths() -> None:+ client = DummyClient()+ openai_metrics = SimpleNamespace(tokens_output=0, cached_tokens=0)+ anthropic_metrics = SimpleNamespace(tokens_output=0, cached_tokens=0)++ openai_response = call_client_transport(+ "openai",+ client,+ model="gpt-4o",+ messages=[{"role": "user", "content": "hello"}],+ stream=False,+ metrics=openai_metrics,+ temperature=0,+ )+ openai_stream = call_client_transport(+ "openai",+ client,+ model="gpt-4o",+ messages=[{"role": "user", "content": "hello"}],+ stream=True,+ metrics=openai_metrics,+ )+ anthropic_response = call_client_transport(+ "anthropic",+ client,+ model="claude-sonnet",+ messages=[{"role": "user", "content": "hello"}],+ stream=False,+ metrics=anthropic_metrics,+ max_tokens=32,+ )+ anthropic_stream = call_client_transport(+ "anthropic",+ client,+ model="claude-sonnet",+ messages=[{"role": "user", "content": "hello"}],+ stream=True,+ metrics=anthropic_metrics,+ max_tokens=32,+ )++ assert openai_response.usage.completion_tokens == 7+ assert openai_metrics.tokens_output == 7+ assert openai_metrics.cached_tokens == 3+ assert openai_stream == ("wrapped", client._wrapped_stream[0])+ assert anthropic_response.usage.output_tokens == 5+ assert anthropic_metrics.tokens_output == 5+ assert anthropic_metrics.cached_tokens == 2+ assert anthropic_stream == "anthropic-stream"+ assert len(client._storage.saved) == 3+++def test_call_client_transport_rejects_unknown_api_style() -> None:+ with pytest.raises(ValueError, match="Unsupported api_style"):+ call_client_transport(+ "unknown",+ DummyClient(),+ model="gpt-4o",+ messages=[],+ stream=False,+ metrics=SimpleNamespace(),+ )diff --git a/tests/test_proxy_copilot_auth_hooks.py b/tests/test_proxy_copilot_auth_hooks.pyindex b16f22211..45eeb3b09 100644--- a/tests/test_proxy_copilot_auth_hooks.py+++ b/tests/test_proxy_copilot_auth_hooks.py@@ -1,199 +1,199 @@-from __future__ import annotations--import asyncio-import importlib.util-import sys-import types-from pathlib import Path-from types import SimpleNamespace--import pytest--ROOT = Path(__file__).resolve().parents[1]-_ISOLATED_MODULE_NAMES = (- "headroom.proxy",- "headroom.proxy.handlers",- "httpx",- "fastapi.responses",- "tests.headroom_proxy_handlers_openai",- "tests.headroom_proxy_handlers_streaming",-)--[email protected](autouse=True)-def restore_isolated_modules() -> None:- saved_modules = {name: sys.modules.get(name) for name in _ISOLATED_MODULE_NAMES}- try:- yield- finally:- for name in _ISOLATED_MODULE_NAMES:- sys.modules.pop(name, None)- for name, module in saved_modules.items():- if module is not None:- sys.modules[name] = module---def _load_handler_module(monkeypatch: pytest.MonkeyPatch, module_name: str, relative_path: str):- proxy_pkg = types.ModuleType("headroom.proxy")- proxy_pkg.__path__ = [str(ROOT / "headroom" / "proxy")]- monkeypatch.setitem(sys.modules, "headroom.proxy", proxy_pkg)-- handlers_pkg = types.ModuleType("headroom.proxy.handlers")- handlers_pkg.__path__ = [str(ROOT / "headroom" / "proxy" / "handlers")]- monkeypatch.setitem(sys.modules, "headroom.proxy.handlers", handlers_pkg)-- httpx_mod = types.ModuleType("httpx")- httpx_mod.ConnectError = type("ConnectError", (Exception,), {})- httpx_mod.ConnectTimeout = type("ConnectTimeout", (Exception,), {})- httpx_mod.PoolTimeout = type("PoolTimeout", (Exception,), {})- monkeypatch.setitem(sys.modules, "httpx", httpx_mod)-- responses_mod = types.ModuleType("fastapi.responses")-- class Response:- def __init__(self, content=None, status_code: int = 200, headers=None, media_type=None):- self.content = content- self.status_code = status_code- self.headers = headers or {}- self.media_type = media_type-- class StreamingResponse(Response):- pass-- class JSONResponse(Response):- pass-- responses_mod.Response = Response- responses_mod.StreamingResponse = StreamingResponse- responses_mod.JSONResponse = JSONResponse- monkeypatch.setitem(sys.modules, "fastapi.responses", responses_mod)-- spec = importlib.util.spec_from_file_location(module_name, ROOT / relative_path)- assert spec is not None and spec.loader is not None- module = importlib.util.module_from_spec(spec)- monkeypatch.setitem(sys.modules, module_name, module)- spec.loader.exec_module(module)- return module---def test_openai_passthrough_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch) -> None:- openai_mod = _load_handler_module(- monkeypatch,- "tests.headroom_proxy_handlers_openai",- "headroom/proxy/handlers/openai.py",- )-- seen: dict[str, object] = {}-- async def fake_apply(headers: dict[str, str], *, url: str) -> dict[str, str]:- seen["headers"] = dict(headers)- seen["url"] = url- return {"Authorization": "Bearer upstream-token"}-- monkeypatch.setattr(openai_mod, "apply_copilot_api_auth", fake_apply)-- class Dummy(openai_mod.OpenAIHandlerMixin):- def __init__(self) -> None:- self.metrics = SimpleNamespace(record_request=self._record_request)- self.http_client = SimpleNamespace(request=self._request)-- async def _record_request(self, **kwargs) -> None: # noqa: ANN003- return None-- async def _request(self, **kwargs): # noqa: ANN003- seen["request_kwargs"] = kwargs- return SimpleNamespace(headers={}, content=b"{}", status_code=200)-- request = SimpleNamespace(- url=SimpleNamespace(path="/v1/models", query=""),- headers={- "authorization": "Bearer downstream",- "host": "localhost",- "accept-encoding": "gzip",- },- method="GET",- body=lambda: None,- )-- async def body() -> bytes:- return b""-- request.body = body-- handler = Dummy()- response = asyncio.run(- handler.handle_passthrough(- request,- "https://api.githubcopilot.com",- "models",- "openai",- )- )-- assert seen["url"] == "https://api.githubcopilot.com/models"- assert seen["request_kwargs"]["headers"] == {"Authorization": "Bearer upstream-token"}- assert response.status_code == 200---def test_streaming_response_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch) -> None:- streaming_mod = _load_handler_module(- monkeypatch,- "tests.headroom_proxy_handlers_streaming",- "headroom/proxy/handlers/streaming.py",- )-- seen: dict[str, object] = {}-- async def fake_apply(headers: dict[str, str], *, url: str) -> dict[str, str]:- seen["headers"] = dict(headers)- seen["url"] = url- return {"Authorization": "Bearer upstream-token"}-- monkeypatch.setattr(streaming_mod, "apply_copilot_api_auth", fake_apply)-- class Dummy(streaming_mod.StreamingMixin):- def __init__(self) -> None:- self.memory_handler = None- self.config = SimpleNamespace(- retry_max_attempts=1,- retry_base_delay_ms=1,- retry_max_delay_ms=1,- )- self.http_client = SimpleNamespace(- build_request=self._build_request,- send=self._send,- )-- def _build_request(self, method: str, url: str, json: dict, headers: dict): # noqa: ANN003, A002- seen["request"] = {- "method": method,- "url": url,- "json": json,- "headers": headers,- }- return SimpleNamespace()-- async def _send(self, request, stream: bool): # noqa: ANN001, ANN003- return SimpleNamespace(headers={}, status_code=200)-- handler = Dummy()- response = asyncio.run(- handler._stream_response(- url="https://api.githubcopilot.com/v1/responses",- headers={"authorization": "Bearer downstream"},- body={"model": "gpt-4o"},- provider="openai",- model="gpt-4o",- request_id="req-test",- original_tokens=0,- optimized_tokens=0,- tokens_saved=0,- transforms_applied=[],- tags={},- optimization_latency=0.0,- )- )-- assert seen["url"] == "https://api.githubcopilot.com/v1/responses"- assert seen["request"]["headers"] == {"Authorization": "Bearer upstream-token"}- assert response.status_code == 200+from __future__ import annotations++import asyncio+import importlib.util+import sys+import types+from pathlib import Path+from types import SimpleNamespace++import pytest++ROOT = Path(__file__).resolve().parents[1]+_ISOLATED_MODULE_NAMES = (+ "headroom.proxy",+ "headroom.proxy.handlers",+ "httpx",+ "fastapi.responses",+ "tests.headroom_proxy_handlers_openai",+ "tests.headroom_proxy_handlers_streaming",+)++[email protected](autouse=True)+def restore_isolated_modules() -> None:+ saved_modules = {name: sys.modules.get(name) for name in _ISOLATED_MODULE_NAMES}+ try:+ yield+ finally:+ for name in _ISOLATED_MODULE_NAMES:+ sys.modules.pop(name, None)+ for name, module in saved_modules.items():+ if module is not None:+ sys.modules[name] = module+++def _load_handler_module(monkeypatch: pytest.MonkeyPatch, module_name: str, relative_path: str):+ proxy_pkg = types.ModuleType("headroom.proxy")+ proxy_pkg.__path__ = [str(ROOT / "headroom" / "proxy")]+ monkeypatch.setitem(sys.modules, "headroom.proxy", proxy_pkg)++ handlers_pkg = types.ModuleType("headroom.proxy.handlers")+ handlers_pkg.__path__ = [str(ROOT / "headroom" / "proxy" / "handlers")]+ monkeypatch.setitem(sys.modules, "headroom.proxy.handlers", handlers_pkg)++ httpx_mod = types.ModuleType("httpx")+ httpx_mod.ConnectError = type("ConnectError", (Exception,), {})+ httpx_mod.ConnectTimeout = type("ConnectTimeout", (Exception,), {})+ httpx_mod.PoolTimeout = type("PoolTimeout", (Exception,), {})+ monkeypatch.setitem(sys.modules, "httpx", httpx_mod)++ responses_mod = types.ModuleType("fastapi.responses")++ class Response:+ def __init__(self, content=None, status_code: int = 200, headers=None, media_type=None):+ self.content = content+ self.status_code = status_code+ self.headers = headers or {}+ self.media_type = media_type++ class StreamingResponse(Response):+ pass++ class JSONResponse(Response):+ pass++ responses_mod.Response = Response+ responses_mod.StreamingResponse = StreamingResponse+ responses_mod.JSONResponse = JSONResponse+ monkeypatch.setitem(sys.modules, "fastapi.responses", responses_mod)++ spec = importlib.util.spec_from_file_location(module_name, ROOT / relative_path)+ assert spec is not None and spec.loader is not None+ module = importlib.util.module_from_spec(spec)+ monkeypatch.setitem(sys.modules, module_name, module)+ spec.loader.exec_module(module)+ return module+++def test_openai_passthrough_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch) -> None:+ openai_mod = _load_handler_module(+ monkeypatch,+ "tests.headroom_proxy_handlers_openai",+ "headroom/proxy/handlers/openai.py",+ )++ seen: dict[str, object] = {}++ async def fake_apply(headers: dict[str, str], *, url: str) -> dict[str, str]:+ seen["headers"] = dict(headers)+ seen["url"] = url+ return {"Authorization": "Bearer upstream-token"}++ monkeypatch.setattr(openai_mod, "apply_copilot_api_auth", fake_apply)++ class Dummy(openai_mod.OpenAIHandlerMixin):+ def __init__(self) -> None:+ self.metrics = SimpleNamespace(record_request=self._record_request)+ self.http_client = SimpleNamespace(request=self._request)++ async def _record_request(self, **kwargs) -> None: # noqa: ANN003+ return None++ async def _request(self, **kwargs): # noqa: ANN003+ seen["request_kwargs"] = kwargs+ return SimpleNamespace(headers={}, content=b"{}", status_code=200)++ request = SimpleNamespace(+ url=SimpleNamespace(path="/v1/models", query=""),+ headers={+ "authorization": "Bearer downstream",+ "host": "localhost",+ "accept-encoding": "gzip",+ },+ method="GET",+ body=lambda: None,+ )++ async def body() -> bytes:+ return b""++ request.body = body++ handler = Dummy()+ response = asyncio.run(+ handler.handle_passthrough(+ request,+ "https://api.githubcopilot.com",+ "models",+ "openai",+ )+ )++ assert seen["url"] == "https://api.githubcopilot.com/models"+ assert seen["request_kwargs"]["headers"] == {"Authorization": "Bearer upstream-token"}+ assert response.status_code == 200+++def test_streaming_response_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch) -> None:+ streaming_mod = _load_handler_module(+ monkeypatch,+ "tests.headroom_proxy_handlers_streaming",+ "headroom/proxy/handlers/streaming.py",+ )++ seen: dict[str, object] = {}++ async def fake_apply(headers: dict[str, str], *, url: str) -> dict[str, str]:+ seen["headers"] = dict(headers)+ seen["url"] = url+ return {"Authorization": "Bearer upstream-token"}++ monkeypatch.setattr(streaming_mod, "apply_copilot_api_auth", fake_apply)++ class Dummy(streaming_mod.StreamingMixin):+ def __init__(self) -> None:+ self.memory_handler = None+ self.config = SimpleNamespace(+ retry_max_attempts=1,+ retry_base_delay_ms=1,+ retry_max_delay_ms=1,+ )+ self.http_client = SimpleNamespace(+ build_request=self._build_request,+ send=self._send,+ )++ def _build_request(self, method: str, url: str, json: dict, headers: dict): # noqa: ANN003, A002+ seen["request"] = {+ "method": method,+ "url": url,+ "json": json,+ "headers": headers,+ }+ return SimpleNamespace()++ async def _send(self, request, stream: bool): # noqa: ANN001, ANN003+ return SimpleNamespace(headers={}, status_code=200)++ handler = Dummy()+ response = asyncio.run(+ handler._stream_response(+ url="https://api.githubcopilot.com/v1/responses",+ headers={"authorization": "Bearer downstream"},+ body={"model": "gpt-4o"},+ provider="openai",+ model="gpt-4o",+ request_id="req-test",+ original_tokens=0,+ optimized_tokens=0,+ tokens_saved=0,+ transforms_applied=[],+ tags={},+ optimization_latency=0.0,+ )+ )++ assert seen["url"] == "https://api.githubcopilot.com/v1/responses"+ assert seen["request"]["headers"] == {"Authorization": "Bearer upstream-token"}+ assert response.status_code == 200diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.pyindex 53d3087e3..9a87da187 100644--- a/tests/test_proxy_handler_helpers.py+++ b/tests/test_proxy_handler_helpers.py@@ -1,214 +1,214 @@-from __future__ import annotations--import base64-import json--from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin-from headroom.proxy.handlers.openai import OpenAIHandlerMixin, _decode_openai_bearer_payload---def _jwt(payload: object) -> str:- header = {"alg": "none", "typ": "JWT"}-- def encode(part: object) -> str:- raw = json.dumps(part, separators=(",", ":")).encode("utf-8")- return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")-- return f"{encode(header)}.{encode(payload)}."---class _ImageCompressor:- def __init__(self, compressed_message):- self._compressed_message = compressed_message-- def compress(self, messages, provider): # noqa: ANN001, ANN201- assert provider == "anthropic"- return [self._compressed_message]---def test_decode_openai_bearer_payload_handles_missing_and_non_mapping_payloads() -> None:- assert _decode_openai_bearer_payload({}) is None- assert _decode_openai_bearer_payload({"authorization": "Basic abc"}) is None- assert (- _decode_openai_bearer_payload({"authorization": f"Bearer {_jwt(['not', 'a', 'dict'])}"})- is None- )---def test_openai_handler_prefix_helpers_cover_edge_cases() -> None:- assert OpenAIHandlerMixin._strict_previous_turn_frozen_count([], 2) == 2- assert (- OpenAIHandlerMixin._strict_previous_turn_frozen_count(- [{"role": "assistant"}, {"role": "user"}],- 0,- )- == 1- )- assert (- OpenAIHandlerMixin._strict_previous_turn_frozen_count(- [{"role": "user"}, {"role": "assistant"}],- 0,- )- == 2- )-- original = [{"role": "system", "content": "keep"}, {"role": "user", "content": "hello"}]- restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(- original,- [],- frozen_message_count=1,- )- assert restored == [{"role": "system", "content": "keep"}]- assert changed == 1-- restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(- original,- [{"role": "system", "content": "changed"}, {"role": "user", "content": "hello"}],- frozen_message_count=1,- )- assert restored == original- assert changed == 1---def test_anthropic_tool_sort_and_context_append_helpers() -> None:- tools = [- {"type": "function", "function": {"name": "beta"}},- {"name": "alpha"},- {"type": "tool"},- ]-- sorted_tools = AnthropicHandlerMixin._sort_tools_deterministically(tools)-- assert [AnthropicHandlerMixin._tool_sort_key(tool)[0] for tool in sorted_tools] == [- "alpha",- "beta",- "tool",- ]- assert AnthropicHandlerMixin._sort_tools_deterministically(None) is None- assert (- AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(- [], "ctx", frozen_message_count=0- )- == []- )- assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(- [{"role": "user", "content": "hello"}],- "ctx",- frozen_message_count=0,- ) == [{"role": "user", "content": "hello\n\nctx"}]- assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(- [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],- "ctx",- frozen_message_count=0,- ) == [{"role": "user", "content": [{"type": "text", "text": "hello"}]}]---def test_anthropic_image_compression_helper_only_rewrites_latest_eligible_turn() -> None:- image_message = {- "role": "user",- "content": [{"type": "image", "source": {"type": "base64", "data": "abc"}}],- }- compressed = {- "role": "user",- "content": [{"type": "image", "source": {"type": "base64", "data": "xyz"}}],- }-- assert (- AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(- [],- frozen_message_count=0,- compressor=_ImageCompressor(compressed),- )- == []- )- assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(- [image_message],- frozen_message_count=1,- compressor=_ImageCompressor(compressed),- ) == [image_message]- assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(- [{"role": "assistant", "content": image_message["content"]}],- frozen_message_count=0,- compressor=_ImageCompressor(compressed),- ) == [{"role": "assistant", "content": image_message["content"]}]- assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(- [{"role": "user", "content": "no-image"}],- frozen_message_count=0,- compressor=_ImageCompressor(compressed),- ) == [{"role": "user", "content": "no-image"}]- assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(- [image_message],- frozen_message_count=0,- compressor=_ImageCompressor(image_message),- ) == [image_message]- assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(- [image_message],- frozen_message_count=0,- compressor=_ImageCompressor(compressed),- ) == [compressed]---def test_anthropic_cache_delta_helpers_cover_string_list_and_role_mismatch() -> None:- previous_original = [{"role": "user", "content": "hello"}]- previous_forwarded = [{"role": "user", "content": "HELLO"}]-- assert AnthropicHandlerMixin._extract_cache_stable_delta(- [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "next"}],- previous_original,- previous_forwarded,- ) == (previous_forwarded, [{"role": "assistant", "content": "next"}])- assert (- AnthropicHandlerMixin._extract_cache_stable_delta(- [{"role": "assistant", "content": "hello"}],- previous_original,- previous_forwarded,- )- is None- )-- string_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(- [{"role": "user", "content": "hello world"}],- previous_original,- previous_forwarded,- )- assert string_suffix == ([], previous_forwarded[0], [{"role": "user", "content": " world"}])-- list_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(- [- {- "role": "user",- "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],- }- ],- [{"role": "user", "content": [{"type": "text", "text": "a"}]}],- [{"role": "user", "content": [{"type": "text", "text": "A"}]}],- )- assert list_suffix == (- [],- {"role": "user", "content": [{"type": "text", "text": "A"}]},- [{"role": "user", "content": [{"type": "text", "text": "b"}]}],- )-- assert AnthropicHandlerMixin._merge_appended_message_delta(- {"role": "user", "content": "HELLO"},- {"role": "user", "content": " world"},- ) == {"role": "user", "content": "HELLO world"}- assert AnthropicHandlerMixin._merge_appended_message_delta(- {"role": "user", "content": [{"type": "text", "text": "A"}]},- {"role": "user", "content": [{"type": "text", "text": "b"}]},- ) == {"role": "user", "content": [{"type": "text", "text": "A"}, {"type": "text", "text": "b"}]}- assert (- AnthropicHandlerMixin._merge_appended_message_delta(- {"role": "user", "content": "A"},- {"role": "assistant", "content": "B"},- )- is None- )---def test_anthropic_assistant_message_helper_requires_assistant_role() -> None:- assert AnthropicHandlerMixin._assistant_message_from_response_json(None) is None- assert AnthropicHandlerMixin._assistant_message_from_response_json({"role": "user"}) is None- assert AnthropicHandlerMixin._assistant_message_from_response_json(- {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}- ) == {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}+from __future__ import annotations++import base64+import json++from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin+from headroom.proxy.handlers.openai import OpenAIHandlerMixin, _decode_openai_bearer_payload+++def _jwt(payload: object) -> str:+ header = {"alg": "none", "typ": "JWT"}++ def encode(part: object) -> str:+ raw = json.dumps(part, separators=(",", ":")).encode("utf-8")+ return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")++ return f"{encode(header)}.{encode(payload)}."+++class _ImageCompressor:+ def __init__(self, compressed_message):+ self._compressed_message = compressed_message++ def compress(self, messages, provider): # noqa: ANN001, ANN201+ assert provider == "anthropic"+ return [self._compressed_message]+++def test_decode_openai_bearer_payload_handles_missing_and_non_mapping_payloads() -> None:+ assert _decode_openai_bearer_payload({}) is None+ assert _decode_openai_bearer_payload({"authorization": "Basic abc"}) is None+ assert (+ _decode_openai_bearer_payload({"authorization": f"Bearer {_jwt(['not', 'a', 'dict'])}"})+ is None+ )+++def test_openai_handler_prefix_helpers_cover_edge_cases() -> None:+ assert OpenAIHandlerMixin._strict_previous_turn_frozen_count([], 2) == 2+ assert (+ OpenAIHandlerMixin._strict_previous_turn_frozen_count(+ [{"role": "assistant"}, {"role": "user"}],+ 0,+ )+ == 1+ )+ assert (+ OpenAIHandlerMixin._strict_previous_turn_frozen_count(+ [{"role": "user"}, {"role": "assistant"}],+ 0,+ )+ == 2+ )++ original = [{"role": "system", "content": "keep"}, {"role": "user", "content": "hello"}]+ restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(+ original,+ [],+ frozen_message_count=1,+ )+ assert restored == [{"role": "system", "content": "keep"}]+ assert changed == 1++ restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(+ original,+ [{"role": "system", "content": "changed"}, {"role": "user", "content": "hello"}],+ frozen_message_count=1,+ )+ assert restored == original+ assert changed == 1+++def test_anthropic_tool_sort_and_context_append_helpers() -> None:+ tools = [+ {"type": "function", "function": {"name": "beta"}},+ {"name": "alpha"},+ {"type": "tool"},+ ]++ sorted_tools = AnthropicHandlerMixin._sort_tools_deterministically(tools)++ assert [AnthropicHandlerMixin._tool_sort_key(tool)[0] for tool in sorted_tools] == [+ "alpha",+ "beta",+ "tool",+ ]+ assert AnthropicHandlerMixin._sort_tools_deterministically(None) is None+ assert (+ AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(+ [], "ctx", frozen_message_count=0+ )+ == []+ )+ assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(+ [{"role": "user", "content": "hello"}],+ "ctx",+ frozen_message_count=0,+ ) == [{"role": "user", "content": "hello\n\nctx"}]+ assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(+ [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],+ "ctx",+ frozen_message_count=0,+ ) == [{"role": "user", "content": [{"type": "text", "text": "hello"}]}]+++def test_anthropic_image_compression_helper_only_rewrites_latest_eligible_turn() -> None:+ image_message = {+ "role": "user",+ "content": [{"type": "image", "source": {"type": "base64", "data": "abc"}}],+ }+ compressed = {+ "role": "user",+ "content": [{"type": "image", "source": {"type": "base64", "data": "xyz"}}],+ }++ assert (+ AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(+ [],+ frozen_message_count=0,+ compressor=_ImageCompressor(compressed),+ )+ == []+ )+ assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(+ [image_message],+ frozen_message_count=1,+ compressor=_ImageCompressor(compressed),+ ) == [image_message]+ assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(+ [{"role": "assistant", "content": image_message["content"]}],+ frozen_message_count=0,+ compressor=_ImageCompressor(compressed),+ ) == [{"role": "assistant", "content": image_message["content"]}]+ assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(+ [{"role": "user", "content": "no-image"}],+ frozen_message_count=0,+ compressor=_ImageCompressor(compressed),+ ) == [{"role": "user", "content": "no-image"}]+ assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(+ [image_message],+ frozen_message_count=0,+ compressor=_ImageCompressor(image_message),+ ) == [image_message]+ assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(+ [image_message],+ frozen_message_count=0,+ compressor=_ImageCompressor(compressed),+ ) == [compressed]+++def test_anthropic_cache_delta_helpers_cover_string_list_and_role_mismatch() -> None:+ previous_original = [{"role": "user", "content": "hello"}]+ previous_forwarded = [{"role": "user", "content": "HELLO"}]++ assert AnthropicHandlerMixin._extract_cache_stable_delta(+ [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "next"}],+ previous_original,+ previous_forwarded,+ ) == (previous_forwarded, [{"role": "assistant", "content": "next"}])+ assert (+ AnthropicHandlerMixin._extract_cache_stable_delta(+ [{"role": "assistant", "content": "hello"}],+ previous_original,+ previous_forwarded,+ )+ is None+ )++ string_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(+ [{"role": "user", "content": "hello world"}],+ previous_original,+ previous_forwarded,+ )+ assert string_suffix == ([], previous_forwarded[0], [{"role": "user", "content": " world"}])++ list_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(+ [+ {+ "role": "user",+ "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],+ }+ ],+ [{"role": "user", "content": [{"type": "text", "text": "a"}]}],+ [{"role": "user", "content": [{"type": "text", "text": "A"}]}],+ )+ assert list_suffix == (+ [],+ {"role": "user", "content": [{"type": "text", "text": "A"}]},+ [{"role": "user", "content": [{"type": "text", "text": "b"}]}],+ )++ assert AnthropicHandlerMixin._merge_appended_message_delta(+ {"role": "user", "content": "HELLO"},+ {"role": "user", "content": " world"},+ ) == {"role": "user", "content": "HELLO world"}+ assert AnthropicHandlerMixin._merge_appended_message_delta(+ {"role": "user", "content": [{"type": "text", "text": "A"}]},+ {"role": "user", "content": [{"type": "text", "text": "b"}]},+ ) == {"role": "user", "content": [{"type": "text", "text": "A"}, {"type": "text", "text": "b"}]}+ assert (+ AnthropicHandlerMixin._merge_appended_message_delta(+ {"role": "user", "content": "A"},+ {"role": "assistant", "content": "B"},+ )+ is None+ )+++def test_anthropic_assistant_message_helper_requires_assistant_role() -> None:+ assert AnthropicHandlerMixin._assistant_message_from_response_json(None) is None+ assert AnthropicHandlerMixin._assistant_message_from_response_json({"role": "user"}) is None+ assert AnthropicHandlerMixin._assistant_message_from_response_json(+ {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}+ ) == {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}diff --git a/tests/test_proxy_pipeline_lifecycle.py b/tests/test_proxy_pipeline_lifecycle.pyindex fde19d8e1..aea3ec06d 100644--- a/tests/test_proxy_pipeline_lifecycle.py+++ b/tests/test_proxy_pipeline_lifecycle.py@@ -1,184 +1,184 @@-from __future__ import annotations--from types import SimpleNamespace-from unittest.mock import AsyncMock--import httpx-from fastapi.testclient import TestClient--from headroom.pipeline import PipelineStage-from headroom.proxy.server import ProxyConfig, create_app---class _RecordingExtension:- def __init__(self) -> None:- self.stages: list[PipelineStage] = []-- def on_pipeline_event(self, event):- self.stages.append(event.stage)- return None---class _DummyTokenizer:- def count_messages(self, messages):- return len(messages)---def _assert_stage_order(stages: list[PipelineStage]) -> None:- expected = [- PipelineStage.SETUP,- PipelineStage.PRE_START,- PipelineStage.POST_START,- PipelineStage.INPUT_RECEIVED,- PipelineStage.INPUT_ROUTED,- PipelineStage.INPUT_COMPRESSED,- PipelineStage.INPUT_REMEMBERED,- PipelineStage.PRE_SEND,- PipelineStage.POST_SEND,- PipelineStage.RESPONSE_RECEIVED,- ]- positions = [stages.index(stage) for stage in expected]- assert positions == sorted(positions)---def test_openai_chat_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:- recorder = _RecordingExtension()- config = ProxyConfig(- optimize=True,- image_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,- pipeline_extensions=[recorder],- discover_pipeline_extensions=False,- )- app = create_app(config)-- with TestClient(app) as client:- proxy = client.app.state.proxy- proxy.openai_pipeline = SimpleNamespace(- apply=lambda messages, model, **kwargs: SimpleNamespace(- messages=[- {"role": "system", "content": "memory"},- {"role": "user", "content": "hello"},- ],- transforms_applied=["router:text:kompress"],- tokens_before=10,- tokens_after=6,- )- )- proxy.memory_handler = SimpleNamespace(- config=SimpleNamespace(inject_context=True, inject_tools=False),- search_and_format_context=AsyncMock(return_value="memory"),- has_memory_tool_calls=lambda response, provider: False,- )-- monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())-- async def _fake_retry(method, url, headers, body, stream=False): # noqa: ANN001- return httpx.Response(- 200,- json={- "id": "chatcmpl_1",- "object": "chat.completion",- "choices": [{"message": {"role": "assistant", "content": "ok"}}],- "usage": {"prompt_tokens": 10, "completion_tokens": 3, "total_tokens": 13},- },- )-- proxy._retry_request = _fake_retry-- response = client.post(- "/v1/chat/completions",- headers={"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},- json={- "model": "gpt-5.4",- "messages": [{"role": "user", "content": "hello"}],- "tools": [{"type": "function", "function": {"name": "tool_a"}}],- },- )-- assert response.status_code == 200- _assert_stage_order(recorder.stages)---def test_anthropic_messages_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:- recorder = _RecordingExtension()- config = ProxyConfig(- optimize=True,- 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,- image_optimize=False,- pipeline_extensions=[recorder],- discover_pipeline_extensions=False,- )- app = create_app(config)-- with TestClient(app) as client:- proxy = client.app.state.proxy- proxy.anthropic_pipeline = SimpleNamespace(- apply=lambda messages, model, **kwargs: SimpleNamespace(- messages=[- {"role": "system", "content": "memory"},- {"role": "user", "content": "hello"},- ],- transforms_applied=["router:text:kompress"],- tokens_before=10,- tokens_after=6,- )- )- proxy.memory_handler = SimpleNamespace(- config=SimpleNamespace(inject_context=True, inject_tools=False),- search_and_format_context=AsyncMock(return_value="memory"),- has_memory_tool_calls=lambda response, provider: False,- )-- monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())-- async def _fake_retry(method, url, headers, body, stream=False): # noqa: ANN001- return httpx.Response(- 200,- json={- "id": "msg_1",- "type": "message",- "role": "assistant",- "content": [{"type": "text", "text": "ok"}],- "usage": {- "input_tokens": 10,- "output_tokens": 3,- "cache_read_input_tokens": 0,- "cache_creation_input_tokens": 0,- },- },- )-- proxy._retry_request = _fake_retry-- response = client.post(- "/v1/messages",- headers={- "x-api-key": "test-key",- "anthropic-version": "2023-06-01",- "x-headroom-user-id": "user-1",- },- json={- "model": "claude-sonnet-4-6",- "max_tokens": 128,- "messages": [{"role": "user", "content": "hello"}],- "tools": [- {"name": "tool_a", "description": "a", "input_schema": {"type": "object"}}- ],- },- )-- assert response.status_code == 200- _assert_stage_order(recorder.stages)+from __future__ import annotations++from types import SimpleNamespace+from unittest.mock import AsyncMock++import httpx+from fastapi.testclient import TestClient++from headroom.pipeline import PipelineStage+from headroom.proxy.server import ProxyConfig, create_app+++class _RecordingExtension:+ def __init__(self) -> None:+ self.stages: list[PipelineStage] = []++ def on_pipeline_event(self, event):+ self.stages.append(event.stage)+ return None+++class _DummyTokenizer:+ def count_messages(self, messages):+ return len(messages)+++def _assert_stage_order(stages: list[PipelineStage]) -> None:+ expected = [+ PipelineStage.SETUP,+ PipelineStage.PRE_START,+ PipelineStage.POST_START,+ PipelineStage.INPUT_RECEIVED,+ PipelineStage.INPUT_ROUTED,+ PipelineStage.INPUT_COMPRESSED,+ PipelineStage.INPUT_REMEMBERED,+ PipelineStage.PRE_SEND,+ PipelineStage.POST_SEND,+ PipelineStage.RESPONSE_RECEIVED,+ ]+ positions = [stages.index(stage) for stage in expected]+ assert positions == sorted(positions)+++def test_openai_chat_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:+ recorder = _RecordingExtension()+ config = ProxyConfig(+ optimize=True,+ image_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,+ pipeline_extensions=[recorder],+ discover_pipeline_extensions=False,+ )+ app = create_app(config)++ with TestClient(app) as client:+ proxy = client.app.state.proxy+ proxy.openai_pipeline = SimpleNamespace(+ apply=lambda messages, model, **kwargs: SimpleNamespace(+ messages=[+ {"role": "system", "content": "memory"},+ {"role": "user", "content": "hello"},+ ],+ transforms_applied=["router:text:kompress"],+ tokens_before=10,+ tokens_after=6,+ )+ )+ proxy.memory_handler = SimpleNamespace(+ config=SimpleNamespace(inject_context=True, inject_tools=False),+ search_and_format_context=AsyncMock(return_value="memory"),+ has_memory_tool_calls=lambda response, provider: False,+ )++ monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())++ async def _fake_retry(method, url, headers, body, stream=False): # noqa: ANN001+ return httpx.Response(+ 200,+ json={+ "id": "chatcmpl_1",+ "object": "chat.completion",+ "choices": [{"message": {"role": "assistant", "content": "ok"}}],+ "usage": {"prompt_tokens": 10, "completion_tokens": 3, "total_tokens": 13},+ },+ )++ proxy._retry_request = _fake_retry++ response = client.post(+ "/v1/chat/completions",+ headers={"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},+ json={+ "model": "gpt-5.4",+ "messages": [{"role": "user", "content": "hello"}],+ "tools": [{"type": "function", "function": {"name": "tool_a"}}],+ },+ )++ assert response.status_code == 200+ _assert_stage_order(recorder.stages)+++def test_anthropic_messages_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:+ recorder = _RecordingExtension()+ config = ProxyConfig(+ optimize=True,+ 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,+ image_optimize=False,+ pipeline_extensions=[recorder],+ discover_pipeline_extensions=False,+ )+ app = create_app(config)++ with TestClient(app) as client:+ proxy = client.app.state.proxy+ proxy.anthropic_pipeline = SimpleNamespace(+ apply=lambda messages, model, **kwargs: SimpleNamespace(+ messages=[+ {"role": "system", "content": "memory"},+ {"role": "user", "content": "hello"},+ ],+ transforms_applied=["router:text:kompress"],+ tokens_before=10,+ tokens_after=6,+ )+ )+ proxy.memory_handler = SimpleNamespace(+ config=SimpleNamespace(inject_context=True, inject_tools=False),+ search_and_format_context=AsyncMock(return_value="memory"),+ has_memory_tool_calls=lambda response, provider: False,+ )++ monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())++ async def _fake_retry(method, url, headers, body, stream=False): # noqa: ANN001+ return httpx.Response(+ 200,+ json={+ "id": "msg_1",+ "type": "message",+ "role": "assistant",+ "content": [{"type": "text", "text": "ok"}],+ "usage": {+ "input_tokens": 10,+ "output_tokens": 3,+ "cache_read_input_tokens": 0,+ "cache_creation_input_tokens": 0,+ },+ },+ )++ proxy._retry_request = _fake_retry++ response = client.post(+ "/v1/messages",+ headers={+ "x-api-key": "test-key",+ "anthropic-version": "2023-06-01",+ "x-headroom-user-id": "user-1",+ },+ json={+ "model": "claude-sonnet-4-6",+ "max_tokens": 128,+ "messages": [{"role": "user", "content": "hello"}],+ "tools": [+ {"name": "tool_a", "description": "a", "input_schema": {"type": "object"}}+ ],+ },+ )++ assert response.status_code == 200+ _assert_stage_order(recorder.stages)diff --git a/tests/test_proxy_savings_history.py b/tests/test_proxy_savings_history.pyindex f261c95dc..e4874f5a6 100644--- a/tests/test_proxy_savings_history.py+++ b/tests/test_proxy_savings_history.py@@ -1,711 +1,711 @@-"""Tests for durable proxy savings history."""--from __future__ import annotations--import asyncio-import json-from datetime import datetime, timedelta, timezone-from pathlib import Path-from types import SimpleNamespace--import pytest--pytest.importorskip("fastapi")--from fastapi.testclient import TestClient--import headroom.proxy.savings_tracker as savings_tracker_module-from headroom.proxy.savings_tracker import HEADROOM_SAVINGS_PATH_ENV_VAR, SavingsTracker-from headroom.proxy.server import ProxyConfig, create_app---def _record_request(- client: TestClient,- *,- model: str,- tokens_saved: int,- input_tokens: int = 120,-) -> None:- proxy = client.app.state.proxy- if proxy.cost_tracker:- proxy.cost_tracker.record_tokens(model, tokens_saved, input_tokens)- asyncio.run(- proxy.metrics.record_request(- provider="openai",- model=model,- input_tokens=input_tokens,- output_tokens=24,- tokens_saved=tokens_saved,- latency_ms=15.0,- )- )---def test_savings_tracker_helpers_normalize_inputs_and_paths(tmp_path, monkeypatch):- override_path = tmp_path / "custom-savings.json"- monkeypatch.setenv(HEADROOM_SAVINGS_PATH_ENV_VAR, str(override_path))- assert savings_tracker_module.get_default_savings_storage_path() == str(override_path)-- monkeypatch.delenv(HEADROOM_SAVINGS_PATH_ENV_VAR, raising=False)- default_path = savings_tracker_module.get_default_savings_storage_path()- assert Path(default_path).as_posix().endswith(".headroom/proxy_savings.json")-- assert savings_tracker_module._parse_timestamp("") is None- assert savings_tracker_module._parse_timestamp("not-a-timestamp") is None- assert savings_tracker_module._parse_timestamp("2026-03-27T09:00:00") == datetime(- 2026, 3, 27, 9, 0, tzinfo=timezone.utc- )-- assert savings_tracker_module._coerce_int("7") == 7- assert savings_tracker_module._coerce_int(-5) == 0- assert savings_tracker_module._coerce_float("0.25") == pytest.approx(0.25)- assert savings_tracker_module._coerce_float(-0.25) == 0.0-- assert savings_tracker_module._normalize_history_entry(- ["2026-03-27T09:00:00Z", "12", "0.5"]- ) == {- "timestamp": "2026-03-27T09:00:00Z",- "total_tokens_saved": 12,- "compression_savings_usd": 0.5,- "total_input_tokens": 0,- "total_input_cost_usd": 0.0,- }- assert savings_tracker_module._normalize_history_entry({"timestamp": "bad"}) is None- assert savings_tracker_module._normalize_history_entry(object()) is None---def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):- path = tmp_path / "proxy_savings.json"- path.write_text(- json.dumps(- {- "schema_version": 0,- "lifetime": {- "tokens_saved": 1,- "compression_savings_usd": 0.001,- },- "history": [- ["2026-03-24T08:00:00Z", 10, 0.01],- {- "timestamp": "2026-03-26T12:00:00Z",- "total_tokens_saved": 20,- "compression_savings_usd": 0.02,- },- {- "timestamp": "2026-03-27T09:00:00Z",- "total_tokens_saved": 30,- "compression_savings_usd": 0.03,- },- {"timestamp": "bad", "total_tokens_saved": 999},- ],- }- ),- encoding="utf-8",- )-- tracker = SavingsTracker(- path=str(path),- max_history_points=1,- max_history_age_days=2,- )- snapshot = tracker.snapshot()-- assert snapshot["schema_version"] == 2- assert snapshot["lifetime"] == {- "requests": 0,- "tokens_saved": 30,- "compression_savings_usd": pytest.approx(0.03),- "total_input_tokens": 0,- "total_input_cost_usd": 0.0,- }- assert snapshot["display_session"] == savings_tracker_module._empty_display_session()- assert snapshot["history"] == [- {- "timestamp": "2026-03-27T09:00:00Z",- "total_tokens_saved": 30,- "compression_savings_usd": 0.03,- "total_input_tokens": 0,- "total_input_cost_usd": 0.0,- }- ]- assert snapshot["retention"] == {- "max_history_points": 1,- "max_history_age_days": 2,- "max_response_history_points": 500,- }---def test_non_dict_savings_state_resets_to_default(tmp_path):- path = tmp_path / "proxy_savings.json"- path.write_text("[]", encoding="utf-8")-- tracker = SavingsTracker(path=str(path))- snapshot = tracker.snapshot()-- assert snapshot["lifetime"] == {- "requests": 0,- "tokens_saved": 0,- "compression_savings_usd": 0.0,- "total_input_tokens": 0,- "total_input_cost_usd": 0.0,- }- assert snapshot["display_session"] == savings_tracker_module._empty_display_session()- assert snapshot["history"] == []---def test_record_compression_savings_skips_empty_updates_and_normalizes_timestamps(- tmp_path, monkeypatch-):- path = tmp_path / "proxy_savings.json"- tracker = SavingsTracker(path=str(path))- monkeypatch.setattr(- savings_tracker_module,- "_estimate_compression_savings_usd",- lambda model, tokens_saved: tokens_saved / 1000.0,- )-- assert tracker.record_compression_savings(model="gpt-4o", tokens_saved=0) is False- assert not path.exists()-- local_time = datetime(2026, 3, 27, 10, 0, tzinfo=timezone(timedelta(hours=2)))- assert tracker.record_compression_savings(- model="gpt-4o",- tokens_saved=10,- total_input_tokens=120,- total_input_cost_usd=0.24,- timestamp=local_time,- )-- fallback_time = datetime(2026, 3, 27, 12, 34, tzinfo=timezone.utc)- monkeypatch.setattr(savings_tracker_module, "_utc_now", lambda: fallback_time)- assert tracker.record_compression_savings(- model="gpt-4o",- tokens_saved=5,- total_input_tokens=180,- total_input_cost_usd=0.36,- timestamp="not-a-timestamp",- )-- snapshot = tracker.snapshot()- assert snapshot["history"] == [- {- "timestamp": "2026-03-27T08:00:00Z",- "total_tokens_saved": 10,- "compression_savings_usd": 0.01,- "total_input_tokens": 120,- "total_input_cost_usd": 0.24,- },- {- "timestamp": "2026-03-27T12:34:00Z",- "total_tokens_saved": 15,- "compression_savings_usd": 0.015,- "total_input_tokens": 180,- "total_input_cost_usd": 0.36,- },- ]-- persisted = json.loads(path.read_text(encoding="utf-8"))- assert persisted["lifetime"]["tokens_saved"] == 15- assert persisted["lifetime"]["total_input_tokens"] == 180- assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.36)- assert persisted["history"][-1]["timestamp"] == "2026-03-27T12:34:00Z"---def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):- def fake_cost_per_token(*, model, prompt_tokens, completion_tokens):- if model in {"gpt-4o", "anthropic/claude-sonnet-4-6"}:- return {- "model": model,- "prompt_tokens": prompt_tokens,- "completion_tokens": completion_tokens,- }- raise RuntimeError("unknown model")-- fake_litellm = SimpleNamespace(- cost_per_token=fake_cost_per_token,- model_cost={- "anthropic/claude-sonnet-4-6": {"input_cost_per_token": 0.002},- "gpt-4o": {"input_cost_per_token": 0.001},- },- )- monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", True)- monkeypatch.setattr(savings_tracker_module, "litellm", fake_litellm)-- assert savings_tracker_module._resolve_litellm_model("gpt-4o") == "gpt-4o"- assert (- savings_tracker_module._resolve_litellm_model("claude-sonnet-4-6")- == "anthropic/claude-sonnet-4-6"- )- assert savings_tracker_module._estimate_compression_savings_usd(- "claude-sonnet-4-6", 100- ) == pytest.approx(0.2)- assert savings_tracker_module._estimate_input_cost_usd(- "claude-sonnet-4-6",- 100,- cache_read_tokens=10,- cache_write_tokens=5,- uncached_input_tokens=85,- ) == pytest.approx(0.2)-- fake_litellm.model_cost = {}- assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0- assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0-- monkeypatch.setattr(- fake_litellm,- "cost_per_token",- lambda **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),- )- assert savings_tracker_module._resolve_litellm_model("mystery-model") == "mystery-model"- assert savings_tracker_module._estimate_compression_savings_usd("mystery-model", 100) == 0.0-- monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", False)- assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0- assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0---def test_display_session_rolls_after_inactivity_and_counts_zero_savings_requests(- tmp_path, monkeypatch-):- path = tmp_path / "proxy_savings.json"- tracker = SavingsTracker(path=str(path), display_session_inactivity_minutes=30)- monkeypatch.setattr(- savings_tracker_module,- "_estimate_compression_savings_usd",- lambda model, tokens_saved: tokens_saved / 1000.0,- )- monkeypatch.setattr(- savings_tracker_module,- "_estimate_input_cost_usd",- lambda model, input_tokens, **kwargs: input_tokens / 1000.0,- )-- tracker.record_request(- model="gpt-4o",- input_tokens=120,- tokens_saved=0,- timestamp="2026-03-27T09:00:00Z",- )- tracker.record_request(- model="gpt-4o",- input_tokens=80,- tokens_saved=20,- timestamp="2026-03-27T09:10:00Z",- )-- monkeypatch.setattr(- savings_tracker_module,- "_utc_now",- lambda: datetime(2026, 3, 27, 9, 15, tzinfo=timezone.utc),- )- active_session = tracker.snapshot()["display_session"]- assert active_session == {- "requests": 2,- "tokens_saved": 20,- "compression_savings_usd": pytest.approx(0.02),- "total_input_tokens": 200,- "total_input_cost_usd": pytest.approx(0.2),- "savings_percent": pytest.approx(9.09),- "started_at": "2026-03-27T09:00:00Z",- "last_activity_at": "2026-03-27T09:10:00Z",- }-- monkeypatch.setattr(- savings_tracker_module,- "_utc_now",- lambda: datetime(2026, 3, 27, 9, 45, tzinfo=timezone.utc),- )- assert tracker.snapshot()["display_session"] == savings_tracker_module._empty_display_session()-- tracker.record_request(- model="gpt-4o",- input_tokens=50,- tokens_saved=5,- timestamp="2026-03-27T10:05:00Z",- )-- monkeypatch.setattr(- savings_tracker_module,- "_utc_now",- lambda: datetime(2026, 3, 27, 10, 10, tzinfo=timezone.utc),- )- rolled = tracker.snapshot()- assert rolled["lifetime"]["requests"] == 3- assert rolled["display_session"] == {- "requests": 1,- "tokens_saved": 5,- "compression_savings_usd": pytest.approx(0.005),- "total_input_tokens": 50,- "total_input_cost_usd": pytest.approx(0.05),- "savings_percent": pytest.approx(9.09),- "started_at": "2026-03-27T10:05:00Z",- "last_activity_at": "2026-03-27T10:05:00Z",- }---def test_savings_tracker_rollups_preserve_spend_and_input_history(tmp_path, monkeypatch):- path = tmp_path / "proxy_savings.json"- tracker = SavingsTracker(- path=str(path),- max_history_points=100,- max_history_age_days=30,- )- monkeypatch.setattr(- "headroom.proxy.savings_tracker._estimate_compression_savings_usd",- lambda model, tokens_saved: tokens_saved / 1000.0,- )-- tracker.record_compression_savings(- model="gpt-4o",- tokens_saved=100,- total_input_tokens=120,- total_input_cost_usd=0.24,- timestamp="2026-03-27T09:10:00Z",- )- tracker.record_compression_savings(- model="gpt-4o",- tokens_saved=50,- total_input_tokens=210,- total_input_cost_usd=0.42,- timestamp="2026-03-27T09:40:00Z",- )- tracker.record_compression_savings(- model="gpt-4o",- tokens_saved=25,- total_input_tokens=300,- total_input_cost_usd=0.63,- timestamp="2026-03-27T10:05:00Z",- )- tracker.record_compression_savings(- model="gpt-4o",- tokens_saved=10,- total_input_tokens=360,- total_input_cost_usd=0.75,- timestamp="2026-03-28T08:00:00Z",- )- tracker.record_compression_savings(- model="gpt-4o",- tokens_saved=20,- total_input_tokens=450,- total_input_cost_usd=0.93,- timestamp="2026-04-02T14:00:00Z",- )-- response = tracker.history_response()-- assert response["lifetime"]["tokens_saved"] == 205- assert response["lifetime"]["compression_savings_usd"] == pytest.approx(0.205)- assert response["lifetime"]["total_input_tokens"] == 450- assert response["lifetime"]["total_input_cost_usd"] == pytest.approx(0.93)- assert len(response["history"]) == 5-- hourly = response["series"]["hourly"]- assert [point["timestamp"] for point in hourly] == [- "2026-03-27T09:00:00Z",- "2026-03-27T10:00:00Z",- "2026-03-28T08:00:00Z",- "2026-04-02T14:00:00Z",- ]- assert hourly[0]["tokens_saved"] == 150- assert hourly[0]["total_tokens_saved"] == 150- assert hourly[0]["total_input_tokens_delta"] == 210- assert hourly[0]["total_input_tokens"] == 210- assert hourly[0]["total_input_cost_usd_delta"] == pytest.approx(0.42)- assert hourly[0]["total_input_cost_usd"] == pytest.approx(0.42)- assert hourly[1]["tokens_saved"] == 25- assert hourly[1]["total_tokens_saved"] == 175- assert hourly[1]["total_input_tokens_delta"] == 90- assert hourly[1]["total_input_tokens"] == 300- assert hourly[1]["total_input_cost_usd_delta"] == pytest.approx(0.21)- assert hourly[1]["total_input_cost_usd"] == pytest.approx(0.63)- assert hourly[2]["tokens_saved"] == 10- assert hourly[2]["total_tokens_saved"] == 185- assert hourly[2]["total_input_tokens_delta"] == 60- assert hourly[2]["total_input_tokens"] == 360- assert hourly[2]["total_input_cost_usd_delta"] == pytest.approx(0.12)- assert hourly[2]["total_input_cost_usd"] == pytest.approx(0.75)- assert hourly[3]["tokens_saved"] == 20- assert hourly[3]["total_tokens_saved"] == 205- assert hourly[3]["total_input_tokens_delta"] == 90- assert hourly[3]["total_input_tokens"] == 450- assert hourly[3]["total_input_cost_usd_delta"] == pytest.approx(0.18)- assert hourly[3]["total_input_cost_usd"] == pytest.approx(0.93)-- daily = response["series"]["daily"]- assert [point["timestamp"] for point in daily] == [- "2026-03-27T00:00:00Z",- "2026-03-28T00:00:00Z",- "2026-04-02T00:00:00Z",- ]- assert daily[0]["tokens_saved"] == 175- assert daily[0]["total_tokens_saved"] == 175- assert daily[0]["total_input_tokens_delta"] == 300- assert daily[0]["total_input_tokens"] == 300- assert daily[0]["total_input_cost_usd_delta"] == pytest.approx(0.63)- assert daily[0]["total_input_cost_usd"] == pytest.approx(0.63)- assert daily[1]["tokens_saved"] == 10- assert daily[1]["total_tokens_saved"] == 185- assert daily[1]["total_input_tokens_delta"] == 60- assert daily[1]["total_input_tokens"] == 360- assert daily[1]["total_input_cost_usd_delta"] == pytest.approx(0.12)- assert daily[1]["total_input_cost_usd"] == pytest.approx(0.75)- assert daily[2]["tokens_saved"] == 20- assert daily[2]["total_tokens_saved"] == 205- assert daily[2]["total_input_tokens_delta"] == 90- assert daily[2]["total_input_tokens"] == 450- assert daily[2]["total_input_cost_usd_delta"] == pytest.approx(0.18)- assert daily[2]["total_input_cost_usd"] == pytest.approx(0.93)-- weekly = response["series"]["weekly"]- assert [point["timestamp"] for point in weekly] == [- "2026-03-23T00:00:00Z",- "2026-03-30T00:00:00Z",- ]- assert weekly[0]["tokens_saved"] == 185- assert weekly[0]["total_tokens_saved"] == 185- assert weekly[1]["tokens_saved"] == 20- assert weekly[1]["total_tokens_saved"] == 205-- monthly = response["series"]["monthly"]- assert [point["timestamp"] for point in monthly] == [- "2026-03-01T00:00:00Z",- "2026-04-01T00:00:00Z",- ]- assert monthly[0]["tokens_saved"] == 185- assert monthly[0]["total_tokens_saved"] == 185- assert monthly[1]["tokens_saved"] == 20- assert monthly[1]["total_tokens_saved"] == 205-- assert response["exports"]["available_formats"] == ["json", "csv"]- assert response["exports"]["available_series"] == [- "history",- "hourly",- "daily",- "weekly",- "monthly",- ]---def test_stats_history_defaults_to_compact_history_but_can_return_full_history(- tmp_path, monkeypatch-):- path = tmp_path / "proxy_savings.json"- tracker = SavingsTracker(- path=str(path),- max_history_points=100,- max_history_age_days=30,- max_response_history_points=5,- )- monkeypatch.setattr(- "headroom.proxy.savings_tracker._estimate_compression_savings_usd",- lambda model, tokens_saved: tokens_saved / 1000.0,- )-- for i in range(8):- tracker.record_compression_savings(- model="gpt-4o",- tokens_saved=10,- total_input_tokens=(i + 1) * 100,- total_input_cost_usd=(i + 1) * 0.1,- timestamp=f"2026-03-27T09:{i:02d}:00Z",- )-- compact = tracker.history_response()- assert compact["history_summary"] == {- "mode": "compact",- "stored_points": 8,- "returned_points": 5,- "compacted": True,- }- assert len(compact["history"]) == 5- assert compact["history"][0]["timestamp"] == "2026-03-27T09:00:00Z"- assert compact["history"][-1]["timestamp"] == "2026-03-27T09:07:00Z"-- full = tracker.history_response(history_mode="full")- assert full["history_summary"] == {- "mode": "full",- "stored_points": 8,- "returned_points": 8,- "compacted": False,- }- assert len(full["history"]) == 8-- none = tracker.history_response(history_mode="none")- assert none["history"] == []- assert none["history_summary"] == {- "mode": "none",- "stored_points": 8,- "returned_points": 0,- "compacted": True,- }---def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_path, monkeypatch):- savings_path = tmp_path / "proxy_savings.json"- monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))- monkeypatch.setattr(- "headroom.proxy.server.CostTracker._get_cache_prices",- lambda self, model: (0.001, 0.0015, 0.002),- )-- config = ProxyConfig(- cache_enabled=False,- rate_limit_enabled=False,- log_requests=False,- )-- with TestClient(create_app(config)) as client:- _record_request(client, model="gpt-4o", tokens_saved=40)-- stats = client.get("/stats")- assert stats.status_code == 200- stats_data = stats.json()- assert "savings_history" in stats_data- assert "persistent_savings" in stats_data- assert all(len(point) == 2 for point in stats_data["savings_history"])- assert stats_data["persistent_savings"]["lifetime"]["tokens_saved"] == 40- assert stats_data["persistent_savings"]["storage_path"] == str(savings_path)-- history = client.get("/stats-history")- assert history.status_code == 200- history_data = history.json()- assert history_data["schema_version"] == 2- assert history_data["storage_path"] == str(savings_path)- assert history_data["lifetime"]["tokens_saved"] == 40- assert history_data["lifetime"]["total_input_tokens"] == 120- assert history_data["lifetime"]["total_input_cost_usd"] == pytest.approx(0.24)- assert history_data["display_session"]["requests"] == 1- assert history_data["display_session"]["tokens_saved"] == 40- assert history_data["display_session"]["total_input_tokens"] == 120- assert history_data["display_session"]["savings_percent"] == pytest.approx(25.0)- assert list(history_data["series"].keys()) == [- "hourly",- "daily",- "weekly",- "monthly",- ]- assert history_data["exports"]["available_series"][-2:] == ["weekly", "monthly"]- assert history_data["series"]["hourly"][0]["total_input_tokens_delta"] == 120- assert history_data["series"]["hourly"][0]["total_input_cost_usd_delta"] == pytest.approx(- 0.24- )- assert history_data["history_summary"] == {- "mode": "compact",- "stored_points": 1,- "returned_points": 1,- "compacted": False,- }-- assert stats_data["display_session"] == history_data["display_session"]- assert (- stats_data["persistent_savings"]["display_session"] == history_data["display_session"]- )-- with TestClient(create_app(config)) as client:- history = client.get("/stats-history")- assert history.status_code == 200- assert history.json()["lifetime"]["tokens_saved"] == 40- assert history.json()["display_session"]["requests"] == 1-- _record_request(client, model="gpt-4o", tokens_saved=15)-- updated = client.get("/stats-history").json()- assert updated["lifetime"]["tokens_saved"] == 55- assert updated["lifetime"]["total_input_tokens"] == 240- assert updated["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)- assert updated["lifetime"]["requests"] == 2- assert len(updated["history"]) == 2- assert updated["display_session"]["requests"] == 2- assert updated["display_session"]["tokens_saved"] == 55- assert updated["display_session"]["total_input_tokens"] == 240- assert updated["display_session"]["savings_percent"] == pytest.approx(18.64)- assert updated["series"]["daily"][0]["total_input_tokens_delta"] == 240- assert updated["series"]["daily"][0]["total_input_cost_usd_delta"] == pytest.approx(0.48)-- full = client.get("/stats-history?history_mode=full").json()- assert full["history_summary"]["mode"] == "full"- assert full["history_summary"]["stored_points"] == 2- assert full["history_summary"]["returned_points"] == 2-- persisted = json.loads(savings_path.read_text())- assert persisted["lifetime"]["tokens_saved"] == 55- assert persisted["lifetime"]["total_input_tokens"] == 240- assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)- assert persisted["display_session"]["requests"] == 2---def test_stats_history_csv_export_is_frontend_friendly(tmp_path, monkeypatch):- savings_path = tmp_path / "proxy_savings.json"- monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))- monkeypatch.setattr(- "headroom.proxy.server.CostTracker._get_cache_prices",- lambda self, model: (0.001, 0.0015, 0.002),- )-- config = ProxyConfig(- cache_enabled=False,- rate_limit_enabled=False,- log_requests=False,- )-- with TestClient(create_app(config)) as client:- _record_request(client, model="gpt-4o", tokens_saved=40)- _record_request(client, model="gpt-4o", tokens_saved=10)-- response = client.get("/stats-history?format=csv&series=daily")- assert response.status_code == 200- assert response.headers["content-type"].startswith("text/csv")- assert (- 'attachment; filename="headroom-stats-history-daily.csv"'- == response.headers["content-disposition"]- )- lines = response.text.strip().splitlines()- assert lines[0] == (- "timestamp,tokens_saved,compression_savings_usd_delta,total_tokens_saved,"- "compression_savings_usd,total_input_tokens_delta,total_input_tokens,"- "total_input_cost_usd_delta,total_input_cost_usd"- )- assert len(lines) >= 2- assert "total_tokens_saved" in lines[0]- assert "total_input_cost_usd" in lines[0]---def test_malformed_savings_state_is_ignored_safely(tmp_path, monkeypatch):- savings_path = tmp_path / "proxy_savings.json"- savings_path.write_text("{not valid json", encoding="utf-8")- monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))-- config = ProxyConfig(- cache_enabled=False,- rate_limit_enabled=False,- log_requests=False,- )-- with TestClient(create_app(config)) as client:- response = client.get("/stats-history")- assert response.status_code == 200- data = response.json()- assert data["lifetime"]["tokens_saved"] == 0- assert data["history"] == []---def test_dashboard_includes_history_toggle_and_endpoint(tmp_path, monkeypatch):- savings_path = tmp_path / "proxy_savings.json"- monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))-- config = ProxyConfig(- cache_enabled=False,- rate_limit_enabled=False,- log_requests=False,- )-- with TestClient(create_app(config)) as client:- response = client.get("/dashboard")- assert response.status_code == 200- html = response.text- assert "Session" in html- assert "Historical" in html- assert "fetch('/stats-history')" in html- assert "Export CSV" in html- assert "Weekly Savings" in html- assert "Monthly Savings" in html+"""Tests for durable proxy savings history."""++from __future__ import annotations++import asyncio+import json+from datetime import datetime, timedelta, timezone+from pathlib import Path+from types import SimpleNamespace++import pytest++pytest.importorskip("fastapi")++from fastapi.testclient import TestClient++import headroom.proxy.savings_tracker as savings_tracker_module+from headroom.proxy.savings_tracker import HEADROOM_SAVINGS_PATH_ENV_VAR, SavingsTracker+from headroom.proxy.server import ProxyConfig, create_app+++def _record_request(+ client: TestClient,+ *,+ model: str,+ tokens_saved: int,+ input_tokens: int = 120,+) -> None:+ proxy = client.app.state.proxy+ if proxy.cost_tracker:+ proxy.cost_tracker.record_tokens(model, tokens_saved, input_tokens)+ asyncio.run(+ proxy.metrics.record_request(+ provider="openai",+ model=model,+ input_tokens=input_tokens,+ output_tokens=24,+ tokens_saved=tokens_saved,+ latency_ms=15.0,+ )+ )+++def test_savings_tracker_helpers_normalize_inputs_and_paths(tmp_path, monkeypatch):+ override_path = tmp_path / "custom-savings.json"+ monkeypatch.setenv(HEADROOM_SAVINGS_PATH_ENV_VAR, str(override_path))+ assert savings_tracker_module.get_default_savings_storage_path() == str(override_path)++ monkeypatch.delenv(HEADROOM_SAVINGS_PATH_ENV_VAR, raising=False)+ default_path = savings_tracker_module.get_default_savings_storage_path()+ assert Path(default_path).as_posix().endswith(".headroom/proxy_savings.json")++ assert savings_tracker_module._parse_timestamp("") is None+ assert savings_tracker_module._parse_timestamp("not-a-timestamp") is None+ assert savings_tracker_module._parse_timestamp("2026-03-27T09:00:00") == datetime(+ 2026, 3, 27, 9, 0, tzinfo=timezone.utc+ )++ assert savings_tracker_module._coerce_int("7") == 7+ assert savings_tracker_module._coerce_int(-5) == 0+ assert savings_tracker_module._coerce_float("0.25") == pytest.approx(0.25)+ assert savings_tracker_module._coerce_float(-0.25) == 0.0++ assert savings_tracker_module._normalize_history_entry(+ ["2026-03-27T09:00:00Z", "12", "0.5"]+ ) == {+ "timestamp": "2026-03-27T09:00:00Z",+ "total_tokens_saved": 12,+ "compression_savings_usd": 0.5,+ "total_input_tokens": 0,+ "total_input_cost_usd": 0.0,+ }+ assert savings_tracker_module._normalize_history_entry({"timestamp": "bad"}) is None+ assert savings_tracker_module._normalize_history_entry(object()) is None+++def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):+ path = tmp_path / "proxy_savings.json"+ path.write_text(+ json.dumps(+ {+ "schema_version": 0,+ "lifetime": {+ "tokens_saved": 1,+ "compression_savings_usd": 0.001,+ },+ "history": [+ ["2026-03-24T08:00:00Z", 10, 0.01],+ {+ "timestamp": "2026-03-26T12:00:00Z",+ "total_tokens_saved": 20,+ "compression_savings_usd": 0.02,+ },+ {+ "timestamp": "2026-03-27T09:00:00Z",+ "total_tokens_saved": 30,+ "compression_savings_usd": 0.03,+ },+ {"timestamp": "bad", "total_tokens_saved": 999},+ ],+ }+ ),+ encoding="utf-8",+ )++ tracker = SavingsTracker(+ path=str(path),+ max_history_points=1,+ max_history_age_days=2,+ )+ snapshot = tracker.snapshot()++ assert snapshot["schema_version"] == 2+ assert snapshot["lifetime"] == {+ "requests": 0,+ "tokens_saved": 30,+ "compression_savings_usd": pytest.approx(0.03),+ "total_input_tokens": 0,+ "total_input_cost_usd": 0.0,+ }+ assert snapshot["display_session"] == savings_tracker_module._empty_display_session()+ assert snapshot["history"] == [+ {+ "timestamp": "2026-03-27T09:00:00Z",+ "total_tokens_saved": 30,+ "compression_savings_usd": 0.03,+ "total_input_tokens": 0,+ "total_input_cost_usd": 0.0,+ }+ ]+ assert snapshot["retention"] == {+ "max_history_points": 1,+ "max_history_age_days": 2,+ "max_response_history_points": 500,+ }+++def test_non_dict_savings_state_resets_to_default(tmp_path):+ path = tmp_path / "proxy_savings.json"+ path.write_text("[]", encoding="utf-8")++ tracker = SavingsTracker(path=str(path))+ snapshot = tracker.snapshot()++ assert snapshot["lifetime"] == {+ "requests": 0,+ "tokens_saved": 0,+ "compression_savings_usd": 0.0,+ "total_input_tokens": 0,+ "total_input_cost_usd": 0.0,+ }+ assert snapshot["display_session"] == savings_tracker_module._empty_display_session()+ assert snapshot["history"] == []+++def test_record_compression_savings_skips_empty_updates_and_normalizes_timestamps(+ tmp_path, monkeypatch+):+ path = tmp_path / "proxy_savings.json"+ tracker = SavingsTracker(path=str(path))+ monkeypatch.setattr(+ savings_tracker_module,+ "_estimate_compression_savings_usd",+ lambda model, tokens_saved: tokens_saved / 1000.0,+ )++ assert tracker.record_compression_savings(model="gpt-4o", tokens_saved=0) is False+ assert not path.exists()++ local_time = datetime(2026, 3, 27, 10, 0, tzinfo=timezone(timedelta(hours=2)))+ assert tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=10,+ total_input_tokens=120,+ total_input_cost_usd=0.24,+ timestamp=local_time,+ )++ fallback_time = datetime(2026, 3, 27, 12, 34, tzinfo=timezone.utc)+ monkeypatch.setattr(savings_tracker_module, "_utc_now", lambda: fallback_time)+ assert tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=5,+ total_input_tokens=180,+ total_input_cost_usd=0.36,+ timestamp="not-a-timestamp",+ )++ snapshot = tracker.snapshot()+ assert snapshot["history"] == [+ {+ "timestamp": "2026-03-27T08:00:00Z",+ "total_tokens_saved": 10,+ "compression_savings_usd": 0.01,+ "total_input_tokens": 120,+ "total_input_cost_usd": 0.24,+ },+ {+ "timestamp": "2026-03-27T12:34:00Z",+ "total_tokens_saved": 15,+ "compression_savings_usd": 0.015,+ "total_input_tokens": 180,+ "total_input_cost_usd": 0.36,+ },+ ]++ persisted = json.loads(path.read_text(encoding="utf-8"))+ assert persisted["lifetime"]["tokens_saved"] == 15+ assert persisted["lifetime"]["total_input_tokens"] == 180+ assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.36)+ assert persisted["history"][-1]["timestamp"] == "2026-03-27T12:34:00Z"+++def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):+ def fake_cost_per_token(*, model, prompt_tokens, completion_tokens):+ if model in {"gpt-4o", "anthropic/claude-sonnet-4-6"}:+ return {+ "model": model,+ "prompt_tokens": prompt_tokens,+ "completion_tokens": completion_tokens,+ }+ raise RuntimeError("unknown model")++ fake_litellm = SimpleNamespace(+ cost_per_token=fake_cost_per_token,+ model_cost={+ "anthropic/claude-sonnet-4-6": {"input_cost_per_token": 0.002},+ "gpt-4o": {"input_cost_per_token": 0.001},+ },+ )+ monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", True)+ monkeypatch.setattr(savings_tracker_module, "litellm", fake_litellm)++ assert savings_tracker_module._resolve_litellm_model("gpt-4o") == "gpt-4o"+ assert (+ savings_tracker_module._resolve_litellm_model("claude-sonnet-4-6")+ == "anthropic/claude-sonnet-4-6"+ )+ assert savings_tracker_module._estimate_compression_savings_usd(+ "claude-sonnet-4-6", 100+ ) == pytest.approx(0.2)+ assert savings_tracker_module._estimate_input_cost_usd(+ "claude-sonnet-4-6",+ 100,+ cache_read_tokens=10,+ cache_write_tokens=5,+ uncached_input_tokens=85,+ ) == pytest.approx(0.2)++ fake_litellm.model_cost = {}+ assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0+ assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0++ monkeypatch.setattr(+ fake_litellm,+ "cost_per_token",+ lambda **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),+ )+ assert savings_tracker_module._resolve_litellm_model("mystery-model") == "mystery-model"+ assert savings_tracker_module._estimate_compression_savings_usd("mystery-model", 100) == 0.0++ monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", False)+ assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0+ assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0+++def test_display_session_rolls_after_inactivity_and_counts_zero_savings_requests(+ tmp_path, monkeypatch+):+ path = tmp_path / "proxy_savings.json"+ tracker = SavingsTracker(path=str(path), display_session_inactivity_minutes=30)+ monkeypatch.setattr(+ savings_tracker_module,+ "_estimate_compression_savings_usd",+ lambda model, tokens_saved: tokens_saved / 1000.0,+ )+ monkeypatch.setattr(+ savings_tracker_module,+ "_estimate_input_cost_usd",+ lambda model, input_tokens, **kwargs: input_tokens / 1000.0,+ )++ tracker.record_request(+ model="gpt-4o",+ input_tokens=120,+ tokens_saved=0,+ timestamp="2026-03-27T09:00:00Z",+ )+ tracker.record_request(+ model="gpt-4o",+ input_tokens=80,+ tokens_saved=20,+ timestamp="2026-03-27T09:10:00Z",+ )++ monkeypatch.setattr(+ savings_tracker_module,+ "_utc_now",+ lambda: datetime(2026, 3, 27, 9, 15, tzinfo=timezone.utc),+ )+ active_session = tracker.snapshot()["display_session"]+ assert active_session == {+ "requests": 2,+ "tokens_saved": 20,+ "compression_savings_usd": pytest.approx(0.02),+ "total_input_tokens": 200,+ "total_input_cost_usd": pytest.approx(0.2),+ "savings_percent": pytest.approx(9.09),+ "started_at": "2026-03-27T09:00:00Z",+ "last_activity_at": "2026-03-27T09:10:00Z",+ }++ monkeypatch.setattr(+ savings_tracker_module,+ "_utc_now",+ lambda: datetime(2026, 3, 27, 9, 45, tzinfo=timezone.utc),+ )+ assert tracker.snapshot()["display_session"] == savings_tracker_module._empty_display_session()++ tracker.record_request(+ model="gpt-4o",+ input_tokens=50,+ tokens_saved=5,+ timestamp="2026-03-27T10:05:00Z",+ )++ monkeypatch.setattr(+ savings_tracker_module,+ "_utc_now",+ lambda: datetime(2026, 3, 27, 10, 10, tzinfo=timezone.utc),+ )+ rolled = tracker.snapshot()+ assert rolled["lifetime"]["requests"] == 3+ assert rolled["display_session"] == {+ "requests": 1,+ "tokens_saved": 5,+ "compression_savings_usd": pytest.approx(0.005),+ "total_input_tokens": 50,+ "total_input_cost_usd": pytest.approx(0.05),+ "savings_percent": pytest.approx(9.09),+ "started_at": "2026-03-27T10:05:00Z",+ "last_activity_at": "2026-03-27T10:05:00Z",+ }+++def test_savings_tracker_rollups_preserve_spend_and_input_history(tmp_path, monkeypatch):+ path = tmp_path / "proxy_savings.json"+ tracker = SavingsTracker(+ path=str(path),+ max_history_points=100,+ max_history_age_days=30,+ )+ monkeypatch.setattr(+ "headroom.proxy.savings_tracker._estimate_compression_savings_usd",+ lambda model, tokens_saved: tokens_saved / 1000.0,+ )++ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=100,+ total_input_tokens=120,+ total_input_cost_usd=0.24,+ timestamp="2026-03-27T09:10:00Z",+ )+ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=50,+ total_input_tokens=210,+ total_input_cost_usd=0.42,+ timestamp="2026-03-27T09:40:00Z",+ )+ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=25,+ total_input_tokens=300,+ total_input_cost_usd=0.63,+ timestamp="2026-03-27T10:05:00Z",+ )+ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=10,+ total_input_tokens=360,+ total_input_cost_usd=0.75,+ timestamp="2026-03-28T08:00:00Z",+ )+ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=20,+ total_input_tokens=450,+ total_input_cost_usd=0.93,+ timestamp="2026-04-02T14:00:00Z",+ )++ response = tracker.history_response()++ assert response["lifetime"]["tokens_saved"] == 205+ assert response["lifetime"]["compression_savings_usd"] == pytest.approx(0.205)+ assert response["lifetime"]["total_input_tokens"] == 450+ assert response["lifetime"]["total_input_cost_usd"] == pytest.approx(0.93)+ assert len(response["history"]) == 5++ hourly = response["series"]["hourly"]+ assert [point["timestamp"] for point in hourly] == [+ "2026-03-27T09:00:00Z",+ "2026-03-27T10:00:00Z",+ "2026-03-28T08:00:00Z",+ "2026-04-02T14:00:00Z",+ ]+ assert hourly[0]["tokens_saved"] == 150+ assert hourly[0]["total_tokens_saved"] == 150+ assert hourly[0]["total_input_tokens_delta"] == 210+ assert hourly[0]["total_input_tokens"] == 210+ assert hourly[0]["total_input_cost_usd_delta"] == pytest.approx(0.42)+ assert hourly[0]["total_input_cost_usd"] == pytest.approx(0.42)+ assert hourly[1]["tokens_saved"] == 25+ assert hourly[1]["total_tokens_saved"] == 175+ assert hourly[1]["total_input_tokens_delta"] == 90+ assert hourly[1]["total_input_tokens"] == 300+ assert hourly[1]["total_input_cost_usd_delta"] == pytest.approx(0.21)+ assert hourly[1]["total_input_cost_usd"] == pytest.approx(0.63)+ assert hourly[2]["tokens_saved"] == 10+ assert hourly[2]["total_tokens_saved"] == 185+ assert hourly[2]["total_input_tokens_delta"] == 60+ assert hourly[2]["total_input_tokens"] == 360+ assert hourly[2]["total_input_cost_usd_delta"] == pytest.approx(0.12)+ assert hourly[2]["total_input_cost_usd"] == pytest.approx(0.75)+ assert hourly[3]["tokens_saved"] == 20+ assert hourly[3]["total_tokens_saved"] == 205+ assert hourly[3]["total_input_tokens_delta"] == 90+ assert hourly[3]["total_input_tokens"] == 450+ assert hourly[3]["total_input_cost_usd_delta"] == pytest.approx(0.18)+ assert hourly[3]["total_input_cost_usd"] == pytest.approx(0.93)++ daily = response["series"]["daily"]+ assert [point["timestamp"] for point in daily] == [+ "2026-03-27T00:00:00Z",+ "2026-03-28T00:00:00Z",+ "2026-04-02T00:00:00Z",+ ]+ assert daily[0]["tokens_saved"] == 175+ assert daily[0]["total_tokens_saved"] == 175+ assert daily[0]["total_input_tokens_delta"] == 300+ assert daily[0]["total_input_tokens"] == 300+ assert daily[0]["total_input_cost_usd_delta"] == pytest.approx(0.63)+ assert daily[0]["total_input_cost_usd"] == pytest.approx(0.63)+ assert daily[1]["tokens_saved"] == 10+ assert daily[1]["total_tokens_saved"] == 185+ assert daily[1]["total_input_tokens_delta"] == 60+ assert daily[1]["total_input_tokens"] == 360+ assert daily[1]["total_input_cost_usd_delta"] == pytest.approx(0.12)+ assert daily[1]["total_input_cost_usd"] == pytest.approx(0.75)+ assert daily[2]["tokens_saved"] == 20+ assert daily[2]["total_tokens_saved"] == 205+ assert daily[2]["total_input_tokens_delta"] == 90+ assert daily[2]["total_input_tokens"] == 450+ assert daily[2]["total_input_cost_usd_delta"] == pytest.approx(0.18)+ assert daily[2]["total_input_cost_usd"] == pytest.approx(0.93)++ weekly = response["series"]["weekly"]+ assert [point["timestamp"] for point in weekly] == [+ "2026-03-23T00:00:00Z",+ "2026-03-30T00:00:00Z",+ ]+ assert weekly[0]["tokens_saved"] == 185+ assert weekly[0]["total_tokens_saved"] == 185+ assert weekly[1]["tokens_saved"] == 20+ assert weekly[1]["total_tokens_saved"] == 205++ monthly = response["series"]["monthly"]+ assert [point["timestamp"] for point in monthly] == [+ "2026-03-01T00:00:00Z",+ "2026-04-01T00:00:00Z",+ ]+ assert monthly[0]["tokens_saved"] == 185+ assert monthly[0]["total_tokens_saved"] == 185+ assert monthly[1]["tokens_saved"] == 20+ assert monthly[1]["total_tokens_saved"] == 205++ assert response["exports"]["available_formats"] == ["json", "csv"]+ assert response["exports"]["available_series"] == [+ "history",+ "hourly",+ "daily",+ "weekly",+ "monthly",+ ]+++def test_stats_history_defaults_to_compact_history_but_can_return_full_history(+ tmp_path, monkeypatch+):+ path = tmp_path / "proxy_savings.json"+ tracker = SavingsTracker(+ path=str(path),+ max_history_points=100,+ max_history_age_days=30,+ max_response_history_points=5,+ )+ monkeypatch.setattr(+ "headroom.proxy.savings_tracker._estimate_compression_savings_usd",+ lambda model, tokens_saved: tokens_saved / 1000.0,+ )++ for i in range(8):+ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=10,+ total_input_tokens=(i + 1) * 100,+ total_input_cost_usd=(i + 1) * 0.1,+ timestamp=f"2026-03-27T09:{i:02d}:00Z",+ )++ compact = tracker.history_response()+ assert compact["history_summary"] == {+ "mode": "compact",+ "stored_points": 8,+ "returned_points": 5,+ "compacted": True,+ }+ assert len(compact["history"]) == 5+ assert compact["history"][0]["timestamp"] == "2026-03-27T09:00:00Z"+ assert compact["history"][-1]["timestamp"] == "2026-03-27T09:07:00Z"++ full = tracker.history_response(history_mode="full")+ assert full["history_summary"] == {+ "mode": "full",+ "stored_points": 8,+ "returned_points": 8,+ "compacted": False,+ }+ assert len(full["history"]) == 8++ none = tracker.history_response(history_mode="none")+ assert none["history"] == []+ assert none["history_summary"] == {+ "mode": "none",+ "stored_points": 8,+ "returned_points": 0,+ "compacted": True,+ }+++def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_path, monkeypatch):+ savings_path = tmp_path / "proxy_savings.json"+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))+ monkeypatch.setattr(+ "headroom.proxy.server.CostTracker._get_cache_prices",+ lambda self, model: (0.001, 0.0015, 0.002),+ )++ config = ProxyConfig(+ cache_enabled=False,+ rate_limit_enabled=False,+ log_requests=False,+ )++ with TestClient(create_app(config)) as client:+ _record_request(client, model="gpt-4o", tokens_saved=40)++ stats = client.get("/stats")+ assert stats.status_code == 200+ stats_data = stats.json()+ assert "savings_history" in stats_data+ assert "persistent_savings" in stats_data+ assert all(len(point) == 2 for point in stats_data["savings_history"])+ assert stats_data["persistent_savings"]["lifetime"]["tokens_saved"] == 40+ assert stats_data["persistent_savings"]["storage_path"] == str(savings_path)++ history = client.get("/stats-history")+ assert history.status_code == 200+ history_data = history.json()+ assert history_data["schema_version"] == 2+ assert history_data["storage_path"] == str(savings_path)+ assert history_data["lifetime"]["tokens_saved"] == 40+ assert history_data["lifetime"]["total_input_tokens"] == 120+ assert history_data["lifetime"]["total_input_cost_usd"] == pytest.approx(0.24)+ assert history_data["display_session"]["requests"] == 1+ assert history_data["display_session"]["tokens_saved"] == 40+ assert history_data["display_session"]["total_input_tokens"] == 120+ assert history_data["display_session"]["savings_percent"] == pytest.approx(25.0)+ assert list(history_data["series"].keys()) == [+ "hourly",+ "daily",+ "weekly",+ "monthly",+ ]+ assert history_data["exports"]["available_series"][-2:] == ["weekly", "monthly"]+ assert history_data["series"]["hourly"][0]["total_input_tokens_delta"] == 120+ assert history_data["series"]["hourly"][0]["total_input_cost_usd_delta"] == pytest.approx(+ 0.24+ )+ assert history_data["history_summary"] == {+ "mode": "compact",+ "stored_points": 1,+ "returned_points": 1,+ "compacted": False,+ }++ assert stats_data["display_session"] == history_data["display_session"]+ assert (+ stats_data["persistent_savings"]["display_session"] == history_data["display_session"]+ )++ with TestClient(create_app(config)) as client:+ history = client.get("/stats-history")+ assert history.status_code == 200+ assert history.json()["lifetime"]["tokens_saved"] == 40+ assert history.json()["display_session"]["requests"] == 1++ _record_request(client, model="gpt-4o", tokens_saved=15)++ updated = client.get("/stats-history").json()+ assert updated["lifetime"]["tokens_saved"] == 55+ assert updated["lifetime"]["total_input_tokens"] == 240+ assert updated["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)+ assert updated["lifetime"]["requests"] == 2+ assert len(updated["history"]) == 2+ assert updated["display_session"]["requests"] == 2+ assert updated["display_session"]["tokens_saved"] == 55+ assert updated["display_session"]["total_input_tokens"] == 240+ assert updated["display_session"]["savings_percent"] == pytest.approx(18.64)+ assert updated["series"]["daily"][0]["total_input_tokens_delta"] == 240+ assert updated["series"]["daily"][0]["total_input_cost_usd_delta"] == pytest.approx(0.48)++ full = client.get("/stats-history?history_mode=full").json()+ assert full["history_summary"]["mode"] == "full"+ assert full["history_summary"]["stored_points"] == 2+ assert full["history_summary"]["returned_points"] == 2++ persisted = json.loads(savings_path.read_text())+ assert persisted["lifetime"]["tokens_saved"] == 55+ assert persisted["lifetime"]["total_input_tokens"] == 240+ assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)+ assert persisted["display_session"]["requests"] == 2+++def test_stats_history_csv_export_is_frontend_friendly(tmp_path, monkeypatch):+ savings_path = tmp_path / "proxy_savings.json"+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))+ monkeypatch.setattr(+ "headroom.proxy.server.CostTracker._get_cache_prices",+ lambda self, model: (0.001, 0.0015, 0.002),+ )++ config = ProxyConfig(+ cache_enabled=False,+ rate_limit_enabled=False,+ log_requests=False,+ )++ with TestClient(create_app(config)) as client:+ _record_request(client, model="gpt-4o", tokens_saved=40)+ _record_request(client, model="gpt-4o", tokens_saved=10)++ response = client.get("/stats-history?format=csv&series=daily")+ assert response.status_code == 200+ assert response.headers["content-type"].startswith("text/csv")+ assert (+ 'attachment; filename="headroom-stats-history-daily.csv"'+ == response.headers["content-disposition"]+ )+ lines = response.text.strip().splitlines()+ assert lines[0] == (+ "timestamp,tokens_saved,compression_savings_usd_delta,total_tokens_saved,"+ "compression_savings_usd,total_input_tokens_delta,total_input_tokens,"+ "total_input_cost_usd_delta,total_input_cost_usd"+ )+ assert len(lines) >= 2+ assert "total_tokens_saved" in lines[0]+ assert "total_input_cost_usd" in lines[0]+++def test_malformed_savings_state_is_ignored_safely(tmp_path, monkeypatch):+ savings_path = tmp_path / "proxy_savings.json"+ savings_path.write_text("{not valid json", encoding="utf-8")+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))++ config = ProxyConfig(+ cache_enabled=False,+ rate_limit_enabled=False,+ log_requests=False,+ )++ with TestClient(create_app(config)) as client:+ response = client.get("/stats-history")+ assert response.status_code == 200+ data = response.json()+ assert data["lifetime"]["tokens_saved"] == 0+ assert data["history"] == []+++def test_dashboard_includes_history_toggle_and_endpoint(tmp_path, monkeypatch):+ savings_path = tmp_path / "proxy_savings.json"+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))++ config = ProxyConfig(+ cache_enabled=False,+ rate_limit_enabled=False,+ log_requests=False,+ )++ with TestClient(create_app(config)) as client:+ response = client.get("/dashboard")+ assert response.status_code == 200+ html = response.text+ assert "Session" in html+ assert "Historical" in html+ assert "fetch('/stats-history')" in html+ assert "Export CSV" in html+ assert "Weekly Savings" in html+ assert "Monthly Savings" in htmldiff --git a/tests/test_quota_registry.py b/tests/test_quota_registry.pyindex 7824c5970..8a3f37bd8 100644--- a/tests/test_quota_registry.py+++ b/tests/test_quota_registry.py@@ -1,263 +1,263 @@-"""Tests for the pluggable QuotaTracker / QuotaTrackerRegistry abstraction."""--from __future__ import annotations--import asyncio-from typing import Any--import pytest--from headroom.subscription.base import (- QuotaTracker,- QuotaTrackerRegistry,- get_quota_registry,- reset_quota_registry,-)--# ----------------------------------------------------------------------------# Minimal concrete trackers for test use-# ------------------------------------------------------------------------------class _AlwaysOnTracker(QuotaTracker):- key = "always_on"- label = "AlwaysOn"-- def __init__(self, stats: dict | None = None) -> None:- self._stats = stats or {"value": 1}- self.started = False- self.stopped = False-- async def start(self) -> None:- self.started = True-- async def stop(self) -> None:- self.stopped = True-- def get_stats(self) -> dict[str, Any] | None:- return self._stats---class _UnavailableTracker(QuotaTracker):- key = "unavailable"- label = "Unavailable"-- def is_available(self) -> bool:- return False-- def get_stats(self) -> dict[str, Any] | None:- return {"should_not_appear": True}---class _NoDataTracker(QuotaTracker):- key = "no_data"- label = "NoData"-- def get_stats(self) -> dict[str, Any] | None:- return None---class _PassiveTracker(QuotaTracker):- """Uses inherited no-op start/stop."""-- key = "passive"- label = "Passive"-- def get_stats(self) -> dict[str, Any] | None:- return {"passive": True}---# ----------------------------------------------------------------------------# Fixtures-# -----------------------------------------------------------------------------[email protected](autouse=True)-def fresh_registry():- """Reset the global registry before every test."""- reset_quota_registry()- yield- reset_quota_registry()---# ----------------------------------------------------------------------------# Registration tests-# ------------------------------------------------------------------------------def test_register_single_tracker():- registry = QuotaTrackerRegistry()- tracker = _AlwaysOnTracker()- registry.register(tracker)- assert registry.get("always_on") is tracker---def test_register_multiple_trackers():- registry = QuotaTrackerRegistry()- t1 = _AlwaysOnTracker()- t2 = _PassiveTracker()- registry.register(t1)- registry.register(t2)- assert len(registry.trackers) == 2---def test_duplicate_key_raises():- registry = QuotaTrackerRegistry()- registry.register(_AlwaysOnTracker())- with pytest.raises(ValueError, match="already registered"):- registry.register(_AlwaysOnTracker())---def test_get_unknown_key_returns_none():- registry = QuotaTrackerRegistry()- assert registry.get("nonexistent") is None---def test_trackers_property_is_snapshot():- registry = QuotaTrackerRegistry()- t = _AlwaysOnTracker()- registry.register(t)- snapshot = registry.trackers- # Mutations to the snapshot don't affect the registry- snapshot.clear()- assert len(registry.trackers) == 1---# ----------------------------------------------------------------------------# Lifecycle tests-# ------------------------------------------------------------------------------def test_start_all_calls_available_trackers():- registry = QuotaTrackerRegistry()- t = _AlwaysOnTracker()- registry.register(t)- asyncio.run(registry.start_all())- assert t.started is True---def test_start_all_skips_unavailable_trackers():- registry = QuotaTrackerRegistry()- unavailable = _UnavailableTracker()- registry.register(unavailable)-- # Patch start to detect if it was called- called = []-- async def _start() -> None:- called.append(True)-- unavailable.start = _start # type: ignore[method-assign]- asyncio.run(registry.start_all())- assert called == []---def test_stop_all_calls_stop_on_all_registered():- registry = QuotaTrackerRegistry()- t = _AlwaysOnTracker()- unavailable = _UnavailableTracker()- registry.register(t)- registry.register(unavailable)- asyncio.run(registry.stop_all())- assert t.stopped is True---def test_stop_all_continues_on_exception():- registry = QuotaTrackerRegistry()-- class _BrokenTracker(QuotaTracker):- key = "broken"- label = "Broken"-- async def stop(self) -> None:- raise RuntimeError("stop failed")-- def get_stats(self) -> dict | None:- return None-- registry.register(_BrokenTracker())- # Should not raise- asyncio.run(registry.stop_all())---def test_passive_tracker_start_stop_are_noops():- registry = QuotaTrackerRegistry()- t = _PassiveTracker()- registry.register(t)- asyncio.run(registry.start_all())- asyncio.run(registry.stop_all())- # No assertions needed — we verify no exception is raised---# ----------------------------------------------------------------------------# Stats tests-# ------------------------------------------------------------------------------def test_get_all_stats_includes_available_with_data():- registry = QuotaTrackerRegistry()- registry.register(_AlwaysOnTracker({"x": 1}))- stats = registry.get_all_stats()- assert "always_on" in stats- assert stats["always_on"] == {"x": 1}---def test_get_all_stats_excludes_unavailable():- registry = QuotaTrackerRegistry()- registry.register(_UnavailableTracker())- stats = registry.get_all_stats()- assert "unavailable" not in stats---def test_get_all_stats_excludes_none_data():- registry = QuotaTrackerRegistry()- registry.register(_NoDataTracker())- stats = registry.get_all_stats()- assert "no_data" not in stats---def test_get_all_stats_mixed():- registry = QuotaTrackerRegistry()- registry.register(_AlwaysOnTracker({"ok": True}))- registry.register(_UnavailableTracker())- registry.register(_NoDataTracker())- stats = registry.get_all_stats()- assert set(stats.keys()) == {"always_on"}---def test_get_stats_single_key():- registry = QuotaTrackerRegistry()- registry.register(_AlwaysOnTracker({"z": 99}))- assert registry.get_stats("always_on") == {"z": 99}---def test_get_stats_missing_key_returns_none():- registry = QuotaTrackerRegistry()- assert registry.get_stats("missing") is None---# ----------------------------------------------------------------------------# Global singleton tests-# ------------------------------------------------------------------------------def test_get_quota_registry_returns_same_instance():- r1 = get_quota_registry()- r2 = get_quota_registry()- assert r1 is r2---def test_reset_quota_registry_gives_fresh_instance():- r1 = get_quota_registry()- r1.register(_AlwaysOnTracker())- reset_quota_registry()- r2 = get_quota_registry()- assert r1 is not r2- assert len(r2.trackers) == 0---def test_reset_quota_registry_clears_registrations():- registry = get_quota_registry()- registry.register(_AlwaysOnTracker())- reset_quota_registry()- assert len(get_quota_registry().trackers) == 0+"""Tests for the pluggable QuotaTracker / QuotaTrackerRegistry abstraction."""++from __future__ import annotations++import asyncio+from typing import Any++import pytest++from headroom.subscription.base import (+ QuotaTracker,+ QuotaTrackerRegistry,+ get_quota_registry,+ reset_quota_registry,+)++# ---------------------------------------------------------------------------+# Minimal concrete trackers for test use+# ---------------------------------------------------------------------------+++class _AlwaysOnTracker(QuotaTracker):+ key = "always_on"+ label = "AlwaysOn"++ def __init__(self, stats: dict | None = None) -> None:+ self._stats = stats or {"value": 1}+ self.started = False+ self.stopped = False++ async def start(self) -> None:+ self.started = True++ async def stop(self) -> None:+ self.stopped = True++ def get_stats(self) -> dict[str, Any] | None:+ return self._stats+++class _UnavailableTracker(QuotaTracker):+ key = "unavailable"+ label = "Unavailable"++ def is_available(self) -> bool:+ return False++ def get_stats(self) -> dict[str, Any] | None:+ return {"should_not_appear": True}+++class _NoDataTracker(QuotaTracker):+ key = "no_data"+ label = "NoData"++ def get_stats(self) -> dict[str, Any] | None:+ return None+++class _PassiveTracker(QuotaTracker):+ """Uses inherited no-op start/stop."""++ key = "passive"+ label = "Passive"++ def get_stats(self) -> dict[str, Any] | None:+ return {"passive": True}+++# ---------------------------------------------------------------------------+# Fixtures+# ---------------------------------------------------------------------------++[email protected](autouse=True)+def fresh_registry():+ """Reset the global registry before every test."""+ reset_quota_registry()+ yield+ reset_quota_registry()+++# ---------------------------------------------------------------------------+# Registration tests+# ---------------------------------------------------------------------------+++def test_register_single_tracker():+ registry = QuotaTrackerRegistry()+ tracker = _AlwaysOnTracker()+ registry.register(tracker)+ assert registry.get("always_on") is tracker+++def test_register_multiple_trackers():+ registry = QuotaTrackerRegistry()+ t1 = _AlwaysOnTracker()+ t2 = _PassiveTracker()+ registry.register(t1)+ registry.register(t2)+ assert len(registry.trackers) == 2+++def test_duplicate_key_raises():+ registry = QuotaTrackerRegistry()+ registry.register(_AlwaysOnTracker())+ with pytest.raises(ValueError, match="already registered"):+ registry.register(_AlwaysOnTracker())+++def test_get_unknown_key_returns_none():+ registry = QuotaTrackerRegistry()+ assert registry.get("nonexistent") is None+++def test_trackers_property_is_snapshot():+ registry = QuotaTrackerRegistry()+ t = _AlwaysOnTracker()+ registry.register(t)+ snapshot = registry.trackers+ # Mutations to the snapshot don't affect the registry+ snapshot.clear()+ assert len(registry.trackers) == 1+++# ---------------------------------------------------------------------------+# Lifecycle tests+# ---------------------------------------------------------------------------+++def test_start_all_calls_available_trackers():+ registry = QuotaTrackerRegistry()+ t = _AlwaysOnTracker()+ registry.register(t)+ asyncio.run(registry.start_all())+ assert t.started is True+++def test_start_all_skips_unavailable_trackers():+ registry = QuotaTrackerRegistry()+ unavailable = _UnavailableTracker()+ registry.register(unavailable)++ # Patch start to detect if it was called+ called = []++ async def _start() -> None:+ called.append(True)++ unavailable.start = _start # type: ignore[method-assign]+ asyncio.run(registry.start_all())+ assert called == []+++def test_stop_all_calls_stop_on_all_registered():+ registry = QuotaTrackerRegistry()+ t = _AlwaysOnTracker()+ unavailable = _UnavailableTracker()+ registry.register(t)+ registry.register(unavailable)+ asyncio.run(registry.stop_all())+ assert t.stopped is True+++def test_stop_all_continues_on_exception():+ registry = QuotaTrackerRegistry()++ class _BrokenTracker(QuotaTracker):+ key = "broken"+ label = "Broken"++ async def stop(self) -> None:+ raise RuntimeError("stop failed")++ def get_stats(self) -> dict | None:+ return None++ registry.register(_BrokenTracker())+ # Should not raise+ asyncio.run(registry.stop_all())+++def test_passive_tracker_start_stop_are_noops():+ registry = QuotaTrackerRegistry()+ t = _PassiveTracker()+ registry.register(t)+ asyncio.run(registry.start_all())+ asyncio.run(registry.stop_all())+ # No assertions needed — we verify no exception is raised+++# ---------------------------------------------------------------------------+# Stats tests+# ---------------------------------------------------------------------------+++def test_get_all_stats_includes_available_with_data():+ registry = QuotaTrackerRegistry()+ registry.register(_AlwaysOnTracker({"x": 1}))+ stats = registry.get_all_stats()+ assert "always_on" in stats+ assert stats["always_on"] == {"x": 1}+++def test_get_all_stats_excludes_unavailable():+ registry = QuotaTrackerRegistry()+ registry.register(_UnavailableTracker())+ stats = registry.get_all_stats()+ assert "unavailable" not in stats+++def test_get_all_stats_excludes_none_data():+ registry = QuotaTrackerRegistry()+ registry.register(_NoDataTracker())+ stats = registry.get_all_stats()+ assert "no_data" not in stats+++def test_get_all_stats_mixed():+ registry = QuotaTrackerRegistry()+ registry.register(_AlwaysOnTracker({"ok": True}))+ registry.register(_UnavailableTracker())+ registry.register(_NoDataTracker())+ stats = registry.get_all_stats()+ assert set(stats.keys()) == {"always_on"}+++def test_get_stats_single_key():+ registry = QuotaTrackerRegistry()+ registry.register(_AlwaysOnTracker({"z": 99}))+ assert registry.get_stats("always_on") == {"z": 99}+++def test_get_stats_missing_key_returns_none():+ registry = QuotaTrackerRegistry()+ assert registry.get_stats("missing") is None+++# ---------------------------------------------------------------------------+# Global singleton tests+# ---------------------------------------------------------------------------+++def test_get_quota_registry_returns_same_instance():+ r1 = get_quota_registry()+ r2 = get_quota_registry()+ assert r1 is r2+++def test_reset_quota_registry_gives_fresh_instance():+ r1 = get_quota_registry()+ r1.register(_AlwaysOnTracker())+ reset_quota_registry()+ r2 = get_quota_registry()+ assert r1 is not r2+ assert len(r2.trackers) == 0+++def test_reset_quota_registry_clears_registrations():+ registry = get_quota_registry()+ registry.register(_AlwaysOnTracker())+ reset_quota_registry()+ assert len(get_quota_registry().trackers) == 0diff --git a/tests/test_release_version.py b/tests/test_release_version.pyindex 5485eeb20..4c66afa72 100644--- a/tests/test_release_version.py+++ b/tests/test_release_version.py@@ -1,186 +1,186 @@-"""Tests for release version normalization and bumping."""--import os-import subprocess-import sys-from pathlib import Path-from unittest.mock import Mock--import pytest--from headroom.release_version import (- CommitInfo,- classify_commit_bump,- compute_release_version,- determine_bump_level,- find_latest_release_tag,- get_canonical_version,- list_release_commits,- normalize_release_tag,- parse_release_tag,-)--ROOT = Path(__file__).resolve().parent.parent---def test_normalize_release_tag_preserves_three_part_tag() -> None:- assert str(normalize_release_tag("v0.5.20")) == "0.5.20"---def test_normalize_release_tag_collapses_four_part_tag() -> None:- assert str(normalize_release_tag("v0.5.25.2")) == "0.5.25"---def test_compute_patch_release_from_four_part_history() -> None:- info = compute_release_version(- canonical_version="0.5.25",- level="patch",- tags=["v0.5.20", "v0.5.25.1", "v0.5.25.2"],- )-- assert info.version == "0.5.26"- assert info.npm_version == "0.5.26"- assert info.previous_tag == "v0.5.25.2"- assert info.bump == "patch"---def test_compute_minor_release_from_four_part_history() -> None:- info = compute_release_version(- canonical_version="0.5.25",- level="minor",- tags=["v0.5.20", "v0.5.25.1", "v0.5.25.2"],- )-- assert info.version == "0.6.0"- assert info.npm_version == "0.6.0"- assert info.previous_tag == "v0.5.25.2"- assert info.bump == "minor"---def test_compute_patch_release_from_canonical_without_tags() -> None:- info = compute_release_version(- canonical_version="0.5.25",- level="patch",- tags=[],- )-- assert info.version == "0.5.26"- assert info.npm_version == "0.5.26"- assert info.previous_tag == ""---def test_manual_version_override_uses_single_semver() -> None:- info = compute_release_version(- canonical_version="0.5.25",- level="patch",- tags=["v0.5.25.2"],- manual_version="0.6.0",- )-- assert info.version == "0.6.0"- assert info.npm_version == "0.6.0"- assert info.previous_tag == ""- assert info.bump == "manual"---def test_manual_version_override_rejects_legacy_four_part_version() -> None:- with pytest.raises(ValueError, match="Invalid semantic version"):- compute_release_version(- canonical_version="0.5.25",- level="patch",- tags=["v0.5.25.2"],- manual_version="0.5.25.3",- )---def test_find_latest_release_tag_prefers_highest_normalized_version() -> None:- assert find_latest_release_tag(["v0.5.25.2", "v0.5.27", "not-a-tag"]) == "v0.5.27"---def test_find_latest_release_tag_prefers_higher_legacy_height_with_same_base() -> None:- assert find_latest_release_tag(["v0.5.25.2", "v0.5.25.3", "v0.5.25"]) == "v0.5.25.3"---def test_parse_release_tag_preserves_legacy_height_for_sorting() -> None:- tag = parse_release_tag("v0.5.25.3")- assert str(tag.version) == "0.5.25"- assert tag.legacy_height == 3---def test_classify_commit_bump_treats_breaking_change_as_major() -> None:- assert (- classify_commit_bump(- CommitInfo(subject="fix(api)!: change response shape", body=""),- )- == "major"- )---def test_determine_bump_level_uses_greatest_commit_level() -> None:- commits = [- CommitInfo(subject="fix: patch one", body=""),- CommitInfo(subject="feat: add capability", body=""),- CommitInfo(subject="chore: maintenance", body=""),- ]-- assert determine_bump_level(commits) == "minor"---def test_determine_bump_level_prefers_major_over_minor_and_patch() -> None:- commits = [- CommitInfo(subject="fix: patch one", body=""),- CommitInfo(subject="feat: add capability", body=""),- CommitInfo(- subject="docs: update migration guide",- body="BREAKING CHANGE: the API changed",- ),- ]-- assert determine_bump_level(commits) == "major"---def test_list_release_commits_parses_empty_body_entries(- monkeypatch: pytest.MonkeyPatch,-) -> None:- run = Mock()- run.return_value = Mock(- stdout="feat: add capability\x1f\x1efix: patch bug\x1fbody text\x1e",- )- monkeypatch.setattr("headroom.release_version.subprocess.run", run)-- commits = list_release_commits(ROOT, "")-- assert commits == [- CommitInfo(subject="feat: add capability", body=""),- CommitInfo(subject="fix: patch bug", body="body text"),- ]---def test_release_version_script_runs_directly_without_importing_headroom_package(- tmp_path: Path,-) -> None:- output_path = tmp_path / "github-output.txt"- env = os.environ.copy()- env["GITHUB_OUTPUT"] = str(output_path)- env["LEVEL"] = "patch"- env["MANUAL_VER"] = "0.6.0"-- result = subprocess.run(- [sys.executable, str(ROOT / "headroom" / "release_version.py")],- cwd=ROOT,- capture_output=True,- text=True,- env=env,- check=False,- )-- assert result.returncode == 0, result.stderr- canonical_version = get_canonical_version(ROOT)- assert output_path.read_text(encoding="utf-8").splitlines() == [- "version=0.6.0",- "npm_version=0.6.0",- f"canonical={canonical_version}",- "height=0",- "bump=manual",- "previous_tag=",- ]+"""Tests for release version normalization and bumping."""++import os+import subprocess+import sys+from pathlib import Path+from unittest.mock import Mock++import pytest++from headroom.release_version import (+ CommitInfo,+ classify_commit_bump,+ compute_release_version,+ determine_bump_level,+ find_latest_release_tag,+ get_canonical_version,+ list_release_commits,+ normalize_release_tag,+ parse_release_tag,+)++ROOT = Path(__file__).resolve().parent.parent+++def test_normalize_release_tag_preserves_three_part_tag() -> None:+ assert str(normalize_release_tag("v0.5.20")) == "0.5.20"+++def test_normalize_release_tag_collapses_four_part_tag() -> None:+ assert str(normalize_release_tag("v0.5.25.2")) == "0.5.25"+++def test_compute_patch_release_from_four_part_history() -> None:+ info = compute_release_version(+ canonical_version="0.5.25",+ level="patch",+ tags=["v0.5.20", "v0.5.25.1", "v0.5.25.2"],+ )++ assert info.version == "0.5.26"+ assert info.npm_version == "0.5.26"+ assert info.previous_tag == "v0.5.25.2"+ assert info.bump == "patch"+++def test_compute_minor_release_from_four_part_history() -> None:+ info = compute_release_version(+ canonical_version="0.5.25",+ level="minor",+ tags=["v0.5.20", "v0.5.25.1", "v0.5.25.2"],+ )++ assert info.version == "0.6.0"+ assert info.npm_version == "0.6.0"+ assert info.previous_tag == "v0.5.25.2"+ assert info.bump == "minor"+++def test_compute_patch_release_from_canonical_without_tags() -> None:+ info = compute_release_version(+ canonical_version="0.5.25",+ level="patch",+ tags=[],+ )++ assert info.version == "0.5.26"+ assert info.npm_version == "0.5.26"+ assert info.previous_tag == ""+++def test_manual_version_override_uses_single_semver() -> None:+ info = compute_release_version(+ canonical_version="0.5.25",+ level="patch",+ tags=["v0.5.25.2"],+ manual_version="0.6.0",+ )++ assert info.version == "0.6.0"+ assert info.npm_version == "0.6.0"+ assert info.previous_tag == ""+ assert info.bump == "manual"+++def test_manual_version_override_rejects_legacy_four_part_version() -> None:+ with pytest.raises(ValueError, match="Invalid semantic version"):+ compute_release_version(+ canonical_version="0.5.25",+ level="patch",+ tags=["v0.5.25.2"],+ manual_version="0.5.25.3",+ )+++def test_find_latest_release_tag_prefers_highest_normalized_version() -> None:+ assert find_latest_release_tag(["v0.5.25.2", "v0.5.27", "not-a-tag"]) == "v0.5.27"+++def test_find_latest_release_tag_prefers_higher_legacy_height_with_same_base() -> None:+ assert find_latest_release_tag(["v0.5.25.2", "v0.5.25.3", "v0.5.25"]) == "v0.5.25.3"+++def test_parse_release_tag_preserves_legacy_height_for_sorting() -> None:+ tag = parse_release_tag("v0.5.25.3")+ assert str(tag.version) == "0.5.25"+ assert tag.legacy_height == 3+++def test_classify_commit_bump_treats_breaking_change_as_major() -> None:+ assert (+ classify_commit_bump(+ CommitInfo(subject="fix(api)!: change response shape", body=""),+ )+ == "major"+ )+++def test_determine_bump_level_uses_greatest_commit_level() -> None:+ commits = [+ CommitInfo(subject="fix: patch one", body=""),+ CommitInfo(subject="feat: add capability", body=""),+ CommitInfo(subject="chore: maintenance", body=""),+ ]++ assert determine_bump_level(commits) == "minor"+++def test_determine_bump_level_prefers_major_over_minor_and_patch() -> None:+ commits = [+ CommitInfo(subject="fix: patch one", body=""),+ CommitInfo(subject="feat: add capability", body=""),+ CommitInfo(+ subject="docs: update migration guide",+ body="BREAKING CHANGE: the API changed",+ ),+ ]++ assert determine_bump_level(commits) == "major"+++def test_list_release_commits_parses_empty_body_entries(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ run = Mock()+ run.return_value = Mock(+ stdout="feat: add capability\x1f\x1efix: patch bug\x1fbody text\x1e",+ )+ monkeypatch.setattr("headroom.release_version.subprocess.run", run)++ commits = list_release_commits(ROOT, "")++ assert commits == [+ CommitInfo(subject="feat: add capability", body=""),+ CommitInfo(subject="fix: patch bug", body="body text"),+ ]+++def test_release_version_script_runs_directly_without_importing_headroom_package(+ tmp_path: Path,+) -> None:+ output_path = tmp_path / "github-output.txt"+ env = os.environ.copy()+ env["GITHUB_OUTPUT"] = str(output_path)+ env["LEVEL"] = "patch"+ env["MANUAL_VER"] = "0.6.0"++ result = subprocess.run(+ [sys.executable, str(ROOT / "headroom" / "release_version.py")],+ cwd=ROOT,+ capture_output=True,+ text=True,+ env=env,+ check=False,+ )++ assert result.returncode == 0, result.stderr+ canonical_version = get_canonical_version(ROOT)+ assert output_path.read_text(encoding="utf-8").splitlines() == [+ "version=0.6.0",+ "npm_version=0.6.0",+ f"canonical={canonical_version}",+ "height=0",+ "bump=manual",+ "previous_tag=",+ ]diff --git a/tests/test_release_workflows.py b/tests/test_release_workflows.pyindex c753ff882..6cf067e7f 100644--- a/tests/test_release_workflows.py+++ b/tests/test_release_workflows.py@@ -1,62 +1,62 @@-"""Workflow regression tests for release publishing behavior."""--from __future__ import annotations--from pathlib import Path--ROOT = Path(__file__).resolve().parent.parent---def test_docker_workflow_normalizes_repository_name_for_signing() -> None:- content = (ROOT / ".github" / "workflows" / "docker.yml").read_text(encoding="utf-8")-- assert "id: image-name" in content- assert "tr '[:upper:]' '[:lower:]'" in content- assert "steps.image-name.outputs.image_name" in content---def test_release_workflow_publishes_both_node_packages_to_github_packages() -> None:- content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")-- assert "Publish ${{ env.NPM_SDK_PACKAGE }} to GitHub Package Registry" in content- assert "Publish ${{ env.NPM_OPENCLAW_PACKAGE }} to GitHub Package Registry" in content- assert "pkg.name = `@${process.env.GITHUB_PACKAGES_SCOPE}/${pkg.name}`;" in content- assert (- 'unscoped_sdk_tarball="$(npm pack --pack-destination "$assets_dir" | tail -n 1)"' in content- )- assert "SDK_TARBALL: ${{ steps.gpr-sdk-publish.outputs.unscoped_sdk_tarball }}" in content---def test_release_workflow_publishes_python_distributions_to_github_release() -> None:- content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")-- assert "Publish ${{ env.PYPI_PACKAGE }} Python distributions to GitHub Release" in content- assert (- 'gh release upload "$TAG" release-assets/*.whl release-assets/*.tar.gz --clobber' in content- )- assert "Publish Node package tarballs to GitHub Release" in content- assert 'gh release upload "$TAG" release-assets/*.tgz --clobber' in content---def test_create_release_runs_after_successful_build_even_if_other_publishes_fail() -> None:- content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")-- assert (- "needs: [detect-version, build, publish-pypi, publish-npm, publish-github-packages, publish-docker]"- in content- )- assert "always()" in content- assert "needs.build.result == 'success'" in content---def test_macos_native_wrapper_dependency_install_retries_pypi_downloads() -> None:- content = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")-- assert "python -m pip install --retries 10 --timeout 60 pytest" in content---def test_ci_commitlint_skips_default_github_merge_commits() -> None:- content = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")-- assert "github.event_name != 'push'" in content- assert "!startsWith(github.event.head_commit.message, 'Merge pull request ')" in content+"""Workflow regression tests for release publishing behavior."""++from __future__ import annotations++from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent+++def test_docker_workflow_normalizes_repository_name_for_signing() -> None:+ content = (ROOT / ".github" / "workflows" / "docker.yml").read_text(encoding="utf-8")++ assert "id: image-name" in content+ assert "tr '[:upper:]' '[:lower:]'" in content+ assert "steps.image-name.outputs.image_name" in content+++def test_release_workflow_publishes_both_node_packages_to_github_packages() -> None:+ content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")++ assert "Publish ${{ env.NPM_SDK_PACKAGE }} to GitHub Package Registry" in content+ assert "Publish ${{ env.NPM_OPENCLAW_PACKAGE }} to GitHub Package Registry" in content+ assert "pkg.name = `@${process.env.GITHUB_PACKAGES_SCOPE}/${pkg.name}`;" in content+ assert (+ 'unscoped_sdk_tarball="$(npm pack --pack-destination "$assets_dir" | tail -n 1)"' in content+ )+ assert "SDK_TARBALL: ${{ steps.gpr-sdk-publish.outputs.unscoped_sdk_tarball }}" in content+++def test_release_workflow_publishes_python_distributions_to_github_release() -> None:+ content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")++ assert "Publish ${{ env.PYPI_PACKAGE }} Python distributions to GitHub Release" in content+ assert (+ 'gh release upload "$TAG" release-assets/*.whl release-assets/*.tar.gz --clobber' in content+ )+ assert "Publish Node package tarballs to GitHub Release" in content+ assert 'gh release upload "$TAG" release-assets/*.tgz --clobber' in content+++def test_create_release_runs_after_successful_build_even_if_other_publishes_fail() -> None:+ content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")++ assert (+ "needs: [detect-version, build, publish-pypi, publish-npm, publish-github-packages, publish-docker]"+ in content+ )+ assert "always()" in content+ assert "needs.build.result == 'success'" in content+++def test_macos_native_wrapper_dependency_install_retries_pypi_downloads() -> None:+ content = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")++ assert "python -m pip install --retries 10 --timeout 60 pytest" in content+++def test_ci_commitlint_skips_default_github_merge_commits() -> None:+ content = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")++ assert "github.event_name != 'push'" in content+ assert "!startsWith(github.event.head_commit.message, 'Merge pull request ')" in contentdiff --git a/tests/test_reporting.py b/tests/test_reporting.pyindex 8a9f150c2..407bfd67c 100644--- a/tests/test_reporting.py+++ b/tests/test_reporting.py@@ -1,305 +1,305 @@-from __future__ import annotations--import builtins-import sys-from dataclasses import dataclass-from datetime import datetime, timedelta-from types import SimpleNamespace--import pytest--import headroom.reporting as reporting-from headroom.reporting import generator---@dataclass-class FakeMetrics:- request_id: str- model: str- mode: str- timestamp: datetime- tokens_input_before: int- tokens_input_after: int- cache_alignment_score: float- waste_signals: dict[str, int]---class FakeStorage:- def __init__(self, stats: dict, items: list[FakeMetrics]) -> None:- self._stats = stats- self._items = items- self.closed = False-- def get_summary_stats(self, start_time, end_time):- return dict(self._stats)-- def iter_all(self):- return iter(self._items)-- def close(self) -> None:- self.closed = True---def test_reporting_public_export() -> None:- assert reporting.generate_report is generator.generate_report- assert reporting.__all__ == ["generate_report"]---def test_get_jinja2_template_success_with_stub(monkeypatch) -> None:- class FakeTemplate:- def __init__(self, template_str: str) -> None:- self.template_str = template_str-- def render(self, **kwargs) -> str:- return f"{self.template_str}:{kwargs['name']}"-- monkeypatch.setitem(sys.modules, "jinja2", SimpleNamespace(Template=FakeTemplate))- template = generator._get_jinja2_template("hello")- assert template.render(name="world") == "hello:world"---def test_get_jinja2_template_raises_helpful_error(monkeypatch) -> None:- real_import = builtins.__import__-- def fake_import(name, globals=None, locals=None, fromlist=(), level=0):- if name == "jinja2":- raise ImportError("missing")- return real_import(name, globals, locals, fromlist, level)-- monkeypatch.setattr(builtins, "__import__", fake_import)- with pytest.raises(ImportError, match="jinja2 is required for report generation"):- generator._get_jinja2_template("ignored")---def test_build_waste_histogram_empty_and_filtered_data() -> None:- now = datetime(2026, 4, 23, 12, 0, 0)- metrics = [- FakeMetrics(- request_id="before",- model="gpt-4o",- mode="audit",- timestamp=now - timedelta(days=2),- tokens_input_before=100,- tokens_input_after=90,- cache_alignment_score=10,- waste_signals={"json_bloat": 5},- ),- FakeMetrics(- request_id="inside",- model="gpt-4o",- mode="optimize",- timestamp=now,- tokens_input_before=200,- tokens_input_after=100,- cache_alignment_score=70,- waste_signals={"json_bloat": 30, "html_noise": 10, "dynamic_date": 5},- ),- FakeMetrics(- request_id="flat",- model="gpt-4o",- mode="audit",- timestamp=now,- tokens_input_before=50,- tokens_input_after=50,- cache_alignment_score=50,- waste_signals={"whitespace": 4},- ),- FakeMetrics(- request_id="after",- model="gpt-4o",- mode="audit",- timestamp=now + timedelta(days=2),- tokens_input_before=100,- tokens_input_after=20,- cache_alignment_score=20,- waste_signals={"base64": 50},- ),- ]- histogram = generator._build_waste_histogram(- FakeStorage({}, metrics),- start_time=now - timedelta(hours=1),- end_time=now + timedelta(hours=1),- )-- assert histogram[0] == {"label": "History Bloat", "tokens": 55, "percentage": 100.0}- assert histogram[1] == pytest.approx(- {"label": "Tool JSON Bloat", "tokens": 30, "percentage": 54.54545454545454}- )- assert any(item["label"] == "HTML Noise" and item["tokens"] == 10 for item in histogram)- assert any(item["label"] == "Dynamic Dates" and item["tokens"] == 5 for item in histogram)- assert any(item["label"] == "Base64 Blobs" and item["tokens"] == 0 for item in histogram)-- empty = generator._build_waste_histogram(FakeStorage({}, []), None, None)- assert all(item["tokens"] == 0 and item["percentage"] == 0 for item in empty)---def test_get_top_waste_requests_sorts_filters_and_limits() -> None:- now = datetime(2026, 4, 23, 12, 0, 0)- metrics = [- FakeMetrics("one", "gpt-4o", "audit", now, 400, 100, 80, {}),- FakeMetrics("two", "gpt-4o-mini", "optimize", now, 350, 330, 70, {}),- FakeMetrics("three", "claude", "audit", now - timedelta(days=3), 1000, 10, 50, {}),- FakeMetrics("four", "claude", "audit", now + timedelta(days=3), 1000, 200, 40, {}),- ]- top_requests = generator._get_top_waste_requests(- FakeStorage({}, metrics),- start_time=now - timedelta(hours=1),- end_time=now + timedelta(hours=1),- limit=1,- )- assert top_requests == [- {- "request_id": "one",- "model": "gpt-4o",- "mode": "audit",- "tokens_before": 400,- "tokens_saved": 300,- "cache_alignment": 80,- }- ]---def test_generate_recommendations_for_heavy_waste_and_for_getting_started() -> None:- stats = {- "avg_cache_alignment": 40,- "audit_count": 7,- "optimize_count": 3,- "total_tokens_saved": 120000,- "estimated_savings": "$1.23",- }- histogram = [- {"label": "Tool JSON Bloat", "tokens": 15000, "percentage": 100},- {"label": "History Bloat", "tokens": 60000, "percentage": 50},- ]- recommendations = generator._generate_recommendations(stats, histogram, top_requests=[{}])- titles = [item["title"] for item in recommendations]- assert titles == [- "Improve Cache Alignment",- "Enable Tool Output Compression",- "Review Rolling Window Settings",- "Switch to Optimize Mode",- "Continue Monitoring",- ]- assert "15,000" in recommendations[1]["description"]- assert "60,000" in recommendations[2]["description"]-- starter = generator._generate_recommendations(- {- "avg_cache_alignment": 90,- "audit_count": 1,- "optimize_count": 1,- "total_tokens_saved": 0,- "estimated_savings": "$0.00",- },- [{"label": "Tool JSON Bloat", "tokens": 1, "percentage": 100}],- top_requests=[],- )- assert starter == [- {- "title": "Get Started",- "description": "No optimizations applied yet. Try setting headroom_mode='optimize' "- "on your next request to start seeing token savings.",- }- ]--- ("start_time", "end_time", "expected_period"),- [- (- datetime(2026, 4, 20, 8, 0, 0),- datetime(2026, 4, 23, 18, 0, 0),- "2026-04-20 to 2026-04-23",- ),- (datetime(2026, 4, 20, 8, 0, 0), None, "Since 2026-04-20"),- (None, datetime(2026, 4, 23, 18, 0, 0), "Until 2026-04-23"),- (None, None, "All time"),- ],-)-def test_generate_report_writes_output_and_closes_storage(- monkeypatch, tmp_path, start_time, end_time, expected_period-) -> None:- storage = FakeStorage(- {- "total_requests": 3,- "total_tokens_saved": 50,- "avg_tokens_saved": 16.6,- "total_tokens_before": 100,- "total_tokens_after": 0,- "avg_cache_alignment": 82,- "audit_count": 1,- "optimize_count": 2,- },- [],- )- render_calls: list[dict] = []-- class FakeTemplate:- def render(self, **kwargs) -> str:- render_calls.append(kwargs)- return "<html>report</html>"-- monkeypatch.setattr(generator, "create_storage", lambda store_url: storage)- monkeypatch.setattr(- generator, "_build_waste_histogram", lambda *args: [{"label": "x", "tokens": 1}]- )- monkeypatch.setattr(- generator, "_get_top_waste_requests", lambda *args, **kwargs: [{"request_id": "abc"}]- )- monkeypatch.setattr(- generator, "_generate_recommendations", lambda *args: [{"title": "Keep going"}]- )- monkeypatch.setattr(generator, "_get_jinja2_template", lambda template_str: FakeTemplate())- monkeypatch.setattr(- generator,- "estimate_cost",- lambda tokens, output_tokens, model: {100: 2.0, 0: None}[tokens],- )- monkeypatch.setattr(generator, "format_cost", lambda cost: f"${cost:.2f}")-- output_path = tmp_path / "report.html"- result = generator.generate_report(- "sqlite:///demo.db",- output_path=str(output_path),- start_time=start_time,- end_time=end_time,- )-- assert result == str(output_path)- assert output_path.read_text() == "<html>report</html>"- assert render_calls[0]["period"] == expected_period- assert render_calls[0]["stats"]["tpm_multiplier"] == 100.0- assert render_calls[0]["stats"]["estimated_savings"] == "$2.00"- assert storage.closed is True---def test_generate_report_closes_storage_when_render_fails(monkeypatch, tmp_path) -> None:- storage = FakeStorage(- {- "total_requests": 0,- "total_tokens_saved": 0,- "avg_tokens_saved": 0,- "total_tokens_before": 0,- "total_tokens_after": 0,- "avg_cache_alignment": 0,- "audit_count": 0,- "optimize_count": 0,- },- [],- )-- class FakeTemplate:- def render(self, **kwargs) -> str:- raise RuntimeError("boom")-- monkeypatch.setattr(generator, "create_storage", lambda store_url: storage)- monkeypatch.setattr(generator, "_build_waste_histogram", lambda *args: [])- monkeypatch.setattr(generator, "_get_top_waste_requests", lambda *args, **kwargs: [])- monkeypatch.setattr(generator, "_generate_recommendations", lambda *args: [])- monkeypatch.setattr(generator, "_get_jinja2_template", lambda template_str: FakeTemplate())- monkeypatch.setattr(generator, "estimate_cost", lambda *args: 0.0)- monkeypatch.setattr(generator, "format_cost", lambda cost: "$0.00")-- with pytest.raises(RuntimeError, match="boom"):- generator.generate_report("sqlite:///demo.db", output_path=str(tmp_path / "report.html"))- assert storage.closed is True+from __future__ import annotations++import builtins+import sys+from dataclasses import dataclass+from datetime import datetime, timedelta+from types import SimpleNamespace++import pytest++import headroom.reporting as reporting+from headroom.reporting import generator+++@dataclass+class FakeMetrics:+ request_id: str+ model: str+ mode: str+ timestamp: datetime+ tokens_input_before: int+ tokens_input_after: int+ cache_alignment_score: float+ waste_signals: dict[str, int]+++class FakeStorage:+ def __init__(self, stats: dict, items: list[FakeMetrics]) -> None:+ self._stats = stats+ self._items = items+ self.closed = False++ def get_summary_stats(self, start_time, end_time):+ return dict(self._stats)++ def iter_all(self):+ return iter(self._items)++ def close(self) -> None:+ self.closed = True+++def test_reporting_public_export() -> None:+ assert reporting.generate_report is generator.generate_report+ assert reporting.__all__ == ["generate_report"]+++def test_get_jinja2_template_success_with_stub(monkeypatch) -> None:+ class FakeTemplate:+ def __init__(self, template_str: str) -> None:+ self.template_str = template_str++ def render(self, **kwargs) -> str:+ return f"{self.template_str}:{kwargs['name']}"++ monkeypatch.setitem(sys.modules, "jinja2", SimpleNamespace(Template=FakeTemplate))+ template = generator._get_jinja2_template("hello")+ assert template.render(name="world") == "hello:world"+++def test_get_jinja2_template_raises_helpful_error(monkeypatch) -> None:+ real_import = builtins.__import__++ def fake_import(name, globals=None, locals=None, fromlist=(), level=0):+ if name == "jinja2":+ raise ImportError("missing")+ return real_import(name, globals, locals, fromlist, level)++ monkeypatch.setattr(builtins, "__import__", fake_import)+ with pytest.raises(ImportError, match="jinja2 is required for report generation"):+ generator._get_jinja2_template("ignored")+++def test_build_waste_histogram_empty_and_filtered_data() -> None:+ now = datetime(2026, 4, 23, 12, 0, 0)+ metrics = [+ FakeMetrics(+ request_id="before",+ model="gpt-4o",+ mode="audit",+ timestamp=now - timedelta(days=2),+ tokens_input_before=100,+ tokens_input_after=90,+ cache_alignment_score=10,+ waste_signals={"json_bloat": 5},+ ),+ FakeMetrics(+ request_id="inside",+ model="gpt-4o",+ mode="optimize",+ timestamp=now,+ tokens_input_before=200,+ tokens_input_after=100,+ cache_alignment_score=70,+ waste_signals={"json_bloat": 30, "html_noise": 10, "dynamic_date": 5},+ ),+ FakeMetrics(+ request_id="flat",+ model="gpt-4o",+ mode="audit",+ timestamp=now,+ tokens_input_before=50,+ tokens_input_after=50,+ cache_alignment_score=50,+ waste_signals={"whitespace": 4},+ ),+ FakeMetrics(+ request_id="after",+ model="gpt-4o",+ mode="audit",+ timestamp=now + timedelta(days=2),+ tokens_input_before=100,+ tokens_input_after=20,+ cache_alignment_score=20,+ waste_signals={"base64": 50},+ ),+ ]+ histogram = generator._build_waste_histogram(+ FakeStorage({}, metrics),+ start_time=now - timedelta(hours=1),+ end_time=now + timedelta(hours=1),+ )++ assert histogram[0] == {"label": "History Bloat", "tokens": 55, "percentage": 100.0}+ assert histogram[1] == pytest.approx(+ {"label": "Tool JSON Bloat", "tokens": 30, "percentage": 54.54545454545454}+ )+ assert any(item["label"] == "HTML Noise" and item["tokens"] == 10 for item in histogram)+ assert any(item["label"] == "Dynamic Dates" and item["tokens"] == 5 for item in histogram)+ assert any(item["label"] == "Base64 Blobs" and item["tokens"] == 0 for item in histogram)++ empty = generator._build_waste_histogram(FakeStorage({}, []), None, None)+ assert all(item["tokens"] == 0 and item["percentage"] == 0 for item in empty)+++def test_get_top_waste_requests_sorts_filters_and_limits() -> None:+ now = datetime(2026, 4, 23, 12, 0, 0)+ metrics = [+ FakeMetrics("one", "gpt-4o", "audit", now, 400, 100, 80, {}),+ FakeMetrics("two", "gpt-4o-mini", "optimize", now, 350, 330, 70, {}),+ FakeMetrics("three", "claude", "audit", now - timedelta(days=3), 1000, 10, 50, {}),+ FakeMetrics("four", "claude", "audit", now + timedelta(days=3), 1000, 200, 40, {}),+ ]+ top_requests = generator._get_top_waste_requests(+ FakeStorage({}, metrics),+ start_time=now - timedelta(hours=1),+ end_time=now + timedelta(hours=1),+ limit=1,+ )+ assert top_requests == [+ {+ "request_id": "one",+ "model": "gpt-4o",+ "mode": "audit",+ "tokens_before": 400,+ "tokens_saved": 300,+ "cache_alignment": 80,+ }+ ]+++def test_generate_recommendations_for_heavy_waste_and_for_getting_started() -> None:+ stats = {+ "avg_cache_alignment": 40,+ "audit_count": 7,+ "optimize_count": 3,+ "total_tokens_saved": 120000,+ "estimated_savings": "$1.23",+ }+ histogram = [+ {"label": "Tool JSON Bloat", "tokens": 15000, "percentage": 100},+ {"label": "History Bloat", "tokens": 60000, "percentage": 50},+ ]+ recommendations = generator._generate_recommendations(stats, histogram, top_requests=[{}])+ titles = [item["title"] for item in recommendations]+ assert titles == [+ "Improve Cache Alignment",+ "Enable Tool Output Compression",+ "Review Rolling Window Settings",+ "Switch to Optimize Mode",+ "Continue Monitoring",+ ]+ assert "15,000" in recommendations[1]["description"]+ assert "60,000" in recommendations[2]["description"]++ starter = generator._generate_recommendations(+ {+ "avg_cache_alignment": 90,+ "audit_count": 1,+ "optimize_count": 1,+ "total_tokens_saved": 0,+ "estimated_savings": "$0.00",+ },+ [{"label": "Tool JSON Bloat", "tokens": 1, "percentage": 100}],+ top_requests=[],+ )+ assert starter == [+ {+ "title": "Get Started",+ "description": "No optimizations applied yet. Try setting headroom_mode='optimize' "+ "on your next request to start seeing token savings.",+ }+ ]+++ ("start_time", "end_time", "expected_period"),+ [+ (+ datetime(2026, 4, 20, 8, 0, 0),+ datetime(2026, 4, 23, 18, 0, 0),+ "2026-04-20 to 2026-04-23",+ ),+ (datetime(2026, 4, 20, 8, 0, 0), None, "Since 2026-04-20"),+ (None, datetime(2026, 4, 23, 18, 0, 0), "Until 2026-04-23"),+ (None, None, "All time"),+ ],+)+def test_generate_report_writes_output_and_closes_storage(+ monkeypatch, tmp_path, start_time, end_time, expected_period+) -> None:+ storage = FakeStorage(+ {+ "total_requests": 3,+ "total_tokens_saved": 50,+ "avg_tokens_saved": 16.6,+ "total_tokens_before": 100,+ "total_tokens_after": 0,+ "avg_cache_alignment": 82,+ "audit_count": 1,+ "optimize_count": 2,+ },+ [],+ )+ render_calls: list[dict] = []++ class FakeTemplate:+ def render(self, **kwargs) -> str:+ render_calls.append(kwargs)+ return "<html>report</html>"++ monkeypatch.setattr(generator, "create_storage", lambda store_url: storage)+ monkeypatch.setattr(+ generator, "_build_waste_histogram", lambda *args: [{"label": "x", "tokens": 1}]+ )+ monkeypatch.setattr(+ generator, "_get_top_waste_requests", lambda *args, **kwargs: [{"request_id": "abc"}]+ )+ monkeypatch.setattr(+ generator, "_generate_recommendations", lambda *args: [{"title": "Keep going"}]+ )+ monkeypatch.setattr(generator, "_get_jinja2_template", lambda template_str: FakeTemplate())+ monkeypatch.setattr(+ generator,+ "estimate_cost",+ lambda tokens, output_tokens, model: {100: 2.0, 0: None}[tokens],+ )+ monkeypatch.setattr(generator, "format_cost", lambda cost: f"${cost:.2f}")++ output_path = tmp_path / "report.html"+ result = generator.generate_report(+ "sqlite:///demo.db",+ output_path=str(output_path),+ start_time=start_time,+ end_time=end_time,+ )++ assert result == str(output_path)+ assert output_path.read_text() == "<html>report</html>"+ assert render_calls[0]["period"] == expected_period+ assert render_calls[0]["stats"]["tpm_multiplier"] == 100.0+ assert render_calls[0]["stats"]["estimated_savings"] == "$2.00"+ assert storage.closed is True+++def test_generate_report_closes_storage_when_render_fails(monkeypatch, tmp_path) -> None:+ storage = FakeStorage(+ {+ "total_requests": 0,+ "total_tokens_saved": 0,+ "avg_tokens_saved": 0,+ "total_tokens_before": 0,+ "total_tokens_after": 0,+ "avg_cache_alignment": 0,+ "audit_count": 0,+ "optimize_count": 0,+ },+ [],+ )++ class FakeTemplate:+ def render(self, **kwargs) -> str:+ raise RuntimeError("boom")++ monkeypatch.setattr(generator, "create_storage", lambda store_url: storage)+ monkeypatch.setattr(generator, "_build_waste_histogram", lambda *args: [])+ monkeypatch.setattr(generator, "_get_top_waste_requests", lambda *args, **kwargs: [])+ monkeypatch.setattr(generator, "_generate_recommendations", lambda *args: [])+ monkeypatch.setattr(generator, "_get_jinja2_template", lambda template_str: FakeTemplate())+ monkeypatch.setattr(generator, "estimate_cost", lambda *args: 0.0)+ monkeypatch.setattr(generator, "format_cost", lambda cost: "$0.00")++ with pytest.raises(RuntimeError, match="boom"):+ generator.generate_report("sqlite:///demo.db", output_path=str(tmp_path / "report.html"))+ assert storage.closed is Truediff --git a/tests/test_subscription_base.py b/tests/test_subscription_base.pyindex ae73952af..6f233a6e6 100644--- a/tests/test_subscription_base.py+++ b/tests/test_subscription_base.py@@ -1,140 +1,140 @@-from __future__ import annotations--import pytest--import headroom.subscription.base as base_module-from headroom.subscription.base import (- QuotaTracker,- QuotaTrackerRegistry,- get_quota_registry,- reset_quota_registry,-)---class DummyTracker(QuotaTracker):- def __init__(- self,- key: str,- *,- label: str = "Dummy",- available: bool = True,- stats: dict | None = None,- stop_error: Exception | None = None,- ) -> None:- self._key = key- self._label = label- self._available = available- self._stats = stats- self._stop_error = stop_error- self.started = 0- self.stopped = 0-- @property- def key(self) -> str:- return self._key-- @property- def label(self) -> str:- return self._label-- def is_available(self) -> bool:- return self._available-- async def start(self) -> None:- self.started += 1-- async def stop(self) -> None:- self.stopped += 1- if self._stop_error:- raise self._stop_error-- def get_stats(self) -> dict | None:- return self._stats---class PassiveTracker(QuotaTracker):- @property- def key(self) -> str:- return "passive"-- @property- def label(self) -> str:- return "Passive"-- def get_stats(self) -> dict | None:- return {"passive": True}---def test_register_get_trackers_and_duplicate_keys() -> None:- registry = QuotaTrackerRegistry()- tracker = DummyTracker("alpha", stats={"ok": True})- registry.register(tracker)-- assert registry.get("alpha") is tracker- assert registry.get("missing") is None- assert registry.trackers == [tracker]- assert registry.get_stats("alpha") == {"ok": True}- assert registry.get_stats("missing") is None-- snapshot = registry.trackers- snapshot.clear()- assert registry.trackers == [tracker]-- with pytest.raises(ValueError, match="already registered"):- registry.register(DummyTracker("alpha"))---async def test_start_all_stop_all_and_stats_filtering() -> None:- registry = QuotaTrackerRegistry()- enabled = DummyTracker("enabled", label="Enabled", stats={"value": 1})- disabled = DummyTracker("disabled", label="Disabled", available=False, stats={"skip": True})- empty = DummyTracker("empty", label="Empty", stats=None)- broken = DummyTracker(- "broken", label="Broken", stats={"value": 2}, stop_error=RuntimeError("boom")- )-- for tracker in (enabled, disabled, empty, broken):- registry.register(tracker)-- await registry.start_all()- assert enabled.started == 1- assert disabled.started == 0- assert empty.started == 1- assert broken.started == 1-- assert registry.get_all_stats() == {- "enabled": {"value": 1},- "broken": {"value": 2},- }-- await registry.stop_all()- assert enabled.stopped == 1- assert disabled.stopped == 1- assert empty.stopped == 1- assert broken.stopped == 1---def test_quota_registry_singleton_reset() -> None:- reset_quota_registry()- base_module._registry = None- first = get_quota_registry()- second = get_quota_registry()- assert first is second-- first.register(DummyTracker("singleton"))- assert get_quota_registry().get("singleton") is not None-- reset_quota_registry()- refreshed = get_quota_registry()- assert refreshed is not first- assert refreshed.trackers == []---async def test_quota_tracker_default_methods() -> None:- tracker = PassiveTracker()- assert tracker.is_available() is True- await tracker.start()- await tracker.stop()- assert tracker.get_stats() == {"passive": True}+from __future__ import annotations++import pytest++import headroom.subscription.base as base_module+from headroom.subscription.base import (+ QuotaTracker,+ QuotaTrackerRegistry,+ get_quota_registry,+ reset_quota_registry,+)+++class DummyTracker(QuotaTracker):+ def __init__(+ self,+ key: str,+ *,+ label: str = "Dummy",+ available: bool = True,+ stats: dict | None = None,+ stop_error: Exception | None = None,+ ) -> None:+ self._key = key+ self._label = label+ self._available = available+ self._stats = stats+ self._stop_error = stop_error+ self.started = 0+ self.stopped = 0++ @property+ def key(self) -> str:+ return self._key++ @property+ def label(self) -> str:+ return self._label++ def is_available(self) -> bool:+ return self._available++ async def start(self) -> None:+ self.started += 1++ async def stop(self) -> None:+ self.stopped += 1+ if self._stop_error:+ raise self._stop_error++ def get_stats(self) -> dict | None:+ return self._stats+++class PassiveTracker(QuotaTracker):+ @property+ def key(self) -> str:+ return "passive"++ @property+ def label(self) -> str:+ return "Passive"++ def get_stats(self) -> dict | None:+ return {"passive": True}+++def test_register_get_trackers_and_duplicate_keys() -> None:+ registry = QuotaTrackerRegistry()+ tracker = DummyTracker("alpha", stats={"ok": True})+ registry.register(tracker)++ assert registry.get("alpha") is tracker+ assert registry.get("missing") is None+ assert registry.trackers == [tracker]+ assert registry.get_stats("alpha") == {"ok": True}+ assert registry.get_stats("missing") is None++ snapshot = registry.trackers+ snapshot.clear()+ assert registry.trackers == [tracker]++ with pytest.raises(ValueError, match="already registered"):+ registry.register(DummyTracker("alpha"))+++async def test_start_all_stop_all_and_stats_filtering() -> None:+ registry = QuotaTrackerRegistry()+ enabled = DummyTracker("enabled", label="Enabled", stats={"value": 1})+ disabled = DummyTracker("disabled", label="Disabled", available=False, stats={"skip": True})+ empty = DummyTracker("empty", label="Empty", stats=None)+ broken = DummyTracker(+ "broken", label="Broken", stats={"value": 2}, stop_error=RuntimeError("boom")+ )++ for tracker in (enabled, disabled, empty, broken):+ registry.register(tracker)++ await registry.start_all()+ assert enabled.started == 1+ assert disabled.started == 0+ assert empty.started == 1+ assert broken.started == 1++ assert registry.get_all_stats() == {+ "enabled": {"value": 1},+ "broken": {"value": 2},+ }++ await registry.stop_all()+ assert enabled.stopped == 1+ assert disabled.stopped == 1+ assert empty.stopped == 1+ assert broken.stopped == 1+++def test_quota_registry_singleton_reset() -> None:+ reset_quota_registry()+ base_module._registry = None+ first = get_quota_registry()+ second = get_quota_registry()+ assert first is second++ first.register(DummyTracker("singleton"))+ assert get_quota_registry().get("singleton") is not None++ reset_quota_registry()+ refreshed = get_quota_registry()+ assert refreshed is not first+ assert refreshed.trackers == []+++async def test_quota_tracker_default_methods() -> None:+ tracker = PassiveTracker()+ assert tracker.is_available() is True+ await tracker.start()+ await tracker.stop()+ assert tracker.get_stats() == {"passive": True}diff --git a/tests/test_subscription_client.py b/tests/test_subscription_client.pyindex f8056d719..65d9a8756 100644--- a/tests/test_subscription_client.py+++ b/tests/test_subscription_client.py@@ -1,179 +1,179 @@-from __future__ import annotations--import json-from pathlib import Path--import httpx-import pytest--from headroom.subscription.client import (- _BETA_HEADER,- _USAGE_URL,- SubscriptionClient,- _credentials_path,- _load_credentials_file,- read_cached_oauth_token,-)---class DummyResponse:- def __init__(self, status_code: int, data: dict | None = None) -> None:- self.status_code = status_code- self._data = data or {}-- def json(self) -> dict:- return self._data---class AsyncClientStub:- def __init__(- self,- *,- response=None,- error: Exception | None = None,- record: dict | None = None,- timeout=None,- ):- self._response = response- self._error = error- self._record = record if record is not None else {}- self._record["timeout"] = timeout-- async def __aenter__(self):- return self-- async def __aexit__(self, exc_type, exc, tb):- return False-- async def get(self, url: str, headers: dict[str, str]):- self._record["url"] = url- self._record["headers"] = headers- if self._error:- raise self._error- return self._response---def test_credentials_path_uses_env_override(- monkeypatch: pytest.MonkeyPatch, tmp_path: Path-) -> None:- monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))- assert _credentials_path() == tmp_path / ".credentials.json"---def test_load_credentials_file_handles_missing_invalid_and_valid(- monkeypatch: pytest.MonkeyPatch, tmp_path: Path-) -> None:- monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))- assert _load_credentials_file() is None-- creds_path = tmp_path / ".credentials.json"- creds_path.write_text("{invalid", encoding="utf-8")- assert _load_credentials_file() is None-- payload = {"claudeAiOauth": {"accessToken": "token-from-file"}}- creds_path.write_text(json.dumps(payload), encoding="utf-8")- assert _load_credentials_file() == payload---def test_read_cached_oauth_token_prefers_env_and_checks_expiry(- monkeypatch: pytest.MonkeyPatch,-) -> None:- monkeypatch.setenv("CLAUDE_CODE_OAUTH_TOKEN", " env-token ")- monkeypatch.setattr("headroom.subscription.client._load_credentials_file", lambda: None)- assert read_cached_oauth_token() == "env-token"-- monkeypatch.delenv("CLAUDE_CODE_OAUTH_TOKEN", raising=False)- monkeypatch.setattr(- "headroom.subscription.client._load_credentials_file",- lambda: {"claudeAiOauth": {"accessToken": "cached-token"}},- )- assert read_cached_oauth_token() == "cached-token"-- monkeypatch.setattr(- "headroom.subscription.client._load_credentials_file",- lambda: {- "claudeAiOauth": {- "accessToken": "expired-token",- "expiresAt": 59_000,- }- },- )- monkeypatch.setattr("time.time", lambda: 60)- assert read_cached_oauth_token() is None-- monkeypatch.setattr(- "headroom.subscription.client._load_credentials_file",- lambda: {"claudeAiOauth": {"accessToken": ""}},- )- assert read_cached_oauth_token() is None-- monkeypatch.setattr(- "headroom.subscription.client._load_credentials_file",- lambda: None,- )- assert read_cached_oauth_token() is None---async def test_subscription_client_fetch_handles_success_and_status_codes(- monkeypatch: pytest.MonkeyPatch,-) -> None:- record: dict = {}- monkeypatch.setattr(- "headroom.subscription.client.httpx.AsyncClient",- lambda timeout: AsyncClientStub(- response=DummyResponse(200, {"five_hour": {"total": 1}}),- record=record,- timeout=timeout,- ),- )- monkeypatch.setattr(- "headroom.subscription.client.SubscriptionSnapshot.from_api_response",- lambda data, token="": {"data": data, "token": token},- )-- client = SubscriptionClient(timeout=3.5)- result = await client.fetch(" explicit-token ")- assert result == {"data": {"five_hour": {"total": 1}}, "token": "explicit-token"}- assert record["timeout"] == 3.5- assert record["url"] == _USAGE_URL- assert record["headers"] == {- "Authorization": "Bearer explicit-token",- "anthropic-beta": _BETA_HEADER,- "Content-Type": "application/json",- }-- for status_code in (401, 404, 500):- monkeypatch.setattr(- "headroom.subscription.client.httpx.AsyncClient",- lambda timeout, status_code=status_code: AsyncClientStub(- response=DummyResponse(status_code), timeout=timeout- ),- )- assert await client.fetch("explicit-token") is None---async def test_subscription_client_fetch_uses_cached_token_and_handles_exceptions(- monkeypatch: pytest.MonkeyPatch,-) -> None:- client = SubscriptionClient()-- monkeypatch.setattr("headroom.subscription.client.read_cached_oauth_token", lambda: None)- assert await client.fetch() is None-- monkeypatch.setattr(- "headroom.subscription.client.read_cached_oauth_token",- lambda: "cached-token",- )- monkeypatch.setattr(- "headroom.subscription.client.httpx.AsyncClient",- lambda timeout: AsyncClientStub(error=httpx.TimeoutException("slow"), timeout=timeout),- )- assert await client.fetch() is None-- monkeypatch.setattr(- "headroom.subscription.client.httpx.AsyncClient",- lambda timeout: AsyncClientStub(error=RuntimeError("boom"), timeout=timeout),- )- assert await client.fetch() is None+from __future__ import annotations++import json+from pathlib import Path++import httpx+import pytest++from headroom.subscription.client import (+ _BETA_HEADER,+ _USAGE_URL,+ SubscriptionClient,+ _credentials_path,+ _load_credentials_file,+ read_cached_oauth_token,+)+++class DummyResponse:+ def __init__(self, status_code: int, data: dict | None = None) -> None:+ self.status_code = status_code+ self._data = data or {}++ def json(self) -> dict:+ return self._data+++class AsyncClientStub:+ def __init__(+ self,+ *,+ response=None,+ error: Exception | None = None,+ record: dict | None = None,+ timeout=None,+ ):+ self._response = response+ self._error = error+ self._record = record if record is not None else {}+ self._record["timeout"] = timeout++ async def __aenter__(self):+ return self++ async def __aexit__(self, exc_type, exc, tb):+ return False++ async def get(self, url: str, headers: dict[str, str]):+ self._record["url"] = url+ self._record["headers"] = headers+ if self._error:+ raise self._error+ return self._response+++def test_credentials_path_uses_env_override(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))+ assert _credentials_path() == tmp_path / ".credentials.json"+++def test_load_credentials_file_handles_missing_invalid_and_valid(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))+ assert _load_credentials_file() is None++ creds_path = tmp_path / ".credentials.json"+ creds_path.write_text("{invalid", encoding="utf-8")+ assert _load_credentials_file() is None++ payload = {"claudeAiOauth": {"accessToken": "token-from-file"}}+ creds_path.write_text(json.dumps(payload), encoding="utf-8")+ assert _load_credentials_file() == payload+++def test_read_cached_oauth_token_prefers_env_and_checks_expiry(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setenv("CLAUDE_CODE_OAUTH_TOKEN", " env-token ")+ monkeypatch.setattr("headroom.subscription.client._load_credentials_file", lambda: None)+ assert read_cached_oauth_token() == "env-token"++ monkeypatch.delenv("CLAUDE_CODE_OAUTH_TOKEN", raising=False)+ monkeypatch.setattr(+ "headroom.subscription.client._load_credentials_file",+ lambda: {"claudeAiOauth": {"accessToken": "cached-token"}},+ )+ assert read_cached_oauth_token() == "cached-token"++ monkeypatch.setattr(+ "headroom.subscription.client._load_credentials_file",+ lambda: {+ "claudeAiOauth": {+ "accessToken": "expired-token",+ "expiresAt": 59_000,+ }+ },+ )+ monkeypatch.setattr("time.time", lambda: 60)+ assert read_cached_oauth_token() is None++ monkeypatch.setattr(+ "headroom.subscription.client._load_credentials_file",+ lambda: {"claudeAiOauth": {"accessToken": ""}},+ )+ assert read_cached_oauth_token() is None++ monkeypatch.setattr(+ "headroom.subscription.client._load_credentials_file",+ lambda: None,+ )+ assert read_cached_oauth_token() is None+++async def test_subscription_client_fetch_handles_success_and_status_codes(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ record: dict = {}+ monkeypatch.setattr(+ "headroom.subscription.client.httpx.AsyncClient",+ lambda timeout: AsyncClientStub(+ response=DummyResponse(200, {"five_hour": {"total": 1}}),+ record=record,+ timeout=timeout,+ ),+ )+ monkeypatch.setattr(+ "headroom.subscription.client.SubscriptionSnapshot.from_api_response",+ lambda data, token="": {"data": data, "token": token},+ )++ client = SubscriptionClient(timeout=3.5)+ result = await client.fetch(" explicit-token ")+ assert result == {"data": {"five_hour": {"total": 1}}, "token": "explicit-token"}+ assert record["timeout"] == 3.5+ assert record["url"] == _USAGE_URL+ assert record["headers"] == {+ "Authorization": "Bearer explicit-token",+ "anthropic-beta": _BETA_HEADER,+ "Content-Type": "application/json",+ }++ for status_code in (401, 404, 500):+ monkeypatch.setattr(+ "headroom.subscription.client.httpx.AsyncClient",+ lambda timeout, status_code=status_code: AsyncClientStub(+ response=DummyResponse(status_code), timeout=timeout+ ),+ )+ assert await client.fetch("explicit-token") is None+++async def test_subscription_client_fetch_uses_cached_token_and_handles_exceptions(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ client = SubscriptionClient()++ monkeypatch.setattr("headroom.subscription.client.read_cached_oauth_token", lambda: None)+ assert await client.fetch() is None++ monkeypatch.setattr(+ "headroom.subscription.client.read_cached_oauth_token",+ lambda: "cached-token",+ )+ monkeypatch.setattr(+ "headroom.subscription.client.httpx.AsyncClient",+ lambda timeout: AsyncClientStub(error=httpx.TimeoutException("slow"), timeout=timeout),+ )+ assert await client.fetch() is None++ monkeypatch.setattr(+ "headroom.subscription.client.httpx.AsyncClient",+ lambda timeout: AsyncClientStub(error=RuntimeError("boom"), timeout=timeout),+ )+ assert await client.fetch() is Nonediff --git a/tests/test_subscription_tracker.py b/tests/test_subscription_tracker.pyindex 6b274a6f9..d246f438b 100644--- a/tests/test_subscription_tracker.py+++ b/tests/test_subscription_tracker.py@@ -1,201 +1,201 @@-from __future__ import annotations--import sys-from datetime import timedelta-from pathlib import Path-from types import SimpleNamespace--import pytest--import headroom.subscription.tracker as tracker_module-from headroom.subscription.models import (- HeadroomContribution,- RateLimitWindow,- SubscriptionSnapshot,- WindowDiscrepancy,- WindowTokens,- _utc_now,-)-from headroom.subscription.tracker import SubscriptionTracker---def _make_snapshot(- *, token_prefix: str = "token123", reset_offset_hours: int = 5-) -> SubscriptionSnapshot:- return SubscriptionSnapshot(- five_hour=RateLimitWindow(- used=10,- limit=100,- utilization_pct=10.0,- resets_at=_utc_now() + timedelta(hours=reset_offset_hours),- ),- seven_day=RateLimitWindow(used=20, limit=200, utilization_pct=10.0),- token_prefix=token_prefix,- )---def test_tracker_notify_active_update_and_basic_state(monkeypatch: pytest.MonkeyPatch) -> None:- monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)- tracker = SubscriptionTracker(enabled=False)-- assert tracker.is_available() is False- assert tracker.latest_snapshot is None- assert tracker.is_active() is False- assert isinstance(tracker.get_stats(), dict)-- tracker.notify_active("")- tracker.notify_active("Basic token")- tracker.notify_active("Bearer sk-ant-api-key")- assert tracker._current_token is None-- tracker.notify_active("Bearer oauth-token-123")- assert tracker._current_token == "oauth-token-123"- assert tracker._full_tokens["oauth-to"] == 1- assert tracker.is_active() is True-- tracker.update_contribution(- tokens_submitted=10,- tokens_saved_compression=5,- tokens_saved_rtk=-1,- tokens_saved_cache_reads=3,- compression_savings_usd=1.25,- cache_savings_usd=-2.0,- )- contribution = tracker._state.contribution- assert contribution.tokens_submitted == 10- assert contribution.tokens_saved_compression == 5- assert contribution.tokens_saved_rtk == 0- assert contribution.tokens_saved_cache_reads == 3- assert contribution.compression_savings_usd == 1.25- assert contribution.cache_savings_usd == 0.0---async def test_tracker_start_stop_and_rollover_reset(- monkeypatch: pytest.MonkeyPatch, tmp_path: Path-) -> None:- monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)- tracker = SubscriptionTracker(persist_path=tmp_path / "state.json")-- async def fake_poll_loop() -> None:- assert tracker._stop_event is not None- await tracker._stop_event.wait()-- tracker._poll_loop = fake_poll_loop # type: ignore[method-assign]- await tracker.start()- first_task = tracker._poll_task- assert first_task is not None-- await tracker.start()- assert tracker._poll_task is first_task-- await tracker.stop()- assert tracker._stop_event is not None and tracker._stop_event.is_set()- assert tracker._persist_path.exists()-- tracker._state.history = [- _make_snapshot(reset_offset_hours=5),- _make_snapshot(reset_offset_hours=6),- ]- tracker._state.contribution = HeadroomContribution(tokens_submitted=99)- tracker._maybe_reset_contribution(tracker._state.history[-1])- assert tracker._state.contribution.tokens_submitted == 0---async def test_maybe_poll_handles_inactive_and_none_snapshot(- monkeypatch: pytest.MonkeyPatch,-) -> None:- monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)- tracker = SubscriptionTracker()-- monkeypatch.setattr("headroom.subscription.client.read_cached_oauth_token", lambda: None)- await tracker._maybe_poll()- assert tracker._state.poll_count == 0-- monkeypatch.setattr(- "headroom.subscription.client.read_cached_oauth_token", lambda: "cached-token"- )-- async def fetch_none(token: str | None):- return None-- tracker._client = SimpleNamespace(fetch=fetch_none)- await tracker._maybe_poll()- assert tracker._state.last_error == "fetch returned None"- assert tracker._state.poll_errors == 1---async def test_maybe_poll_success_updates_state_and_metrics(- monkeypatch: pytest.MonkeyPatch,-) -> None:- monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)- tracker = SubscriptionTracker()- tracker.notify_active("Bearer live-oauth-token")-- snapshot = _make_snapshot()- discrepancies = [WindowDiscrepancy(kind="cache_miss", description="miss", severity="warning")]- metrics_calls: list[dict] = []-- async def fetch_snapshot(token: str | None):- assert token == "live-oauth-token"- return snapshot-- tracker._client = SimpleNamespace(fetch=fetch_snapshot)- monkeypatch.setattr(- tracker_module, "_compute_window_tokens_for_snapshot", lambda snap: WindowTokens(input=7)- )- monkeypatch.setattr(tracker_module, "_detect_discrepancies", lambda snap, tokens: discrepancies)- monkeypatch.setattr(- tracker, "_persist_state", lambda: metrics_calls.append({"persisted": True})- )- monkeypatch.setitem(- sys.modules,- "headroom.observability.metrics",- SimpleNamespace(- get_otel_metrics=lambda: SimpleNamespace(- record_subscription_window=lambda state: metrics_calls.append(state)- )- ),- )-- await tracker._maybe_poll()- assert tracker.latest_snapshot is snapshot- assert tracker._state.window_tokens.input == 7- assert tracker._state.discrepancies[-1].kind == "cache_miss"- assert tracker._state.last_error is None- assert tracker._state.poll_count == 1- assert metrics_calls[0] == {"persisted": True}- assert isinstance(metrics_calls[1], dict)---def test_persist_and_load_state_round_trip(tmp_path: Path) -> None:- persist_path = tmp_path / "tracker-state.json"- tracker = SubscriptionTracker(persist_path=persist_path)- tracker.update_contribution(- tokens_submitted=11,- tokens_saved_compression=2,- tokens_saved_rtk=3,- tokens_saved_cache_reads=4,- compression_savings_usd=1.5,- cache_savings_usd=2.5,- )- tracker._state.poll_count = 7- tracker._persist_state()-- loader = SubscriptionTracker(persist_path=persist_path)- assert loader._state.contribution.tokens_submitted == 11- assert loader._state.contribution.tokens_saved_compression == 2- assert loader._state.contribution.tokens_saved_rtk == 3- assert loader._state.contribution.tokens_saved_cache_reads == 4- assert loader._state.contribution.compression_savings_usd == 1.5- assert loader._state.contribution.cache_savings_usd == 2.5- assert loader._state.poll_count == 7-- persist_path.write_text("{invalid", encoding="utf-8")- broken = SubscriptionTracker(persist_path=persist_path)- assert broken._state.poll_count == 0-- missing = SubscriptionTracker(persist_path=tmp_path / "missing.json")- assert missing._state.poll_count == 0+from __future__ import annotations++import sys+from datetime import timedelta+from pathlib import Path+from types import SimpleNamespace++import pytest++import headroom.subscription.tracker as tracker_module+from headroom.subscription.models import (+ HeadroomContribution,+ RateLimitWindow,+ SubscriptionSnapshot,+ WindowDiscrepancy,+ WindowTokens,+ _utc_now,+)+from headroom.subscription.tracker import SubscriptionTracker+++def _make_snapshot(+ *, token_prefix: str = "token123", reset_offset_hours: int = 5+) -> SubscriptionSnapshot:+ return SubscriptionSnapshot(+ five_hour=RateLimitWindow(+ used=10,+ limit=100,+ utilization_pct=10.0,+ resets_at=_utc_now() + timedelta(hours=reset_offset_hours),+ ),+ seven_day=RateLimitWindow(used=20, limit=200, utilization_pct=10.0),+ token_prefix=token_prefix,+ )+++def test_tracker_notify_active_update_and_basic_state(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)+ tracker = SubscriptionTracker(enabled=False)++ assert tracker.is_available() is False+ assert tracker.latest_snapshot is None+ assert tracker.is_active() is False+ assert isinstance(tracker.get_stats(), dict)++ tracker.notify_active("")+ tracker.notify_active("Basic token")+ tracker.notify_active("Bearer sk-ant-api-key")+ assert tracker._current_token is None++ tracker.notify_active("Bearer oauth-token-123")+ assert tracker._current_token == "oauth-token-123"+ assert tracker._full_tokens["oauth-to"] == 1+ assert tracker.is_active() is True++ tracker.update_contribution(+ tokens_submitted=10,+ tokens_saved_compression=5,+ tokens_saved_rtk=-1,+ tokens_saved_cache_reads=3,+ compression_savings_usd=1.25,+ cache_savings_usd=-2.0,+ )+ contribution = tracker._state.contribution+ assert contribution.tokens_submitted == 10+ assert contribution.tokens_saved_compression == 5+ assert contribution.tokens_saved_rtk == 0+ assert contribution.tokens_saved_cache_reads == 3+ assert contribution.compression_savings_usd == 1.25+ assert contribution.cache_savings_usd == 0.0+++async def test_tracker_start_stop_and_rollover_reset(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)+ tracker = SubscriptionTracker(persist_path=tmp_path / "state.json")++ async def fake_poll_loop() -> None:+ assert tracker._stop_event is not None+ await tracker._stop_event.wait()++ tracker._poll_loop = fake_poll_loop # type: ignore[method-assign]+ await tracker.start()+ first_task = tracker._poll_task+ assert first_task is not None++ await tracker.start()+ assert tracker._poll_task is first_task++ await tracker.stop()+ assert tracker._stop_event is not None and tracker._stop_event.is_set()+ assert tracker._persist_path.exists()++ tracker._state.history = [+ _make_snapshot(reset_offset_hours=5),+ _make_snapshot(reset_offset_hours=6),+ ]+ tracker._state.contribution = HeadroomContribution(tokens_submitted=99)+ tracker._maybe_reset_contribution(tracker._state.history[-1])+ assert tracker._state.contribution.tokens_submitted == 0+++async def test_maybe_poll_handles_inactive_and_none_snapshot(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)+ tracker = SubscriptionTracker()++ monkeypatch.setattr("headroom.subscription.client.read_cached_oauth_token", lambda: None)+ await tracker._maybe_poll()+ assert tracker._state.poll_count == 0++ monkeypatch.setattr(+ "headroom.subscription.client.read_cached_oauth_token", lambda: "cached-token"+ )++ async def fetch_none(token: str | None):+ return None++ tracker._client = SimpleNamespace(fetch=fetch_none)+ await tracker._maybe_poll()+ assert tracker._state.last_error == "fetch returned None"+ assert tracker._state.poll_errors == 1+++async def test_maybe_poll_success_updates_state_and_metrics(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)+ tracker = SubscriptionTracker()+ tracker.notify_active("Bearer live-oauth-token")++ snapshot = _make_snapshot()+ discrepancies = [WindowDiscrepancy(kind="cache_miss", description="miss", severity="warning")]+ metrics_calls: list[dict] = []++ async def fetch_snapshot(token: str | None):+ assert token == "live-oauth-token"+ return snapshot++ tracker._client = SimpleNamespace(fetch=fetch_snapshot)+ monkeypatch.setattr(+ tracker_module, "_compute_window_tokens_for_snapshot", lambda snap: WindowTokens(input=7)+ )+ monkeypatch.setattr(tracker_module, "_detect_discrepancies", lambda snap, tokens: discrepancies)+ monkeypatch.setattr(+ tracker, "_persist_state", lambda: metrics_calls.append({"persisted": True})+ )+ monkeypatch.setitem(+ sys.modules,+ "headroom.observability.metrics",+ SimpleNamespace(+ get_otel_metrics=lambda: SimpleNamespace(+ record_subscription_window=lambda state: metrics_calls.append(state)+ )+ ),+ )++ await tracker._maybe_poll()+ assert tracker.latest_snapshot is snapshot+ assert tracker._state.window_tokens.input == 7+ assert tracker._state.discrepancies[-1].kind == "cache_miss"+ assert tracker._state.last_error is None+ assert tracker._state.poll_count == 1+ assert metrics_calls[0] == {"persisted": True}+ assert isinstance(metrics_calls[1], dict)+++def test_persist_and_load_state_round_trip(tmp_path: Path) -> None:+ persist_path = tmp_path / "tracker-state.json"+ tracker = SubscriptionTracker(persist_path=persist_path)+ tracker.update_contribution(+ tokens_submitted=11,+ tokens_saved_compression=2,+ tokens_saved_rtk=3,+ tokens_saved_cache_reads=4,+ compression_savings_usd=1.5,+ cache_savings_usd=2.5,+ )+ tracker._state.poll_count = 7+ tracker._persist_state()++ loader = SubscriptionTracker(persist_path=persist_path)+ assert loader._state.contribution.tokens_submitted == 11+ assert loader._state.contribution.tokens_saved_compression == 2+ assert loader._state.contribution.tokens_saved_rtk == 3+ assert loader._state.contribution.tokens_saved_cache_reads == 4+ assert loader._state.contribution.compression_savings_usd == 1.5+ assert loader._state.contribution.cache_savings_usd == 2.5+ assert loader._state.poll_count == 7++ persist_path.write_text("{invalid", encoding="utf-8")+ broken = SubscriptionTracker(persist_path=persist_path)+ assert broken._state.poll_count == 0++ missing = SubscriptionTracker(persist_path=tmp_path / "missing.json")+ assert missing._state.poll_count == 0diff --git a/tests/test_tokenizer.py b/tests/test_tokenizer.pyindex 030aeb56f..f95295ae1 100644--- a/tests/test_tokenizer.py+++ b/tests/test_tokenizer.py@@ -1,50 +1,50 @@-from __future__ import annotations--from typing import Any--from headroom.tokenizer import Tokenizer, count_tokens_messages, count_tokens_text---class FakeTokenCounter:- def __init__(self) -> None:- self.calls: list[tuple[str, Any]] = []-- def count_text(self, text: str) -> int:- self.calls.append(("text", text))- return len(text.split())-- def count_message(self, message: dict[str, Any]) -> int:- self.calls.append(("message", message))- return len(str(message.get("content", "")).split())-- def count_messages(self, messages: list[dict[str, Any]]) -> int:- self.calls.append(("messages", messages))- return sum(len(str(msg.get("content", "")).split()) for msg in messages)---def test_tokenizer_delegates_to_counter() -> None:- counter = FakeTokenCounter()- tokenizer = Tokenizer(counter, model="gpt-4o")-- assert tokenizer.model == "gpt-4o"- assert tokenizer.available is True- assert tokenizer.count_text("hello world") == 2- assert tokenizer.count_message({"role": "user", "content": "three word text"}) == 3- assert tokenizer.count_messages([{"content": "one two"}, {"content": "three"}]) == 3- assert counter.calls == [- ("text", "hello world"),- ("message", {"role": "user", "content": "three word text"}),- ("messages", [{"content": "one two"}, {"content": "three"}]),- ]---def test_tokenizer_convenience_functions() -> None:- counter = FakeTokenCounter()- messages = [{"content": "one"}, {"content": "two three"}]-- assert count_tokens_text("alpha beta gamma", counter) == 3- assert count_tokens_messages(messages, counter) == 3- assert counter.calls == [- ("text", "alpha beta gamma"),- ("messages", messages),- ]+from __future__ import annotations++from typing import Any++from headroom.tokenizer import Tokenizer, count_tokens_messages, count_tokens_text+++class FakeTokenCounter:+ def __init__(self) -> None:+ self.calls: list[tuple[str, Any]] = []++ def count_text(self, text: str) -> int:+ self.calls.append(("text", text))+ return len(text.split())++ def count_message(self, message: dict[str, Any]) -> int:+ self.calls.append(("message", message))+ return len(str(message.get("content", "")).split())++ def count_messages(self, messages: list[dict[str, Any]]) -> int:+ self.calls.append(("messages", messages))+ return sum(len(str(msg.get("content", "")).split()) for msg in messages)+++def test_tokenizer_delegates_to_counter() -> None:+ counter = FakeTokenCounter()+ tokenizer = Tokenizer(counter, model="gpt-4o")++ assert tokenizer.model == "gpt-4o"+ assert tokenizer.available is True+ assert tokenizer.count_text("hello world") == 2+ assert tokenizer.count_message({"role": "user", "content": "three word text"}) == 3+ assert tokenizer.count_messages([{"content": "one two"}, {"content": "three"}]) == 3+ assert counter.calls == [+ ("text", "hello world"),+ ("message", {"role": "user", "content": "three word text"}),+ ("messages", [{"content": "one two"}, {"content": "three"}]),+ ]+++def test_tokenizer_convenience_functions() -> None:+ counter = FakeTokenCounter()+ messages = [{"content": "one"}, {"content": "two three"}]++ assert count_tokens_text("alpha beta gamma", counter) == 3+ assert count_tokens_messages(messages, counter) == 3+ assert counter.calls == [+ ("text", "alpha beta gamma"),+ ("messages", messages),+ ]diff --git a/tests/test_transforms_content_detection.py b/tests/test_transforms_content_detection.pyindex 1ca9de7ea..9bf7a6353 100644--- a/tests/test_transforms_content_detection.py+++ b/tests/test_transforms_content_detection.py@@ -1,202 +1,202 @@-from __future__ import annotations--from headroom.transforms.content_detector import (- ContentType,- _try_detect_code,- _try_detect_diff,- _try_detect_html,- _try_detect_json,- _try_detect_log,- _try_detect_search,- detect_content_type,- is_json_array_of_dicts,-)-from headroom.transforms.error_detection import (- ERROR_INDICATOR_KEYWORDS,- ERROR_KEYWORDS,- ERROR_PATTERN,- IMPORTANCE_KEYWORDS,- IMPORTANCE_PATTERN,- PRIORITY_PATTERNS_DIFF,- PRIORITY_PATTERNS_SEARCH,- PRIORITY_PATTERNS_TEXT,- SECURITY_KEYWORDS,- SECURITY_PATTERN,- WARNING_PATTERN,- content_has_error_indicators,-)---def test_detect_content_type_handles_empty_and_plain_text() -> None:- empty = detect_content_type(" ")- assert empty.content_type is ContentType.PLAIN_TEXT- assert empty.confidence == 0.0-- plain = detect_content_type("just a normal paragraph with no strong patterns")- assert plain.content_type is ContentType.PLAIN_TEXT- assert plain.confidence == 0.5---def test_json_detection_distinguishes_dict_arrays_and_other_lists() -> None:- dict_result = _try_detect_json('[{"id": 1}, {"id": 2}]')- assert dict_result is not None- assert dict_result.content_type is ContentType.JSON_ARRAY- assert dict_result.confidence == 1.0- assert dict_result.metadata == {"item_count": 2, "is_dict_array": True}-- scalar_result = _try_detect_json("[1, 2, 3]")- assert scalar_result is not None- assert scalar_result.confidence == 0.8- assert scalar_result.metadata == {"item_count": 3, "is_dict_array": False}-- empty_result = _try_detect_json("[]")- assert empty_result is not None- assert empty_result.metadata == {"item_count": 0, "is_dict_array": False}-- assert _try_detect_json('{"id": 1}') is None- assert _try_detect_json("[not valid json") is None- assert is_json_array_of_dicts('[{"id": 1}]') is True- assert is_json_array_of_dicts('["value"]') is False---def test_diff_detection_tracks_headers_and_changes() -> None:- diff = "\n".join(- [- "diff --git a/app.py b/app.py",- "--- a/app.py",- "@@ -1,2 +1,2 @@",- "-old line",- "+new line",- ]- )- result = _try_detect_diff(diff)- assert result is not None- assert result.content_type is ContentType.GIT_DIFF- assert result.metadata["header_matches"] == 3- assert result.metadata["change_lines"] == 2- assert result.confidence == 1.0- assert detect_content_type(diff).content_type is ContentType.GIT_DIFF-- assert _try_detect_diff("+not enough by itself") is None---def test_html_detection_requires_real_structure() -> None:- html = """- <!DOCTYPE html>- <html>- <head><meta charset="utf-8"></head>- <body><main><section><div>Hello</div><nav>Links</nav></section></main></body>- </html>- """- result = _try_detect_html(html)- assert result is not None- assert result.content_type is ContentType.HTML- assert result.metadata["has_doctype"] is True- assert result.metadata["has_html_tag"] is True- assert result.metadata["structural_tags"] >= 3- assert detect_content_type(html).content_type is ContentType.HTML-- assert _try_detect_html("<div>only one tag</div>") is None- assert _try_detect_html("<html><title>too sparse</title></html>") is None---def test_search_detection_uses_match_ratio() -> None:- search_output = "\n".join(- [- "src/app.py:10:def main():",- "src/app.py:20:print('hello')",- "README.md:5:usage docs",- "plain text footer",- ]- )- result = _try_detect_search(search_output)- assert result is not None- assert result.content_type is ContentType.SEARCH_RESULTS- assert result.metadata == {"matching_lines": 3, "total_lines": 4}- assert result.confidence == 0.85- assert detect_content_type(search_output).content_type is ContentType.SEARCH_RESULTS-- assert _try_detect_search("one:1:match\nplain\nplain\nplain") is None- assert _try_detect_search("\n\n") is None---def test_log_detection_prefers_build_output_patterns() -> None:- log_output = "\n".join(- [- "2025-01-01 Starting run",- "ERROR failed to compile",- "WARNING retrying build",- "PASSED unit test",- "Traceback (most recent call last)",- "plain footer",- ]- )- result = _try_detect_log(log_output)- assert result is not None- assert result.content_type is ContentType.BUILD_OUTPUT- assert result.metadata == {"pattern_matches": 5, "error_matches": 2, "total_lines": 6}- assert result.confidence == 0.8166666666666667- assert detect_content_type(log_output).content_type is ContentType.BUILD_OUTPUT-- assert _try_detect_log("plain\ntext\nonly") is None- assert _try_detect_log("\n\n") is None- assert _try_detect_log("\n".join(["ERROR one", *["plain"] * 15])) is None---def test_code_detection_identifies_language_and_thresholds() -> None:- python_code = "\n".join(- [- "import os",- "from pathlib import Path",- "",- "@cached",- "class App:",- " pass",- "def main():",- ' """Run."""',- ]- )- result = _try_detect_code(python_code)- assert result is not None- assert result.content_type is ContentType.SOURCE_CODE- assert result.metadata == {"language": "python", "pattern_matches": 6}- assert result.confidence == 0.8628571428571429- assert detect_content_type(python_code).content_type is ContentType.SOURCE_CODE-- assert _try_detect_code("function maybe() {}\nplain text") is None- assert _try_detect_code("import os\ndef main():") is None- assert _try_detect_code("\n\n") is None---def test_detect_content_type_respects_priority_order() -> None:- diff_like_search = "\n".join(- [- "diff --git a/src/app.py b/src/app.py",- "@@ -1,1 +1,1 @@",- "+src/app.py:10:def still_diff_first()",- ]- )- assert detect_content_type(diff_like_search).content_type is ContentType.GIT_DIFF---def test_error_detection_keywords_patterns_and_indicator_helper() -> None:- assert {"error", "failed", "critical"} <= ERROR_KEYWORDS- assert {"warning", "todo", "fix"} <= IMPORTANCE_KEYWORDS- assert {"security", "password", "token"} <= SECURITY_KEYWORDS- assert ERROR_INDICATOR_KEYWORDS[0] == "error"-- assert ERROR_PATTERN.search("Fatal error occurred")- assert WARNING_PATTERN.search("warning: be careful")- assert IMPORTANCE_PATTERN.search("TODO fix this hack")- assert SECURITY_PATTERN.search("rotate the auth token")-- assert PRIORITY_PATTERNS_SEARCH[:3] == [ERROR_PATTERN, WARNING_PATTERN, IMPORTANCE_PATTERN]- assert PRIORITY_PATTERNS_DIFF == [ERROR_PATTERN, IMPORTANCE_PATTERN, SECURITY_PATTERN]- assert PRIORITY_PATTERNS_TEXT[0] is ERROR_PATTERN- assert PRIORITY_PATTERNS_TEXT[1] is IMPORTANCE_PATTERN- assert PRIORITY_PATTERNS_TEXT[2].match("## Header")- assert PRIORITY_PATTERNS_TEXT[3].match("**Bold")- assert PRIORITY_PATTERNS_TEXT[4].match("> quote")-- assert content_has_error_indicators("TRACEBACK: Fatal crash in worker") is True- assert content_has_error_indicators("Everything completed successfully") is False+from __future__ import annotations++from headroom.transforms.content_detector import (+ ContentType,+ _try_detect_code,+ _try_detect_diff,+ _try_detect_html,+ _try_detect_json,+ _try_detect_log,+ _try_detect_search,+ detect_content_type,+ is_json_array_of_dicts,+)+from headroom.transforms.error_detection import (+ ERROR_INDICATOR_KEYWORDS,+ ERROR_KEYWORDS,+ ERROR_PATTERN,+ IMPORTANCE_KEYWORDS,+ IMPORTANCE_PATTERN,+ PRIORITY_PATTERNS_DIFF,+ PRIORITY_PATTERNS_SEARCH,+ PRIORITY_PATTERNS_TEXT,+ SECURITY_KEYWORDS,+ SECURITY_PATTERN,+ WARNING_PATTERN,+ content_has_error_indicators,+)+++def test_detect_content_type_handles_empty_and_plain_text() -> None:+ empty = detect_content_type(" ")+ assert empty.content_type is ContentType.PLAIN_TEXT+ assert empty.confidence == 0.0++ plain = detect_content_type("just a normal paragraph with no strong patterns")+ assert plain.content_type is ContentType.PLAIN_TEXT+ assert plain.confidence == 0.5+++def test_json_detection_distinguishes_dict_arrays_and_other_lists() -> None:+ dict_result = _try_detect_json('[{"id": 1}, {"id": 2}]')+ assert dict_result is not None+ assert dict_result.content_type is ContentType.JSON_ARRAY+ assert dict_result.confidence == 1.0+ assert dict_result.metadata == {"item_count": 2, "is_dict_array": True}++ scalar_result = _try_detect_json("[1, 2, 3]")+ assert scalar_result is not None+ assert scalar_result.confidence == 0.8+ assert scalar_result.metadata == {"item_count": 3, "is_dict_array": False}++ empty_result = _try_detect_json("[]")+ assert empty_result is not None+ assert empty_result.metadata == {"item_count": 0, "is_dict_array": False}++ assert _try_detect_json('{"id": 1}') is None+ assert _try_detect_json("[not valid json") is None+ assert is_json_array_of_dicts('[{"id": 1}]') is True+ assert is_json_array_of_dicts('["value"]') is False+++def test_diff_detection_tracks_headers_and_changes() -> None:+ diff = "\n".join(+ [+ "diff --git a/app.py b/app.py",+ "--- a/app.py",+ "@@ -1,2 +1,2 @@",+ "-old line",+ "+new line",+ ]+ )+ result = _try_detect_diff(diff)+ assert result is not None+ assert result.content_type is ContentType.GIT_DIFF+ assert result.metadata["header_matches"] == 3+ assert result.metadata["change_lines"] == 2+ assert result.confidence == 1.0+ assert detect_content_type(diff).content_type is ContentType.GIT_DIFF++ assert _try_detect_diff("+not enough by itself") is None+++def test_html_detection_requires_real_structure() -> None:+ html = """+ <!DOCTYPE html>+ <html>+ <head><meta charset="utf-8"></head>+ <body><main><section><div>Hello</div><nav>Links</nav></section></main></body>+ </html>+ """+ result = _try_detect_html(html)+ assert result is not None+ assert result.content_type is ContentType.HTML+ assert result.metadata["has_doctype"] is True+ assert result.metadata["has_html_tag"] is True+ assert result.metadata["structural_tags"] >= 3+ assert detect_content_type(html).content_type is ContentType.HTML++ assert _try_detect_html("<div>only one tag</div>") is None+ assert _try_detect_html("<html><title>too sparse</title></html>") is None+++def test_search_detection_uses_match_ratio() -> None:+ search_output = "\n".join(+ [+ "src/app.py:10:def main():",+ "src/app.py:20:print('hello')",+ "README.md:5:usage docs",+ "plain text footer",+ ]+ )+ result = _try_detect_search(search_output)+ assert result is not None+ assert result.content_type is ContentType.SEARCH_RESULTS+ assert result.metadata == {"matching_lines": 3, "total_lines": 4}+ assert result.confidence == 0.85+ assert detect_content_type(search_output).content_type is ContentType.SEARCH_RESULTS++ assert _try_detect_search("one:1:match\nplain\nplain\nplain") is None+ assert _try_detect_search("\n\n") is None+++def test_log_detection_prefers_build_output_patterns() -> None:+ log_output = "\n".join(+ [+ "2025-01-01 Starting run",+ "ERROR failed to compile",+ "WARNING retrying build",+ "PASSED unit test",+ "Traceback (most recent call last)",+ "plain footer",+ ]+ )+ result = _try_detect_log(log_output)+ assert result is not None+ assert result.content_type is ContentType.BUILD_OUTPUT+ assert result.metadata == {"pattern_matches": 5, "error_matches": 2, "total_lines": 6}+ assert result.confidence == 0.8166666666666667+ assert detect_content_type(log_output).content_type is ContentType.BUILD_OUTPUT++ assert _try_detect_log("plain\ntext\nonly") is None+ assert _try_detect_log("\n\n") is None+ assert _try_detect_log("\n".join(["ERROR one", *["plain"] * 15])) is None+++def test_code_detection_identifies_language_and_thresholds() -> None:+ python_code = "\n".join(+ [+ "import os",+ "from pathlib import Path",+ "",+ "@cached",+ "class App:",+ " pass",+ "def main():",+ ' """Run."""',+ ]+ )+ result = _try_detect_code(python_code)+ assert result is not None+ assert result.content_type is ContentType.SOURCE_CODE+ assert result.metadata == {"language": "python", "pattern_matches": 6}+ assert result.confidence == 0.8628571428571429+ assert detect_content_type(python_code).content_type is ContentType.SOURCE_CODE++ assert _try_detect_code("function maybe() {}\nplain text") is None+ assert _try_detect_code("import os\ndef main():") is None+ assert _try_detect_code("\n\n") is None+++def test_detect_content_type_respects_priority_order() -> None:+ diff_like_search = "\n".join(+ [+ "diff --git a/src/app.py b/src/app.py",+ "@@ -1,1 +1,1 @@",+ "+src/app.py:10:def still_diff_first()",+ ]+ )+ assert detect_content_type(diff_like_search).content_type is ContentType.GIT_DIFF+++def test_error_detection_keywords_patterns_and_indicator_helper() -> None:+ assert {"error", "failed", "critical"} <= ERROR_KEYWORDS+ assert {"warning", "todo", "fix"} <= IMPORTANCE_KEYWORDS+ assert {"security", "password", "token"} <= SECURITY_KEYWORDS+ assert ERROR_INDICATOR_KEYWORDS[0] == "error"++ assert ERROR_PATTERN.search("Fatal error occurred")+ assert WARNING_PATTERN.search("warning: be careful")+ assert IMPORTANCE_PATTERN.search("TODO fix this hack")+ assert SECURITY_PATTERN.search("rotate the auth token")++ assert PRIORITY_PATTERNS_SEARCH[:3] == [ERROR_PATTERN, WARNING_PATTERN, IMPORTANCE_PATTERN]+ assert PRIORITY_PATTERNS_DIFF == [ERROR_PATTERN, IMPORTANCE_PATTERN, SECURITY_PATTERN]+ assert PRIORITY_PATTERNS_TEXT[0] is ERROR_PATTERN+ assert PRIORITY_PATTERNS_TEXT[1] is IMPORTANCE_PATTERN+ assert PRIORITY_PATTERNS_TEXT[2].match("## Header")+ assert PRIORITY_PATTERNS_TEXT[3].match("**Bold")+ assert PRIORITY_PATTERNS_TEXT[4].match("> quote")++ assert content_has_error_indicators("TRACEBACK: Fatal crash in worker") is True+ assert content_has_error_indicators("Everything completed successfully") is Falsediff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.pyindex 7969bb152..dfbd60ebe 100644--- a/tests/test_transforms_content_router.py+++ b/tests/test_transforms_content_router.py@@ -1,294 +1,294 @@-from __future__ import annotations--from types import SimpleNamespace--import pytest--import headroom.transforms.content_router as content_router_module-from headroom.transforms.content_detector import ContentType, DetectionResult-from headroom.transforms.content_router import (- CompressionCache,- CompressionStrategy,- ContentRouter,- ContentRouterConfig,- RouterCompressionResult,- RoutingDecision,- _create_content_signature,- _detect_content,- _extract_json_block,- is_mixed_content,- split_into_sections,-)---def test_compression_cache_handles_hits_skips_evictions_and_clear(- monkeypatch: pytest.MonkeyPatch,-) -> None:- times = iter([100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 112.0, 112.0])- monkeypatch.setattr(content_router_module.time, "time", lambda: next(times))- monkeypatch.setattr(content_router_module.time, "perf_counter_ns", lambda: 50)-- cache = CompressionCache(ttl_seconds=10)- cache.put(1, "compressed", 0.4, "text")- cache.mark_skip(2)-- assert cache.get(1) == ("compressed", 0.4, "text")- assert cache.is_skipped(2) is True- assert cache.size == 1- assert cache.skip_size == 1-- cache.move_to_skip(1)- assert cache.get(1) is None- assert cache.is_skipped(1) is True-- # Expire both skip entries- assert cache.is_skipped(2) is False- assert cache.is_skipped(1) is False-- assert cache.stats["cache_hits"] == 1- assert cache.stats["cache_skip_hits"] == 2- assert cache.stats["cache_misses"] == 1- assert cache.stats["cache_evictions"] >= 2-- cache.clear()- assert cache.size == 0- assert cache.skip_size == 0---def test_router_result_helpers_and_summary() -> None:- pure = RouterCompressionResult(- compressed="small",- original="very large",- strategy_used=CompressionStrategy.TEXT,- routing_log=[- RoutingDecision(- content_type=ContentType.PLAIN_TEXT,- strategy=CompressionStrategy.TEXT,- original_tokens=10,- compressed_tokens=4,- )- ],- )- assert pure.total_original_tokens == 10- assert pure.total_compressed_tokens == 4- assert pure.compression_ratio == 0.4- assert pure.tokens_saved == 6- assert pure.savings_percentage == 60.0- assert pure.summary() == "Pure text: 10→4 tokens (60% saved)"-- mixed = RouterCompressionResult(- compressed="joined",- original="original",- strategy_used=CompressionStrategy.MIXED,- sections_processed=2,- routing_log=[- RoutingDecision(- content_type=ContentType.PLAIN_TEXT,- strategy=CompressionStrategy.TEXT,- original_tokens=0,- compressed_tokens=0,- ),- RoutingDecision(- content_type=ContentType.SEARCH_RESULTS,- strategy=CompressionStrategy.SEARCH,- original_tokens=8,- compressed_tokens=2,- ),- ],- )- assert mixed.routing_log[0].compression_ratio == 1.0- assert mixed.summary().startswith("Mixed content: 2 sections, routed to ")---def test_content_signature_and_detection_helpers(monkeypatch: pytest.MonkeyPatch) -> None:- signature = _create_content_signature("search", "file.py:10:match", language="python")- assert signature is not None- assert len(signature.structure_hash) == 24-- fake_detector = SimpleNamespace(- detect=lambda content: SimpleNamespace(- content_type=SimpleNamespace(value="code"),- confidence=0.91,- language="python",- raw_label="python",- )- )- monkeypatch.setattr(content_router_module, "_get_magika_detector", lambda: fake_detector)- magika_result = _detect_content("def main(): pass")- assert magika_result == DetectionResult(- content_type=ContentType.SOURCE_CODE,- confidence=0.91,- metadata={"language": "python", "raw_label": "python"},- )-- fallback = DetectionResult(ContentType.PLAIN_TEXT, 0.6, {"kind": "fallback"})- monkeypatch.setattr(content_router_module, "_get_magika_detector", lambda: None)- monkeypatch.setattr(content_router_module, "detect_content_type", lambda content: fallback)- assert _detect_content("plain") is fallback---def test_mixed_content_section_splitting_and_json_extraction() -> None:- content = "\n".join(- [- "Intro paragraph with Several words included for prose detection.",- "Another line with enough words to read as normal prose today.",- "Third line adds more prose so the detector sees real text content.",- "Fourth sentence keeps the count moving higher for prose patterns.",- "Fifth sentence does the same for mixed content identification.",- "Sixth sentence seals the prose threshold for the helper.",- "```python",- "def main():",- " return 1",- "```",- '[{"id": 1}]',- "src/app.py:10:def main():",- "src/app.py:11:return 1",- ]- )- assert is_mixed_content(content) is True-- sections = split_into_sections(content)- assert [section.content_type for section in sections] == [- ContentType.PLAIN_TEXT,- ContentType.SOURCE_CODE,- ContentType.JSON_ARRAY,- ContentType.SEARCH_RESULTS,- ]- assert sections[1].language == "python"- assert sections[1].is_code_fence is True- assert sections[2].content == '[{"id": 1}]'- assert sections[3].end_line == 12-- json_block, end_idx = _extract_json_block(["[", '{"id": 1}', "]"], 0)- assert json_block == '[\n{"id": 1}\n]'- assert end_idx == 2- assert _extract_json_block(["{", '"a": 1'], 0) == (None, 0)---def test_content_router_strategy_and_compress_paths(monkeypatch: pytest.MonkeyPatch) -> None:- router = ContentRouter(ContentRouterConfig(prefer_code_aware_for_code=False))-- monkeypatch.setattr(content_router_module, "is_mixed_content", lambda content: False)- monkeypatch.setattr(- content_router_module,- "_detect_content",- lambda content: DetectionResult(ContentType.SOURCE_CODE, 1.0, {}),- )- assert router._determine_strategy("code") is CompressionStrategy.KOMPRESS- assert (- router._strategy_from_detection(DetectionResult(ContentType.SEARCH_RESULTS, 1.0, {}))- is CompressionStrategy.SEARCH- )- assert router._strategy_from_detection_type(ContentType.GIT_DIFF) is CompressionStrategy.DIFF- assert (- router._content_type_from_strategy(CompressionStrategy.PASSTHROUGH)- is ContentType.PLAIN_TEXT- )-- mixed_result = RouterCompressionResult(- compressed="mixed",- original="mixed",- strategy_used=CompressionStrategy.MIXED,- )- pure_result = RouterCompressionResult(- compressed="pure",- original="pure",- strategy_used=CompressionStrategy.TEXT,- )- monkeypatch.setattr(router, "_compress_mixed", lambda *args, **kwargs: mixed_result)- monkeypatch.setattr(router, "_compress_pure", lambda *args, **kwargs: pure_result)-- monkeypatch.setattr(router, "_determine_strategy", lambda content: CompressionStrategy.MIXED)- assert router.compress("mixed") is mixed_result-- monkeypatch.setattr(router, "_determine_strategy", lambda content: CompressionStrategy.TEXT)- assert router.compress("pure") is pure_result- assert router.compress(" ").strategy_used is CompressionStrategy.PASSTHROUGH---def test_content_router_mixed_pure_apply_and_toin(monkeypatch: pytest.MonkeyPatch) -> None:- router = ContentRouter()- mixed_content = "\n".join(["before", "```python", "print('x')", "```", "after"])- monkeypatch.setattr(- content_router_module,- "split_into_sections",- lambda content: [- SimpleNamespace(- content="print('x')",- content_type=ContentType.SOURCE_CODE,- language="python",- is_code_fence=True,- ),- SimpleNamespace(- content="after text",- content_type=ContentType.PLAIN_TEXT,- language=None,- is_code_fence=False,- ),- ],- )- monkeypatch.setattr(- router,- "_apply_strategy_to_content",- lambda content, strategy, context, language=None, question=None, bias=1.0: (- f"{strategy.value}:{content}",- len(content.split()) - 1,- ),- )- result = router._compress_mixed(mixed_content, "ctx")- assert result.strategy_used is CompressionStrategy.MIXED- assert result.sections_processed == 2- assert "```python\ncode_aware:print('x')\n```" in result.compressed-- monkeypatch.setattr(- router,- "_apply_strategy_to_content",- lambda content, strategy, context, language=None, question=None, bias=1.0: (- "shrunk",- 1,- ),- )- pure = router._compress_pure("some plain text", CompressionStrategy.TEXT, "ctx")- assert pure.routing_log[0].content_type is ContentType.PLAIN_TEXT- assert pure.total_original_tokens == 3- assert pure.total_compressed_tokens == 1-- calls: list[dict] = []- router._toin = SimpleNamespace(record_compression=lambda **kwargs: calls.append(kwargs))- monkeypatch.setattr(content_router_module, "_create_content_signature", lambda **kwargs: "sig")- router._record_to_toin(- CompressionStrategy.TEXT,- "original content",- "small",- original_tokens=10,- compressed_tokens=4,- language="python",- context="question",- )- assert calls[0]["tool_signature"] == "sig"- assert calls[0]["strategy"] == "text"- assert calls[0]["query_context"] == "question"-- router._record_to_toin(- CompressionStrategy.SMART_CRUSHER,- "x",- "x",- original_tokens=10,- compressed_tokens=4,- )- router._record_to_toin(- CompressionStrategy.TEXT,- "x",- "x",- original_tokens=2,- compressed_tokens=2,- )- monkeypatch.setattr(content_router_module, "_create_content_signature", lambda **kwargs: None)- router._record_to_toin(- CompressionStrategy.TEXT,- "x",- "y",- original_tokens=5,- compressed_tokens=1,- )- assert len(calls) == 1+from __future__ import annotations++from types import SimpleNamespace++import pytest++import headroom.transforms.content_router as content_router_module+from headroom.transforms.content_detector import ContentType, DetectionResult+from headroom.transforms.content_router import (+ CompressionCache,+ CompressionStrategy,+ ContentRouter,+ ContentRouterConfig,+ RouterCompressionResult,+ RoutingDecision,+ _create_content_signature,+ _detect_content,+ _extract_json_block,+ is_mixed_content,+ split_into_sections,+)+++def test_compression_cache_handles_hits_skips_evictions_and_clear(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ times = iter([100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 112.0, 112.0])+ monkeypatch.setattr(content_router_module.time, "time", lambda: next(times))+ monkeypatch.setattr(content_router_module.time, "perf_counter_ns", lambda: 50)++ cache = CompressionCache(ttl_seconds=10)+ cache.put(1, "compressed", 0.4, "text")+ cache.mark_skip(2)++ assert cache.get(1) == ("compressed", 0.4, "text")+ assert cache.is_skipped(2) is True+ assert cache.size == 1+ assert cache.skip_size == 1++ cache.move_to_skip(1)+ assert cache.get(1) is None+ assert cache.is_skipped(1) is True++ # Expire both skip entries+ assert cache.is_skipped(2) is False+ assert cache.is_skipped(1) is False++ assert cache.stats["cache_hits"] == 1+ assert cache.stats["cache_skip_hits"] == 2+ assert cache.stats["cache_misses"] == 1+ assert cache.stats["cache_evictions"] >= 2++ cache.clear()+ assert cache.size == 0+ assert cache.skip_size == 0+++def test_router_result_helpers_and_summary() -> None:+ pure = RouterCompressionResult(+ compressed="small",+ original="very large",+ strategy_used=CompressionStrategy.TEXT,+ routing_log=[+ RoutingDecision(+ content_type=ContentType.PLAIN_TEXT,+ strategy=CompressionStrategy.TEXT,+ original_tokens=10,+ compressed_tokens=4,+ )+ ],+ )+ assert pure.total_original_tokens == 10+ assert pure.total_compressed_tokens == 4+ assert pure.compression_ratio == 0.4+ assert pure.tokens_saved == 6+ assert pure.savings_percentage == 60.0+ assert pure.summary() == "Pure text: 10→4 tokens (60% saved)"++ mixed = RouterCompressionResult(+ compressed="joined",+ original="original",+ strategy_used=CompressionStrategy.MIXED,+ sections_processed=2,+ routing_log=[+ RoutingDecision(+ content_type=ContentType.PLAIN_TEXT,+ strategy=CompressionStrategy.TEXT,+ original_tokens=0,+ compressed_tokens=0,+ ),+ RoutingDecision(+ content_type=ContentType.SEARCH_RESULTS,+ strategy=CompressionStrategy.SEARCH,+ original_tokens=8,+ compressed_tokens=2,+ ),+ ],+ )+ assert mixed.routing_log[0].compression_ratio == 1.0+ assert mixed.summary().startswith("Mixed content: 2 sections, routed to ")+++def test_content_signature_and_detection_helpers(monkeypatch: pytest.MonkeyPatch) -> None:+ signature = _create_content_signature("search", "file.py:10:match", language="python")+ assert signature is not None+ assert len(signature.structure_hash) == 24++ fake_detector = SimpleNamespace(+ detect=lambda content: SimpleNamespace(+ content_type=SimpleNamespace(value="code"),+ confidence=0.91,+ language="python",+ raw_label="python",+ )+ )+ monkeypatch.setattr(content_router_module, "_get_magika_detector", lambda: fake_detector)+ magika_result = _detect_content("def main(): pass")+ assert magika_result == DetectionResult(+ content_type=ContentType.SOURCE_CODE,+ confidence=0.91,+ metadata={"language": "python", "raw_label": "python"},+ )++ fallback = DetectionResult(ContentType.PLAIN_TEXT, 0.6, {"kind": "fallback"})+ monkeypatch.setattr(content_router_module, "_get_magika_detector", lambda: None)+ monkeypatch.setattr(content_router_module, "detect_content_type", lambda content: fallback)+ assert _detect_content("plain") is fallback+++def test_mixed_content_section_splitting_and_json_extraction() -> None:+ content = "\n".join(+ [+ "Intro paragraph with Several words included for prose detection.",+ "Another line with enough words to read as normal prose today.",+ "Third line adds more prose so the detector sees real text content.",+ "Fourth sentence keeps the count moving higher for prose patterns.",+ "Fifth sentence does the same for mixed content identification.",+ "Sixth sentence seals the prose threshold for the helper.",+ "```python",+ "def main():",+ " return 1",+ "```",+ '[{"id": 1}]',+ "src/app.py:10:def main():",+ "src/app.py:11:return 1",+ ]+ )+ assert is_mixed_content(content) is True++ sections = split_into_sections(content)+ assert [section.content_type for section in sections] == [+ ContentType.PLAIN_TEXT,+ ContentType.SOURCE_CODE,+ ContentType.JSON_ARRAY,+ ContentType.SEARCH_RESULTS,+ ]+ assert sections[1].language == "python"+ assert sections[1].is_code_fence is True+ assert sections[2].content == '[{"id": 1}]'+ assert sections[3].end_line == 12++ json_block, end_idx = _extract_json_block(["[", '{"id": 1}', "]"], 0)+ assert json_block == '[\n{"id": 1}\n]'+ assert end_idx == 2+ assert _extract_json_block(["{", '"a": 1'], 0) == (None, 0)+++def test_content_router_strategy_and_compress_paths(monkeypatch: pytest.MonkeyPatch) -> None:+ router = ContentRouter(ContentRouterConfig(prefer_code_aware_for_code=False))++ monkeypatch.setattr(content_router_module, "is_mixed_content", lambda content: False)+ monkeypatch.setattr(+ content_router_module,+ "_detect_content",+ lambda content: DetectionResult(ContentType.SOURCE_CODE, 1.0, {}),+ )+ assert router._determine_strategy("code") is CompressionStrategy.KOMPRESS+ assert (+ router._strategy_from_detection(DetectionResult(ContentType.SEARCH_RESULTS, 1.0, {}))+ is CompressionStrategy.SEARCH+ )+ assert router._strategy_from_detection_type(ContentType.GIT_DIFF) is CompressionStrategy.DIFF+ assert (+ router._content_type_from_strategy(CompressionStrategy.PASSTHROUGH)+ is ContentType.PLAIN_TEXT+ )++ mixed_result = RouterCompressionResult(+ compressed="mixed",+ original="mixed",+ strategy_used=CompressionStrategy.MIXED,+ )+ pure_result = RouterCompressionResult(+ compressed="pure",+ original="pure",+ strategy_used=CompressionStrategy.TEXT,+ )+ monkeypatch.setattr(router, "_compress_mixed", lambda *args, **kwargs: mixed_result)+ monkeypatch.setattr(router, "_compress_pure", lambda *args, **kwargs: pure_result)++ monkeypatch.setattr(router, "_determine_strategy", lambda content: CompressionStrategy.MIXED)+ assert router.compress("mixed") is mixed_result++ monkeypatch.setattr(router, "_determine_strategy", lambda content: CompressionStrategy.TEXT)+ assert router.compress("pure") is pure_result+ assert router.compress(" ").strategy_used is CompressionStrategy.PASSTHROUGH+++def test_content_router_mixed_pure_apply_and_toin(monkeypatch: pytest.MonkeyPatch) -> None:+ router = ContentRouter()+ mixed_content = "\n".join(["before", "```python", "print('x')", "```", "after"])+ monkeypatch.setattr(+ content_router_module,+ "split_into_sections",+ lambda content: [+ SimpleNamespace(+ content="print('x')",+ content_type=ContentType.SOURCE_CODE,+ language="python",+ is_code_fence=True,+ ),+ SimpleNamespace(+ content="after text",+ content_type=ContentType.PLAIN_TEXT,+ language=None,+ is_code_fence=False,+ ),+ ],+ )+ monkeypatch.setattr(+ router,+ "_apply_strategy_to_content",+ lambda content, strategy, context, language=None, question=None, bias=1.0: (+ f"{strategy.value}:{content}",+ len(content.split()) - 1,+ ),+ )+ result = router._compress_mixed(mixed_content, "ctx")+ assert result.strategy_used is CompressionStrategy.MIXED+ assert result.sections_processed == 2+ assert "```python\ncode_aware:print('x')\n```" in result.compressed++ monkeypatch.setattr(+ router,+ "_apply_strategy_to_content",+ lambda content, strategy, context, language=None, question=None, bias=1.0: (+ "shrunk",+ 1,+ ),+ )+ pure = router._compress_pure("some plain text", CompressionStrategy.TEXT, "ctx")+ assert pure.routing_log[0].content_type is ContentType.PLAIN_TEXT+ assert pure.total_original_tokens == 3+ assert pure.total_compressed_tokens == 1++ calls: list[dict] = []+ router._toin = SimpleNamespace(record_compression=lambda **kwargs: calls.append(kwargs))+ monkeypatch.setattr(content_router_module, "_create_content_signature", lambda **kwargs: "sig")+ router._record_to_toin(+ CompressionStrategy.TEXT,+ "original content",+ "small",+ original_tokens=10,+ compressed_tokens=4,+ language="python",+ context="question",+ )+ assert calls[0]["tool_signature"] == "sig"+ assert calls[0]["strategy"] == "text"+ assert calls[0]["query_context"] == "question"++ router._record_to_toin(+ CompressionStrategy.SMART_CRUSHER,+ "x",+ "x",+ original_tokens=10,+ compressed_tokens=4,+ )+ router._record_to_toin(+ CompressionStrategy.TEXT,+ "x",+ "x",+ original_tokens=2,+ compressed_tokens=2,+ )+ monkeypatch.setattr(content_router_module, "_create_content_signature", lambda **kwargs: None)+ router._record_to_toin(+ CompressionStrategy.TEXT,+ "x",+ "y",+ original_tokens=5,+ compressed_tokens=1,+ )+ assert len(calls) == 1diff --git a/tests/test_transforms_log_compressor.py b/tests/test_transforms_log_compressor.pyindex b273bb846..b31649a0a 100644--- a/tests/test_transforms_log_compressor.py+++ b/tests/test_transforms_log_compressor.py@@ -1,183 +1,183 @@-from __future__ import annotations--from types import SimpleNamespace--import pytest--from headroom.transforms.log_compressor import (- LogCompressionResult,- LogCompressor,- LogCompressorConfig,- LogFormat,- LogLevel,- LogLine,-)---def test_detect_parse_and_score_log_lines() -> None:- compressor = LogCompressor(LogCompressorConfig(stack_trace_max_lines=2))- pytest_lines = [- "============================= test session starts =============================",- "collected 2 items",- "ERROR critical failure",- "Traceback (most recent call last)",- ' File "app.py", line 10',- "",- "2 failed, 1 warning",- ]- assert compressor._detect_format(pytest_lines) is LogFormat.PYTEST- assert compressor._detect_format(["npm ERR! missing script"]) is LogFormat.NPM- assert compressor._detect_format(["Compiling app", "warning: check this"]) is LogFormat.CARGO- assert (- compressor._detect_format(["PASS src/app.test.js", "Test Suites: 1 failed"])- is LogFormat.JEST- )- assert compressor._detect_format(["make: *** fail", "gcc -o app app.c"]) is LogFormat.MAKE- assert compressor._detect_format(["unclassified line"]) is LogFormat.GENERIC-- parsed = compressor._parse_lines(pytest_lines)- assert parsed[0].is_summary is True- assert parsed[2].level is LogLevel.ERROR- assert parsed[3].is_stack_trace is True- assert parsed[4].is_stack_trace is True- assert parsed[6].is_summary is True- assert compressor._score_line(LogLine(1, "warn", level=LogLevel.WARN)) == 0.5- assert (- compressor._score_line(- LogLine(2, "error summary", level=LogLevel.ERROR, is_stack_trace=True, is_summary=True)- )- == 1.0- )---def test_select_dedupe_add_context_and_format_output(monkeypatch: pytest.MonkeyPatch) -> None:- compressor = LogCompressor(- LogCompressorConfig(- max_errors=2,- max_warnings=1,- error_context_lines=1,- max_stack_traces=1,- stack_trace_max_lines=2,- )- )- monkeypatch.setitem(- __import__("sys").modules,- "headroom.transforms.adaptive_sizer",- SimpleNamespace(compute_optimal_k=lambda items, **kwargs: 6),- )- log_lines = [- LogLine(0, "info line", level=LogLevel.INFO, score=0.1),- LogLine(1, "ERROR first", level=LogLevel.ERROR, score=1.0),- LogLine(2, "context after first", level=LogLevel.UNKNOWN, score=0.1),- LogLine(3, "WARNING /tmp/a/123 issue", level=LogLevel.WARN, score=0.5),- LogLine(4, "WARNING /tmp/b/999 issue", level=LogLevel.WARN, score=0.5),- LogLine(5, "FAIL final", level=LogLevel.FAIL, score=1.0),- LogLine(6, "Traceback (most recent call last)", is_stack_trace=True, score=0.4),- LogLine(7, ' File "app.py", line 2', is_stack_trace=True, score=0.4),- LogLine(8, "1 failed, 1 warning", is_summary=True, score=0.5),- ]- selected = compressor._select_lines(log_lines)- assert [line.line_number for line in selected] == [1, 3, 4, 5, 6, 8]-- assert compressor._select_with_first_last(log_lines[:2], max_count=5) == log_lines[:2]- many_errors = [- LogLine(10, "first", level=LogLevel.ERROR, score=0.1),- LogLine(11, "mid", level=LogLevel.ERROR, score=0.9),- LogLine(12, "last", level=LogLevel.ERROR, score=0.2),- ]- trimmed = compressor._select_with_first_last(many_errors, max_count=2)- assert trimmed == [many_errors[0], many_errors[2]]- deduped = compressor._dedupe_similar(log_lines[3:5])- assert len(deduped) == 1-- output, stats = compressor._format_output(selected, log_lines)- assert stats == {- "errors": 1,- "fails": 1,- "warnings": 2,- "info": 1,- "total": 9,- "selected": 6,- }- assert output.endswith("[3 lines omitted: 1 ERROR, 1 FAIL, 2 WARN, 1 INFO]")---def test_log_compressor_compress_and_ccr_paths(monkeypatch: pytest.MonkeyPatch) -> None:- compressor = LogCompressor(LogCompressorConfig(enable_ccr=True, min_lines_for_ccr=3))- short = compressor.compress("a\nb")- assert short.format_detected is LogFormat.GENERIC- assert short.compression_ratio == 1.0-- monkeypatch.setattr(compressor, "_detect_format", lambda lines: LogFormat.NPM)- parsed = [LogLine(0, "npm ERR! boom", level=LogLevel.ERROR, score=1.0)]- monkeypatch.setattr(compressor, "_parse_lines", lambda lines: parsed)- monkeypatch.setattr(compressor, "_select_lines", lambda log_lines, bias=1.0: parsed)- monkeypatch.setattr(- compressor,- "_format_output",- lambda selected, all_lines: (- "tiny",- {"errors": 1, "fails": 0, "warnings": 0, "info": 0, "total": 3, "selected": 1},- ),- )- monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: "deadbeef")- result = compressor.compress(- "x\ny\nz\nvery verbose fourth line to improve compression ratio math"- )- assert result.format_detected is LogFormat.NPM- assert result.cache_key == "deadbeef"- assert result.stats["errors"] == 1- assert result.compressed.endswith("[4 lines compressed to 1. Retrieve more: hash=deadbeef]")-- monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: None)- no_cache = compressor.compress(- "x\ny\nz\nvery verbose fourth line to improve compression ratio math"- )- assert no_cache.cache_key is None- assert no_cache.compressed == "tiny"-- monkeypatch.setattr(- compressor,- "_format_output",- lambda selected, all_lines: (- "this output is intentionally much longer than the original content",- {"errors": 1, "fails": 0, "warnings": 0, "info": 0, "total": 4, "selected": 1},- ),- )- high_ratio = compressor.compress("x\ny\nz\nw")- assert high_ratio.cache_key is None---def test_store_in_ccr_and_result_properties(monkeypatch: pytest.MonkeyPatch) -> None:- compressor = LogCompressor()- monkeypatch.setitem(- __import__("sys").modules,- "headroom.cache.compression_store",- SimpleNamespace(- get_compression_store=lambda: SimpleNamespace(- store=lambda original, compressed, original_item_count=0: "stored-log"- )- ),- )- assert compressor._store_in_ccr("orig", "comp", 10) == "stored-log"-- def broken_store():- raise RuntimeError("boom")-- monkeypatch.setitem(- __import__("sys").modules,- "headroom.cache.compression_store",- SimpleNamespace(get_compression_store=broken_store),- )- assert compressor._store_in_ccr("orig", "comp", 10) is None-- result = LogCompressionResult(- compressed="small",- original="this is a substantially longer log body",- original_line_count=20,- compressed_line_count=5,- format_detected=LogFormat.GENERIC,- compression_ratio=0.25,- )- assert result.tokens_saved_estimate > 0- assert result.lines_omitted == 15+from __future__ import annotations++from types import SimpleNamespace++import pytest++from headroom.transforms.log_compressor import (+ LogCompressionResult,+ LogCompressor,+ LogCompressorConfig,+ LogFormat,+ LogLevel,+ LogLine,+)+++def test_detect_parse_and_score_log_lines() -> None:+ compressor = LogCompressor(LogCompressorConfig(stack_trace_max_lines=2))+ pytest_lines = [+ "============================= test session starts =============================",+ "collected 2 items",+ "ERROR critical failure",+ "Traceback (most recent call last)",+ ' File "app.py", line 10',+ "",+ "2 failed, 1 warning",+ ]+ assert compressor._detect_format(pytest_lines) is LogFormat.PYTEST+ assert compressor._detect_format(["npm ERR! missing script"]) is LogFormat.NPM+ assert compressor._detect_format(["Compiling app", "warning: check this"]) is LogFormat.CARGO+ assert (+ compressor._detect_format(["PASS src/app.test.js", "Test Suites: 1 failed"])+ is LogFormat.JEST+ )+ assert compressor._detect_format(["make: *** fail", "gcc -o app app.c"]) is LogFormat.MAKE+ assert compressor._detect_format(["unclassified line"]) is LogFormat.GENERIC++ parsed = compressor._parse_lines(pytest_lines)+ assert parsed[0].is_summary is True+ assert parsed[2].level is LogLevel.ERROR+ assert parsed[3].is_stack_trace is True+ assert parsed[4].is_stack_trace is True+ assert parsed[6].is_summary is True+ assert compressor._score_line(LogLine(1, "warn", level=LogLevel.WARN)) == 0.5+ assert (+ compressor._score_line(+ LogLine(2, "error summary", level=LogLevel.ERROR, is_stack_trace=True, is_summary=True)+ )+ == 1.0+ )+++def test_select_dedupe_add_context_and_format_output(monkeypatch: pytest.MonkeyPatch) -> None:+ compressor = LogCompressor(+ LogCompressorConfig(+ max_errors=2,+ max_warnings=1,+ error_context_lines=1,+ max_stack_traces=1,+ stack_trace_max_lines=2,+ )+ )+ monkeypatch.setitem(+ __import__("sys").modules,+ "headroom.transforms.adaptive_sizer",+ SimpleNamespace(compute_optimal_k=lambda items, **kwargs: 6),+ )+ log_lines = [+ LogLine(0, "info line", level=LogLevel.INFO, score=0.1),+ LogLine(1, "ERROR first", level=LogLevel.ERROR, score=1.0),+ LogLine(2, "context after first", level=LogLevel.UNKNOWN, score=0.1),+ LogLine(3, "WARNING /tmp/a/123 issue", level=LogLevel.WARN, score=0.5),+ LogLine(4, "WARNING /tmp/b/999 issue", level=LogLevel.WARN, score=0.5),+ LogLine(5, "FAIL final", level=LogLevel.FAIL, score=1.0),+ LogLine(6, "Traceback (most recent call last)", is_stack_trace=True, score=0.4),+ LogLine(7, ' File "app.py", line 2', is_stack_trace=True, score=0.4),+ LogLine(8, "1 failed, 1 warning", is_summary=True, score=0.5),+ ]+ selected = compressor._select_lines(log_lines)+ assert [line.line_number for line in selected] == [1, 3, 4, 5, 6, 8]++ assert compressor._select_with_first_last(log_lines[:2], max_count=5) == log_lines[:2]+ many_errors = [+ LogLine(10, "first", level=LogLevel.ERROR, score=0.1),+ LogLine(11, "mid", level=LogLevel.ERROR, score=0.9),+ LogLine(12, "last", level=LogLevel.ERROR, score=0.2),+ ]+ trimmed = compressor._select_with_first_last(many_errors, max_count=2)+ assert trimmed == [many_errors[0], many_errors[2]]+ deduped = compressor._dedupe_similar(log_lines[3:5])+ assert len(deduped) == 1++ output, stats = compressor._format_output(selected, log_lines)+ assert stats == {+ "errors": 1,+ "fails": 1,+ "warnings": 2,+ "info": 1,+ "total": 9,+ "selected": 6,+ }+ assert output.endswith("[3 lines omitted: 1 ERROR, 1 FAIL, 2 WARN, 1 INFO]")+++def test_log_compressor_compress_and_ccr_paths(monkeypatch: pytest.MonkeyPatch) -> None:+ compressor = LogCompressor(LogCompressorConfig(enable_ccr=True, min_lines_for_ccr=3))+ short = compressor.compress("a\nb")+ assert short.format_detected is LogFormat.GENERIC+ assert short.compression_ratio == 1.0++ monkeypatch.setattr(compressor, "_detect_format", lambda lines: LogFormat.NPM)+ parsed = [LogLine(0, "npm ERR! boom", level=LogLevel.ERROR, score=1.0)]+ monkeypatch.setattr(compressor, "_parse_lines", lambda lines: parsed)+ monkeypatch.setattr(compressor, "_select_lines", lambda log_lines, bias=1.0: parsed)+ monkeypatch.setattr(+ compressor,+ "_format_output",+ lambda selected, all_lines: (+ "tiny",+ {"errors": 1, "fails": 0, "warnings": 0, "info": 0, "total": 3, "selected": 1},+ ),+ )+ monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: "deadbeef")+ result = compressor.compress(+ "x\ny\nz\nvery verbose fourth line to improve compression ratio math"+ )+ assert result.format_detected is LogFormat.NPM+ assert result.cache_key == "deadbeef"+ assert result.stats["errors"] == 1+ assert result.compressed.endswith("[4 lines compressed to 1. Retrieve more: hash=deadbeef]")++ monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: None)+ no_cache = compressor.compress(+ "x\ny\nz\nvery verbose fourth line to improve compression ratio math"+ )+ assert no_cache.cache_key is None+ assert no_cache.compressed == "tiny"++ monkeypatch.setattr(+ compressor,+ "_format_output",+ lambda selected, all_lines: (+ "this output is intentionally much longer than the original content",+ {"errors": 1, "fails": 0, "warnings": 0, "info": 0, "total": 4, "selected": 1},+ ),+ )+ high_ratio = compressor.compress("x\ny\nz\nw")+ assert high_ratio.cache_key is None+++def test_store_in_ccr_and_result_properties(monkeypatch: pytest.MonkeyPatch) -> None:+ compressor = LogCompressor()+ monkeypatch.setitem(+ __import__("sys").modules,+ "headroom.cache.compression_store",+ SimpleNamespace(+ get_compression_store=lambda: SimpleNamespace(+ store=lambda original, compressed, original_item_count=0: "stored-log"+ )+ ),+ )+ assert compressor._store_in_ccr("orig", "comp", 10) == "stored-log"++ def broken_store():+ raise RuntimeError("boom")++ monkeypatch.setitem(+ __import__("sys").modules,+ "headroom.cache.compression_store",+ SimpleNamespace(get_compression_store=broken_store),+ )+ assert compressor._store_in_ccr("orig", "comp", 10) is None++ result = LogCompressionResult(+ compressed="small",+ original="this is a substantially longer log body",+ original_line_count=20,+ compressed_line_count=5,+ format_detected=LogFormat.GENERIC,+ compression_ratio=0.25,+ )+ assert result.tokens_saved_estimate > 0+ assert result.lines_omitted == 15diff --git a/tests/test_transforms_package.py b/tests/test_transforms_package.pyindex 95b604a8b..97eb1b6ca 100644--- a/tests/test_transforms_package.py+++ b/tests/test_transforms_package.py@@ -1,26 +1,26 @@-from __future__ import annotations--import pytest--import headroom.transforms as transforms---def test_transforms_getattr_and_dir(monkeypatch: pytest.MonkeyPatch) -> None:- monkeypatch.setattr(transforms, "_HTML_EXTRACTOR_AVAILABLE", True)- monkeypatch.setattr(- transforms,- "_LAZY_EXPORTS",- {"FakeExport": ("fake.module", "VALUE")},- )- monkeypatch.setattr(transforms, "import_module", lambda name: type("M", (), {"VALUE": 123})())-- assert transforms.__getattr__("_HTML_EXTRACTOR_AVAILABLE") is True- assert transforms.__getattr__("FakeExport") == 123- assert transforms.FakeExport == 123- assert "FakeExport" in transforms.__dir__()-- with pytest.raises(AttributeError, match="__path__"):- transforms.__getattr__("__path__")-- with pytest.raises(AttributeError, match="MissingExport"):- transforms.__getattr__("MissingExport")+from __future__ import annotations++import pytest++import headroom.transforms as transforms+++def test_transforms_getattr_and_dir(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(transforms, "_HTML_EXTRACTOR_AVAILABLE", True)+ monkeypatch.setattr(+ transforms,+ "_LAZY_EXPORTS",+ {"FakeExport": ("fake.module", "VALUE")},+ )+ monkeypatch.setattr(transforms, "import_module", lambda name: type("M", (), {"VALUE": 123})())++ assert transforms.__getattr__("_HTML_EXTRACTOR_AVAILABLE") is True+ assert transforms.__getattr__("FakeExport") == 123+ assert transforms.FakeExport == 123+ assert "FakeExport" in transforms.__dir__()++ with pytest.raises(AttributeError, match="__path__"):+ transforms.__getattr__("__path__")++ with pytest.raises(AttributeError, match="MissingExport"):+ transforms.__getattr__("MissingExport")diff --git a/tests/test_transforms_search_compressor.py b/tests/test_transforms_search_compressor.pyindex a2473347e..76d90b0b2 100644--- a/tests/test_transforms_search_compressor.py+++ b/tests/test_transforms_search_compressor.py@@ -1,143 +1,143 @@-from __future__ import annotations--from types import SimpleNamespace--import pytest--from headroom.transforms.search_compressor import (- FileMatches,- SearchCompressionResult,- SearchCompressor,- SearchCompressorConfig,- SearchMatch,-)---def test_parse_score_select_and_format_search_results(monkeypatch: pytest.MonkeyPatch) -> None:- compressor = SearchCompressor(- SearchCompressorConfig(- max_matches_per_file=3,- max_total_matches=4,- max_files=2,- context_keywords=["auth"],- )- )- content = "\n".join(- [- "src/auth.py:10:ERROR auth failed",- "src/auth.py-11-warning auth retry",- "src/auth.py:12:plain auth line",- "src/db.py:2:warning token expired",- "not a match",- ]- )- parsed = compressor._parse_search_results(content)- assert set(parsed) == {"src/auth.py", "src/db.py"}- assert parsed["src/auth.py"].first == SearchMatch(- file="src/auth.py", line_number=10, content="ERROR auth failed"- )- assert parsed["src/auth.py"].last.line_number == 12-- compressor._score_matches(parsed, "find auth error")- assert parsed["src/auth.py"].matches[0].score == 1.0- assert parsed["src/db.py"].matches[0].score > 0-- monkeypatch.setitem(- __import__("sys").modules,- "headroom.transforms.adaptive_sizer",- SimpleNamespace(compute_optimal_k=lambda items, **kwargs: 4),- )- selected = compressor._select_matches(parsed, bias=1.2)- assert list(selected) == ["src/auth.py", "src/db.py"]- assert [m.line_number for m in selected["src/auth.py"].matches] == [10, 11, 12]-- formatted, summaries = compressor._format_output(- selected,- {- **parsed,- "src/db.py": FileMatches(- file="src/db.py",- matches=[- SearchMatch(file="src/db.py", line_number=2, content="warning token expired"),- SearchMatch(file="src/db.py", line_number=3, content="another line"),- ],- ),- },- )- assert "src/auth.py:10:ERROR auth failed" in formatted- assert summaries["src/db.py"] == "[... and 1 more matches in src/db.py]"---def test_search_compressor_compress_paths_and_ccr(monkeypatch: pytest.MonkeyPatch) -> None:- compressor = SearchCompressor(- SearchCompressorConfig(enable_ccr=True, min_matches_for_ccr=2, context_keywords=["auth"])- )- no_match = compressor.compress("plain text only")- assert no_match.original_match_count == 0- assert no_match.compressed == "plain text only"-- parsed = {- "src/auth.py": FileMatches(- file="src/auth.py",- matches=[- SearchMatch(file="src/auth.py", line_number=1, content="auth error"),- SearchMatch(file="src/auth.py", line_number=2, content="auth ok"),- ],- )- }- monkeypatch.setattr(compressor, "_parse_search_results", lambda content: parsed)- monkeypatch.setattr(compressor, "_score_matches", lambda file_matches, context: None)- monkeypatch.setattr(compressor, "_select_matches", lambda file_matches, bias=1.0: parsed)- monkeypatch.setattr(- compressor,- "_format_output",- lambda selected, original: ("short", {"src/auth.py": "summary"}),- )- monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: "abc123")-- result = compressor.compress("raw search", context="auth", bias=0.8)- assert result.original_match_count == 2- assert result.compressed_match_count == 2- assert result.cache_key == "abc123"- assert result.summaries == {"src/auth.py": "summary"}- assert result.compressed.endswith("[2 matches compressed to 2. Retrieve more: hash=abc123]")-- monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: None)- no_cache = compressor.compress("raw search", context="auth")- assert no_cache.cache_key is None- assert no_cache.compressed == "short"---def test_store_in_ccr_and_result_properties(monkeypatch: pytest.MonkeyPatch) -> None:- compressor = SearchCompressor()- monkeypatch.setitem(- __import__("sys").modules,- "headroom.cache.compression_store",- SimpleNamespace(- get_compression_store=lambda: SimpleNamespace(- store=lambda original, compressed, original_item_count=0: "stored-key"- )- ),- )- assert compressor._store_in_ccr("orig", "comp", 5) == "stored-key"-- def broken_store():- raise RuntimeError("boom")-- monkeypatch.setitem(- __import__("sys").modules,- "headroom.cache.compression_store",- SimpleNamespace(get_compression_store=broken_store),- )- assert compressor._store_in_ccr("orig", "comp", 5) is None-- result = SearchCompressionResult(- compressed="tiny",- original="this is a much longer original string",- original_match_count=10,- compressed_match_count=4,- files_affected=2,- compression_ratio=0.3,- )- assert result.tokens_saved_estimate > 0- assert result.matches_omitted == 6+from __future__ import annotations++from types import SimpleNamespace++import pytest++from headroom.transforms.search_compressor import (+ FileMatches,+ SearchCompressionResult,+ SearchCompressor,+ SearchCompressorConfig,+ SearchMatch,+)+++def test_parse_score_select_and_format_search_results(monkeypatch: pytest.MonkeyPatch) -> None:+ compressor = SearchCompressor(+ SearchCompressorConfig(+ max_matches_per_file=3,+ max_total_matches=4,+ max_files=2,+ context_keywords=["auth"],+ )+ )+ content = "\n".join(+ [+ "src/auth.py:10:ERROR auth failed",+ "src/auth.py-11-warning auth retry",+ "src/auth.py:12:plain auth line",+ "src/db.py:2:warning token expired",+ "not a match",+ ]+ )+ parsed = compressor._parse_search_results(content)+ assert set(parsed) == {"src/auth.py", "src/db.py"}+ assert parsed["src/auth.py"].first == SearchMatch(+ file="src/auth.py", line_number=10, content="ERROR auth failed"+ )+ assert parsed["src/auth.py"].last.line_number == 12++ compressor._score_matches(parsed, "find auth error")+ assert parsed["src/auth.py"].matches[0].score == 1.0+ assert parsed["src/db.py"].matches[0].score > 0++ monkeypatch.setitem(+ __import__("sys").modules,+ "headroom.transforms.adaptive_sizer",+ SimpleNamespace(compute_optimal_k=lambda items, **kwargs: 4),+ )+ selected = compressor._select_matches(parsed, bias=1.2)+ assert list(selected) == ["src/auth.py", "src/db.py"]+ assert [m.line_number for m in selected["src/auth.py"].matches] == [10, 11, 12]++ formatted, summaries = compressor._format_output(+ selected,+ {+ **parsed,+ "src/db.py": FileMatches(+ file="src/db.py",+ matches=[+ SearchMatch(file="src/db.py", line_number=2, content="warning token expired"),+ SearchMatch(file="src/db.py", line_number=3, content="another line"),+ ],+ ),+ },+ )+ assert "src/auth.py:10:ERROR auth failed" in formatted+ assert summaries["src/db.py"] == "[... and 1 more matches in src/db.py]"+++def test_search_compressor_compress_paths_and_ccr(monkeypatch: pytest.MonkeyPatch) -> None:+ compressor = SearchCompressor(+ SearchCompressorConfig(enable_ccr=True, min_matches_for_ccr=2, context_keywords=["auth"])+ )+ no_match = compressor.compress("plain text only")+ assert no_match.original_match_count == 0+ assert no_match.compressed == "plain text only"++ parsed = {+ "src/auth.py": FileMatches(+ file="src/auth.py",+ matches=[+ SearchMatch(file="src/auth.py", line_number=1, content="auth error"),+ SearchMatch(file="src/auth.py", line_number=2, content="auth ok"),+ ],+ )+ }+ monkeypatch.setattr(compressor, "_parse_search_results", lambda content: parsed)+ monkeypatch.setattr(compressor, "_score_matches", lambda file_matches, context: None)+ monkeypatch.setattr(compressor, "_select_matches", lambda file_matches, bias=1.0: parsed)+ monkeypatch.setattr(+ compressor,+ "_format_output",+ lambda selected, original: ("short", {"src/auth.py": "summary"}),+ )+ monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: "abc123")++ result = compressor.compress("raw search", context="auth", bias=0.8)+ assert result.original_match_count == 2+ assert result.compressed_match_count == 2+ assert result.cache_key == "abc123"+ assert result.summaries == {"src/auth.py": "summary"}+ assert result.compressed.endswith("[2 matches compressed to 2. Retrieve more: hash=abc123]")++ monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: None)+ no_cache = compressor.compress("raw search", context="auth")+ assert no_cache.cache_key is None+ assert no_cache.compressed == "short"+++def test_store_in_ccr_and_result_properties(monkeypatch: pytest.MonkeyPatch) -> None:+ compressor = SearchCompressor()+ monkeypatch.setitem(+ __import__("sys").modules,+ "headroom.cache.compression_store",+ SimpleNamespace(+ get_compression_store=lambda: SimpleNamespace(+ store=lambda original, compressed, original_item_count=0: "stored-key"+ )+ ),+ )+ assert compressor._store_in_ccr("orig", "comp", 5) == "stored-key"++ def broken_store():+ raise RuntimeError("boom")++ monkeypatch.setitem(+ __import__("sys").modules,+ "headroom.cache.compression_store",+ SimpleNamespace(get_compression_store=broken_store),+ )+ assert compressor._store_in_ccr("orig", "comp", 5) is None++ result = SearchCompressionResult(+ compressed="tiny",+ original="this is a much longer original string",+ original_match_count=10,+ compressed_match_count=4,+ files_affected=2,+ compression_ratio=0.3,+ )+ assert result.tokens_saved_estimate > 0+ assert result.matches_omitted == 6diff --git a/tests/test_utils.py b/tests/test_utils.pyindex 5e6b6bbf0..7d78bb27d 100644--- a/tests/test_utils.py+++ b/tests/test_utils.py@@ -1,122 +1,122 @@-from __future__ import annotations--from datetime import datetime--from headroom import utils---class FakeProvider:- def __init__(self, result):- self.result = result- self.calls: list[tuple[int, int, str, int]] = []-- def estimate_cost(- self, input_tokens: int, output_tokens: int, model: str, cached_tokens: int = 0- ):- self.calls.append((input_tokens, output_tokens, model, cached_tokens))- return self.result---def test_hash_helpers_and_request_id() -> None:- request_id = utils.generate_request_id()- assert len(request_id) == 36- assert request_id.count("-") == 4-- assert (- utils.compute_hash("hello")- == "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"- )- assert utils.compute_hash("hi\ud800") == utils.compute_hash(- "hi\ud800".encode("utf-8", "surrogatepass")- )- assert utils.compute_short_hash("hello", length=8) == "2cf24dba"- assert utils.fast_hash("hello", length=8) == "5d41402a"---def test_extract_user_query_and_message_hashes() -> None:- messages = [- {"role": "system", "content": "rules"},- {"role": "user", "content": " "},- {"role": "assistant", "content": "skip"},- {- "role": "user",- "content": [{"type": "image"}, {"type": "text", "text": " latest question "}],- },- ]- assert utils.extract_user_query(messages) == "latest question"- assert utils.extract_user_query([{"role": "assistant", "content": "skip"}]) == ""-- hash_one = utils.compute_messages_hash(messages)- hash_two = utils.compute_messages_hash(list(messages))- assert hash_one == hash_two- assert len(hash_one) == 16-- prefix_default = utils.compute_prefix_hash(- [- {"role": "system", "content": "a"},- {"role": "system", "content": "b"},- {"role": "user", "content": "c"},- {"role": "assistant", "content": "d"},- ]- )- prefix_explicit = utils.compute_prefix_hash(- [- {"role": "system", "content": "a"},- {"role": "system", "content": "b"},- {"role": "user", "content": "c"},- {"role": "assistant", "content": "d"},- ],- prefix_count=3,- )- assert prefix_default == prefix_explicit- assert utils.compute_prefix_hash([]) == utils.compute_short_hash("")---def test_timestamp_marker_and_json_helpers() -> None:- ts = utils.format_timestamp(datetime(2026, 4, 23, 6, 0, 0))- assert ts == "2026-04-23T06:00:00Z"- assert utils.parse_timestamp(ts) == datetime(2026, 4, 23, 6, 0, 0)- assert utils.parse_timestamp("2026-04-23T06:00:00") == datetime(2026, 4, 23, 6, 0, 0)-- marker = utils.create_marker("tool_digest", sha256="abc", count="2")- assert marker == '<headroom:tool_digest sha256="abc" count="2">'- assert utils.create_tool_digest_marker("abc") == '<headroom:tool_digest sha256="abc">'- assert utils.create_dropped_context_marker("budget") == (- '<headroom:dropped_context reason="budget">'- )- assert utils.create_dropped_context_marker("budget", count=4) == (- '<headroom:dropped_context reason="budget" count="4">'- )- assert utils.create_truncated_marker(100, 25) == (- '<headroom:truncated original="100" truncated_to="25">'- )-- extracted = utils.extract_markers(- 'x <headroom:tool_digest sha256="abc"> y <headroom:dropped_context reason="budget" count="2">'- )- assert extracted == [- {"type": "tool_digest", "attributes": {"sha256": "abc"}},- {"type": "dropped_context", "attributes": {"reason": "budget", "count": "2"}},- ]-- assert utils.safe_json_loads('{"ok": true}') == ({"ok": True}, True)- assert utils.safe_json_loads("{bad") == (None, False)- assert utils.safe_json_dumps({"emoji": "café"}) == '{"emoji":"café"}'---def test_cost_formatting_and_deep_copy() -> None:- provider = FakeProvider("1.25")- assert utils.estimate_cost(100, 50, "gpt-4o", cached_tokens=10, provider=provider) == 1.25- assert provider.calls == [(100, 50, "gpt-4o", 10)]- assert utils.estimate_cost(1, 1, "gpt-4o", provider=None) is None-- none_provider = FakeProvider(None)- assert utils.estimate_cost(1, 1, "gpt-4o", provider=none_provider) is None-- assert utils.format_cost(0.0099) == "$0.0099"- assert utils.format_cost(1.234) == "$1.23"-- messages = [{"role": "user", "content": {"nested": ["a"]}}]- copied = utils.deep_copy_messages(messages)- copied[0]["content"]["nested"].append("b")- assert messages == [{"role": "user", "content": {"nested": ["a"]}}]+from __future__ import annotations++from datetime import datetime++from headroom import utils+++class FakeProvider:+ def __init__(self, result):+ self.result = result+ self.calls: list[tuple[int, int, str, int]] = []++ def estimate_cost(+ self, input_tokens: int, output_tokens: int, model: str, cached_tokens: int = 0+ ):+ self.calls.append((input_tokens, output_tokens, model, cached_tokens))+ return self.result+++def test_hash_helpers_and_request_id() -> None:+ request_id = utils.generate_request_id()+ assert len(request_id) == 36+ assert request_id.count("-") == 4++ assert (+ utils.compute_hash("hello")+ == "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"+ )+ assert utils.compute_hash("hi\ud800") == utils.compute_hash(+ "hi\ud800".encode("utf-8", "surrogatepass")+ )+ assert utils.compute_short_hash("hello", length=8) == "2cf24dba"+ assert utils.fast_hash("hello", length=8) == "5d41402a"+++def test_extract_user_query_and_message_hashes() -> None:+ messages = [+ {"role": "system", "content": "rules"},+ {"role": "user", "content": " "},+ {"role": "assistant", "content": "skip"},+ {+ "role": "user",+ "content": [{"type": "image"}, {"type": "text", "text": " latest question "}],+ },+ ]+ assert utils.extract_user_query(messages) == "latest question"+ assert utils.extract_user_query([{"role": "assistant", "content": "skip"}]) == ""++ hash_one = utils.compute_messages_hash(messages)+ hash_two = utils.compute_messages_hash(list(messages))+ assert hash_one == hash_two+ assert len(hash_one) == 16++ prefix_default = utils.compute_prefix_hash(+ [+ {"role": "system", "content": "a"},+ {"role": "system", "content": "b"},+ {"role": "user", "content": "c"},+ {"role": "assistant", "content": "d"},+ ]+ )+ prefix_explicit = utils.compute_prefix_hash(+ [+ {"role": "system", "content": "a"},+ {"role": "system", "content": "b"},+ {"role": "user", "content": "c"},+ {"role": "assistant", "content": "d"},+ ],+ prefix_count=3,+ )+ assert prefix_default == prefix_explicit+ assert utils.compute_prefix_hash([]) == utils.compute_short_hash("")+++def test_timestamp_marker_and_json_helpers() -> None:+ ts = utils.format_timestamp(datetime(2026, 4, 23, 6, 0, 0))+ assert ts == "2026-04-23T06:00:00Z"+ assert utils.parse_timestamp(ts) == datetime(2026, 4, 23, 6, 0, 0)+ assert utils.parse_timestamp("2026-04-23T06:00:00") == datetime(2026, 4, 23, 6, 0, 0)++ marker = utils.create_marker("tool_digest", sha256="abc", count="2")+ assert marker == '<headroom:tool_digest sha256="abc" count="2">'+ assert utils.create_tool_digest_marker("abc") == '<headroom:tool_digest sha256="abc">'+ assert utils.create_dropped_context_marker("budget") == (+ '<headroom:dropped_context reason="budget">'+ )+ assert utils.create_dropped_context_marker("budget", count=4) == (+ '<headroom:dropped_context reason="budget" count="4">'+ )+ assert utils.create_truncated_marker(100, 25) == (+ '<headroom:truncated original="100" truncated_to="25">'+ )++ extracted = utils.extract_markers(+ 'x <headroom:tool_digest sha256="abc"> y <headroom:dropped_context reason="budget" count="2">'+ )+ assert extracted == [+ {"type": "tool_digest", "attributes": {"sha256": "abc"}},+ {"type": "dropped_context", "attributes": {"reason": "budget", "count": "2"}},+ ]++ assert utils.safe_json_loads('{"ok": true}') == ({"ok": True}, True)+ assert utils.safe_json_loads("{bad") == (None, False)+ assert utils.safe_json_dumps({"emoji": "café"}) == '{"emoji":"café"}'+++def test_cost_formatting_and_deep_copy() -> None:+ provider = FakeProvider("1.25")+ assert utils.estimate_cost(100, 50, "gpt-4o", cached_tokens=10, provider=provider) == 1.25+ assert provider.calls == [(100, 50, "gpt-4o", 10)]+ assert utils.estimate_cost(1, 1, "gpt-4o", provider=None) is None++ none_provider = FakeProvider(None)+ assert utils.estimate_cost(1, 1, "gpt-4o", provider=none_provider) is None++ assert utils.format_cost(0.0099) == "$0.0099"+ assert utils.format_cost(1.234) == "$1.23"++ messages = [{"role": "user", "content": {"nested": ["a"]}}]+ copied = utils.deep_copy_messages(messages)+ copied[0]["content"]["nested"].append("b")+ assert messages == [{"role": "user", "content": {"nested": ["a"]}}]