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
refactor(proxy): migrate Gemini + Anthropic non-streaming onto outcome funnel
chopratejas7aca00445e23
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 4f66f1fd2..8df17f320 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -25,6 +25,7 @@ import httpxfrom headroom.pipeline import PipelineStage, summarize_routing_markersfrom headroom.proxy.auth_mode import classify_auth_mode+from headroom.proxy.outcome import RequestOutcomelogger = logging.getLogger("headroom.proxy")@@ -352,7 +353,6 @@ class AnthropicHandlerMixin:from headroom.cache.compression_store import get_compression_storefrom headroom.ccr import CCRToolInjector- from headroom.proxy.cost import _summarize_transformsfrom headroom.proxy.helpers import (MAX_MESSAGE_ARRAY_LENGTH,MAX_REQUEST_BODY_SIZE,@@ -361,7 +361,6 @@ class AnthropicHandlerMixin:compute_turn_id,read_request_json_with_bytes,)- from headroom.proxy.models import RequestLogfrom headroom.proxy.modes import is_cache_mode, is_token_modefrom headroom.tokenizers import get_tokenizerfrom headroom.utils import extract_user_query@@ -700,14 +699,28 @@ class AnthropicHandlerMixin:)optimization_latency = (time.time() - start_time) * 1000- await self.metrics.record_request(- provider="anthropic",- model=model,- input_tokens=0,- output_tokens=0,- tokens_saved=0, # Savings already counted when response was cached- latency_ms=optimization_latency,- cached=True,+ # Response-cache hit: response body came from+ # Headroom's semantic cache, not the upstream+ # provider. ``from_response_cache=True`` is a+ # distinct signal from `cache_read_tokens > 0`+ # (which means upstream-prompt-cache hit). Dashboards+ # can split the two; the funnel collapses them into+ # the single `cached` boolean for Prometheus.+ await self._record_request_outcome(+ RequestOutcome(+ request_id=request_id,+ provider="anthropic",+ model=model,+ original_tokens=0,+ optimized_tokens=0,+ output_tokens=0,+ tokens_saved=0,+ attempted_input_tokens=0,+ from_response_cache=True,+ total_latency_ms=optimization_latency,+ overhead_ms=optimization_latency,+ num_messages=len(messages),+ ))# Remove compression headers from cached response@@ -1610,50 +1623,36 @@ class AnthropicHandlerMixin:)except Exception:attempted_input_tokens = original_tokens- await self.metrics.record_request(- provider=_backend_name,- model=model,- input_tokens=optimized_tokens,- output_tokens=output_tokens,- tokens_saved=tokens_saved,- latency_ms=total_latency,- cached=False,- overhead_ms=optimization_latency,- pipeline_timing=pipeline_timing,- attempted_input_tokens=attempted_input_tokens,- )-- if self.cost_tracker:- self.cost_tracker.record_tokens(model, tokens_saved, optimized_tokens)-- # Log request- if self.logger:- self.logger.log(- RequestLog(- request_id=request_id,- timestamp=datetime.now().isoformat(),- provider=_backend_name,- model=model,- input_tokens_original=original_tokens,- input_tokens_optimized=optimized_tokens,- output_tokens=output_tokens,- tokens_saved=tokens_saved,- savings_percent=(tokens_saved / original_tokens * 100)- if original_tokens > 0- else 0,- optimization_latency_ms=optimization_latency,- total_latency_ms=total_latency,- tags=tags,- cache_hit=False,- transforms_applied=transforms_applied,- request_messages=body.get("messages")- if self.config.log_full_messages- else None,- turn_id=compute_turn_id(- model, body.get("system"), body.get("messages")- ),- )+ # Backend (Bedrock / Vertex) non-streaming.+ # Cache metrics aren't extracted from the backend+ # response here yet — that's a follow-up. The+ # funnel passes 0s for the cache fields, which+ # is the same observable behaviour as the+ # pre-refactor code (which also omitted them).+ await self._record_request_outcome(+ RequestOutcome(+ request_id=request_id,+ provider=_backend_name,+ model=model,+ original_tokens=original_tokens,+ optimized_tokens=optimized_tokens,+ output_tokens=output_tokens,+ tokens_saved=tokens_saved,+ attempted_input_tokens=attempted_input_tokens,+ total_latency_ms=total_latency,+ overhead_ms=optimization_latency,+ pipeline_timing=pipeline_timing,+ transforms_applied=tuple(transforms_applied),+ num_messages=len(body.get("messages", [])),+ tags=tags,+ turn_id=compute_turn_id(+ model, body.get("system"), body.get("messages")+ ),+ request_messages=body.get("messages")+ if self.config.log_full_messages+ else None,)+ )return JSONResponse(status_code=backend_response.status_code,@@ -2087,18 +2086,6 @@ class AnthropicHandlerMixin:original_messages=next_original_messages,)- if self.cost_tracker:- self.cost_tracker.record_tokens(- model,- tokens_saved,- optimized_tokens,- cache_read_tokens=cr_tokens,- cache_write_tokens=cw_tokens,- cache_write_5m_tokens=cw_5m_tokens,- cache_write_1h_tokens=cw_1h_tokens,- uncached_tokens=uncached_input_tokens,- )-# Cache responseif self.cache and response.status_code == 200:await self.cache.set(@@ -2109,26 +2096,10 @@ class AnthropicHandlerMixin:tokens_saved=tokens_saved,)- # Record metrics — use optimized_tokens (what we sent), not API's- # input_tokens which is just the non-cached portion with prompt caching- await self.metrics.record_request(- provider="anthropic",- model=model,- input_tokens=optimized_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=cr_tokens,- cache_write_tokens=cw_tokens,- cache_write_5m_tokens=cw_5m_tokens,- cache_write_1h_tokens=cw_1h_tokens,- uncached_input_tokens=uncached_input_tokens,- )-- # Subscription tracker: update headroom contribution counters+ # Subscription tracker: update headroom contribution+ # counters. Provider-specific OAuth/subscription+ # accounting — stays outside the funnel (different+ # concern, only fires for Bearer-not-sk-ant tokens).if _auth_header.startswith("Bearer ") and not _auth_header.startswith("Bearer sk-ant-api"):@@ -2144,56 +2115,53 @@ class AnthropicHandlerMixin:tokens_saved_cache_reads=cr_tokens,)- # Log request- if self.logger:- self.logger.log(- RequestLog(- request_id=request_id,- timestamp=datetime.now().isoformat(),- provider="anthropic",- model=model,- input_tokens_original=original_tokens,- input_tokens_optimized=optimized_tokens,- output_tokens=output_tokens,- tokens_saved=tokens_saved,- savings_percent=(tokens_saved / original_tokens * 100)- if original_tokens > 0- else 0,- optimization_latency_ms=optimization_latency,- total_latency_ms=total_latency,- tags=tags,- cache_hit=cache_hit,- transforms_applied=transforms_applied,- waste_signals=waste_signals_dict,- request_messages=messages- if self.config.log_full_messages- else None,- turn_id=compute_turn_id(- model, body.get("system"), body.get("messages")- ),- )+ # The pre-refactor PERF emit (above) read raw usage+ # off ``resp_usage`` instead of trusting cr_tokens /+ # cw_tokens. Both paths land on identical numbers+ # (extraction happens just above the cost_tracker+ # call), so the funnel uses the already-computed+ # values for consistency. Pre-refactor's+ # ``cache_hit`` local was correctly derived from+ # cache_read>0; the funnel re-derives via the+ # outcome property — same result.+ #+ # ``attempted_input_tokens`` was MISSING from the+ # pre-refactor record_request call here (one of the+ # 7-of-18 sites the P0 audit flagged). The funnel+ # forces it to a value — using+ # ``optimized_tokens + tokens_saved`` as the+ # fallback denominator, same as the streaming path+ # uses (see _finalize_stream_response). Dashboards+ # that were showing 0% active-savings on non-+ # streaming Anthropic traffic will now show the+ # correct ratio.+ await self._record_request_outcome(+ RequestOutcome(+ request_id=request_id,+ provider="anthropic",+ model=model,+ original_tokens=original_tokens,+ optimized_tokens=optimized_tokens,+ output_tokens=output_tokens,+ tokens_saved=tokens_saved,+ attempted_input_tokens=optimized_tokens + tokens_saved,+ cache_read_tokens=cr_tokens,+ cache_write_tokens=cw_tokens,+ cache_write_5m_tokens=cw_5m_tokens,+ cache_write_1h_tokens=cw_1h_tokens,+ uncached_input_tokens=uncached_input_tokens,+ total_latency_ms=total_latency,+ overhead_ms=optimization_latency,+ pipeline_timing=pipeline_timing,+ waste_signals=waste_signals_dict,+ transforms_applied=tuple(transforms_applied),+ num_messages=len(messages),+ tags=tags,+ turn_id=compute_turn_id(+ model, body.get("system"), body.get("messages")+ ),+ request_messages=messages if self.config.log_full_messages else None,)-- # Structured perf log line for `headroom perf` analysis- num_msgs = len(messages)- resp_usage = resp_json.get("usage", {}) if resp_json else {}- cr = resp_usage.get("cache_read_input_tokens", 0)- cw = resp_usage.get("cache_creation_input_tokens", 0)- chp = round(cr / (cr + cw) * 100) if (cr + cw) > 0 else 0- timing_str = (- " ".join(f"{k}={v:.0f}ms" for k, v in pipeline_timing.items())- if pipeline_timing- else ""- )- logger.info(- f"[{request_id}] PERF "- f"model={model} msgs={num_msgs} "- f"tok_before={original_tokens} tok_after={optimized_tokens} "- f"tok_saved={tokens_saved} "- f"cache_read={cr} cache_write={cw} cache_hit_pct={chp} "- f"opt_ms={optimization_latency:.0f} "- f"transforms={_summarize_transforms(transforms_applied)}"- f"{' timing=' + timing_str if timing_str else ''}")# Remove compression headers since httpx already decompressed the response@@ -2509,16 +2477,27 @@ class AnthropicHandlerMixin:path_for_log="/v1/messages/batches",)- # Record metrics- await self.metrics.record_request(- provider="anthropic",- model="batch",- input_tokens=total_optimized_tokens,- output_tokens=0,- tokens_saved=total_tokens_saved,- latency_ms=optimization_latency,- overhead_ms=optimization_latency,- pipeline_timing=pipeline_timing,+ # Batch create: tokens accumulated across all requests in+ # the batch. The funnel records it as a single observation+ # under the synthetic model name "batch" — same as+ # pre-refactor, just routed through the canonical path so+ # batch traffic appears in RequestLog + PERF (it didn't+ # before — sites 4/5/6 were "metrics-only").+ await self._record_request_outcome(+ RequestOutcome(+ request_id=request_id,+ provider="anthropic",+ model="batch",+ original_tokens=total_original_tokens,+ optimized_tokens=total_optimized_tokens,+ output_tokens=0,+ tokens_saved=total_tokens_saved,+ attempted_input_tokens=total_optimized_tokens + total_tokens_saved,+ total_latency_ms=optimization_latency,+ overhead_ms=optimization_latency,+ pipeline_timing=pipeline_timing,+ num_messages=len(compressed_requests),+ ))# Log compression stats@@ -2588,6 +2567,7 @@ class AnthropicHandlerMixin:"""from fastapi.responses import Response+ request_id = await self._next_request_id()start_time = time.time()path = request.url.pathurl = f"{self.ANTHROPIC_API_URL}{path}"@@ -2618,15 +2598,22 @@ class AnthropicHandlerMixin:content=body,)- # Track metrics+ # Batch passthrough: no compression, no transforms — but we+ # still record the request so dashboards see the upstream call+ # happened. Same funnel as the other 5 anthropic sites.latency_ms = (time.time() - start_time) * 1000- await self.metrics.record_request(- provider="anthropic",- model="passthrough:batches",- input_tokens=0,- output_tokens=0,- tokens_saved=0,- latency_ms=latency_ms,+ await self._record_request_outcome(+ RequestOutcome(+ request_id=request_id,+ provider="anthropic",+ model="passthrough:batches",+ original_tokens=0,+ optimized_tokens=0,+ output_tokens=0,+ tokens_saved=0,+ attempted_input_tokens=0,+ total_latency_ms=latency_ms,+ ))# Remove compression headers@@ -2699,6 +2686,7 @@ class AnthropicHandlerMixin:from headroom.ccr import BatchResultProcessor, get_batch_context_store+ request_id = await self._next_request_id()start_time = time.time()# Forward request to get raw results@@ -2785,15 +2773,22 @@ class AnthropicHandlerMixin:processed_content = "\n".join(processed_lines)- # Track metrics+ # Batch results, post-CCR processing. Like the other batch+ # sites, no token accounting but we record the request so it's+ # visible in dashboards + headroom perf.latency_ms = (time.time() - start_time) * 1000- await self.metrics.record_request(- provider="anthropic",- model="batch:ccr-processed",- input_tokens=0,- output_tokens=0,- tokens_saved=0,- latency_ms=latency_ms,+ await self._record_request_outcome(+ RequestOutcome(+ request_id=request_id,+ provider="anthropic",+ model="batch:ccr-processed",+ original_tokens=0,+ optimized_tokens=0,+ output_tokens=0,+ tokens_saved=0,+ attempted_input_tokens=0,+ total_latency_ms=latency_ms,+ ))return Response(diff --git a/headroom/proxy/handlers/gemini.py b/headroom/proxy/handlers/gemini.pyindex 1da75635a..b02ec82a6 100644--- a/headroom/proxy/handlers/gemini.py+++ b/headroom/proxy/handlers/gemini.py@@ -15,6 +15,8 @@ if TYPE_CHECKING:from fastapi import Requestfrom fastapi.responses import JSONResponse, Response, StreamingResponse+from headroom.proxy.outcome import RequestOutcome+logger = logging.getLogger("headroom.proxy")DEFAULT_CLOUDCODE_API_URL = "https://cloudcode-pa.googleapis.com"@@ -466,35 +468,39 @@ class GeminiHandlerMixin: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,- )-# Eligible-tracking is TODO for Gemini; pass the full# pre-compression request size as the fallback denominator.# This makes Gemini's contribution to the aggregate# active_savings_percent equal its whole-request ratio —# not ideal but coherent until per-part live-zone# tracking exists for this provider.- attempted_input_tokens = total_input_tokens + tokens_saved- await self.metrics.record_request(+ #+ # Gemini reports read-side context-cache only via+ # ``cachedContentTokenCount``. There is no write counter+ # in the Gemini response; cache writes happen out-of-band+ # via the explicit Cache API. cache_write_* fields on the+ # outcome stay at their 0 defaults — the dataclass+ # handles "this provider doesn't have this concept"+ # without per-handler conditionals.+ outcome = RequestOutcome(+ request_id=request_id,provider="gemini",model=model,- input_tokens=total_input_tokens,+ original_tokens=original_tokens,+ optimized_tokens=total_input_tokens,output_tokens=output_tokens,tokens_saved=tokens_saved,- latency_ms=total_latency,- overhead_ms=optimization_latency,- waste_signals=waste_signals_dict,+ attempted_input_tokens=total_input_tokens + tokens_saved,cache_read_tokens=cache_read_tokens,uncached_input_tokens=uncached_input_tokens,- attempted_input_tokens=attempted_input_tokens,+ total_latency_ms=total_latency,+ overhead_ms=optimization_latency,+ waste_signals=waste_signals_dict,+ transforms_applied=tuple(transforms_applied),+ num_messages=len(body.get("contents", [])),+ tags=tags or {},)+ await self._record_request_outcome(outcome)if tokens_saved > 0:logger.info(@@ -902,15 +908,22 @@ class GeminiHandlerMixin:# Fallback denominator (see comment on the main gemini# record_request site) — pre-comp request size.- attempted_input_tokens = compressed_tokens + tokens_saved- await self.metrics.record_request(- provider="gemini",- model=model,- input_tokens=compressed_tokens,- output_tokens=0,- tokens_saved=tokens_saved,- latency_ms=total_latency,- attempted_input_tokens=attempted_input_tokens,+ # countTokens is a sizing helper; it never generates output+ # tokens and never touches cache. The funnel handles the+ # "nothing to report" shape with all-zero cache defaults.+ await self._record_request_outcome(+ RequestOutcome(+ request_id=request_id,+ provider="gemini",+ model=model,+ original_tokens=original_tokens,+ optimized_tokens=compressed_tokens,+ output_tokens=0,+ tokens_saved=tokens_saved,+ attempted_input_tokens=compressed_tokens + tokens_saved,+ total_latency_ms=total_latency,+ transforms_applied=tuple(transforms_applied),+ ))if tokens_saved > 0:diff --git a/headroom/proxy/outcome.py b/headroom/proxy/outcome.pyindex afdfe20ab..a501c4c00 100644--- a/headroom/proxy/outcome.py+++ b/headroom/proxy/outcome.py@@ -7,9 +7,10 @@ disagreed on argument shape — 9 of 18 omitted ``cached=``, 7 of 18omitted ``attempted_input_tokens=``, only 4 sites emitted a structuredPERF log at all. This module is the structural fix: every handlerconverges on building a :class:`RequestOutcome` at end-of-request and-hands it to :meth:`HeadroomProxy._record_request_outcome`, which owns-the four downstream effects (Prometheus, cost tracker, request logger,-PERF log).+hands it to :func:`emit_request_outcome` (also exposed as+:meth:`HeadroomProxy._record_request_outcome`), which owns the four+downstream effects (Prometheus, cost tracker, request logger, PERF+log).Note: this is **output unification, not input unification**. ProviderAPIs (Anthropic ``/v1/messages``, OpenAI Responses WS, Gemini@@ -24,9 +25,13 @@ actually reports.from __future__ import annotations+import loggingfrom dataclasses import dataclass, field+from datetime import datetimefrom typing import Any+logger = logging.getLogger("headroom.proxy")+@dataclass(frozen=True)class RequestOutcome:@@ -75,6 +80,12 @@ class RequestOutcome:cache_write_1h_tokens: int = 0uncached_input_tokens: int = 0cache_inferred: bool = False+ # Response-cache hit (Headroom's own semantic cache served the+ # response from a prior call — completely distinct from+ # upstream-prompt-cache `cache_read_tokens`). True means the proxy+ # never reached the provider at all. Used to drive the+ # Prometheus ``cached`` counter and dashboard "response cache" row.+ from_response_cache: bool = False# ── Timing ────────────────────────────────────────────────────────# total_latency_ms: wall-clock end-to-end for this request@@ -111,13 +122,18 @@ class RequestOutcome:@propertydef cache_hit(self) -> bool:- """True iff upstream reported any cache read.+ """True iff EITHER upstream reported a cache read OR the response+ was served from Headroom's own response cache.++ Two distinct concepts collapsed into one observable boolean for+ downstream consumers (Prometheus ``cached`` counter, RequestLog+ ``cache_hit`` flag). The dataclass tracks them separately so+ dashboards can split them; the derived property unifies them.- Used by ``RequestLog.cache_hit`` and ``record_request(cached=...)``.Pre-refactor 9 of 18 sites hardcoded this to False — this propertymakes "I forgot to compute it" structurally impossible."""- return self.cache_read_tokens > 0+ return self.cache_read_tokens > 0 or self.from_response_cache@propertydef cache_hit_pct(self) -> int:@@ -144,3 +160,106 @@ class RequestOutcome:if self.original_tokens <= 0:return 0.0return self.tokens_saved / self.original_tokens * 100.0+++# ── The funnel ───────────────────────────────────────────────────────+++async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:+ """Single funnel for per-request bookkeeping. The contract.++ Owns the four downstream effects in canonical order:++ 1. ``handler.metrics.record_request(...)`` — Prometheus / SavingsTracker+ 2. ``handler.cost_tracker.record_tokens(...)`` — cost dashboard+ (skipped when cost_tracker is None, i.e. ``--no-cost``)+ 3. ``handler.logger.log(RequestLog(...))`` — per-request log feed+ (skipped when logger is None, i.e. ``--no-request-logging``)+ 4. structured PERF log line — consumed by ``headroom perf``++ Takes the handler as a free argument rather than ``self`` so this+ function is callable from:+ * ``HeadroomProxy._record_request_outcome`` (production)+ * any test dummy that has the three required attributes+ (``metrics``, ``cost_tracker``, optionally ``logger``)+ * any provider handler mixin++ The handler argument is structurally typed (duck-typed); no formal+ Protocol — the requirement is simply that ``handler.metrics`` exists+ and is awaitable-compatible. We could lift this to a typing.Protocol+ if/when another contract surface emerges, but YAGNI.+ """+ from headroom.proxy.cost import _summarize_transforms+ from headroom.proxy.models import RequestLog++ # 1. Prometheus / SavingsTracker.+ await handler.metrics.record_request(+ provider=outcome.provider,+ model=outcome.model,+ input_tokens=outcome.optimized_tokens,+ output_tokens=outcome.output_tokens,+ tokens_saved=outcome.tokens_saved,+ latency_ms=outcome.total_latency_ms,+ cached=outcome.cache_hit,+ overhead_ms=outcome.overhead_ms,+ ttfb_ms=outcome.ttfb_ms,+ pipeline_timing=outcome.pipeline_timing,+ waste_signals=outcome.waste_signals,+ cache_read_tokens=outcome.cache_read_tokens,+ cache_write_tokens=outcome.cache_write_tokens,+ cache_write_5m_tokens=outcome.cache_write_5m_tokens,+ cache_write_1h_tokens=outcome.cache_write_1h_tokens,+ uncached_input_tokens=outcome.uncached_input_tokens,+ attempted_input_tokens=outcome.attempted_input_tokens,+ )++ # 2. Cost tracker (optional).+ cost_tracker = getattr(handler, "cost_tracker", None)+ if cost_tracker is not None:+ cost_tracker.record_tokens(+ outcome.model,+ outcome.tokens_saved,+ outcome.optimized_tokens,+ cache_read_tokens=outcome.cache_read_tokens,+ cache_write_tokens=outcome.cache_write_tokens,+ cache_write_5m_tokens=outcome.cache_write_5m_tokens,+ cache_write_1h_tokens=outcome.cache_write_1h_tokens,+ uncached_tokens=outcome.uncached_input_tokens,+ )++ # 3. Per-request log (optional).+ request_logger = getattr(handler, "logger", None)+ if request_logger is not None:+ request_logger.log(+ RequestLog(+ request_id=outcome.request_id,+ timestamp=datetime.now().isoformat(),+ provider=outcome.provider,+ model=outcome.model,+ input_tokens_original=outcome.original_tokens,+ input_tokens_optimized=outcome.optimized_tokens,+ output_tokens=outcome.output_tokens,+ tokens_saved=outcome.tokens_saved,+ savings_percent=outcome.savings_pct,+ optimization_latency_ms=outcome.overhead_ms,+ total_latency_ms=outcome.total_latency_ms,+ tags=outcome.tags,+ cache_hit=outcome.cache_hit,+ transforms_applied=list(outcome.transforms_applied),+ waste_signals=outcome.waste_signals,+ request_messages=outcome.request_messages,+ turn_id=outcome.turn_id,+ )+ )++ # 4. Structured PERF log line.+ logger.info(+ f"[{outcome.request_id}] PERF "+ f"model={outcome.model} msgs={outcome.num_messages} "+ f"tok_before={outcome.original_tokens} tok_after={outcome.optimized_tokens} "+ f"tok_saved={outcome.tokens_saved} "+ f"cache_read={outcome.cache_read_tokens} cache_write={outcome.cache_write_tokens} "+ f"cache_hit_pct={outcome.cache_hit_pct} "+ f"opt_ms={outcome.overhead_ms:.0f} "+ f"transforms={_summarize_transforms(list(outcome.transforms_applied))}"+ )diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 2c6882eb6..41001a7ad 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -1153,93 +1153,19 @@ class HeadroomProxy(async def _record_request_outcome(self, outcome: RequestOutcome) -> None:"""Single funnel for per-request bookkeeping.- Replaces the divergent four-call sequence (``metrics.record_request``- + ``cost_tracker.record_tokens`` + ``logger.log(RequestLog(...))``- + structured PERF log) that pre-refactor lived inline at 18 sites- across four handler files with subtly different argument shapes.- Provider handlers build a :class:`RequestOutcome` from local- context and call here — the wire shape for metrics/log/PERF is- defined exactly once, in this method, and nowhere else.+ Thin wrapper around :func:`headroom.proxy.outcome.emit_request_outcome`+ so call sites can write ``await self._record_request_outcome(outcome)``+ (idiomatic) instead of ``await emit_request_outcome(self, outcome)``.+ The real implementation lives in ``outcome.py`` as a free function so+ test dummies and provider mixins can call it without inheriting from+ ``HeadroomProxy``.See ``docs/superpowers/specs/P0-proxy-pipeline-audit.md`` for thedivergence catalog this funnel collapses."""+ from headroom.proxy.outcome import emit_request_outcome- # 1. Prometheus / SavingsTracker.- await self.metrics.record_request(- provider=outcome.provider,- model=outcome.model,- input_tokens=outcome.optimized_tokens,- output_tokens=outcome.output_tokens,- tokens_saved=outcome.tokens_saved,- latency_ms=outcome.total_latency_ms,- cached=outcome.cache_hit,- overhead_ms=outcome.overhead_ms,- ttfb_ms=outcome.ttfb_ms,- pipeline_timing=outcome.pipeline_timing,- waste_signals=outcome.waste_signals,- cache_read_tokens=outcome.cache_read_tokens,- cache_write_tokens=outcome.cache_write_tokens,- cache_write_5m_tokens=outcome.cache_write_5m_tokens,- cache_write_1h_tokens=outcome.cache_write_1h_tokens,- uncached_input_tokens=outcome.uncached_input_tokens,- attempted_input_tokens=outcome.attempted_input_tokens,- )-- # 2. Cost tracker (optional — disabled when proxy --no-cost).- if self.cost_tracker:- self.cost_tracker.record_tokens(- outcome.model,- outcome.tokens_saved,- outcome.optimized_tokens,- cache_read_tokens=outcome.cache_read_tokens,- cache_write_tokens=outcome.cache_write_tokens,- cache_write_5m_tokens=outcome.cache_write_5m_tokens,- cache_write_1h_tokens=outcome.cache_write_1h_tokens,- uncached_tokens=outcome.uncached_input_tokens,- )-- # 3. Per-request log (optional — disabled when proxy- # --no-request-logging or when logger isn't installed).- request_logger = getattr(self, "logger", None)- if request_logger is not None:- request_logger.log(- RequestLog(- request_id=outcome.request_id,- timestamp=datetime.now().isoformat(),- provider=outcome.provider,- model=outcome.model,- input_tokens_original=outcome.original_tokens,- input_tokens_optimized=outcome.optimized_tokens,- output_tokens=outcome.output_tokens,- tokens_saved=outcome.tokens_saved,- savings_percent=outcome.savings_pct,- optimization_latency_ms=outcome.overhead_ms,- total_latency_ms=outcome.total_latency_ms,- tags=outcome.tags,- cache_hit=outcome.cache_hit,- transforms_applied=list(outcome.transforms_applied),- waste_signals=outcome.waste_signals,- request_messages=outcome.request_messages,- turn_id=outcome.turn_id,- )- )-- # 4. Structured PERF log — consumed by ``headroom perf``.- # Format frozen so the analyzer's key=value parser keeps- # working; future P3 work replaces the free-text shape with a- # structured event, at which point this becomes a presentation- # of the event rather than a parallel log line.- logger.info(- f"[{outcome.request_id}] PERF "- f"model={outcome.model} msgs={outcome.num_messages} "- f"tok_before={outcome.original_tokens} tok_after={outcome.optimized_tokens} "- f"tok_saved={outcome.tokens_saved} "- f"cache_read={outcome.cache_read_tokens} cache_write={outcome.cache_write_tokens} "- f"cache_hit_pct={outcome.cache_hit_pct} "- f"opt_ms={outcome.overhead_ms:.0f} "- f"transforms={_summarize_transforms(list(outcome.transforms_applied))}"- )+ await emit_request_outcome(self, outcome)async def _next_request_id(self) -> str:"""Generate unique request ID."""diff --git a/tests/test_anthropic_pre_upstream_backpressure.py b/tests/test_anthropic_pre_upstream_backpressure.pyindex bd198cce7..8b1496118 100644--- a/tests/test_anthropic_pre_upstream_backpressure.py+++ b/tests/test_anthropic_pre_upstream_backpressure.py@@ -215,6 +215,14 @@ class _DummyAnthropicHandler(AnthropicHandlerMixin):future = loop.run_in_executor(self._compression_executor, _wrapped)return await asyncio.wait_for(future, timeout=timeout)+ async def _record_request_outcome(self, outcome) -> None: # noqa: ANN001+ # Mirror of ``HeadroomProxy._record_request_outcome`` for the+ # mixin tests. Delegates to the free function in ``outcome.py``+ # so the wire shape is identical to production.+ from headroom.proxy.outcome import emit_request_outcome++ await emit_request_outcome(self, outcome)+async def _next_request_id(self) -> str:# Unique IDs so log assertions remain disambiguated under parallelism.return f"req-{id(object()):x}"