Skip to content

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.

chore: renormalize line endings to LF

Garmefd2ac1ca4d8
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 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)
-# =============================================================================
-
-
-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)
+# =============================================================================
+
+
+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.py
index 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 _pipeline
diff --git a/headroom/copilot_auth.py b/headroom/copilot_auth.py
index 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 resolved
diff --git a/headroom/install/health.py b/headroom/install/health.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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__.py
index 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.py
index 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.py
index 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 None
diff --git a/headroom/subscription/codex_rate_limits.py b/headroom/subscription/codex_rate_limits.py
index 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 _state
diff --git a/headroom/subscription/copilot_quota.py b/headroom/subscription/copilot_quota.py
index 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 _singleton
diff --git a/headroom/subscription/models.py b/headroom/subscription/models.py
index 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 d
diff --git a/headroom/subscription/session_tracking.py b/headroom/subscription/session_tracking.py
index 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.py
index 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.py
index 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.compressed
diff --git a/scripts/changelog-gen.py b/scripts/changelog-gen.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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_one
diff --git a/tests/test_ccr_response_handler_extra.py b/tests/test_ccr_response_handler_extra.py
index 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.py
index 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.output
diff --git a/tests/test_cli_learn.py b/tests/test_cli_learn.py
index 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.output
diff --git a/tests/test_codex_rate_limits.py b/tests/test_codex_rate_limits.py
index 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.0
diff --git a/tests/test_compress_api.py b/tests/test_compress_api.py
index 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 data
diff --git a/tests/test_compress_failure.py b/tests/test_compress_failure.py
index 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.py
index 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.py
index 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 None
diff --git a/tests/test_evals_metrics.py b/tests/test_evals_metrics.py
index 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.0
diff --git a/tests/test_exceptions.py b/tests/test_exceptions.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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_repo
diff --git a/tests/test_pricing.py b/tests/test_pricing.py
index 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.py
index 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 None
diff --git a/tests/test_provider_aider.py b/tests/test_provider_aider.py
index 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.py
index 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.py
index 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.py
index 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 False
diff --git a/tests/test_provider_openclaw_wrap.py b/tests/test_provider_openclaw_wrap.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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 == 200
diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.py
index 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.py
index 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.py
index 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 html
diff --git a/tests/test_quota_registry.py b/tests/test_quota_registry.py
index 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) == 0
diff --git a/tests/test_release_version.py b/tests/test_release_version.py
index 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.py
index 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 content
diff --git a/tests/test_reporting.py b/tests/test_reporting.py
index 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 True
diff --git a/tests/test_subscription_base.py b/tests/test_subscription_base.py
index 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.py
index 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 None
diff --git a/tests/test_subscription_tracker.py b/tests/test_subscription_tracker.py
index 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 == 0
diff --git a/tests/test_tokenizer.py b/tests/test_tokenizer.py
index 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.py
index 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 False
diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.py
index 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) == 1
diff --git a/tests/test_transforms_log_compressor.py b/tests/test_transforms_log_compressor.py
index 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 == 15
diff --git a/tests/test_transforms_package.py b/tests/test_transforms_package.py
index 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.py
index 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 == 6
diff --git a/tests/test_utils.py b/tests/test_utils.py
index 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"]}}]