Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
Merge upstream/main into feat/canonical-pipeline
JerrettDavis88dc15ea852f
diff --cc .claude-plugin/marketplace.jsonindex afc9d8b26,ca48115ac..b3db2229c--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@@ -5,14 -5,14 +5,14 @@@},"metadata": {"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",- "version": "0.10.0"- "version": "0.9.2"++ "version": "0.11.0"},"plugins": [{"name": "headroom","source": "./plugins/headroom-agent-hooks","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",- "version": "0.10.0",- "version": "0.9.2",++ "version": "0.11.0","author": {"name": "Headroom Contributors","url": "https://github.com/chopratejas/headroom"diff --cc .github/plugin/marketplace.jsonindex afc9d8b26,ca48115ac..b3db2229c--- a/.github/plugin/marketplace.json+++ b/.github/plugin/marketplace.json@@@ -5,14 -5,14 +5,14 @@@},"metadata": {"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",- "version": "0.10.0"- "version": "0.9.2"++ "version": "0.11.0"},"plugins": [{"name": "headroom","source": "./plugins/headroom-agent-hooks","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",- "version": "0.10.0",- "version": "0.9.2",++ "version": "0.11.0","author": {"name": "Headroom Contributors","url": "https://github.com/chopratejas/headroom"diff --cc headroom/cli/wrap.pyindex 51e0402d6,1ccedb849..8f3e5e725--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@@ -1,2069 -1,2240 +1,2134 @@@--"""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-import urllib.error-import urllib.request--from pathlib import Path- from typing import Any-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.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 headroom.copilot_auth import DEFAULT_API_URL as COPILOT_API_URL-from headroom.copilot_auth import has_oauth_auth, resolve_client_bearer_token----from .main import main---def _live_wrap_module() -> Any:- """Return the current live wrap module instance.-- CLI tests sometimes reload `headroom.cli.wrap` while still invoking Click- command callbacks that were registered from an older module instance. By- resolving helper calls through `sys.modules[__name__]`, patched helpers on- the live module continue to affect those callbacks.- """-- 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 -->"------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 — only writes if the section is missing-- or the port changed.-- """-- config_dir = Path.home() / ".codex"-- config_file = config_dir / "config.toml"---- # model_provider must be a top-level TOML key (before any [section]).-- # The [model_providers.headroom] table can go at the end.-- top_level_marker = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"-- top_level_block = f'{top_level_marker}\nmodel_provider = "headroom"\n'-- provider_section = (-- f"\n[model_providers.headroom]\n"-- f'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"# --- end Headroom ---\n"-- )---- marker = top_level_marker-- end_marker = "# --- end Headroom ---"---- try:-- config_dir.mkdir(parents=True, exist_ok=True)---- if config_file.exists():-- content = config_file.read_text()-- if marker in content:-- # Remove existing Headroom blocks entirely-- start = content.index(marker)-- end = content.index(end_marker) + len(end_marker)-- content = content[:start].rstrip("\n") + content[end:].lstrip("\n")---- # Strip any stale top-level model_provider left behind-- import re---- content = re.sub(r'\nmodel_provider\s*=\s*"headroom"\n', "\n", content)---- # Place top-level key at the very beginning, provider table at the end-- content = top_level_block + "\n" + content.strip() + "\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 _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)---- 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)- if provider_type != "auto":- return provider_type-- effective_backend = backend or os.environ.get("HEADROOM_BACKEND") or "anthropic"- return "anthropic" if effective_backend == "anthropic" else "openai"------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)- url = f"http://127.0.0.1:{port}/health"- try:- with urllib.request.urlopen(url, timeout=2) as response:- payload = json.loads(response.read().decode("utf-8"))- except (OSError, urllib.error.URLError, ValueError, json.JSONDecodeError):- return None-- config = payload.get("config")- if not isinstance(config, dict):- return None- return config------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)- config = _query_proxy_config(port)- if config is None:- return None- backend = config.get("backend")- return backend if isinstance(backend, str) else None------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)- helpers = _live_wrap_module()- manifest = helpers._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)- if env.get("COPILOT_MODEL") or env.get("COPILOT_PROVIDER_MODEL_ID"):- return True-- for idx, arg in enumerate(copilot_args):- if arg == "--model" and idx + 1 < len(copilot_args):- return True- if arg.startswith("--model="):- return True-- return False---def _should_use_copilot_oauth(- *,- backend: str | None,- provider_type: str,- env: dict[str, str],-) -> bool:- """Prefer existing Copilot auth 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 = _find_persistent_manifest(port)- 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 _recover_persistent_proxy(port):- if helpers._recover_persistent_proxy(port):-- return None- raise click.ClickException(- f"Persistent deployment '{manifest.profile}' on port {port} is not healthy."- 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 _check_proxy(port):- if helpers._check_proxy(port):-- # Proxy is running — check if it has the features we need-- needs_restart = False- running_config = _query_proxy_config(port)- 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 _kill_proxy_by_pid(int(proxy_pid), port):- 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 = _start_proxy(- port,- learn=learn,- memory=memory,- agent_type=agent_type,- code_graph=code_graph,- backend=backend,- anyllm_provider=anyllm_provider,- region=region,- proc = cast(- subprocess.Popen[Any],- helpers._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 _check_proxy(port):- 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)- values = provider_ids or ()- seen: set[str] = set()- normalized: list[str] = []-- for entry in values:- provider_id = entry.strip()- if not provider_id or provider_id in seen:- continue- seen.add(provider_id)- normalized.append(provider_id)-- if normalized:- return normalized- return ["openai-codex"]------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)- if not raw_value:- return None-- try:- return json.loads(raw_value)- except json.JSONDecodeError:- return 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,- base_entry = existing_entry if isinstance(existing_entry, dict) else {}- existing_config = base_entry.get("config")- next_config = dict(existing_config) if isinstance(existing_config, dict) else {}-- next_config["proxyPort"] = proxy_port- next_config["autoStart"] = not no_auto_start- next_config["startupTimeoutMs"] = startup_timeout_ms- next_config["gatewayProviderIds"] = _normalize_openclaw_gateway_provider_ids(- gateway_provider_ids-- )-- if python_path:- next_config["pythonPath"] = python_path- else:- next_config.pop("pythonPath", None)-- return {- **base_entry,- "enabled": enabled,- "config": next_config,- }------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)- base_entry = existing_entry if isinstance(existing_entry, dict) else {}- existing_config = {}- if isinstance(existing_entry, dict) and isinstance(existing_entry.get("config"), dict):- existing_config = {- key: value- for key, value in existing_entry["config"].items()- if key- not in {- "gatewayProviderIds",- "proxyUrl",- "proxyPort",- "autoStart",- "startupTimeoutMs",- "pythonPath",- }- }-- return {**base_entry, "enabled": False, "config": existing_config}------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)-- """- helpers = _live_wrap_module()--- if prepare_only:-- if not no_rtk:- _prepare_wrap_rtk(verbose=verbose, label="Claude")- helpers._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)- cleanup = helpers._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- proxy_holder[0] = helpers._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)- helpers._setup_rtk(verbose=verbose)-- elif verbose:-- click.echo(" Skipping rtk (--no-rtk)")---- if code_graph:- _setup_code_graph(verbose=verbose)- helpers._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)}")- click.echo(f" ANTHROPIC_BASE_URL=http://127.0.0.1:{port}")-- if claude_args:-- click.echo(f" Extra args: {' '.join(claude_args)}")- _print_telemetry_notice()- helpers._print_telemetry_notice()-- click.echo()---- env = os.environ.copy()- env["ANTHROPIC_BASE_URL"] = _claude_proxy_base_url(port)- env["ANTHROPIC_BASE_URL"] = f"http://127.0.0.1:{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 effective_provider_type == "anthropic" and wire_api is not None:- raise click.ClickException(- "--wire-api is only valid when Copilot is using the openai provider type."- )- if wire_api == "responses" and effective_backend not in (None, "anthropic"):- raise click.ClickException(- "--wire-api responses is not supported with translated backends; use completions."- )---- 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, env_vars_display = _build_copilot_launch_env(- port=port,- provider_type=effective_provider_type,- wire_api=wire_api,- environ=os.environ,- )- env = os.environ.copy()- env.pop("COPILOT_PROVIDER_WIRE_API", None)- openai_api_url: str | None = None--- 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 _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."- )--- 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`."- )- env["COPILOT_PROVIDER_TYPE"] = "openai"- env["COPILOT_PROVIDER_BASE_URL"] = f"http://127.0.0.1:{port}/v1"- env["COPILOT_PROVIDER_WIRE_API"] = wire_api or "completions"- 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={env['COPILOT_PROVIDER_WIRE_API']}",- "COPILOT_AUTH_MODE=github-oauth",- ]- openai_api_url = COPILOT_API_URL- else:- env["COPILOT_PROVIDER_TYPE"] = effective_provider_type-- # Copilot BYOK requires COPILOT_PROVIDER_API_KEY — propagate from the- # user's existing provider key so they don't have to set it twice.- if not env.get("COPILOT_PROVIDER_API_KEY"):- if effective_provider_type == "anthropic":- _key = env.get("ANTHROPIC_API_KEY", "")- else:- _key = env.get("OPENAI_API_KEY", "")- if _key:- env["COPILOT_PROVIDER_API_KEY"] = _key-- if effective_provider_type == "anthropic":- env["COPILOT_PROVIDER_BASE_URL"] = f"http://127.0.0.1:{port}"- env_vars_display = [- "COPILOT_PROVIDER_TYPE=anthropic",- f"COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:{port}",- ]- else:- effective_wire_api = wire_api or "completions"- env["COPILOT_PROVIDER_BASE_URL"] = f"http://127.0.0.1:{port}/v1"- env["COPILOT_PROVIDER_WIRE_API"] = effective_wire_api- 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}",- ]-- if not env.get("COPILOT_PROVIDER_API_KEY"):- src = (- "ANTHROPIC_API_KEY" if effective_provider_type == "anthropic" else "OPENAI_API_KEY"- )- click.echo(- f"\n Error: Copilot BYOK mode requires a provider API key.\n"- f" No reusable GitHub Copilot OAuth session was found, so Headroom fell back to\n"- f" Copilot's BYOK provider mode. That mode bypasses GitHub's Copilot API and\n"- f" routes requests directly to the model provider through the Headroom proxy.\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)- env = os.environ.copy()- env["OPENAI_BASE_URL"] = f"http://127.0.0.1:{port}/v1"---- # 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,- env_vars_display=[f"OPENAI_BASE_URL=http://127.0.0.1:{port}/v1"],-- 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)- env = os.environ.copy()- env["OPENAI_API_BASE"] = f"http://127.0.0.1:{port}/v1"- env["ANTHROPIC_BASE_URL"] = f"http://127.0.0.1:{port}"---- _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,- env_vars_display=[- f"OPENAI_API_BASE=http://127.0.0.1:{port}/v1",- f"ANTHROPIC_BASE_URL=http://127.0.0.1:{port}",- ],-- 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)- click.echo(" Headroom proxy is running. Configure Cursor:")- click.echo()- click.echo(" For OpenAI models:")- click.echo(f" Base URL: http://127.0.0.1:{port}/v1")- click.echo(" API Key: your-openai-api-key")- click.echo()- click.echo(" For Anthropic models:")- click.echo(f" Base URL: http://127.0.0.1:{port}")- click.echo(" API Key: your-anthropic-api-key")- click.echo()- click.echo(" In Cursor:")- click.echo(" Settings > Models > OpenAI API Key > Override OpenAI Base URL")- click.echo(f" Set to: http://127.0.0.1:{port}/v1")-- 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()++"""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 -->"++++++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 — only writes if the section is missing++ or the port changed.++ """++ config_dir = Path.home() / ".codex"++ config_file = config_dir / "config.toml"++++ # model_provider must be a top-level TOML key (before any [section]).++ # The [model_providers.headroom] table can go at the end.++ top_level_marker = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"++ top_level_block = f'{top_level_marker}\nmodel_provider = "headroom"\n'++ provider_section = (++ f"\n[model_providers.headroom]\n"++ f'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"# --- end Headroom ---\n"++ )++++ marker = top_level_marker++ end_marker = "# --- end Headroom ---"++++ try:++ config_dir.mkdir(parents=True, exist_ok=True)++++ if config_file.exists():++ content = config_file.read_text()++ if marker in content:++ # Remove existing Headroom blocks entirely++ start = content.index(marker)++ end = content.index(end_marker) + len(end_marker)++ content = content[:start].rstrip("\n") + content[end:].lstrip("\n")++++ # Strip any stale top-level model_provider left behind++ import re++++ content = re.sub(r'\nmodel_provider\s*=\s*"headroom"\n', "\n", content)++++ # Place top-level key at the very beginning, provider table at the end++ content = top_level_block + "\n" + content.strip() + "\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 _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)++++ 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."""++ if not no_proxy:++ manifest = _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 _recover_persistent_proxy(port):++ return None++ raise click.ClickException(++ f"Persistent deployment '{manifest.profile}' on port {port} is not healthy."++ )++++ if _check_proxy(port):++ # Proxy is running — check if it has the features we need++ needs_restart = False++ running_config = _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 _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 _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()diff --cc headroom/proxy/handlers/openai.pyindex 41a422842,7cbb0dd30..73207bfc6--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@@ -1,2746 -1,2558 +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- from headroom.pipeline import PipelineStage, summarize_routing_markers-from headroom.copilot_auth import apply_copilot_api_auth, build_copilot_upstream_url----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 = f"{self.OPENAI_API_URL}/v1/chat/completions"- 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 = f"{self.OPENAI_API_URL}/v1/responses"- 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 = f"{ws_base}/v1/responses"- 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 = f"{self.OPENAI_API_URL}/v1/responses"- 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 = f"{base_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 --cc headroom/proxy/server.pyindex 398210e8e,e96213507..d16dcd9ca--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@@ -1,2578 -1,3028 +1,2619 @@@-"""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, WebSocket- 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.providers.anthropic import AnthropicProvider-from headroom.providers.openai import OpenAIProvider--# =============================================================================-# 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,-)--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")--# Preserve module-level backend symbols for tests and patch-based integrations-# while still importing the actual backend implementations lazily at runtime.-AnyLLMBackend = None-LiteLLMBackend = None--# 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 = "https://api.anthropic.com"- OPENAI_API_URL = "https://api.openai.com"- GEMINI_API_URL = "https://generativelanguage.googleapis.com"- CLOUDCODE_API_URL = "https://cloudcode-pa.googleapis.com"-- def __init__(self, config: ProxyConfig):- self.config = config- self.config.mode = normalize_proxy_mode(self.config.mode)-- # Reset per-instance API targets first so test runs and multiple app instances- # do not leak class-level overrides across each other.- HeadroomProxy.ANTHROPIC_API_URL = "https://api.anthropic.com"- HeadroomProxy.OPENAI_API_URL = "https://api.openai.com"- HeadroomProxy.GEMINI_API_URL = "https://generativelanguage.googleapis.com"- HeadroomProxy.CLOUDCODE_API_URL = "https://cloudcode-pa.googleapis.com"-- # Override ANTHROPIC_API_URL with config if set.- # Strip trailing /v1 or /v1/ to avoid double-path (e.g., .../v1/v1/models).- if config.anthropic_api_url:- url = config.anthropic_api_url.rstrip("/")- if url.endswith("/v1"):- url = url[:-3]- HeadroomProxy.ANTHROPIC_API_URL = url-- # Override OPENAI_API_URL with config if set.- # Strip trailing /v1 or /v1/ to avoid double-path (e.g., .../v1/v1/models).- if config.openai_api_url:- url = config.openai_api_url.rstrip("/")- if url.endswith("/v1"):- url = url[:-3]- HeadroomProxy.OPENAI_API_URL = url-- # Override GEMINI_API_URL with config if set.- if config.gemini_api_url:- gurl = config.gemini_api_url.rstrip("/")- if gurl.endswith("/v1"):- gurl = gurl[:-3]- HeadroomProxy.GEMINI_API_URL = gurl-- # Override CLOUDCODE_API_URL with config if set.- if config.cloudcode_api_url:- curl = config.cloudcode_api_url.rstrip("/")- if curl.endswith("/v1"):- curl = curl[:-3]- HeadroomProxy.CLOUDCODE_API_URL = curl-- # Initialize providers- self.anthropic_provider = AnthropicProvider()- self.openai_provider = OpenAIProvider()-- # 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 = None- if config.backend != "anthropic":- backend = config.backend-- # Handle any-llm backend- if backend == "anyllm" or backend.startswith("anyllm-"):- provider = config.anyllm_provider- try:- global AnyLLMBackend- if AnyLLMBackend is None:- from headroom.backends.anyllm import AnyLLMBackend as ImportedAnyLLMBackend-- AnyLLMBackend = ImportedAnyLLMBackend-- self.anthropic_backend = AnyLLMBackend(provider=provider)- logger.info(f"any-llm backend enabled (provider={provider})")- except ImportError as e:- logger.warning(f"any-llm backend not available: {e}")- except Exception as e:- logger.error(f"Failed to initialize any-llm backend: {e}")- else:- # Handle LiteLLM backend- # Normalize backend name: "bedrock" -> "litellm-bedrock"- if not backend.startswith("litellm-"):- backend = f"litellm-{backend}"- provider = backend.replace("litellm-", "")-- try:- global LiteLLMBackend- if LiteLLMBackend is None:- from headroom.backends.litellm import (- LiteLLMBackend as ImportedLiteLLMBackend,- )-- LiteLLMBackend = ImportedLiteLLMBackend-- self.anthropic_backend = LiteLLMBackend(- provider=provider,- region=config.bedrock_region,- )- logger.info(- f"LiteLLM backend enabled (provider={provider}, region={config.bedrock_region})"- )- except ImportError as e:- logger.warning(f"LiteLLM backend not available: {e}")- except Exception as e:- logger.error(f"Failed to initialize LiteLLM backend: {e}")-- # 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-- 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.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")-- 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."""- 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"),- }- )-- 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)-- # Anthropic endpoints- @app.post("/v1/messages")- async def anthropic_messages(request: Request):- return await proxy.handle_anthropic_messages(request)-- @app.post("/v1/messages/count_tokens")- async def anthropic_count_tokens(request: Request):- return await proxy.handle_passthrough(- request, proxy.ANTHROPIC_API_URL, "count_tokens", "anthropic"- )-- # Anthropic Message Batches API endpoints- @app.post("/v1/messages/batches")- async def anthropic_batch_create(request: Request):- """Create a message batch with compression applied to all requests."""- return await proxy.handle_anthropic_batch_create(request)-- @app.get("/v1/messages/batches")- async def anthropic_batch_list(request: Request):- """List message batches (passthrough)."""- return await proxy.handle_anthropic_batch_passthrough(request)-- @app.get("/v1/messages/batches/{batch_id}")- async def anthropic_batch_get(request: Request, batch_id: str):- """Get a specific message batch (passthrough)."""- return await proxy.handle_anthropic_batch_passthrough(request, batch_id)-- @app.get("/v1/messages/batches/{batch_id}/results")- async def anthropic_batch_results(request: Request, batch_id: str):- """Get results for a message batch with CCR post-processing."""- return await proxy.handle_anthropic_batch_results(request, batch_id)-- @app.post("/v1/messages/batches/{batch_id}/cancel")- async def anthropic_batch_cancel(request: Request, batch_id: str):- """Cancel a message batch (passthrough)."""- return await proxy.handle_anthropic_batch_passthrough(request, batch_id)-- # OpenAI endpoints- @app.post("/v1/chat/completions")- async def openai_chat(request: Request):- return await proxy.handle_openai_chat(request)-- @app.post("/v1/responses")- async def openai_responses(request: Request):- """OpenAI Responses API (new API introduced March 2025)."""- return await proxy.handle_openai_responses(request)-- @app.post("/v1/codex/responses")- async def openai_v1_codex_responses(request: Request):- """Pi/OpenAI Codex compatibility path for OpenAI-style /v1 base URLs."""- return await proxy.handle_openai_responses(request)-- @app.post("/backend-api/responses")- async def openai_codex_responses(request: Request):- """OpenAI Codex Responses API path preserved from ChatGPT backend."""- return await proxy.handle_openai_responses(request)-- @app.post("/backend-api/codex/responses")- async def openai_codex_nested_responses(request: Request):- """OpenAI Codex Responses API path for codex-shaped proxy base URLs."""- return await proxy.handle_openai_responses(request)-- @app.websocket("/v1/responses")- async def openai_responses_ws(websocket: WebSocket):- """OpenAI Responses API via WebSocket (Codex gpt-5.4+)."""- await proxy.handle_openai_responses_ws(websocket)-- @app.websocket("/v1/codex/responses")- async def openai_v1_codex_responses_ws(websocket: WebSocket):- """Pi/OpenAI Codex compatibility WebSocket path for /v1 base URLs."""- await proxy.handle_openai_responses_ws(websocket)-- # OpenAI Responses API sub-endpoints (passthrough).- # Codex sub-agents use /v1/responses/compact and other sub-paths- # that we don't need to compress — just forward with correct auth routing.- @app.api_route("/v1/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"])- async def openai_responses_sub(request: Request, sub_path: str):- """Passthrough for /v1/responses/* sub-endpoints (compact, cancel, etc.)."""- from fastapi.responses import Response-- from headroom.proxy.handlers.openai import _resolve_codex_routing_headers-- headers = dict(request.headers.items())- headers.pop("host", None)- 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 with /responses/...- # path (no /v1/ prefix). API key auth uses api.openai.com/v1/responses/...- if is_chatgpt_auth:- url = f"https://chatgpt.com/backend-api/codex/responses/{sub_path}"- else:- url = f"{proxy.OPENAI_API_URL}/v1/responses/{sub_path}"-- if request.url.query:- url = f"{url}?{request.url.query}"-- body = await request.body()- try:- assert proxy.http_client is not None- resp = await proxy.http_client.request(- request.method,- url,- headers=headers,- content=body,- timeout=120.0,- )- return Response(- content=resp.content,- status_code=resp.status_code,- headers=dict(resp.headers),- )- except Exception as e:- logger.error(f"Passthrough /v1/responses/{sub_path} failed: {e}")- return Response(content=str(e), status_code=502)-- @app.api_route("/v1/codex/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"])- async def openai_v1_codex_responses_sub(request: Request, sub_path: str):- """Passthrough for Pi/OpenAI Codex /v1/codex/responses/* sub-endpoints."""- return await openai_responses_sub(request, sub_path)-- @app.websocket("/backend-api/responses")- async def openai_codex_responses_ws(websocket: WebSocket):- """OpenAI Codex Responses WebSocket path preserved from ChatGPT backend."""- await proxy.handle_openai_responses_ws(websocket)-- @app.websocket("/backend-api/codex/responses")- async def openai_codex_nested_responses_ws(websocket: WebSocket):- """OpenAI Codex Responses WebSocket path for codex-shaped proxy base URLs."""- await proxy.handle_openai_responses_ws(websocket)-- @app.api_route("/backend-api/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"])- async def openai_codex_responses_sub(request: Request, sub_path: str):- """Passthrough for /backend-api/responses/* sub-endpoints."""- return await openai_responses_sub(request, sub_path)-- @app.api_route(- "/backend-api/codex/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"]- )- async def openai_codex_nested_responses_sub(request: Request, sub_path: str):- """Passthrough for /backend-api/codex/responses/* sub-endpoints."""- return await openai_responses_sub(request, sub_path)-- # OpenAI Batch API endpoints (with compression!)- @app.post("/v1/batches")- async def create_batch(request: Request):- """Create a batch with automatic compression of messages."""- return await proxy.handle_batch_create(request)-- @app.get("/v1/batches")- async def list_batches(request: Request):- """List batches (passthrough to OpenAI)."""- return await proxy.handle_batch_list(request)-- @app.get("/v1/batches/{batch_id}")- async def get_batch(request: Request, batch_id: str):- """Get batch details (passthrough to OpenAI)."""- return await proxy.handle_batch_get(request, batch_id)-- @app.post("/v1/batches/{batch_id}/cancel")- async def cancel_batch(request: Request, batch_id: str):- """Cancel a batch (passthrough to OpenAI)."""- return await proxy.handle_batch_cancel(request, batch_id)-- # Gemini native endpoints- @app.post("/v1beta/models/{model}:generateContent")- async def gemini_generate_content(request: Request, model: str):- """Gemini native generateContent API."""- return await proxy.handle_gemini_generate_content(request, model)-- @app.post("/v1beta/models/{model}:streamGenerateContent")- async def gemini_stream_generate_content(request: Request, model: str):- """Gemini native streaming generateContent API."""- return await proxy.handle_gemini_stream_generate_content(request, model)-- @app.post("/v1beta/models/{model}:countTokens")- async def gemini_count_tokens(request: Request, model: str):- """Gemini countTokens API with compression applied."""- return await proxy.handle_gemini_count_tokens(request, model)-- @app.post("/v1internal:streamGenerateContent")- async def google_cloudcode_stream_generate_content(request: Request):- """Google Cloud Code Assist / Antigravity compatibility streaming endpoint."""- return await proxy.handle_google_cloudcode_stream(request)-- @app.post("/v1/v1internal:streamGenerateContent")- async def google_cloudcode_stream_generate_content_v1(request: Request):- """Compatibility endpoint for clients configured with a /v1 proxy base URL."""- return await proxy.handle_google_cloudcode_stream(request)-- # =========================================================================- # Databricks Native Endpoints- # =========================================================================-- @app.post("/serving-endpoints/{model}/invocations")- async def databricks_invocations(request: Request, model: str):- """Databricks native serving endpoint - compatible with Databricks CLI.-- This allows using the Databricks CLI directly with Headroom proxy:- databricks serving-endpoints query <model> --profile HEADROOM --json '{"messages": [...]}'-- The request format is identical to OpenAI chat completions.- """- return await proxy.handle_databricks_invocations(request, model)-- # =========================================================================- # Passthrough Endpoints (no compression needed)- # =========================================================================-- # --- OpenAI Passthrough Endpoints ----- @app.get("/v1/models")- async def list_models(request: Request):- """List models - route based on auth header.-- - x-api-key / anthropic-version / Bearer sk-ant-* -> Anthropic- - Otherwise -> OpenAI- """- if is_anthropic_auth(dict(request.headers)):- return await proxy.handle_passthrough(- request, proxy.ANTHROPIC_API_URL, "models", "anthropic"- )- return await proxy.handle_passthrough(request, proxy.OPENAI_API_URL, "models", "openai")-- @app.get("/v1/models/{model_id}")- async def get_model(request: Request, model_id: str):- """Get model details - route based on auth header.-- - x-api-key / anthropic-version / Bearer sk-ant-* -> Anthropic- - Otherwise -> OpenAI- """- if is_anthropic_auth(dict(request.headers)):- return await proxy.handle_passthrough(- request, proxy.ANTHROPIC_API_URL, "models", "anthropic"- )- return await proxy.handle_passthrough(request, proxy.OPENAI_API_URL, "models", "openai")-- @app.post("/v1/embeddings")- async def openai_embeddings(request: Request):- """OpenAI embeddings API - passthrough."""- return await proxy.handle_passthrough(request, proxy.OPENAI_API_URL, "embeddings", "openai")-- @app.post("/v1/moderations")- async def openai_moderations(request: Request):- """OpenAI moderations API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.OPENAI_API_URL, "moderations", "openai"- )-- @app.post("/v1/images/generations")- async def openai_images_generations(request: Request):- """OpenAI image generation API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.OPENAI_API_URL, "images/generations", "openai"- )-- @app.post("/v1/audio/transcriptions")- async def openai_audio_transcriptions(request: Request):- """OpenAI audio transcription API (multipart/form-data) - passthrough."""- return await proxy.handle_passthrough(- request, proxy.OPENAI_API_URL, "audio/transcriptions", "openai"- )-- @app.post("/v1/audio/speech")- async def openai_audio_speech(request: Request):- """OpenAI text-to-speech API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.OPENAI_API_URL, "audio/speech", "openai"- )-- # --- Gemini Passthrough Endpoints ----- @app.get("/v1beta/models")- async def gemini_list_models(request: Request):- """Gemini list models API - passthrough."""- return await proxy.handle_passthrough(request, proxy.GEMINI_API_URL, "models", "gemini")-- @app.get("/v1beta/models/{model_name}")- async def gemini_get_model(request: Request, model_name: str):- """Gemini get model API - passthrough.-- Note: This handles GET /v1beta/models/{model_name} but NOT :countTokens- which is handled by a separate POST route above.- """- return await proxy.handle_passthrough(request, proxy.GEMINI_API_URL, "models", "gemini")-- @app.post("/v1beta/models/{model}:embedContent")- async def gemini_embed_content(request: Request, model: str):- """Gemini embedding API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.GEMINI_API_URL, "embedContent", "gemini"- )-- @app.post("/v1beta/models/{model}:batchEmbedContents")- async def gemini_batch_embed_contents(request: Request, model: str):- """Gemini batch embeddings API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.GEMINI_API_URL, "batchEmbedContents", "gemini"- )-- # Google/Gemini Batch API endpoints (with compression!)- @app.post("/v1beta/models/{model}:batchGenerateContent")- async def gemini_batch_create(request: Request, model: str):- """Create a Gemini batch with compression applied to all requests."""- return await proxy.handle_google_batch_create(request, model)-- @app.get("/v1beta/batches/{batch_name}")- async def gemini_batch_get(request: Request, batch_name: str):- """Get a specific Gemini batch with CCR post-processing."""- return await proxy.handle_google_batch_results(request, batch_name)-- @app.post("/v1beta/batches/{batch_name}:cancel")- async def gemini_batch_cancel(request: Request, batch_name: str):- """Cancel a Gemini batch (passthrough)."""- return await proxy.handle_google_batch_passthrough(request, batch_name)-- @app.delete("/v1beta/batches/{batch_name}")- async def gemini_batch_delete(request: Request, batch_name: str):- """Delete a Gemini batch (passthrough)."""- return await proxy.handle_google_batch_passthrough(request, batch_name)-- @app.post("/v1beta/cachedContents")- async def gemini_create_cached_content(request: Request):- """Gemini create cached content API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.GEMINI_API_URL, "cachedContents", "gemini"- )-- @app.get("/v1beta/cachedContents")- async def gemini_list_cached_contents(request: Request):- """Gemini list cached contents API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.GEMINI_API_URL, "cachedContents", "gemini"- )-- @app.get("/v1beta/cachedContents/{cache_id}")- async def gemini_get_cached_content(request: Request, cache_id: str):- """Gemini get cached content API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.GEMINI_API_URL, "cachedContents", "gemini"- )-- @app.delete("/v1beta/cachedContents/{cache_id}")- async def gemini_delete_cached_content(request: Request, cache_id: str):- """Gemini delete cached content API - passthrough."""- return await proxy.handle_passthrough(- request, proxy.GEMINI_API_URL, "cachedContents", "gemini"- )-- # =========================================================================- # Catch-all Passthrough- # =========================================================================-- # Passthrough - route to correct backend based on headers- @app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])- async def passthrough(request: Request, path: str):- # Allow explicit base URL override (for Azure, custom endpoints, etc.)- custom_base = request.headers.get("x-headroom-base-url")- if custom_base:- return await proxy.handle_passthrough(request, custom_base.rstrip("/"))-- # Anthropic: x-api-key, anthropic-version, or Bearer sk-ant-* token- if is_anthropic_auth(dict(request.headers)):- base_url = proxy.ANTHROPIC_API_URL- # Gemini: sends x-goog-api-key- elif request.headers.get("x-goog-api-key"):- base_url = proxy.GEMINI_API_URL- # Azure OpenAI: sends api-key header (not x-api-key)- elif request.headers.get("api-key"):- # Azure requires explicit base URL (varies per deployment)- azure_base = request.headers.get("x-headroom-base-url", "")- if azure_base:- base_url = azure_base.rstrip("/")- else:- base_url = proxy.OPENAI_API_URL # Fallback- else:- # Default: OpenAI- base_url = proxy.OPENAI_API_URL- return await proxy.handle_passthrough(request, base_url)-- 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 - use provider registry for display info- if config.backend == "anthropic":- backend_status = "ANTHROPIC (direct API)"- elif config.backend == "anyllm" or config.backend.startswith("anyllm-"):- backend_status = f"{config.anyllm_provider.title()} via any-llm"- else:- from headroom.backends.litellm import get_provider_config-- provider = config.backend.replace("litellm-", "")- provider_config = get_provider_config(provider)- if provider_config.uses_region:- backend_status = (- f"{provider_config.display_name} via LiteLLM (region={config.bedrock_region})"- )- else:- backend_status = f"{provider_config.display_name} via LiteLLM"-- 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: {HeadroomProxy.OPENAI_API_URL})"- )- parser.add_argument(- "--anthropic-api-url",- help=f"Custom Anthropic API URL (default: {HeadroomProxy.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++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()+- @app.get("/stats")- async def stats():- """Get comprehensive proxy statistics.++ 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"),+ }+ )++ 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 --cc plugins/headroom-agent-hooks/.claude-plugin/plugin.jsonindex 4b2fd52e0,0d63bd1cd..be1087785--- a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json+++ b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json@@@ -1,6 -1,6 +1,6 @@@{"name": "headroom",- "version": "0.10.0",- "version": "0.9.2",++ "version": "0.11.0","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.","author": {"name": "Headroom Contributors",diff --cc plugins/headroom-agent-hooks/.github/plugin/plugin.jsonindex f8fe831d1,c43dbaf24..ab08604b0--- a/plugins/headroom-agent-hooks/.github/plugin/plugin.json+++ b/plugins/headroom-agent-hooks/.github/plugin/plugin.json@@@ -1,6 -1,6 +1,6 @@@{"name": "headroom",- "version": "0.10.0",- "version": "0.9.2",++ "version": "0.11.0","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.","author": {"name": "Headroom Contributors",