Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

refactor(proxy): introduce RequestOutcome funnel; collapse 3 streaming finalizers

chopratejase898f68b89fc
diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py
index fc0cacd30..72e274096 100644
--- a/headroom/proxy/handlers/streaming.py
+++ b/headroom/proxy/handlers/streaming.py
@@ -10,7 +10,6 @@ import contextlib
import json
import logging
import time
-from datetime import datetime
from typing import TYPE_CHECKING, Any
from 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 RequestOutcome
total_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 RequestOutcome
start_time = time.time()
@@ -1367,19 +1315,7 @@ class StreamingMixin:
yield f"event: error\ndata: {json.dumps(error_event)}\n\n".encode()
finally:
- # Record metrics
total_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_transforms
from headroom.proxy.handlers.openai import _infer_openai_cache_write_tokens
+ from headroom.proxy.outcome import RequestOutcome
assert self.anthropic_backend is not None
@@ -1555,19 +1450,15 @@ class StreamingMixin:
output_tokens = stream_state["output_tokens"] or 0
cache_read_tokens = stream_state["cache_read_input_tokens"] or 0
if upstream_input is None:
- input_tokens = 0
cache_write_tokens = 0
uncached_input_tokens = 0
- cache_hit_pct = 0
+ cache_inferred = False
else:
- input_tokens = upstream_input
cache_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 = True
total_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.py
new file mode 100644
index 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.0
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index f2e963754..2c6882eb6 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -42,6 +42,7 @@ if TYPE_CHECKING:
from ..backends.base import Backend
from ..cache.compression_cache import CompressionCache
from ..memory.tracker import MemoryTracker
+ from .outcome import RequestOutcome
import 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.py
new file mode 100644
index 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