Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix: stabilize codex compression, stats, and proxy lifecycle
Tejas Chopraeaf5980b4ac4
diff --git a/.gitignore b/.gitignoreindex 09075e8b5..b3173fc3a 100644--- a/.gitignore+++ b/.gitignore@@ -187,6 +187,7 @@ benchmark_results/.deepeval/# Headroom specific+.headroom/headroom.dbheadroom_*.db*.jsonldiff --git a/crates/headroom-core/src/transforms/live_zone.rs b/crates/headroom-core/src/transforms/live_zone.rsindex 058a72b49..d621d7165 100644--- a/crates/headroom-core/src/transforms/live_zone.rs+++ b/crates/headroom-core/src/transforms/live_zone.rs@@ -94,7 +94,7 @@//! parameter in the signature now means later PRs are pure//! implementation swaps, not signature redesigns.-use std::sync::OnceLock;+use std::{collections::HashSet, sync::OnceLock};use serde::Deserialize;use serde_json::value::RawValue;@@ -148,27 +148,27 @@ pub const DEFAULT_MODEL: &str = "claude-3-5-sonnet-20241022";// Pinned as `const` rather than a hard-coded `match` so the values are// grep-able and reviewable in one place.-/// JSON-array tool_results below this size route to no-op (1 KiB).-const THRESHOLD_JSON_ARRAY: usize = 1024;+/// JSON-array tool_results below this size route to no-op.+const THRESHOLD_JSON_ARRAY: usize = 512;/// Build / log output below this size routes to no-op (512 B). Logs/// are the most repetitive content type so the threshold is the/// lowest of the bunch.const THRESHOLD_BUILD_OUTPUT: usize = 512;-/// Search-result blocks below this size route to no-op (1 KiB).-const THRESHOLD_SEARCH_RESULTS: usize = 1024;-/// Git-diff blocks below this size route to no-op (1 KiB).-const THRESHOLD_GIT_DIFF: usize = 1024;-/// Source-code blocks below this size route to no-op (2 KiB). Pinned+/// Search-result blocks below this size route to no-op.+const THRESHOLD_SEARCH_RESULTS: usize = 512;+/// Git-diff blocks below this size route to no-op.+const THRESHOLD_GIT_DIFF: usize = 512;+/// Source-code blocks below this size route to no-op. Pinned/// for the future Rust code-compressor port — currently unused/// because `ContentType::SourceCode` short-circuits to no-op above/// the dispatch (see `dispatch_compressor`).-const THRESHOLD_SOURCE_CODE: usize = 2048;-/// Plain-text blocks below this size route to no-op (5 KiB). Pinned+const THRESHOLD_SOURCE_CODE: usize = 512;+/// Plain-text blocks below this size route to no-op. Pinned/// for the future Kompress wiring (PR-B7 follow-up); currently unused.-const THRESHOLD_PLAIN_TEXT: usize = 5120;+const THRESHOLD_PLAIN_TEXT: usize = 512;/// HTML blocks have no compressor; threshold matches plain text so/// when an HTML compressor lands the value is already pinned.-const THRESHOLD_HTML: usize = 5120;+const THRESHOLD_HTML: usize = 512;/// Map a content type to its byte threshold. Returning `usize` rather/// than an `Option` because every variant has a sensible default;@@ -428,6 +428,59 @@ impl CompressionManifest {}}+/// Summarize why a Responses live-zone dispatch made no changes.+///+/// The proxy uses this to log stable, grep-able reasons instead of the+/// generic `rust_no_compression` bucket. The classification is+/// intentionally coarse: operators want to know whether the dispatcher+/// saw no eligible items, hit a size floor, rejected output as not+/// smaller, or encountered a compressor error.+pub fn summarize_openai_responses_no_change_reason(manifest: &CompressionManifest) -> &'static str {+ if manifest.block_outcomes.is_empty() {+ return "no_eligible_items";+ }++ let mut saw_no_compression_applied = false;+ let mut saw_excluded = false;+ let mut saw_below_output_floor = false;+ let mut saw_below_plain_text_floor = false;+ let mut saw_rejected_not_smaller = false;+ let mut saw_compressor_error = false;++ for outcome in &manifest.block_outcomes {+ match &outcome.action {+ BlockAction::CompressorError { .. } => saw_compressor_error = true,+ BlockAction::RejectedNotSmaller { .. } => saw_rejected_not_smaller = true,+ BlockAction::BelowByteThreshold { content_type, .. } => {+ if *content_type == "output_item" {+ saw_below_output_floor = true;+ } else {+ saw_below_plain_text_floor = true;+ }+ }+ BlockAction::NoCompressionApplied { .. } => saw_no_compression_applied = true,+ BlockAction::Excluded { .. } => saw_excluded = true,+ BlockAction::Compressed { .. } => {}+ }+ }++ if saw_compressor_error {+ "compressor_error"+ } else if saw_rejected_not_smaller {+ "rejected_not_smaller"+ } else if saw_below_output_floor {+ "below_output_floor"+ } else if saw_below_plain_text_floor {+ "below_plain_text_floor"+ } else if saw_excluded {+ "excluded_live_zone"+ } else if saw_no_compression_applied {+ "no_compressible_content"+ } else {+ "no_change"+ }+}+/// Outcome of dispatching the live zone.#[derive(Debug)]pub enum LiveZoneOutcome {@@ -1482,7 +1535,7 @@ mod tests {let out = compress_anthropic_live_zone(&b, 0, AuthMode::Payg, DEFAULT_MODEL).unwrap();let actions = outcome_block_actions(&out);assert_eq!(actions.len(), 3);- // tool_result with tiny content → BelowByteThreshold (1 byte < 5 KiB plain-text threshold).+ // tool_result with tiny content → BelowByteThreshold.assert!(matches!(actions[0], BlockAction::BelowByteThreshold { .. }));assert!(matches!(actions[1],@@ -1490,7 +1543,7 @@ mod tests {reason: ExclusionReason::HotZoneBlockType}));- // text block with "ok" → BelowByteThreshold (2 bytes < 5 KiB plain-text threshold).+ // text block with "ok" → BelowByteThreshold.assert!(matches!(actions[2], BlockAction::BelowByteThreshold { .. }));}@@ -1506,7 +1559,7 @@ mod tests {};assert_eq!(manifest.block_outcomes.len(), 1);assert_eq!(manifest.block_outcomes[0].block_type, "string_content");- // 13 bytes of plain text is well below the 5 KiB plain-text threshold.+ // 13 bytes of plain text is well below the plain-text threshold.assert!(matches!(manifest.block_outcomes[0].action,BlockAction::BelowByteThreshold { .. }@@ -2153,14 +2206,14 @@ mod openai_chat_tests {// records a `NoCompressionApplied` outcome but never plans a// replacement.//-// Output items must additionally clear a 2 KiB minimum (per spec line+// Output items must additionally clear a 512-byte minimum// 167) before the per-content-type byte threshold even runs./// Output-item floor below which the Responses dispatcher does not-/// even attempt compression. Per spec PR-C3 §scope. Matches+/// even attempt compression. Matches/// `responses_items::OUTPUT_ITEM_MIN_BYTES`; pinned here too because/// `headroom-core` is independent of the proxy crate.-const RESPONSES_OUTPUT_MIN_BYTES: usize = 2 * 1024;+const RESPONSES_OUTPUT_MIN_BYTES: usize = 512;/// Compress live-zone blocks of an OpenAI Responses request.///@@ -2182,11 +2235,13 @@ const RESPONSES_OUTPUT_MIN_BYTES: usize = 2 * 1024;/// }/// ```///-/// Live zone = the latest item of each compressible kind:-/// `function_call_output`, `local_shell_call_output`,-/// `apply_patch_call_output`, plus the latest `message` text. Earlier-/// items of those kinds are frozen (cached prefix); never rewritten.-/// All other item types pass through verbatim.+/// Live zone = every current-frame output item with a byte-safe+/// string payload (`function_call_output`, `local_shell_call_output`,+/// `apply_patch_call_output`), except CCR retrieval outputs that must+/// reach the model byte-for-byte.+/// Codex commonly batches parallel tool results in one `response.create`+/// frame; those sibling outputs are all live input for the next model+/// turn. All other item types pass through verbatim.////// Cache-safety invariant matches the Anthropic / Chat dispatchers:/// bytes outside the rewritten ranges are *literally copied* from the@@ -2217,54 +2272,46 @@ pub fn compress_openai_responses_live_zone(let items_total = items.len();- // Walk items from the back, tagging the first occurrence of each- // compressible kind. This naturally yields "latest" semantics.- let mut latest_function_output: Option<usize> = None;- let mut latest_local_shell_output: Option<usize> = None;- let mut latest_apply_patch_output: Option<usize> = None;- let mut latest_message: Option<usize> = None;+ // Output items in the current Responses frame are live deltas, not+ // cached history. Codex often sends several sibling tool outputs+ // after parallel local commands; compressing only the last one+ // leaves large same-frame payloads untouched.+ let mut headroom_retrieve_call_ids: HashSet<&str> = HashSet::new();+ for item in items {+ if item.get("type").and_then(Value::as_str) != Some("function_call") {+ continue;+ }+ let name = item.get("name").and_then(Value::as_str).unwrap_or("");+ if name == "headroom_retrieve" || name.ends_with("__headroom_retrieve") {+ if let Some(call_id) = item.get("call_id").and_then(Value::as_str) {+ headroom_retrieve_call_ids.insert(call_id);+ }+ }+ }- for (idx, item) in items.iter().enumerate().rev() {+ let mut output_candidates: Vec<(usize, &str)> = Vec::new();+ let latest_message: Option<usize> = None;++ for (idx, item) in items.iter().enumerate() {let type_tag = item.get("type").and_then(Value::as_str).unwrap_or("");match type_tag {- "function_call_output" if latest_function_output.is_none() => {- latest_function_output = Some(idx);- }- "local_shell_call_output" if latest_local_shell_output.is_none() => {- latest_local_shell_output = Some(idx);- }- "apply_patch_call_output" if latest_apply_patch_output.is_none() => {- latest_apply_patch_output = Some(idx);- }- // Only consider user-role messages for compression.- // Assistant messages are part of the cache hot zone- // (next-turn continuation context).- "message"- if latest_message.is_none()- && item.get("role").and_then(Value::as_str) == Some("user") =>- {- latest_message = Some(idx);+ "function_call_output" | "local_shell_call_output" | "apply_patch_call_output" => {+ let call_id = item.get("call_id").and_then(Value::as_str);+ if call_id.is_some_and(|id| headroom_retrieve_call_ids.contains(id)) {+ continue;+ }+ output_candidates.push((idx, type_tag));}_ => {}}- // Early-exit if we've found everything we care about.- if latest_function_output.is_some()- && latest_local_shell_output.is_some()- && latest_apply_patch_output.is_some()- && latest_message.is_some()- {- break;- }}- let candidates: &[(Option<usize>, &str)] = &[- (latest_function_output, "function_call_output"),- (latest_local_shell_output, "local_shell_call_output"),- (latest_apply_patch_output, "apply_patch_call_output"),- (latest_message, "message"),- ];+ let mut candidates = output_candidates;+ if let Some(idx) = latest_message {+ candidates.push((idx, "message"));+ }- if candidates.iter().all(|(idx, _)| idx.is_none()) {+ if candidates.is_empty() {return Ok(LiveZoneOutcome::NoChange {manifest: CompressionManifest {messages_total: items_total,@@ -2279,10 +2326,9 @@ pub fn compress_openai_responses_live_zone(// one slot (output items have a single string field; messages// have a single text content slot).let mut all_slots: Vec<(usize, ResponsesPlanSlot)> = Vec::new();- for (maybe_idx, kind_tag) in candidates {- let Some(idx) = maybe_idx else { continue };- match plan_responses_item(body_raw, *idx, kind_tag) {- Ok(Some(slot)) => all_slots.push((*idx, slot)),+ for (idx, kind_tag) in candidates {+ match plan_responses_item(body_raw, idx, kind_tag) {+ Ok(Some(slot)) => all_slots.push((idx, slot)),Ok(None) => {}Err(_) => {// Body shape doesn't match what we expect for this@@ -2308,7 +2354,7 @@ pub fn compress_openai_responses_live_zone(let mut replacements: Vec<Replacement> = Vec::new();for (msg_idx, slot) in all_slots {- // Output items must clear the 2 KiB floor BEFORE the+ // Output items must clear the response-output floor BEFORE the// per-content-type threshold even runs. This is on top of the// existing per-block byte-threshold gate.if slot.is_output_item && slot.content_text.len() < RESPONSES_OUTPUT_MIN_BYTES {@@ -2368,7 +2414,7 @@ pub fn compress_openai_responses_live_zone(/// Per-kind plan slot for the Responses dispatcher. Mirrors/// `OpenAiPlanSlot` but tracks whether the slot is an `*_output` item-/// (so the 2 KiB floor only applies there, not to `message` text).+/// (so the response-output floor only applies there, not to `message` text).struct ResponsesPlanSlot {block_index: Option<usize>,block_type: String,@@ -2376,7 +2422,7 @@ struct ResponsesPlanSlot {content_byte_range: (usize, usize),/// True when the slot is one of `function_call_output`,/// `local_shell_call_output`, `apply_patch_call_output`. Used to- /// gate the 2 KiB output-item floor.+ /// gate the response-output floor.is_output_item: bool,}@@ -2578,9 +2624,9 @@ mod openai_responses_tests {}#[test]- fn output_below_2kb_skipped() {- // 1 KB output → below the output-item floor.- let small = "x".repeat(1024);+ fn output_below_512b_skipped() {+ // 256 B output → below the output-item floor.+ let small = "x".repeat(256);let b = body(json!({"model": "gpt-4o","input": [@@ -2598,8 +2644,8 @@ mod openai_responses_tests {threshold_bytes,} => {assert_eq!(*content_type, "output_item");- assert_eq!(*byte_count, 1024);- assert_eq!(*threshold_bytes, 2048);+ assert_eq!(*byte_count, 256);+ assert_eq!(*threshold_bytes, RESPONSES_OUTPUT_MIN_BYTES);}other => panic!("expected BelowByteThreshold, got {other:?}"),}@@ -2609,10 +2655,10 @@ mod openai_responses_tests {}#[test]- fn picks_latest_function_output_only() {- // Two function_call_output items; only the latest is in the- // live zone. Both small, so neither compresses, but the- // manifest must show one slot, not two.+ fn plans_all_same_frame_function_outputs() {+ // Codex can batch parallel tool results in a single+ // response.create frame. They are all current-frame live+ // inputs, so each byte-safe output string gets a slot.let b = body(json!({"model": "gpt-4o","input": [@@ -2631,8 +2677,45 @@ mod openai_responses_tests {.iter().filter(|b| b.block_type == "function_call_output").collect();- assert_eq!(outputs.len(), 1);- assert_eq!(outputs[0].message_index, 2);+ assert_eq!(outputs.len(), 2);+ assert_eq!(outputs[0].message_index, 0);+ assert_eq!(outputs[1].message_index, 2);+ }++ #[test]+ fn compresses_multiple_same_frame_outputs() {+ let mut first = String::new();+ let mut second = String::new();+ for i in 0..400 {+ first.push_str(&format!(+ "./src/foo_{i}.rs:12: error[E0308]: mismatched types in module foo_{i}\n"+ ));+ second.push_str(&format!(+ "./tests/bar_{i}.rs:44: warning: unused variable in test bar_{i}\n"+ ));+ }+ let b = body(json!({+ "model": "gpt-4o",+ "input": [+ {"type": "function_call_output", "call_id": "c1", "output": first},+ {"type": "function_call", "call_id": "c2", "name": "f", "arguments": "{}"},+ {"type": "function_call_output", "call_id": "c2", "output": second},+ ]+ }));+ let out = compress_openai_responses_live_zone(&b, AuthMode::Payg, "gpt-4o").unwrap();+ let manifest = match &out {+ LiveZoneOutcome::NoChange { manifest } => manifest,+ LiveZoneOutcome::Modified { manifest, .. } => manifest,+ };+ let compressed_outputs = manifest+ .block_outcomes+ .iter()+ .filter(|b| {+ b.block_type == "function_call_output"+ && matches!(b.action, BlockAction::Compressed { .. })+ })+ .count();+ assert_eq!(compressed_outputs, 2, "{manifest:?}");}#[test]@@ -2702,7 +2785,7 @@ mod openai_responses_tests {}#[test]- fn message_user_content_planned() {+ fn message_user_content_not_in_live_zone() {let b = body(json!({"model": "gpt-4o","input": [@@ -2713,8 +2796,35 @@ mod openai_responses_tests {let out = compress_openai_responses_live_zone(&b, AuthMode::Payg, "gpt-4o").unwrap();match &out {LiveZoneOutcome::NoChange { manifest } => {- assert_eq!(manifest.block_outcomes.len(), 1);- assert_eq!(manifest.block_outcomes[0].block_type, "message_input_text");+ assert!(manifest.block_outcomes.is_empty());+ }+ _ => panic!("expected NoChange"),+ }+ }++ #[test]+ fn headroom_retrieve_output_not_in_live_zone() {+ let retrieved = "retrieved original content ".repeat(100);+ let b = body(json!({+ "model": "gpt-4o",+ "input": [+ {+ "type": "function_call",+ "call_id": "call_retrieve",+ "name": "mcp__headroom__headroom_retrieve",+ "arguments": "{}"+ },+ {+ "type": "function_call_output",+ "call_id": "call_retrieve",+ "output": retrieved+ }+ ]+ }));+ let out = compress_openai_responses_live_zone(&b, AuthMode::Payg, "gpt-4o").unwrap();+ match &out {+ LiveZoneOutcome::NoChange { manifest } => {+ assert!(manifest.block_outcomes.is_empty());}_ => panic!("expected NoChange"),}@@ -2739,4 +2849,36 @@ mod openai_responses_tests {_ => panic!("expected NoChange"),}}++ #[test]+ fn no_change_reason_empty_input_is_no_eligible_items() {+ let manifest = CompressionManifest::empty();+ assert_eq!(+ summarize_openai_responses_no_change_reason(&manifest),+ "no_eligible_items"+ );+ }++ #[test]+ fn no_change_reason_prefers_output_floor() {+ let manifest = CompressionManifest {+ messages_total: 1,+ messages_below_frozen_floor: 0,+ latest_user_message_index: Some(0),+ block_outcomes: vec![BlockOutcome {+ message_index: 0,+ block_index: None,+ block_type: "function_call_output".to_string(),+ action: BlockAction::BelowByteThreshold {+ content_type: "output_item",+ byte_count: 1024,+ threshold_bytes: RESPONSES_OUTPUT_MIN_BYTES,+ },+ }],+ };+ assert_eq!(+ summarize_openai_responses_no_change_reason(&manifest),+ "below_output_floor"+ );+ }}diff --git a/crates/headroom-core/src/transforms/mod.rs b/crates/headroom-core/src/transforms/mod.rsindex 5546d45b8..6c909d96f 100644--- a/crates/headroom-core/src/transforms/mod.rs+++ b/crates/headroom-core/src/transforms/mod.rs@@ -40,8 +40,9 @@ pub use diff_compressor::{};pub use live_zone::{compress_anthropic_live_zone, compress_openai_chat_live_zone,- compress_openai_responses_live_zone, AuthMode, BlockAction, BlockOutcome, CompressionManifest,- ExclusionReason, LiveZoneError, LiveZoneOutcome,+ compress_openai_responses_live_zone, summarize_openai_responses_no_change_reason, AuthMode,+ BlockAction, BlockOutcome, CompressionManifest, ExclusionReason, LiveZoneError,+ LiveZoneOutcome,};pub use log_compressor::{LogCompressionResult, LogCompressor, LogCompressorConfig, LogCompressorStats, LogFormat,diff --git a/crates/headroom-proxy/src/compression/live_zone_responses.rs b/crates/headroom-proxy/src/compression/live_zone_responses.rsindex 213f1fd3f..ef4e58378 100644--- a/crates/headroom-proxy/src/compression/live_zone_responses.rs+++ b/crates/headroom-proxy/src/compression/live_zone_responses.rs@@ -35,7 +35,8 @@ use bytes::Bytes;use headroom_core::auth_mode::AuthMode as RequestAuthMode;use headroom_core::transforms::live_zone::DEFAULT_MODEL;use headroom_core::transforms::{- compress_openai_responses_live_zone, BlockAction, LiveZoneError, LiveZoneOutcome,+ compress_openai_responses_live_zone, summarize_openai_responses_no_change_reason, BlockAction,+ LiveZoneError, LiveZoneOutcome,};use serde_json::Value;@@ -146,6 +147,7 @@ pub fn compress_openai_responses_request(// the rationale — same wiring on the OpenAI Responses path.match compress_openai_responses_live_zone(&dispatch_body, auth_mode.into(), model) {Ok(LiveZoneOutcome::NoChange { manifest }) => {+ let reason = summarize_openai_responses_no_change_reason(&manifest);tracing::info!(event = "compression_decision",request_id = %request_id,@@ -153,7 +155,7 @@ pub fn compress_openai_responses_request(method = "POST",compression_mode = mode.as_str(),decision = "no_change",- reason = "no_block_compressed",+ reason = reason,body_bytes = body.len(),items_total = manifest.messages_total,latest_user_message_index = ?manifest.latest_user_message_index,diff --git a/crates/headroom-proxy/src/responses_items.rs b/crates/headroom-proxy/src/responses_items.rsindex 4aabd710a..0b6ec999c 100644--- a/crates/headroom-proxy/src/responses_items.rs+++ b/crates/headroom-proxy/src/responses_items.rs@@ -25,7 +25,7 @@//! (`function_call_output`, `local_shell_call_output`,//! `apply_patch_call_output`) are eligible for live-zone//! compression — but only the *latest* of each kind, only above the-//! 2 KiB output-item floor, and only when the per-content-type+//! output-item floor, and only when the per-content-type//! compressor agrees the result shrinks the token count.//! - **Unknown item types** are logged at warn level and preserved//! byte-for-byte via `serde_json::value::RawValue`. This is the@@ -122,7 +122,7 @@ pub struct ApplyPatchOperation<'a> {/// the wire; never parse it as JSON inside the proxy. The model/// built it; the model parses it./// - `output` on `*_output` items is a string. Compressors run only-/// on the latest of each kind, and only above the 2 KiB output-item+/// on the latest of each kind, and only above the output-item/// floor (see [`OUTPUT_ITEM_MIN_BYTES`])./// - String fields use `Cow<'a, str>` so escape-bearing JSON values/// (e.g. `"{\"q\":\"hello\"}"`) succeed without allocation on the@@ -180,7 +180,7 @@ pub enum ResponseItem<'a> {/// Function tool output. `output` is the string the proxy may/// compress when this is the latest `function_call_output` and- /// the bytes exceed the 2 KiB floor.+ /// the bytes exceed the output-item floor.#[serde(rename = "function_call_output")]FunctionCallOutput {#[serde(default, borrow)]@@ -379,11 +379,10 @@ impl<'a> ResponseItem<'a> {}/// Per-item-type minimum bytes before the live-zone dispatcher even-/// inspects an `*_output` payload. Per spec PR-C3 §scope: 2 KiB.+/// inspects an `*_output` payload./// Per-content-type thresholds from `transforms::live_zone` still-/// apply on top of this floor (e.g. logs at 512 B → still skipped-/// because output items must clear 2 KiB first).-pub const OUTPUT_ITEM_MIN_BYTES: usize = 2 * 1024;+/// apply on top of this floor.+pub const OUTPUT_ITEM_MIN_BYTES: usize = 512;/// Two-pass result: a typed view alongside the byte-faithful raw/// slice. Lifetime ties to the underlying request body. Alwaysdiff --git a/crates/headroom-proxy/tests/sse_framing.rs b/crates/headroom-proxy/tests/sse_framing.rsindex e04208859..bf487e4cb 100644--- a/crates/headroom-proxy/tests/sse_framing.rs+++ b/crates/headroom-proxy/tests/sse_framing.rs@@ -147,20 +147,17 @@ fn chunk_boundary_inside_event_name() {// ───────────────────────────── property test ─────────────────────────//// The framer must NEVER panic on arbitrary byte input. TCP can hand us-// anything — partial codepoints, NUL bytes, fuzz noise. 100K random-// inputs is the project default for "no panic" parser invariants per-// `feedback_realignment_build_constraints.md`. The test does not assert-// what the framer yields, only that pushing arbitrary bytes and pulling-// events terminates without panic.+// anything — partial codepoints, NUL bytes, fuzz noise. Keep this in the+// same order of magnitude as the other Rust parser fuzz tests so+// `cargo test --workspace` remains practical in CI.use proptest::prelude::*;proptest! {#![proptest_config(ProptestConfig {- cases: 100_000,- // Disable shrinking timeout — 100K trivial cases run fast on- // CI and we want the fuzzer to actually shrink any panic it- // finds (vs. give up early).+ cases: 4_096,+ // We want the fuzzer to shrink any panic it finds instead of+ // giving up early.max_shrink_iters: 1024,..ProptestConfig::default()})]diff --git a/crates/headroom-py/src/lib.rs b/crates/headroom-py/src/lib.rsindex 9dac7b9dc..e47c9b649 100644--- a/crates/headroom-py/src/lib.rs+++ b/crates/headroom-py/src/lib.rs@@ -30,6 +30,7 @@ use headroom_core::transforms::tag_protector::{use headroom_core::transforms::{compress_openai_responses_live_zone as rust_compress_openai_responses_live_zone,detect as rust_detect_chain, is_json_array_of_dicts as rust_is_json_array_of_dicts,+ summarize_openai_responses_no_change_reason as rust_summarize_openai_responses_no_change_reason,AuthMode as RustLiveZoneAuthMode, ContentType as RustContentType,DetectionResult as RustDetectionResult, DiffCompressionResult, DiffCompressor,DiffCompressorConfig, DiffCompressorStats, LiveZoneOutcome,@@ -1498,7 +1499,7 @@ fn compress_openai_responses_live_zone(body: &[u8],auth_mode: &str,model: &str,-) -> (Py<PyBytes>, bool, u64, Vec<String>) {+) -> (Py<PyBytes>, bool, u64, Vec<String>, Option<String>) {let mode = match auth_mode.to_ascii_lowercase().as_str() {"payg" => RustLiveZoneAuthMode::Payg,"oauth" => RustLiveZoneAuthMode::OAuth,@@ -1519,11 +1520,13 @@ fn compress_openai_responses_live_zone(.into_iter().map(String::from).collect();+ let reason = rust_summarize_openai_responses_no_change_reason(&manifest).to_string();(PyBytes::new_bound(py, body).unbind(),false,saved,transforms,+ Some(reason),)}Ok(LiveZoneOutcome::Modified { new_body, manifest }) => {@@ -1541,12 +1544,19 @@ fn compress_openai_responses_live_zone(true,saved,transforms,+ None,)}Err(_) => {// BodyNotJson / NoMessagesArray are non-fatal: nothing to// compress, fall through to passthrough byte-for-byte.- (PyBytes::new_bound(py, body).unbind(), false, 0, Vec::new())+ (+ PyBytes::new_bound(py, body).unbind(),+ false,+ 0,+ Vec::new(),+ Some("dispatch_error".to_string()),+ )}}}diff --git a/headroom/_version.py b/headroom/_version.pyindex bbe9da5e6..07d29900a 100644--- a/headroom/_version.py+++ b/headroom/_version.py@@ -1,3 +1,3 @@"""Package version metadata."""-__version__ = "0.5.25"+__version__ = "0.9.1"diff --git a/headroom/cache/compression_store.py b/headroom/cache/compression_store.pyindex 810d1a07c..31d6d042b 100644--- a/headroom/cache/compression_store.py+++ b/headroom/cache/compression_store.py@@ -409,12 +409,7 @@ class CompressionStore:if entry is None:return []- try:- items = json.loads(entry.original_content)- if not isinstance(items, list):- return []- except json.JSONDecodeError:- return []+ items = self._search_items_from_original(entry.original_content)if not items:return []@@ -450,6 +445,149 @@ class CompressionStore:return results+ def _search_items_from_original(self, original_content: str) -> list[Any]:+ """Normalize cached originals into searchable items.++ CCR producers store different shapes:+ - SmartCrusher/search-style paths usually store JSON arrays.+ - Kompress stores the original plain text.+ - Some callers store JSON objects or scalar JSON values.++ Search should work for all of them. Preserve the legacy JSON-array+ result shape, but fall back to structured text chunks for everything+ else so `headroom_retrieve(hash, query=...)` can find plain-text+ originals.+ """++ try:+ parsed = json.loads(original_content)+ except json.JSONDecodeError:+ return self._plain_text_search_items(original_content)++ if isinstance(parsed, list):+ return parsed+ if isinstance(parsed, dict):+ return self._json_object_search_items(parsed)+ if isinstance(parsed, str):+ return self._plain_text_search_items(parsed)+ if parsed is None:+ return []+ return [{"type": "json_scalar", "value": parsed}]++ def _json_object_search_items(self, value: dict[str, Any]) -> list[dict[str, Any]]:+ """Return searchable leaf records for a JSON object."""++ items: list[dict[str, Any]] = []++ def walk(node: Any, path: str) -> None:+ if isinstance(node, dict):+ for key, child in node.items():+ child_path = f"{path}.{key}" if path else str(key)+ walk(child, child_path)+ return+ if isinstance(node, list):+ for idx, child in enumerate(node):+ walk(child, f"{path}[{idx}]")+ return+ if node is None:+ return+ items.append({"type": "json_leaf", "path": path, "value": node})++ walk(value, "")+ if items:+ return items+ return [{"type": "json_object", "value": value}]++ def _plain_text_search_items(self, text: str) -> list[dict[str, Any]]:+ """Chunk arbitrary text into searchable records.++ Line-aware chunks work well for logs/source. Word-window chunks handle+ Kompress originals, which are often long single-line text blobs.+ """++ if not text or not text.strip():+ return []++ normalized = text.replace("\r\n", "\n").replace("\r", "\n")+ lines = normalized.split("\n")+ if len(lines) > 1:+ return self._line_text_search_items(lines)++ words = normalized.split()+ if not words:+ return []+ max_words = 350+ overlap_words = 50+ if len(words) <= max_words:+ return [+ {+ "type": "text",+ "text": normalized,+ "chunk_index": 0,+ "word_start": 1,+ "word_end": len(words),+ }+ ]++ items: list[dict[str, Any]] = []+ start = 0+ chunk_index = 0+ step = max_words - overlap_words+ while start < len(words):+ end = min(len(words), start + max_words)+ items.append(+ {+ "type": "text",+ "text": " ".join(words[start:end]),+ "chunk_index": chunk_index,+ "word_start": start + 1,+ "word_end": end,+ }+ )+ if end == len(words):+ break+ start += step+ chunk_index += 1+ return items++ @staticmethod+ def _line_text_search_items(lines: list[str]) -> list[dict[str, Any]]:+ max_chars = 2000+ items: list[dict[str, Any]] = []+ current: list[str] = []+ line_start = 1+ char_count = 0++ for idx, line in enumerate(lines, start=1):+ line_len = len(line) + 1+ if current and char_count + line_len > max_chars:+ items.append(+ {+ "type": "text",+ "text": "\n".join(current),+ "chunk_index": len(items),+ "line_start": line_start,+ "line_end": idx - 1,+ }+ )+ current = []+ line_start = idx+ char_count = 0+ current.append(line)+ char_count += line_len++ if current:+ items.append(+ {+ "type": "text",+ "text": "\n".join(current),+ "chunk_index": len(items),+ "line_start": line_start,+ "line_end": len(lines),+ }+ )+ return items+def _get_entry_for_search(self,hash_key: str,diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex f0a8989d9..afc473a58 100644--- a/headroom/cli/proxy.py+++ b/headroom/cli/proxy.py@@ -6,6 +6,7 @@ from typing import Anyimport click+from headroom import paths as _pathsfrom headroom.providers.registry import resolve_api_overrides, resolve_api_targetsfrom headroom.proxy.modes import PROXY_MODE_TOKEN, normalize_proxy_mode@@ -191,6 +192,19 @@ def _get_env_bool(name: str, default: bool) -> bool:is_flag=True,help="Enable full message logging (request/response content stored for live feed)",)+ "--codex-wire-debug",+ is_flag=True,+ help="Enable local Codex wire snapshots and matching proxy.log frame traces.",+)+ "--codex-wire-debug-dir",+ default=None,+ help=(+ "Directory for Codex wire snapshots (default: "+ "~/.headroom/logs/codex_wire or workspace .headroom/logs/codex_wire)."+ ),+)@click.option("--budget",type=float,@@ -393,6 +407,8 @@ def proxy(anthropic_pre_upstream_memory_context_timeout_seconds: float | None,log_file: str | None,log_messages: bool,+ codex_wire_debug: bool,+ codex_wire_debug_dir: str | None,budget: float | None,code_aware_flag: bool | None,code_graph: bool,@@ -498,6 +514,12 @@ def proxy(if no_telemetry:os.environ["HEADROOM_TELEMETRY"] = "off"+ if codex_wire_debug or codex_wire_debug_dir:+ os.environ["HEADROOM_CODEX_WIRE_DEBUG"] = "1"+ os.environ["HEADROOM_CODEX_WIRE_DEBUG_DIR"] = codex_wire_debug_dir or str(+ _paths.codex_wire_debug_dir()+ )+# Stateless mode: suppress TOIN filesystem persistenceif is_stateless:os.environ["HEADROOM_TOIN_BACKEND"] = "none"diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex ea54e4d76..fc0eb0c2a 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -188,6 +188,7 @@ def _start_proxy(stdout=log_file,stderr=log_file,env=proxy_env,+ start_new_session=os.name == "posix",)# Wait for proxy to be ready (up to 45 seconds).@@ -242,6 +243,74 @@ def _setup_rtk(verbose: bool = False) -> Path | None:return rtk_path+def _remove_claude_rtk_hooks(settings_path: Path | None = None) -> bool:+ """Remove Headroom/rtk-managed Claude hook entries from settings.json.++ `rtk init --global --auto-patch` installs a Claude PreToolUse hook that+ points at an ``rtk-rewrite`` script. Unwrap should remove that hook without+ touching unrelated Claude settings or user-authored hooks.+ """++ path = settings_path or (Path.home() / ".claude" / "settings.json")+ if not path.exists():+ return False++ try:+ payload = json.loads(path.read_text(encoding="utf-8"))+ except (OSError, json.JSONDecodeError):+ return False+ if not isinstance(payload, dict):+ return False++ hooks = payload.get("hooks")+ if not isinstance(hooks, dict):+ return False++ changed = False+ for event, entries in list(hooks.items()):+ if not isinstance(entries, list):+ continue+ retained_entries: list[Any] = []+ for entry in entries:+ if not isinstance(entry, dict):+ retained_entries.append(entry)+ continue+ hook_items = entry.get("hooks")+ if not isinstance(hook_items, list):+ retained_entries.append(entry)+ continue+ retained_hooks = [+ item+ for item in hook_items+ if not (+ isinstance(item, dict) and "rtk-rewrite" in str(item.get("command", "")).lower()+ )+ ]+ if len(retained_hooks) != len(hook_items):+ changed = True+ if retained_hooks:+ retained_entries.append({**entry, "hooks": retained_hooks})+ elif len(retained_hooks) == len(hook_items):+ retained_entries.append(entry)+ else:+ changed = True+ if retained_entries:+ hooks[event] = retained_entries+ else:+ del hooks[event]+ changed = True++ if not changed:+ return False++ if hooks:+ payload["hooks"] = hooks+ else:+ payload.pop("hooks", None)+ path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")+ return True++def _setup_headroom_mcp(registrar: Any, port: int, *, verbose: bool = False, force: bool = False) -> None:@@ -454,6 +523,8 @@ _MEMORY_AGENTS_MARKER = "<!-- headroom:memory-instructions -->"# Codex config injection markers_CODEX_TOP_LEVEL_MARKER = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"_CODEX_END_MARKER = "# --- end Headroom ---"+_CODEX_MCP_MARKER = "# --- Headroom MCP server ---"+_CODEX_MCP_END = "# --- end Headroom MCP server ---"# File name used for the pre-wrap snapshot of ~/.codex/config.toml. The# snapshot lets `headroom unwrap codex` restore the exact prior state, even# if the user had their own `model_provider` / `[model_providers.*]` config@@ -469,7 +540,7 @@ def _codex_config_paths() -> tuple[Path, Path]:return config_file, backup_file-def _strip_codex_headroom_blocks(content: str) -> str:+def _strip_codex_headroom_blocks(content: str, *, remove_mcp: bool = False) -> str:"""Remove all Headroom-managed blocks from a Codex ``config.toml`` string.Returns the cleaned content. Safe to call on content that never contained@@ -478,19 +549,25 @@ def _strip_codex_headroom_blocks(content: str) -> str:"""import re+ def _remove_marker_span(text: str, start_marker: str, end_marker: str) -> str:+ while start_marker in text and end_marker in text:+ start = text.index(start_marker)+ end_idx = text.index(end_marker, start)+ if end_idx < start:+ break+ end = end_idx + len(end_marker)+ text = text[:start].rstrip("\n") + "\n" + text[end:].lstrip("\n")+ text = text.replace(start_marker + "\n", "")+ text = text.replace(end_marker + "\n", "")+ return text+# Remove any top-level-marker → end-marker span, possibly repeated.- while _CODEX_TOP_LEVEL_MARKER in content and _CODEX_END_MARKER in content:- start = content.index(_CODEX_TOP_LEVEL_MARKER)- end_idx = content.index(_CODEX_END_MARKER, start)- if end_idx < start:- break- end = end_idx + len(_CODEX_END_MARKER)- content = content[:start].rstrip("\n") + "\n" + content[end:].lstrip("\n")-- # Remove any stale top-level marker or end marker that lost its partner- # (e.g. a crashed prior wrap).- content = content.replace(_CODEX_TOP_LEVEL_MARKER + "\n", "")- content = content.replace(_CODEX_END_MARKER + "\n", "")+ content = _remove_marker_span(content, _CODEX_TOP_LEVEL_MARKER, _CODEX_END_MARKER)++ if remove_mcp:+ # Remove Headroom-managed MCP blocks written by `wrap codex`.+ content = _remove_marker_span(content, _CODEX_MCP_MARKER, _CODEX_MCP_END)+ content = _remove_marker_span(content, _MEMORY_MCP_MARKER, _MEMORY_MCP_END)# Strip any leftover top-level keys that older (or crashed) versions of# `wrap codex` may have written outside the marker block.@@ -673,7 +750,7 @@ def _restore_codex_provider_config() -> tuple[str, Path]:if config_file.exists():original = config_file.read_text()if _CODEX_TOP_LEVEL_MARKER in original or _CODEX_END_MARKER in original:- cleaned = _strip_codex_headroom_blocks(original)+ cleaned = _strip_codex_headroom_blocks(original, remove_mcp=True)if not cleaned.strip():# Nothing left but Headroom content — remove the file entirely# so Codex falls back to its default config.@@ -845,6 +922,56 @@ def _kill_proxy_by_pid(pid: int, port: int) -> bool:return False+def _stop_local_proxy_for_unwrap(port: int) -> str:+ """Stop a local Headroom proxy for durable unwrap commands.++ Returns a status string:+ * ``"stopped"``: a Headroom proxy was identified and stopped.+ * ``"not_running"``: nothing is listening on the requested port.+ * ``"unidentified"``: something is listening, but it did not expose+ Headroom's health/config payload, so we did not kill it.+ * ``"no_pid"``: the service looked like Headroom but did not expose a PID.+ * ``"failed"``: a PID was found but the port stayed bound after stop.+ """++ if not _check_proxy(port):+ return "not_running"++ running_config = _query_proxy_config(port)+ if running_config is None:+ return "unidentified"++ proxy_pid = running_config.get("pid")+ if proxy_pid is None:+ return "no_pid"++ try:+ pid = int(proxy_pid)+ except (TypeError, ValueError):+ return "no_pid"++ return "stopped" if _kill_proxy_by_pid(pid, port) else "failed"+++def _echo_unwrap_proxy_stop_status(status: str, port: int) -> None:+ """Print a human-readable proxy stop result for unwrap commands."""++ if status == "stopped":+ click.echo(f" Stopped local Headroom proxy on port {port}.")+ elif status == "not_running":+ click.echo(f" No local Headroom proxy detected on port {port}.")+ elif status == "unidentified":+ click.echo(+ f" Warning: port {port} is in use, but it did not look like Headroom; left it running."+ )+ elif status == "no_pid":+ click.echo(+ f" Warning: Headroom proxy on port {port} did not expose a PID; left it running."+ )+ else:+ click.echo(f" Warning: failed to stop Headroom proxy on port {port}; stop it manually.")++def _find_persistent_manifest(port: int) -> Any:"""Return a matching persistent deployment manifest for the requested port."""from headroom.install.state import list_manifests@@ -1069,6 +1196,12 @@ def _make_cleanup(proxy_proc_holder: list, port: int = 8787) -> Any:return cleanup+def _ignore_child_sigint(signum: int | None = None, frame: Any = None) -> None:+ """Keep the wrapper alive when Ctrl-C is intended for the child CLI."""++ return None++def _launch_tool(binary: str,args: tuple,@@ -1090,7 +1223,7 @@ def _launch_tool("""Common logic: start proxy, launch tool, clean up."""proxy_holder: list[subprocess.Popen | None] = [None]cleanup = _make_cleanup(proxy_holder, port)- signal.signal(signal.SIGINT, cleanup)+ signal.signal(signal.SIGINT, _ignore_child_sigint)signal.signal(signal.SIGTERM, cleanup)try:@@ -1431,7 +1564,7 @@ def claude(# Setup rtk before launching (Claude-specific)proxy_holder: list[subprocess.Popen | None] = [None]cleanup = _make_cleanup(proxy_holder, port)- signal.signal(signal.SIGINT, cleanup)+ signal.signal(signal.SIGINT, _ignore_child_sigint)signal.signal(signal.SIGTERM, cleanup)# Memory sync BEFORE proxy startup — sync headroom DB ↔ Claude's files@@ -1526,6 +1659,62 @@ def claude(cleanup()+# =============================================================================+# Claude Code (unwrap)+# =============================================================================++[email protected]("claude")[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-stop-proxy", is_flag=True, help="Do not stop the local Headroom proxy")[email protected]("--keep-mcp", is_flag=True, help="Keep Headroom MCP registrations")[email protected]("--keep-rtk", is_flag=True, help="Keep rtk Claude hooks")+def unwrap_claude(+ port: int,+ no_stop_proxy: bool,+ keep_mcp: bool,+ keep_rtk: bool,+) -> None:+ """Undo durable setup from ``headroom wrap claude``."""+ click.echo()+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(" ║ HEADROOM UNWRAP: CLAUDE ║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()++ if not keep_mcp:+ from headroom.mcp_registry import ClaudeRegistrar++ registrar = ClaudeRegistrar()+ if registrar.detect():+ removed_headroom = registrar.unregister_server("headroom")+ removed_code_graph = registrar.unregister_server(_CBM_MCP_SERVER_NAME)+ if removed_headroom:+ click.echo(" Removed Headroom MCP retrieve tool from Claude.")+ else:+ click.echo(" Headroom MCP retrieve tool was not registered in Claude.")+ if removed_code_graph:+ click.echo(" Removed code graph MCP server from Claude.")+ else:+ click.echo(" Claude Code not detected; skipped MCP cleanup.")+ else:+ click.echo(" Kept Claude MCP registrations (--keep-mcp).")++ if not keep_rtk:+ if _remove_claude_rtk_hooks():+ click.echo(" Removed rtk Claude hook from settings.json.")+ else:+ click.echo(" No rtk Claude hook found in settings.json.")+ else:+ click.echo(" Kept rtk Claude hooks (--keep-rtk).")++ click.echo()+ click.echo("✓ Claude is no longer durably wrapped by Headroom.")+ if not no_stop_proxy:+ _echo_unwrap_proxy_stop_status(_stop_local_proxy_for_unwrap(port), port)+ click.echo()++# =============================================================================# GitHub Copilot CLI# =============================================================================@@ -2320,11 +2509,15 @@ def openclaw(@unwrap.command("openclaw")[email protected]("--proxy-port", default=8787, type=int, help="Headroom proxy port")[email protected]("--no-stop-proxy", is_flag=True, help="Do not stop the local Headroom proxy")@click.option("--no-restart", is_flag=True, help="Do not restart OpenClaw gateway at the end")@click.option("--verbose", "-v", is_flag=True, help="Verbose output")@click.option("--prepare-only", is_flag=True, hidden=True)@click.option("--existing-entry-json", default=None, hidden=True)def unwrap_openclaw(+ proxy_port: int,+ no_stop_proxy: bool,no_restart: bool,verbose: bool,prepare_only: bool,@@ -2384,6 +2577,8 @@ def unwrap_openclaw(click.echo("✓ OpenClaw Headroom wrap removed.")click.echo(" Plugin: headroom (installed, disabled)")click.echo(" Slot: plugins.slots.contextEngine = legacy")+ if not no_stop_proxy:+ _echo_unwrap_proxy_stop_status(_stop_local_proxy_for_unwrap(proxy_port), proxy_port)click.echo()@@ -2393,7 +2588,9 @@ def unwrap_openclaw(@unwrap.command("codex")-def unwrap_codex() -> None:[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-stop-proxy", is_flag=True, help="Do not stop the local Headroom proxy")+def unwrap_codex(port: int, no_stop_proxy: bool) -> None:"""Undo ``headroom wrap codex`` edits to ``~/.codex/config.toml``.Behaviour:@@ -2430,4 +2627,6 @@ def unwrap_codex() -> None:click.echo()click.echo("✓ Codex is no longer routed through the Headroom proxy.")+ if not no_stop_proxy:+ _echo_unwrap_proxy_stop_status(_stop_local_proxy_for_unwrap(port), port)click.echo()diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.htmlindex a1db508b6..7d44b366a 100644--- a/headroom/dashboard/templates/dashboard.html+++ b/headroom/dashboard/templates/dashboard.html@@ -99,29 +99,34 @@<main class="p-6 max-w-7xl mx-auto"><template x-if="viewMode === 'session'"><div>- <!-- Hero Metrics (reordered: Savings $ -> Tokens Saved % -> Quality Confidence -> Overhead) -->+ <!-- Hero Metrics (reordered: Savings $ -> Compression % -> Quality Confidence -> Overhead) --><div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-6">- <!-- Savings ($) - Compression only, priced at model list rate -->+ <!-- Savings ($) - proxy compression only, priced at model list rate --><div class="bg-surface rounded-lg p-4 border border-border">- <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Compression Savings</div>+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Proxy $ Saved</div><div class="flex items-baseline gap-2"><span class="text-3xl font-light tabular-nums text-emerald-400" x-text="'$' + formatCurrency(stats.cost?.savings_usd || 0)"></span></div><div class="mt-2 text-xs text-gray-500"><span x-show="stats.cost?.savings_usd > 0"- x-text="formatNumber(stats.tokens?.saved || 0) + ' tokens at model list price'"></span>+ x-text="formatNumber(stats.tokens?.proxy_compression_saved || 0) + ' proxy tokens only; RTK excluded from $'"></span><span x-show="!(stats.cost?.savings_usd > 0)"x-text="formatNumber(stats.requests?.total || 0) + ' requests processed'"></span></div></div>- <!-- Tokens Saved (%) -->+ <!-- Token Savings (%) --><div class="bg-surface rounded-lg p-4 border border-border">- <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Tokens Saved</div>+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Token Savings</div><div class="flex items-baseline gap-2"><span class="text-3xl font-light tabular-nums text-accent" x-text="formatNumber(stats.tokens?.saved || 0)"></span><span class="text-sm text-accent" x-text="(stats.tokens?.savings_percent || 0).toFixed(1) + '%'"></span></div>+ <div class="mt-1 text-xs text-gray-500 leading-relaxed">+ <span x-text="'Proxy ' + formatNumber(stats.tokens?.proxy_compression_saved || 0) + ' (' + proxyShareOfTotal.toFixed(1) + '%)'"></span>+ <span class="mx-1 text-gray-600">/</span>+ <span x-text="'RTK ' + formatNumber(stats.tokens?.rtk_saved || 0) + ' (' + rtkShareOfTotal.toFixed(1) + '%)'"></span>+ </div><div class="mt-2 h-8"><svg class="w-full h-full" viewBox="0 0 100 32" preserveAspectRatio="none"><defs>@@ -166,7 +171,7 @@<div><div class="text-xs text-gray-500 mb-1">Compression</div><div class="text-2xl font-light tabular-nums text-emerald-400" x-text="'$' + formatCurrency(stats.cost?.compression_savings_usd || 0)"></div>- <div class="text-xs text-gray-500" x-text="formatNumber(stats.tokens?.saved || 0) + ' tokens removed'"></div>+ <div class="text-xs text-gray-500" x-text="formatNumber(stats.tokens?.proxy_compression_saved || 0) + ' proxy tokens removed'"></div></div><template x-if="(stats.cost?.cache_savings_usd || 0) > 0"><div>@@ -692,6 +697,14 @@<span class="text-sm text-gray-400">Before Compression</span><span class="font-mono text-sm" x-text="formatNumber(stats.tokens?.total_before_compression || 0)"></span></div>+ <div class="flex justify-between items-center">+ <span class="text-sm text-gray-400">RTK Filtered</span>+ <span class="font-mono text-sm text-emerald-400" x-text="formatNumber(stats.tokens?.rtk_saved || 0)"></span>+ </div>+ <div class="flex justify-between items-center">+ <span class="text-sm text-gray-400">Proxy Removed</span>+ <span class="font-mono text-sm text-accent" x-text="formatNumber(stats.tokens?.proxy_compression_saved || 0)"></span>+ </div><div class="flex justify-between items-center"><span class="text-sm text-gray-400">After Compression (sent)</span><span class="font-mono text-sm" x-text="formatNumber(stats.tokens?.input || 0)"></span>@@ -1755,10 +1768,26 @@return Math.min((tokens / max) * 100, 100);},+ get compressionTotalBefore() {+ return this.stats.tokens?.total_before_compression || 0;+ },++ get proxyShareOfTotal() {+ const total = this.compressionTotalBefore;+ if (total <= 0) return 0;+ return (this.stats.tokens?.proxy_compression_saved || 0) / total * 100;+ },++ get rtkShareOfTotal() {+ const total = this.compressionTotalBefore;+ if (total <= 0) return 0;+ return (this.stats.tokens?.rtk_saved || 0) / total * 100;+ },+// --- Compression Confidence ---get confidenceLevel() {- const saved = this.stats.tokens?.saved || 0;+ const saved = this.stats.tokens?.proxy_compression_saved || 0;if (saved === 0) return 'none';const signals = this.stats.waste_signals || {};const totalWaste = Object.values(signals).reduce((a, b) => a + b, 0);@@ -1785,7 +1814,7 @@},get confidenceDetail() {- const saved = this.stats.tokens?.saved || 0;+ const saved = this.stats.tokens?.proxy_compression_saved || 0;if (saved === 0) return 'No compression yet';const signals = this.stats.waste_signals || {};const totalWaste = Object.values(signals).reduce((a, b) => a + b, 0);diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.pyindex 99855802a..0eed221ef 100644--- a/headroom/proxy/cost.py+++ b/headroom/proxy/cost.py@@ -387,7 +387,9 @@ def build_session_summary(best_compression = best["savings_pct"]best_detail = f"{best['original']:,} → {best['optimized']:,} tokens"- # Cost summary — savings_usd is compression savings at model list price (monotonic)+ # Cost summary — dollar savings are proxy-compression only at model list+ # price. rtk tokens are counted in token savings but have no model-specific+ # price because they never reached the proxy request.cost_stats = proxy.cost_tracker.stats() if proxy.cost_tracker else {}cost_with = cost_stats.get("cost_with_headroom_usd", 0.0)compression_savings = cost_stats.get("savings_usd", 0.0)@@ -412,6 +414,9 @@ def build_session_summary("best_compression_pct": best_compression,"best_detail": best_detail,"total_tokens_removed": metrics.tokens_saved_total,+ "rtk_tokens_avoided": cli_tokens_avoided,+ "total_tokens_saved_with_rtk": metrics.tokens_saved_total + cli_tokens_avoided,+ "total_tokens_before_with_rtk": total_tokens_before,},"uncompressed_requests": {k: v for k, v in uncompressed_reasons.items() if v > 0},"cost": {@@ -422,6 +427,11 @@ def build_session_summary("breakdown": {"cache_savings_usd": round(cache_net, 2),"compression_savings_usd": round(compression_savings, 2),+ "rtk_savings_usd": None,+ "rtk_savings_note": (+ "rtk tokens are included in token savings only; dollar savings "+ "use proxy compression tokens at model list price."+ ),},},}@@ -470,6 +480,19 @@ class CostTracker:self._api_cache_write_1h_by_model: dict[str, int] = {}self._api_uncached_by_model: dict[str, int] = {}+ def reset_runtime(self) -> None:+ """Reset in-memory cost/token counters for local test/debug use."""+ self._costs.clear()+ self._last_prune_time = datetime.now()+ self._tokens_saved_by_model.clear()+ self._tokens_sent_by_model.clear()+ self._requests_by_model.clear()+ self._api_cache_read_by_model.clear()+ self._api_cache_write_by_model.clear()+ self._api_cache_write_5m_by_model.clear()+ self._api_cache_write_1h_by_model.clear()+ self._api_uncached_by_model.clear()+# Cache resolved model names to avoid repeated litellm lookups.# This is critical: litellm.cost_per_token() is synchronous and can block# the async event loop if it triggers I/O (lazy model info download).diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 8a40e8d60..7ddd293a8 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -17,7 +17,7 @@ import uuidfrom datetime import datetimefrom typing import TYPE_CHECKING, Any-from headroom.proxy.helpers import jitter_delay_ms+from headroom.proxy.helpers import _headroom_bypass_enabled, jitter_delay_msfrom headroom.proxy.stage_timer import StageTimer, emit_stage_timings_logfrom headroom.proxy.ws_session_registry import (TerminationCause,@@ -51,7 +51,20 @@ RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS = 2.0WS_FIRST_FRAME_TIMEOUT_SECONDS = 60.0-def _extract_responses_usage(event: dict[str, Any]) -> tuple[int, int, int, int]:+def _infer_openai_cache_write_tokens(input_tokens: int, cache_read_tokens: int) -> int:+ """Infer OpenAI automatic prompt-cache writes from uncached input tokens.++ OpenAI reports prompt-cache reads as ``cached_tokens`` but does not expose a+ separate write counter. For dashboard observability, the uncached portion of+ a Codex/OpenAI request is the best available write-volume proxy. OpenAI has+ no write premium in our cache economics, so this affects cache-write+ counters, not dollar savings.+ """++ return max(input_tokens - cache_read_tokens, 0)+++def _extract_responses_usage(event: dict[str, Any]) -> tuple[int, int, int, int, int]:"""Return input/output/cache usage from a Responses event.Codex WebSocket streams include usage on ``response.completed`` events.@@ -61,14 +74,14 @@ def _extract_responses_usage(event: dict[str, Any]) -> tuple[int, int, int, int]"""if event.get("type") != "response.completed":- return 0, 0, 0, 0+ return 0, 0, 0, 0, 0response = event.get("response")if not isinstance(response, dict):response = {}usage = response.get("usage") or event.get("usage")if not isinstance(usage, dict):- return 0, 0, 0, 0+ return 0, 0, 0, 0, 0def _int(value: Any) -> int:try:@@ -80,8 +93,9 @@ def _extract_responses_usage(event: dict[str, Any]) -> tuple[int, int, int, int]output_tokens = _int(usage.get("output_tokens"))details = usage.get("input_tokens_details")cached_tokens = _int(details.get("cached_tokens")) if isinstance(details, dict) else 0+ cache_write_tokens = _infer_openai_cache_write_tokens(input_tokens, cached_tokens)uncached_tokens = max(input_tokens - cached_tokens, 0)- return input_tokens, output_tokens, cached_tokens, uncached_tokens+ return input_tokens, output_tokens, cached_tokens, cache_write_tokens, uncached_tokensdef _decode_openai_bearer_payload(headers: dict[str, str]) -> dict[str, Any] | None:@@ -134,6 +148,18 @@ def _resolve_codex_routing_headers(headers: dict[str, str]) -> tuple[dict[str, sclass OpenAIHandlerMixin:"""Mixin providing OpenAI API handler methods for HeadroomProxy."""+ OPENAI_RESPONSES_ROUTER_MIN_BYTES = 512+ OPENAI_RESPONSES_OUTPUT_TYPES = {+ "function_call_output",+ "local_shell_call_output",+ "apply_patch_call_output",+ }++ @staticmethod+ def _headroom_bypass_enabled(headers: Any) -> bool:+ """Return True when inbound headers request full passthrough."""+ return _headroom_bypass_enabled(headers)+@staticmethoddef _strict_previous_turn_frozen_count(messages: list[dict[str, Any]],@@ -171,6 +197,230 @@ class OpenAIHandlerMixin:changed += 1return restored, changed+ def _compress_openai_responses_live_text_units_with_router(+ self,+ payload: dict[str, Any],+ *,+ model: str,+ request_id: str,+ ) -> tuple[dict[str, Any], bool, int, list[str]]:+ """Run ContentRouter on OpenAI Responses text units.++ This is the Responses provider scaffold: it extracts text-bearing+ request slots into provider-neutral ``CompressionUnit`` objects, lets+ the shared router enforce role/type policy and choose compressors, then+ splices accepted replacements back into the Responses payload. Opaque+ items such as reasoning, compaction, tool calls, and non-string outputs+ are intentionally not exposed as text units.+ """+ items = payload.get("input") or payload.get("messages")+ if not isinstance(items, list):+ return payload, False, 0, []+ try:+ from headroom.transforms.compression_units import (+ CompressionUnit,+ RoutedCompressionUnit,+ compress_units_with_router,+ find_content_router,+ )+ except Exception as exc:+ logger.debug(+ "[%s] CompressionUnit adapter unavailable: %s",+ request_id,+ exc,+ )+ return payload, False, 0, []++ router = find_content_router(self.openai_pipeline)+ if router is None:+ logger.debug("[%s] OpenAI Responses ContentRouter unavailable", request_id)+ return payload, False, 0, []++ try:+ tokenizer = self.openai_provider.get_token_counter(model)+ except Exception as exc:+ logger.debug(+ "[%s] OpenAI Responses ContentRouter tokenizer unavailable: %s",+ request_id,+ exc,+ )+ return payload, False, 0, []++ def _slot_text(item: dict[str, Any]) -> tuple[str, tuple[str, int | None]] | None:+ type_tag = item.get("type")+ if type_tag in self.OPENAI_RESPONSES_OUTPUT_TYPES:+ output = item.get("output")+ if isinstance(output, str):+ return output, ("output", None)+ return None++ if type_tag == "message":+ content = item.get("content")+ if isinstance(content, str):+ return content, ("message_string", None)+ if isinstance(content, list):+ for idx, part in enumerate(content):+ if isinstance(part, str):+ return part, ("message_list_string", idx)+ if not isinstance(part, dict):+ continue+ if part.get("type") not in ("input_text", "text", "output_text"):+ continue+ text = part.get("text")+ if isinstance(text, str):+ return text, ("message_part", idx)+ return None++ def _set_slot_text(+ item: dict[str, Any],+ slot: tuple[str, int | None],+ replacement: str,+ ) -> None:+ kind, part_idx = slot+ if kind == "output":+ item["output"] = replacement+ elif kind == "message_string":+ item["content"] = replacement+ elif kind == "message_part" and part_idx is not None:+ content = item.get("content")+ if isinstance(content, list) and part_idx < len(content):+ part = content[part_idx]+ if isinstance(part, dict):+ part["text"] = replacement+ elif kind == "message_list_string" and part_idx is not None:+ content = item.get("content")+ if isinstance(content, list) and part_idx < len(content):+ content[part_idx] = replacement++ headroom_retrieve_call_ids: set[str] = set()+ for item in items:+ if not isinstance(item, dict):+ continue+ if item.get("type") != "function_call":+ continue+ name = item.get("name")+ if isinstance(name, str) and (+ name == "headroom_retrieve" or name.endswith("__headroom_retrieve")+ ):+ call_id = item.get("call_id")+ if isinstance(call_id, str) and call_id:+ headroom_retrieve_call_ids.add(call_id)++ candidates: list[tuple[int, tuple[str, int | None], str]] = []+ for idx, item in enumerate(items):+ if not isinstance(item, dict):+ continue+ item_type = item.get("type")+ if item_type in self.OPENAI_RESPONSES_OUTPUT_TYPES:+ call_id = item.get("call_id")+ if isinstance(call_id, str) and call_id in headroom_retrieve_call_ids:+ continue+ slot = _slot_text(item)+ if slot is not None:+ text, slot_ref = slot+ candidates.append((idx, slot_ref, text))+ elif item_type == "message":+ slot = _slot_text(item)+ if slot is not None:+ text, slot_ref = slot+ candidates.append((idx, slot_ref, text))++ if not candidates:+ return payload, False, 0, []++ updated = copy.deepcopy(payload)+ updated_items = updated.get("input") or updated.get("messages")+ if not isinstance(updated_items, list):+ return payload, False, 0, []++ modified = False+ tokens_saved_total = 0+ transforms: list[str] = []+ routed_units: list[RoutedCompressionUnit] = []++ for item_idx, slot_ref, original_text in candidates:+ item = items[item_idx] if item_idx < len(items) else {}+ item_type = item.get("type", "unknown") if isinstance(item, dict) else "unknown"+ role = str(item.get("role") or "tool") if isinstance(item, dict) else "tool"+ unit = CompressionUnit(+ text=original_text,+ provider="openai",+ endpoint="responses",+ role=role,+ item_type=str(item_type),+ cache_zone="live",+ mutable=True,+ min_bytes=self.OPENAI_RESPONSES_ROUTER_MIN_BYTES,+ )+ routed_units.append(RoutedCompressionUnit(unit=unit, slot=(item_idx, slot_ref)))++ for slot, result in compress_units_with_router(+ routed_units,+ router=router,+ tokenizer=tokenizer,+ ):+ if not result.modified:+ continue++ item_idx, slot_ref = slot+ target_item = updated_items[item_idx]+ if not isinstance(target_item, dict):+ continue+ _set_slot_text(target_item, slot_ref, result.compressed)+ modified = True+ tokens_saved_total += result.tokens_saved+ for transform in result.transforms_applied:+ if transform not in transforms:+ transforms.append(transform)++ return updated, modified, tokens_saved_total, transforms++ def _compress_openai_responses_payload(+ self,+ payload: dict[str, Any],+ *,+ model: str,+ request_id: str,+ ) -> tuple[dict[str, Any], bool, int, list[str], str | None, int, int]:+ """Compress an OpenAI Responses payload through the shared router.++ Provider adapters pass only the inner Responses payload here. This+ function is envelope-agnostic: it extracts Responses text slots into+ provider-neutral compression units, lets ContentRouter choose the+ compressor, then splices accepted replacements back into the payload.+ """++ input_bytes = json.dumps(payload).encode("utf-8")+ working = payload+ modified = False+ tokens_saved = 0+ transforms: list[str] = []+ reason: str | None = None++ router_payload, router_modified, router_saved, router_transforms = (+ self._compress_openai_responses_live_text_units_with_router(+ working,+ model=model,+ request_id=request_id,+ )+ )+ if router_modified:+ working = router_payload+ modified = True+ reason = None+ tokens_saved += int(router_saved)+ transforms.extend(router_transforms)+ else:+ reason = "router_no_compression"++ deduped: list[str] = []+ for transform in transforms:+ if transform not in deduped:+ deduped.append(transform)++ output_bytes = json.dumps(working).encode("utf-8")+ return working, modified, tokens_saved, deduped, reason, len(input_bytes), len(output_bytes)+async def handle_openai_chat(self,request: Request,@@ -270,10 +520,7 @@ class OpenAIHandlerMixin:stream = body.get("stream", False)# Bypass: skip ALL compression for explicit opt-out- _bypass = (- request.headers.get("x-headroom-bypass", "").lower() == "true"- or request.headers.get("x-headroom-mode", "").lower() == "passthrough"- )+ _bypass = self._headroom_bypass_enabled(request.headers)if _bypass:logger.info(f"[{request_id}] Bypass: skipping compression (header)")@@ -1082,9 +1329,13 @@ class OpenAIHandlerMixin:)# Update prefix cache tracker for next turn+ cache_write_tokens = _infer_openai_cache_write_tokens(+ total_input_tokens,+ cache_read_tokens,+ )openai_prefix_tracker.update_from_response(cache_read_tokens=cache_read_tokens,- cache_write_tokens=0, # OpenAI doesn't report write tokens+ cache_write_tokens=cache_write_tokens,messages=optimized_messages,)@@ -1097,6 +1348,7 @@ class OpenAIHandlerMixin:tokens_saved,optimized_tokens,cache_read_tokens=cache_read_tokens,+ cache_write_tokens=cache_write_tokens,uncached_tokens=uncached_input_tokens,)@@ -1178,6 +1430,7 @@ class OpenAIHandlerMixin:pipeline_timing=pipeline_timing,waste_signals=waste_signals_dict,cache_read_tokens=cache_read_tokens,+ cache_write_tokens=cache_write_tokens,uncached_input_tokens=uncached_input_tokens,)@@ -1325,6 +1578,12 @@ class OpenAIHandlerMixin:model = body.get("model", "unknown")stream = body.get("stream", False)+ _bypass = self._headroom_bypass_enabled(request.headers)+ if _bypass:+ logger.info(+ "[%s] Responses passthrough reason=bypass_header mutation=disabled",+ request_id,+ )from headroom.proxy.helpers import capture_codex_wire_debug@@ -1450,7 +1709,7 @@ class OpenAIHandlerMixin:optimization_latency = (time.time() - start_time) * 1000# Memory: inject context and tools for Responses API requests- if self.memory_handler and memory_user_id:+ if self.memory_handler and memory_user_id and not _bypass:try:# Memory context now routes exclusively to the live-zone tail# (latest non-frozen user item). Instructions are part of the@@ -1582,6 +1841,11 @@ class OpenAIHandlerMixin:logger.info(f"[{request_id}] Memory: Injected memory tools (openai/responses)")except Exception as e:logger.warning(f"[{request_id}] Memory injection failed (responses): {e}")+ elif self.memory_handler and memory_user_id and _bypass:+ logger.info(+ "[%s] Responses memory passthrough reason=bypass_header",+ request_id,+ )# /v1/responses is OpenAI-specific (Codex) — always routes direct.# LiteLLM/AnyLLM backends use /v1/chat/completions or /v1/messages.@@ -1611,42 +1875,45 @@ class OpenAIHandlerMixin:# invoking the same dispatcher in-process via `headroom._core`.# All policy gating already happened upstream (auth_mode classify,# CompressionPolicy resolve at request entry).- if self.config.optimize:+ if self.config.optimize and not _bypass:try:- from headroom._core import (- compress_openai_responses_live_zone as _rust_compress_responses,- )-- _input_bytes = json.dumps(body).encode("utf-8")(- _new_bytes,+ body,_modified,- _rust_tokens_saved,- _rust_transforms,- ) = _rust_compress_responses(- _input_bytes,- auth_mode.value,- model,+ _tokens_saved,+ _transforms,+ _reason,+ _bytes_before,+ _bytes_after,+ ) = self._compress_openai_responses_payload(+ body,+ model=model,+ request_id=request_id,)if _modified:- body = json.loads(_new_bytes)- tokens_saved = int(_rust_tokens_saved)+ tokens_saved = int(_tokens_saved)optimized_tokens = max(0, original_tokens - tokens_saved)- transforms_applied = [- "openai_responses_live_zone",- *_rust_transforms,- *list(transforms_applied),- ]+ transforms_applied = [*_transforms, *list(transforms_applied)]logger.info("[%s] /v1/responses compressed %d→%d bytes ""(%d tokens saved, auth_mode=%s, transforms=%s)",request_id,- len(_input_bytes),- len(_new_bytes),+ _bytes_before,+ _bytes_after,tokens_saved,auth_mode.value,transforms_applied,)+ else:+ logger.info(+ "[%s] /v1/responses compression passthrough "+ "reason=%s bytes=%d auth_mode=%s model=%s",+ request_id,+ _reason or "no_compression",+ _bytes_before,+ auth_mode.value,+ model or "unknown",+ )except Exception as _e:logger.warning(f"[{request_id}] /v1/responses compression failed; "@@ -1719,11 +1986,25 @@ class OpenAIHandlerMixin:total_input_tokens = original_tokens # fallbackoutput_tokens = 0+ cache_read_tokens = 0try:resp_json = response.json()usage = resp_json.get("usage", {})- total_input_tokens = usage.get("input_tokens", original_tokens)- output_tokens = usage.get("output_tokens", 0)++ def _usage_int(value: Any, default: int = 0) -> int:+ try:+ return max(int(value), 0)+ except (TypeError, ValueError):+ return default++ total_input_tokens = _usage_int(+ usage.get("input_tokens"),+ original_tokens,+ )+ output_tokens = _usage_int(usage.get("output_tokens"))+ details = usage.get("input_tokens_details")+ if isinstance(details, dict):+ cache_read_tokens = _usage_int(details.get("cached_tokens"))except (KeyError, TypeError, AttributeError) as e:logger.debug(f"[{request_id}] Failed to extract cached tokens from OpenAI passthrough response: {e}"@@ -1805,7 +2086,33 @@ class OpenAIHandlerMixin:)if self.cost_tracker:- self.cost_tracker.record_tokens(model, tokens_saved, total_input_tokens)+ cache_write_tokens = _infer_openai_cache_write_tokens(+ total_input_tokens,+ cache_read_tokens,+ )+ uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens)+ self.cost_tracker.record_tokens(+ model,+ tokens_saved,+ total_input_tokens,+ cache_read_tokens=cache_read_tokens,+ cache_write_tokens=cache_write_tokens,+ uncached_tokens=uncached_input_tokens,+ )+ else:+ cache_write_tokens = _infer_openai_cache_write_tokens(+ total_input_tokens,+ cache_read_tokens,+ )+ uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens)++ effective_optimized_tokens = (+ total_input_tokens if total_input_tokens > 0 else optimized_tokens+ )+ effective_original_tokens = max(+ original_tokens,+ effective_optimized_tokens + tokens_saved,+ )_resp_log_tags = {**(tags or {}),@@ -1821,6 +2128,9 @@ class OpenAIHandlerMixin:tokens_saved=tokens_saved,latency_ms=total_latency,overhead_ms=optimization_latency,+ cache_read_tokens=cache_read_tokens,+ cache_write_tokens=cache_write_tokens,+ uncached_input_tokens=uncached_input_tokens,)# Per-request log entry for /transformations/feed +@@ -1837,12 +2147,12 @@ class OpenAIHandlerMixin:timestamp=datetime.now().isoformat(),provider="openai",model=model,- input_tokens_original=original_tokens,- input_tokens_optimized=optimized_tokens,+ input_tokens_original=effective_original_tokens,+ input_tokens_optimized=effective_optimized_tokens,output_tokens=output_tokens,tokens_saved=tokens_saved,- savings_percent=(tokens_saved / original_tokens * 100)- if original_tokens > 0+ savings_percent=(tokens_saved / effective_original_tokens * 100)+ if effective_original_tokens > 0else 0,optimization_latency_ms=optimization_latency,total_latency_ms=total_latency,@@ -2204,6 +2514,27 @@ class OpenAIHandlerMixin:# via `_maybe_compress_response_create_frame` in# `_client_to_upstream` so long-lived subscription Codex# sessions get savings on every turn, not just the first.++ def _log_ws_passthrough(+ reason: str,+ *,+ frame_index: int,+ raw_bytes: int,+ frame_type: str = "",+ model: str = "",+ ) -> None:+ logger.info(+ "[%s] WS /v1/responses frame passthrough "+ "reason=%s frame=%d bytes=%d type=%s auth_mode=%s model=%s",+ request_id,+ reason,+ frame_index,+ raw_bytes,+ frame_type or "unknown",+ classify_auth_mode(ws_headers).value,+ model or "unknown",+ )+body: dict[str, Any] = {}tokens_saved = 0transforms_applied: list[str] = []@@ -2216,8 +2547,21 @@ class OpenAIHandlerMixin:ws_input_tokens_total = 0ws_output_tokens_total = 0ws_cache_read_tokens_total = 0+ ws_cache_write_tokens_total = 0ws_uncached_input_tokens_total = 0+ ws_recorded_input_tokens_total = 0+ ws_recorded_output_tokens_total = 0+ ws_recorded_cache_read_tokens_total = 0+ ws_recorded_cache_write_tokens_total = 0+ ws_recorded_uncached_input_tokens_total = 0+ ws_recorded_tokens_saved_total = 0ws_response_create_frames = 1+ _ws_bypass = self._headroom_bypass_enabled(ws_headers)+ if _ws_bypass:+ logger.info(+ "[%s] WS /v1/responses passthrough reason=bypass_header mutation=disabled",+ request_id,+ )capture_codex_wire_debug("ws_inbound_first_frame",@@ -2233,7 +2577,7 @@ class OpenAIHandlerMixin:# --- Memory: inject context, tools, and instructions ---memory_user_id: str | None = None- if self.memory_handler and body:+ if self.memory_handler and body and not _ws_bypass:memory_user_id = ws_headers.get("x-headroom-user-id",os.environ.get("USER", os.environ.get("USERNAME", "default")),@@ -2367,6 +2711,11 @@ class OpenAIHandlerMixin:first_msg_raw = json.dumps(body)except Exception as e:logger.warning(f"[{request_id}] WS Memory injection failed: {e}")+ elif self.memory_handler and body and _ws_bypass:+ logger.info(+ "[%s] WS memory passthrough reason=bypass_header",+ request_id,+ )# Hot-fix follow-up to PR #406 — inline Rust compression on the# WS first frame before forwarding upstream. PR #406 enabled@@ -2391,12 +2740,8 @@ class OpenAIHandlerMixin:# internal errors), but we wrap the call site in try/except# anyway so a JSON-shape edge case can never break the WS# session.- if self.config.optimize:+ if self.config.optimize and not _ws_bypass:try:- from headroom._core import (- compress_openai_responses_live_zone as _rust_compress_responses,- )-_ws_auth_mode = classify_auth_mode(ws_headers)try:_send_body = json.loads(first_msg_raw)@@ -2410,33 +2755,28 @@ class OpenAIHandlerMixin:_inner = _send_body["response"] if _wrapped else _send_body_model = (_inner.get("model") if isinstance(_inner, dict) else None) or ""- _inner_bytes = json.dumps(_inner).encode("utf-8")(- _new_bytes,+ _new_inner,_modified,- _ws_rust_saved,- _ws_rust_transforms,- ) = _rust_compress_responses(- _inner_bytes,- _ws_auth_mode.value,- _model,+ _ws_saved,+ _ws_transforms,+ _ws_reason,+ _bytes_before,+ _bytes_after,+ ) = self._compress_openai_responses_payload(+ _inner,+ model=_model,+ request_id=request_id,)if _modified:- try:- _new_inner = json.loads(_new_bytes)- except json.JSONDecodeError:- _new_inner = Noneif isinstance(_new_inner, dict):if _wrapped:_send_body["response"] = _new_innerelse:_send_body = _new_innerfirst_msg_raw = json.dumps(_send_body)- tokens_saved += int(_ws_rust_saved)- for _t in (- "openai_responses_ws_live_zone",- *list(_ws_rust_transforms),- ):+ tokens_saved += int(_ws_saved)+ for _t in _ws_transforms:if _t not in transforms_applied:transforms_applied.append(_t)logger.info(@@ -2444,26 +2784,51 @@ class OpenAIHandlerMixin:"%d→%d bytes (%d tokens saved, ""auth_mode=%s, transforms=%s)",request_id,- len(_inner_bytes),- len(_new_bytes),- int(_ws_rust_saved),+ _bytes_before,+ _bytes_after,+ int(_ws_saved),_ws_auth_mode.value,transforms_applied,)else:- logger.info(- "[%s] WS /v1/responses first frame passthrough "- "(%d bytes, auth_mode=%s, model=%s)",- request_id,- len(_inner_bytes),- _ws_auth_mode.value,- _model or "unknown",+ _log_ws_passthrough(+ _ws_reason or "no_compression",+ frame_index=1,+ raw_bytes=_bytes_before,+ frame_type=str(_send_body.get("type") or "response.create"),+ model=_model or "unknown",)+ else:+ _log_ws_passthrough(+ "first_frame_non_json",+ frame_index=1,+ raw_bytes=len(first_msg_raw.encode("utf-8", errors="replace")),+ frame_type="unknown",+ )except Exception as _ce:logger.warning(f"[{request_id}] WS /v1/responses compression failed; "f"forwarding original frame: {type(_ce).__name__}: {_ce}")+ _log_ws_passthrough(+ "compression_exception",+ frame_index=1,+ raw_bytes=len(first_msg_raw.encode("utf-8", errors="replace")),+ frame_type="response.create" if body else "unknown",+ model=str(body.get("model") or "unknown")+ if isinstance(body, dict)+ else "unknown",+ )+ else:+ _log_ws_passthrough(+ "bypass_header" if _ws_bypass else "optimize_disabled",+ frame_index=1,+ raw_bytes=len(first_msg_raw.encode("utf-8", errors="replace")),+ frame_type="response.create" if body else "unknown",+ model=str(body.get("model") or "unknown")+ if isinstance(body, dict)+ else "unknown",+ )_first_upstream_body: Any = Nonetry:@@ -2542,7 +2907,9 @@ class OpenAIHandlerMixin:async def _maybe_compress_response_create_frame(raw_msg: str,- ) -> str:+ *,+ frame_index: int,+ ) -> tuple[str, bool, str | None]:"""Compress a single client→upstream framewhen its `type` is `response.create`. Otherevent types (response.cancel, session.update,@@ -2557,40 +2924,71 @@ class OpenAIHandlerMixin:"""nonlocal tokens_saved, transforms_appliednonlocal ws_frames_compressed+ if _ws_bypass:+ _log_ws_passthrough(+ "bypass_header",+ frame_index=frame_index,+ raw_bytes=len(raw_msg.encode("utf-8", errors="replace")),+ )+ return raw_msg, False, "bypass_header"if not self.config.optimize:- return raw_msg+ _log_ws_passthrough(+ "optimize_disabled",+ frame_index=frame_index,+ raw_bytes=len(raw_msg.encode("utf-8", errors="replace")),+ )+ return raw_msg, False, "optimize_disabled"try:parsed_frame = json.loads(raw_msg)except json.JSONDecodeError:- return raw_msg+ _log_ws_passthrough(+ "non_json",+ frame_index=frame_index,+ raw_bytes=len(raw_msg.encode("utf-8", errors="replace")),+ )+ return raw_msg, False, "non_json"if (not isinstance(parsed_frame, dict)or parsed_frame.get("type") != "response.create"):- return raw_msg+ _log_ws_passthrough(+ "not_response_create",+ frame_index=frame_index,+ raw_bytes=len(raw_msg.encode("utf-8", errors="replace")),+ frame_type=(+ parsed_frame.get("type")+ if isinstance(parsed_frame, dict)+ else type(parsed_frame).__name__+ ),+ )+ return raw_msg, False, "not_response_create"wrapped_frame = isinstance(parsed_frame.get("response"), dict)inner_payload = (parsed_frame["response"] if wrapped_frame else parsed_frame)if not isinstance(inner_payload, dict):- return raw_msg- try:- from headroom._core import (- compress_openai_responses_live_zone as _ws_frame_compress,+ _log_ws_passthrough(+ "invalid_inner_payload",+ frame_index=frame_index,+ raw_bytes=len(raw_msg.encode("utf-8", errors="replace")),+ frame_type="response.create",)-- inner_bytes = json.dumps(inner_payload).encode("utf-8")+ return raw_msg, False, "invalid_inner_payload"+ try:model_for_frame = inner_payload.get("model") or ""_frame_auth_mode = classify_auth_mode(ws_headers)(- new_inner_bytes,+ new_inner,modified,- rust_saved,- rust_transforms,- ) = _ws_frame_compress(- inner_bytes,- _frame_auth_mode.value,- model_for_frame,+ frame_saved,+ frame_transforms,+ frame_reason,+ bytes_before,+ bytes_after,+ ) = self._compress_openai_responses_payload(+ inner_payload,+ model=model_for_frame,+ request_id=request_id,)except Exception as _frame_err:logger.warning(@@ -2600,25 +2998,40 @@ class OpenAIHandlerMixin:type(_frame_err).__name__,_frame_err,)- return raw_msg+ _log_ws_passthrough(+ "compression_exception",+ frame_index=frame_index,+ raw_bytes=len(raw_msg.encode("utf-8", errors="replace")),+ frame_type="response.create",+ model=str(inner_payload.get("model") or "unknown"),+ )+ return raw_msg, False, "compression_exception"if not modified:- return raw_msg- try:- new_inner = json.loads(new_inner_bytes)- except json.JSONDecodeError:- return raw_msg+ reason = frame_reason or "no_compression"+ _log_ws_passthrough(+ reason,+ frame_index=frame_index,+ raw_bytes=bytes_before,+ frame_type="response.create",+ model=str(inner_payload.get("model") or "unknown"),+ )+ return raw_msg, False, reasonif not isinstance(new_inner, dict):- return raw_msg+ _log_ws_passthrough(+ "compressed_payload_not_dict",+ frame_index=frame_index,+ raw_bytes=len(raw_msg.encode("utf-8", errors="replace")),+ frame_type="response.create",+ model=str(inner_payload.get("model") or "unknown"),+ )+ return raw_msg, False, "compressed_payload_not_dict"if wrapped_frame:parsed_frame["response"] = new_innerrewritten = json.dumps(parsed_frame)else:rewritten = json.dumps(new_inner)- tokens_saved += int(rust_saved)- for t in (- "openai_responses_ws_live_zone",- *list(rust_transforms),- ):+ tokens_saved += int(frame_saved)+ for t in frame_transforms:if t not in transforms_applied:transforms_applied.append(t)ws_frames_compressed += 1@@ -2627,13 +3040,13 @@ class OpenAIHandlerMixin:"%d→%d bytes (%d tokens saved, ""auth_mode=%s, frame=%d)",request_id,- len(inner_bytes),- len(new_inner_bytes),- int(rust_saved),+ bytes_before,+ bytes_after,+ int(frame_saved),_frame_auth_mode.value,ws_frames_compressed,)- return rewritten+ return rewritten, True, frame_reason or "compressed"async def _client_to_upstream() -> None:nonlocal client_relay_error, ws_response_create_frames@@ -2663,7 +3076,14 @@ class OpenAIHandlerMixin:and _inbound_frame_body.get("type") == "response.create"):ws_response_create_frames += 1- msg = await _maybe_compress_response_create_frame(msg)+ (+ msg,+ _frame_modified,+ _frame_reason,+ ) = await _maybe_compress_response_create_frame(+ msg,+ frame_index=client_frame_index,+ )_outbound_frame_body: Any = Nonetry:_outbound_frame_body = json.loads(msg)@@ -2726,7 +3146,14 @@ class OpenAIHandlerMixin:nonlocal response_completed_seennonlocal upstream_relay_errornonlocal ws_input_tokens_total, ws_output_tokens_total- nonlocal ws_cache_read_tokens_total, ws_uncached_input_tokens_total+ nonlocal ws_cache_read_tokens_total, ws_cache_write_tokens_total+ nonlocal ws_uncached_input_tokens_total+ nonlocal ws_recorded_input_tokens_total+ nonlocal ws_recorded_output_tokens_total+ nonlocal ws_recorded_cache_read_tokens_total+ nonlocal ws_recorded_cache_write_tokens_total+ nonlocal ws_recorded_uncached_input_tokens_total+ nonlocal ws_recorded_tokens_saved_totalmemory_enabled = bool(self.memory_handler and memory_user_id)@@ -2745,6 +3172,79 @@ class OpenAIHandlerMixin:pending_fcs.clear()resp_id = None+ response_started_ms: float | None = None++ async def _record_ws_response_metrics() -> None:+ """Record one completed Responses turn on long-lived WS sessions."""+ nonlocal ws_recorded_input_tokens_total+ nonlocal ws_recorded_output_tokens_total+ nonlocal ws_recorded_cache_read_tokens_total+ nonlocal ws_recorded_cache_write_tokens_total+ nonlocal ws_recorded_uncached_input_tokens_total+ nonlocal ws_recorded_tokens_saved_total++ input_delta = ws_input_tokens_total - ws_recorded_input_tokens_total+ output_delta = (+ ws_output_tokens_total - ws_recorded_output_tokens_total+ )+ cache_read_delta = (+ ws_cache_read_tokens_total - ws_recorded_cache_read_tokens_total+ )+ cache_write_delta = (+ ws_cache_write_tokens_total+ - ws_recorded_cache_write_tokens_total+ )+ uncached_delta = (+ ws_uncached_input_tokens_total+ - ws_recorded_uncached_input_tokens_total+ )+ saved_delta = tokens_saved - ws_recorded_tokens_saved_total+ if (+ input_delta <= 0+ and output_delta <= 0+ and cache_read_delta <= 0+ and cache_write_delta <= 0+ and uncached_delta <= 0+ and saved_delta <= 0+ ):+ return++ model_for_metrics = str(body.get("model") or "unknown")+ if self.cost_tracker:+ self.cost_tracker.record_tokens(+ model_for_metrics,+ max(0, saved_delta),+ max(0, input_delta),+ cache_read_tokens=max(0, cache_read_delta),+ cache_write_tokens=max(0, cache_write_delta),+ uncached_tokens=max(0, uncached_delta),+ )+ latency_ms = (+ (time.perf_counter() * 1000.0 - response_started_ms)+ if response_started_ms is not None+ else 0.0+ )+ await self.metrics.record_request(+ provider="openai",+ model=model_for_metrics,+ input_tokens=max(0, input_delta),+ output_tokens=max(0, output_delta),+ tokens_saved=max(0, saved_delta),+ latency_ms=latency_ms,+ cache_read_tokens=max(0, cache_read_delta),+ cache_write_tokens=max(0, cache_write_delta),+ uncached_input_tokens=max(0, uncached_delta),+ )++ ws_recorded_input_tokens_total = ws_input_tokens_total+ ws_recorded_output_tokens_total = ws_output_tokens_total+ ws_recorded_cache_read_tokens_total = ws_cache_read_tokens_total+ ws_recorded_cache_write_tokens_total = ws_cache_write_tokens_total+ ws_recorded_uncached_input_tokens_total = (+ ws_uncached_input_tokens_total+ )+ ws_recorded_tokens_saved_total = tokens_saved+# The retry-loop variable is safe to close over here:# ``_upstream_to_client`` is defined and awaited within# a single iteration and never escapes.@@ -2806,19 +3306,26 @@ class OpenAIHandlerMixin:continueevent_type = event.get("type", "")+ if event_type == "response.created":+ response_started_ms = time.perf_counter() * 1000.0(usage_input_tokens,usage_output_tokens,usage_cache_read_tokens,+ usage_cache_write_tokens,usage_uncached_tokens,) = _extract_responses_usage(event)if usage_input_tokens or usage_output_tokens:ws_input_tokens_total += usage_input_tokensws_output_tokens_total += usage_output_tokensws_cache_read_tokens_total += usage_cache_read_tokens+ ws_cache_write_tokens_total += usage_cache_write_tokensws_uncached_input_tokens_total += usage_uncached_tokensif not memory_enabled:+ if event_type == "response.completed":+ response_completed_seen = True+ await _record_ws_response_metrics()await websocket.send_text(msg_str)continue@@ -2850,13 +3357,14 @@ class OpenAIHandlerMixin:elif event_type == "response.completed":# No output items at all — flushdecided = True- for buf in event_buffer:- await websocket.send_text(buf)- event_buffer.clear()- _reset()- response_completed_seen = True+ for buf in event_buffer:+ await websocket.send_text(buf)+ event_buffer.clear()+ await _record_ws_response_metrics()+ _reset()+ response_completed_seen = True- continue+ continue# --- Phase 2a: Suppress mode (memory response) ---if suppress_response:@@ -2870,6 +3378,7 @@ class OpenAIHandlerMixin:elif event_type == "response.completed":response_completed_seen = True+ await _record_ws_response_metrics()resp = event.get("response", {})resp_id = resp.get("id")@@ -3131,6 +3640,21 @@ class OpenAIHandlerMixin:or "unknown")_final_auth_mode = classify_auth_mode(ws_headers)+ residual_input_tokens = max(0, ws_input_tokens_total - ws_recorded_input_tokens_total)+ residual_output_tokens = max(+ 0, ws_output_tokens_total - ws_recorded_output_tokens_total+ )+ residual_cache_read_tokens = max(+ 0, ws_cache_read_tokens_total - ws_recorded_cache_read_tokens_total+ )+ residual_cache_write_tokens = max(+ 0, ws_cache_write_tokens_total - ws_recorded_cache_write_tokens_total+ )+ residual_uncached_input_tokens = max(+ 0,+ ws_uncached_input_tokens_total - ws_recorded_uncached_input_tokens_total,+ )+ residual_tokens_saved = max(0, tokens_saved - ws_recorded_tokens_saved_total)ws_session_tags = {**(ws_tags or {}),"auth_mode": _final_auth_mode.value,@@ -3142,18 +3666,37 @@ class OpenAIHandlerMixin:"ws_response_create_frames": str(ws_response_create_frames),"ws_frames_compressed": str(ws_frames_compressed),"cache_read_tokens": str(ws_cache_read_tokens_total),+ "cache_write_tokens": str(ws_cache_write_tokens_total),"uncached_input_tokens": str(ws_uncached_input_tokens_total),}- await self.metrics.record_request(- provider="openai",- model=model_name,- input_tokens=ws_input_tokens_total,- output_tokens=ws_output_tokens_total,- tokens_saved=tokens_saved,- latency_ms=ws_session_duration_ms,- cache_read_tokens=ws_cache_read_tokens_total,- uncached_input_tokens=ws_uncached_input_tokens_total,- )+ if (+ residual_input_tokens > 0+ or residual_output_tokens > 0+ or residual_tokens_saved > 0+ or residual_cache_read_tokens > 0+ or residual_cache_write_tokens > 0+ or residual_uncached_input_tokens > 0+ ):+ if self.cost_tracker:+ self.cost_tracker.record_tokens(+ model_name,+ residual_tokens_saved,+ residual_input_tokens,+ cache_read_tokens=residual_cache_read_tokens,+ cache_write_tokens=residual_cache_write_tokens,+ uncached_tokens=residual_uncached_input_tokens,+ )+ await self.metrics.record_request(+ provider="openai",+ model=model_name,+ input_tokens=residual_input_tokens,+ output_tokens=residual_output_tokens,+ tokens_saved=residual_tokens_saved,+ latency_ms=ws_session_duration_ms,+ cache_read_tokens=residual_cache_read_tokens,+ cache_write_tokens=residual_cache_write_tokens,+ uncached_input_tokens=residual_uncached_input_tokens,+ )if getattr(self, "logger", None) is not None:from headroom.proxy.helpers import compute_turn_idfrom headroom.proxy.models import RequestLogdiff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.pyindex f3b4f4e45..060c18aaa 100644--- a/headroom/proxy/handlers/streaming.py+++ b/headroom/proxy/handlers/streaming.py@@ -230,11 +230,38 @@ class StreamingMixin:elif provider == "openai":chunk_usage = data.get("usage")- if chunk_usage:- usage_found["input_tokens"] = chunk_usage.get("prompt_tokens", 0)- usage_found["output_tokens"] = chunk_usage.get("completion_tokens", 0)- details = chunk_usage.get("prompt_tokens_details") or {}- usage_found["cache_read_input_tokens"] = details.get("cached_tokens", 0)+ if not isinstance(chunk_usage, dict):+ response = data.get("response")+ if isinstance(response, dict):+ chunk_usage = response.get("usage")+ if isinstance(chunk_usage, dict):++ def _usage_int(value: Any) -> int:+ try:+ return max(int(value), 0)+ except (TypeError, ValueError):+ return 0++ # Chat Completions streams report prompt/completion tokens.+ # Responses streams report input/output tokens under+ # response.usage on response.completed.+ input_tokens = chunk_usage.get("prompt_tokens")+ if input_tokens is None:+ input_tokens = chunk_usage.get("input_tokens", 0)+ output_tokens = chunk_usage.get("completion_tokens")+ if output_tokens is None:+ output_tokens = chunk_usage.get("output_tokens", 0)+ usage_found["input_tokens"] = _usage_int(input_tokens)+ usage_found["output_tokens"] = _usage_int(output_tokens)+ details = (+ chunk_usage.get("prompt_tokens_details")+ or chunk_usage.get("input_tokens_details")+ or {}+ )+ if isinstance(details, dict):+ usage_found["cache_read_input_tokens"] = _usage_int(+ details.get("cached_tokens")+ )elif provider == "gemini":usage_meta = data.get("usageMetadata")@@ -569,11 +596,24 @@ class StreamingMixin:f"estimating {output_tokens} from {stream_state['total_bytes']} bytes")+ provider_input_tokens = stream_state.get("input_tokens")+ effective_optimized_tokens = optimized_tokens+ effective_original_tokens = original_tokens+ if (+ provider == "openai"+ and isinstance(provider_input_tokens, int)+ and provider_input_tokens > 0+ ):+ effective_optimized_tokens = provider_input_tokens+ effective_original_tokens = max(original_tokens, provider_input_tokens + tokens_saved)+cache_read_tokens = stream_state["cache_read_input_tokens"] or 0cache_write_tokens = stream_state["cache_creation_input_tokens"] or 0cache_write_5m_tokens = stream_state["cache_creation_ephemeral_5m_input_tokens"] or 0cache_write_1h_tokens = stream_state["cache_creation_ephemeral_1h_input_tokens"] or 0- uncached_input_tokens = max(optimized_tokens - cache_read_tokens - cache_write_tokens, 0)+ uncached_input_tokens = max(+ effective_optimized_tokens - cache_read_tokens - cache_write_tokens, 0+ )num_msgs = len(body.get("messages", []))cache_hit_pct = (@@ -584,7 +624,7 @@ class StreamingMixin:logger.info(f"[{request_id}] PERF "f"model={model} msgs={num_msgs} "- f"tok_before={original_tokens} tok_after={optimized_tokens} "+ 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} "@@ -622,7 +662,7 @@ class StreamingMixin:self.cost_tracker.record_tokens(model,tokens_saved,- optimized_tokens,+ effective_optimized_tokens,cache_read_tokens=cache_read_tokens,cache_write_tokens=cache_write_tokens,cache_write_5m_tokens=cache_write_5m_tokens,@@ -634,7 +674,7 @@ class StreamingMixin:await self.metrics.record_request(provider=provider,model=model,- input_tokens=optimized_tokens,+ input_tokens=effective_optimized_tokens,output_tokens=output_tokens,tokens_saved=tokens_saved,latency_ms=total_latency,@@ -662,12 +702,12 @@ class StreamingMixin:timestamp=datetime.now().isoformat(),provider=provider,model=model,- input_tokens_original=original_tokens,- input_tokens_optimized=optimized_tokens,+ input_tokens_original=effective_original_tokens,+ input_tokens_optimized=effective_optimized_tokens,output_tokens=output_tokens,tokens_saved=tokens_saved,- savings_percent=(tokens_saved / original_tokens * 100)- if original_tokens > 0+ savings_percent=(tokens_saved / effective_original_tokens * 100)+ if effective_original_tokens > 0else 0,optimization_latency_ms=optimization_latency,total_latency_ms=total_latency,diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex dc7c503b8..f346459a2 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -100,6 +100,32 @@ def _safe_event_name(event: str) -> str:return "".join(ch if ch.isalnum() or ch in ("-", "_") else "_" for ch in event)[:80]+def _wire_debug_preview(value: Any, *, max_chars: int = 900) -> str:+ """Return a compact, human-readable preview for proxy.log.++ This is intentionally lossy: the full redacted payload is already written+ to the wire-debug JSON file. The log line should be short enough to scan+ live without flooding the proxy log.+ """++ try:+ if isinstance(value, bytes):+ text = safe_decode_for_logging(value, max_bytes=max_chars)+ elif isinstance(value, str):+ text = value+ elif value is None:+ return ""+ else:+ text = json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":"))+ except Exception:+ text = repr(value)++ text = " ".join(text.split())+ if len(text) > max_chars:+ return text[: max_chars - 1] + "…"+ return text++def capture_codex_wire_debug(event: str,*,@@ -159,6 +185,21 @@ def capture_codex_wire_debug(request_id or "",event,)+ preview_source = redact_for_wire_debug(body) if body is not None else raw_text+ preview = _wire_debug_preview(preview_source)+ meta_keys = ",".join(sorted((metadata or {}).keys()))+ logger.info(+ "event=codex_wire_debug_frame request_id=%s session_id=%s wire_event=%s "+ "transport=%s direction=%s status_code=%s meta_keys=%s preview=%s",+ request_id or "",+ session_id or "",+ event,+ transport,+ direction,+ status_code if status_code is not None else "",+ meta_keys,+ preview,+ )return pathexcept Exception as exc: # pragma: no cover - debug path must never break trafficlogger.warning("event=codex_wire_debug_capture_failed error=%s", exc)@@ -250,6 +291,21 @@ def get_python_forwarder_mode() -> PythonForwarderMode:)+def _headroom_bypass_enabled(headers: Any) -> bool:+ """Return True when inbound headers request full Headroom passthrough.++ This is transport-neutral policy: HTTP and WebSocket handlers both call+ it on original inbound headers before request-body mutation.+ """++ try:+ bypass = str(headers.get("x-headroom-bypass", "")).strip().lower() == "true"+ passthrough = str(headers.get("x-headroom-mode", "")).strip().lower() == "passthrough"+ except AttributeError:+ return False+ return bypass or passthrough++def serialize_body_canonical(body: dict[str, Any]) -> bytes:"""Re-serialize a request body deterministically with cache-stable formatting.@@ -517,6 +573,11 @@ _rtk_stats_cache: dict[str, Any] = {"has_value": False,"value": None,}+_rtk_session_baseline: dict[str, Any] = {+ "initialized": False,+ "total_commands": 0,+ "tokens_saved": 0,+}# Maximum request body size (100MB - increased to support image-heavy requests)MAX_REQUEST_BODY_SIZE = 100 * 1024 * 1024@@ -742,39 +803,20 @@ def _setup_file_logging() -> None:pass-def _get_rtk_stats() -> dict[str, Any] | None:- """Get rtk (Rust Token Killer) savings stats if rtk is installed.+def _read_rtk_lifetime_stats() -> dict[str, Any] | None:+ """Read rtk's current project-level lifetime stats."""- Reads from rtk's tracking database via `rtk gain --format json`.- Results are memoized briefly so dashboard polling does not spawn a new- subprocess on every refresh.- """import subprocess as _spfrom headroom.rtk import get_rtk_path- now = time.monotonic()- with _rtk_stats_cache_lock:- if _rtk_stats_cache["has_value"] and now < float(_rtk_stats_cache["expires_at"]):- return cast(dict[str, Any] | None, _rtk_stats_cache["value"])-- payload: dict[str, Any] | Nonertk_path = get_rtk_path()if not rtk_path:- payload = None- with _rtk_stats_cache_lock:- _rtk_stats_cache.update(- {- "expires_at": time.monotonic() + RTK_STATS_CACHE_TTL_SECONDS,- "has_value": True,- "value": payload,- }- )- return payload+ return Nonetry:result = _sp.run(- [str(rtk_path), "gain", "--format", "json"],+ [str(rtk_path), "gain", "--project", "--format", "json"],capture_output=True,text=True,timeout=5,@@ -789,21 +831,83 @@ def _get_rtk_stats() -> dict[str, Any] | None:"avg_savings_pct": summary.get("avg_savings_pct", 0.0),}else:- payload = {+ return {"installed": True,"total_commands": 0,"tokens_saved": 0,"avg_savings_pct": 0.0,}except Exception:- payload = {+ return {"installed": True,"total_commands": 0,"tokens_saved": 0,"avg_savings_pct": 0.0,}+ return payload+++def initialize_rtk_session_baseline() -> None:+ """Pin the current rtk counters as the proxy-session baseline."""++ payload = _read_rtk_lifetime_stats()+ with _rtk_stats_cache_lock:+ _rtk_session_baseline.update(+ {+ "initialized": True,+ "total_commands": int((payload or {}).get("total_commands", 0) or 0),+ "tokens_saved": int((payload or {}).get("tokens_saved", 0) or 0),+ }+ )+ _rtk_stats_cache.update(+ {+ "expires_at": 0.0,+ "has_value": False,+ "value": None,+ }+ )+++def _get_rtk_stats() -> dict[str, Any] | None:+ """Get rtk savings for the current Headroom proxy session.++ rtk persists project-level lifetime counters. Dashboard stats should be+ session-local, so we subtract the counter snapshot captured at proxy+ startup instead of resetting rtk's own history.+ """++ now = time.monotonic()+ with _rtk_stats_cache_lock:+ if _rtk_stats_cache["has_value"] and now < float(_rtk_stats_cache["expires_at"]):+ return cast(dict[str, Any] | None, _rtk_stats_cache["value"])++ payload = _read_rtk_lifetime_stats()with _rtk_stats_cache_lock:+ if not _rtk_session_baseline["initialized"]:+ _rtk_session_baseline.update(+ {+ "initialized": True,+ "total_commands": int((payload or {}).get("total_commands", 0) or 0),+ "tokens_saved": int((payload or {}).get("tokens_saved", 0) or 0),+ }+ )++ if payload is not None:+ payload = {+ **payload,+ "total_commands": max(+ int(payload.get("total_commands", 0) or 0)+ - int(_rtk_session_baseline["total_commands"]),+ 0,+ ),+ "tokens_saved": max(+ int(payload.get("tokens_saved", 0) or 0)+ - int(_rtk_session_baseline["tokens_saved"]),+ 0,+ ),+ }+_rtk_stats_cache.update({"expires_at": time.monotonic() + RTK_STATS_CACHE_TTL_SECONDS,diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.pyindex e8d5616e7..c479069f0 100644--- a/headroom/proxy/prometheus_metrics.py+++ b/headroom/proxy/prometheus_metrics.py@@ -193,6 +193,62 @@ class PrometheusMetrics:self._stage_timing_lock = threading.Lock()self._otel_metrics = otel_metrics+ async def reset_runtime(self) -> None:+ """Reset in-memory request/compression counters for local test/debug use."""+ async with self._lock:+ self.requests_total = 0+ self.requests_by_provider.clear()+ self.requests_by_model.clear()+ self.requests_by_stack.clear()+ self.requests_cached = 0+ self.requests_rate_limited = 0+ self.requests_failed = 0++ self.tokens_input_total = 0+ self.tokens_output_total = 0+ self.tokens_saved_total = 0++ self.compressions_by_strategy.clear()+ self.tokens_saved_by_strategy.clear()++ self.latency_sum_ms = 0.0+ self.latency_min_ms = float("inf")+ self.latency_max_ms = 0.0+ self.latency_count = 0++ self.overhead_sum_ms = 0.0+ self.overhead_min_ms = float("inf")+ self.overhead_max_ms = 0.0+ self.overhead_count = 0++ self.ttfb_sum_ms = 0.0+ self.ttfb_min_ms = float("inf")+ self.ttfb_max_ms = 0.0+ self.ttfb_count = 0++ self.transform_timing_sum.clear()+ self.transform_timing_count.clear()+ self.transform_timing_max.clear()++ self.waste_signals_total.clear()+ self.cache_by_provider.clear()+ self._cache_requests_by_model.clear()++ self.prefix_freeze_busts_avoided = 0+ self.prefix_freeze_tokens_preserved = 0+ self.prefix_freeze_compression_foregone = 0+ self.cache_bust_tokens_lost = 0+ self.cache_bust_count = 0+ self.savings_history = []++ with self._stage_timing_lock:+ self.stage_timing_sum.clear()+ self.stage_timing_count.clear()+ self.stage_timing_max.clear()+ self.ws_session_duration_sum_ms.clear()+ self.ws_session_duration_count.clear()+ self.ws_session_duration_max_ms.clear()+def _get_otel_metrics(self) -> HeadroomOtelMetrics:return self._otel_metrics or get_otel_metrics()diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 592aa77cb..361601b62 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -74,9 +74,7 @@ from headroom.ccr import ()from headroom.config import (CacheAlignerConfig,- CCRConfig,ReadLifecycleConfig,- SmartCrusherConfig,)from headroom.dashboard import get_dashboard_htmlfrom headroom.observability import (@@ -122,6 +120,7 @@ from headroom.proxy.helpers import (_get_rtk_stats, # noqa: F401_read_request_json, # noqa: F401_setup_file_logging, # noqa: F401+ initialize_rtk_session_baseline,is_anthropic_auth, # noqa: F401jitter_delay_ms,)@@ -157,7 +156,6 @@ from headroom.transforms import (CodeCompressorConfig,ContentRouter,ContentRouterConfig,- SmartCrusher,TransformPipeline,is_tree_sitter_available,)@@ -346,41 +344,22 @@ class HeadroomProxy(# Reported via metrics as `_context_manager_status = "passthrough"`.self._context_manager_status = "passthrough"- if config.smart_routing:- # Smart routing: ContentRouter handles all content types intelligently- # It lazy-loads compressors only when needed- router_config = ContentRouterConfig(- enable_code_aware=config.code_aware_enabled,- tool_profiles=config.tool_profiles,- read_lifecycle=ReadLifecycleConfig(enabled=config.read_lifecycle),- )- # Token mode: allow compression of older excluded-tool results- if is_token_mode(config.mode):- router_config.protect_recent_reads_fraction = 0.3- transforms = [- CacheAligner(CacheAlignerConfig(enabled=False)),- ContentRouter(router_config, observer=self.metrics),- ]- self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"- else:- # Legacy mode: sequential pipeline- transforms = [- CacheAligner(CacheAlignerConfig(enabled=False)),- SmartCrusher(- SmartCrusherConfig( # type: ignore[arg-type]- enabled=True,- min_tokens_to_crush=config.min_tokens_to_crush,- max_items_after_crush=config.max_items_after_crush,- ),- ccr_config=CCRConfig(- enabled=config.ccr_inject_tool,- inject_retrieval_marker=config.ccr_inject_tool, # Add CCR markers- ),- observer=self.metrics,- ),- ]- # Add CodeAware if enabled and available- self._code_aware_status = self._setup_code_aware(config, transforms)+ # ContentRouter is the single proxy routing surface. Provider handlers+ # normalize their request shapes into messages or CompressionUnits, and+ # the router chooses SmartCrusher, log/search/diff/code, or Kompress.+ router_config = ContentRouterConfig(+ enable_code_aware=config.code_aware_enabled,+ tool_profiles=config.tool_profiles,+ read_lifecycle=ReadLifecycleConfig(enabled=config.read_lifecycle),+ )+ # Token mode: allow compression of older excluded-tool results.+ if is_token_mode(config.mode):+ router_config.protect_recent_reads_fraction = 0.3+ transforms = [+ CacheAligner(CacheAlignerConfig(enabled=False)),+ ContentRouter(router_config, observer=self.metrics),+ ]+ self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"self.anthropic_pipeline = TransformPipeline(transforms=transforms,@@ -862,11 +841,7 @@ class HeadroomProxy(self.anthropic_pre_upstream_memory_context_timeout_seconds,)- # Smart routing status- if self.config.smart_routing:- logger.info("Smart Routing: ENABLED (intelligent content detection)")- else:- logger.info("Smart Routing: DISABLED (legacy sequential mode)")+ logger.info("Smart Routing: ENABLED (ContentRouter is always active)")# Eagerly load ALL compressors, parsers, and detectors at startup# This eliminates cold-start latency spikes on first requests.@@ -1364,6 +1339,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:app.state.started_at = time.time()app.state.ready = Falseapp.state.startup_error = None+ initialize_rtk_session_baseline()try:try:@@ -1734,8 +1710,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# compression and rtk both remove tokens before they reach model# context, so dashboard-facing compression savings combines them.proxy_compression_tokens = m.tokens_saved_total- compression_tokens = proxy_compression_tokens + cli_tokens_avoided- total_tokens_before = m.tokens_input_total + compression_tokens+ all_layers_tokens_saved = proxy_compression_tokens + cli_tokens_avoided+ total_tokens_before = m.tokens_input_total + all_layers_tokens_saved+ proxy_total_before_compression = m.tokens_input_total + proxy_compression_tokens# Build human-readable summarysummary = _build_session_summary(@@ -1780,7 +1757,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# Build unified savings summary (all layers)cache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)- total_tokens_all_layers = compression_tokens+ total_tokens_all_layers = all_layers_tokens_savedpersistent_savings = m.savings_tracker.stats_preview()display_session = persistent_savings.get("display_session", {})@@ -1791,18 +1768,20 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"by_layer": {"cli_filtering": {"tokens": cli_tokens_avoided,- "included_in": "compression",+ "included_in": "tokens.saved","description": ("Tokens avoided by CLI output filtering (rtk) before reaching context. "- "Included in dashboard compression savings."+ "Included in dashboard token savings, but not in dollar savings."),},"compression": {- "tokens": compression_tokens,+ "tokens": proxy_compression_tokens,"proxy_tokens": proxy_compression_tokens,"rtk_tokens": cli_tokens_avoided,+ "all_layers_tokens": all_layers_tokens_saved,"description": (- "Tokens removed before model context by proxy compression plus rtk CLI filtering."+ "Tokens removed by Headroom proxy compression. "+ "Dashboard token savings also includes rtk CLI filtering."),},"prefix_cache": {@@ -1827,13 +1806,27 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"tokens": {"input": m.tokens_input_total,"output": m.tokens_output_total,- "saved": compression_tokens,+ "saved": all_layers_tokens_saved,"proxy_compression_saved": proxy_compression_tokens,"rtk_saved": cli_tokens_avoided,"cli_tokens_avoided": cli_tokens_avoided,+ "proxy_total_before_compression": proxy_total_before_compression,"total_before_compression": total_tokens_before,+ "all_layers_saved": all_layers_tokens_saved,+ "proxy_savings_percent": round(+ (proxy_compression_tokens / proxy_total_before_compression * 100)+ if proxy_total_before_compression > 0+ else 0,+ 2,+ ),"savings_percent": round(- (compression_tokens / total_tokens_before * 100)+ (all_layers_tokens_saved / total_tokens_before * 100)+ if total_tokens_before > 0+ else 0,+ 2,+ ),+ "all_layers_savings_percent": round(+ (all_layers_tokens_saved / total_tokens_before * 100)if total_tokens_before > 0else 0,2,@@ -1957,6 +1950,18 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:return await _get_cached_stats_payload()return await _build_stats_payload()+ @app.post("/stats/reset", dependencies=[Depends(_require_loopback)])+ async def stats_reset():+ """Reset in-memory proxy stats for local test/debug isolation."""+ await proxy.metrics.reset_runtime()+ if proxy.cost_tracker:+ proxy.cost_tracker.reset_runtime()+ initialize_rtk_session_baseline()+ async with _stats_snapshot_lock:+ _stats_snapshot["value"] = None+ _stats_snapshot["expires_at"] = 0.0+ return JSONResponse(status_code=200, content={"status": "reset"})+@app.get("/stats-history")async def stats_history(format: Literal["json", "csv"] = "json",@@ -2105,6 +2110,10 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:store = get_compression_store()if query:+ if not store.exists(hash_key, clean_expired=True):+ raise HTTPException(+ status_code=404, detail="Entry not found or expired (TTL: 5 minutes)"+ )# Search within cached contentresults = store.search(hash_key, query)return {@@ -2415,6 +2424,8 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:store = get_compression_store()if query:+ if not store.exists(hash_key, clean_expired=True):+ raise HTTPException(status_code=404, detail="Entry not found or expired")results = store.search(hash_key, query)return {"hash": hash_key,@@ -2911,13 +2922,6 @@ if __name__ == "__main__":parser.add_argument("--log-file", help="Log file path")parser.add_argument("--log-messages", action="store_true", help="Log full messages")- # Smart routing (content-aware compression)- parser.add_argument(- "--no-smart-routing",- action="store_true",- help="Disable smart routing (use legacy sequential pipeline)",- )-# Code-aware compressionparser.add_argument("--code-aware",@@ -2934,7 +2938,6 @@ if __name__ == "__main__":# Environment variable defaults (HEADROOM_* prefix)# CLI args override env vars, env vars override ProxyConfig defaults- env_smart_routing = _get_env_bool("HEADROOM_SMART_ROUTING", True)env_code_aware = _get_env_bool("HEADROOM_CODE_AWARE_ENABLED", True)env_optimize = _get_env_bool("HEADROOM_OPTIMIZE", True)env_cache = _get_env_bool("HEADROOM_CACHE_ENABLED", True)@@ -2942,7 +2945,6 @@ if __name__ == "__main__":# Determine settings: CLI flags override env vars# --no-X explicitly disables, --X explicitly enables, neither uses env var- smart_routing = env_smart_routing if not args.no_smart_routing else Falsecode_aware_enabled = (env_code_awareif not (args.code_aware or args.no_code_aware)@@ -2983,7 +2985,7 @@ if __name__ == "__main__":if args.log_fileelse os.environ.get("HEADROOM_LOG_FILE"),log_full_messages=args.log_messages or _get_env_bool("HEADROOM_LOG_MESSAGES", False),- smart_routing=smart_routing,+ smart_routing=True,code_aware_enabled=code_aware_enabled,# Connection pool settingsmax_connections=_get_env_int("HEADROOM_MAX_CONNECTIONS", args.max_connections),diff --git a/headroom/transforms/compression_units.py b/headroom/transforms/compression_units.pynew file mode 100644index 000000000..16a424cd5--- /dev/null+++ b/headroom/transforms/compression_units.py@@ -0,0 +1,176 @@+"""Provider-neutral compression units.++Provider adapters own request-envelope details and cache/live-zone decisions.+They should extract only safe, mutable text ranges into ``CompressionUnit``+objects, ask ContentRouter to compress each unit, then splice accepted+replacements back into their native request shape.+"""++from __future__ import annotations++from collections.abc import Iterable+from dataclasses import dataclass, field+from typing import Protocol++from .content_router import CompressionStrategy, ContentRouter, RouterCompressionResult+++class TokenCounterLike(Protocol):+ def count_text(self, text: str) -> int: ...+++@dataclass(frozen=True)+class CompressionUnit:+ """One provider-extracted, cache-safe text slot."""++ text: str+ provider: str+ endpoint: str+ role: str+ item_type: str+ cache_zone: str = "live"+ mutable: bool = True+ context: str = ""+ question: str | None = None+ bias: float = 1.0+ min_bytes: int = 512+ metadata: dict[str, str] = field(default_factory=dict)+++@dataclass(frozen=True)+class UnitCompressionResult:+ original: str+ compressed: str+ modified: bool+ tokens_before: int+ tokens_after: int+ tokens_saved: int+ transforms_applied: list[str]+ strategy: str+ reason: str | None = None+ router_result: RouterCompressionResult | None = None+++@dataclass(frozen=True)+class RoutedCompressionUnit:+ """A unit paired with its provider-owned slot reference."""++ unit: CompressionUnit+ slot: object+++def find_content_router(transforms: object) -> ContentRouter | None:+ """Return the first ContentRouter in a pipeline or iterable."""++ candidates = getattr(transforms, "transforms", transforms)+ try:+ iterator = iter(candidates) # type: ignore[arg-type]+ except TypeError:+ return None+ for transform in iterator:+ if isinstance(transform, ContentRouter):+ return transform+ return None+++def compress_unit_with_router(+ unit: CompressionUnit,+ *,+ router: ContentRouter,+ tokenizer: TokenCounterLike,+) -> UnitCompressionResult:+ """Compress one safe text unit through ContentRouter.++ The final accept/reject gate uses the provider/model tokenizer, not the+ router's internal word-count estimates.+ """++ tokens_before = tokenizer.count_text(unit.text)+ base = {+ "original": unit.text,+ "compressed": unit.text,+ "modified": False,+ "tokens_before": tokens_before,+ "tokens_after": tokens_before,+ "tokens_saved": 0,+ "transforms_applied": [],+ "strategy": CompressionStrategy.PASSTHROUGH.value,+ "router_result": None,+ }++ if not unit.mutable:+ return UnitCompressionResult(**base, reason="immutable")+ if unit.role == "user":+ return UnitCompressionResult(**base, reason="protected_user_message")+ if unit.role in {"system", "developer"}:+ return UnitCompressionResult(**base, reason="protected_system_message")+ if unit.role == "assistant" and unit.metadata.get("compress_assistant") != "true":+ return UnitCompressionResult(**base, reason="protected_assistant_message")+ if unit.cache_zone != "live":+ return UnitCompressionResult(**base, reason=f"cache_zone_{unit.cache_zone}")+ if len(unit.text) < unit.min_bytes:+ return UnitCompressionResult(**base, reason="below_unit_floor")+ if "Retrieve more: hash=" in unit.text or "Retrieve original: hash=" in unit.text:+ return UnitCompressionResult(**base, reason="already_compressed")++ router_result = router.compress(+ unit.text,+ context=unit.context,+ question=unit.question,+ bias=unit.bias,+ )+ replacement = router_result.compressed+ strategy = router_result.strategy_used.value+ if replacement == unit.text:+ return UnitCompressionResult(+ **{**base, "strategy": strategy, "router_result": router_result},+ reason="router_no_change",+ )++ tokens_after = tokenizer.count_text(replacement)+ if tokens_after >= tokens_before:+ return UnitCompressionResult(+ **{+ **base,+ "compressed": replacement,+ "tokens_after": tokens_after,+ "strategy": strategy,+ "router_result": router_result,+ },+ reason="rejected_not_smaller",+ )++ return UnitCompressionResult(+ original=unit.text,+ compressed=replacement,+ modified=True,+ tokens_before=tokens_before,+ tokens_after=tokens_after,+ tokens_saved=tokens_before - tokens_after,+ transforms_applied=[+ f"router:{unit.provider}:{unit.endpoint}:{unit.item_type}:{strategy}",+ strategy,+ ],+ strategy=strategy,+ reason=None,+ router_result=router_result,+ )+++def compress_units_with_router(+ units: Iterable[RoutedCompressionUnit],+ *,+ router: ContentRouter,+ tokenizer: TokenCounterLike,+) -> list[tuple[object, UnitCompressionResult]]:+ """Compress provider-extracted units and preserve provider slot refs.++ Provider adapters use this when they have many candidate text slots in one+ request envelope. The slot object is intentionally opaque here; only the+ provider adapter knows how to splice the result back into its native shape.+ """++ return [+ (routed.slot, compress_unit_with_router(routed.unit, router=router, tokenizer=tokenizer))+ for routed in units+ ]diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 05eacc8a5..ccec45590 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -1520,7 +1520,7 @@ class ContentRouter(Transform):skip_user = (kwargs.get("compress_user_messages") is not True and self.config.skip_user_messages)- skip_system = kwargs.get("compress_system_messages") is False+ skip_system = kwargs.get("compress_system_messages") is not Trueprotect_recent = kwargs.get("protect_recent", self.config.protect_recent_code)protect_analysis = kwargs.get("protect_analysis_context", self.config.protect_analysis_context@@ -1715,10 +1715,11 @@ class ContentRouter(Transform):route_counts["user_msg"] += 1continue- # Protection 1b: Never compress system messages (when disabled)- if skip_system and role == "system":+ # Protection 1b: Never compress system/developer messages unless+ # explicitly opted in. These are cache-hot instruction bytes.+ if skip_system and role in {"system", "developer"}:result_slots[i] = message- transforms_applied.append("router:protected:system_message")+ transforms_applied.append(f"router:protected:{role}_message")route_counts.setdefault("system_msg", 0)route_counts["system_msg"] += 1continue@@ -2004,7 +2005,7 @@ class ContentRouter(Transform):# Role-based gate for `text` blocks. Tool/function roles are tool# outputs and compress freely; assistant defaults to skip (cache# safety) with explicit opt-in; unknown roles default to skip.- if (skip_user and role == "user") or (skip_system and role == "system"):+ if (skip_user and role == "user") or (skip_system and role in {"system", "developer"}):protect_text_blocks = Trueelif role == "assistant" and not compress_assistant_text_blocks:protect_text_blocks = Truediff --git a/headroom/transforms/pipeline.py b/headroom/transforms/pipeline.pyindex 126bff1f9..7822d24fa 100644--- a/headroom/transforms/pipeline.py+++ b/headroom/transforms/pipeline.py@@ -21,7 +21,6 @@ from ..utils import deep_copy_messagesfrom .base import Transformfrom .cache_aligner import CacheAlignerfrom .content_router import ContentRouter-from .smart_crusher import SmartCrusherif TYPE_CHECKING:from ..providers.base import Provider@@ -37,7 +36,6 @@ class TransformPipeline:1. Cache Aligner - normalize prefix for cache hits2. Content Router - intelligent content-aware compression (routes to appropriatecompressor: Kompress for text, SmartCrusher for JSON, CodeCompressor for code, etc.)- 3. SmartCrusher - fallback if ContentRouter disabledPhase B PR-B1 retired the IntelligentContextManager / RollingWindow"drop messages from history" stage. Live-zone-only compression is the@@ -100,26 +98,13 @@ class TransformPipeline:# - Logs -> LogCompressor# - Search results -> SearchCompressor# - HTML -> HTMLExtractor- if self.config.content_router_enabled:- transforms.append(ContentRouter())- logger.info("Pipeline using ContentRouter for intelligent content-aware compression")- elif self.config.smart_crusher.enabled:- # Fallback: SmartCrusher only handles JSON arrays- from .smart_crusher import SmartCrusherConfig as SCConfig-- smart_config = SCConfig(- enabled=True,- min_items_to_analyze=self.config.smart_crusher.min_items_to_analyze,- min_tokens_to_crush=self.config.smart_crusher.min_tokens_to_crush,- variance_threshold=self.config.smart_crusher.variance_threshold,- uniqueness_threshold=self.config.smart_crusher.uniqueness_threshold,- similarity_threshold=self.config.smart_crusher.similarity_threshold,- max_items_after_crush=self.config.smart_crusher.max_items_after_crush,- preserve_change_points=self.config.smart_crusher.preserve_change_points,- factor_out_constants=self.config.smart_crusher.factor_out_constants,- include_summaries=self.config.smart_crusher.include_summaries,+ if not self.config.content_router_enabled:+ logger.warning(+ "HeadroomConfig.content_router_enabled=False is deprecated and ignored; "+ "ContentRouter is always present in the default pipeline")- transforms.append(SmartCrusher(smart_config))+ transforms.append(ContentRouter())+ logger.info("Pipeline using ContentRouter for intelligent content-aware compression")return transformsdiff --git a/tests/test_canonical_pipeline.py b/tests/test_canonical_pipeline.pyindex 621e6b0b9..96d6622d3 100644--- a/tests/test_canonical_pipeline.py+++ b/tests/test_canonical_pipeline.py@@ -15,6 +15,8 @@ from headroom.pipeline import (summarize_routing_markers,)from headroom.providers.base import Provider, TokenCounter+from headroom.transforms import ContentRouter, TransformPipeline+from headroom.transforms.content_router import CompressionStrategyclass RecordingExtension:@@ -146,6 +148,49 @@ def test_pipeline_extension_manager_uses_canonical_stage_contract():assert event.messages == [{"role": "user", "content": "mutated"}]+def test_default_transform_pipeline_always_uses_content_router() -> None:+ config = HeadroomConfig(content_router_enabled=False)++ pipeline = TransformPipeline(config)++ assert any(isinstance(transform, ContentRouter) for transform in pipeline.transforms)+ assert not any(type(transform).__name__ == "SmartCrusher" for transform in pipeline.transforms)+++def test_content_router_protects_instruction_roles_but_compresses_tool_outputs() -> None:+ class Tokenizer:+ def count_text(self, text: str) -> int:+ return max(1, len(text.split()))++ router = ContentRouter()+ calls: list[str] = []++ def fake_compress(text: str, **kwargs: Any) -> SimpleNamespace:+ calls.append(text)+ return SimpleNamespace(+ compressed="COMPRESSED",+ compression_ratio=0.1,+ strategy_used=CompressionStrategy.KOMPRESS,+ )++ router.compress = fake_compress # type: ignore[method-assign]+ tool_text = "tool output " * 120+ messages = [+ {"role": "system", "content": "system instructions " * 120},+ {"role": "developer", "content": "developer instructions " * 120},+ {"role": "user", "content": "user prompt " * 120},+ {"role": "tool", "tool_call_id": "call_1", "content": tool_text},+ ]++ result = router.apply(messages, Tokenizer())++ assert result.messages[0]["content"] == messages[0]["content"]+ assert result.messages[1]["content"] == messages[1]["content"]+ assert result.messages[2]["content"] == messages[2]["content"]+ assert result.messages[3]["content"] == "COMPRESSED"+ assert calls == [tool_text]++def test_pipeline_extension_manager_replaces_events_and_ignores_failures(caplog):recorder = RecordingExtension()manager = PipelineExtensionManager(diff --git a/tests/test_cli/test_unwrap_claude.py b/tests/test_cli/test_unwrap_claude.pynew file mode 100644index 000000000..db6b9c7ba--- /dev/null+++ b/tests/test_cli/test_unwrap_claude.py@@ -0,0 +1,128 @@+from __future__ import annotations++import json+from pathlib import Path+from unittest.mock import patch++import pytest+from click.testing import CliRunner++from headroom.cli import wrap as wrap_cli+from headroom.cli.main import main+++def runner() -> CliRunner:+ return CliRunner()+++def test_remove_claude_rtk_hooks_preserves_unrelated_hooks(tmp_path: Path) -> None:+ settings = tmp_path / "settings.json"+ settings.write_text(+ json.dumps(+ {+ "model": "opus",+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Bash",+ "hooks": [+ {+ "type": "command",+ "command": "/Users/test/.claude/hooks/rtk-rewrite.sh",+ },+ {"type": "command", "command": "echo keep"},+ ],+ }+ ],+ "SessionStart": [+ {"matcher": "startup", "hooks": [{"type": "command", "command": "keep"}]}+ ],+ },+ }+ )+ + "\n",+ encoding="utf-8",+ )++ assert wrap_cli._remove_claude_rtk_hooks(settings) is True++ payload = json.loads(settings.read_text(encoding="utf-8"))+ pre_tool_hooks = payload["hooks"]["PreToolUse"][0]["hooks"]+ assert pre_tool_hooks == [{"type": "command", "command": "echo keep"}]+ assert payload["hooks"]["SessionStart"][0]["hooks"][0]["command"] == "keep"+++def test_unwrap_claude_removes_mcp_rtk_and_stops_proxy(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ home = str(tmp_path)+ monkeypatch.setenv("HOME", home)+ monkeypatch.setenv("USERPROFILE", home)+ claude_dir = tmp_path / ".claude"+ claude_dir.mkdir()+ settings = claude_dir / "settings.json"+ settings.write_text(+ json.dumps(+ {+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Bash",+ "hooks": [+ {"type": "command", "command": str(claude_dir / "rtk-rewrite.sh")}+ ],+ }+ ]+ }+ }+ )+ + "\n",+ encoding="utf-8",+ )+ stopped: list[int] = []+ unregistered: list[str] = []++ class Registrar:+ def detect(self) -> bool:+ return True++ def unregister_server(self, server_name: str) -> bool:+ unregistered.append(server_name)+ return True++ with (+ patch("headroom.mcp_registry.ClaudeRegistrar", return_value=Registrar()),+ patch(+ "headroom.cli.wrap._stop_local_proxy_for_unwrap",+ side_effect=lambda port: stopped.append(port) or "stopped",+ ),+ ):+ result = runner.invoke(main, ["unwrap", "claude", "--port", "9999"])++ assert result.exit_code == 0, result.output+ assert unregistered == ["headroom", "codebase-memory-mcp"]+ assert stopped == [9999]+ assert "Stopped local Headroom proxy on port 9999" in result.output+ assert "hooks" not in json.loads(settings.read_text(encoding="utf-8"))+++def test_unwrap_claude_keep_flags_skip_cleanup(+ runner: CliRunner,+) -> None:+ with (+ patch("headroom.mcp_registry.ClaudeRegistrar") as registrar,+ patch("headroom.cli.wrap._remove_claude_rtk_hooks") as remove_rtk,+ patch("headroom.cli.wrap._stop_local_proxy_for_unwrap") as stop_proxy,+ ):+ result = runner.invoke(+ main,+ ["unwrap", "claude", "--keep-mcp", "--keep-rtk", "--no-stop-proxy"],+ )++ assert result.exit_code == 0, result.output+ registrar.assert_not_called()+ remove_rtk.assert_not_called()+ stop_proxy.assert_not_called()diff --git a/tests/test_cli/test_wrap_codex.py b/tests/test_cli/test_wrap_codex.pyindex b04168acd..a9aa75875 100644--- a/tests/test_cli/test_wrap_codex.py+++ b/tests/test_cli/test_wrap_codex.py@@ -80,11 +80,30 @@ class TestStripCodexHeadroomBlocks:def test_removes_stray_top_level_model_provider_line(self) -> None:# Old wrap versions left `model_provider = "headroom"` outside markers.content = 'foo = 1\nmodel_provider = "headroom"\nbar = 2\n'- cleaned = wrap_mod._strip_codex_headroom_blocks(content)+ cleaned = wrap_mod._strip_codex_headroom_blocks(content, remove_mcp=True)assert 'model_provider = "headroom"' not in cleanedassert "foo = 1" in cleanedassert "bar = 2" in cleaned+ def test_removes_codex_mcp_blocks(self) -> None:+ content = (+ '[profiles.default]\nmodel = "gpt-4o"\n\n'+ f"{wrap_mod._CODEX_MCP_MARKER}\n"+ "[mcp_servers.headroom]\n"+ 'command = "headroom"\n'+ f"{wrap_mod._CODEX_MCP_END}\n\n"+ f"{wrap_mod._MEMORY_MCP_MARKER}\n"+ "[mcp_servers.headroom_memory]\n"+ 'command = "python"\n'+ f"{wrap_mod._MEMORY_MCP_END}\n"+ )++ cleaned = wrap_mod._strip_codex_headroom_blocks(content, remove_mcp=True)++ assert "[mcp_servers.headroom]" not in cleaned+ assert "[mcp_servers.headroom_memory]" not in cleaned+ assert 'model = "gpt-4o"' in cleaned+class TestSnapshotCodexConfig:"""Tests for ``_snapshot_codex_config_if_unwrapped``."""@@ -240,6 +259,35 @@ class TestInjectAndRestoreRoundTrip:assert 'model_provider = "headroom"' not in cleanedassert 'model = "gpt-4o"' in cleaned+ def test_unwrap_without_backup_removes_provider_and_mcp_blocks(+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+ ) -> None:+ _set_test_home(monkeypatch, tmp_path)+ config_dir = tmp_path / ".codex"+ config_dir.mkdir()+ config_file = config_dir / "config.toml"+ config_file.write_text(+ '[profiles.default]\nmodel = "gpt-4o"\n\n'+ f"{wrap_mod._CODEX_TOP_LEVEL_MARKER}\n"+ 'model_provider = "headroom"\n'+ f"{wrap_mod._CODEX_END_MARKER}\n\n"+ f"{wrap_mod._CODEX_MCP_MARKER}\n"+ "[mcp_servers.headroom]\n"+ 'command = "headroom"\n'+ f"{wrap_mod._CODEX_MCP_END}\n\n"+ f"{wrap_mod._MEMORY_MCP_MARKER}\n"+ "[mcp_servers.headroom_memory]\n"+ 'command = "python"\n'+ f"{wrap_mod._MEMORY_MCP_END}\n"+ )++ status, _ = wrap_mod._restore_codex_provider_config()++ assert status == "cleaned"+ cleaned = config_file.read_text()+ assert 'model = "gpt-4o"' in cleaned+ assert "headroom" not in cleaned+def test_unwrap_handles_malformed_prior_config(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:@@ -358,6 +406,62 @@ def test_wrap_codex_prepare_only_creates_backup_and_config(assert backup.read_text() == original+def test_start_proxy_uses_separate_session_for_signal_isolation(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ """Proxy child should not receive Ctrl-C intended for the wrapped CLI."""+ popen_kwargs: dict[str, object] = {}++ class FakeProc:+ returncode = None++ def poll(self) -> None:+ return None++ def fake_popen(*args: object, **kwargs: object) -> FakeProc:+ popen_kwargs.update(kwargs)+ return FakeProc()++ monkeypatch.setattr(wrap_mod, "_get_log_path", lambda: tmp_path / "proxy.log")+ monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: True)+ monkeypatch.setattr(wrap_mod.subprocess, "Popen", fake_popen)++ proc = wrap_mod._start_proxy(8787, agent_type="codex")++ assert isinstance(proc, FakeProc)+ assert popen_kwargs["start_new_session"] == (wrap_mod.os.name == "posix")+++def test_launch_tool_ignores_sigint_in_wrapper(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Ctrl-C should be handled by the child CLI, not kill the proxy from wrapper."""+ signal_handlers: dict[object, object] = {}++ class FakeCompleted:+ returncode = 0++ monkeypatch.setattr(wrap_mod, "_ensure_proxy", lambda *args, **kwargs: None)+ monkeypatch.setattr(+ wrap_mod.signal, "signal", lambda sig, fn: signal_handlers.setdefault(sig, fn)+ )+ monkeypatch.setattr(wrap_mod.subprocess, "run", lambda *args, **kwargs: FakeCompleted())++ with pytest.raises(SystemExit) as exc:+ wrap_mod._launch_tool(+ binary="codex",+ args=(),+ env={},+ port=8787,+ no_proxy=True,+ tool_label="CODEX",+ env_vars_display=[],+ )++ assert exc.value.code == 0+ assert signal_handlers[wrap_mod.signal.SIGINT] is wrap_mod._ignore_child_sigint++def test_wrap_codex_prepare_only_updates_stale_mcp_proxy_url(runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:@@ -407,7 +511,13 @@ def test_unwrap_codex_restores_prior_config_end_to_end(assert wrap_result.exit_code == 0, wrap_result.outputassert 'model_provider = "headroom"' in config_file.read_text()- unwrap_result = runner.invoke(main, ["unwrap", "codex"])+ stopped: list[int] = []++ with patch(+ "headroom.cli.wrap._stop_local_proxy_for_unwrap",+ side_effect=lambda port: stopped.append(port) or "stopped",+ ):+ unwrap_result = runner.invoke(main, ["unwrap", "codex", "--port", "9999"])assert unwrap_result.exit_code == 0, unwrap_result.output# Config must be byte-for-byte what the user had before wrap, and the@@ -416,6 +526,49 @@ def test_unwrap_codex_restores_prior_config_end_to_end(assert config_file.read_text() == originalassert 'model_provider = "headroom"' not in config_file.read_text()assert not (tmp_path / ".codex" / "config.toml.headroom-backup").exists()+ assert stopped == [9999]+ assert "Stopped local Headroom proxy on port 9999" in unwrap_result.output+++def test_unwrap_codex_no_stop_proxy_leaves_proxy_alone(+ runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ _set_test_home(monkeypatch, tmp_path)++ with patch("headroom.cli.wrap._stop_local_proxy_for_unwrap") as stop_proxy:+ result = runner.invoke(main, ["unwrap", "codex", "--no-stop-proxy"])++ assert result.exit_code == 0, result.output+ stop_proxy.assert_not_called()+++def test_stop_local_proxy_for_unwrap_kills_identified_headroom_proxy(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ killed: list[tuple[int, int]] = []++ monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: True)+ monkeypatch.setattr(wrap_mod, "_query_proxy_config", lambda port: {"pid": "12345"})+ monkeypatch.setattr(+ wrap_mod,+ "_kill_proxy_by_pid",+ lambda pid, port: killed.append((pid, port)) or True,+ )++ assert wrap_mod._stop_local_proxy_for_unwrap(8787) == "stopped"+ assert killed == [(12345, 8787)]+++def test_stop_local_proxy_for_unwrap_refuses_unidentified_listener(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: True)+ monkeypatch.setattr(wrap_mod, "_query_proxy_config", lambda port: None)++ with patch("headroom.cli.wrap._kill_proxy_by_pid") as kill_proxy:+ assert wrap_mod._stop_local_proxy_for_unwrap(8787) == "unidentified"++ kill_proxy.assert_not_called()def test_unwrap_codex_is_safe_noop_with_no_prior_wrap(diff --git a/tests/test_cli/test_wrap_openclaw.py b/tests/test_cli/test_wrap_openclaw.pyindex a880ff8de..c50ce7e67 100644--- a/tests/test_cli/test_wrap_openclaw.py+++ b/tests/test_cli/test_wrap_openclaw.py@@ -407,6 +407,28 @@ def test_build_openclaw_unwrap_entry_preserves_top_level_metadata() -> None:assert entry["config"] == {"customFlag": True}+def test_unwrap_openclaw_stops_proxy_by_default(runner: CliRunner) -> None:+ calls: list[dict] = []++ def which(name: str) -> str | None:+ return "openclaw" if name == "openclaw" else None++ with patch("headroom.cli.wrap.shutil.which", side_effect=which):+ with patch("headroom.cli.wrap.subprocess.run", side_effect=_make_successful_run(calls)):+ with patch(+ "headroom.cli.wrap._stop_local_proxy_for_unwrap",+ return_value="stopped",+ ) as stop_proxy:+ result = runner.invoke(+ main,+ ["unwrap", "openclaw", "--proxy-port", "9999", "--no-restart"],+ )++ assert result.exit_code == 0, result.output+ stop_proxy.assert_called_once_with(9999)+ assert "Stopped local Headroom proxy on port 9999" in result.output++def test_wrap_openclaw_no_auto_start_does_not_default_python_path(runner: CliRunner, plugin_dir: Path) -> None:diff --git a/tests/test_compression_store.py b/tests/test_compression_store.pyindex a471c8cab..764bd1671 100644--- a/tests/test_compression_store.py+++ b/tests/test_compression_store.py@@ -803,8 +803,40 @@ class TestCompressionStoreSearch:results = store.search(hash_key, "query")assert results == []+ def test_search_plain_text_returns_matching_chunks(self, store: CompressionStore):+ """search() can find content in Kompress-style plain-text originals."""+ original = (+ "The OpenAI handler contains def _compress_openai_responses_payload "+ "for Responses API live-zone compression. Other text is irrelevant."+ )+ hash_key = store.store(original=original, compressed="compressed")++ results = store.search(hash_key, "def _compress_openai_responses_payload")++ assert len(results) == 1+ assert results[0]["type"] == "text"+ assert "_compress_openai_responses_payload" in results[0]["text"]++ def test_search_json_object_returns_matching_leaf(self, store: CompressionStore):+ """search() can find values inside JSON objects, not only arrays."""+ original = json.dumps(+ {+ "module": {+ "name": "openai",+ "function": "_compress_openai_responses_payload",+ }+ }+ )+ hash_key = store.store(original=original, compressed="{}")++ results = store.search(hash_key, "_compress_openai_responses_payload")++ assert len(results) == 1+ assert results[0]["path"] == "module.function"+ assert results[0]["value"] == "_compress_openai_responses_payload"+def test_search_non_array_returns_empty(self, store: CompressionStore):- """search() returns empty for non-array content."""+ """search() returns empty for JSON objects without matching leaves."""hash_key = store.store(original=json.dumps({"key": "value"}), compressed="{}")results = store.search(hash_key, "query")assert results == []diff --git a/tests/test_compression_units.py b/tests/test_compression_units.pynew file mode 100644index 000000000..d012fce29--- /dev/null+++ b/tests/test_compression_units.py@@ -0,0 +1,160 @@+from __future__ import annotations++from headroom.transforms.compression_units import (+ CompressionUnit,+ RoutedCompressionUnit,+ compress_unit_with_router,+ compress_units_with_router,+)+from headroom.transforms.content_router import (+ CompressionStrategy,+ RouterCompressionResult,+)+++class TokenCounter:+ def count_text(self, text: str) -> int:+ return len(text.split())+++class Router:+ def __init__(self, compressed: str):+ self.compressed = compressed++ def compress(self, content: str, **_kwargs):+ return RouterCompressionResult(+ compressed=self.compressed,+ original=content,+ strategy_used=CompressionStrategy.KOMPRESS,+ )+++def test_compression_unit_accepts_token_shrinking_replacement():+ result = compress_unit_with_router(+ CompressionUnit(+ text="alpha beta gamma delta epsilon",+ provider="openai",+ endpoint="responses",+ role="tool",+ item_type="local_shell_call_output",+ min_bytes=1,+ ),+ router=Router("alpha beta"),+ tokenizer=TokenCounter(),+ )++ assert result.modified is True+ assert result.tokens_saved == 3+ assert result.compressed == "alpha beta"+ assert "router:openai:responses:local_shell_call_output:kompress" in result.transforms_applied+++def test_compression_unit_rejects_non_shrinking_replacement():+ result = compress_unit_with_router(+ CompressionUnit(+ text="alpha beta",+ provider="anthropic",+ endpoint="messages",+ role="tool",+ item_type="tool_result",+ min_bytes=1,+ ),+ router=Router("alpha beta gamma"),+ tokenizer=TokenCounter(),+ )++ assert result.modified is False+ assert result.reason == "rejected_not_smaller"+ assert result.original == "alpha beta"+++def test_compression_unit_respects_cache_zone_and_floor():+ frozen = compress_unit_with_router(+ CompressionUnit(+ text="alpha beta gamma delta",+ provider="anthropic",+ endpoint="messages",+ role="tool",+ item_type="tool_result",+ cache_zone="frozen",+ min_bytes=1,+ ),+ router=Router("alpha"),+ tokenizer=TokenCounter(),+ )+ small = compress_unit_with_router(+ CompressionUnit(+ text="small text",+ provider="openai",+ endpoint="responses",+ role="tool",+ item_type="function_call_output",+ min_bytes=500,+ ),+ router=Router("small"),+ tokenizer=TokenCounter(),+ )++ assert frozen.modified is False+ assert frozen.reason == "cache_zone_frozen"+ assert small.modified is False+ assert small.reason == "below_unit_floor"+++def test_batch_compression_preserves_provider_slot_references():+ routed = [+ RoutedCompressionUnit(+ unit=CompressionUnit(+ text="alpha beta gamma",+ provider="openai",+ endpoint="responses",+ role="tool",+ item_type="function_call_output",+ min_bytes=1,+ ),+ slot=("input", 3, "output"),+ ),+ RoutedCompressionUnit(+ unit=CompressionUnit(+ text="one two three",+ provider="gemini",+ endpoint="generateContent",+ role="user",+ item_type="part.text",+ min_bytes=1,+ ),+ slot={"path": ["contents", 0, "parts", 0, "text"]},+ ),+ ]++ results = compress_units_with_router(+ routed,+ router=Router("short"),+ tokenizer=TokenCounter(),+ )++ assert results[0][0] == ("input", 3, "output")+ assert results[1][0] == {"path": ["contents", 0, "parts", 0, "text"]}+ assert [result.modified for _slot, result in results] == [True, False]+++def test_compress_unit_protects_prompt_roles() -> None:+ for role, reason in [+ ("user", "protected_user_message"),+ ("developer", "protected_system_message"),+ ("system", "protected_system_message"),+ ("assistant", "protected_assistant_message"),+ ]:+ unit = CompressionUnit(+ text="alpha beta gamma delta",+ provider="openai",+ endpoint="responses",+ role=role,+ item_type="message",+ min_bytes=1,+ )++ result = compress_unit_with_router(unit, router=Router("alpha"), tokenizer=TokenCounter())++ assert result.modified is False+ assert result.reason == reasondiff --git a/tests/test_openai_codex_routing.py b/tests/test_openai_codex_routing.pyindex 02a34eb3d..9c317f08d 100644--- a/tests/test_openai_codex_routing.py+++ b/tests/test_openai_codex_routing.py@@ -246,6 +246,26 @@ def test_handle_openai_responses_routes_chatgpt_auth_to_backend_api(monkeypatch)assert response.status_code == 200+def test_handle_openai_responses_routes_api_key_auth_direct_to_openai(monkeypatch):+ request = _build_request(+ {"model": "gpt-4o-mini", "input": "hello"},+ {"Authorization": "Bearer sk-test"},+ )+ handler = _DummyOpenAIHandler()++ monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())++ response = anyio.run(handler.handle_openai_responses, request)++ assert handler.captured_request is not None+ method, url, headers, body = handler.captured_request+ assert method == "POST"+ assert url == "https://api.openai.com/v1/responses"+ assert headers.get("ChatGPT-Account-ID") is None+ assert body["input"] == "hello"+ assert response.status_code == 200++def test_handle_openai_responses_stream_skips_python_compression(monkeypatch):"""PR-C5: Python no longer compresses /v1/responses (Rust handles itnatively). The streaming forward path must still fire — only thediff --git a/tests/test_openai_codex_ws_lifecycle.py b/tests/test_openai_codex_ws_lifecycle.pyindex e13f650e6..eb3926085 100644--- a/tests/test_openai_codex_ws_lifecycle.py+++ b/tests/test_openai_codex_ws_lifecycle.py@@ -288,6 +288,7 @@ async def test_ws_session_metrics_include_response_completed_usage():assert recorded["input_tokens"] == 100assert recorded["output_tokens"] == 12assert recorded["cache_read_tokens"] == 75+ assert recorded["cache_write_tokens"] == 25assert recorded["uncached_input_tokens"] == 25diff --git a/tests/test_openai_responses_compression_units.py b/tests/test_openai_responses_compression_units.pynew file mode 100644index 000000000..7c5193c4e--- /dev/null+++ b/tests/test_openai_responses_compression_units.py@@ -0,0 +1,194 @@+from __future__ import annotations++from types import MethodType, SimpleNamespace++from headroom.proxy.handlers.openai import OpenAIHandlerMixin+from headroom.transforms.content_router import (+ CompressionStrategy,+ ContentRouter,+ RouterCompressionResult,+)+++class TokenCounter:+ def count_text(self, text: str) -> int:+ return len(text.split())+++def _handler_with_router(router: ContentRouter) -> OpenAIHandlerMixin:+ handler = OpenAIHandlerMixin()+ handler.openai_pipeline = SimpleNamespace(transforms=[router])+ handler.openai_provider = SimpleNamespace(+ get_token_counter=lambda _model: TokenCounter(),+ )+ return handler+++def test_openai_responses_adapter_compresses_only_live_text_slots():+ router = ContentRouter()++ def compress(self, content: str, **_kwargs):+ return RouterCompressionResult(+ compressed="kept words",+ original=content,+ strategy_used=CompressionStrategy.KOMPRESS,+ )++ router.compress = MethodType(compress, router)+ handler = _handler_with_router(router)+ long_text = " ".join(f"word{i}" for i in range(180))+ payload = {+ "model": "gpt-5",+ "input": [+ {"type": "reasoning", "encrypted_content": long_text},+ {"type": "function_call", "arguments": long_text},+ {"type": "local_shell_call_output", "call_id": "c1", "output": long_text},+ {+ "type": "message",+ "role": "user",+ "content": [{"type": "input_text", "text": long_text}],+ },+ ],+ }++ new_payload, modified, saved, transforms = (+ handler._compress_openai_responses_live_text_units_with_router(+ payload,+ model="gpt-5",+ request_id="req_test",+ )+ )++ assert modified is True+ assert saved > 0+ assert new_payload["input"][0]["encrypted_content"] == long_text+ assert new_payload["input"][1]["arguments"] == long_text+ assert new_payload["input"][2]["output"] == "kept words"+ assert new_payload["input"][3]["content"][0]["text"] == long_text+ assert any(t.startswith("router:openai:responses:") for t in transforms)+++def test_openai_responses_adapter_preserves_headroom_retrieve_outputs():+ router = ContentRouter()++ def compress(self, content: str, **_kwargs):+ return RouterCompressionResult(+ compressed="compressed retrieve output",+ original=content,+ strategy_used=CompressionStrategy.KOMPRESS,+ )++ router.compress = MethodType(compress, router)+ handler = _handler_with_router(router)+ retrieved = " ".join(f"retrieved{i}" for i in range(180))+ payload = {+ "model": "gpt-5",+ "input": [+ {+ "type": "function_call",+ "call_id": "call_retrieve",+ "name": "mcp__headroom__headroom_retrieve",+ "arguments": "{}",+ },+ {+ "type": "function_call_output",+ "call_id": "call_retrieve",+ "output": retrieved,+ },+ ],+ }++ new_payload, modified, saved, transforms = (+ handler._compress_openai_responses_live_text_units_with_router(+ payload,+ model="gpt-5",+ request_id="req_test",+ )+ )++ assert modified is False+ assert saved == 0+ assert transforms == []+ assert new_payload == payload+++def test_openai_responses_adapter_keeps_small_and_opaque_items():+ router = ContentRouter()++ def compress(self, content: str, **_kwargs):+ return RouterCompressionResult(+ compressed="short",+ original=content,+ strategy_used=CompressionStrategy.KOMPRESS,+ )++ router.compress = MethodType(compress, router)+ handler = _handler_with_router(router)+ payload = {+ "model": "gpt-5",+ "input": [+ {"type": "local_shell_call_output", "call_id": "c1", "output": "too small"},+ {"type": "compaction", "encrypted_content": " ".join(["secret"] * 200)},+ ],+ }++ new_payload, modified, saved, transforms = (+ handler._compress_openai_responses_live_text_units_with_router(+ payload,+ model="gpt-5",+ request_id="req_test",+ )+ )++ assert modified is False+ assert saved == 0+ assert transforms == []+ assert new_payload == payload+++def test_openai_responses_payload_routes_through_content_router_without_rust(+ monkeypatch,+):+ router = ContentRouter()++ def compress(self, content: str, **_kwargs):+ return RouterCompressionResult(+ compressed="compressed fallback",+ original=content,+ strategy_used=CompressionStrategy.KOMPRESS,+ )++ router.compress = MethodType(compress, router)+ handler = _handler_with_router(router)++ import headroom._core as core++ def rust_must_not_run(*_args, **_kwargs):+ raise AssertionError("Responses payload compression should route through ContentRouter")++ monkeypatch.setattr(core, "compress_openai_responses_live_zone", rust_must_not_run)++ payload = {+ "model": "gpt-5",+ "input": [+ {+ "type": "local_shell_call_output",+ "call_id": "c1",+ "output": " ".join(f"word{i}" for i in range(180)),+ }+ ],+ }++ new_payload, modified, saved, transforms, reason, _, _ = (+ handler._compress_openai_responses_payload(+ payload,+ model="gpt-5",+ request_id="req_router",+ )+ )++ assert modified is True+ assert saved > 0+ assert reason is None+ assert new_payload["input"][0]["output"] == "compressed fallback"+ assert any(t.startswith("router:openai:responses:") for t in transforms)diff --git a/tests/test_proxy_ccr.py b/tests/test_proxy_ccr.pyindex f3a64665d..d9c0ff7a4 100644--- a/tests/test_proxy_ccr.py+++ b/tests/test_proxy_ccr.py@@ -118,6 +118,35 @@ class TestCCRRetrieveEndpoint:assert "results" in dataassert data["count"] >= 1+ def test_retrieve_with_search_plain_text_original(self, client):+ """Query retrieval searches plain-text originals stored by Kompress."""+ store = get_compression_store()+ original = (+ "Codex WS compression stores plain text originals. "+ "The target symbol is _compress_openai_responses_payload."+ )+ hash_key = store.store(original=original, compressed="compressed")++ response = client.post(+ "/v1/retrieve",+ json={"hash": hash_key, "query": "_compress_openai_responses_payload"},+ )+ assert response.status_code == 200++ data = response.json()+ assert data["hash"] == hash_key+ assert data["count"] == 1+ assert data["results"][0]["type"] == "text"+ assert "_compress_openai_responses_payload" in data["results"][0]["text"]++ def test_retrieve_with_search_nonexistent_hash_returns_404(self, client):+ """Query mode should not mask a missing hash as an empty search."""+ response = client.post(+ "/v1/retrieve",+ json={"hash": "nonexistent123", "query": "anything"},+ )+ assert response.status_code == 404+def test_retrieve_increments_count(self, client):"""Each retrieval increments the retrieval count."""store = get_compression_store()@@ -185,6 +214,21 @@ class TestCCRRetrieveGetEndpoint:# Results should be a list (may be empty if BM25 threshold not met)assert isinstance(data["results"], list)+ def test_get_retrieve_with_query_plain_text_original(self, client):+ """GET query retrieval searches plain-text originals."""+ store = get_compression_store()+ hash_key = store.store(+ original="plain text contains _compress_openai_responses_payload",+ compressed="plain text",+ )++ response = client.get(f"/v1/retrieve/{hash_key}?query=_compress_openai_responses_payload")+ assert response.status_code == 200++ data = response.json()+ assert data["count"] == 1+ assert data["results"][0]["type"] == "text"+def test_get_retrieve_nonexistent(self, client):"""GET with nonexistent hash returns 404."""response = client.get("/v1/retrieve/nonexistent123")diff --git a/tests/test_proxy_dashboard_stats_cache.py b/tests/test_proxy_dashboard_stats_cache.pyindex e41f4a087..eea9521a3 100644--- a/tests/test_proxy_dashboard_stats_cache.py+++ b/tests/test_proxy_dashboard_stats_cache.py@@ -30,17 +30,25 @@ class _ToinStub:@pytest.fixture(autouse=True)def _reset_rtk_stats_cache() -> None:proxy_helpers._rtk_stats_cache.update({"expires_at": 0.0, "has_value": False, "value": None})+ proxy_helpers._rtk_session_baseline.update(+ {"initialized": False, "total_commands": 0, "tokens_saved": 0}+ )def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatch) -> None:now = {"value": 100.0}calls = {"run": 0}+ totals = [+ {"total_commands": 7, "total_saved": 1234},+ {"total_commands": 9, "total_saved": 1500},+ ]def _fake_run(*args, **kwargs):calls["run"] += 1+ summary = totals[min(calls["run"] - 1, len(totals) - 1)]return SimpleNamespace(returncode=0,- stdout=json.dumps({"summary": {"total_commands": 7, "total_saved": 1234}}),+ stdout=json.dumps({"summary": summary}),)monkeypatch.setattr(proxy_helpers.time, "monotonic", lambda: now["value"])@@ -53,8 +61,8 @@ def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatchassert first == secondassert first == {"installed": True,- "total_commands": 7,- "tokens_saved": 1234,+ "total_commands": 0,+ "tokens_saved": 0,"avg_savings_pct": 0.0,}assert calls["run"] == 1@@ -62,7 +70,12 @@ def test_get_rtk_stats_memoizes_subprocess_calls(monkeypatch: pytest.MonkeyPatchnow["value"] += proxy_helpers.RTK_STATS_CACHE_TTL_SECONDS + 0.1third = proxy_helpers._get_rtk_stats()- assert third == first+ assert third == {+ "installed": True,+ "total_commands": 2,+ "tokens_saved": 266,+ "avg_savings_pct": 0.0,+ }assert calls["run"] == 2@@ -135,8 +148,71 @@ def test_stats_cached_query_reuses_short_ttl_snapshot(monkeypatch: pytest.Monkeyassert first.json()["tokens"]["saved"] == 5assert first.json()["tokens"]["proxy_compression_saved"] == 0assert first.json()["tokens"]["rtk_saved"] == 5- assert first.json()["savings"]["by_layer"]["compression"]["tokens"] == 5+ assert first.json()["tokens"]["all_layers_saved"] == 5+ assert (+ first.json()["tokens"]["savings_percent"]+ == first.json()["tokens"]["all_layers_savings_percent"]+ )+ assert first.json()["savings"]["by_layer"]["compression"]["tokens"] == 0assert first.json()["savings"]["by_layer"]["compression"]["rtk_tokens"] == 5+ assert first.json()["savings"]["by_layer"]["compression"]["all_layers_tokens"] == 5+++def test_stats_reset_clears_runtime_proxy_counters(monkeypatch: pytest.MonkeyPatch) -> None:+ pytest.importorskip("fastapi")+ from fastapi.testclient import TestClient++ import headroom.proxy.server as server+ from headroom.proxy.loopback_guard import require_loopback+ from headroom.proxy.server import ProxyConfig, create_app++ monkeypatch.setattr(+ server,+ "get_compression_store",+ lambda: _StatsStub({"store": 0}, "store", {}),+ )+ monkeypatch.setattr(+ server,+ "get_telemetry_collector",+ lambda: _StatsStub({"telemetry": 0}, "telemetry", {}),+ )+ monkeypatch.setattr(+ server,+ "get_compression_feedback",+ lambda: _StatsStub({"feedback": 0}, "feedback", {}),+ )+ monkeypatch.setattr(server, "_get_rtk_stats", lambda: None)+ monkeypatch.setattr(server, "get_toin", lambda: _ToinStub())++ app = create_app(+ ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ ccr_inject_tool=False,+ ccr_handle_responses=False,+ ccr_context_tracking=False,+ )+ )+ app.dependency_overrides[require_loopback] = lambda: None++ with TestClient(app) as client:+ proxy = client.app.state.proxy+ proxy.metrics.tokens_saved_total = 123+ proxy.metrics.tokens_input_total = 456+ proxy.metrics.requests_total = 2++ before = client.get("/stats").json()+ reset = client.post("/stats/reset")+ after = client.get("/stats").json()++ assert before["tokens"]["proxy_compression_saved"] == 123+ assert reset.status_code == 200+ assert after["tokens"]["proxy_compression_saved"] == 0+ assert after["tokens"]["input"] == 0+ assert after["requests"]["total"] == 0def test_dashboard_uses_cached_stats_and_lazy_history_feed_polling() -> None:diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.pyindex 769f35e1e..2c8f4fa6f 100644--- a/tests/test_proxy_handler_helpers.py+++ b/tests/test_proxy_handler_helpers.py@@ -7,6 +7,7 @@ from unittest.mock import patchfrom headroom.proxy.handlers.anthropic import AnthropicHandlerMixinfrom headroom.proxy.handlers.openai import OpenAIHandlerMixin, _decode_openai_bearer_payload+from headroom.proxy.helpers import _headroom_bypass_enableddef _jwt(payload: object) -> str:@@ -79,6 +80,17 @@ def test_openai_handler_prefix_helpers_cover_edge_cases() -> None:assert changed == 1+def test_headroom_bypass_helper_is_transport_neutral() -> None:+ assert _headroom_bypass_enabled({"x-headroom-bypass": "true"}) is True+ assert _headroom_bypass_enabled({"x-headroom-bypass": " TRUE "}) is True+ assert _headroom_bypass_enabled({"x-headroom-mode": "passthrough"}) is True+ assert _headroom_bypass_enabled({"x-headroom-mode": " PASSTHROUGH "}) is True+ assert _headroom_bypass_enabled({"x-headroom-bypass": "false"}) is False+ assert _headroom_bypass_enabled({}) is False+ assert _headroom_bypass_enabled(None) is False+ assert OpenAIHandlerMixin._headroom_bypass_enabled({"x-headroom-bypass": "true"}) is True++def test_anthropic_tool_sort_and_context_append_helpers() -> None:tools = [{"type": "function", "function": {"name": "beta"}},diff --git a/tests/test_proxy_openai_responses_bypass.py b/tests/test_proxy_openai_responses_bypass.pynew file mode 100644index 000000000..ceeb9d7fd--- /dev/null+++ b/tests/test_proxy_openai_responses_bypass.py@@ -0,0 +1,109 @@+from __future__ import annotations++from types import SimpleNamespace+from typing import Any++import httpx+import pytest++pytest.importorskip("fastapi")++from fastapi.testclient import TestClient # noqa: E402++from headroom.proxy.loopback_guard import require_loopback # noqa: E402+from headroom.proxy.server import ProxyConfig, create_app # noqa: E402+++class _MemoryHandler:+ def __init__(self) -> None:+ self.search_calls = 0+ self.tool_calls = 0+ self.config = SimpleNamespace(inject_context=True, inject_tools=True)++ async def search_and_format_context(self, user_id: str, messages: list[dict[str, Any]]) -> str:+ self.search_calls += 1+ return "memory context that must not be injected"++ def compute_memory_tool_definitions(self, provider: str) -> list[dict[str, Any]]:+ self.tool_calls += 1+ return [+ {+ "type": "function",+ "function": {+ "name": "memory_search",+ "description": "search memory",+ "parameters": {"type": "object", "properties": {}},+ },+ }+ ]++ def has_memory_tool_calls(self, response: dict[str, Any], provider: str) -> bool:+ return False+++def test_responses_bypass_skips_memory_and_compression_mutation() -> None:+ app = create_app(+ ProxyConfig(+ optimize=True,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ )+ )+ app.dependency_overrides[require_loopback] = lambda: None++ original_input = [+ {+ "type": "message",+ "role": "user",+ "content": [{"type": "input_text", "text": "summarize"}],+ },+ {+ "type": "function_call_output",+ "call_id": "call_1",+ "output": "large tool output " * 200,+ },+ ]+ captured: dict[str, Any] = {}++ with TestClient(app) as client:+ proxy = client.app.state.proxy+ memory_handler = _MemoryHandler()+ proxy.memory_handler = memory_handler++ async def _fake_retry(+ method: str,+ url: str,+ headers: dict[str, str],+ body: dict[str, Any],+ stream: bool = False,+ **kwargs: Any,+ ) -> httpx.Response:+ captured["body"] = body+ return httpx.Response(+ 200,+ json={+ "id": "resp_1",+ "output": [],+ "usage": {"input_tokens": 10, "output_tokens": 1},+ },+ )++ proxy._retry_request = _fake_retry++ response = client.post(+ "/v1/responses",+ headers={+ "authorization": "Bearer test-key",+ "x-headroom-bypass": "true",+ "x-headroom-user-id": "user-1",+ },+ json={"model": "gpt-4o-mini", "input": original_input},+ )++ assert response.status_code == 200+ assert captured["body"]["input"] == original_input+ assert "tools" not in captured["body"]+ assert memory_handler.search_calls == 0+ assert memory_handler.tool_calls == 0diff --git a/tests/test_proxy_openai_responses_integration.py b/tests/test_proxy_openai_responses_integration.pyindex 4ae97963a..aa99b809d 100644--- a/tests/test_proxy_openai_responses_integration.py+++ b/tests/test_proxy_openai_responses_integration.py@@ -22,6 +22,7 @@ pytest.importorskip("httpx")from fastapi.testclient import TestClient # noqa: E402+from headroom.proxy.loopback_guard import require_loopback # noqa: E402from headroom.proxy.server import ProxyConfig, create_app # noqa: E402@@ -35,6 +36,7 @@ def openai_responses_client():cost_tracking_enabled=False,)app = create_app(config)+ app.dependency_overrides[require_loopback] = lambda: Nonewith TestClient(app) as client:yield client@@ -295,8 +297,9 @@ class TestOpenAIResponsesCompression:assert response.status_code == 200stats = openai_responses_client.get("/stats").json()- # With bypass, no tokens should be saved- assert stats["tokens"]["saved"] == 0+ # With bypass, proxy compression should not save tokens. The headline+ # saved count may include RTK CLI savings from the developer shell.+ assert stats["tokens"]["proxy_compression_saved"] == 0class TestOpenAIResponsesStats:diff --git a/tests/test_proxy_streaming_request_logger.py b/tests/test_proxy_streaming_request_logger.pyindex bc36dd6e3..aad6d50c0 100644--- a/tests/test_proxy_streaming_request_logger.py+++ b/tests/test_proxy_streaming_request_logger.py@@ -7,6 +7,7 @@ The non-streaming Anthropic path and the Bedrock streaming path were theonly ones that called `self.logger.log(...)`."""+import jsonfrom unittest.mock import AsyncMock, MagicMockimport httpx@@ -49,6 +50,35 @@ def _stream_state(output_tokens: int = 42) -> dict:}+def test_parse_openai_responses_completed_usage_from_sse_buffer():+ proxy = _build_proxy_with_real_logger(log_full_messages=False)+ completed = {+ "type": "response.completed",+ "response": {+ "id": "resp_1",+ "usage": {+ "input_tokens": 844_000,+ "input_tokens_details": {"cached_tokens": 657_400},+ "output_tokens": 6_635,+ },+ },+ }+ state = {+ "sse_buffer": bytearray(+ f"event: response.completed\ndata: {json.dumps(completed)}\n\n".encode()+ )+ }++ usage = proxy._parse_sse_usage_from_buffer(state, "openai")++ assert usage == {+ "input_tokens": 844_000,+ "output_tokens": 6_635,+ "cache_read_input_tokens": 657_400,+ }+ assert state["sse_buffer"] == bytearray()++@pytest.mark.asyncioasync def test_finalize_stream_response_logs_request_for_feed():proxy = _build_proxy_with_real_logger(log_full_messages=False)@@ -153,6 +183,51 @@ async def test_finalize_stream_response_handles_zero_original_tokens():assert entries[0]["savings_percent"] == 0+async def test_finalize_openai_responses_stream_uses_provider_usage_for_dashboard():+ proxy = _build_proxy_with_real_logger(log_full_messages=False)+ state = _stream_state(output_tokens=6_635)+ state["input_tokens"] = 844_000+ state["cache_read_input_tokens"] = 657_400++ await proxy._finalize_stream_response(+ body={"model": "gpt-5.5", "input": [{"type": "message", "role": "user"}]},+ provider="openai",+ model="gpt-5.5",+ request_id="req-openai-responses-stream",+ original_tokens=0,+ optimized_tokens=0,+ tokens_saved=663_000,+ transforms_applied=["openai_responses_live_zone"],+ optimization_latency=26.0,+ stream_state=state,+ start_time=0.0,+ )++ entries = proxy.logger.get_recent(10)+ assert len(entries) == 1+ entry = entries[0]+ assert entry["input_tokens_optimized"] == 844_000+ assert entry["input_tokens_original"] == 1_507_000+ assert entry["tokens_saved"] == 663_000+ assert entry["savings_percent"] == pytest.approx(663_000 / 1_507_000 * 100)+ assert entry["output_tokens"] == 6_635++ proxy.metrics.record_request.assert_awaited_once()+ metrics_kwargs = proxy.metrics.record_request.await_args.kwargs+ assert metrics_kwargs["input_tokens"] == 844_000+ assert metrics_kwargs["output_tokens"] == 6_635+ assert metrics_kwargs["tokens_saved"] == 663_000+ assert metrics_kwargs["cache_read_tokens"] == 657_400+ assert metrics_kwargs["uncached_input_tokens"] == 186_600++ proxy.cost_tracker.record_tokens.assert_called_once()+ cost_args, cost_kwargs = proxy.cost_tracker.record_tokens.call_args+ assert cost_args[:3] == ("gpt-5.5", 663_000, 844_000)+ assert cost_kwargs["cache_read_tokens"] == 657_400+ assert cost_kwargs["uncached_tokens"] == 186_600++@pytest.mark.asyncioasync def test_finalize_stream_response_no_op_when_logger_disabled():proxy = _build_proxy_with_real_logger(log_full_messages=False)diff --git a/tests/test_responses_pyo3_compression.py b/tests/test_responses_pyo3_compression.pyindex e3ffd6fe2..58d756d95 100644--- a/tests/test_responses_pyo3_compression.py+++ b/tests/test_responses_pyo3_compression.py@@ -48,21 +48,21 @@ class TestPassthroughCases:def test_not_json_passthrough(self):compress = _ensure_binding()body = b"this is not JSON at all"- out, modified, _saved, _transforms = compress(body, "payg", "gpt-4o-mini")+ out, modified, _saved, _transforms, _reason = compress(body, "payg", "gpt-4o-mini")assert out == bodyassert modified is Falsedef test_no_input_array_passthrough(self):compress = _ensure_binding()body = json.dumps({"model": "gpt-4o-mini"}).encode()- out, modified, _saved, _transforms = compress(body, "payg", "gpt-4o-mini")+ out, modified, _saved, _transforms, _reason = compress(body, "payg", "gpt-4o-mini")assert out == bodyassert modified is Falsedef test_empty_input_array_passthrough(self):compress = _ensure_binding()body = json.dumps({"model": "gpt-4o-mini", "input": []}).encode()- out, modified, _saved, _transforms = compress(body, "payg", "gpt-4o-mini")+ out, modified, _saved, _transforms, _reason = compress(body, "payg", "gpt-4o-mini")assert out == bodyassert modified is False@@ -76,7 +76,7 @@ class TestPassthroughCases:"input": [{"type": "message", "role": "user", "content": "hi"}],}).encode()- out, modified, _saved, _transforms = compress(body, "payg", "gpt-4o-mini")+ out, modified, _saved, _transforms, _reason = compress(body, "payg", "gpt-4o-mini")assert modified is False# Body should be byte-equal (passthrough, not re-serialized).assert out == body@@ -94,7 +94,7 @@ class TestAuthModeAccepted:compress = _ensure_binding()body = json.dumps({"model": "gpt-4o-mini", "input": []}).encode()# Should not raise on any string input.- out, modified, _saved, _transforms = compress(body, auth_mode, "gpt-4o-mini")+ out, modified, _saved, _transforms, _reason = compress(body, auth_mode, "gpt-4o-mini")assert isinstance(out, bytes)assert modified is False@@ -105,7 +105,7 @@ class TestModelDefault:def test_empty_model_uses_default(self):compress = _ensure_binding()body = json.dumps({"input": []}).encode()- out, modified, _saved, _transforms = compress(body, "payg", "")+ out, modified, _saved, _transforms, _reason = compress(body, "payg", "")assert isinstance(out, bytes)assert modified is False@@ -118,13 +118,15 @@ class TestNoExceptionsLeak:def test_garbage_bytes_no_raise(self):compress = _ensure_binding()- out, modified, _saved, _transforms = compress(b"\xff\xfe\x00\xff", "payg", "gpt-4o-mini")+ out, modified, _saved, _transforms, _reason = compress(+ b"\xff\xfe\x00\xff", "payg", "gpt-4o-mini"+ )assert modified is Falseassert out == b"\xff\xfe\x00\xff"def test_empty_body_no_raise(self):compress = _ensure_binding()- out, modified, _saved, _transforms = compress(b"", "payg", "gpt-4o-mini")+ out, modified, _saved, _transforms, _reason = compress(b"", "payg", "gpt-4o-mini")assert modified is Falseassert out == b""@@ -142,11 +144,12 @@ class TestTelemetryFields:def test_no_change_returns_zero_savings_and_empty_transforms(self):compress = _ensure_binding()body = json.dumps({"model": "gpt-4o-mini", "input": []}).encode()- out, modified, saved, transforms = compress(body, "payg", "gpt-4o-mini")+ out, modified, saved, transforms, reason = compress(body, "payg", "gpt-4o-mini")assert modified is Falseassert out == bodyassert saved == 0assert transforms == []+ assert reason == "no_eligible_items"def test_field_types(self):"""Pin the wire shape so downstream callers don't break."""@@ -154,13 +157,14 @@ class TestTelemetryFields:body = json.dumps({"model": "gpt-4o-mini", "input": []}).encode()result = compress(body, "payg", "gpt-4o-mini")assert isinstance(result, tuple)- assert len(result) == 4- out, modified, saved, transforms = result+ assert len(result) == 5+ out, modified, saved, transforms, reason = resultassert isinstance(out, bytes)assert isinstance(modified, bool)assert isinstance(saved, int)assert isinstance(transforms, list)assert all(isinstance(t, str) for t in transforms)+ assert reason is None or isinstance(reason, str)def test_large_local_shell_output_compresses_with_telemetry(self):"""End-to-end check: a payload large enough to clear the@@ -186,10 +190,11 @@ class TestTelemetryFields:],}).encode()- out, modified, saved, transforms = compress(body, "payg", "gpt-4o")+ out, modified, saved, transforms, reason = compress(body, "payg", "gpt-4o")assert modified is Trueassert saved > 0assert transforms, "expected at least one strategy in transforms"+ assert reason is Nonenew_doc = json.loads(out)assert new_doc["input"][0]["type"] == "local_shell_call_output"assert len(new_doc["input"][0]["output"]) < len(log_body)diff --git a/tests/test_responses_ws_pyo3_compression.py b/tests/test_responses_ws_pyo3_compression.pyindex 632856f9e..1da24eb5d 100644--- a/tests/test_responses_ws_pyo3_compression.py+++ b/tests/test_responses_ws_pyo3_compression.py@@ -36,6 +36,7 @@ def _ensure_binding():def _ws_compress_first_frame(first_msg_raw: str,auth_mode_value: str = "payg",+ bypass: bool = False,) -> tuple[str, bool]:"""Replicates the WS-handler compression block as a pure function.@@ -45,6 +46,9 @@ def _ws_compress_first_frame(up a full WebSocket fixture. If you change the handler'scompression block, mirror it here so the tests catch the drift."""+ if bypass:+ return first_msg_raw, False+compress = _ensure_binding()try:@@ -60,7 +64,9 @@ def _ws_compress_first_frame(model = (inner.get("model") if isinstance(inner, dict) else None) or ""inner_bytes = json.dumps(inner).encode("utf-8")- new_bytes, modified, _saved, _transforms = compress(inner_bytes, auth_mode_value, model)+ new_bytes, modified, _saved, _transforms, _reason = compress(+ inner_bytes, auth_mode_value, model+ )if not modified:return first_msg_raw, False@@ -111,6 +117,37 @@ class TestWrappedEnvelopeShape:assert modified is Falseassert json.loads(out) == json.loads(first_msg)+ def test_bypass_header_short_circuits_first_frame(self):+ first_msg = json.dumps(+ {+ "type": "response.create",+ "response": {+ "model": "gpt-5",+ "input": [+ {+ "type": "function_call_output",+ "call_id": "call_1",+ "output": json.dumps(+ [+ {+ "id": i,+ "name": f"Item {i}",+ "desc": "large repeated payload " * 20,+ }+ for i in range(100)+ ]+ ),+ }+ ],+ },+ }+ )++ out, modified = _ws_compress_first_frame(first_msg, bypass=True)++ assert modified is False+ assert out == first_msg+class TestUnwrappedShape:"""Older Codex versions (and some test fixtures) send the Responses