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): introduce RequestOutcome funnel; collapse 3 streaming finalizers
chopratejase898f68b89fc
diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.pyindex fc0cacd30..72e274096 100644--- a/headroom/proxy/handlers/streaming.py+++ b/headroom/proxy/handlers/streaming.py@@ -10,7 +10,6 @@ import contextlibimport jsonimport loggingimport time-from datetime import datetimefrom typing import TYPE_CHECKING, Anyfrom headroom.proxy.helpers import compute_turn_id, jitter_delay_ms@@ -585,7 +584,7 @@ class StreamingMixin:full_sse_data: str = "",parsed_response: dict[str, Any] | None = None,) -> None:- from headroom.proxy.cost import _summarize_transforms+ from headroom.proxy.outcome import RequestOutcometotal_latency = (time.time() - start_time) * 1000@@ -647,23 +646,9 @@ class StreamingMixin:effective_optimized_tokens - cache_read_tokens - cache_write_tokens, 0)- num_msgs = len(body.get("messages", []))- cache_hit_pct = (- round(cache_read_tokens / (cache_read_tokens + cache_write_tokens) * 100)- if (cache_read_tokens + cache_write_tokens) > 0- else 0- )- logger.info(- f"[{request_id}] PERF "- f"model={model} msgs={num_msgs} "- f"tok_before={effective_original_tokens} tok_after={effective_optimized_tokens} "- f"tok_saved={tokens_saved} "- f"cache_read={cache_read_tokens} cache_write={cache_write_tokens} "- f"cache_hit_pct={cache_hit_pct} "- f"opt_ms={optimization_latency:.0f} "- f"transforms={_summarize_transforms(transforms_applied)}"- )-+ # Prefix-tracker mutation is provider-specific state that lives+ # outside the metric funnel. Run it before the funnel so the next+ # request inherits correct prefix state regardless of metric path.if prefix_tracker is not None:import copy as _copy@@ -690,76 +675,40 @@ class StreamingMixin:original_messages=next_original,)- if self.cost_tracker:- self.cost_tracker.record_tokens(- model,- tokens_saved,- effective_optimized_tokens,- cache_read_tokens=cache_read_tokens,- cache_write_tokens=cache_write_tokens,- cache_write_5m_tokens=cache_write_5m_tokens,- cache_write_1h_tokens=cache_write_1h_tokens,- uncached_tokens=uncached_input_tokens,- )+ # Active-compression denominator. No frozen_message_count is+ # propagated to the streaming finalizer yet, so we fall back to+ # the pre-comp request size (effective_optimized + tokens_saved).+ # Per-message live-zone tracking is a follow-up; without this+ # fallback the dashboard headline collapses to 0% for streaming+ # traffic even though compression is happening (issue #455).+ attempted_input_tokens = effective_optimized_tokens + tokens_saved- if getattr(self, "metrics", None) is not None:- # Active-compression denominator. No frozen_message_count is- # propagated to the streaming finalizer yet, so we fall- # back to the pre-comp request size (effective_optimized +- # tokens_saved). Per-message live-zone tracking is a- # follow-up; without this fallback the dashboard headline- # collapses to 0% for streaming traffic even though- # compression is happening (issue #455).- attempted_input_tokens = effective_optimized_tokens + tokens_saved- await self.metrics.record_request(- provider=provider,- model=model,- input_tokens=effective_optimized_tokens,- output_tokens=output_tokens,- tokens_saved=tokens_saved,- latency_ms=total_latency,- overhead_ms=optimization_latency,- ttfb_ms=stream_state["ttfb_ms"] or total_latency,- pipeline_timing=pipeline_timing,- cache_read_tokens=cache_read_tokens,- cache_write_tokens=cache_write_tokens,- cache_write_5m_tokens=cache_write_5m_tokens,- cache_write_1h_tokens=cache_write_1h_tokens,- uncached_input_tokens=uncached_input_tokens,- attempted_input_tokens=attempted_input_tokens,- )-- # Log the request to the in-memory request logger so it shows up in- # /stats `recent_requests` and `/transformations/feed`. Without this- # the streaming Anthropic path (which is what Claude Code uses) is- # invisible to both surfaces — only Bedrock streaming and the- # non-streaming Anthropic path were logged previously.- if getattr(self, "logger", None) is not None:- from headroom.proxy.models import RequestLog-- self.logger.log(- RequestLog(- request_id=request_id,- timestamp=datetime.now().isoformat(),- provider=provider,- model=model,- input_tokens_original=effective_original_tokens,- input_tokens_optimized=effective_optimized_tokens,- output_tokens=output_tokens,- tokens_saved=tokens_saved,- savings_percent=(tokens_saved / effective_original_tokens * 100)- if effective_original_tokens > 0- else 0,- optimization_latency_ms=optimization_latency,- total_latency_ms=total_latency,- tags=tags or {},- cache_hit=False,- transforms_applied=transforms_applied,- request_messages=body.get("messages")- if getattr(self.config, "log_full_messages", False)- else None,- )- )+ outcome = RequestOutcome(+ request_id=request_id,+ provider=provider,+ model=model,+ original_tokens=effective_original_tokens,+ optimized_tokens=effective_optimized_tokens,+ output_tokens=output_tokens,+ tokens_saved=tokens_saved,+ attempted_input_tokens=attempted_input_tokens,+ cache_read_tokens=cache_read_tokens,+ cache_write_tokens=cache_write_tokens,+ cache_write_5m_tokens=cache_write_5m_tokens,+ cache_write_1h_tokens=cache_write_1h_tokens,+ uncached_input_tokens=uncached_input_tokens,+ total_latency_ms=total_latency,+ overhead_ms=optimization_latency,+ ttfb_ms=stream_state["ttfb_ms"] or total_latency,+ pipeline_timing=pipeline_timing,+ transforms_applied=tuple(transforms_applied),+ num_messages=len(body.get("messages", [])),+ tags=tags or {},+ request_messages=body.get("messages")+ if getattr(self.config, "log_full_messages", False)+ else None,+ )+ await self._record_request_outcome(outcome)async def _stream_response(self,@@ -1298,8 +1247,7 @@ class StreamingMixin:"""from fastapi.responses import StreamingResponse- from headroom.proxy.cost import _summarize_transforms- from headroom.proxy.models import RequestLog+ from headroom.proxy.outcome import RequestOutcomestart_time = time.time()@@ -1367,19 +1315,7 @@ class StreamingMixin:yield f"event: error\ndata: {json.dumps(error_event)}\n\n".encode()finally:- # Record metricstotal_latency = (time.time() - start_time) * 1000- output_tokens = stream_state["output_tokens"]- cache_read_tokens = stream_state["cache_read_input_tokens"]- cache_write_tokens = stream_state["cache_creation_input_tokens"]- cache_write_5m_tokens = stream_state["cache_creation_ephemeral_5m_input_tokens"]- cache_write_1h_tokens = stream_state["cache_creation_ephemeral_1h_input_tokens"]- cache_hit_pct = (- round(cache_read_tokens / (cache_read_tokens + cache_write_tokens) * 100)- if (cache_read_tokens + cache_write_tokens) > 0- else 0- )-_backend_name = (self.anthropic_backend.name if self.anthropic_backend else "anthropic")@@ -1387,73 +1323,32 @@ class StreamingMixin:# Bedrock streaming doesn't propagate frozen_message_count# here either; without this, attempted_input_tokens_total# stays 0 and the dashboard headline reads 0% (#455).- attempted_input_tokens = optimized_tokens + tokens_saved- await self.metrics.record_request(+ outcome = RequestOutcome(+ request_id=request_id,provider=_backend_name,model=model,- input_tokens=optimized_tokens,- output_tokens=output_tokens,+ original_tokens=original_tokens,+ optimized_tokens=optimized_tokens,+ output_tokens=stream_state["output_tokens"],tokens_saved=tokens_saved,- latency_ms=total_latency,- cached=cache_read_tokens > 0,+ attempted_input_tokens=optimized_tokens + tokens_saved,+ cache_read_tokens=stream_state["cache_read_input_tokens"],+ cache_write_tokens=stream_state["cache_creation_input_tokens"],+ cache_write_5m_tokens=stream_state["cache_creation_ephemeral_5m_input_tokens"],+ cache_write_1h_tokens=stream_state["cache_creation_ephemeral_1h_input_tokens"],+ total_latency_ms=total_latency,overhead_ms=optimization_latency,ttfb_ms=stream_state["ttfb_ms"] or 0,pipeline_timing=pipeline_timing,- attempted_input_tokens=attempted_input_tokens,- )-- if self.cost_tracker:- self.cost_tracker.record_tokens(- model,- tokens_saved,- optimized_tokens,- cache_read_tokens=cache_read_tokens,- cache_write_tokens=cache_write_tokens,- cache_write_5m_tokens=cache_write_5m_tokens,- cache_write_1h_tokens=cache_write_1h_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=cache_read_tokens > 0,- 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")- ),- )- )-- # Structured perf log line for `headroom perf` analysis- num_msgs = len(body.get("messages", []))- 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={cache_read_tokens} cache_write={cache_write_tokens} "- f"cache_hit_pct={cache_hit_pct} "- f"opt_ms={optimization_latency:.0f} "- f"transforms={_summarize_transforms(transforms_applied)}"+ transforms_applied=tuple(transforms_applied),+ num_messages=len(body.get("messages", [])),+ tags=tags or {},+ turn_id=compute_turn_id(model, body.get("system"), body.get("messages")),+ request_messages=body.get("messages")+ if getattr(self.config, "log_full_messages", False)+ else None,)+ await self._record_request_outcome(outcome)return StreamingResponse(generate(),@@ -1493,8 +1388,8 @@ class StreamingMixin:"""from fastapi.responses import StreamingResponse- from headroom.proxy.cost import _summarize_transformsfrom headroom.proxy.handlers.openai import _infer_openai_cache_write_tokens+ from headroom.proxy.outcome import RequestOutcomeassert self.anthropic_backend is not None@@ -1555,19 +1450,15 @@ class StreamingMixin:output_tokens = stream_state["output_tokens"] or 0cache_read_tokens = stream_state["cache_read_input_tokens"] or 0if upstream_input is None:- input_tokens = 0cache_write_tokens = 0uncached_input_tokens = 0- cache_hit_pct = 0+ cache_inferred = Falseelse:- input_tokens = upstream_inputcache_write_tokens = _infer_openai_cache_write_tokens(- input_tokens, cache_read_tokens- )- uncached_input_tokens = max(input_tokens - cache_read_tokens, 0)- cache_hit_pct = (- round(cache_read_tokens / input_tokens * 100) if input_tokens > 0 else 0+ upstream_input, cache_read_tokens)+ uncached_input_tokens = max(upstream_input - cache_read_tokens, 0)+ cache_inferred = Truetotal_latency = (time.time() - start_time) * 1000# Active-compression denominator for backend-routed@@ -1577,78 +1468,31 @@ class StreamingMixin:# comp request size. This keeps active_savings_percent# in sync with proxy_savings_percent for this provider# instead of collapsing the dashboard headline to 0%.- attempted_input_tokens = optimized_tokens + tokens_saved- await self.metrics.record_request(+ outcome = RequestOutcome(+ request_id=request_id,provider=self.anthropic_backend.name,model=model,- input_tokens=optimized_tokens,+ original_tokens=original_tokens,+ optimized_tokens=optimized_tokens,output_tokens=output_tokens,tokens_saved=tokens_saved,- latency_ms=total_latency,- cached=cache_read_tokens > 0,+ attempted_input_tokens=optimized_tokens + tokens_saved,+ cache_read_tokens=cache_read_tokens,+ cache_write_tokens=cache_write_tokens,+ uncached_input_tokens=uncached_input_tokens,+ cache_inferred=cache_inferred,+ total_latency_ms=total_latency,overhead_ms=optimization_latency,pipeline_timing=pipeline_timing,waste_signals=waste_signals,- attempted_input_tokens=attempted_input_tokens,- )-- if self.cost_tracker:- self.cost_tracker.record_tokens(- model,- tokens_saved,- optimized_tokens,- cache_read_tokens=cache_read_tokens,- cache_write_tokens=cache_write_tokens,- uncached_tokens=uncached_input_tokens,- )-- # Mirror the Anthropic-stream path: log to RequestLogger so- # /stats.recent_requests and /transformations/feed see this- # request. Without it the OpenAI-via-backend path is invisible.- if getattr(self, "logger", None) is not None:- from headroom.proxy.models import RequestLog-- self.logger.log(- RequestLog(- request_id=request_id,- timestamp=datetime.now().isoformat(),- provider=self.anthropic_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 or {},- cache_hit=cache_read_tokens > 0,- transforms_applied=transforms_applied,- waste_signals=waste_signals,- request_messages=body.get("messages")- if getattr(self.config, "log_full_messages", False)- else None,- )- )-- # Structured perf log line for `headroom perf` analysis.- # Missing this line is why issue #327 reported- # ``Cache write: 0`` on Azure-GPT/Codex backend-routed- # traffic: the entire request was invisible to the perf- # parser, not zero — but the symptom is identical.- num_msgs = len(body.get("messages", []))- 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={cache_read_tokens} cache_write={cache_write_tokens} "- f"cache_hit_pct={cache_hit_pct} "- f"opt_ms={optimization_latency:.0f} "- f"transforms={_summarize_transforms(transforms_applied)}"+ transforms_applied=tuple(transforms_applied),+ num_messages=len(body.get("messages", [])),+ tags=tags or {},+ request_messages=body.get("messages")+ if getattr(self.config, "log_full_messages", False)+ else None,)+ await self._record_request_outcome(outcome)if tokens_saved > 0:logger.info(diff --git a/headroom/proxy/outcome.py b/headroom/proxy/outcome.pynew file mode 100644index 000000000..afdfe20ab--- /dev/null+++ b/headroom/proxy/outcome.py@@ -0,0 +1,146 @@+"""``RequestOutcome``: the canonical value type for "what happened during+one completed proxy request."++Per the P0 audit (``docs/superpowers/specs/P0-proxy-pipeline-audit.md``),+18 ``metrics.record_request`` call sites across four handler files+disagreed on argument shape — 9 of 18 omitted ``cached=``, 7 of 18+omitted ``attempted_input_tokens=``, only 4 sites emitted a structured+PERF log at all. This module is the structural fix: every handler+converges 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).++Note: this is **output unification, not input unification**. Provider+APIs (Anthropic ``/v1/messages``, OpenAI Responses WS, Gemini+``generateContent``, Bedrock, Vertex) stay wildly different — the proxy+talks each upstream in its native dialect. This dataclass standardises+only the *observation* about a completed request. Provider-specific+concepts (Anthropic's 5m/1h cache TTL splits, OpenAI's+inferred-write flag, Gemini's read-only cache count) live as optional+fields with neutral defaults; handlers populate what their provider+actually reports.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any+++@dataclass(frozen=True)+class RequestOutcome:+ """Immutable, value-equal snapshot of a completed request.++ Construction policy: every field that downstream consumers read MUST+ be either required (no default) or have a neutral default that makes+ the consumer's behaviour identical to "field not present". This keeps+ the contract honest — a handler that forgets a field doesn't silently+ produce wrong metrics; it produces zeros, which the dashboard can+ surface as a missing-data condition (P3 follow-up).+ """++ # ── Identity ──────────────────────────────────────────────────────+ request_id: str+ provider: str+ model: str++ # ── Tokens (required — every site has these) ──────────────────────+ # original_tokens: pre-compression request size, for `tok_before`+ # optimized_tokens: post-compression bytes actually forwarded, for+ # ``input_tokens`` and ``tok_after``+ # output_tokens: response tokens from upstream+ # tokens_saved: original - optimized (or 0 if compression bypassed)+ # attempted_input_tokens: denominator for active-savings-percent.+ # The compressible portion only — excludes user messages, system+ # prompts, prior assistant turns, frozen prefix bytes. This is the+ # field 7 of 18 audit sites forgot to pass, collapsing+ # ``active_savings_percent`` to 0 (#454 / #455).+ original_tokens: int+ optimized_tokens: int+ output_tokens: int+ tokens_saved: int+ attempted_input_tokens: int++ # ── Cache (provider-agnostic; unused fields stay 0) ───────────────+ # Anthropic populates all five (read + write + 5m + 1h + uncached).+ # OpenAI populates read + inferred-write + uncached, and sets+ # ``cache_inferred=True`` so the dashboard can warn that the write+ # column is an estimate rather than an upstream-reported counter.+ # Gemini populates read only.+ # Bedrock mirrors Anthropic (it forwards Anthropic-shape usage).+ cache_read_tokens: int = 0+ cache_write_tokens: int = 0+ cache_write_5m_tokens: int = 0+ cache_write_1h_tokens: int = 0+ uncached_input_tokens: int = 0+ cache_inferred: bool = False++ # ── Timing ────────────────────────────────────────────────────────+ # total_latency_ms: wall-clock end-to-end for this request+ # overhead_ms: time spent in compression dispatch only (subset of total)+ # ttfb_ms: time to first upstream byte for streaming paths; 0 for+ # non-streaming or when unmeasured (no None — convention is 0)+ # pipeline_timing: optional per-stage breakdown surfaced on dashboards+ total_latency_ms: float = 0.0+ overhead_ms: float = 0.0+ ttfb_ms: float = 0.0+ pipeline_timing: dict[str, float] | None = None++ # ── Transforms + diagnostics ──────────────────────────────────────+ # transforms_applied: tuple (immutable) of every transform that ran.+ # RequestLog still wants list[str]; the funnel converts at the+ # boundary.+ # waste_signals: per-router signals captured during routing (counts+ # of skipped vs applied units etc.); dashboards summarise.+ # num_messages: messages in the original request (for ``msgs=N`` in+ # PERF), counted from body.input/body.messages.+ # turn_id: stable hash of the conversation prefix; used by+ # dashboards to group multi-turn sessions.+ # request_messages: only populated when ``config.log_full_messages``+ # is enabled (off by default — message bodies are sensitive).+ # tags: client-provided routing/identification tags.+ transforms_applied: tuple[str, ...] = ()+ waste_signals: dict[str, int] | None = None+ num_messages: int = 0+ turn_id: str | None = None+ request_messages: list[dict[str, Any]] | None = None+ tags: dict[str, str] = field(default_factory=dict)++ # ── Derived (computed once, no caching needed — properties are cheap) ─++ @property+ def cache_hit(self) -> bool:+ """True iff upstream reported any cache read.++ Used by ``RequestLog.cache_hit`` and ``record_request(cached=...)``.+ Pre-refactor 9 of 18 sites hardcoded this to False — this property+ makes "I forgot to compute it" structurally impossible.+ """+ return self.cache_read_tokens > 0++ @property+ def cache_hit_pct(self) -> int:+ """Cache read share of (read + write), rounded to int percent.++ Returns 0 when neither read nor write fired (a request that did no+ cache work; distinguishing this from "0% hit rate on real cache+ work" requires looking at the absolute values, not the ratio).+ """+ denom = self.cache_read_tokens + self.cache_write_tokens+ if denom <= 0:+ return 0+ return round(self.cache_read_tokens / denom * 100)++ @property+ def savings_pct(self) -> float:+ """Compression savings as a fraction of the original request size.++ This is the proxy-side ratio: ``tokens_saved / original_tokens``.+ The dashboard headline "active savings percent" uses a different+ ratio (``tokens_saved / attempted_input_tokens``) — see the+ Prometheus metric for the active calculation.+ """+ if self.original_tokens <= 0:+ return 0.0+ return self.tokens_saved / self.original_tokens * 100.0diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex f2e963754..2c6882eb6 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -42,6 +42,7 @@ if TYPE_CHECKING:from ..backends.base import Backendfrom ..cache.compression_cache import CompressionCachefrom ..memory.tracker import MemoryTracker+ from .outcome import RequestOutcomeimport httpx@@ -1149,6 +1150,97 @@ class HeadroomProxy(logger.info(f"Avg latency: {avg_latency:.0f}ms")logger.info("=" * 70)+ 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.++ See ``docs/superpowers/specs/P0-proxy-pipeline-audit.md`` for the+ divergence catalog this funnel collapses.+ """++ # 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))}"+ )+async def _next_request_id(self) -> str:"""Generate unique request ID."""async with self._request_counter_lock:diff --git a/tests/test_request_outcome.py b/tests/test_request_outcome.pynew file mode 100644index 000000000..4a2f1d9b0--- /dev/null+++ b/tests/test_request_outcome.py@@ -0,0 +1,305 @@+"""Tests for :class:`headroom.proxy.outcome.RequestOutcome` and the+:meth:`HeadroomProxy._record_request_outcome` funnel.++The point of this file is the *contract* — every behavioural assertion+here is a thing that, prior to the funnel, lived inline at one or more+of the 18 metrics-emit sites identified in+``docs/superpowers/specs/P0-proxy-pipeline-audit.md``. Locking the+contract in tests means future migrations onto the funnel cannot+silently regress the wire shape.+"""++from __future__ import annotations++import logging+from dataclasses import FrozenInstanceError+from typing import Any+from unittest.mock import AsyncMock, MagicMock++import pytest++from headroom.proxy.outcome import RequestOutcome++# ── Value-type contract ────────────────────────────────────────────────+++def _outcome(**overrides: Any) -> RequestOutcome:+ """Construct a RequestOutcome with sensible defaults; override fields per test."""+ defaults: dict[str, Any] = {+ "request_id": "req-1",+ "provider": "anthropic",+ "model": "claude-sonnet-4",+ "original_tokens": 1000,+ "optimized_tokens": 300,+ "output_tokens": 50,+ "tokens_saved": 700,+ "attempted_input_tokens": 800,+ }+ defaults.update(overrides)+ return RequestOutcome(**defaults)+++def test_outcome_is_frozen() -> None:+ """Mutability would let a handler patch the outcome after handing it+ to the funnel — bypassing the contract. Must error."""+ o = _outcome()+ with pytest.raises(FrozenInstanceError):+ o.cache_read_tokens = 999 # type: ignore[misc]+++def test_cache_hit_is_derived_not_stored() -> None:+ """Pre-refactor, 9 of 18 ``RequestLog`` sites hardcoded ``cache_hit=False``+ even when ``cache_read_tokens > 0``. Deriving from the actual value+ makes "forgot to compute it" structurally impossible."""+ assert _outcome(cache_read_tokens=0).cache_hit is False+ assert _outcome(cache_read_tokens=1).cache_hit is True+ assert _outcome(cache_read_tokens=500).cache_hit is True+++def test_cache_hit_pct_handles_zero_denominator() -> None:+ """No reads + no writes is a no-cache request, not a 0%-hit cache request.+ Returning 0 here is correct as long as dashboards distinguish via the+ absolute ``cache_read_tokens`` / ``cache_write_tokens`` values."""+ assert _outcome(cache_read_tokens=0, cache_write_tokens=0).cache_hit_pct == 0+++def test_cache_hit_pct_rounds_to_int() -> None:+ """PERF log line consumed by ``headroom perf`` parses an integer here;+ keep the type contract tight."""+ o = _outcome(cache_read_tokens=2, cache_write_tokens=1) # 66.66%+ assert o.cache_hit_pct == 67+ assert isinstance(o.cache_hit_pct, int)+++def test_savings_pct_handles_zero_original() -> None:+ """A request with 0 original tokens — e.g. an empty body — should not+ raise ZeroDivisionError. Sites pre-refactor handled this inconsistently."""+ assert _outcome(original_tokens=0).savings_pct == 0.0+++def test_savings_pct_basic() -> None:+ assert _outcome(original_tokens=1000, tokens_saved=300).savings_pct == 30.0+++def test_provider_specific_fields_default_to_zero() -> None:+ """Anthropic's 5m/1h cache TTL splits don't exist on OpenAI / Gemini.+ The dataclass defaults them to 0 so non-Anthropic handlers don't+ have to know about them."""+ o = _outcome(provider="openai", cache_read_tokens=100, cache_write_tokens=200)+ assert o.cache_write_5m_tokens == 0+ assert o.cache_write_1h_tokens == 0+ # And OpenAI's "inferred" flag defaults False — only the OpenAI+ # handler sets it True after running _infer_openai_cache_write_tokens.+ assert o.cache_inferred is False+++def test_optional_fields_default_to_neutral_values() -> None:+ """Handlers that don't have a field (e.g. Bedrock with no waste_signals)+ must not have to pass anything — defaults handle it."""+ o = _outcome()+ assert o.ttfb_ms == 0.0+ assert o.pipeline_timing is None+ assert o.waste_signals is None+ assert o.transforms_applied == ()+ assert o.turn_id is None+ assert o.request_messages is None+ assert o.tags == {}+++# ── Funnel contract (_record_request_outcome) ──────────────────────────+++class _CollectingLogger:+ """Minimal stand-in for ``RequestLogger``."""++ def __init__(self) -> None:+ self.logs: list[Any] = []++ def log(self, entry: Any) -> None:+ self.logs.append(entry)+++class _FunnelHarness:+ """Pulls just enough of HeadroomProxy onto an object to exercise+ ``_record_request_outcome`` without instantiating the full proxy.++ The harness assigns the real method to ``self`` via descriptor+ binding so the implementation is exactly the production one — no+ forking, no mock-the-thing-you're-testing.+ """++ def __init__(self, *, with_cost_tracker: bool = True, with_logger: bool = True) -> None:+ from headroom.proxy.server import HeadroomProxy++ self.metrics = MagicMock()+ self.metrics.record_request = AsyncMock()+ self.cost_tracker = MagicMock() if with_cost_tracker else None+ self.logger = _CollectingLogger() if with_logger else None+ # Bind the real method to this harness.+ self._record_request_outcome = HeadroomProxy._record_request_outcome.__get__(+ self, type(self)+ )+++async def test_funnel_calls_metrics_with_full_kwargs() -> None:+ """The funnel must pass EVERY field that+ ``PrometheusMetrics.record_request`` knows about, not the+ pre-refactor "pass-what-was-convenient" subset. Otherwise a handler+ that forgets to populate a field silently degrades dashboard data."""+ h = _FunnelHarness()+ o = _outcome(+ provider="openai",+ model="gpt-4",+ optimized_tokens=300,+ output_tokens=50,+ tokens_saved=700,+ attempted_input_tokens=800,+ cache_read_tokens=200,+ cache_write_tokens=100,+ cache_write_5m_tokens=50,+ cache_write_1h_tokens=50,+ uncached_input_tokens=0,+ total_latency_ms=1234.5,+ overhead_ms=12.3,+ ttfb_ms=200.0,+ pipeline_timing={"phase": 1.0},+ waste_signals={"skipped": 3},+ )+ await h._record_request_outcome(o)++ h.metrics.record_request.assert_awaited_once()+ kwargs = h.metrics.record_request.await_args.kwargs+ assert kwargs["provider"] == "openai"+ assert kwargs["model"] == "gpt-4"+ assert kwargs["input_tokens"] == 300 # optimized → input+ assert kwargs["output_tokens"] == 50+ assert kwargs["tokens_saved"] == 700+ assert kwargs["latency_ms"] == 1234.5+ assert kwargs["cached"] is True # derived from cache_read > 0+ assert kwargs["overhead_ms"] == 12.3+ assert kwargs["ttfb_ms"] == 200.0+ assert kwargs["pipeline_timing"] == {"phase": 1.0}+ assert kwargs["waste_signals"] == {"skipped": 3}+ assert kwargs["cache_read_tokens"] == 200+ assert kwargs["cache_write_tokens"] == 100+ assert kwargs["cache_write_5m_tokens"] == 50+ assert kwargs["cache_write_1h_tokens"] == 50+ assert kwargs["uncached_input_tokens"] == 0+ assert kwargs["attempted_input_tokens"] == 800+++async def test_funnel_passes_canonical_record_tokens_shape() -> None:+ """``cost_tracker.record_tokens`` takes ``(model, tokens_saved,+ optimized_tokens)`` positionally and the cache args as kwargs. The+ funnel preserves this — moving anything to positional would break+ sites that pass kwargs explicitly."""+ h = _FunnelHarness()+ o = _outcome(+ model="claude-sonnet-4",+ optimized_tokens=300,+ tokens_saved=700,+ cache_read_tokens=200,+ cache_write_tokens=100,+ cache_write_5m_tokens=80,+ cache_write_1h_tokens=20,+ uncached_input_tokens=0,+ )+ await h._record_request_outcome(o)++ h.cost_tracker.record_tokens.assert_called_once()+ args, kwargs = h.cost_tracker.record_tokens.call_args+ assert args == ("claude-sonnet-4", 700, 300)+ assert kwargs == {+ "cache_read_tokens": 200,+ "cache_write_tokens": 100,+ "cache_write_5m_tokens": 80,+ "cache_write_1h_tokens": 20,+ "uncached_tokens": 0,+ }+++async def test_funnel_skips_cost_tracker_when_absent() -> None:+ """When the proxy was started with ``--no-cost``, ``cost_tracker``+ is None and the funnel must skip step 2 silently."""+ h = _FunnelHarness(with_cost_tracker=False)+ await h._record_request_outcome(_outcome())+ # No crash, metrics still recorded.+ h.metrics.record_request.assert_awaited_once()+++async def test_funnel_logs_request_with_derived_cache_hit() -> None:+ """The RequestLog row needs cache_hit derived from cache_read>0, not+ the hardcoded False that 9 of 18 pre-refactor sites used."""+ h = _FunnelHarness()+ await h._record_request_outcome(_outcome(cache_read_tokens=200, cache_write_tokens=100))+ assert len(h.logger.logs) == 1+ log_entry = h.logger.logs[0]+ assert log_entry.cache_hit is True+++async def test_funnel_skips_request_log_when_logger_absent() -> None:+ """Same pattern as cost_tracker — optional surface."""+ h = _FunnelHarness(with_logger=False)+ await h._record_request_outcome(_outcome())+ h.metrics.record_request.assert_awaited_once() # still happens+++async def test_funnel_emits_perf_log_with_canonical_shape(+ caplog: pytest.LogCaptureFixture,+) -> None:+ """``headroom perf`` parses this exact ``key=value`` format. Changing+ it breaks the analyzer. The contract: model, msgs, tok_before,+ tok_after, tok_saved, cache_read, cache_write, cache_hit_pct,+ opt_ms, transforms — in that order, space-separated."""+ h = _FunnelHarness()+ # Direct handler attach: caplog otherwise drops propagation-disabled+ # records (the proxy disables ``headroom.*`` propagation once started).+ target = logging.getLogger("headroom.proxy")+ captured: list[logging.LogRecord] = []++ class _H(logging.Handler):+ def emit(self, record: logging.LogRecord) -> None:+ captured.append(record)++ handler = _H(level=logging.INFO)+ target.addHandler(handler)+ prior_level = target.level+ target.setLevel(logging.INFO)+ try:+ await h._record_request_outcome(+ _outcome(+ request_id="req-perf",+ model="gpt-4",+ original_tokens=1000,+ optimized_tokens=300,+ tokens_saved=700,+ cache_read_tokens=200,+ cache_write_tokens=100,+ num_messages=5,+ overhead_ms=12.0,+ transforms_applied=("smart_crusher", "content_router"),+ )+ )+ finally:+ target.removeHandler(handler)+ target.setLevel(prior_level)++ perf_lines = [r.getMessage() for r in captured if " PERF " in r.getMessage()]+ assert len(perf_lines) == 1+ line = perf_lines[0]+ assert "[req-perf] PERF " in line+ assert "model=gpt-4" in line+ assert "msgs=5" in line+ assert "tok_before=1000" in line+ assert "tok_after=300" in line+ assert "tok_saved=700" in line+ assert "cache_read=200" in line+ assert "cache_write=100" in line+ assert "cache_hit_pct=67" in line # 200/(200+100) * 100 = 67+ assert "opt_ms=12" in line