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: A6 — anthropic-beta and openai-beta deterministic merge + session-sticky
chopratejasaec5ba325386
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 66d7d5528..dba9eb042 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",- "version": "0.20.11"+ "version": "0.20.12"},"plugins": [{"name": "headroom","source": "./plugins/headroom-agent-hooks","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",- "version": "0.20.11",+ "version": "0.20.12","author": {"name": "Headroom Contributors","url": "https://github.com/chopratejas/headroom"diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.jsonindex 66d7d5528..dba9eb042 100644--- a/.github/plugin/marketplace.json+++ b/.github/plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",- "version": "0.20.11"+ "version": "0.20.12"},"plugins": [{"name": "headroom","source": "./plugins/headroom-agent-hooks","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",- "version": "0.20.11",+ "version": "0.20.12","author": {"name": "Headroom Contributors","url": "https://github.com/chopratejas/headroom"diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex ea96872a8..9f64e839a 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -750,6 +750,51 @@ class AnthropicHandlerMixin:frozen_message_count,)+ # PR-A6 (P5-50, preps P0-6): session-sticky `anthropic-beta` merge.+ # Read the client's beta value (note: anthropic-beta is NOT+ # an x-headroom-* header so it survived the A5 strip), union+ # with previously-seen tokens for this session, and update+ # the tracker. Memory-injection (below at line ~1244) uses+ # `merge_anthropic_beta` to add `context-management-2025-06-27`+ # on top of the sticky baseline. Order matters: session-sticky+ # FIRST so we have the canonical baseline; memory injection+ # adds Headroom-required tokens AFTER.+ from headroom.proxy.helpers import (+ get_session_beta_tracker,+ log_beta_header_merge,+ )++ _client_beta_value = headers.get("anthropic-beta")+ _client_beta_count = (+ len([t for t in (_client_beta_value or "").split(",") if t.strip()])+ if _client_beta_value+ else 0+ )+ _sticky_beta_value = get_session_beta_tracker().record_and_get_sticky_betas(+ provider="anthropic",+ session_id=session_id,+ client_value=_client_beta_value,+ )+ _sticky_beta_count = (+ len([t for t in _sticky_beta_value.split(",") if t.strip()])+ if _sticky_beta_value+ else 0+ )+ if _sticky_beta_value and _sticky_beta_value != (_client_beta_value or ""):+ headers["anthropic-beta"] = _sticky_beta_value+ elif not _sticky_beta_value and "anthropic-beta" in headers:+ # Sticky value can only equal "" when both client and+ # session are empty; preserve the (absent) client state.+ pass+ log_beta_header_merge(+ provider="anthropic",+ session_id=session_id,+ client_betas_count=_client_beta_count,+ sticky_betas_count=_sticky_beta_count,+ headroom_added=[],+ request_id=request_id,+ )+# In cache mode, avoid rewriting any message body bytes. The latest user# turn becomes historical on the next request, so even "latest turn only"# rewrites can invalidate the next cache read when the client resends the@@ -1236,18 +1281,55 @@ class AnthropicHandlerMixin:]logger.info(f"[{request_id}] Memory: Injected tools: {tool_names}")- # Add beta headers for native memory tool+ # Add beta headers for native memory tool. PR-A6+ # (P5-50): use the deterministic `merge_anthropic_beta`+ # helper instead of ad-hoc string concat. Order:+ # client tokens first (preserved from session-sticky+ # baseline above), then Headroom-required tokens.+ # The session tracker already recorded the client+ # value; we append Headroom-required tokens here so+ # the next turn re-applies them deterministically.beta_headers = self.memory_handler.get_beta_headers()if beta_headers:+ from headroom.proxy.helpers import (+ log_beta_header_merge as _log_beta_header_merge_mem,+ )+ from headroom.proxy.helpers import (+ merge_anthropic_beta,+ )+for key, value in beta_headers.items():- # Merge with existing beta header if present- existing = headers.get(key, "")- if existing and value not in existing:- headers[key] = f"{existing},{value}"- else:+ if key.lower() != "anthropic-beta":+ # Defensive: memory handler currently+ # only emits anthropic-beta. Any future+ # provider-specific beta header would+ # need its own merge helper.headers[key] = value+ continue+ existing_value = headers.get(key, "")+ required_tokens = [t.strip() for t in value.split(",") if t.strip()]+ merged = merge_anthropic_beta(existing_value, required_tokens)+ _existing_count = (+ len([t for t in existing_value.split(",") if t.strip()])+ if existing_value+ else 0+ )+ _merged_count = (+ len([t for t in merged.split(",") if t.strip()])+ if merged+ else 0+ )+ headers[key] = merged+ _log_beta_header_merge_mem(+ provider="anthropic",+ session_id=session_id,+ client_betas_count=_existing_count,+ sticky_betas_count=_merged_count,+ headroom_added=required_tokens,+ request_id=request_id,+ )logger.info(- f"[{request_id}] Memory: Added beta header: {key}={headers[key]}"+ f"[{request_id}] Memory: Added beta header: {key}={merged}")if memory_context_injected or memory_tools_injected:diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex aede4323f..a96194963 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -357,6 +357,48 @@ class OpenAIHandlerMixin:openai_prefix_tracker = self.session_tracker_store.get_or_create(openai_session_id, "openai")++ # PR-A6 (P5-50, preps P0-6): session-sticky `OpenAI-Beta` merge.+ # Same pattern as anthropic.py — read client value, union with+ # session-seen tokens, update tracker. WS auto-injection of+ # `responses_websockets=2026-02-06` lives on the WS handler;+ # chat-completions has no Headroom-required tokens today, so the+ # merge effectively just makes the client value byte-stable+ # across turns.+ from headroom.proxy.helpers import (+ get_session_beta_tracker as _get_session_beta_tracker_chat,+ )+ from headroom.proxy.helpers import (+ log_beta_header_merge as _log_beta_header_merge_chat,+ )++ _client_openai_beta = headers.get("openai-beta")+ _client_openai_beta_count = (+ len([t for t in (_client_openai_beta or "").split(",") if t.strip()])+ if _client_openai_beta+ else 0+ )+ _sticky_openai_beta = _get_session_beta_tracker_chat().record_and_get_sticky_betas(+ provider="openai",+ session_id=openai_session_id,+ client_value=_client_openai_beta,+ )+ _sticky_openai_beta_count = (+ len([t for t in _sticky_openai_beta.split(",") if t.strip()])+ if _sticky_openai_beta+ else 0+ )+ if _sticky_openai_beta and _sticky_openai_beta != (_client_openai_beta or ""):+ headers["openai-beta"] = _sticky_openai_beta+ _log_beta_header_merge_chat(+ provider="openai",+ session_id=openai_session_id,+ client_betas_count=_client_openai_beta_count,+ sticky_betas_count=_sticky_openai_beta_count,+ headroom_added=[],+ request_id=request_id,+ )+openai_frozen_count = openai_prefix_tracker.get_frozen_message_count()if is_cache_mode(self.config.mode):openai_frozen_count = self._strict_previous_turn_frozen_count(@@ -1166,6 +1208,45 @@ class OpenAIHandlerMixin:request_id=request_id,)+ # PR-A6 (P5-50, preps P0-6): session-sticky `OpenAI-Beta` merge+ # for /v1/responses. Compute a session_id off the same store the+ # chat handler uses so multi-endpoint clients within one+ # conversation share the sticky-token set.+ _responses_session_id = self.session_tracker_store.compute_session_id(+ request, model, messages+ )+ from headroom.proxy.helpers import (+ get_session_beta_tracker as _get_session_beta_tracker_resp,+ )+ from headroom.proxy.helpers import (+ log_beta_header_merge as _log_beta_header_merge_resp,+ )++ _client_resp_beta = headers.get("openai-beta")+ _client_resp_beta_count = (+ len([t for t in (_client_resp_beta or "").split(",") if t.strip()])+ if _client_resp_beta+ else 0+ )+ _sticky_resp_beta = _get_session_beta_tracker_resp().record_and_get_sticky_betas(+ provider="openai",+ session_id=_responses_session_id,+ client_value=_client_resp_beta,+ )+ _sticky_resp_beta_count = (+ len([t for t in _sticky_resp_beta.split(",") if t.strip()]) if _sticky_resp_beta else 0+ )+ if _sticky_resp_beta and _sticky_resp_beta != (_client_resp_beta or ""):+ headers["openai-beta"] = _sticky_resp_beta+ _log_beta_header_merge_resp(+ provider="openai",+ session_id=_responses_session_id,+ client_betas_count=_client_resp_beta_count,+ sticky_betas_count=_sticky_resp_beta_count,+ headroom_added=[],+ request_id=request_id,+ )+# Memory: Get user ID when memory is enabled. Reads `request.headers`# directly because `headers` was stripped of `x-headroom-*` (PR-A5).memory_user_id: str | None = None@@ -1707,9 +1788,59 @@ class OpenAIHandlerMixin:upstream_headers = await apply_copilot_api_auth(upstream_headers, url=upstream_url)# Ensure the required beta header is present — OpenAI returns 500 without it.- # Codex sends `responses_websockets=2026-02-06`; only inject if missing entirely.- if "openai-beta" not in _lower_headers:- upstream_headers["OpenAI-Beta"] = "responses_websockets=2026-02-06"+ # PR-A6 (P5-50): use the deterministic `merge_openai_beta` helper+ # so the auto-injected `responses_websockets=2026-02-06` is+ # appended to the client's value (preserving order, deduping+ # case-insensitively) rather than overwriting it. The+ # SessionBetaTracker also records the merge so a future cross-+ # connection sticky model can replay tokens by session_id.+ from headroom.proxy.helpers import (+ get_session_beta_tracker as _get_session_beta_tracker_ws,+ )+ from headroom.proxy.helpers import (+ log_beta_header_merge as _log_beta_header_merge_ws,+ )+ from headroom.proxy.helpers import merge_openai_beta as _merge_openai_beta_ws++ _ws_required_tokens = ["responses_websockets=2026-02-06"]+ # Read the original (pre-merge) client value from the WS headers+ # to preserve casing and ordering.+ _ws_client_beta_value: str | None = None+ for _k, _v in upstream_headers.items():+ if _k.lower() == "openai-beta":+ _ws_client_beta_value = _v+ break+ # Record session-stickiness BEFORE adding required tokens so the+ # tracker stores the canonical client baseline.+ _ws_sticky_beta = _get_session_beta_tracker_ws().record_and_get_sticky_betas(+ provider="openai",+ session_id=session_id,+ client_value=_ws_client_beta_value,+ )+ _ws_merged_beta = _merge_openai_beta_ws(_ws_sticky_beta, _ws_required_tokens)+ # Replace any existing case-variants of openai-beta with the+ # canonical "OpenAI-Beta" key carrying the merged value.+ _ws_existing_keys = [_k for _k in upstream_headers if _k.lower() == "openai-beta"]+ for _k in _ws_existing_keys:+ del upstream_headers[_k]+ if _ws_merged_beta:+ upstream_headers["OpenAI-Beta"] = _ws_merged_beta+ _ws_client_beta_count = (+ len([t for t in (_ws_client_beta_value or "").split(",") if t.strip()])+ if _ws_client_beta_value+ else 0+ )+ _ws_merged_beta_count = (+ len([t for t in _ws_merged_beta.split(",") if t.strip()]) if _ws_merged_beta else 0+ )+ _log_beta_header_merge_ws(+ provider="openai",+ session_id=session_id,+ client_betas_count=_ws_client_beta_count,+ sticky_betas_count=_ws_merged_beta_count,+ headroom_added=_ws_required_tokens,+ request_id=request_id,+ )logger.debug(f"[{request_id}] WS upstream headers: "diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 01c26da34..24bd1ce9a 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -15,6 +15,7 @@ import osimport randomimport threadingimport time+from collections import OrderedDictfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Literal, cast@@ -655,6 +656,325 @@ def log_outbound_headers()+# ---------------------------------------------------------------------------+# Beta-header merge + per-session stickiness (PR-A6 — fixes P5-50; preps P0-6).+# ---------------------------------------------------------------------------+#+# Anthropic's `anthropic-beta` and OpenAI's `OpenAI-Beta` request headers+# carry a comma-separated list of opt-in beta tokens. Two cache-killer+# patterns motivated PR-A6:+#+# 1. Mid-session mutation: when memory is enabled the proxy historically+# did an ad-hoc concat of `context-management-2025-06-27` onto the+# client value (anthropic.py:1244-1248) — every variant produced a+# different byte sequence and the order was undefined when the same+# client value already contained a Headroom-required token.+#+# 2. Token drop-out across turns: clients (Claude Code, Codex CLI) MAY+# drop a beta token between turn N and turn N+1 even when the proxy+# mutated turn N to add it. The cache hot zone is positional, so the+# next turn's prefix bytes hash differently and the prefix-cache+# read misses.+#+# PR-A6 introduces:+# * `merge_anthropic_beta` / `merge_openai_beta`: deterministic, pure,+# order-preserving merge. Client tokens first (in their original order),+# then Headroom-required tokens (in the order passed). Dedupe is+# case-insensitive but preserves original casing of first occurrence.+# Per Anthropic guide §6.3 #6: sticky-on means we add but never reorder.+#+# * `SessionBetaTracker`: bounded LRU cache keyed by `(provider,+# session_id)` tracking every beta token observed for that session.+# On every request we union the client value with previously-seen+# tokens and update the seen set — so a beta seen in turn N is+# present in turn N+1 even if the client drops it. LRU bound (default+# 1000 sessions) prevents unbounded growth. Reentrant lock so future+# callers from inside another locked method don't self-deadlock.+#+# Operator opt-in `HEADROOM_BETA_HEADER_STICKY=disabled` short-circuits+# the tracker (returns the client value verbatim). That mode is loud and+# explicit per realignment build constraint #4 — NOT a silent fallback.++_BETA_HEADER_STICKY_ENV = "HEADROOM_BETA_HEADER_STICKY"+BetaHeaderStickyMode = Literal["enabled", "disabled"]+_BETA_HEADER_STICKY_DEFAULT: BetaHeaderStickyMode = "enabled"++_BETA_TRACKER_MAX_SESSIONS_ENV = "HEADROOM_BETA_TRACKER_MAX_SESSIONS"+_BETA_TRACKER_MAX_SESSIONS_DEFAULT = 1000+++def get_beta_header_sticky_mode() -> BetaHeaderStickyMode:+ """Return the active beta-header stickiness mode.++ Read at request time so operators can flip behaviour without a+ restart. Unknown values raise loudly per the no-silent-fallback+ build constraint.+ """+ raw = os.environ.get(_BETA_HEADER_STICKY_ENV, "").strip().lower()+ if not raw:+ return _BETA_HEADER_STICKY_DEFAULT+ if raw in ("enabled", "disabled"):+ return cast(BetaHeaderStickyMode, raw)+ raise ValueError(f"Invalid {_BETA_HEADER_STICKY_ENV}={raw!r}; expected 'enabled' or 'disabled'")+++def get_beta_tracker_max_sessions() -> int:+ """Return the LRU bound for `SessionBetaTracker` (sessions cap)."""+ raw = os.environ.get(_BETA_TRACKER_MAX_SESSIONS_ENV, "").strip()+ if not raw:+ return _BETA_TRACKER_MAX_SESSIONS_DEFAULT+ try:+ value = int(raw)+ except ValueError as exc:+ raise ValueError(+ f"Invalid {_BETA_TRACKER_MAX_SESSIONS_ENV}={raw!r}; expected positive int"+ ) from exc+ if value <= 0:+ raise ValueError(f"Invalid {_BETA_TRACKER_MAX_SESSIONS_ENV}={raw!r}; expected positive int")+ return value+++def _split_beta_tokens(value: str | None) -> list[str]:+ """Split a comma-separated beta-header value into trimmed tokens.++ Empty/whitespace-only entries are dropped. Pure function, no regex.+ """+ if not value:+ return []+ out: list[str] = []+ for raw in value.split(","):+ token = raw.strip()+ if token:+ out.append(token)+ return out+++def _merge_beta_tokens(client_value: str | None, headroom_required: list[str]) -> str:+ """Shared deterministic merge for `anthropic-beta` / `OpenAI-Beta` tokens.++ Rules (per Anthropic guide §6.3 #6 "sticky-on; add but never reorder"):++ * Client tokens come first, in their original order.+ * Headroom-required tokens append in the order given, skipping any+ token already present (case-insensitive).+ * Dedupe is case-insensitive but the FIRST occurrence's casing wins+ (prevents drift when client uses one casing across turns).+ * Returns ``""`` when both inputs are empty.++ Pure function. No regex. No global state.+ """+ seen_lower: set[str] = set()+ out: list[str] = []+ for token in _split_beta_tokens(client_value):+ lower = token.lower()+ if lower in seen_lower:+ continue+ seen_lower.add(lower)+ out.append(token)+ for token in headroom_required:+ if not token:+ continue+ token = token.strip()+ if not token:+ continue+ lower = token.lower()+ if lower in seen_lower:+ continue+ seen_lower.add(lower)+ out.append(token)+ return ",".join(out)+++def merge_anthropic_beta(client_value: str | None, headroom_required: list[str]) -> str:+ """Merge client `anthropic-beta` value with Headroom-required tokens.++ See `_merge_beta_tokens` for full semantics. Order is deterministic:+ client tokens first (in their original order), then headroom tokens+ (in the order passed). No sorting — sticky-on per Anthropic guide+ §6.3 #6 means we add but never reorder. Dedupe is case-insensitive+ but preserves the original casing of the first occurrence.++ Returns ``""`` when both inputs are empty.+ """+ return _merge_beta_tokens(client_value, headroom_required)+++def merge_openai_beta(client_value: str | None, headroom_required: list[str]) -> str:+ """Merge client `OpenAI-Beta` value with Headroom-required tokens.++ Mirror of `merge_anthropic_beta`. Same semantics — the OpenAI header+ follows the same comma-separated convention and the same cache-stable+ rules apply.+ """+ return _merge_beta_tokens(client_value, headroom_required)+++class SessionBetaTracker:+ """Bounded LRU tracker of beta-header tokens observed per (provider, session).++ On every request:+ * Read the client's beta-header value.+ * Union with previously-seen tokens for this session (sticky-on).+ * Update the session's seen set.+ * Return the union (preserving first-seen order).++ Bounded by `max_sessions` (default 1000) via `OrderedDict` LRU+ eviction: hits move-to-end; overflow pops oldest. Reentrant lock so+ future callers from inside another locked method don't self-deadlock+ (mirrors `CompressionCache` pattern).++ The tracker is provider-aware: the same `session_id` for Anthropic+ and OpenAI keeps independent token sets (clients/upstreams differ on+ which tokens are valid).+ """++ def __init__(self, max_sessions: int | None = None) -> None:+ if max_sessions is None:+ max_sessions = get_beta_tracker_max_sessions()+ if max_sessions <= 0:+ raise ValueError("max_sessions must be > 0")+ self._max_sessions: int = max_sessions+ # OrderedDict per `compression_cache.py` LRU pattern. Entries+ # store the per-session ordered token list (preserving first-seen+ # order). RLock allows future callers from inside another locked+ # method to enter without self-deadlock.+ self._lock = threading.RLock()+ self._sessions: OrderedDict[tuple[str, str], list[str]] = OrderedDict()++ @property+ def active_sessions(self) -> int:+ with self._lock:+ return len(self._sessions)++ def _key(self, provider: str, session_id: str) -> tuple[str, str]:+ return (provider, session_id)++ def record_and_get_sticky_betas(+ self,+ provider: str,+ session_id: str,+ client_value: str | None,+ ) -> str:+ """Union client tokens with session-seen tokens; update; return.++ ``provider`` is the upstream identifier (``anthropic`` /+ ``openai``). ``session_id`` is the proxy's per-conversation ID+ (e.g. `SessionTrackerStore.compute_session_id` output for the+ HTTP path; the WS handler's per-connection UUID for the WS+ path — note WS sessions are short-lived and won't accumulate+ cross-turn).++ When `HEADROOM_BETA_HEADER_STICKY=disabled` returns the client+ value verbatim (operator diagnostic opt-in; documented as a+ per-deploy choice, NOT a silent fallback).++ Returns the merged comma-separated value (possibly empty).+ """+ if not provider:+ raise ValueError("provider must be non-empty")+ if not session_id:+ raise ValueError("session_id must be non-empty")++ if get_beta_header_sticky_mode() == "disabled":+ # Diagnostic mode — return the client value verbatim, do not+ # touch tracker state. This is loud (operators read the env+ # var) and per-deploy.+ return (client_value or "").strip()++ client_tokens = _split_beta_tokens(client_value)+ key = self._key(provider, session_id)++ with self._lock:+ previous = self._sessions.get(key)+ if previous is None:+ merged_list: list[str] = []+ seen_lower: set[str] = set()+ else:+ # Move-to-end on hit (LRU touch).+ self._sessions.move_to_end(key)+ merged_list = list(previous)+ seen_lower = {t.lower() for t in merged_list}++ # Append client tokens preserving order; first-seen casing wins.+ for token in client_tokens:+ lower = token.lower()+ if lower in seen_lower:+ continue+ seen_lower.add(lower)+ merged_list.append(token)++ self._sessions[key] = merged_list+ self._sessions.move_to_end(key)++ # Bound: evict oldest until at-or-below cap.+ while len(self._sessions) > self._max_sessions:+ self._sessions.popitem(last=False)++ return ",".join(merged_list)++ def reset(self) -> None:+ """Clear all session state (test helper)."""+ with self._lock:+ self._sessions.clear()+++# Process-wide singleton. Lazily replaced by tests via `reset` /+# `_reset_session_beta_tracker_for_test`. One tracker for both providers+# — the (provider, session_id) key keeps namespaces independent.+_session_beta_tracker_lock = threading.Lock()+_session_beta_tracker: SessionBetaTracker | None = None+++def get_session_beta_tracker() -> SessionBetaTracker:+ """Return the process-wide `SessionBetaTracker` singleton.++ Lazily constructed so the env-var bound (`HEADROOM_BETA_TRACKER_MAX_SESSIONS`)+ is honored at first use. Tests use `_reset_session_beta_tracker_for_test`.+ """+ global _session_beta_tracker+ with _session_beta_tracker_lock:+ if _session_beta_tracker is None:+ _session_beta_tracker = SessionBetaTracker()+ return _session_beta_tracker+++def _reset_session_beta_tracker_for_test() -> None:+ """Clear the process-wide tracker (test-only)."""+ global _session_beta_tracker+ with _session_beta_tracker_lock:+ _session_beta_tracker = None+++def log_beta_header_merge(+ *,+ provider: str,+ session_id: str | None,+ client_betas_count: int,+ sticky_betas_count: int,+ headroom_added: list[str],+ request_id: str | None,+) -> None:+ """Structured log for every cache-affecting beta-header merge.++ `headroom_added` is a list of public, documented beta tokens+ (e.g. ``context-management-2025-06-27``,+ ``responses_websockets=2026-02-06``) — safe to log. We intentionally+ do NOT log the raw client value because beta tokens, while public,+ can carry experiment IDs the user has not opted to share with+ Headroom logs. Emitting counts only makes the decision auditable.+ """+ logger.info(+ "event=beta_header_merge provider=%s session_id=%s "+ "client_betas=%d sticky_betas=%d headroom_added=%s request_id=%s",+ provider,+ session_id or "",+ client_betas_count,+ sticky_betas_count,+ ",".join(headroom_added) if headroom_added else "",+ request_id or "",+ )++async def _read_request_body_bytes(request: Request) -> bytes:"""Read and (if needed) decompress the request body, returning raw UTF-8 bytes.diff --git a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json b/plugins/headroom-agent-hooks/.claude-plugin/plugin.jsonindex 357127d88..67c874fa2 100644--- a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json+++ b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "headroom",- "version": "0.20.11",+ "version": "0.20.12","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.","author": {"name": "Headroom Contributors",diff --git a/plugins/headroom-agent-hooks/.github/plugin/plugin.json b/plugins/headroom-agent-hooks/.github/plugin/plugin.jsonindex a5a432f11..36427b792 100644--- a/plugins/headroom-agent-hooks/.github/plugin/plugin.json+++ b/plugins/headroom-agent-hooks/.github/plugin/plugin.json@@ -1,6 +1,6 @@{"name": "headroom",- "version": "0.20.11",+ "version": "0.20.12","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.","author": {"name": "Headroom Contributors",diff --git a/tests/test_anthropic_beta_session_sticky.py b/tests/test_anthropic_beta_session_sticky.pynew file mode 100644index 000000000..a4c16252f--- /dev/null+++ b/tests/test_anthropic_beta_session_sticky.py@@ -0,0 +1,346 @@+"""Session-sticky `anthropic-beta` tests for PR-A6 (P5-50, preps P0-6).++Two cache-killer patterns the merge + tracker must defeat:++ 1. Mid-session mutation: when memory is enabled the proxy historically+ did an ad-hoc concat of `context-management-2025-06-27` onto the+ client value (anthropic.py:1244-1248). The order varied with the+ client value, breaking byte-stable headers across turns.++ 2. Token drop-out across turns: clients (Claude Code, Codex CLI) MAY+ drop a beta token between turn N and turn N+1 even when the proxy+ mutated turn N to add it. The cache hot zone is positional, so the+ next turn's prefix bytes hash differently and the prefix-cache+ read misses.++The fix:++ * `merge_anthropic_beta`: deterministic, pure, order-preserving.+ * `SessionBetaTracker`: bounded LRU keyed by (provider, session_id),+ unioning client tokens with previously-seen tokens.++Operator opt-in `HEADROOM_BETA_HEADER_STICKY=disabled` short-circuits+the tracker (returns the client value verbatim). That mode is loud and+explicit per realignment build constraint #4 — NOT a silent fallback.+"""++from __future__ import annotations++import threading++import pytest++from headroom.proxy.helpers import (+ SessionBetaTracker,+ _reset_session_beta_tracker_for_test,+ get_beta_header_sticky_mode,+ get_beta_tracker_max_sessions,+ get_session_beta_tracker,+ merge_anthropic_beta,+)++# ---------------------------------------------------------------------------+# Pure helper: `merge_anthropic_beta`+# ---------------------------------------------------------------------------+++def test_merge_helper_pure_function() -> None:+ """Same inputs → same output, no global state."""+ result1 = merge_anthropic_beta("a,b", ["c"])+ result2 = merge_anthropic_beta("a,b", ["c"])+ assert result1 == result2 == "a,b,c"+++def test_merge_helper_empty_inputs_returns_empty_string() -> None:+ assert merge_anthropic_beta(None, []) == ""+ assert merge_anthropic_beta("", []) == ""+ assert merge_anthropic_beta(" ", []) == ""+++def test_merge_helper_only_client() -> None:+ assert merge_anthropic_beta("a,b", []) == "a,b"+++def test_merge_helper_only_headroom() -> None:+ assert merge_anthropic_beta(None, ["a", "b"]) == "a,b"+++def test_merge_helper_preserves_client_order_and_appends_headroom() -> None:+ # Client tokens FIRST in their original order, headroom AFTER in passed order.+ assert (+ merge_anthropic_beta("client-1,client-2", ["headroom-a", "headroom-b"])+ == "client-1,client-2,headroom-a,headroom-b"+ )+++def test_dedupe_case_insensitive_preserves_first_casing() -> None:+ # Client casing wins over headroom casing.+ assert (+ merge_anthropic_beta("Context-Management-2025-06-27", ["context-management-2025-06-27"])+ == "Context-Management-2025-06-27"+ )+ # Within client list: first occurrence's casing wins.+ assert merge_anthropic_beta("Foo,foo", []) == "Foo"+++def test_test_memory_injection_appends_deterministic_order() -> None:+ """Memory injection appends `context-management-2025-06-27` AFTER client tokens."""+ merged = merge_anthropic_beta(+ "interleaved-thinking-2025-05-14",+ ["context-management-2025-06-27"],+ )+ assert merged == "interleaved-thinking-2025-05-14,context-management-2025-06-27"+++def test_merge_helper_skips_empty_tokens() -> None:+ # Whitespace-only entries are dropped.+ assert merge_anthropic_beta("a, ,b", []) == "a,b"+ assert merge_anthropic_beta("a", ["", "b", " "]) == "a,b"+++def test_merge_helper_no_double_inject_when_already_present() -> None:+ # Headroom token already in client value → not re-appended.+ assert (+ merge_anthropic_beta("context-management-2025-06-27", ["context-management-2025-06-27"])+ == "context-management-2025-06-27"+ )+++# ---------------------------------------------------------------------------+# `SessionBetaTracker`+# ---------------------------------------------------------------------------++[email protected](autouse=True)+def _isolate_tracker(monkeypatch: pytest.MonkeyPatch) -> None:+ """Reset the process-wide tracker singleton + env flags between tests."""+ monkeypatch.delenv("HEADROOM_BETA_HEADER_STICKY", raising=False)+ monkeypatch.delenv("HEADROOM_BETA_TRACKER_MAX_SESSIONS", raising=False)+ _reset_session_beta_tracker_for_test()+ yield+ _reset_session_beta_tracker_for_test()+++def test_beta_seen_turn_1_present_in_turn_2_even_if_client_drops() -> None:+ """The core sticky-on guarantee — token observed in turn 1 stays in turn 2."""+ tracker = SessionBetaTracker(max_sessions=10)++ # Turn 1: client sends two tokens.+ out1 = tracker.record_and_get_sticky_betas(+ provider="anthropic",+ session_id="s-1",+ client_value="prompt-caching-2024-07-31,interleaved-thinking-2025-05-14",+ )+ assert out1 == "prompt-caching-2024-07-31,interleaved-thinking-2025-05-14"++ # Turn 2: client drops `interleaved-thinking-2025-05-14` entirely.+ out2 = tracker.record_and_get_sticky_betas(+ provider="anthropic",+ session_id="s-1",+ client_value="prompt-caching-2024-07-31",+ )+ # Sticky-on: token survives.+ assert out2 == "prompt-caching-2024-07-31,interleaved-thinking-2025-05-14"+++def test_client_value_preserved_when_no_injection() -> None:+ """First-turn client value flows through unchanged when no headroom adds."""+ tracker = SessionBetaTracker(max_sessions=10)+ out = tracker.record_and_get_sticky_betas(+ provider="anthropic",+ session_id="s-1",+ client_value="alpha,beta",+ )+ assert out == "alpha,beta"+++def test_empty_client_value_returns_empty_string() -> None:+ tracker = SessionBetaTracker(max_sessions=10)+ assert (+ tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="s-1", client_value=None+ )+ == ""+ )+ assert (+ tracker.record_and_get_sticky_betas(provider="anthropic", session_id="s-1", client_value="")+ == ""+ )+++def test_provider_namespaces_are_independent() -> None:+ """Same session_id under two providers keeps independent token sets."""+ tracker = SessionBetaTracker(max_sessions=10)+ tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="shared", client_value="a-only"+ )+ tracker.record_and_get_sticky_betas(+ provider="openai", session_id="shared", client_value="o-only"+ )+ a_out = tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="shared", client_value=None+ )+ o_out = tracker.record_and_get_sticky_betas(+ provider="openai", session_id="shared", client_value=None+ )+ assert a_out == "a-only"+ assert o_out == "o-only"+++def test_first_seen_casing_preserved_across_turns() -> None:+ tracker = SessionBetaTracker(max_sessions=10)+ tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="s-1", client_value="Context-Management-2025-06-27"+ )+ out = tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="s-1", client_value="context-management-2025-06-27"+ )+ # Original casing wins.+ assert out == "Context-Management-2025-06-27"+++def test_lru_eviction_at_max_sessions() -> None:+ """Bounded LRU pops the oldest session when overflowing."""+ tracker = SessionBetaTracker(max_sessions=2)+ tracker.record_and_get_sticky_betas(provider="anthropic", session_id="s-1", client_value="a")+ tracker.record_and_get_sticky_betas(provider="anthropic", session_id="s-2", client_value="b")+ assert tracker.active_sessions == 2++ # Touch s-1 so s-2 becomes the LRU.+ tracker.record_and_get_sticky_betas(provider="anthropic", session_id="s-1", client_value=None)++ # Add s-3: pops s-2 (oldest by recent access).+ tracker.record_and_get_sticky_betas(provider="anthropic", session_id="s-3", client_value="c")+ assert tracker.active_sessions == 2++ # s-2 was evicted: a fresh request shows no carry-over.+ out = tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="s-2", client_value=None+ )+ assert out == ""+++def test_max_sessions_invalid_raises() -> None:+ with pytest.raises(ValueError):+ SessionBetaTracker(max_sessions=0)+ with pytest.raises(ValueError):+ SessionBetaTracker(max_sessions=-1)+++def test_disabled_mode_passes_through(monkeypatch: pytest.MonkeyPatch) -> None:+ """`HEADROOM_BETA_HEADER_STICKY=disabled` returns client value verbatim."""+ monkeypatch.setenv("HEADROOM_BETA_HEADER_STICKY", "disabled")+ tracker = SessionBetaTracker(max_sessions=10)++ # Turn 1: record a token.+ out1 = tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="s-1", client_value="alpha"+ )+ # Disabled mode: client value flows through verbatim, no tracker update.+ assert out1 == "alpha"++ # Turn 2: client drops the token.+ out2 = tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="s-1", client_value=None+ )+ # Disabled mode: empty client value → empty result; NOT sticky.+ assert out2 == ""+++def test_disabled_mode_invalid_value_raises(monkeypatch: pytest.MonkeyPatch) -> None:+ """Unknown values raise loudly — no silent fallback."""+ monkeypatch.setenv("HEADROOM_BETA_HEADER_STICKY", "yolo")+ with pytest.raises(ValueError, match="HEADROOM_BETA_HEADER_STICKY"):+ get_beta_header_sticky_mode()+++def test_max_sessions_env_var_default() -> None:+ assert get_beta_tracker_max_sessions() == 1000+++def test_max_sessions_env_var_custom(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_BETA_TRACKER_MAX_SESSIONS", "42")+ assert get_beta_tracker_max_sessions() == 42+++def test_max_sessions_env_var_invalid_raises(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_BETA_TRACKER_MAX_SESSIONS", "0")+ with pytest.raises(ValueError):+ get_beta_tracker_max_sessions()+ monkeypatch.setenv("HEADROOM_BETA_TRACKER_MAX_SESSIONS", "-3")+ with pytest.raises(ValueError):+ get_beta_tracker_max_sessions()+ monkeypatch.setenv("HEADROOM_BETA_TRACKER_MAX_SESSIONS", "not-int")+ with pytest.raises(ValueError):+ get_beta_tracker_max_sessions()+++def test_thread_safe_concurrent_access() -> None:+ """Spawn N threads on same session_id; assert no exceptions and final state correct."""+ tracker = SessionBetaTracker(max_sessions=10)+ n_threads = 16+ iterations = 50+ errors: list[BaseException] = []++ def worker(thread_idx: int) -> None:+ try:+ for i in range(iterations):+ tracker.record_and_get_sticky_betas(+ provider="anthropic",+ session_id="shared",+ client_value=f"t{thread_idx}-i{i}",+ )+ except BaseException as e: # noqa: BLE001+ errors.append(e)++ threads = [threading.Thread(target=worker, args=(idx,)) for idx in range(n_threads)]+ for t in threads:+ t.start()+ for t in threads:+ t.join()++ assert errors == []+ # Final state contains every thread's contributed token.+ final = tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="shared", client_value=None+ )+ final_tokens = set(final.split(","))+ expected = {f"t{idx}-i{i}" for idx in range(n_threads) for i in range(iterations)}+ assert expected.issubset(final_tokens)+++def test_blank_provider_or_session_raises() -> None:+ tracker = SessionBetaTracker(max_sessions=10)+ with pytest.raises(ValueError):+ tracker.record_and_get_sticky_betas(provider="", session_id="s", client_value="a")+ with pytest.raises(ValueError):+ tracker.record_and_get_sticky_betas(provider="anthropic", session_id="", client_value="a")+++def test_singleton_get_session_beta_tracker_returns_same_instance() -> None:+ a = get_session_beta_tracker()+ b = get_session_beta_tracker()+ assert a is b+++def test_singleton_reset_replaces_instance() -> None:+ a = get_session_beta_tracker()+ _reset_session_beta_tracker_for_test()+ b = get_session_beta_tracker()+ assert a is not b+++def test_memory_injection_appends_deterministic_order() -> None:+ """End-to-end: client value + memory beta token → deterministic merged value.++ Mirrors the ad-hoc concat that the handler used to do but via the+ new merge helper. Order is client first, headroom token after.+ """+ client = "interleaved-thinking-2025-05-14"+ merged = merge_anthropic_beta(client, ["context-management-2025-06-27"])+ assert merged == "interleaved-thinking-2025-05-14,context-management-2025-06-27"++ # When client already had the token, no double-inject.+ client2 = "context-management-2025-06-27,interleaved-thinking-2025-05-14"+ merged2 = merge_anthropic_beta(client2, ["context-management-2025-06-27"])+ assert merged2 == client2diff --git a/tests/test_openai_beta_session_sticky.py b/tests/test_openai_beta_session_sticky.pynew file mode 100644index 000000000..2cc78a0bb--- /dev/null+++ b/tests/test_openai_beta_session_sticky.py@@ -0,0 +1,226 @@+"""Session-sticky `OpenAI-Beta` tests for PR-A6 (P5-50, preps P0-6).++OpenAI's `OpenAI-Beta` follows the same comma-separated convention as+Anthropic's `anthropic-beta`. The proxy auto-injects+`responses_websockets=2026-02-06` on the WS path when absent+(handlers/openai.py:~1711). PR-A6 routes that injection through+`merge_openai_beta` so the client's tokens are preserved and the+auto-injected token is appended deterministically.++The same `SessionBetaTracker` (provider-aware, keyed by+``(provider, session_id)``) backs both providers — one tracker, two+namespaces.+"""++from __future__ import annotations++import threading++import pytest++from headroom.proxy.helpers import (+ SessionBetaTracker,+ _reset_session_beta_tracker_for_test,+ merge_openai_beta,+)++# ---------------------------------------------------------------------------+# Pure helper: `merge_openai_beta`+# ---------------------------------------------------------------------------+++def test_merge_helper_pure_function() -> None:+ """Same inputs → same output, no global state."""+ a = merge_openai_beta("a,b", ["c"])+ b = merge_openai_beta("a,b", ["c"])+ assert a == b == "a,b,c"+++def test_merge_helper_empty_inputs_returns_empty_string() -> None:+ assert merge_openai_beta(None, []) == ""+ assert merge_openai_beta("", []) == ""+++def test_merge_helper_only_client() -> None:+ assert merge_openai_beta("alpha=1,beta=2", []) == "alpha=1,beta=2"+++def test_merge_helper_only_headroom() -> None:+ assert merge_openai_beta(None, ["responses_websockets=2026-02-06"]) == (+ "responses_websockets=2026-02-06"+ )+++def test_merge_helper_preserves_client_order_appends_headroom() -> None:+ out = merge_openai_beta(+ "alpha=1,beta=2",+ ["responses_websockets=2026-02-06"],+ )+ assert out == "alpha=1,beta=2,responses_websockets=2026-02-06"+++def test_merge_helper_no_double_inject_when_already_present() -> None:+ out = merge_openai_beta(+ "responses_websockets=2026-02-06,alpha=1",+ ["responses_websockets=2026-02-06"],+ )+ assert out == "responses_websockets=2026-02-06,alpha=1"+++def test_dedupe_case_insensitive_preserves_first_casing() -> None:+ # OpenAI tokens are usually `kebab=value` so casing rarely differs in+ # practice, but the helper's contract is provider-agnostic.+ assert (+ merge_openai_beta("Responses_Websockets=2026-02-06", ["responses_websockets=2026-02-06"])+ == "Responses_Websockets=2026-02-06"+ )+++def test_merge_helper_skips_empty_tokens() -> None:+ assert merge_openai_beta("a, ,b", []) == "a,b"+ assert merge_openai_beta("a", ["", "b", " "]) == "a,b"+++def test_test_memory_injection_appends_deterministic_order() -> None:+ """Auto-injected `responses_websockets` appends AFTER client tokens."""+ out = merge_openai_beta("client-token", ["responses_websockets=2026-02-06"])+ assert out == "client-token,responses_websockets=2026-02-06"+++# ---------------------------------------------------------------------------+# `SessionBetaTracker` — provider="openai"+# ---------------------------------------------------------------------------++[email protected](autouse=True)+def _isolate_tracker(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv("HEADROOM_BETA_HEADER_STICKY", raising=False)+ monkeypatch.delenv("HEADROOM_BETA_TRACKER_MAX_SESSIONS", raising=False)+ _reset_session_beta_tracker_for_test()+ yield+ _reset_session_beta_tracker_for_test()+++def test_beta_seen_turn_1_present_in_turn_2_even_if_client_drops() -> None:+ tracker = SessionBetaTracker(max_sessions=10)++ out1 = tracker.record_and_get_sticky_betas(+ provider="openai",+ session_id="s-1",+ client_value="responses_websockets=2026-02-06,extra-beta=1",+ )+ assert out1 == "responses_websockets=2026-02-06,extra-beta=1"++ out2 = tracker.record_and_get_sticky_betas(+ provider="openai",+ session_id="s-1",+ client_value="responses_websockets=2026-02-06",+ )+ assert out2 == "responses_websockets=2026-02-06,extra-beta=1"+++def test_client_value_preserved_when_no_injection() -> None:+ tracker = SessionBetaTracker(max_sessions=10)+ out = tracker.record_and_get_sticky_betas(+ provider="openai", session_id="s-1", client_value="alpha,beta"+ )+ assert out == "alpha,beta"+++def test_lru_eviction_at_max_sessions() -> None:+ tracker = SessionBetaTracker(max_sessions=2)+ tracker.record_and_get_sticky_betas(provider="openai", session_id="s-1", client_value="a")+ tracker.record_and_get_sticky_betas(provider="openai", session_id="s-2", client_value="b")+ tracker.record_and_get_sticky_betas(provider="openai", session_id="s-1", client_value=None)+ tracker.record_and_get_sticky_betas(provider="openai", session_id="s-3", client_value="c")+ # s-2 evicted.+ out = tracker.record_and_get_sticky_betas(+ provider="openai", session_id="s-2", client_value=None+ )+ assert out == ""+++def test_disabled_mode_passes_through(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_BETA_HEADER_STICKY", "disabled")+ tracker = SessionBetaTracker(max_sessions=10)++ out1 = tracker.record_and_get_sticky_betas(+ provider="openai", session_id="s-1", client_value="alpha"+ )+ assert out1 == "alpha"+ out2 = tracker.record_and_get_sticky_betas(+ provider="openai", session_id="s-1", client_value=None+ )+ assert out2 == ""+++def test_thread_safe_concurrent_access() -> None:+ tracker = SessionBetaTracker(max_sessions=10)+ n_threads = 16+ iterations = 50+ errors: list[BaseException] = []++ def worker(idx: int) -> None:+ try:+ for i in range(iterations):+ tracker.record_and_get_sticky_betas(+ provider="openai",+ session_id="shared",+ client_value=f"o-t{idx}-i{i}",+ )+ except BaseException as e: # noqa: BLE001+ errors.append(e)++ threads = [threading.Thread(target=worker, args=(idx,)) for idx in range(n_threads)]+ for t in threads:+ t.start()+ for t in threads:+ t.join()+ assert errors == []+ final = tracker.record_and_get_sticky_betas(+ provider="openai", session_id="shared", client_value=None+ )+ final_tokens = set(final.split(","))+ expected = {f"o-t{idx}-i{i}" for idx in range(n_threads) for i in range(iterations)}+ assert expected.issubset(final_tokens)+++def test_provider_namespaces_are_independent() -> None:+ tracker = SessionBetaTracker(max_sessions=10)+ tracker.record_and_get_sticky_betas(+ provider="openai", session_id="shared", client_value="o-token"+ )+ tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="shared", client_value="a-token"+ )+ out_openai = tracker.record_and_get_sticky_betas(+ provider="openai", session_id="shared", client_value=None+ )+ out_anth = tracker.record_and_get_sticky_betas(+ provider="anthropic", session_id="shared", client_value=None+ )+ assert out_openai == "o-token"+ assert out_anth == "a-token"+++def test_ws_required_token_appended_deterministically() -> None:+ """Mirrors the WS handler logic — record client value, then merge required."""+ tracker = SessionBetaTracker(max_sessions=10)+ sticky = tracker.record_and_get_sticky_betas(+ provider="openai",+ session_id="ws-1",+ client_value="custom-beta=1",+ )+ merged = merge_openai_beta(sticky, ["responses_websockets=2026-02-06"])+ assert merged == "custom-beta=1,responses_websockets=2026-02-06"+++def test_ws_required_token_no_double_when_client_already_has_it() -> None:+ tracker = SessionBetaTracker(max_sessions=10)+ sticky = tracker.record_and_get_sticky_betas(+ provider="openai",+ session_id="ws-2",+ client_value="responses_websockets=2026-02-06",+ )+ merged = merge_openai_beta(sticky, ["responses_websockets=2026-02-06"])+ assert merged == "responses_websockets=2026-02-06"diff --git a/tests/test_openai_codex_routing.py b/tests/test_openai_codex_routing.pyindex c56a2f9ae..2a75d3dec 100644--- a/tests/test_openai_codex_routing.py+++ b/tests/test_openai_codex_routing.py@@ -141,6 +141,13 @@ class _DummyOpenAIHandler(OpenAIHandlerMixin):self.anthropic_backend = Noneself.cost_tracker = Noneself.memory_handler = None+ # PR-A6 wires session-sticky `OpenAI-Beta` merging into the+ # responses HTTP handler — it reads `compute_session_id` to key+ # the SessionBetaTracker. The routing tests don't exercise the+ # tracker semantics themselves, so a fixed-id stub is enough.+ self.session_tracker_store = SimpleNamespace(+ compute_session_id=lambda *a, **k: "sess-openai-1",+ )self.captured_request: tuple[str, str, dict, dict] | None = Noneself.captured_stream_request: tuple[str, dict, dict] | None = None