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
fix: expose compression latency bottlenecks
Tejas Choprae9cae0131bfe
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 484fd68f7..70596acf6 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -7,12 +7,14 @@ from __future__ import annotationsimport asyncioimport base64+import concurrent.futuresimport contextlibimport copyimport hashlibimport jsonimport loggingimport os+import threadingimport timeimport uuidfrom datetime import datetime@@ -42,6 +44,64 @@ from headroom.proxy.auth_mode import classify_auth_modelogger = logging.getLogger("headroom.proxy")+_CODEX_WS_UNIT_ROUTER_MAX_WORKERS = 10+_CODEX_WS_UNIT_ROUTER_SEMAPHORE = threading.BoundedSemaphore(+ _CODEX_WS_UNIT_ROUTER_MAX_WORKERS+)+++def _codex_ws_unit_worker_count(unit_count: int) -> int:+ if unit_count <= 1:+ return 1+ raw = os.environ.get("HEADROOM_CODEX_WS_UNIT_WORKERS", "4")+ try:+ requested = int(raw)+ except ValueError:+ requested = 4+ return max(1, min(unit_count, requested, _CODEX_WS_UNIT_ROUTER_MAX_WORKERS))+++def _codex_ws_text_shape(text: str) -> str:+ stripped = text.strip()+ if not stripped:+ return "empty"+ if stripped.startswith("```"):+ return "code_fence"+ if stripped.startswith("<") and stripped.endswith(">"):+ return "xml_or_html"+ if stripped.startswith("["):+ return "json_array_like"+ if stripped.startswith("{"):+ lines = [line for line in stripped.splitlines() if line.strip()]+ if len(lines) > 1 and all(line.lstrip().startswith("{") for line in lines[:20]):+ return "jsonl_like"+ return "json_object_like"+ if stripped.startswith("Traceback (most recent call last)"):+ return "traceback"+ lines = stripped.splitlines()+ sample = lines[:50]+ if sample:+ timestamp_lines = sum(+ 1+ for line in sample+ if len(line) >= 10 and line[:4].isdigit() and line[4:5] == "-" and line[7:8] == "-"+ )+ level_lines = sum(+ 1+ for line in sample+ if any(level in line for level in (" ERROR ", " WARN ", " WARNING ", " INFO "))+ )+ search_lines = sum(+ 1+ for line in sample+ if ":" in line and line.split(":", 2)[1:2] and line.split(":", 2)[1].isdigit()+ )+ if timestamp_lines >= max(2, len(sample) // 5) or level_lines >= max(2, len(sample) // 5):+ return "log_like"+ if search_lines >= max(2, len(sample) // 3):+ return "search_result_like"+ return "plain_text_like"+def _json_debug_dumps(value: Any) -> str:return json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":"))@@ -51,6 +111,13 @@ def _log_codex_compression_debug(_event: str, **_payload: Any) -> None:return+_CODEX_COMPRESSION_DEBUG_NOOP = _log_codex_compression_debug+++def _codex_compression_debug_enabled() -> bool:+ return _log_codex_compression_debug is not _CODEX_COMPRESSION_DEBUG_NOOP++def _json_shape(value: str) -> dict[str, Any]:try:parsed = json.loads(value)@@ -362,6 +429,7 @@ class OpenAIHandlerMixin:model: str,request_id: str,pass_id: str | None = None,+ timing: dict[str, float] | None = None,) -> tuple[dict[str, Any], bool, int, list[str], dict[str, int], list[str], int]:"""Run ContentRouter on OpenAI Responses text units.@@ -373,8 +441,17 @@ class OpenAIHandlerMixin:are intentionally not exposed as text units."""+ debug_enabled = _codex_compression_debug_enabled()+def _log(_event: str, **_fields: Any) -> None:- return+ if debug_enabled:+ _log_codex_compression_debug(+ _event,+ request_id=request_id,+ pass_id=pass_id,+ model=model,+ **_fields,+ )input_items = payload.get("input")messages_items = payload.get("messages")@@ -385,7 +462,7 @@ class OpenAIHandlerMixin:from headroom.transforms.compression_units import (CompressionUnit,RoutedCompressionUnit,- compress_units_with_router,+ compress_unit_with_router,find_content_router,)except Exception as exc:@@ -447,75 +524,89 @@ class OpenAIHandlerMixin:if isinstance(call_id, str) and call_id:headroom_retrieve_call_ids.add(call_id)+ timing_sink: dict[str, float] = timing if timing is not None else {}++ def _add_timing(name: str, started_at: float) -> None:+ timing_sink[name] = (+ timing_sink.get(name, 0.0) + (time.perf_counter() - started_at) * 1000.0+ )++ extraction_started = time.perf_counter()candidates: list[tuple[int, tuple[str, int | None], str]] = []extraction_debug: list[dict[str, Any]] = []for idx, item in enumerate(items):if not isinstance(item, dict):- extraction_debug.append(- {- "index": idx,- "eligible": False,- "reason": "item_not_dict",- "item_type": type(item).__name__,- "item": item,- }- )- continue- item_type = item.get("type")- if item_type in self.OPENAI_RESPONSES_OUTPUT_TYPES:- call_id = item.get("call_id")- if isinstance(call_id, str) and call_id in headroom_retrieve_call_ids:+ if debug_enabled:extraction_debug.append({"index": idx,"eligible": False,- "reason": "headroom_retrieve_output_protected",- "item_type": item_type,- "call_id": call_id,+ "reason": "item_not_dict",+ "item_type": type(item).__name__,"item": item,})+ continue+ item_type = item.get("type")+ if item_type in self.OPENAI_RESPONSES_OUTPUT_TYPES:+ call_id = item.get("call_id")+ if isinstance(call_id, str) and call_id in headroom_retrieve_call_ids:+ if debug_enabled:+ extraction_debug.append(+ {+ "index": idx,+ "eligible": False,+ "reason": "headroom_retrieve_output_protected",+ "item_type": item_type,+ "call_id": call_id,+ "item": item,+ }+ )continueslot = _slot_text(item)if slot is not None:text, slot_ref = slotcandidates.append((idx, slot_ref, text))- extraction_debug.append(- {- "index": idx,- "eligible": True,- "item_type": item_type,- "role": item.get("role"),- "slot": slot_ref,- "text_chars": len(text),- "text_bytes": len(text.encode("utf-8", errors="replace")),- "text_json_shape": _json_shape(text),- "item": item,- "text": text,- }- )+ if debug_enabled:+ extraction_debug.append(+ {+ "index": idx,+ "eligible": True,+ "item_type": item_type,+ "role": item.get("role"),+ "slot": slot_ref,+ "text_chars": len(text),+ "text_bytes": len(text.encode("utf-8", errors="replace")),+ "text_json_shape": _json_shape(text),+ "item": item,+ "text": text,+ }+ )else:+ if debug_enabled:+ extraction_debug.append(+ {+ "index": idx,+ "eligible": False,+ "reason": "output_type_without_text_slot",+ "item_type": item_type,+ "item": item,+ }+ )+ else:+ if debug_enabled:extraction_debug.append({"index": idx,"eligible": False,- "reason": "output_type_without_text_slot",+ "reason": "unsupported_item_type","item_type": item_type,+ "role": item.get("role"),"item": item,})- else:- extraction_debug.append(- {- "index": idx,- "eligible": False,- "reason": "unsupported_item_type",- "item_type": item_type,- "role": item.get("role"),- "item": item,- }- )+ _add_timing("compression_live_unit_extraction", extraction_started)_log("codex_compression_extraction",item_count=len(items),@@ -535,7 +626,9 @@ class OpenAIHandlerMixin:)return payload, False, 0, [], {}, [], 0+ deepcopy_started = time.perf_counter()updated = copy.deepcopy(payload)+ _add_timing("compression_payload_deepcopy", deepcopy_started)updated_input_items = updated.get("input")updated_messages_items = updated.get("messages")updated_items = (@@ -558,6 +651,7 @@ class OpenAIHandlerMixin:transforms: list[str] = []routed_units: list[RoutedCompressionUnit] = []+ unit_build_started = time.perf_counter()unit_debug: list[dict[str, Any]] = []for item_idx, slot_ref, original_text in candidates:item = items[item_idx] if item_idx < len(items) else {}@@ -574,23 +668,25 @@ class OpenAIHandlerMixin:min_bytes=self.OPENAI_RESPONSES_ROUTER_MIN_BYTES,)routed_units.append(RoutedCompressionUnit(unit=unit, slot=(item_idx, slot_ref)))- unit_debug.append(- {- "item_index": item_idx,- "slot": slot_ref,- "provider": unit.provider,- "endpoint": unit.endpoint,- "role": unit.role,- "item_type": unit.item_type,- "cache_zone": unit.cache_zone,- "mutable": unit.mutable,- "min_bytes": unit.min_bytes,- "text_chars": len(unit.text),- "text_bytes": len(unit.text.encode("utf-8", errors="replace")),- "text_json_shape": _json_shape(unit.text),- "text": unit.text,- }- )+ if debug_enabled:+ unit_debug.append(+ {+ "item_index": item_idx,+ "slot": slot_ref,+ "provider": unit.provider,+ "endpoint": unit.endpoint,+ "role": unit.role,+ "item_type": unit.item_type,+ "cache_zone": unit.cache_zone,+ "mutable": unit.mutable,+ "min_bytes": unit.min_bytes,+ "text_chars": len(unit.text),+ "text_bytes": len(unit.text.encode("utf-8", errors="replace")),+ "text_json_shape": _json_shape(unit.text),+ "text": unit.text,+ }+ )+ _add_timing("compression_unit_build", unit_build_started)_log("codex_compression_units",@@ -603,11 +699,83 @@ class OpenAIHandlerMixin:units_by_category: dict[str, int] = {}strategy_chain_union: list[str] = []- for slot, result in compress_units_with_router(- routed_units,- router=router,- tokenizer=tokenizer,- ):+ def _compress_routed_unit(+ routed: RoutedCompressionUnit,+ ) -> tuple[object, Any, float]:+ unit_started = time.perf_counter()+ with _CODEX_WS_UNIT_ROUTER_SEMAPHORE:+ result = compress_unit_with_router(routed.unit, router=router, tokenizer=tokenizer)+ elapsed_ms = (time.perf_counter() - unit_started) * 1000.0+ return routed.slot, result, elapsed_ms++ router_total_started = time.perf_counter()+ worker_count = _codex_ws_unit_worker_count(len(routed_units))+ if worker_count <= 1:+ routed_results = [_compress_routed_unit(routed) for routed in routed_units]+ else:+ with concurrent.futures.ThreadPoolExecutor(max_workers=worker_count) as executor:+ routed_results = list(executor.map(_compress_routed_unit, routed_units))++ for _, result, elapsed_ms in routed_results:+ router_chain = list(result.router_result.strategy_chain) if result.router_result else []+ router_content_type = (+ result.router_result.routing_log[0].content_type.value+ if result.router_result and result.router_result.routing_log+ else "unknown"+ )+ timing_sink["compression_unit_router_total"] = (+ timing_sink.get("compression_unit_router_total", 0.0) + elapsed_ms+ )+ timing_sink[f"compression_unit_router_strategy_{result.strategy}"] = (+ timing_sink.get(f"compression_unit_router_strategy_{result.strategy}", 0.0)+ + elapsed_ms+ )+ timing_sink[f"compression_unit_router_category_{result.reason_category}"] = (+ timing_sink.get(+ f"compression_unit_router_category_{result.reason_category}", 0.0+ )+ + elapsed_ms+ )+ record_unit = getattr(getattr(self, "metrics", None), "record_codex_ws_unit", None)+ if record_unit is not None:+ record_unit(+ strategy=result.strategy,+ reason_category=result.reason_category,+ elapsed_ms=elapsed_ms,+ text_bytes=result.text_bytes,+ tokens_before=result.tokens_before,+ tokens_after=result.tokens_after,+ tokens_saved=result.tokens_saved,+ modified=result.modified,+ strategy_chain=router_chain,+ content_type=router_content_type,+ text_shape=_codex_ws_text_shape(result.original),+ )+ if elapsed_ms >= 1000.0:+ logger.info(+ "[%s] WS /v1/responses slow compression unit "+ "elapsed_ms=%.0f strategy=%s category=%s modified=%s "+ "content_type=%s text_shape=%s bytes=%d min_bytes=%d "+ "tokens_before=%d tokens_after=%d tokens_saved=%d "+ "strategy_chain=%s",+ request_id,+ elapsed_ms,+ result.strategy,+ result.reason_category,+ result.modified,+ router_content_type,+ _codex_ws_text_shape(result.original),+ result.text_bytes,+ result.min_bytes,+ result.tokens_before,+ result.tokens_after,+ result.tokens_saved,+ router_chain,+ )+ _add_timing("compression_units_router_loop", router_total_started)++ apply_started = time.perf_counter()+ for slot, result, _elapsed_ms in routed_results:item_idx, slot_ref = slotrouter_chain = list(result.router_result.strategy_chain) if result.router_result else []for s in router_chain:@@ -621,32 +789,33 @@ class OpenAIHandlerMixin:# role-protected, or in a frozen cache_zone don't count.if result.router_result is not None or result.modified:attempted_input_tokens += result.tokens_before- _log(- "codex_compression_unit_result",- item_index=item_idx,- slot=slot_ref,- modified=result.modified,- reason=result.reason,- reason_category=cat,- text_bytes=result.text_bytes,- min_bytes=result.min_bytes,- strategy=result.strategy,- strategy_chain=router_chain,- tokens_before=result.tokens_before,- tokens_after=result.tokens_after,- tokens_saved=result.tokens_saved,- transforms_applied=result.transforms_applied,- router_strategy=(- result.router_result.strategy_used.value if result.router_result else None- ),- router_summary=result.router_result.summary() if result.router_result else None,- router_routing_log=_routing_log_debug(result.router_result),- router_cache_hit=(- result.router_result.cache_hit if result.router_result else False- ),- original=result.original,- compressed=result.compressed,- )+ if debug_enabled:+ _log(+ "codex_compression_unit_result",+ item_index=item_idx,+ slot=slot_ref,+ modified=result.modified,+ reason=result.reason,+ reason_category=cat,+ text_bytes=result.text_bytes,+ min_bytes=result.min_bytes,+ strategy=result.strategy,+ strategy_chain=router_chain,+ tokens_before=result.tokens_before,+ tokens_after=result.tokens_after,+ tokens_saved=result.tokens_saved,+ transforms_applied=result.transforms_applied,+ router_strategy=(+ result.router_result.strategy_used.value if result.router_result else None+ ),+ router_summary=result.router_result.summary() if result.router_result else None,+ router_routing_log=_routing_log_debug(result.router_result),+ router_cache_hit=(+ result.router_result.cache_hit if result.router_result else False+ ),+ original=result.original,+ compressed=result.compressed,+ )if not result.modified:continue@@ -659,6 +828,7 @@ class OpenAIHandlerMixin:for transform in result.transforms_applied:if transform not in transforms:transforms.append(transform)+ _add_timing("compression_unit_apply_results", apply_started)_log("codex_compression_payload_result",@@ -687,6 +857,7 @@ class OpenAIHandlerMixin:*,model: str,request_id: str,+ timing: dict[str, float] | None = None,) -> tuple[dict[str, Any], bool, int, list[str], str | None, int, int, int]:"""Compress an OpenAI Responses payload through the shared router.@@ -696,7 +867,16 @@ class OpenAIHandlerMixin:compressor, then splices accepted replacements back into the payload."""+ timing_sink: dict[str, float] = timing if timing is not None else {}++ def _add_timing(name: str, started_at: float) -> None:+ timing_sink[name] = (+ timing_sink.get(name, 0.0) + (time.perf_counter() - started_at) * 1000.0+ )++ input_serialization_started = time.perf_counter()input_bytes = json.dumps(payload).encode("utf-8")+ _add_timing("compression_input_json_dump", input_serialization_started)# Codex/Responses requests can re-enter this method many times per# request_id (one per turn over the same websocket). Tag every# event in this single pass with a content-derived id so dashboards@@ -707,54 +887,63 @@ class OpenAIHandlerMixin:# Identical pass_ids within one request_id indicate idempotent# retries on the same input bytes and are the only thing that# should be deduped.- pass_id = hashlib.sha256(input_bytes).hexdigest()[:12]- input_context_budget = _openai_responses_context_budget(payload)- _log_codex_compression_debug(- "codex_compression_payload_input",- request_id=request_id,- pass_id=pass_id,- model=model,- input_bytes=len(input_bytes),- context_budget=input_context_budget,- input_top_level_keys=list(payload.keys()),- input_field_type=type(payload.get("input")).__name__,- messages_field_type=type(payload.get("messages")).__name__,- payload=payload,- )+ debug_enabled = _codex_compression_debug_enabled()+ pass_id = hashlib.sha256(input_bytes).hexdigest()[:12] if debug_enabled else None+ input_context_budget: dict[str, Any] | None = None+ if debug_enabled:+ input_context_budget = _openai_responses_context_budget(payload)+ _log_codex_compression_debug(+ "codex_compression_payload_input",+ request_id=request_id,+ pass_id=pass_id,+ model=model,+ input_bytes=len(input_bytes),+ context_budget=input_context_budget,+ input_top_level_keys=list(payload.keys()),+ input_field_type=type(payload.get("input")).__name__,+ messages_field_type=type(payload.get("messages")).__name__,+ payload=payload,+ )working = payloadmodified = Falsetokens_saved = 0transforms: list[str] = []reason: str | None = None+ tool_compaction_started = time.perf_counter()compacted_payload, tools_modified, tools_before_bytes, tools_after_bytes = (_compact_openai_responses_tools(working))+ _add_timing("compression_tool_schema_compaction", tool_compaction_started)if tools_modified:working = compacted_payloadmodified = Truereason = Nonetransforms.append("openai:responses:tool_schema_compaction")try:+ tool_token_started = time.perf_counter()tokenizer = self.openai_provider.get_token_counter(model)tokens_saved += max(0,tokenizer.count_text(_json_debug_dumps(payload.get("tools")))- tokenizer.count_text(_json_debug_dumps(working.get("tools"))),)+ _add_timing("compression_tool_schema_token_count", tool_token_started)except Exception:pass- _log_codex_compression_debug(- "codex_tool_schema_compaction",- request_id=request_id,- pass_id=pass_id,- model=model,- modified=True,- tools_bytes_before=tools_before_bytes,- tools_bytes_after=tools_after_bytes,- tools_bytes_saved=tools_before_bytes - tools_after_bytes,- )+ if debug_enabled:+ _log_codex_compression_debug(+ "codex_tool_schema_compaction",+ request_id=request_id,+ pass_id=pass_id,+ model=model,+ modified=True,+ tools_bytes_before=tools_before_bytes,+ tools_bytes_after=tools_after_bytes,+ tools_bytes_saved=tools_before_bytes - tools_after_bytes,+ )+ live_units_started = time.perf_counter()(router_payload,router_modified,@@ -768,7 +957,9 @@ class OpenAIHandlerMixin:model=model,request_id=request_id,pass_id=pass_id,+ timing=timing_sink,)+ _add_timing("compression_live_units_total", live_units_started)if router_modified:working = router_payloadmodified = True@@ -788,20 +979,31 @@ class OpenAIHandlerMixin:attempted_input_tokens = int(router_attempted_tokens)if tools_modified:try:+ attempted_token_started = time.perf_counter()tokenizer = self.openai_provider.get_token_counter(model)attempted_input_tokens += tokenizer.count_text(_json_debug_dumps(payload.get("tools")))+ _add_timing(+ "compression_tool_schema_attempted_token_count",+ attempted_token_started,+ )except Exception:pass+ dedupe_started = time.perf_counter()deduped: list[str] = []for transform in transforms:if transform not in deduped:deduped.append(transform)+ _add_timing("compression_transform_dedupe", dedupe_started)+ output_serialization_started = time.perf_counter()output_bytes = json.dumps(working).encode("utf-8")- output_context_budget = _openai_responses_context_budget(working)+ _add_timing("compression_output_json_dump", output_serialization_started)+ output_context_budget = (+ _openai_responses_context_budget(working) if debug_enabled else None+ )# One-line summary at INFO — the single event a human reading# logs should scan first to understand "what happened on this# pass". All the verbose per-event debug data stays available@@ -825,41 +1027,42 @@ class OpenAIHandlerMixin:attempted_pct = ((tokens_saved / attempted_input_tokens) * 100.0 if attempted_input_tokens > 0 else 0.0)- _log_codex_compression_debug(- "codex_compression_pass_summary",- request_id=request_id,- pass_id=pass_id,- model=model,- modified=modified,- reason=reason,- input_bytes=len(input_bytes),- output_bytes=len(output_bytes),- bytes_saved=len(input_bytes) - len(output_bytes),- savings_pct=round(savings_pct, 2),- tokens_saved=tokens_saved,- attempted_input_tokens=attempted_input_tokens,- attempted_pct=round(attempted_pct, 2),- strategy_chain=strategy_chain,- units_by_category=units_by_category,- transforms=deduped,- )- _log_codex_compression_debug(- "codex_compression_payload_output",- request_id=request_id,- pass_id=pass_id,- model=model,- modified=modified,- reason=reason,- tokens_saved=tokens_saved,- attempted_input_tokens=attempted_input_tokens,- transforms=deduped,- input_bytes=len(input_bytes),- output_bytes=len(output_bytes),- context_budget_before=input_context_budget,- context_budget_after=output_context_budget,- input_payload=payload,- output_payload=working,- )+ if debug_enabled:+ _log_codex_compression_debug(+ "codex_compression_pass_summary",+ request_id=request_id,+ pass_id=pass_id,+ model=model,+ modified=modified,+ reason=reason,+ input_bytes=len(input_bytes),+ output_bytes=len(output_bytes),+ bytes_saved=len(input_bytes) - len(output_bytes),+ savings_pct=round(savings_pct, 2),+ tokens_saved=tokens_saved,+ attempted_input_tokens=attempted_input_tokens,+ attempted_pct=round(attempted_pct, 2),+ strategy_chain=strategy_chain,+ units_by_category=units_by_category,+ transforms=deduped,+ )+ _log_codex_compression_debug(+ "codex_compression_payload_output",+ request_id=request_id,+ pass_id=pass_id,+ model=model,+ modified=modified,+ reason=reason,+ tokens_saved=tokens_saved,+ attempted_input_tokens=attempted_input_tokens,+ transforms=deduped,+ input_bytes=len(input_bytes),+ output_bytes=len(output_bytes),+ context_budget_before=input_context_budget,+ context_budget_after=output_context_budget,+ input_payload=payload,+ output_payload=working,+ )return (working,modified,@@ -877,15 +1080,33 @@ class OpenAIHandlerMixin:*,model: str,request_id: str,- ) -> tuple[dict[str, Any], bool, int, list[str], str | None, int, int, int]:- return await self._run_compression_in_executor(- lambda: self._compress_openai_responses_payload(- payload,- model=model,- request_id=request_id,- ),+ ) -> tuple[dict[str, Any], bool, int, list[str], str | None, int, int, int, dict[str, float]]:+ timing: dict[str, float] = {}++ def _compress(): # noqa: ANN202+ try:+ return self._compress_openai_responses_payload(+ payload,+ model=model,+ request_id=request_id,+ timing=timing,+ )+ except TypeError as exc:+ if "unexpected keyword argument 'timing'" not in str(exc):+ raise+ return self._compress_openai_responses_payload(+ payload,+ model=model,+ request_id=request_id,+ )++ result = await self._run_compression_in_executor(+ _compress,timeout=COMPRESSION_TIMEOUT_SECONDS,)+ if len(result) == 8:+ return (*result, timing)+ return resultasync def handle_openai_chat(self,@@ -2366,6 +2587,7 @@ class OpenAIHandlerMixin:_bytes_before,_bytes_after,_attempted_tokens,+ _compression_timing,) = await self._compress_openai_responses_payload_in_executor(body,model=model,@@ -3067,6 +3289,8 @@ class OpenAIHandlerMixin:ws_client_disconnect_seen = Falsews_overhead_ms_total = 0.0ws_recorded_overhead_ms_total = 0.0+ ws_compression_timing_totals: dict[str, float] = {}+ ws_recorded_compression_timing_totals: dict[str, float] = {}ws_ttfb_ms: float | None = Nonews_recorded_ttfb_ms = False_ws_bypass = self._headroom_bypass_enabled(ws_headers)@@ -3094,6 +3318,29 @@ class OpenAIHandlerMixin:if ws_overhead_ms_total > 0:stage_timer.record("compression", ws_overhead_ms_total)+ def _record_ws_compression_timing(name: str, duration_ms: float) -> None:+ ws_compression_timing_totals[name] = (+ ws_compression_timing_totals.get(name, 0.0)+ + max(0.0, float(duration_ms))+ )++ def _codex_ws_final_strategies(timing: dict[str, float]) -> list[str]:+ prefix = "compression_unit_router_strategy_"+ return [+ name.removeprefix(prefix)+ for name, ms in timing.items()+ if name.startswith(prefix) and ms > 0+ ]++ def _codex_ws_strategy_chain(transforms: list[str]) -> list[str]:+ chain: list[str] = []+ for transform in transforms:+ if ":" in transform:+ continue+ if transform not in chain:+ chain.append(transform)+ return chain+def _current_ws_overhead_ms() -> float:summary = stage_timer.summary()return ws_overhead_ms_total + max(0.0, float(summary.get("memory_context") or 0.0))@@ -3109,6 +3356,12 @@ class OpenAIHandlerMixin:if ttfb_ms > 0:timing["codex_ws.ttfb"] = ttfb_ms+ for stage_name, total_ms in ws_compression_timing_totals.items():+ recorded_ms = ws_recorded_compression_timing_totals.get(stage_name, 0.0)+ delta_ms = max(0.0, total_ms - recorded_ms)+ if delta_ms > 0:+ timing[f"codex_ws.{stage_name}"] = delta_ms+summary = stage_timer.summary()for stage_name in ("memory_context",@@ -3306,7 +3559,9 @@ class OpenAIHandlerMixin:# anyway so a JSON-shape edge case can never break the WS# session.if self.config.optimize and not _ws_bypass:+ _first_frame_compression_elapsed_ms = 0.0try:+ _preflight_started = time.perf_counter()_ws_auth_mode = classify_auth_mode(ws_headers)try:_send_body = json.loads(first_msg_raw)@@ -3320,6 +3575,12 @@ class OpenAIHandlerMixin:_inner = _send_body["response"] if _wrapped else _send_body_model = (_inner.get("model") if isinstance(_inner, dict) else None) or ""+ _preflight_ms = (time.perf_counter() - _preflight_started) * 1000.0+ _record_ws_compression_timing(+ "compression_preflight_serialization",+ _preflight_ms,+ )+ _record_ws_compression_overhead(_preflight_ms)_compression_started = time.perf_counter()try:(@@ -3331,22 +3592,55 @@ class OpenAIHandlerMixin:_bytes_before,_bytes_after,_ws_attempted_tokens,+ _ws_compression_timing,) = await self._compress_openai_responses_payload_in_executor(_inner,model=_model,request_id=request_id,)+ for _timing_name, _timing_ms in _ws_compression_timing.items():+ _record_ws_compression_timing(_timing_name, _timing_ms)finally:+ _first_frame_compression_elapsed_ms = (+ time.perf_counter() - _compression_started+ ) * 1000.0+ _record_ws_compression_timing(+ "compression_executor_wait_run",+ _first_frame_compression_elapsed_ms,+ )_record_ws_compression_overhead(- (time.perf_counter() - _compression_started) * 1000.0+ _first_frame_compression_elapsed_ms+ )+ record_frame = getattr(+ getattr(self, "metrics", None), "record_codex_ws_frame", None+ )+ if record_frame is not None:+ record_frame(+ elapsed_ms=_first_frame_compression_elapsed_ms,+ bytes_before=_bytes_before,+ bytes_after=_bytes_after,+ attempted_tokens=_ws_attempted_tokens,+ tokens_saved=_ws_saved,+ modified=_modified,+ strategy_chain=_codex_ws_strategy_chain(_ws_transforms),+ final_strategies=_codex_ws_final_strategies(+ _ws_compression_timing+ ),)if _modified:if isinstance(_new_inner, dict):+ _rewrite_started = time.perf_counter()if _wrapped:_send_body["response"] = _new_innerelse:_send_body = _new_innerfirst_msg_raw = json.dumps(_send_body)+ _rewrite_ms = (time.perf_counter() - _rewrite_started) * 1000.0+ _record_ws_compression_timing(+ "compression_payload_rewrite_json_dump",+ _rewrite_ms,+ )+ _record_ws_compression_overhead(_rewrite_ms)tokens_saved += int(_ws_saved)attempted_input_tokens_total += int(_ws_attempted_tokens)for _t in _ws_transforms:@@ -3363,6 +3657,7 @@ class OpenAIHandlerMixin:_ws_auth_mode.value,transforms_applied,)+ ws_frames_compressed += 1else:_log_ws_passthrough(_ws_reason or "no_compression",@@ -3379,6 +3674,18 @@ class OpenAIHandlerMixin:frame_type="unknown",)except Exception as _ce:+ if _first_frame_compression_elapsed_ms > 0:+ record_frame = getattr(+ getattr(self, "metrics", None), "record_codex_ws_frame", None+ )+ if record_frame is not None:+ record_frame(+ elapsed_ms=_first_frame_compression_elapsed_ms,+ bytes_before=len(+ first_msg_raw.encode("utf-8", errors="replace")+ ),+ failed=True,+ )logger.warning(f"[{request_id}] WS /v1/responses compression failed; "f"forwarding original frame: {type(_ce).__name__}: {_ce}"@@ -3511,6 +3818,7 @@ class OpenAIHandlerMixin:raw_bytes=len(raw_msg.encode("utf-8", errors="replace")),)return raw_msg, False, "optimize_disabled"+ _preflight_started = time.perf_counter()try:parsed_frame = json.loads(raw_msg)except json.JSONDecodeError:@@ -3547,9 +3855,18 @@ class OpenAIHandlerMixin:frame_type="response.create",)return raw_msg, False, "invalid_inner_payload"+ frame_compression_elapsed_ms = 0.0try:model_for_frame = inner_payload.get("model") or ""_frame_auth_mode = classify_auth_mode(ws_headers)+ _preflight_ms = (+ time.perf_counter() - _preflight_started+ ) * 1000.0+ _record_ws_compression_timing(+ "compression_preflight_serialization",+ _preflight_ms,+ )+ _record_ws_compression_overhead(_preflight_ms)_compression_started = time.perf_counter()try:(@@ -3561,16 +3878,62 @@ class OpenAIHandlerMixin:bytes_before,bytes_after,frame_attempted_tokens,+ frame_compression_timing,) = await self._compress_openai_responses_payload_in_executor(inner_payload,model=model_for_frame,request_id=request_id,)+ for _timing_name, _timing_ms in (+ frame_compression_timing.items()+ ):+ _record_ws_compression_timing(_timing_name, _timing_ms)finally:+ frame_compression_elapsed_ms = (+ time.perf_counter() - _compression_started+ ) * 1000.0+ _record_ws_compression_timing(+ "compression_executor_wait_run",+ frame_compression_elapsed_ms,+ )_record_ws_compression_overhead(- (time.perf_counter() - _compression_started) * 1000.0+ frame_compression_elapsed_ms+ )+ record_frame = getattr(+ getattr(self, "metrics", None),+ "record_codex_ws_frame",+ None,+ )+ if record_frame is not None:+ record_frame(+ elapsed_ms=frame_compression_elapsed_ms,+ bytes_before=bytes_before,+ bytes_after=bytes_after,+ attempted_tokens=frame_attempted_tokens,+ tokens_saved=frame_saved,+ modified=modified,+ strategy_chain=_codex_ws_strategy_chain(+ frame_transforms+ ),+ final_strategies=_codex_ws_final_strategies(+ frame_compression_timing+ ),)except Exception as _frame_err:+ if frame_compression_elapsed_ms > 0:+ record_frame = getattr(+ getattr(self, "metrics", None),+ "record_codex_ws_frame",+ None,+ )+ if record_frame is not None:+ record_frame(+ elapsed_ms=frame_compression_elapsed_ms,+ bytes_before=len(+ raw_msg.encode("utf-8", errors="replace")+ ),+ failed=True,+ )logger.warning("[%s] WS /v1/responses frame compression ""failed; forwarding original: %s: %s",@@ -3606,10 +3969,18 @@ class OpenAIHandlerMixin:)return raw_msg, False, "compressed_payload_not_dict"if wrapped_frame:+ _rewrite_started = time.perf_counter()parsed_frame["response"] = new_innerrewritten = json.dumps(parsed_frame)else:+ _rewrite_started = time.perf_counter()rewritten = json.dumps(new_inner)+ _rewrite_ms = (time.perf_counter() - _rewrite_started) * 1000.0+ _record_ws_compression_timing(+ "compression_payload_rewrite_json_dump",+ _rewrite_ms,+ )+ _record_ws_compression_overhead(_rewrite_ms)tokens_saved += int(frame_saved)attempted_input_tokens_total += int(frame_attempted_tokens)for t in frame_transforms:@@ -3889,6 +4260,9 @@ class OpenAIHandlerMixin:attempted_input_tokens_total)ws_recorded_overhead_ms_total = _current_ws_overhead_ms()+ ws_recorded_compression_timing_totals.update(+ ws_compression_timing_totals+ )if ttfb_for_record_ms > 0:ws_recorded_ttfb_ms = Truediff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 4223f4611..f99170446 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -571,7 +571,7 @@ _CONTEXT_TOOL_ENV = "HEADROOM_CONTEXT_TOOL"_CONTEXT_TOOL_RTK = "rtk"_CONTEXT_TOOL_LEAN_CTX = "lean-ctx"-RTK_STATS_CACHE_TTL_SECONDS = 5.0+RTK_STATS_CACHE_TTL_SECONDS = float(os.environ.get("HEADROOM_CONTEXT_TOOL_STATS_TTL_SECONDS", "60"))CONTEXT_TOOL_STATS_CACHE_TTL_SECONDS = RTK_STATS_CACHE_TTL_SECONDS_context_tool_stats_cache_lock = threading.Lock()_context_tool_stats_cache: dict[str, Any] = {@@ -584,7 +584,11 @@ _context_tool_session_baseline: dict[str, Any] = {"initialized": False,"tool": None,"total_commands": 0,+ "input_tokens": 0,+ "output_tokens": 0,"tokens_saved": 0,+ "total_time_ms": 0,+ "captured_at": 0.0,}_rtk_stats_cache_lock = _context_tool_stats_cache_lock_rtk_stats_cache = _context_tool_stats_cache@@ -849,6 +853,107 @@ def _first_value(mapping: dict[str, Any], keys: tuple[str, ...], default: Any =return default+def _context_tool_summary_payload(+ *,+ tool: str,+ installed: bool,+ summary: dict[str, Any] | None = None,+) -> dict[str, Any]:+ """Normalize RTK/lean-ctx lifetime gain output into one schema.++ Both tools expose cumulative counters, but field names vary slightly.+ Headroom computes session values by subtracting a startup baseline, so+ keeping raw input/output counters is necessary for a truthful session+ savings percentage.+ """++ summary = summary or {}+ input_tokens = _coerce_int(+ _first_value(+ summary,+ (+ "total_input",+ "total_input_tokens",+ "input_tokens",+ "tokens_input",+ "totalBefore",+ ),+ )+ )+ output_tokens = _coerce_int(+ _first_value(+ summary,+ (+ "total_output",+ "total_output_tokens",+ "output_tokens",+ "tokens_output",+ "totalAfter",+ ),+ )+ )+ tokens_saved = _coerce_int(+ _first_value(+ summary,+ (+ "total_saved",+ "tokens_saved",+ "total_tokens_saved",+ "saved_tokens",+ "totalSaved",+ ),+ )+ )+ if tokens_saved <= 0 and input_tokens > 0 and output_tokens >= 0:+ tokens_saved = max(input_tokens - output_tokens, 0)+ if input_tokens <= 0 and tokens_saved > 0 and output_tokens >= 0:+ input_tokens = tokens_saved + output_tokens++ lifetime_savings_pct = _coerce_float(+ _first_value(+ summary,+ (+ "avg_savings_pct",+ "average_savings_pct",+ "savings_pct",+ "savings_percent",+ "avgSavingsPct",+ ),+ 0.0,+ )+ )+ if lifetime_savings_pct <= 0 and input_tokens > 0:+ lifetime_savings_pct = (tokens_saved / input_tokens) * 100.0++ return {+ "tool": tool,+ "label": _context_tool_label(tool),+ "installed": installed,+ "scope": "project" if tool == _CONTEXT_TOOL_RTK else "local",+ "total_commands": _coerce_int(+ _first_value(+ summary,+ (+ "total_commands",+ "commands",+ "command_count",+ "totalCommandCount",+ ),+ )+ ),+ "input_tokens": input_tokens,+ "output_tokens": output_tokens,+ "tokens_saved": tokens_saved,+ # Backward-compatible name. See `lifetime_avg_savings_pct` and+ # `session_savings_pct` below for explicit scopes.+ "avg_savings_pct": lifetime_savings_pct,+ "lifetime_avg_savings_pct": lifetime_savings_pct,+ "total_time_ms": _coerce_int(+ _first_value(summary, ("total_time_ms", "time_ms", "totalTimeMs"))+ ),+ }++def _read_rtk_lifetime_stats() -> dict[str, Any] | None:"""Read rtk's current project-level lifetime stats."""@@ -860,9 +965,14 @@ def _read_rtk_lifetime_stats() -> dict[str, Any] | None:"tool": _CONTEXT_TOOL_RTK,"label": _context_tool_label(_CONTEXT_TOOL_RTK),"installed": False,+ "scope": "project","total_commands": 0,+ "input_tokens": 0,+ "output_tokens": 0,"tokens_saved": 0,"avg_savings_pct": 0.0,+ "lifetime_avg_savings_pct": 0.0,+ "total_time_ms": 0,}try:@@ -875,31 +985,38 @@ def _read_rtk_lifetime_stats() -> dict[str, Any] | None:if result.returncode == 0 and result.stdout.strip():data = json.loads(result.stdout)summary = data.get("summary", {})- payload = {- "tool": _CONTEXT_TOOL_RTK,- "label": _context_tool_label(_CONTEXT_TOOL_RTK),- "installed": True,- "total_commands": _coerce_int(summary.get("total_commands", 0)),- "tokens_saved": _coerce_int(summary.get("total_saved", 0)),- "avg_savings_pct": _coerce_float(summary.get("avg_savings_pct", 0.0)),- }+ payload = _context_tool_summary_payload(+ tool=_CONTEXT_TOOL_RTK,+ installed=True,+ summary=summary if isinstance(summary, dict) else {},+ )else:return {"tool": _CONTEXT_TOOL_RTK,"label": _context_tool_label(_CONTEXT_TOOL_RTK),"installed": True,+ "scope": "project","total_commands": 0,+ "input_tokens": 0,+ "output_tokens": 0,"tokens_saved": 0,"avg_savings_pct": 0.0,+ "lifetime_avg_savings_pct": 0.0,+ "total_time_ms": 0,}except Exception:return {"tool": _CONTEXT_TOOL_RTK,"label": _context_tool_label(_CONTEXT_TOOL_RTK),"installed": True,+ "scope": "project","total_commands": 0,+ "input_tokens": 0,+ "output_tokens": 0,"tokens_saved": 0,"avg_savings_pct": 0.0,+ "lifetime_avg_savings_pct": 0.0,+ "total_time_ms": 0,}return payload@@ -916,18 +1033,28 @@ def _read_lean_ctx_lifetime_stats() -> dict[str, Any] | None:"tool": _CONTEXT_TOOL_LEAN_CTX,"label": _context_tool_label(_CONTEXT_TOOL_LEAN_CTX),"installed": False,+ "scope": "local","total_commands": 0,+ "input_tokens": 0,+ "output_tokens": 0,"tokens_saved": 0,"avg_savings_pct": 0.0,+ "lifetime_avg_savings_pct": 0.0,+ "total_time_ms": 0,}base_payload = {"tool": _CONTEXT_TOOL_LEAN_CTX,"label": _context_tool_label(_CONTEXT_TOOL_LEAN_CTX),"installed": True,+ "scope": "local","total_commands": 0,+ "input_tokens": 0,+ "output_tokens": 0,"tokens_saved": 0,"avg_savings_pct": 0.0,+ "lifetime_avg_savings_pct": 0.0,+ "total_time_ms": 0,}try:@@ -945,44 +1072,11 @@ def _read_lean_ctx_lifetime_stats() -> dict[str, Any] | None:if not isinstance(summary, dict):return dict(base_payload)- return {- **base_payload,- "total_commands": _coerce_int(- _first_value(- summary,- (- "total_commands",- "commands",- "command_count",- "totalCommandCount",- ),- )- ),- "tokens_saved": _coerce_int(- _first_value(- summary,- (- "total_saved",- "tokens_saved",- "total_tokens_saved",- "saved_tokens",- "totalSaved",- ),- )- ),- "avg_savings_pct": _coerce_float(- _first_value(- summary,- (- "avg_savings_pct",- "average_savings_pct",- "avgSavingsPct",- "savings_percent",- ),- 0.0,- )- ),- }+ return _context_tool_summary_payload(+ tool=_CONTEXT_TOOL_LEAN_CTX,+ installed=True,+ summary=summary,+ )except Exception:return dict(base_payload)@@ -1004,7 +1098,11 @@ def initialize_context_tool_session_baseline() -> None:"initialized": True,"tool": tool,"total_commands": int((payload or {}).get("total_commands", 0) or 0),+ "input_tokens": int((payload or {}).get("input_tokens", 0) or 0),+ "output_tokens": int((payload or {}).get("output_tokens", 0) or 0),"tokens_saved": int((payload or {}).get("tokens_saved", 0) or 0),+ "total_time_ms": int((payload or {}).get("total_time_ms", 0) or 0),+ "captured_at": time.time(),})_context_tool_stats_cache.update(@@ -1053,25 +1151,124 @@ def _get_context_tool_stats() -> dict[str, Any] | None:"initialized": True,"tool": tool,"total_commands": int((payload or {}).get("total_commands", 0) or 0),+ "input_tokens": int((payload or {}).get("input_tokens", 0) or 0),+ "output_tokens": int((payload or {}).get("output_tokens", 0) or 0),"tokens_saved": int((payload or {}).get("tokens_saved", 0) or 0),+ "total_time_ms": int((payload or {}).get("total_time_ms", 0) or 0),+ "captured_at": time.time(),})if payload is not None:+ lifetime_total_commands = int(payload.get("total_commands", 0) or 0)+ lifetime_input_tokens = int(payload.get("input_tokens", 0) or 0)+ lifetime_output_tokens = int(payload.get("output_tokens", 0) or 0)+ lifetime_tokens_saved = int(payload.get("tokens_saved", 0) or 0)+ lifetime_total_time_ms = int(payload.get("total_time_ms", 0) or 0)+ baseline_total_commands = int(_context_tool_session_baseline["total_commands"])+ baseline_input_tokens = int(_context_tool_session_baseline["input_tokens"])+ baseline_output_tokens = int(_context_tool_session_baseline["output_tokens"])+ baseline_tokens_saved = int(_context_tool_session_baseline["tokens_saved"])+ baseline_total_time_ms = int(_context_tool_session_baseline["total_time_ms"])+ counter_reset_detected = (+ lifetime_total_commands < baseline_total_commands+ or lifetime_input_tokens < baseline_input_tokens+ or lifetime_output_tokens < baseline_output_tokens+ or lifetime_tokens_saved < baseline_tokens_saved+ or lifetime_total_time_ms < baseline_total_time_ms+ )+ if counter_reset_detected:+ baseline_total_commands = lifetime_total_commands+ baseline_input_tokens = lifetime_input_tokens+ baseline_output_tokens = lifetime_output_tokens+ baseline_tokens_saved = lifetime_tokens_saved+ baseline_total_time_ms = lifetime_total_time_ms+ _context_tool_session_baseline.update(+ {+ "total_commands": baseline_total_commands,+ "input_tokens": baseline_input_tokens,+ "output_tokens": baseline_output_tokens,+ "tokens_saved": baseline_tokens_saved,+ "total_time_ms": baseline_total_time_ms,+ "captured_at": time.time(),+ }+ )++ session_total_commands = max(lifetime_total_commands - baseline_total_commands, 0)+ session_input_tokens = max(lifetime_input_tokens - baseline_input_tokens, 0)+ session_output_tokens = max(lifetime_output_tokens - baseline_output_tokens, 0)+ session_tokens_saved = max(lifetime_tokens_saved - baseline_tokens_saved, 0)+ session_total_time_ms = max(lifetime_total_time_ms - baseline_total_time_ms, 0)+ session_savings_pct = (+ round(session_tokens_saved / session_input_tokens * 100.0, 4)+ if session_input_tokens > 0+ else None+ )+ session_avg_time_ms = (+ round(session_total_time_ms / session_total_commands, 2)+ if session_total_commands > 0 and session_total_time_ms > 0+ else None+ )+ lifetime_savings_pct = float(payload.get("lifetime_avg_savings_pct", 0.0) or 0.0)+payload = {**payload,"tool": tool,"label": _context_tool_label(tool),- "total_commands": max(- int(payload.get("total_commands", 0) or 0)- - int(_context_tool_session_baseline["total_commands"]),- 0,- ),- "tokens_saved": max(- int(payload.get("tokens_saved", 0) or 0)- - int(_context_tool_session_baseline["tokens_saved"]),- 0,+ # Backward-compatible session-delta fields.+ "total_commands": session_total_commands,+ "input_tokens": session_input_tokens,+ "output_tokens": session_output_tokens,+ "tokens_saved": session_tokens_saved,+ "total_time_ms": session_total_time_ms,+ "session_savings_pct": session_savings_pct,+ "session_avg_time_ms": session_avg_time_ms,+ # Keep old field for compatibility, but declare its scope.+ "avg_savings_pct": lifetime_savings_pct,+ "avg_savings_pct_scope": "lifetime",+ "lifetime_avg_savings_pct": lifetime_savings_pct,+ "lifetime_total_commands": lifetime_total_commands,+ "lifetime_input_tokens": lifetime_input_tokens,+ "lifetime_output_tokens": lifetime_output_tokens,+ "lifetime_tokens_saved": lifetime_tokens_saved,+ "lifetime_total_time_ms": lifetime_total_time_ms,+ "session_baseline_total_commands": baseline_total_commands,+ "session_baseline_input_tokens": baseline_input_tokens,+ "session_baseline_output_tokens": baseline_output_tokens,+ "session_baseline_tokens_saved": baseline_tokens_saved,+ "session_baseline_total_time_ms": baseline_total_time_ms,+ "session_baseline_captured_at": _context_tool_session_baseline.get(+ "captured_at", 0.0),+ "session": {+ "commands": session_total_commands,+ "input_tokens": session_input_tokens,+ "output_tokens": session_output_tokens,+ "tokens_saved": session_tokens_saved,+ "savings_pct": session_savings_pct,+ "total_time_ms": session_total_time_ms,+ "avg_time_ms": session_avg_time_ms,+ },+ "lifetime": {+ "commands": lifetime_total_commands,+ "input_tokens": lifetime_input_tokens,+ "output_tokens": lifetime_output_tokens,+ "tokens_saved": lifetime_tokens_saved,+ "savings_pct": lifetime_savings_pct,+ "total_time_ms": lifetime_total_time_ms,+ },+ "baseline": {+ "commands": baseline_total_commands,+ "input_tokens": baseline_input_tokens,+ "output_tokens": baseline_output_tokens,+ "tokens_saved": baseline_tokens_saved,+ "total_time_ms": baseline_total_time_ms,+ "captured_at": _context_tool_session_baseline.get("captured_at", 0.0),+ },+ "sampled_at": time.time(),+ "sample_ttl_seconds": CONTEXT_TOOL_STATS_CACHE_TTL_SECONDS,+ "refresh_interval_seconds": CONTEXT_TOOL_STATS_CACHE_TTL_SECONDS,+ "counter_reset_detected": counter_reset_detected,}_context_tool_stats_cache.update(diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.pyindex 4c5aee0d1..600b485f8 100644--- a/headroom/proxy/prometheus_metrics.py+++ b/headroom/proxy/prometheus_metrics.py@@ -106,6 +106,36 @@ class PrometheusMetrics:self.compressions_by_strategy: dict[str, int] = defaultdict(int)self.tokens_saved_by_strategy: dict[str, int] = defaultdict(int)+ # Codex WebSocket compression observability. These are intentionally+ # aggregate counters/sums, not per-unit storage, so /stats can answer+ # routing questions without growing with traffic volume.+ self.codex_ws_units_total = 0+ self.codex_ws_units_modified_total = 0+ self.codex_ws_units_to_kompress_total = 0+ self.codex_ws_units_kompress_attempted_total = 0+ self.codex_ws_units_by_strategy: dict[str, int] = defaultdict(int)+ self.codex_ws_units_by_category: dict[str, int] = defaultdict(int)+ self.codex_ws_units_by_content_type: dict[str, int] = defaultdict(int)+ self.codex_ws_units_by_text_shape: dict[str, int] = defaultdict(int)+ self.codex_ws_unit_elapsed_ms_sum = 0.0+ self.codex_ws_unit_elapsed_ms_max = 0.0+ self.codex_ws_unit_bytes_sum = 0+ self.codex_ws_unit_tokens_before_sum = 0+ self.codex_ws_unit_tokens_after_sum = 0+ self.codex_ws_unit_tokens_saved_sum = 0++ self.codex_ws_frames_attempted_total = 0+ self.codex_ws_frames_compressed_total = 0+ self.codex_ws_frames_failed_total = 0+ self.codex_ws_frames_to_kompress_total = 0+ self.codex_ws_frames_kompress_attempted_total = 0+ self.codex_ws_frame_elapsed_ms_sum = 0.0+ self.codex_ws_frame_elapsed_ms_max = 0.0+ self.codex_ws_frame_bytes_before_sum = 0+ self.codex_ws_frame_bytes_after_sum = 0+ self.codex_ws_frame_attempted_tokens_sum = 0+ self.codex_ws_frame_tokens_saved_sum = 0+self.latency_sum_ms = 0.0self.latency_min_ms = float("inf")self.latency_max_ms = 0.0@@ -242,6 +272,33 @@ class PrometheusMetrics:self.compressions_by_strategy.clear()self.tokens_saved_by_strategy.clear()+ self.codex_ws_units_total = 0+ self.codex_ws_units_modified_total = 0+ self.codex_ws_units_to_kompress_total = 0+ self.codex_ws_units_kompress_attempted_total = 0+ self.codex_ws_units_by_strategy.clear()+ self.codex_ws_units_by_category.clear()+ self.codex_ws_units_by_content_type.clear()+ self.codex_ws_units_by_text_shape.clear()+ self.codex_ws_unit_elapsed_ms_sum = 0.0+ self.codex_ws_unit_elapsed_ms_max = 0.0+ self.codex_ws_unit_bytes_sum = 0+ self.codex_ws_unit_tokens_before_sum = 0+ self.codex_ws_unit_tokens_after_sum = 0+ self.codex_ws_unit_tokens_saved_sum = 0++ self.codex_ws_frames_attempted_total = 0+ self.codex_ws_frames_compressed_total = 0+ self.codex_ws_frames_failed_total = 0+ self.codex_ws_frames_to_kompress_total = 0+ self.codex_ws_frames_kompress_attempted_total = 0+ self.codex_ws_frame_elapsed_ms_sum = 0.0+ self.codex_ws_frame_elapsed_ms_max = 0.0+ self.codex_ws_frame_bytes_before_sum = 0+ self.codex_ws_frame_bytes_after_sum = 0+ self.codex_ws_frame_attempted_tokens_sum = 0+ self.codex_ws_frame_tokens_saved_sum = 0+self.latency_sum_ms = 0.0self.latency_min_ms = float("inf")self.latency_max_ms = 0.0@@ -383,6 +440,83 @@ class PrometheusMetrics:if count > 0:self.router_route_counts[category] += int(count)+ def record_codex_ws_unit(+ self,+ *,+ strategy: str,+ reason_category: str,+ elapsed_ms: float,+ text_bytes: int,+ tokens_before: int,+ tokens_after: int,+ tokens_saved: int,+ modified: bool,+ strategy_chain: list[str] | None = None,+ content_type: str = "unknown",+ text_shape: str = "unknown",+ ) -> None:+ """Record one Codex WS compression unit decision."""++ strategy = strategy or "unknown"+ reason_category = reason_category or "unknown"+ chain = strategy_chain or []++ self.codex_ws_units_total += 1+ self.codex_ws_units_by_strategy[strategy] += 1+ self.codex_ws_units_by_category[reason_category] += 1+ self.codex_ws_units_by_content_type[content_type or "unknown"] += 1+ self.codex_ws_units_by_text_shape[text_shape or "unknown"] += 1+ if modified:+ self.codex_ws_units_modified_total += 1+ if strategy == "kompress":+ self.codex_ws_units_to_kompress_total += 1+ if "kompress" in chain or strategy == "kompress":+ self.codex_ws_units_kompress_attempted_total += 1++ elapsed_ms = max(0.0, float(elapsed_ms))+ self.codex_ws_unit_elapsed_ms_sum += elapsed_ms+ self.codex_ws_unit_elapsed_ms_max = max(self.codex_ws_unit_elapsed_ms_max, elapsed_ms)+ self.codex_ws_unit_bytes_sum += max(0, int(text_bytes))+ self.codex_ws_unit_tokens_before_sum += max(0, int(tokens_before))+ self.codex_ws_unit_tokens_after_sum += max(0, int(tokens_after))+ self.codex_ws_unit_tokens_saved_sum += max(0, int(tokens_saved))++ def record_codex_ws_frame(+ self,+ *,+ elapsed_ms: float,+ bytes_before: int,+ bytes_after: int = 0,+ attempted_tokens: int = 0,+ tokens_saved: int = 0,+ modified: bool = False,+ failed: bool = False,+ strategy_chain: list[str] | None = None,+ final_strategies: list[str] | None = None,+ ) -> None:+ """Record one Codex WS response.create compression attempt."""++ chain = strategy_chain or []+ strategies = final_strategies or []++ self.codex_ws_frames_attempted_total += 1+ if modified:+ self.codex_ws_frames_compressed_total += 1+ if failed:+ self.codex_ws_frames_failed_total += 1+ if "kompress" in strategies:+ self.codex_ws_frames_to_kompress_total += 1+ if "kompress" in chain or "kompress" in strategies:+ self.codex_ws_frames_kompress_attempted_total += 1++ elapsed_ms = max(0.0, float(elapsed_ms))+ self.codex_ws_frame_elapsed_ms_sum += elapsed_ms+ self.codex_ws_frame_elapsed_ms_max = max(self.codex_ws_frame_elapsed_ms_max, elapsed_ms)+ self.codex_ws_frame_bytes_before_sum += max(0, int(bytes_before))+ self.codex_ws_frame_bytes_after_sum += max(0, int(bytes_after))+ self.codex_ws_frame_attempted_tokens_sum += max(0, int(attempted_tokens))+ self.codex_ws_frame_tokens_saved_sum += max(0, int(tokens_saved))+def record_inbound_request(self, *, method: str, path: str) -> None:self.inbound_requests_total += 1self.inbound_requests_active += 1diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 33d73dd63..2432290d0 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -498,9 +498,16 @@ class HeadroomProxy(# Gauge: currently-running compression tasks. Mutated under# ``_compression_metrics_lock`` from worker threads + the asyncio# event loop.+ self._compression_queued: int = 0+ self._compression_queued_max: int = 0+ self._compression_queue_timeouts: int = 0+ self._compression_queue_wait_seconds_total: float = 0.0+ self._compression_queue_wait_seconds_max: float = 0.0self._compression_in_flight: int = 0# High-water mark for in-flight count.self._compression_in_flight_max: int = 0+ self._compression_run_seconds_total: float = 0.0+ self._compression_run_seconds_max: float = 0.0# Counter: threads that finished AFTER their asyncio future hit the# timeout. Stuck-thread leak indicator.self._compression_leaked_threads: int = 0@@ -683,10 +690,12 @@ class HeadroomProxy(actually cancel a thread that has started — Python has no way topreempt running CPython bytecode or in-flight Rust calls. Theworker keeps running to completion, ignored. We detect this by- recording the start timestamp and incrementing+ marking the call timed out on the asyncio side and incrementing``_compression_leaked_threads`` from the worker's ``finally``- block when ``elapsed > timeout``. Operators can see leaked-thread- rate climbing in ``/stats`` before the pool fills up.+ block after it eventually finishes. Jobs that time out before a+ worker starts are removed from the queued gauge instead. Operators+ can see leaked-thread rate and queue pressure climbing in+ ``/stats`` before the pool fills up.Args:fn: A no-arg sync callable that runs the compression. Must not@@ -706,24 +715,49 @@ class HeadroomProxy(unchanged."""loop = asyncio.get_running_loop()- start = time.monotonic()+ queued_at = time.monotonic()+ state = {"queued": True, "timed_out": False}with self._compression_metrics_lock:- self._compression_in_flight += 1- if self._compression_in_flight > self._compression_in_flight_max:- self._compression_in_flight_max = self._compression_in_flight+ self._compression_queued += 1+ if self._compression_queued > self._compression_queued_max:+ self._compression_queued_max = self._compression_queueddef _wrapped(): # noqa: ANN202+ started_at = time.monotonic()+ queue_wait = started_at - queued_at+ with self._compression_metrics_lock:+ if state["queued"]:+ self._compression_queued -= 1+ state["queued"] = False+ self._compression_queue_wait_seconds_total += queue_wait+ if queue_wait > self._compression_queue_wait_seconds_max:+ self._compression_queue_wait_seconds_max = queue_wait+ self._compression_in_flight += 1+ if self._compression_in_flight > self._compression_in_flight_max:+ self._compression_in_flight_max = self._compression_in_flighttry:return fn()finally:- elapsed = time.monotonic() - start+ elapsed = time.monotonic() - started_atwith self._compression_metrics_lock:self._compression_in_flight -= 1- if elapsed > timeout:+ self._compression_run_seconds_total += elapsed+ if elapsed > self._compression_run_seconds_max:+ self._compression_run_seconds_max = elapsed+ if state["timed_out"]:self._compression_leaked_threads += 1future = loop.run_in_executor(self._compression_executor, _wrapped)- return await asyncio.wait_for(future, timeout=timeout)+ try:+ return await asyncio.wait_for(future, timeout=timeout)+ except asyncio.TimeoutError:+ with self._compression_metrics_lock:+ state["timed_out"] = True+ if state["queued"]:+ self._compression_queued -= 1+ state["queued"] = False+ self._compression_queue_timeouts += 1+ raisedef _get_compression_cache(self, session_id: str) -> CompressionCache:"""Get or create a CompressionCache for a session.@@ -1491,8 +1525,15 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# Snapshot compression executor metrics under their lock (gauges# mutated by worker threads; not safe to read without).with proxy._compression_metrics_lock:+ _comp_queued = proxy._compression_queued+ _comp_queued_max = proxy._compression_queued_max+ _comp_queue_timeouts = proxy._compression_queue_timeouts+ _comp_queue_wait_total = proxy._compression_queue_wait_seconds_total+ _comp_queue_wait_max = proxy._compression_queue_wait_seconds_max_comp_in_flight = proxy._compression_in_flight_comp_in_flight_max = proxy._compression_in_flight_max+ _comp_run_total = proxy._compression_run_seconds_total+ _comp_run_max = proxy._compression_run_seconds_max_comp_leaked = proxy._compression_leaked_threadsreturn {"anthropic_pre_upstream": {@@ -1510,8 +1551,16 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:},"compression_executor": {"max_workers": proxy.compression_max_workers,+ "queued": _comp_queued,+ "queued_max": _comp_queued_max,+ "queue_timeouts_total": _comp_queue_timeouts,+ "queue_wait_seconds_total": _comp_queue_wait_total,+ "queue_wait_seconds_max": _comp_queue_wait_max,+ "running": _comp_in_flight,"in_flight": _comp_in_flight,"in_flight_max": _comp_in_flight_max,+ "run_seconds_total": _comp_run_total,+ "run_seconds_max": _comp_run_max,"leaked_threads_total": _comp_leaked,"source": ("auto" if config.compression_max_workers is None else "explicit"),},@@ -1782,6 +1831,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:)max_ttfb_ms = round(m.ttfb_max_ms, 2) if m.ttfb_count > 0 else 0+ def _pct(part: int | float, whole: int | float) -> float:+ return round((float(part) / float(whole)) * 100.0, 2) if whole else 0.0+# Get compression store statsstore = get_compression_store()compression_stats = store.get_stats()@@ -1809,6 +1861,12 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:cli_tokens_avoided = (cli_filtering_stats.get("tokens_saved", 0) if cli_filtering_stats else 0)+ cli_filtering_session = (+ cli_filtering_stats.get("session", {}) if cli_filtering_stats else {}+ )+ cli_filtering_lifetime = (+ cli_filtering_stats.get("lifetime", {}) if cli_filtering_stats else {}+ )rtk_tokens_avoided = cli_tokens_avoided if cli_filtering_tool == "rtk" else 0lean_ctx_tokens_avoided = cli_tokens_avoided if cli_filtering_tool == "lean-ctx" else 0@@ -1890,6 +1948,23 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"label": cli_filtering_label,"tokens": cli_tokens_avoided,"tokens_saved": cli_tokens_avoided,+ "session": cli_filtering_session,+ "lifetime": cli_filtering_lifetime,+ "session_savings_pct": (+ cli_filtering_stats.get("session_savings_pct")+ if cli_filtering_stats+ else None+ ),+ "lifetime_savings_pct": (+ cli_filtering_stats.get("lifetime_avg_savings_pct")+ if cli_filtering_stats+ else None+ ),+ "refresh_interval_seconds": (+ cli_filtering_stats.get("refresh_interval_seconds")+ if cli_filtering_stats+ else None+ ),"included_in": "tokens.saved","description": (f"Tokens avoided by CLI output filtering ({cli_filtering_label}) "@@ -2009,6 +2084,65 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:else {},"compressions_by_strategy": dict(m.compressions_by_strategy),"tokens_saved_by_strategy": dict(m.tokens_saved_by_strategy),+ "codex_ws": {+ "units_total": m.codex_ws_units_total,+ "units_modified_total": m.codex_ws_units_modified_total,+ "units_by_strategy": dict(m.codex_ws_units_by_strategy),+ "units_by_category": dict(m.codex_ws_units_by_category),+ "units_by_content_type": dict(m.codex_ws_units_by_content_type),+ "units_by_text_shape": dict(m.codex_ws_units_by_text_shape),+ "units_to_kompress_total": m.codex_ws_units_to_kompress_total,+ "units_kompress_attempted_total": m.codex_ws_units_kompress_attempted_total,+ "units_to_kompress_percent": _pct(+ m.codex_ws_units_to_kompress_total,+ m.codex_ws_units_total,+ ),+ "units_kompress_attempted_percent": _pct(+ m.codex_ws_units_kompress_attempted_total,+ m.codex_ws_units_total,+ ),+ "unit_elapsed_ms": {+ "average": round(+ m.codex_ws_unit_elapsed_ms_sum / m.codex_ws_units_total,+ 2,+ )+ if m.codex_ws_units_total+ else 0.0,+ "max": round(m.codex_ws_unit_elapsed_ms_max, 2),+ },+ "unit_bytes_sum": m.codex_ws_unit_bytes_sum,+ "unit_tokens_before_sum": m.codex_ws_unit_tokens_before_sum,+ "unit_tokens_after_sum": m.codex_ws_unit_tokens_after_sum,+ "unit_tokens_saved_sum": m.codex_ws_unit_tokens_saved_sum,+ "frames_attempted_total": m.codex_ws_frames_attempted_total,+ "frames_compressed_total": m.codex_ws_frames_compressed_total,+ "frames_failed_total": m.codex_ws_frames_failed_total,+ "frames_to_kompress_total": m.codex_ws_frames_to_kompress_total,+ "frames_kompress_attempted_total": (+ m.codex_ws_frames_kompress_attempted_total+ ),+ "frames_to_kompress_percent": _pct(+ m.codex_ws_frames_to_kompress_total,+ m.codex_ws_frames_attempted_total,+ ),+ "frames_kompress_attempted_percent": _pct(+ m.codex_ws_frames_kompress_attempted_total,+ m.codex_ws_frames_attempted_total,+ ),+ "frame_elapsed_ms": {+ "average": round(+ m.codex_ws_frame_elapsed_ms_sum / m.codex_ws_frames_attempted_total,+ 2,+ )+ if m.codex_ws_frames_attempted_total+ else 0.0,+ "max": round(m.codex_ws_frame_elapsed_ms_max, 2),+ },+ "frame_bytes_before_sum": m.codex_ws_frame_bytes_before_sum,+ "frame_bytes_after_sum": m.codex_ws_frame_bytes_after_sum,+ "frame_attempted_tokens_sum": m.codex_ws_frame_attempted_tokens_sum,+ "frame_tokens_saved_sum": m.codex_ws_frame_tokens_saved_sum,+ },"waste_signals": dict(m.waste_signals_total) if m.waste_signals_total else {},# ContentRouter protection categories aggregated across the# session. Lets operators see, e.g., that 80% of messagesdiff --git a/headroom/transforms/compression_units.py b/headroom/transforms/compression_units.pyindex ab97426eb..62ab046b3 100644--- a/headroom/transforms/compression_units.py+++ b/headroom/transforms/compression_units.py@@ -13,7 +13,11 @@ from collections.abc import Iterablefrom dataclasses import dataclass, field, replacefrom typing import Protocol-from .content_router import CompressionStrategy, ContentRouter, RouterCompressionResult+from .content_router import (+ CompressionStrategy,+ ContentRouter,+ RouterCompressionResult,+)class TokenCounterLike(Protocol):diff --git a/headroom/transforms/content_detector.py b/headroom/transforms/content_detector.pyindex cca6f0e93..324139726 100644--- a/headroom/transforms/content_detector.py+++ b/headroom/transforms/content_detector.py@@ -108,6 +108,7 @@ _LOG_PATTERNS = [re.compile(r"^\s*PASSED|^\s*FAILED|^\s*SKIPPED"), # test resultsre.compile(r"^npm ERR!|^yarn error|^cargo error"), # build toolsre.compile(r"Traceback \(most recent call last\)"), # Python traceback+ re.compile(r"^\w*(Error|Exception):"), # Python exception final linere.compile(r"^\s*at\s+[\w.$]+\("), # JS/Java stack trace]diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 06539b52a..ef96b487d 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -49,6 +49,7 @@ from ..config import DEFAULT_EXCLUDE_TOOLS, ReadLifecycleConfig, TransformResultfrom ..tokenizer import Tokenizerfrom .base import Transformfrom .content_detector import ContentType, DetectionResult+from .content_detector import detect_content_type as _regex_detect_content_typelogger = logging.getLogger(__name__)@@ -58,8 +59,10 @@ def _router_debug_dumps(value: Any) -> str:def _log_router_debug(event: str, **payload: Any) -> None:+ if not logger.isEnabledFor(logging.DEBUG):+ returnpayload = {"event": event, **payload}- logger.info("event=%s %s", event, _router_debug_dumps(payload))+ logger.debug("event=%s %s", event, _router_debug_dumps(payload))def _json_shape(content: str) -> dict[str, Any]:@@ -125,6 +128,10 @@ def _detect_content(content: str) -> DetectionResult:# "json_array"); translate to the Python `ContentType` enum so# downstream mapping keys match.content_type = ContentType(rust_result.content_type)+ if content_type is ContentType.PLAIN_TEXT:+ regex_result = _regex_detect_content_type(content)+ if regex_result.content_type is not ContentType.PLAIN_TEXT:+ return regex_resultreturn DetectionResult(content_type=content_type,confidence=rust_result.confidence,@@ -837,25 +844,31 @@ class ContentRouter(Transform):Returns:RouterCompressionResult with compressed content and routing metadata."""- request_debug = {- "chars": len(content),- "bytes": len(content.encode("utf-8", errors="replace")),- "tokens_estimate": len(content.split()),- "json_shape": _json_shape(content),- "mixed_indicators": _mixed_indicators(content),- "context_chars": len(context),- "question": question,- "bias": bias,- "content": content,- "context": context,- }+ debug_enabled = logger.isEnabledFor(logging.DEBUG)+ request_debug = (+ {+ "chars": len(content),+ "bytes": len(content.encode("utf-8", errors="replace")),+ "tokens_estimate": len(content.split()),+ "json_shape": _json_shape(content),+ "mixed_indicators": _mixed_indicators(content),+ "context_chars": len(context),+ "question": question,+ "bias": bias,+ "content": content,+ "context": context,+ }+ if debug_enabled+ else {}+ )if not content or not content.strip():- _log_router_debug(- "content_router_input",- **request_debug,- selected_strategy=CompressionStrategy.PASSTHROUGH.value,- selection_reason="empty_or_whitespace",- )+ if debug_enabled:+ _log_router_debug(+ "content_router_input",+ **request_debug,+ selected_strategy=CompressionStrategy.PASSTHROUGH.value,+ selection_reason="empty_or_whitespace",+ )result = RouterCompressionResult(compressed=content,original=content,@@ -867,14 +880,15 @@ class ContentRouter(Transform):mixed = is_mixed_content(content)detection = _detect_content(content)strategy = self._determine_strategy(content)- _log_router_debug(- "content_router_input",- **request_debug,- detected_content_type=detection.content_type.value,- detection_confidence=detection.confidence,- selected_strategy=strategy.value,- selection_reason="mixed_content" if mixed else "content_detection",- )+ if debug_enabled:+ _log_router_debug(+ "content_router_input",+ **request_debug,+ detected_content_type=detection.content_type.value,+ detection_confidence=detection.confidence,+ selected_strategy=strategy.value,+ selection_reason="mixed_content" if mixed else "content_detection",+ )if strategy == CompressionStrategy.MIXED:result = self._compress_mixed(content, context, question, bias=bias)@@ -885,30 +899,31 @@ class ContentRouter(Transform):# forcing function for catching strategy-level regressions.# Empty routing_log (passthrough fast path) → no calls.self._observe(result)- _log_router_debug(- "content_router_output",- selected_strategy=result.strategy_used.value,- sections_processed=result.sections_processed,- total_original_tokens=result.total_original_tokens,- total_compressed_tokens=result.total_compressed_tokens,- tokens_saved=result.tokens_saved,- savings_percentage=result.savings_percentage,- compression_ratio=result.compression_ratio,- routing_log=[- {- "content_type": decision.content_type.value,- "strategy": decision.strategy.value,- "original_tokens": decision.original_tokens,- "compressed_tokens": decision.compressed_tokens,- "confidence": decision.confidence,- "section_index": decision.section_index,- "compression_ratio": decision.compression_ratio,- }- for decision in result.routing_log- ],- original=result.original,- compressed=result.compressed,- )+ if debug_enabled:+ _log_router_debug(+ "content_router_output",+ selected_strategy=result.strategy_used.value,+ sections_processed=result.sections_processed,+ total_original_tokens=result.total_original_tokens,+ total_compressed_tokens=result.total_compressed_tokens,+ tokens_saved=result.tokens_saved,+ savings_percentage=result.savings_percentage,+ compression_ratio=result.compression_ratio,+ routing_log=[+ {+ "content_type": decision.content_type.value,+ "strategy": decision.strategy.value,+ "original_tokens": decision.original_tokens,+ "compressed_tokens": decision.compressed_tokens,+ "confidence": decision.confidence,+ "section_index": decision.section_index,+ "compression_ratio": decision.compression_ratio,+ }+ for decision in result.routing_log+ ],+ original=result.original,+ compressed=result.compressed,+ )return resultdef _observe(self, result: RouterCompressionResult) -> None:@@ -997,12 +1012,13 @@ class ContentRouter(Transform):RouterCompressionResult with reassembled content."""sections = split_into_sections(content)- _log_router_debug(- "content_router_mixed_sections",- section_count=len(sections),- sections=[_section_debug(section, idx) for idx, section in enumerate(sections)],- content=content,- )+ if logger.isEnabledFor(logging.DEBUG):+ _log_router_debug(+ "content_router_mixed_sections",+ section_count=len(sections),+ sections=[_section_debug(section, idx) for idx, section in enumerate(sections)],+ content=content,+ )if not sections:return RouterCompressionResult(@@ -1241,6 +1257,12 @@ class ContentRouter(Transform):compressor_name = "KompressCompressor"decision_reason = "text_uses_kompress"+ elif strategy == CompressionStrategy.PASSTHROUGH:+ compressed = content+ compressed_tokens = original_tokens+ compressor_name = "Passthrough"+ decision_reason = "explicit_passthrough"+except Exception as e:error = f"{type(e).__name__}: {e}"decision_reason = "compression_exception"@@ -1251,8 +1273,6 @@ class ContentRouter(Transform):fallback_eligible_strategy = strategy in {CompressionStrategy.SMART_CRUSHER,CompressionStrategy.CODE_AWARE,- CompressionStrategy.DIFF,- CompressionStrategy.LOG,}fallback_no_savings = compressed == content or compressed_tokens >= original_tokensif fallback_eligible_strategy and fallback_no_savings:@@ -1294,25 +1314,28 @@ class ContentRouter(Transform):f"{decision_reason}_fallback_log_after_no_savings")- _log_router_debug(- "content_router_strategy_result",- requested_strategy=requested_strategy.value,- actual_strategy=actual_strategy.value,- strategy_chain=strategy_chain,- compressor=compressor_name,- reason=decision_reason,- language=language,- question=question,- bias=bias,- original_tokens=original_tokens,- compressed_tokens=compressed_tokens,- tokens_saved=max(0, original_tokens - compressed_tokens),- compression_ratio=compressed_tokens / original_tokens if original_tokens else 1.0,- json_shape=_json_shape(content),- input=content,- output=compressed,- error=error,- )+ if logger.isEnabledFor(logging.DEBUG):+ _log_router_debug(+ "content_router_strategy_result",+ requested_strategy=requested_strategy.value,+ actual_strategy=actual_strategy.value,+ strategy_chain=strategy_chain,+ compressor=compressor_name,+ reason=decision_reason,+ language=language,+ question=question,+ bias=bias,+ original_tokens=original_tokens,+ compressed_tokens=compressed_tokens,+ tokens_saved=max(0, original_tokens - compressed_tokens),+ compression_ratio=compressed_tokens / original_tokens+ if original_tokens+ else 1.0,+ json_shape=_json_shape(content),+ input=content,+ output=compressed,+ error=error,+ )self._record_to_toin(strategy=strategy,content=content,@@ -1326,25 +1349,26 @@ class ContentRouter(Transform):# Fallback: return unchangedstrategy_chain.append(CompressionStrategy.PASSTHROUGH.value)- _log_router_debug(- "content_router_strategy_result",- requested_strategy=requested_strategy.value,- actual_strategy=CompressionStrategy.PASSTHROUGH.value,- strategy_chain=strategy_chain,- compressor=None,- reason=decision_reason,- language=language,- question=question,- bias=bias,- original_tokens=original_tokens,- compressed_tokens=original_tokens,- tokens_saved=0,- compression_ratio=1.0,- json_shape=_json_shape(content),- input=content,- output=content,- error=error,- )+ if logger.isEnabledFor(logging.DEBUG):+ _log_router_debug(+ "content_router_strategy_result",+ requested_strategy=requested_strategy.value,+ actual_strategy=CompressionStrategy.PASSTHROUGH.value,+ strategy_chain=strategy_chain,+ compressor=None,+ reason=decision_reason,+ language=language,+ question=question,+ bias=bias,+ original_tokens=original_tokens,+ compressed_tokens=original_tokens,+ tokens_saved=0,+ compression_ratio=1.0,+ json_shape=_json_shape(content),+ input=content,+ output=content,+ error=error,+ )return content, original_tokens, strategy_chaindef _try_ml_compressor(@@ -1529,8 +1553,10 @@ class ContentRouter(Transform):if self.config.enable_kompress:compressor = self._get_kompress()if compressor:- logger.info("Kompress model pre-loaded at startup")+ backend = compressor.preload() if hasattr(compressor, "preload") else "unknown"+ logger.info("Kompress model pre-loaded at startup backend=%s", backend)status["kompress"] = "enabled"+ status["kompress_backend"] = str(backend)else:status["kompress"] = "unavailable"diff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.pyindex ba9dc99f9..cf9e724c4 100644--- a/headroom/transforms/kompress_compressor.py+++ b/headroom/transforms/kompress_compressor.py@@ -403,6 +403,12 @@ class KompressCompressor(Transform):def __init__(self, config: KompressConfig | None = None):self.config = config or KompressConfig()+ def preload(self) -> str:+ """Load the backing model/tokenizer and return the selected backend."""++ _model, _tokenizer, backend = _load_kompress(self.config.model_id, self.config.device)+ return backend+def compress(self,content: str,diff --git a/tests/test_compression_observability.py b/tests/test_compression_observability.pyindex 89f495aeb..c1f2b5857 100644--- a/tests/test_compression_observability.py+++ b/tests/test_compression_observability.py@@ -273,6 +273,73 @@ def test_prometheus_metrics_accumulates_per_strategy_counters():assert m.tokens_saved_by_strategy == {"smart_crusher": 210}+def test_prometheus_metrics_accumulates_codex_ws_unit_and_frame_counters():+ from headroom.proxy.prometheus_metrics import PrometheusMetrics++ m = PrometheusMetrics()++ m.record_codex_ws_unit(+ strategy="mixed",+ reason_category="applied",+ elapsed_ms=1250,+ text_bytes=10_000,+ tokens_before=2500,+ tokens_after=1000,+ tokens_saved=1500,+ modified=True,+ strategy_chain=["mixed", "kompress"],+ content_type="text",+ text_shape="jsonl_like",+ )+ m.record_codex_ws_unit(+ strategy="passthrough",+ reason_category="size_floor",+ elapsed_ms=2,+ text_bytes=100,+ tokens_before=20,+ tokens_after=20,+ tokens_saved=0,+ modified=False,+ strategy_chain=["passthrough"],+ content_type="unknown",+ text_shape="plain_text_like",+ )+ m.record_codex_ws_frame(+ elapsed_ms=1260,+ bytes_before=20_000,+ bytes_after=8_000,+ attempted_tokens=2500,+ tokens_saved=1500,+ modified=True,+ strategy_chain=["mixed", "kompress"],+ final_strategies=["mixed"],+ )+ m.record_codex_ws_frame(+ elapsed_ms=30_000,+ bytes_before=426_318,+ failed=True,+ )++ assert m.codex_ws_units_total == 2+ assert m.codex_ws_units_modified_total == 1+ assert m.codex_ws_units_by_strategy == {"mixed": 1, "passthrough": 1}+ assert m.codex_ws_units_by_category == {"applied": 1, "size_floor": 1}+ assert m.codex_ws_units_by_content_type == {"text": 1, "unknown": 1}+ assert m.codex_ws_units_by_text_shape == {"jsonl_like": 1, "plain_text_like": 1}+ assert m.codex_ws_units_to_kompress_total == 0+ assert m.codex_ws_units_kompress_attempted_total == 1+ assert m.codex_ws_unit_elapsed_ms_max == 1250+ assert m.codex_ws_unit_tokens_saved_sum == 1500++ assert m.codex_ws_frames_attempted_total == 2+ assert m.codex_ws_frames_compressed_total == 1+ assert m.codex_ws_frames_failed_total == 1+ assert m.codex_ws_frames_to_kompress_total == 0+ assert m.codex_ws_frames_kompress_attempted_total == 1+ assert m.codex_ws_frame_elapsed_ms_max == 30_000+ assert m.codex_ws_frame_tokens_saved_sum == 1500++def test_prometheus_export_does_not_leak_per_strategy_metrics():"""Per-strategy state is tracked in-process only. The Prometheusscrape output deliberately must NOT emit new metric names — thediff --git a/tests/test_openai_codex_ws_lifecycle.py b/tests/test_openai_codex_ws_lifecycle.pyindex 17916a878..5beb90ee7 100644--- a/tests/test_openai_codex_ws_lifecycle.py+++ b/tests/test_openai_codex_ws_lifecycle.py@@ -360,7 +360,10 @@ async def test_ws_session_metrics_include_dashboard_performance_timings():handler = _DummyOpenAIHandler()handler.config.optimize = True- def _noop_compress(payload, *, model, request_id):+ def _noop_compress(payload, *, model, request_id, timing=None):+ if timing is not None:+ timing["compression_live_unit_extraction"] = 2.0+ timing["compression_unit_router_strategy_passthrough"] = 3.0return payload, False, 0, [], "test_noop", 10, 10, 0handler._compress_openai_responses_payload = _noop_compress # type: ignore[method-assign]@@ -374,6 +377,10 @@ async def test_ws_session_metrics_include_dashboard_performance_timings():assert recorded["ttfb_ms"] > 0assert recorded["pipeline_timing"]["codex_ws.compression"] > 0assert recorded["pipeline_timing"]["codex_ws.upstream_first_event"] > 0+ assert recorded["pipeline_timing"]["codex_ws.compression_preflight_serialization"] > 0+ assert recorded["pipeline_timing"]["codex_ws.compression_executor_wait_run"] > 0+ assert recorded["pipeline_timing"]["codex_ws.compression_live_unit_extraction"] == 2.0+ assert recorded["pipeline_timing"]["codex_ws.compression_unit_router_strategy_passthrough"] == 3.0@pytest.mark.asynciodiff --git a/tests/test_openai_codex_ws_timings.py b/tests/test_openai_codex_ws_timings.pyindex d0337798e..8dfb1d099 100644--- a/tests/test_openai_codex_ws_timings.py+++ b/tests/test_openai_codex_ws_timings.py@@ -11,6 +11,7 @@ from unittest.mock import MagicMock, patchimport anyioimport pytest+import headroom.proxy.handlers.openai as openai_handlerfrom headroom.proxy.handlers.openai import OpenAIHandlerMixin@@ -278,3 +279,20 @@ def test_codex_ws_request_id_and_session_id_present_in_log(stage_log_capture):assert payload["request_id"] == "req-ws-test"assert isinstance(payload["session_id"], str)assert len(payload["session_id"]) >= 16++def test_codex_compression_debug_noop_skips_expensive_payload_debug(monkeypatch):+ handler = _DummyOpenAIHandler()++ def _fail_context_budget(_payload):+ raise AssertionError("debug context budget should not be built")++ monkeypatch.setattr(openai_handler, "_openai_responses_context_budget", _fail_context_budget)++ result = handler._compress_openai_responses_payload(+ {"model": "gpt-5.4", "input": "hello"},+ model="gpt-5.4",+ request_id="req-ws-test",+ )++ assert result[1] is False+ assert result[4] == "router_no_compression"diff --git a/tests/test_proxy_compression_executor.py b/tests/test_proxy_compression_executor.pyindex 2c2d78ccc..bd74f22ff 100644--- a/tests/test_proxy_compression_executor.py+++ b/tests/test_proxy_compression_executor.py@@ -13,8 +13,9 @@ Locks the following invariants:``TimeoutError`` — but the worker thread keeps running (Python cannotpreempt running CPython bytecode or in-flight Rust calls), and when thework eventually completes, ``compression_leaked_threads`` increments.-4. ``/stats runtime.compression_executor`` surfaces the gauge + counter so- operators can see leaked-thread rate.+4. Jobs that time out while still queued do not leak the running gauge.+5. ``/stats runtime.compression_executor`` surfaces the gauges + counters so+ operators can see leaked-thread rate and queue pressure.These tests also serve as documentation: anyone reading them sees that"timeout fired" does not mean "compression was cancelled" — it means "we@@ -205,6 +206,58 @@ def test_timeout_fires_and_leaked_thread_is_counted() -> None:assert proxy._compression_in_flight == 0+def test_timeout_before_worker_start_does_not_leak_in_flight() -> None:+ """If a queued job times out before a worker starts, queued accounting+ is cleaned up without touching the running gauge.+ """+ proxy = _make_proxy(compression_max_workers=1)+ first_started = threading.Event()+ release_first = threading.Event()+ second_started = threading.Event()++ def _blocking_compression():+ first_started.set()+ release_first.wait(timeout=5.0)+ return "first"++ def _queued_compression():+ second_started.set()+ return "second"++ async def _drive():+ first_task = asyncio.create_task(+ proxy._run_compression_in_executor(_blocking_compression, timeout=10.0)+ )+ for _ in range(50):+ if first_started.is_set():+ break+ await asyncio.sleep(0.01)+ assert first_started.is_set()++ with pytest.raises(asyncio.TimeoutError):+ await proxy._run_compression_in_executor(_queued_compression, timeout=0.05)++ with proxy._compression_metrics_lock:+ mid_queued = proxy._compression_queued+ mid_in_flight = proxy._compression_in_flight+ queue_timeouts = proxy._compression_queue_timeouts++ release_first.set()+ assert await first_task == "first"+ return mid_queued, mid_in_flight, queue_timeouts++ mid_queued, mid_in_flight, queue_timeouts = asyncio.run(_drive())++ assert not second_started.is_set()+ assert mid_queued == 0+ assert mid_in_flight == 1+ assert queue_timeouts == 1+ with proxy._compression_metrics_lock:+ assert proxy._compression_queued == 0+ assert proxy._compression_in_flight == 0+ assert proxy._compression_leaked_threads == 0++def test_compression_executor_metrics_appear_in_runtime_payload() -> None:"""``/stats runtime.compression_executor`` surfaces the new gauges."""from fastapi.testclient import TestClient@@ -232,7 +285,12 @@ def test_compression_executor_metrics_appear_in_runtime_payload() -> None:assert "compression_executor" in runtimece = runtime["compression_executor"]assert ce["max_workers"] == 5+ assert ce["queued"] == 0+ assert ce["running"] == 0assert ce["in_flight"] == 0+ assert ce["queue_timeouts_total"] == 0+ assert ce["queue_wait_seconds_total"] == 0.0+ assert ce["run_seconds_total"] == 0.0assert ce["leaked_threads_total"] == 0assert ce["source"] == "explicit"diff --git a/tests/test_proxy_dashboard_stats_cache.py b/tests/test_proxy_dashboard_stats_cache.pyindex d9d970615..e4c0fc467 100644--- a/tests/test_proxy_dashboard_stats_cache.py+++ b/tests/test_proxy_dashboard_stats_cache.py@@ -36,7 +36,16 @@ def _reset_rtk_stats_cache(monkeypatch: pytest.MonkeyPatch) -> None:{"expires_at": 0.0, "has_value": False, "tool": None, "value": None})proxy_helpers._rtk_session_baseline.update(- {"initialized": False, "tool": None, "total_commands": 0, "tokens_saved": 0}+ {+ "initialized": False,+ "tool": None,+ "total_commands": 0,+ "input_tokens": 0,+ "output_tokens": 0,+ "tokens_saved": 0,+ "total_time_ms": 0,+ "captured_at": 0.0,+ })@@ -45,8 +54,22 @@ def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatchnow = {"value": 100.0}calls = {"run": 0}totals = [- {"total_commands": 7, "total_saved": 1234},- {"total_commands": 9, "total_saved": 1500},+ {+ "total_commands": 7,+ "total_input": 2000,+ "total_output": 766,+ "total_saved": 1234,+ "avg_savings_pct": 61.7,+ "total_time_ms": 700,+ },+ {+ "total_commands": 9,+ "total_input": 2600,+ "total_output": 1100,+ "total_saved": 1500,+ "avg_savings_pct": 57.69,+ "total_time_ms": 1000,+ },]def _fake_run(*args, **kwargs):@@ -65,26 +88,57 @@ def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatchsecond = proxy_helpers._get_rtk_stats()assert first == second- assert first == {- "tool": "rtk",- "label": "RTK",- "installed": True,- "total_commands": 0,- "tokens_saved": 0,- "avg_savings_pct": 0.0,- }+ assert first["tool"] == "rtk"+ assert first["label"] == "RTK"+ assert first["installed"] is True+ assert first["total_commands"] == 0+ assert first["input_tokens"] == 0+ assert first["output_tokens"] == 0+ assert first["tokens_saved"] == 0+ assert first["session_savings_pct"] is None+ assert first["avg_savings_pct"] == 61.7+ assert first["avg_savings_pct_scope"] == "lifetime"+ assert first["lifetime_total_commands"] == 7+ assert first["lifetime_input_tokens"] == 2000+ assert first["lifetime_output_tokens"] == 766+ assert first["lifetime_tokens_saved"] == 1234+ assert first["session_baseline_total_commands"] == 7+ assert first["session_baseline_input_tokens"] == 2000+ assert first["session_baseline_output_tokens"] == 766+ assert first["session_baseline_tokens_saved"] == 1234+ assert first["session"]["tokens_saved"] == 0+ assert first["lifetime"]["savings_pct"] == 61.7+ assert first["sample_ttl_seconds"] == proxy_helpers.CONTEXT_TOOL_STATS_CACHE_TTL_SECONDSassert calls["run"] == 1now["value"] += proxy_helpers.RTK_STATS_CACHE_TTL_SECONDS + 0.1third = proxy_helpers._get_rtk_stats()- assert third == {- "tool": "rtk",- "label": "RTK",- "installed": True,- "total_commands": 2,+ assert third["tool"] == "rtk"+ assert third["label"] == "RTK"+ assert third["installed"] is True+ assert third["total_commands"] == 2+ assert third["input_tokens"] == 600+ assert third["output_tokens"] == 334+ assert third["tokens_saved"] == 266+ assert third["session_savings_pct"] == pytest.approx(44.3333)+ assert third["session_avg_time_ms"] == 150.0+ assert third["lifetime_total_commands"] == 9+ assert third["lifetime_input_tokens"] == 2600+ assert third["lifetime_output_tokens"] == 1100+ assert third["lifetime_tokens_saved"] == 1500+ assert third["session_baseline_total_commands"] == 7+ assert third["session_baseline_input_tokens"] == 2000+ assert third["session_baseline_output_tokens"] == 766+ assert third["session_baseline_tokens_saved"] == 1234+ assert third["session"] == {+ "commands": 2,+ "input_tokens": 600,+ "output_tokens": 334,"tokens_saved": 266,- "avg_savings_pct": 0.0,+ "savings_pct": pytest.approx(44.3333),+ "total_time_ms": 300,+ "avg_time_ms": 150.0,}assert calls["run"] == 2@@ -94,8 +148,20 @@ def test_get_context_tool_stats_reads_lean_ctx_gain(monkeypatch: pytest.MonkeyPanow = {"value": 100.0}calls = {"run": 0}totals = [- {"total_commands": 3, "tokens_saved": 400, "avg_savings_pct": 12.5},- {"total_commands": 5, "tokens_saved": 475, "avg_savings_pct": 15.0},+ {+ "total_commands": 3,+ "total_input_tokens": 1000,+ "total_output_tokens": 600,+ "tokens_saved": 400,+ "avg_savings_pct": 40.0,+ },+ {+ "total_commands": 5,+ "total_input_tokens": 1250,+ "total_output_tokens": 775,+ "tokens_saved": 475,+ "avg_savings_pct": 38.0,+ },]def _fake_run(args, **kwargs):@@ -115,27 +181,35 @@ def test_get_context_tool_stats_reads_lean_ctx_gain(monkeypatch: pytest.MonkeyPasecond = proxy_helpers._get_context_tool_stats()assert first == second- assert first == {- "tool": "lean-ctx",- "label": "lean-ctx",- "installed": True,- "total_commands": 0,- "tokens_saved": 0,- "avg_savings_pct": 12.5,- }+ assert first["tool"] == "lean-ctx"+ assert first["label"] == "lean-ctx"+ assert first["installed"] is True+ assert first["total_commands"] == 0+ assert first["tokens_saved"] == 0+ assert first["avg_savings_pct"] == 40.0+ assert first["session_savings_pct"] is None+ assert first["lifetime_total_commands"] == 3+ assert first["lifetime_input_tokens"] == 1000+ assert first["lifetime_output_tokens"] == 600+ assert first["lifetime_tokens_saved"] == 400assert calls["run"] == 1now["value"] += proxy_helpers.CONTEXT_TOOL_STATS_CACHE_TTL_SECONDS + 0.1third = proxy_helpers._get_context_tool_stats()- assert third == {- "tool": "lean-ctx",- "label": "lean-ctx",- "installed": True,- "total_commands": 2,- "tokens_saved": 75,- "avg_savings_pct": 15.0,- }+ assert third["tool"] == "lean-ctx"+ assert third["label"] == "lean-ctx"+ assert third["installed"] is True+ assert third["total_commands"] == 2+ assert third["input_tokens"] == 250+ assert third["output_tokens"] == 175+ assert third["tokens_saved"] == 75+ assert third["avg_savings_pct"] == 38.0+ assert third["avg_savings_pct_scope"] == "lifetime"+ assert third["session_savings_pct"] == 30.0+ assert third["lifetime_total_commands"] == 5+ assert third["lifetime_tokens_saved"] == 475+ assert third["session"]["savings_pct"] == 30.0assert calls["run"] == 2diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.pyindex bea4fa735..8ee570979 100644--- a/tests/test_transforms_content_router.py+++ b/tests/test_transforms_content_router.py@@ -302,6 +302,62 @@ def test_content_router_mixed_pure_apply_and_toin(monkeypatch: pytest.MonkeyPatcassert len(calls) == 1+def test_diff_strategy_does_not_fallback_to_kompress_when_diff_is_noop(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ router = ContentRouter()+ diff = "diff --git a/a.txt b/a.txt\n--- a/a.txt\n+++ b/a.txt\n@@ -1 +1 @@\n-a\n+a"++ class NoopDiffCompressor:+ def compress(self, content: str, context: str = "") -> SimpleNamespace:+ return SimpleNamespace(compressed=content)++ monkeypatch.setattr(router, "_get_diff_compressor", lambda: NoopDiffCompressor())++ def fail_kompress(*_args: object, **_kwargs: object) -> tuple[str, int]:+ raise AssertionError("Diff compression must not fallback to Kompress")++ monkeypatch.setattr(router, "_try_ml_compressor", fail_kompress)++ compressed, compressed_tokens, strategy_chain = router._apply_strategy_to_content(+ diff,+ CompressionStrategy.DIFF,+ context="",+ )++ assert compressed == diff+ assert compressed_tokens == len(diff.split())+ assert strategy_chain == ["diff"]+++def test_log_strategy_does_not_fallback_to_kompress_when_log_is_noop(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ router = ContentRouter()+ log = "ERROR one\nERROR two\nERROR three"++ class NoopLogCompressor:+ def compress(self, content: str, bias: float = 1.0) -> SimpleNamespace:+ return SimpleNamespace(compressed=content)++ monkeypatch.setattr(router, "_get_log_compressor", lambda: NoopLogCompressor())++ def fail_kompress(*_args: object, **_kwargs: object) -> tuple[str, int]:+ raise AssertionError("Log compression must not fallback to Kompress")++ monkeypatch.setattr(router, "_try_ml_compressor", fail_kompress)++ compressed, compressed_tokens, strategy_chain = router._apply_strategy_to_content(+ log,+ CompressionStrategy.LOG,+ context="",+ )++ assert compressed == log+ assert compressed_tokens == len(log.split())+ assert strategy_chain == ["log"]++# ---------------------------------------------------------------------------# Cache-safety tests for _process_content_blocks. These pin down the# block-level invariants that protect upstream prefix caches: