From c07da992dde04224d89a0a9c066a30786ccdfbd6 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Wed, 5 Aug 2026 17:01:32 -0700 Subject: [PATCH 001/138] Per-request backend selection for routing extensions (#2809) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## The gap Headroom picks its egress backend **once**, at startup: `create_proxy_backend` returns a single `Backend` (or `None` for the direct Anthropic path) and every request goes through it. That is the right shape for *"run this whole proxy against Bedrock instead of Anthropic"* and the wrong shape for *"this request is cheaper on a different provider than the last one."* `ModelRouter` already lets an extension change `body["model"]` per request — but only within the protocol the request arrived in, because a model id alone cannot move a request to another provider. So an extension can currently **decide** something Headroom has no way to **carry out**. This adds the missing half. ## The seam An extension publishes a decision on the request state: ```python request.state.headroom_route = SimpleNamespace( model="moonshot/kimi-k2", # required provider="moonshot", # optional; inferred from the model id if absent reason="cheaper at this prefix length", ) ``` Headroom resolves a `LiteLLMBackend` for that provider — which is where translation already lives — and serves **that one request** from it. Nothing in core names any particular extension; the field is duck-typed, so an extension does not import Headroom to talk to Headroom. ## Absent means unchanged This is the property the tests are built around, and the reason this should be safe to merge. With nothing published, every path is what it was before. Advice that is **absent, malformed, names an unknown provider, names a native provider, or fails to build** all resolve to `self.anthropic_backend` — including when that is `None`, which is the direct-API path and must survive. A routing preference can never take traffic down. ## Coverage | path | | |---|---| | `/v1/messages` | non-streaming + streaming | | `/v1/chat/completions` | non-streaming + streaming | | Responses API | untouched — does not use the backend abstraction | Streaming is the one that matters. The resolver rewrites `body["model"]`, so had `_stream_response_bedrock` kept reading `self.anthropic_backend`, every streamed routed request would have sent a foreign model id to Anthropic. Both streaming helpers now take an optional `backend`, defaulting to the configured one. ## Details worth review - **Validate the provider name before building.** `LiteLLMBackend` accepts *any* provider string — the registry falls through to a generic pass-through config — so a typo silently builds a backend that only fails later, at request time, with an error pointing nowhere near the typo. `_known_provider()` checks against `litellm.provider_list` first. - **Cache per provider, and cache the failures too**, or a broken provider name costs a construction attempt on every request. (Bedrock construction calls out to AWS to enumerate inference profiles — it is not free.) - **`backend_owns_translation` now asks the per-request backend.** It decides whether Headroom or the backend owns the `max_tokens` / `max_completion_tokens` spelling; asking `self.anthropic_backend` would answer "Headroom does" for a request about to be served by a translating backend that does. - **`_route_resolver` lives in `route_advice.py`, not on a handler mixin.** Two mixins need it, and reaching across sibling mixins only works by accident of how `HeadroomProxy` composes them. ## Tests `tests/test_route_advice.py` — 20 tests, most of them asserting the absent-means-unchanged property from a different angle. Local runs: 20/20 on the new file; **1102 passed, 1 failed** on `-k "openai or chat_completions or ccr"`, and **414 passed, 0 failed** on `-k "stream or bedrock or route_advice"`. The single failure is `test_realignment_live_multi_turn::test_ccr_marker_round_trip_live`, which fails identically on this branch's merge-base — verified by checking out `59314cff~1` and re-running it. Note for anyone reproducing: `pytest-asyncio` is a declared dev dependency but was missing from my venv, which made every `async def test_` in the repo fail. Worth checking before diagnosing a large failure count. ## Docs `docs/content/docs/pipeline-extensions.mdx` gains a section on the contract, next to the existing `x-headroom-base-url` one. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) --- docs/content/docs/pipeline-extensions.mdx | 23 ++ headroom/proxy/handlers/anthropic.py | 21 +- headroom/proxy/handlers/openai.py | 34 ++- headroom/proxy/handlers/streaming.py | 27 +- headroom/proxy/route_advice.py | 206 +++++++++++++++ tests/test_route_advice.py | 289 ++++++++++++++++++++++ 6 files changed, 572 insertions(+), 28 deletions(-) create mode 100644 headroom/proxy/route_advice.py create mode 100644 tests/test_route_advice.py diff --git a/docs/content/docs/pipeline-extensions.mdx b/docs/content/docs/pipeline-extensions.mdx index c98455e59..a525404ee 100644 --- a/docs/content/docs/pipeline-extensions.mdx +++ b/docs/content/docs/pipeline-extensions.mdx @@ -77,3 +77,26 @@ curl http://localhost:8787/v1/chat/completions \ ``` Internal `x-headroom-*` headers (including this one) are stripped before the request is forwarded upstream by default — see `HEADROOM_STRIP_INTERNAL_HEADERS` in [Configuration](/docs/configuration). + +## Per-request model routing with `request.state.headroom_route` + +`x-headroom-base-url` is client-driven and points at one OpenAI-compatible base. When the choice of model belongs to an extension instead of the caller — a router that picks a cheaper model per turn, say — publish it on the request state and Headroom serves that one request from a backend that speaks the target provider: + +```python +# middleware or an extension holding the request +request.state.headroom_route = SimpleNamespace( + model="moonshot/kimi-k2", # required + provider="moonshot", # optional; inferred from the model id if absent + reason="cheaper at this prefix length", +) +``` + +The contract, in `headroom/proxy/route_advice.py`: + +- **Absent means unchanged.** No advice — or advice that is malformed, names an unknown provider, or fails to build a backend — and the request takes exactly the path it took before. A routing preference can never take traffic down. +- **Duck-typed**, so an extension does not import Headroom to publish one. +- A **native** provider (`anthropic`) needs no backend switch — rewrite `body["model"]` yourself. A foreign one is translated by a `LiteLLMBackend` built for it, and Headroom writes the model id. +- Backends are **built once per provider** and cached; a provider that fails to build is not retried per request. +- Honored on `/v1/messages` and `/v1/chat/completions`, streaming and non-streaming alike. (Not the Responses API, which does not use the backend abstraction.) + +`routemegood` is the reference consumer of this seam: it decides, Headroom routes. diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index eaf399937..ede5e72d7 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -2644,7 +2644,17 @@ class AnthropicHandlerMixin: headers["anthropic-beta"] = _client_beta_value # Forward request - use Bedrock backend if configured, otherwise direct API - if self.anthropic_backend is not None: + # + # An extension may have published a per-request routing decision on + # `request.state.headroom_route` (see proxy/route_advice.py). When + # it names a provider we do not already speak, serve this ONE + # request from a translating backend for it. Absent, unresolvable, + # or same-protocol -> `self.anthropic_backend`, i.e. exactly the + # behaviour this line had before. + from headroom.proxy.route_advice import resolver_for + + request_backend = resolver_for(self).for_request(request, body=body) + if request_backend is not None: # Route through Bedrock backend try: if stream: @@ -2675,12 +2685,11 @@ class AnthropicHandlerMixin: original_messages=original_client_messages, prefix_tracker=prefix_tracker, optimized_messages=optimized_messages, + backend=request_backend, ) else: async with stage_timer.measure("upstream_connect"): - backend_response = await self.anthropic_backend.send_message( - body, headers - ) + backend_response = await request_backend.send_message(body, headers) self.pipeline_extensions.emit( PipelineStage.POST_SEND, operation="proxy.request", @@ -2732,9 +2741,7 @@ class AnthropicHandlerMixin: usage = backend_response.body.get("usage", {}) output_tokens = usage.get("output_tokens", 0) - _backend_name = ( - self.anthropic_backend.name if self.anthropic_backend else "anthropic" - ) + _backend_name = request_backend.name if request_backend else "anthropic" # Eligible-only denominator for the active # compression ratio: tokens in the live zone we # actually attempted to compress. Frozen prefix diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py index dd12a2290..9ee4c260b 100644 --- a/headroom/proxy/handlers/openai.py +++ b/headroom/proxy/handlers/openai.py @@ -3702,8 +3702,15 @@ class OpenAIHandlerMixin: # translate it here — the proxy already owns the outbound body — and # those requests work unchanged. No-op when the caller already set # `max_completion_tokens`. + # Resolved without `body=` so nothing is rewritten yet -- we only need + # to know WHICH backend will serve this request, because a translating + # one owns the max_tokens spelling. Cached, so the dispatch-site call + # below is a dict lookup. + from headroom.proxy.route_advice import resolver_for + _normalize_openai_max_tokens( - body, backend_owns_translation=self.anthropic_backend is not None + body, + backend_owns_translation=resolver_for(self).for_request(request) is not None, ) # Output shaping (opt-in via HEADROOM_OUTPUT_SHAPER): verbosity steering @@ -3763,8 +3770,12 @@ class OpenAIHandlerMixin: f"{_shape_result.labels}" ) - # Route through LiteLLM/any-llm backend if configured - if self.anthropic_backend is not None: + # Route through LiteLLM/any-llm backend if configured -- or through a + # per-request one an extension asked for (see proxy/route_advice.py). + # No advice resolves to `self.anthropic_backend`, so this is the same + # condition it has always been. + request_backend = resolver_for(self).for_request(request, body=body) + if request_backend is not None: try: if stream: self.pipeline_extensions.emit( @@ -3794,12 +3805,11 @@ class OpenAIHandlerMixin: waste_signals=waste_signals_dict, prefix_tracker=openai_prefix_tracker, optimized_messages=optimized_messages, + backend=request_backend, ) else: # Non-streaming: use send_openai_message() → JSON - backend_response = await self.anthropic_backend.send_openai_message( - body, headers - ) + backend_response = await request_backend.send_openai_message(body, headers) self.pipeline_extensions.emit( PipelineStage.POST_SEND, operation="proxy.request", @@ -3858,7 +3868,7 @@ class OpenAIHandlerMixin: ): logger.info( f"[{request_id}] CCR: Detected retrieval tool call " - f"on backend path, handling via {self.anthropic_backend.name}" + f"on backend path, handling via {request_backend.name}" ) # Continuation closure — delegates transport to @@ -3885,13 +3895,13 @@ class OpenAIHandlerMixin: ) } - assert self.anthropic_backend is not None + assert request_backend is not None logger.info( f"[{request_id}] CCR: Issuing continuation via " - f"{self.anthropic_backend.name} backend " + f"{request_backend.name} backend " f"({len(msgs)} messages)" ) - cont_resp = await self.anthropic_backend.send_openai_message( + cont_resp = await request_backend.send_openai_message( continuation_body, continuation_headers ) return cont_resp.body @@ -4017,7 +4027,7 @@ class OpenAIHandlerMixin: await self._record_request_outcome( RequestOutcome( request_id=request_id, - provider=self.anthropic_backend.name, + provider=request_backend.name, model=model, original_tokens=original_tokens, # Local count, same tokenizer as original_tokens, so @@ -4049,7 +4059,7 @@ class OpenAIHandlerMixin: if tokens_saved > 0: logger.info( f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} " - f"(saved {tokens_saved:,} tokens) via {self.anthropic_backend.name}" + f"(saved {tokens_saved:,} tokens) via {request_backend.name}" ) return JSONResponse( diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py index fd232dc52..e265ba80c 100644 --- a/headroom/proxy/handlers/streaming.py +++ b/headroom/proxy/handlers/streaming.py @@ -1679,6 +1679,7 @@ class StreamingMixin: original_messages: list[dict] | None = None, prefix_tracker: Any | None = None, optimized_messages: list[dict] | None = None, + backend: Any | None = None, ) -> StreamingResponse: """Stream response from Bedrock backend with metrics tracking. @@ -1697,6 +1698,11 @@ class StreamingMixin: from headroom.proxy.outcome import RequestOutcome + # ``backend`` lets the caller serve this one request from somewhere + # other than the configured backend (see proxy/route_advice.py). None + # means "the configured one", i.e. what this method always did. + backend = backend if backend is not None else self.anthropic_backend + client = classify_client(headers) start_time = time.time() @@ -1721,7 +1727,7 @@ class StreamingMixin: async def generate(): try: - assert self.anthropic_backend is not None + assert backend is not None # Emit a synthetic ping before the first message_start so that # downstream clients (e.g. Claude Code) arm their mid-turn @@ -1731,7 +1737,7 @@ class StreamingMixin: # (issue #902). yield b"event: ping\ndata: {}\n\n" - async for event in self.anthropic_backend.stream_message(body, headers): + async for event in backend.stream_message(body, headers): # Record TTFB on first event if stream_state["ttfb_ms"] is None: stream_state["ttfb_ms"] = (time.time() - start_time) * 1000 @@ -1807,9 +1813,7 @@ class StreamingMixin: finally: total_latency = (time.time() - start_time) * 1000 - _backend_name = ( - self.anthropic_backend.name if self.anthropic_backend else "anthropic" - ) + _backend_name = backend.name if backend else "anthropic" # Update prefix cache tracker for the next turn — mirrors # _finalize_stream_response (direct-API streaming path) @@ -1908,6 +1912,7 @@ class StreamingMixin: waste_signals: dict[str, int] | None = None, prefix_tracker: Any | None = None, optimized_messages: list[dict] | None = None, + backend: Any | None = None, ) -> StreamingResponse: """Stream OpenAI chat completion response from backend. @@ -1942,7 +1947,11 @@ class StreamingMixin: from headroom.proxy.handlers.openai import _infer_openai_cache_write_tokens from headroom.proxy.outcome import RequestOutcome - assert self.anthropic_backend is not None + # ``backend`` lets the caller serve this one request from somewhere + # other than the configured backend (see proxy/route_advice.py). None + # means "the configured one", i.e. what this method always did. + backend = backend if backend is not None else self.anthropic_backend + assert backend is not None client = classify_client(headers) async def generate(): @@ -1972,7 +1981,7 @@ class StreamingMixin: stream_state[key] = usage[key] try: - async for sse_chunk in self.anthropic_backend.stream_openai_message(body, headers): + async for sse_chunk in backend.stream_openai_message(body, headers): chunk_bytes = sse_chunk.encode() if isinstance(sse_chunk, str) else sse_chunk stream_state["sse_buffer"].extend(chunk_bytes) full_sse_bytes.extend(chunk_bytes) @@ -2074,7 +2083,7 @@ class StreamingMixin: # instead of collapsing the dashboard headline to 0%. outcome = RequestOutcome.from_stream( body=body, - provider=self.anthropic_backend.name, + provider=backend.name, model=model, request_id=request_id, original_tokens=original_tokens, @@ -2099,7 +2108,7 @@ class StreamingMixin: if tokens_saved > 0: logger.info( f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} " - f"(saved {tokens_saved:,} tokens) via {self.anthropic_backend.name} [stream]" + f"(saved {tokens_saved:,} tokens) via {backend.name} [stream]" ) return StreamingResponse( diff --git a/headroom/proxy/route_advice.py b/headroom/proxy/route_advice.py new file mode 100644 index 000000000..84ad31e21 --- /dev/null +++ b/headroom/proxy/route_advice.py @@ -0,0 +1,206 @@ +"""Per-request backend selection, published by an extension. + +WHY THIS EXISTS + Headroom picks its egress backend ONCE, at startup: `create_proxy_backend` + returns a single `Backend` (or None for the direct Anthropic path) and + every request goes through it. That is right for "run this whole proxy + against Bedrock instead of Anthropic", and it is the wrong shape for "this + request is cheaper on a different provider than the last one". + + Meanwhile `ModelRouter` already lets an extension change `body["model"]` + per request -- but only within whatever protocol the request arrived in, + because a model id alone cannot move a request to another provider. + + So a router extension can currently decide something Headroom has no way to + carry out. This module is the missing half: a routing decision that names a + PROVIDER as well as a model, and a per-request backend to serve it. + +THE CONTRACT, AND WHY IT IS VENDOR-NEUTRAL + An extension sets `request.state.headroom_route` to a `RouteAdvice`. + Headroom reads it, resolves a backend for `advice.provider`, and dispatches + there. Nothing in core names any particular extension. + +ABSENT MEANS UNCHANGED + This is the property that matters most. With no extension installed, no + extension setting the field, an unresolvable provider, or a backend that + fails to construct, `backend_for()` returns exactly what + `self.anthropic_backend` would have been -- including None, which keeps the + direct-API path. Nothing about the default deployment moves. +""" + +from __future__ import annotations + +import logging +from dataclasses import dataclass +from typing import Any + +log = logging.getLogger(__name__) + +STATE_ATTR = "headroom_route" + +# Providers that speak the Anthropic Messages API natively, i.e. the shape the +# proxy already holds. Everything else needs a translating backend. +_NATIVE = ("anthropic",) + + +@dataclass(frozen=True) +class RouteAdvice: + """A routing decision an extension wants Headroom to carry out. + + Only `model` and `provider` are required; the rest is explanatory and is + logged rather than acted on, so an extension can be as terse as it likes. + """ + + model: str + provider: str = "" + reason: str = "" + + def __post_init__(self) -> None: + if not self.model: + raise ValueError("RouteAdvice needs a model") + + +def advice_from(request: Any) -> RouteAdvice | None: + """The advice an extension published, if any. Never raises. + + Duck-typed on purpose: an extension should not have to import Headroom to + talk to Headroom. Anything carrying `.model` (and optionally `.provider`) + works, which also keeps extensions from breaking when this dataclass gains + a field. + """ + obj = getattr(getattr(request, "state", None), STATE_ATTR, None) + if obj is None: + return None + model = getattr(obj, "model", None) + if not isinstance(model, str) or not model: + return None + provider = getattr(obj, "provider", "") or "" + return RouteAdvice( + model=model, + provider=provider if isinstance(provider, str) else "", + reason=str(getattr(obj, "reason", "") or "")[:400], + ) + + +class BackendResolver: + """Lazily builds and caches one translating backend per provider. + + Construction is not free -- the Bedrock path calls out to AWS to enumerate + inference profiles -- so backends are built on first use for a provider and + kept. A provider that fails to construct is remembered as a failure and not + retried on every request; the request falls back to the default backend + rather than erroring, because a routing preference must never be able to + take traffic down. + """ + + def __init__(self, default: Any = None) -> None: + self._default = default + self._cache: dict[str, Any] = {} + self._failed: set[str] = set() + + @property + def default(self) -> Any: + return self._default + + def for_request(self, request: Any, *, body: dict | None = None) -> Any: + """The backend to serve this request. Falls back to the default.""" + advice = advice_from(request) + if advice is None: + return self._default + + provider = advice.provider or _provider_of(advice.model) + if not provider or provider in _NATIVE: + # Same protocol the proxy already speaks -- a `body["model"]` + # rewrite is enough and the extension has already done it. Nothing + # to switch. + return self._default + if provider in self._failed: + return self._default + + backend = self._cache.get(provider) + if backend is None: + try: + backend = self._build(provider) + except Exception as exc: # noqa: BLE001 - see the class docstring + log.warning("route advice: building %r raised (%s)", provider, exc) + backend = None + if backend is None: + self._failed.add(provider) + return self._default + self._cache[provider] = backend + + if body is not None: + # The extension chose the model; make sure the body agrees, since + # it could not safely write a foreign model id itself. Log here + # too -- a caller asking without a body is only checking WHICH + # backend will serve the request, and would log the same decision + # a second time. + body["model"] = advice.model + log.info( + "route advice: %s via %s (%s)", + advice.model, + provider, + advice.reason or "no reason given", + ) + return backend + + def _build(self, provider: str) -> Any: + # Validate the name FIRST. `LiteLLMBackend` accepts an unknown provider + # happily -- the registry falls through to a generic pass-through + # config -- so a typo builds a backend that only fails later, at + # request time, with an error that points nowhere near the typo. + if not _known_provider(provider): + log.warning("route advice: %r is not a litellm provider; ignoring", provider) + return None + try: + from headroom.backends.litellm import LiteLLMBackend + + return LiteLLMBackend(provider=provider) + except Exception as exc: # noqa: BLE001 - never fail a request for this + log.warning( + "route advice: cannot build a backend for %r (%s); " + "falling back to the configured backend", + provider, + exc, + ) + return None + + +def resolver_for(handler: Any) -> BackendResolver: + """The handler's resolver, built once and reused. + + Lives here rather than on a handler mixin so every protocol handler can + reach it without depending on a sibling mixin. Rebuilt if + `anthropic_backend` is reassigned (tests do this), so the resolver can + never serve a stale default. + """ + default = getattr(handler, "anthropic_backend", None) + cached = getattr(handler, "_route_resolver_cache", None) + if cached is None or cached.default is not default: + cached = BackendResolver(default) + handler._route_resolver_cache = cached + return cached + + +def _known_provider(provider: str) -> bool: + """Is this a provider litellm actually knows about?""" + try: + import litellm + + names = {getattr(p, "value", None) or str(p) for p in getattr(litellm, "provider_list", [])} + return provider in names + except Exception: # noqa: BLE001 + return False + + +def _provider_of(model: str) -> str: + """Provider from a `provider/model` spec, else from litellm's table.""" + if "/" in model: + return model.split("/", 1)[0] + try: + import litellm + + entry = litellm.model_cost.get(model) or {} + return str(entry.get("litellm_provider") or "") + except Exception: # noqa: BLE001 + return "" diff --git a/tests/test_route_advice.py b/tests/test_route_advice.py new file mode 100644 index 000000000..9e84bee9c --- /dev/null +++ b/tests/test_route_advice.py @@ -0,0 +1,289 @@ +"""Per-request backend selection published by an extension. + +The property under test throughout is the one that makes this safe to merge: +with nothing published, every path is exactly what it was before. +""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace + +import pytest + +from headroom.proxy.route_advice import ( + BackendResolver, + RouteAdvice, + advice_from, +) + + +class _Req: + def __init__(self, **state): + self.state = SimpleNamespace(**state) + + +DEFAULT = object() # stands in for the configured backend + + +# --- reading what an extension published ------------------------------------ + + +def test_no_extension_means_no_advice(): + assert advice_from(_Req()) is None + assert advice_from(object()) is None # no .state at all + assert advice_from(None) is None + + +def test_advice_is_duck_typed_so_extensions_need_not_import_us(): + a = advice_from( + _Req( + headroom_route=SimpleNamespace( + model="moonshot/kimi-k2", provider="moonshot", reason="cheaper" + ) + ) + ) + assert a == RouteAdvice("moonshot/kimi-k2", "moonshot", "cheaper") + + +def test_an_extension_may_omit_everything_but_the_model(): + a = advice_from(_Req(headroom_route=SimpleNamespace(model="gpt-5-mini"))) + assert a.model == "gpt-5-mini" and a.provider == "" + + +def test_malformed_advice_is_ignored_rather_than_raised(): + for bad in ( + SimpleNamespace(), + SimpleNamespace(model=""), + SimpleNamespace(model=123), + "not an object", + ): + assert advice_from(_Req(headroom_route=bad)) is None + + +def test_advice_needs_a_model(): + with pytest.raises(ValueError): + RouteAdvice("") + + +# --- absent means unchanged, which is the whole safety argument ------------- + + +def test_no_advice_returns_the_configured_backend(): + r = BackendResolver(DEFAULT) + assert r.for_request(_Req()) is DEFAULT + + +def test_no_advice_and_no_configured_backend_stays_none(): + """None is not "no backend", it is the direct-API path. It must survive.""" + assert BackendResolver(None).for_request(_Req()) is None + + +def test_a_native_provider_does_not_switch_backends(): + """Anthropic is the shape the proxy already holds, so a model rewrite is + enough and the extension has already done it.""" + r = BackendResolver(DEFAULT) + req = _Req(headroom_route=SimpleNamespace(model="claude-haiku-4-5", provider="anthropic")) + assert r.for_request(req) is DEFAULT + + +def test_a_bare_anthropic_model_resolves_its_provider_and_stays_put(): + r = BackendResolver(DEFAULT) + req = _Req(headroom_route=SimpleNamespace(model="claude-haiku-4-5")) + assert r.for_request(req) is DEFAULT + + +# --- switching, and refusing to switch -------------------------------------- + + +def test_a_foreign_provider_gets_its_own_backend(monkeypatch): + built = [] + + class FakeBackend: + def __init__(self, provider): + built.append(provider) + self.provider = provider + + monkeypatch.setattr(BackendResolver, "_build", lambda self, p: FakeBackend(p)) + r = BackendResolver(DEFAULT) + body = {"model": "claude-opus-5"} + req = _Req(headroom_route=SimpleNamespace(model="moonshot/kimi-k2", provider="moonshot")) + got = r.for_request(req, body=body) + assert isinstance(got, FakeBackend) and got.provider == "moonshot" + # The extension could not safely write a foreign model id; we do it. + assert body["model"] == "moonshot/kimi-k2" + + +def test_backends_are_built_once_per_provider(monkeypatch): + built = [] + monkeypatch.setattr(BackendResolver, "_build", lambda self, p: built.append(p) or object()) + r = BackendResolver(DEFAULT) + req = _Req(headroom_route=SimpleNamespace(model="x", provider="moonshot")) + for _ in range(5): + r.for_request(req) + assert built == ["moonshot"], "construction is expensive; cache it" + + +def test_a_backend_that_will_not_build_falls_back_and_stops_retrying(monkeypatch): + calls = [] + monkeypatch.setattr(BackendResolver, "_build", lambda self, p: calls.append(p) or None) + r = BackendResolver(DEFAULT) + req = _Req(headroom_route=SimpleNamespace(model="x", provider="nope")) + for _ in range(5): + assert r.for_request(req) is DEFAULT + assert calls == ["nope"], "a broken provider must not be retried per request" + + +def test_a_routing_preference_can_never_take_traffic_down(monkeypatch): + """Missing credentials, missing optional dependency -- whatever the reason, + the request still has to be served.""" + + def boom(self, provider): + raise RuntimeError("no credentials") + + monkeypatch.setattr(BackendResolver, "_build", boom) + r = BackendResolver(DEFAULT) + req = _Req(headroom_route=SimpleNamespace(model="x", provider="moonshot")) + assert r.for_request(req) is DEFAULT + + +def test_an_unknown_provider_is_rejected_at_resolve_time(): + """LiteLLMBackend accepts ANY provider string -- the registry falls through + to a generic pass-through -- so a typo silently builds a backend that only + fails later, at request time, with an error pointing nowhere near the typo. + Validate the name up front instead.""" + r = BackendResolver(DEFAULT) + assert r._build("definitely-not-a-provider-name") is None + req = _Req(headroom_route=SimpleNamespace(model="x", provider="definitely-not-a-provider-name")) + assert r.for_request(req) is DEFAULT + + +def test_a_real_provider_name_is_accepted(): + assert BackendResolver(DEFAULT)._build("moonshot") is not None + + +# --- streaming, which is the path agents actually take ---------------------- + + +class _Backend: + """Records that it, and not some other backend, served the request.""" + + def __init__(self, name): + self.name = name + self.served = False + + async def stream_message(self, body, headers): + self.served = True + return + yield # pragma: no cover -- makes this an async generator + + async def stream_openai_message(self, body, headers): + self.served = True + return + yield # pragma: no cover + + +async def _drive(handler, **kw): + from headroom.proxy.handlers.streaming import StreamingMixin + + resp = await StreamingMixin._stream_response_bedrock( + handler, + {"messages": []}, + {}, + "anthropic", + "m", + "rid", + 0, + 0, + 0, + [], + {}, + 0.0, + **kw, + ) + async for _ in resp.body_iterator: + pass + + +class _Config: + """Every proxy flag off. Named individually the list would rot; the test + is about which backend served the request, not about config.""" + + def __getattr__(self, name): + return False + + +def _handler(default): + return SimpleNamespace( + anthropic_backend=default, + config=_Config(), + _record_request_outcome=lambda outcome: _noop(), + ) + + +async def _noop(): + return None + + +def test_streaming_honours_the_routed_backend(): + """The non-streaming branch was the easy half. body["model"] has already + been rewritten to a foreign id by the time we get here, so streaming to + the configured backend would send e.g. moonshot/kimi-k2 to Anthropic.""" + configured, routed = _Backend("anthropic"), _Backend("moonshot") + asyncio.run(_drive(_handler(configured), backend=routed)) + assert routed.served and not configured.served + + +def test_streaming_without_a_route_uses_the_configured_backend(): + configured = _Backend("anthropic") + asyncio.run(_drive(_handler(configured))) + assert configured.served + + +async def _drive_openai(handler, **kw): + from headroom.proxy.handlers.streaming import StreamingMixin + + resp = await StreamingMixin._stream_openai_via_backend( + handler, + {"messages": []}, + {}, + "m", + "rid", + 0.0, + 0, + 0, + 0, + [], + {}, + 0.0, + **kw, + ) + async for _ in resp.body_iterator: + pass + + +def test_openai_streaming_honours_the_routed_backend(): + """opencode and pi can speak either protocol, so the OpenAI chat path + needs the same treatment as the Anthropic one.""" + configured, routed = _Backend("openai"), _Backend("moonshot") + asyncio.run(_drive_openai(_handler(configured), backend=routed)) + assert routed.served and not configured.served + + +def test_openai_streaming_without_a_route_uses_the_configured_backend(): + configured = _Backend("openai") + asyncio.run(_drive_openai(_handler(configured))) + assert configured.served + + +def test_the_resolver_follows_a_reassigned_default(): + class H: + anthropic_backend = None + + h = H() + from headroom.proxy.route_advice import BackendResolver as BR + + first = BR(h.anthropic_backend) + assert first.default is None + h.anthropic_backend = DEFAULT + assert BR(h.anthropic_backend).default is DEFAULT From 2954e37048f8dcffe16e1c37b8f71afb0094a0a2 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Wed, 5 Aug 2026 17:01:57 -0700 Subject: [PATCH 002/138] fix(beacon): split session failures by status code (#2815) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description The session beacon reports `failures` as a single count, incremented whenever a turn ends `>= 500` (`headroom/telemetry/session.py`). Across the current corpus that reads **3,969 failures on 595,445 turns (0.67%)** — and the number cannot answer the only question anyone asks of it: an Anthropic `529` is the provider shedding load and there is nothing to fix; a `500` is usually ours. Today the two are indistinguishable, so diagnosis falls back to inference from time-of-day curves and per-install concentration. This counts the status alongside the total. ```json "failures": 3, "failure_statuses": {"529": 2, "500": 1} ``` Motivating investigation on the live corpus (0.67% of turns, 6% of sessions, 63% of all failures from 48 installs, a 2.5% plateau at 08–11 UTC decaying to 0.03% during the fleet's busiest hour) strongly suggests provider-side 529 after retry exhaustion — but "strongly suggests" is exactly the gap this field closes. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - **`headroom/telemetry/session.py`** — `_Session.failure_statuses`, incremented next to `failures` in `record_outcome`. Keys are the bare status string for the 5xx range, `"other"` beyond it. Emitted as a sibling of `failures` in `payload()`. - **`deploy/beacon/worker.js`** — `failure_statuses` added to `ALLOWED_KEYS`. Without this the ingest allowlist silently drops it. - **`deploy/beacon/sample-event.json`** — sample carries the new key in OTLP `kvlistValue` form. ### Why no slug bounding `skips` runs values through `_safe_slug` because they arrive as free strings. A status code is an `int` the proxy itself produced; the `500 <= status < 600` check is what keeps a garbage value from inventing map keys. Nothing here is user-derived, so the field stays content-free. ### Why `schema_version` stays 1 Additive, matching the precedent set by #2796, which added `tokens.tool_saved` and the two `all_layers_*` rates without a bump. Bumping signals a break to consumers when nothing about older rows becomes invalid. ## Testing - [x] Unit tests pass (`pytest`) — the module's own self-check, extended - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) — see note - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ python -m headroom.telemetry.session ok $ ruff check headroom/telemetry/session.py All checks passed! $ ruff format --check headroom/telemetry/session.py 1 file already formatted $ mypy --python-version 3.12 headroom/telemetry/session.py Success: no issues found in 1 source file # --python-version 3.12 only to skip a pre-existing numpy-stub syntax error the # repo's python_version = "3.10" triggers locally; unrelated to this diff. $ node --check deploy/beacon/worker.js # ok $ python -c "import json; json.load(open('deploy/beacon/sample-event.json'))" # parses ``` The self-check in `headroom/telemetry/session.py` now records two 529s and one 500 and asserts both the total and the split: ```python assert emitted[-1]["failures"] == 3 assert emitted[-1]["failure_statuses"] == {"529": 2, "500": 1} ``` plus `assert event["failure_statuses"] == {}` on the clean-session path. ## Real Behavior Proof - **Environment:** macOS 25.4.0, Python 3.12 venv, this branch. - **Exact command / steps:** drive `SessionAggregator` with three failing outcomes and encode the payload through the same `_any_value` the wire uses. ```text payload: 3 {'529': 2, '500': 1} otlp : {"kvlistValue": {"values": [{"key": "529", "value": {"intValue": "2"}}, {"key": "500", "value": {"intValue": "1"}}]}} ``` The OTLP form matches `deploy/beacon/sample-event.json` byte-for-byte in shape, and `unwrap()` in `worker.js` turns `kvlistValue` back into a plain object, so it lands in R2 as `{"529": 2, "500": 1}` — the same shape as `skips`, which DuckDB reads as `MAP(VARCHAR, BIGINT)`. - **Observed result:** as above. Verified against the live corpus that schema evolution here is already routine — 3,836 of 3,884 existing rows have `rates.all_layers_saved_pct = NULL` from #2796 landing mid-corpus, and every report still runs. - **Not tested:** the deployed Worker (no staging R2 binding locally); `node --check` covers syntax only. The allowlist addition is one array entry consumed by the existing `pick()`. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Screenshots (if applicable) N/A — wire-format change, covered by the output above. ## Additional Notes **Deploy order matters.** The Worker allowlist drops unknown keys, so `deploy/beacon/worker.js` must be deployed *before* a client release that emits the field — otherwise it is discarded at the door. No corruption either way, just missing data until the Worker catches up. **Old data is unaffected.** R2 objects are immutable NDJSON written per request; nothing rewrites history. The corpus reader already passes `union_by_name = true`, which fills the column with NULL for rows written before this ships. --- deploy/beacon/sample-event.json | 15 +++++++++++++++ deploy/beacon/worker.js | 1 + headroom/telemetry/session.py | 26 ++++++++++++++++++++++++-- 3 files changed, 40 insertions(+), 2 deletions(-) diff --git a/deploy/beacon/sample-event.json b/deploy/beacon/sample-event.json index 6d5e13bd5..4bacb0ebc 100644 --- a/deploy/beacon/sample-event.json +++ b/deploy/beacon/sample-event.json @@ -284,6 +284,21 @@ "value": { "intValue": "2" } + }, + { + "key": "failure_statuses", + "value": { + "kvlistValue": { + "values": [ + { + "key": "529", + "value": { + "intValue": "2" + } + } + ] + } + } } ] } diff --git a/deploy/beacon/worker.js b/deploy/beacon/worker.js index d4e2d0ac2..5e8ec015f 100644 --- a/deploy/beacon/worker.js +++ b/deploy/beacon/worker.js @@ -42,6 +42,7 @@ const ALLOWED_KEYS = [ 'providers', 'models', 'failures', + 'failure_statuses', ]; // Resource attributes we keep. Same rule: allowlist, not denylist. diff --git a/headroom/telemetry/session.py b/headroom/telemetry/session.py index 26e45a303..cfa77f44c 100644 --- a/headroom/telemetry/session.py +++ b/headroom/telemetry/session.py @@ -246,6 +246,7 @@ class _Session: cache_write_tokens: int = 0 uncached_tokens: int = 0 failures: int = 0 + failure_statuses: dict[str, int] = field(default_factory=dict) passthrough_turns: int = 0 response_cache_hits: int = 0 overhead_ms: float = 0.0 @@ -392,6 +393,12 @@ class _Session: "providers": sorted(self.providers), "models": sorted(self.models), "failures": self.failures, + # The same failures split by status, because the count alone cannot + # answer the only question worth asking about it: a 529 is the + # provider shedding load (nothing to fix here) and a 500 is usually + # ours. Keys are the bare status string; the set is closed and tiny + # (500/502/503/504/529), so this needs no slug bounding. + "failure_statuses": dict(self.failure_statuses), } self.seq += 1 return snapshot @@ -513,8 +520,14 @@ def _fold(sess: _Session, outcome: Any, now: float, source: str = "proxy") -> No sess.uncached_tokens += int(get("uncached_input_tokens") or 0) sess.overhead_ms += float(get("overhead_ms", 0.0) or 0.0) sess.latency_ms += float(get("total_latency_ms", 0.0) or 0.0) - if int(get("status_code", 200) or 200) >= 500: + status = int(get("status_code", 200) or 200) + if status >= 500: sess.failures += 1 + # ponytail: str(status) verbatim for the 5xx range, one bucket for + # anything outside it. Nothing here can be user data, and the range + # check is what keeps a garbage status_code from inventing map keys. + key = str(status) if status < 600 else "other" + sess.failure_statuses[key] = sess.failure_statuses.get(key, 0) + 1 if get("from_response_cache", False): sess.response_cache_hits += 1 @@ -855,6 +868,7 @@ def demo() -> None: assert event["compression"]["transforms"] == {"crush": 2, "dedupe": 2} assert event["providers"] == ["anthropic"] assert event["failures"] == 0 + assert event["failure_statuses"] == {} # The new burst is a distinct session, not a continuation. agg.flush_all() @@ -976,10 +990,18 @@ def demo() -> None: class Failed(FakeOutcome): status_code = 529 + class Broke(FakeOutcome): + status_code = 500 + agg2 = SessionAggregator(emitted.append) agg2.record(Failed(), now=2000.0) + agg2.record(Failed(), now=2001.0) + agg2.record(Broke(), now=2002.0) agg2.flush_all() - assert emitted[-1]["failures"] == 1 + assert emitted[-1]["failures"] == 3 + # Provider load-shedding and our own 500s have to be separable, or the + # count says "0.7% of turns failed" and nothing about whose fault it is. + assert emitted[-1]["failure_statuses"] == {"529": 2, "500": 1} # Flushing an empty aggregator is a no-op, not a null event. before = len(emitted) From 17cdb185bc79d8cfec104e781a7e555af3ef11e1 Mon Sep 17 00:00:00 2001 From: Patrick A <141967+neogenix@users.noreply.github.com> Date: Wed, 5 Aug 2026 23:33:34 -0400 Subject: [PATCH 003/138] fix(proxy): graceful shutdown and reliable Ctrl+C exit (#621) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problems ### 1. Noisy CancelledError traceback on Ctrl+C Every Ctrl+C produced one or more "Exception in ASGI application" ERROR log entries with a CancelledError traceback: ``` ERROR: Exception in ASGI application Traceback (most recent call last): ... File "uvicorn/protocols/http/h11_impl.py", line 410, in run_asgi result = await app(...) ... asyncio.exceptions.CancelledError ``` ### 2. Inconsistent / hung shutdown in multi-worker mode (`--workers 8`) Workers blocked in a C-extension call (hnswlib, tree-sitter, ONNX inference) could prevent Ctrl+C from completing because `timeout_graceful_shutdown` defaulted to `None` (wait forever). --- ## Root causes **Root cause A (CancelledError noise)** uvicorn 0.40.0's `h11_impl.run_asgi()` (line 413) catches `BaseException` — not just `Exception` — so `asyncio.CancelledError` raised on every in-flight request at shutdown is unconditionally logged as `ERROR: Exception in ASGI application`. This is expected behaviour during shutdown, not a bug. **Root cause B (hung multi-worker shutdown)** `uvicorn.run()` was called without `timeout_graceful_shutdown`, which defaults to `None`. This means the supervisor waits indefinitely for in-flight requests to drain. A single request blocked in a C-extension (e.g. hnswlib nearest-neighbour search, tree-sitter parse, ONNX inference) prevents the whole process group from exiting. **Root cause C (hung single-worker shutdown — lifespan unbounded awaits)** The lifespan `finally` block contained unbounded `await` calls to `_beacon.stop()`, `proxy.usage_reporter.stop()`, `proxy.traffic_learner.stop()`, and `proxy.shutdown()`. uvicorn's `lifespan.shutdown()` calls `await self.shutdown_event.wait()` with no timeout — that event is only set once the lifespan `finally` block returns. Any of these awaits hanging (e.g. a reporter making a network call) therefore requires a second Ctrl+C to force-exit. --- ## Changes ### `headroom/proxy/server.py` 1. **`_SuppressCancelledErrorFilter`** (new class, ~10 lines): a `logging.Filter` that returns `False` for ERROR records on `uvicorn.error` whose `exc_info[0]` is a subclass of `asyncio.CancelledError`. Installed on `logging.getLogger("uvicorn.error")` at the start of `run_server()`. 2. **`timeout_graceful_shutdown=10`** added to `uvicorn.run()`: forces cancellation of any tasks still running 10 seconds after the shutdown signal, ensuring workers blocked in C-extensions are reaped promptly. 3. **Bounded awaits in lifespan `finally` block**: a local `_timed(coro, label, timeout)` helper wraps each shutdown step with `asyncio.wait_for()`. Timeouts: beacon.stop 3s, usage_reporter.stop 3s, traffic_learner.stop 3s, proxy.shutdown 5s. Each step logs a warning on timeout/error and continues — the teardown path is now deterministic and completes within ~15s on a single Ctrl+C. 4. **Shutdown log message** in the lifespan `finally` block: `event=proxy_shutdown reason=signal pid=` is logged as the first action on teardown. ### `tests/test_graceful_shutdown.py` (new) 9 tests: - 6 unit tests for `_SuppressCancelledErrorFilter` (suppresses CancelledError at ERROR level, passes through WARNING-level CancelledError, passes through other exceptions, handles `exc_info=None`, handles `(None,None,None)` tuple, suppresses subclasses) - 1 integration test: `run_server()` installs the filter on `uvicorn.error` - 1 integration test: `run_server()` passes `timeout_graceful_shutdown=10` to `uvicorn.run()` - 1 integration test: lifespan emits `event=proxy_shutdown` on teardown --- ## Files changed - `headroom/proxy/server.py` — filter class, bounded lifespan awaits, graceful shutdown timeout - `tests/test_graceful_shutdown.py` (new) — 9 tests - `uv.lock` — dependency lockfile updated (routine sync, no dependency changes) - `CHANGELOG.md` — changelog entry --- ## How to verify 1. Start the proxy: `headroom proxy --port 8787 --workers 8 --memory --code-aware ...` 2. Press Ctrl+C 3. Before: ERROR traceback for each in-flight request; second Ctrl+C sometimes required 4. After: clean `event=proxy_shutdown reason=signal pid=...` log, then process exits within ~15s regardless of stuck C-extensions or slow reporters --------- Co-authored-by: JD Davis --- headroom/proxy/server.py | 49 +++++- tests/test_graceful_shutdown.py | 285 ++++++++++++++++++++++++++++++++ 2 files changed, 328 insertions(+), 6 deletions(-) create mode 100644 tests/test_graceful_shutdown.py diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py index c03c76ee8..1fb97ffe8 100644 --- a/headroom/proxy/server.py +++ b/headroom/proxy/server.py @@ -470,6 +470,18 @@ logging.basicConfig( ) logger = logging.getLogger("headroom.proxy") + +class _SuppressCancelledErrorFilter(logging.Filter): + """Hide expected uvicorn CancelledError tracebacks during shutdown.""" + + def filter(self, record: logging.LogRecord) -> bool: + if record.levelno == logging.ERROR and record.exc_info: + exc_type = record.exc_info[0] + if exc_type is not None and issubclass(exc_type, asyncio.CancelledError): + return False + return True + + LoopExceptionHandler = Callable[[asyncio.AbstractEventLoop, dict[str, Any]], object] @@ -2565,21 +2577,39 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: loop.set_exception_handler(previous) app.state.ready = False - # Shutdown + logger.info("event=proxy_shutdown reason=signal pid=%d", os.getpid()) + + async def _timed(coro: Any, *, label: str, timeout: float) -> None: + try: + await asyncio.wait_for(coro, timeout=timeout) + except Exception as exc: + logger.warning( + "event=shutdown_step_timeout_or_error label=%s timeout=%.1fs exc=%r", + label, + timeout, + exc, + ) + if _cc_reconciler is not None: - await _cc_reconciler.stop() + await _timed(_cc_reconciler.stop(), label="cc_reconciler.stop", timeout=3.0) if _beacon_is_owner[0]: _release_beacon_lock() if proxy.usage_reporter: - await proxy.usage_reporter.stop() + await _timed(proxy.usage_reporter.stop(), label="usage_reporter.stop", timeout=3.0) if proxy.traffic_learner: - await proxy.traffic_learner.stop() + await _timed( + proxy.traffic_learner.stop(), label="traffic_learner.stop", timeout=3.0 + ) if proxy._background_compression_enabled: - await proxy._background_compressor.stop() + await _timed( + proxy._background_compressor.stop(), + label="background_compressor.stop", + timeout=3.0, + ) proxy._background_compression_executor.shutdown(wait=False) if proxy.code_graph_watcher: proxy.code_graph_watcher.stop() - await proxy.shutdown() + await _timed(proxy.shutdown(), label="proxy.shutdown", timeout=5.0) shutdown_headroom_tracing() shutdown_otel_metrics() @@ -5095,6 +5125,12 @@ def run_server( ╚══════════════════════════════════════════════════════════════════════╝ """) + uvicorn_error_logger = logging.getLogger("uvicorn.error") + if not any( + isinstance(item, _SuppressCancelledErrorFilter) for item in uvicorn_error_logger.filters + ): + uvicorn_error_logger.addFilter(_SuppressCancelledErrorFilter()) + app_target: Any uvicorn_kwargs: dict[str, Any] = {} if sys.platform == "win32": @@ -5150,6 +5186,7 @@ def run_server( # default. Disabling proxy_headers here guarantees the guard sees the # real peer address regardless of env. proxy_headers=False, + timeout_graceful_shutdown=10, **uvicorn_kwargs, ) diff --git a/tests/test_graceful_shutdown.py b/tests/test_graceful_shutdown.py new file mode 100644 index 000000000..7bff1e5a1 --- /dev/null +++ b/tests/test_graceful_shutdown.py @@ -0,0 +1,285 @@ +"""Tests for graceful shutdown and Ctrl+C signal handling. + +Covers: +- _SuppressCancelledErrorFilter suppresses "Exception in ASGI application" + log records whose exc_info is CancelledError +- _SuppressCancelledErrorFilter passes through unrelated error records +- timeout_graceful_shutdown is present in the uvicorn.run() call path +- The lifespan shutdown branch logs the proxy_shutdown event +- Lifespan shutdown completes even when individual steps block/raise +""" + +from __future__ import annotations + +import asyncio +import logging + +import pytest + +from headroom.proxy.server import ( + ProxyConfig, + _SuppressCancelledErrorFilter, + create_app, +) + +# --------------------------------------------------------------------------- +# Unit tests for the logging filter +# --------------------------------------------------------------------------- + + +class TestSuppressCancelledErrorFilter: + """_SuppressCancelledErrorFilter silences CancelledError noise from uvicorn.""" + + def _make_record( + self, + level: int = logging.ERROR, + exc_type: type | None = None, + ) -> logging.LogRecord: + record = logging.LogRecord( + name="uvicorn.error", + level=level, + pathname="", + lineno=0, + msg="Exception in ASGI application", + args=(), + exc_info=(exc_type, exc_type() if exc_type else None, None) if exc_type else None, + ) + return record + + def test_suppresses_cancelled_error_at_error_level(self) -> None: + f = _SuppressCancelledErrorFilter() + record = self._make_record(logging.ERROR, asyncio.CancelledError) + assert f.filter(record) is False + + def test_passes_through_cancelled_error_at_warning_level(self) -> None: + # Only suppress ERROR, not lower-severity records + f = _SuppressCancelledErrorFilter() + record = self._make_record(logging.WARNING, asyncio.CancelledError) + assert f.filter(record) is True + + def test_passes_through_other_exception_at_error_level(self) -> None: + f = _SuppressCancelledErrorFilter() + record = self._make_record(logging.ERROR, ValueError) + assert f.filter(record) is True + + def test_passes_through_record_without_exc_info(self) -> None: + f = _SuppressCancelledErrorFilter() + record = self._make_record(logging.ERROR, None) + # exc_info is set to None tuple when exc_type is None + record.exc_info = None + assert f.filter(record) is True + + def test_passes_through_record_with_none_exc_type(self) -> None: + f = _SuppressCancelledErrorFilter() + record = self._make_record(logging.ERROR, None) + record.exc_info = (None, None, None) + assert f.filter(record) is True + + def test_suppresses_subclass_of_cancelled_error(self) -> None: + """BaseException subclasses of CancelledError are also suppressed.""" + + class MyCancelled(asyncio.CancelledError): + pass + + f = _SuppressCancelledErrorFilter() + record = self._make_record(logging.ERROR, MyCancelled) + assert f.filter(record) is False + + +# --------------------------------------------------------------------------- +# Integration: filter is installed on uvicorn.error in run_server() +# --------------------------------------------------------------------------- + + +def test_run_server_installs_cancelled_error_filter(monkeypatch: pytest.MonkeyPatch) -> None: + """run_server() attaches _SuppressCancelledErrorFilter to uvicorn.error logger.""" + installed_filters: list = [] + + original_add_filter = logging.Logger.addFilter + + def capturing_add_filter(self: logging.Logger, f: logging.Filter) -> None: + if self.name == "uvicorn.error" and isinstance(f, _SuppressCancelledErrorFilter): + installed_filters.append(f) + original_add_filter(self, f) + + monkeypatch.setattr(logging.Logger, "addFilter", capturing_add_filter) + + # Intercept uvicorn.run so we don't actually start a server + monkeypatch.setattr("uvicorn.run", lambda *a, **kw: None) + + from headroom.proxy.server import run_server + + run_server(ProxyConfig(), print_banner=False) + + assert len(installed_filters) == 1, "Expected exactly one _SuppressCancelledErrorFilter" + + +# --------------------------------------------------------------------------- +# Integration: timeout_graceful_shutdown is forwarded to uvicorn.run() +# --------------------------------------------------------------------------- + + +def test_run_server_passes_timeout_graceful_shutdown(monkeypatch: pytest.MonkeyPatch) -> None: + """run_server() passes timeout_graceful_shutdown=10 to uvicorn.run().""" + captured: dict = {} + + def fake_uvicorn_run(*args: object, **kwargs: object) -> None: + captured.update(kwargs) + + monkeypatch.setattr("uvicorn.run", fake_uvicorn_run) + + from headroom.proxy.server import run_server + + run_server(ProxyConfig(), print_banner=False) + + assert "timeout_graceful_shutdown" in captured, ( + "uvicorn.run() must receive timeout_graceful_shutdown kwarg" + ) + assert captured["timeout_graceful_shutdown"] == 10 + + +# --------------------------------------------------------------------------- +# Integration: lifespan logs proxy_shutdown event on teardown +# --------------------------------------------------------------------------- + + +def test_lifespan_logs_shutdown_event(monkeypatch: pytest.MonkeyPatch) -> None: + """The lifespan finally-block logs event=proxy_shutdown when the app tears down. + + caplog cannot capture records from loggers that emit before propagation is + configured, so this test installs a custom handler directly on + ``headroom.proxy`` and checks that handler's records. + """ + # Collect log records manually because caplog propagation is unreliable + # when the root logger has pre-existing basicConfig handlers. + captured: list[logging.LogRecord] = [] + + class _Capture(logging.Handler): + def emit(self, record: logging.LogRecord) -> None: + captured.append(record) + + proxy_logger = logging.getLogger("headroom.proxy") + capture_handler = _Capture() + proxy_logger.addHandler(capture_handler) + + try: + # Prevent sys.exit(78) from _check_rust_core when Rust extension absent + monkeypatch.setattr( + "headroom.proxy.server._check_rust_core", lambda: ("disabled", "test-mock") + ) + + config = 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, + image_optimize=False, + ) + app = create_app(config) + + from fastapi.testclient import TestClient + + with TestClient(app, raise_server_exceptions=False): + pass # lifespan shutdown runs when the context manager exits + + finally: + proxy_logger.removeHandler(capture_handler) + + shutdown_records = [r for r in captured if "event=proxy_shutdown" in r.getMessage()] + assert shutdown_records, "Expected at least one log record containing 'event=proxy_shutdown'" + + +# --------------------------------------------------------------------------- +# Lifespan shutdown: bounded await (_timed helper) +# --------------------------------------------------------------------------- + + +def test_lifespan_shutdown_completes_when_proxy_shutdown_hangs( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Lifespan shutdown must complete even if proxy.shutdown() never returns. + + Before the fix, an unbounded ``await _beacon.stop()`` would block the + lifespan finally-block forever, requiring a second Ctrl+C. The fix wraps + every shutdown await with asyncio.wait_for so a slow step is skipped + after its timeout and teardown continues. + """ + import asyncio + + async def hanging_stop() -> None: + await asyncio.sleep(9999) # simulate a blocked network call + + # Prevent sys.exit(78) from the Rust-core check + monkeypatch.setattr("headroom.proxy.server._check_rust_core", lambda: ("disabled", "test-mock")) + + config = 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, + image_optimize=False, + ) + app = create_app(config) + + import headroom.proxy.server as server_mod + + monkeypatch.setattr(server_mod.HeadroomProxy, "shutdown", lambda self: hanging_stop()) + + # If the fix is absent this would hang; with the fix it returns quickly. + import time + + from fastapi.testclient import TestClient + + start = time.monotonic() + with TestClient(app, raise_server_exceptions=False): + pass + elapsed = time.monotonic() - start + # Teardown should complete well within 15 s even with the timeout; hanging + # without the fix would block until the test runner times out (~60 s). + assert elapsed < 15.0, f"Lifespan shutdown took too long: {elapsed:.1f}s" + + +def test_lifespan_shutdown_completes_when_proxy_shutdown_raises( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Lifespan shutdown must complete even if proxy.shutdown() raises. + + The _timed wrapper catches both TimeoutError and arbitrary exceptions, + logs a warning, and continues so all subsequent teardown steps still run. + """ + + async def raising_shutdown() -> None: + raise RuntimeError("simulated shutdown failure") + + monkeypatch.setattr("headroom.proxy.server._check_rust_core", lambda: ("disabled", "test-mock")) + + config = 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, + image_optimize=False, + ) + app = create_app(config) + + import headroom.proxy.server as server_mod + + monkeypatch.setattr(server_mod.HeadroomProxy, "shutdown", lambda self: raising_shutdown()) + + from fastapi.testclient import TestClient + + # Should not raise — the _timed helper swallows the exception with a warning + with TestClient(app, raise_server_exceptions=False): + pass From 7940c05ebf4486c6b9d00984067ae33cedf4dddb Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Wed, 5 Aug 2026 21:05:19 -0700 Subject: [PATCH 004/138] feat(beacon): allowlist the routing summary key (#2818) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit One line in the receiver's allowlist. No client change; the proxy's own payload is untouched. ## Why A routing extension sees things the proxy alone cannot, and they are all measurements rather than opinions: - **Empirical `min_cacheable` per provider.** Fireworks, Together and DeepInfra publish no minimum and litellm carries no value for them, so a router has to guess. But the number is directly observable — send prefix length L, see whether the repeat reports cached tokens. Across enough installs the step function falls out. - **TTL survival.** Currently modelled as a constant. - **Conversation length distribution.** The horizon is the only free parameter in a cache-aware cost model, and it decides the answer: at a 900-token prefix, 1 remaining turn and 20 remaining turns route to different models. - **Predicted vs actual cache hits.** Every response carries `cache_read_input_tokens`. Comparing it to what was predicted is the only way to find out when the cost model is lying. ## What lands here `'routing'` added to `ALLOWED_KEYS`, and the comment above the list corrected — it claimed the set mirrors `_Session.payload()`, which is no longer the whole story now that an extension can emit its own event carrying one of these keys. The ordering constraint is the reason this is its own PR: **allowlisting is a write-side gate**, so anything sent before the key exists is dropped and unrecoverable. This has to be deployed before any client starts emitting it, not alongside. ## Shape of the block Same rule as every other key — counters and model ids, no free text: ```json "routing": { "harness": "claude-code", "decisions": 47, "would_change": 12, "enforced": 9, "holdout": 3, "at_free_boundary": 4, "cross_protocol": 0, "picked": {"claude-haiku-4-5": 12, "claude-opus-5": 35}, "requested": {"claude-opus-5": 47}, "mean_prefix_tokens": 7514, "measured_cost": 0.0236, "modelled_cost": 0.0376, "cache_read_tokens": 3200, "cache_write_tokens": 0, "predicted_hits": 4, "actual_hits": 4 } ``` `measured_cost` comes from the provider's own usage; `modelled_cost` from the router's cost function. They stay separate because the difference is the only thing that means anything. The extension's `reason` string is deliberately absent. It is code-generated, so it carries no user content, but it is unbounded — it stays out rather than being reasoned about. `holdout` is the count of turns deliberately left unrouted as a control. Without it the rest is observational: once a router is acting on every request, the corpus is entirely that router's own policy. `sample-event.json` is unchanged on purpose — it mirrors `_Session.payload()`, which does not produce this key, and adding it there would suggest the proxy emits it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) --- deploy/beacon/worker.js | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/deploy/beacon/worker.js b/deploy/beacon/worker.js index 5e8ec015f..15bc22d4f 100644 --- a/deploy/beacon/worker.js +++ b/deploy/beacon/worker.js @@ -28,9 +28,12 @@ * deanonymise install_id, so it is never read. */ -// Mirrors the payload built by _Session.payload(). A key absent here is -// dropped, not stored. Adding a metric means adding it here first — that -// friction is the point. +// Mostly mirrors the payload built by _Session.payload(); an extension may +// also emit its own event carrying one of these top-level keys. A key absent +// here is dropped, not stored. Adding a metric means adding it here first — +// that friction is the point, and it is also the only privacy control that +// works retroactively, so it must land BEFORE any client starts sending the +// key or that traffic is silently discarded and unrecoverable. const ALLOWED_KEYS = [ 'schema_version', 'session', @@ -43,6 +46,13 @@ const ALLOWED_KEYS = [ 'models', 'failures', 'failure_statuses', + // Model-routing summary. Emitted by a routing extension rather than by the + // proxy itself -- see proxy/route_advice.py for the decision seam. Same rule + // as everything above: counters and model ids, no free text. Allowlisted + // here so the corpus can answer what the proxy alone cannot -- a provider's + // real minimum cacheable prefix, how long a cache actually survives, and how + // far predicted cache hits are from the ones that happened. + 'routing', ]; // Resource attributes we keep. Same rule: allowlist, not denylist. From 564e0a8d0fe440dff21a6c405c88e05698b3059f Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Thu, 6 Aug 2026 17:46:51 -0700 Subject: [PATCH 005/138] fix(deps): bump h2 to 4.4.1 for CVE-2026-71554 (#2839) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `pip-audit` is currently red on every open PR. Not because of anything in those branches — `uv.lock` pins `h2` at 4.3.0, and CVE-2026-71554 was published against `h2 <=4.4.0`. > h2 <=4.4.0 accepts request header blocks containing more than one Host header, and forwards every Host header to the consuming application. Where the consumer downgrades HTTP/2 to HTTP/1.1, the resulting request carries two Host header lines, which is a request smuggling primitive (CWE-444). Fixed in 4.4.1. Closes # ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `uv lock --upgrade-package h2`, which moves exactly two packages: ``` h2 4.3.0 -> 4.4.1 hpack 4.1.0 -> 4.2.0 ``` `h2` arrives transitively via `httpx[http2]`, and the constraint in `pyproject.toml` is already wide enough (`>=3,<5`), so only the lock needed to move — no source or `pyproject.toml` change. `requirements-prod.txt` is not checked in; the audit workflow exports it from `uv.lock` at run time, so the lock bump is the entire fix. ## Testing - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [x] Manual testing performed ### Test Output Reproduced the CI gate locally with the exact command from `.github/workflows/security.yml`: ```text $ uv export --frozen --no-dev --no-emit-project --no-hashes \ --extra all --format requirements-txt > requirements-prod.txt $ grep -E '^(h2|hpack)==' requirements-prod.txt h2==4.4.1 hpack==4.2.0 $ pip-audit -r requirements-prod.txt No known vulnerabilities found ``` Before this change, the same command reported: ```text Name | Version | ID | Fix Versions h2 | 4.3.0 | CVE-2026-71554 | 4.4.1 Found 1 known vulnerability in 1 package ``` ## Real Behavior Proof - **Environment:** macOS, uv 0.9.x, Python 3.12.6. - **Exact command / steps:** `uv lock --upgrade-package h2 --dry-run` to confirm the blast radius, then the real lock, then the workflow's own export + `pip-audit` invocation. - **Observed result:** resolution touches only `h2` and `hpack`; 269 packages resolved with no other version movement. `pip-audit` goes from 1 known vulnerability to none. - **Not tested:** HTTP/2 traffic against a live upstream. `h2` 4.4.1 is a patch release on a library used transitively by `httpx`; Headroom does not import `h2` directly (`grep -rn "import h2" headroom/` is empty), so the exposure is whatever `httpx[http2]` does with it. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes N/A items above: no code changed, so ruff/mypy/new tests do not apply — the verification that matters is the audit output, which is quoted in full. **Why this is standalone.** It surfaced while fixing CI on #2838, but it is not caused by that branch and it blocks #2832 identically. Landing it separately unblocks the gate for every open PR at once and keeps a supply-chain bump out of an unrelated change. **One unrelated warning the resolver prints**, noted so it is not mistaken for a side effect of this PR: ``` warning: `pypdfium2==5.12.0` is yanked (reason: "Setup blunder breaking some bindgen codepaths ... Wheels are valid and effectively identical to 5.12.1") ``` That predates this change and is not touched by it. Worth its own bump, but not here. --- uv.lock | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/uv.lock b/uv.lock index c70b4098d..b80d4d91f 100644 --- a/uv.lock +++ b/uv.lock @@ -1667,15 +1667,15 @@ wheels = [ [[package]] name = "h2" -version = "4.3.0" +version = "4.4.1" source = { registry = "https://pypi.org/simple/" } dependencies = [ { name = "hpack" }, { name = "hyperframe" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/1d/17/afa56379f94ad0fe8defd37d6eb3f89a25404ffc71d4d848893d270325fc/h2-4.3.0.tar.gz", hash = "sha256:6c59efe4323fa18b47a632221a1888bd7fde6249819beda254aeca909f221bf1", size = 2152026, upload-time = "2025-08-23T18:12:19.778Z" } +sdist = { url = "https://files.pythonhosted.org/packages/e7/85/7c366e69d84c17bb778fe41419e1fbcce3033d5b7ce29bbffff0a98b859f/h2-4.4.1.tar.gz", hash = "sha256:4e866ffb1a869ae14dd9b5e6beb5c24a13da0495ad72b65925ded182521c1516", size = 2157281, upload-time = "2026-08-03T11:45:09.509Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/69/b2/119f6e6dcbd96f9069ce9a2665e0146588dc9f88f29549711853645e736a/h2-4.3.0-py3-none-any.whl", hash = "sha256:c438f029a25f7945c69e0ccf0fb951dc3f73a5f6412981daee861431b70e2bdd", size = 61779, upload-time = "2025-08-23T18:12:17.779Z" }, + { url = "https://files.pythonhosted.org/packages/7e/22/e85faf23bd72a92d1921e37d674ca56eb298a3c8be31fdecef0ff2b3aaac/h2-4.4.1-py3-none-any.whl", hash = "sha256:0e25f1462b23c9cb82d9eb02e28bc706dac2a68cb457c6a0d74d63c8a2a5d0e6", size = 62636, upload-time = "2026-08-03T11:44:59.164Z" }, ] [[package]] @@ -2078,11 +2078,11 @@ sdist = { url = "https://files.pythonhosted.org/packages/cf/7a/1a9b1405f2eb59515 [[package]] name = "hpack" -version = "4.1.0" +version = "4.2.0" source = { registry = "https://pypi.org/simple/" } -sdist = { url = "https://files.pythonhosted.org/packages/2c/48/71de9ed269fdae9c8057e5a4c0aa7402e8bb16f2c6e90b3aa53327b113f8/hpack-4.1.0.tar.gz", hash = "sha256:ec5eca154f7056aa06f196a557655c5b009b382873ac8d1e66e79e87535f1dca", size = 51276, upload-time = "2025-01-22T21:44:58.347Z" } +sdist = { url = "https://files.pythonhosted.org/packages/26/5b/fcabf6028144a8723726318b07a32c2f3314acdff6265743cf08a344b18e/hpack-4.2.0.tar.gz", hash = "sha256:0895cfa3b5531fc65fe439c05eb65144f123bf7a394fcaa56aa423548d8e45c0", size = 51300, upload-time = "2026-06-23T18:34:46.667Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/07/c6/80c95b1b2b94682a72cbdbfb85b81ae2daffa4291fbfa1b1464502ede10d/hpack-4.1.0-py3-none-any.whl", hash = "sha256:157ac792668d995c657d93111f46b4535ed114f0c9c8d672271bbec7eae1b496", size = 34357, upload-time = "2025-01-22T21:44:56.92Z" }, + { url = "https://files.pythonhosted.org/packages/71/b4/4a9fcfb2aef6ba44d9073ecd301443aa00b3dac95de5619f2a7de7ec8a91/hpack-4.2.0-py3-none-any.whl", hash = "sha256:858ac0b02280fa582b5080d68db0899c62a80375e0e5413a74970c5e518b6986", size = 34246, upload-time = "2026-06-23T18:34:45.472Z" }, ] [[package]] From 53af90d68c723f644a5a41dd273a606117109866 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Thu, 6 Aug 2026 17:47:40 -0700 Subject: [PATCH 006/138] perf: cut hot-path latency 27% (token-count memo, startup preloads, JSON scan memo) (#2838) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Four independent latency fixes on the request hot path, found by profiling and each measured in isolation. No behaviour changes: every commit is either a memo of a pure function, work moved to startup, or work that was computed and discarded. **End to end: 287ms → 210ms (−27%) on a 68k-token mixed payload, with byte-identical output** (68,514 → 48,725 tokens both before and after). Plus one-off costs removed that don't show in steady-state numbers: ~4.9s of lazy imports that were firing *inside* user requests, and ~750ms of HuggingFace round-trips per process start. Closes # ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [x] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made **1. Memoise `count_text` (`ac369277`)** — tiktoken's `CoreBPE.encode` was 0.243s of a 0.30s profiled request. It dominates because the same string is counted repeatedly: a 103KB payload drove 600KB of encoding, ~6x the content, across six call sites (`tokenizers/base.py:196`, `content_router.py:4704` and `:5474`, `parser.py:185/192/298`). 35% of encode calls and 22% of encoded characters were an exact repeat *within one request*. `count_text` is a pure function of its text, so replaying a stored count returns the same integer. That is the whole safety argument, and it is what makes this safe at the sites whose count feeds a routing decision (`context_pressure` → `min_ratio`) rather than a log line — an *estimate* there would change which blocks compress; a memo cannot. Keyed on the text itself, not a hash: a collision would hand back a wrong count for real content and silently change compression. The cost is holding the strings, so entries and total characters are both capped. Clear-on-full rather than LRU eviction — the pipeline runs on a thread pool, `dict` get/set/clear are atomic under the GIL but `OrderedDict.move_to_end` is not. **2. Preload what was importing mid-request (`2921a15b`)** — `litellm` (2.9–3.8s) was imported lazily *on the event loop* during the first request: `emit_request_outcome` → `record_request` → `_estimate_compression_savings_usd` calls the loader before its own `tokens_saved <= 0` early return, so even a request that saved nothing paid it. `trafilatura` (978ms, pulling `htmldate` → `dateparser` and its timezone tables) is the most expensive lazy import in the transform tree — every other compressor module is 1–20ms — and fires on the first request carrying an HTML-ish or mixed-content block. The TOIN singleton reads ~5MB of learned patterns on construction (~150ms); a stale comment claimed the SmartCrusher preload covered it, and it does not. All three now load in `_eager_preload_transforms`, which already runs under `asyncio.to_thread` and so cannot delay the port bind. Same commit, two Kompress cold-path fixes: `_load_modernbert_tokenizer` always used `local_files_only=False`, which makes transformers re-validate against the Hub on every load — a tree listing plus a HEAD per file — even when fully cached (~900ms warm-cache vs ~150ms local-only). And `ensure_background_download` re-spawned a finished-or-failed thread on the next call, so an unreachable Hub meant one fresh download thread *per request* for the life of the process, each importing transformers and holding the GIL against the event loop. Consecutive failures now back off; success clears it, so the happy path and the transient-failure path are unchanged. **3. Memoise the JSON-block scan (`039c9735`)** — `_has_valid_json_block_with_text` tries every `{`/`[`-leading line as a possible block start. When a candidate never balances, `_extract_json_block` scans character-by-character to the end of the content and returns nothing — then the next candidate does it again. Quadratic, on the request path, growing exactly 4x per doubling. **4. `CostTracker.totals()` (`286b97e4`)** — `_current_savings_tracker_totals` called `stats()` once per request and read two of its fields. Building the rest includes `period_cost_breakdown()`, which walks up to 100k cost records over 31 days, on the event loop, holding the metrics lock. It degrades with proxy **uptime**, not load, which is why no short benchmark would surface it. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ ruff check headroom/ tests/ --exclude headroom/dashboard/templates All checks passed! $ mypy --python-version 3.12 headroom/ Found 1 error in 1 file (checked 515 source files) headroom/release_version.py:235: error: Name "tomllib" already defined (by an import) # pre-existing on main, in a file this PR does not touch — verified by # running the same command on a clean main checkout. $ python -m pytest tests/test_token_count_cache.py tests/test_mixed_content_scan_cache.py \ tests/test_kompress_download_backoff.py tests/test_cost_tracker_totals.py -q 306 passed $ python -m pytest tests/ -q -k "token or tokenizer or count or estimator or provider" 1303 passed, 105 skipped in 423.42s $ python -m pytest tests/ -q -k "cost or budget or metrics or savings or stats" 683 passed, 127 skipped, 1 failed # tests/test_proxy_memory_integration.py::TestMemoryStats::test_health_endpoint_works_with_memory # Order-dependent and pre-existing: it SKIPS in isolation, and fails identically # on a clean main checkout under the same -k selection (681 passed, 1 failed). ``` ## Real Behavior Proof - **Environment:** macOS, Python 3.12.6, local CPU, remote Kompress disabled. Profiled with `cProfile` on `anthropic_pipeline.apply`. - **Exact command / steps:** a 68k-token payload of four `tool_result` blocks (900-item pretty JSON, 60KB of Python source, 500 lines of JS-style object logs, 500 plain log lines), six reps, **content unique per rep so every run is router-cache-cold**, run on this branch and on main in alternation. - **Observed result:** | | median | min | tokens | |---|---|---|---| | main | 287ms | 286ms | 68,514 → 48,725 | | this branch | 210ms | 208ms | 68,514 → 48,725 | Per-change, measured in isolation: | change | before | after | |---|---|---| | `count_text` memo | — | −25% pipeline wall; 44% of counted chars from cache on new content, 100% when history repeats | | litellm / trafilatura / TOIN | 3829 / 978 / 150ms mid-request | at startup, off the event loop | | Kompress tokenizer | ~900ms | ~150ms | | JS-style object logs (1200 lines) | 4643ms | 183ms | | truncated JSONL (1200 lines) | 3737ms | 116ms | | `cost_tracker` per request | 2.8ms @20k records, 13.6ms @100k | loop over models, not records | Output equality: 18/18 payloads byte-identical on `tokens_before`, `tokens_after` and a sha256 of the resulting messages, with the memo forced on vs off. - **Not tested:** Windows and Linux (the ORT dylib and CPU-arena paths differ); multi-worker deployments; a proxy with a genuinely large live cost ledger (the 100k figure is from a synthetic ledger); real HTML-heavy traffic through the preloaded trafilatura path. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes **Docs:** N/A — no user-facing surface changes. The reasoning lives in the code, at the sites where someone debugging would look. **A regression I introduced and caught.** The scan memo initially made pretty-printed JSON ~2x **slower**: content that balances on the first scan has nothing to reuse and just pays the per-line dict traffic. The cache is now built only *after* a scan has run to the end without balancing, which is the actual signal that later candidates will re-walk the same tail. Every shape now improves and none regress: ``` before after js object logs 4642.9ms 182.7ms 25x JSONL truncated 3736.8ms 115.9ms 32x pretty JSON 5.6ms 3.5ms JSONL valid 5.6ms 3.2ms plain logs 1.0ms 0.6ms python source 1.0ms 0.5ms markdown prose 0.9ms 0.5ms ``` Worth stating plainly: had I only benchmarked the shape I was fixing, I'd have shipped a win on rare content and a loss on the common case. **The scan fix is constant-factor, not asymptotic.** The walk over remaining lines is still O(candidates × lines), so 3200 lines of the pathological shape is still ~1.4s. The tests assert scan-call counts rather than implying linearity. True linearity needs a prefix-sum rewrite with a string-state fallback; that seemed like the wrong risk for this PR. **How the parser change is proven safe.** `_extract_json_block` is a parser, so golden values would only encode whatever the new code does. Instead the pre-memo implementation is kept verbatim in the test file as an oracle, and every candidate index of a 139-document corpus — escapes, unterminated strings, delimiters inside strings, code fences, truncated JSON, randomised mixtures — is asserted equal, with a cold cache, with the shared cache the real callers use, and replayed. **Measurement trap, for anyone re-running these numbers.** Give each arm its own content. Reusing one payload across arms lets the second arm hit the router's result cache, which reads as a speedup having nothing to do with the change under test. I hit this twice while working on it: it manufactured a fake "INFO logging costs 21.8%" finding (real answer: 0.3%) and it *understated* the memo win. **Deliberately not in this PR:** - **ONNX thread tuning** — measured zero gain, and `intra_op_num_threads` is not bitwise-safe (1.6e-05 score drift from float reduction order), so it would trade an output risk for nothing. - **`str(content)` on block lists** counts a base64 image at 210,775 tokens instead of 1,604 (131x), pinning `context_pressure` to 1.0 and forcing the most aggressive `min_ratio` on any conversation containing an image. Real bug, but fixing it changes compression output — needs its own reviewed behaviour-change PR. - **`chunk_words=350` against the tokenizer's 512-token limit** silently drops roughly a third of every full chunk (measured: 240/240 words kept in the first 240, 15/110 in the tail). That is data loss rather than latency, it changes every output, and correcting it costs ~1.3x latency. Filing separately. - **Telemetry off the request thread** — the TOIN auto-save is a 236ms inline stall every 600s and the waste-signal re-parse is ~50ms/request that is invisible in `pipeline_total` (computed before it). Both want deferral rather than removal, which is a larger change than belongs here. --- headroom/providers/anthropic.py | 15 +- headroom/proxy/cost.py | 33 ++++ headroom/proxy/prometheus_metrics.py | 8 +- headroom/proxy/server.py | 20 +++ headroom/tokenizers/base.py | 62 +++++++ headroom/tokenizers/estimator.py | 11 +- headroom/tokenizers/tiktoken_counter.py | 11 +- headroom/transforms/content_router.py | 33 +++- headroom/transforms/kompress_compressor.py | 70 +++++++- headroom/transforms/mixed_content.py | 130 ++++++++++---- tests/test_cost_tracker_totals.py | 80 +++++++++ tests/test_kompress_download_backoff.py | 116 ++++++++++++ tests/test_mixed_content_scan_cache.py | 197 +++++++++++++++++++++ tests/test_proxy_eager_preload_bind.py | 9 +- tests/test_token_count_cache.py | 108 +++++++++++ 15 files changed, 854 insertions(+), 49 deletions(-) create mode 100644 tests/test_cost_tracker_totals.py create mode 100644 tests/test_kompress_download_backoff.py create mode 100644 tests/test_mixed_content_scan_cache.py create mode 100644 tests/test_token_count_cache.py diff --git a/headroom/providers/anthropic.py b/headroom/providers/anthropic.py index 5cac19a06..ef488ee3d 100644 --- a/headroom/providers/anthropic.py +++ b/headroom/providers/anthropic.py @@ -24,7 +24,11 @@ import warnings from typing import Any, cast from headroom import paths as _paths -from headroom.tokenizers.base import coerce_countable_text, count_content_blocks +from headroom.tokenizers.base import ( + TokenCountCache, + coerce_countable_text, + count_content_blocks, +) from .base import Provider, TokenCounter @@ -309,6 +313,7 @@ class AnthropicTokenCounter(TokenCounter): self.model = model self._client = client self._encoding: Any = None + self._count_cache = TokenCountCache() self._use_api = client is not None if not self._use_api and warn and not _FALLBACK_WARNING_SHOWN: @@ -351,6 +356,14 @@ class AnthropicTokenCounter(TokenCounter): if not text: return 0 + cached = self._count_cache.get(text) + if cached is not None: + return cached + count = self._count_text_uncached(text) + self._count_cache.put(text, count) + return count + + def _count_text_uncached(self, text: str) -> int: if self._encoding: # tiktoken with ~1.1x multiplier for Claude try: diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.py index 435c09fd4..cff6be4b2 100644 --- a/headroom/proxy/cost.py +++ b/headroom/proxy/cost.py @@ -1057,6 +1057,39 @@ class CostTracker: except Exception: return None + def totals(self) -> tuple[int, float]: + """Return just ``(total_input_tokens, total_input_cost_usd)``. + + The same two numbers ``stats()`` reports, computed without the rest of + it. ``stats()`` is called once per request by the metrics path, which + reads exactly these two fields and discards ``per_model``, + ``savings_usd``, ``cost_with_headroom_usd`` and — the expensive one — + ``budget_basis``, whose ``period_cost_breakdown()`` walks up to 31 days + of retained cost records. MEASURED 2.8ms at 20k records and 13.6ms at + 100k, on the event loop and holding the metrics lock, so it degraded + with proxy uptime rather than with load. + + This loop is over models, not records, so it is bounded by how many + models a deployment talks to. + """ + total_input_tokens = 0 + cost_with_headroom = 0.0 + for model in self._tokens_saved_by_model: + sent = self._tokens_sent_by_model.get(model, 0) + cr = self._api_cache_read_by_model.get(model, 0) + cw = self._api_cache_write_by_model.get(model, 0) + uncached = self._api_uncached_by_model.get(model, 0) + total_input_tokens += sent + + prices = self._get_cache_prices(model) + if prices: + cr_price, cw_price, uncached_price = prices + if cr + cw + uncached > 0: + cost_with_headroom += cr * cr_price + cw * cw_price + uncached * uncached_price + else: + cost_with_headroom += sent * uncached_price + return total_input_tokens, round(cost_with_headroom, 4) + def stats(self) -> dict: """Get token statistics per model.""" per_model = {} diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.py index 4f691b79b..3bf4b4103 100644 --- a/headroom/proxy/prometheus_metrics.py +++ b/headroom/proxy/prometheus_metrics.py @@ -417,14 +417,14 @@ class PrometheusMetrics: return total_input_tokens, total_input_cost_usd try: - cost_stats = self.cost_tracker.stats() + # totals() rather than stats(): identical numbers, without the + # 31-day cost-record walk that stats()["budget_basis"] performs and + # this caller throws away. See CostTracker.totals. + tracked_input_tokens, tracked_input_cost_usd = self.cost_tracker.totals() except Exception: logger.debug("Failed to read cost tracker totals for savings history", exc_info=True) return total_input_tokens, total_input_cost_usd - tracked_input_tokens = cost_stats.get("total_input_tokens") - tracked_input_cost_usd = cost_stats.get("total_input_cost_usd") - if tracked_input_tokens is not None: try: total_input_tokens = self._savings_tracker_input_tokens_offset + max( diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py index 1fb97ffe8..1b58db04e 100644 --- a/headroom/proxy/server.py +++ b/headroom/proxy/server.py @@ -1638,6 +1638,26 @@ class HeadroomProxy( for key, value in transform_status.items(): eager_status.setdefault(key, value) transform_statuses.append(transform_status) + + # LiteLLM's pricing tables. MEASURED 2.9-3.8s to import, and it was + # being imported lazily ON THE EVENT LOOP during the first request: + # emit_request_outcome -> record_request -> _estimate_compression_savings_usd + # calls it before its own `tokens_saved <= 0` early return, so even a + # request that saved nothing pays for it. Nothing about that is visible + # as a failure; it just makes one unlucky user wait ~3s. + # + # This function already runs under asyncio.to_thread, so importing here + # cannot delay the port bind. + try: + from .savings_tracker import _get_litellm_module + + eager_status.setdefault( + "litellm", "ready" if _get_litellm_module() is not None else "not installed" + ) + except Exception as exc: # pricing is optional; never block startup on it + logger.debug("LiteLLM pre-load skipped: %s", exc) + eager_status.setdefault("litellm", "skipped") + return eager_status, transform_statuses async def startup(self): diff --git a/headroom/tokenizers/base.py b/headroom/tokenizers/base.py index 5d291216d..cc9f12515 100644 --- a/headroom/tokenizers/base.py +++ b/headroom/tokenizers/base.py @@ -17,6 +17,68 @@ from typing import Any, Protocol, runtime_checkable #: encode. Truncating keeps the estimate finite and the request alive. _MAX_COERCED_FIELD_CHARS = 200_000 +#: Admission policy for :class:`TokenCountCache`. These bound memory only — they +#: never change a returned count, so they are not a behavioural threshold. +#: Strings below the floor encode in microseconds, so caching them would only +#: evict the large entries that the cache exists for. +_COUNT_CACHE_MIN_CHARS = 256 +_COUNT_CACHE_MAX_ENTRIES = 4096 +_COUNT_CACHE_MAX_CHARS = 8_000_000 + + +class TokenCountCache: + """Exact memo for ``count_text``. + + ``count_text`` is a pure function of its text, so replaying a stored count is + value-identical. That is the whole safety argument: the result is the same + integer, which is why this is safe even at the call sites whose count feeds a + routing decision (``context_pressure`` -> ``min_ratio``) rather than a log line. + + Keyed on the text itself rather than a hash. A hash collision here would hand + back the wrong count for real content and silently change what gets + compressed; the counts are too load-bearing to trade correctness for a + smaller key. The price is holding the strings, so entries *and* total + characters are capped. + + No lock: ``dict`` get/set/clear are atomic under the GIL, and the pipeline + runs on a thread pool. An LRU would need ``move_to_end``, which is not + atomic — hence clear-on-full rather than eviction. A cleared cache costs one + re-encode, never a wrong answer. + """ + + __slots__ = ("_chars", "_counts", "_max_chars", "_max_entries", "_min_chars") + + def __init__( + self, + *, + min_chars: int = _COUNT_CACHE_MIN_CHARS, + max_entries: int = _COUNT_CACHE_MAX_ENTRIES, + max_chars: int = _COUNT_CACHE_MAX_CHARS, + ) -> None: + self._counts: dict[str, int] = {} + self._chars = 0 + self._min_chars = min_chars + self._max_entries = max_entries + self._max_chars = max_chars + + def get(self, text: str) -> int | None: + """Return the stored count for *text*, or None.""" + return self._counts.get(text) + + def put(self, text: str, count: int) -> None: + """Store *count* for *text* if it is worth caching.""" + if len(text) < self._min_chars: + return + if len(self._counts) >= self._max_entries or self._chars >= self._max_chars: + self._counts.clear() + self._chars = 0 + self._counts[text] = count + self._chars += len(text) + + def clear(self) -> None: + self._counts.clear() + self._chars = 0 + def coerce_countable_text(value: Any) -> str: """Return *value* as text safe to pass to ``count_text``. diff --git a/headroom/tokenizers/estimator.py b/headroom/tokenizers/estimator.py index e20ea15d5..a3ee9683e 100644 --- a/headroom/tokenizers/estimator.py +++ b/headroom/tokenizers/estimator.py @@ -11,7 +11,7 @@ import json import re from typing import Any -from .base import BaseTokenizer +from .base import BaseTokenizer, TokenCountCache class EstimatingTokenCounter(BaseTokenizer): @@ -87,6 +87,7 @@ class EstimatingTokenCounter(BaseTokenizer): If None, auto-detects based on content type. """ self._fixed_ratio = chars_per_token + self._count_cache = TokenCountCache() def count_text(self, text: str) -> int: """Estimate token count for text. @@ -100,6 +101,14 @@ class EstimatingTokenCounter(BaseTokenizer): if not text: return 0 + cached = self._count_cache.get(text) + if cached is not None: + return cached + count = self._count_text_uncached(text) + self._count_cache.put(text, count) + return count + + def _count_text_uncached(self, text: str) -> int: # Use fixed ratio if provided. Dense scripts (CJK/Kana/Hangul) still # tokenize at ~1 token per character, so pricing them at the (Latin) # fixed ratio under-counts by 2-4x — the same correction the auto path diff --git a/headroom/tokenizers/tiktoken_counter.py b/headroom/tokenizers/tiktoken_counter.py index 1aa987037..4ec8fadc2 100644 --- a/headroom/tokenizers/tiktoken_counter.py +++ b/headroom/tokenizers/tiktoken_counter.py @@ -16,7 +16,7 @@ import threading from functools import lru_cache from typing import Any -from .base import BaseTokenizer, coerce_countable_text +from .base import BaseTokenizer, TokenCountCache, coerce_countable_text logger = logging.getLogger(__name__) @@ -237,6 +237,7 @@ class TiktokenCounter(BaseTokenizer): self.model = model self.encoding_name = encoding or get_encoding_for_model(model) self._encoding = None # Lazy load + self._count_cache = TokenCountCache() @property def encoding(self): @@ -256,6 +257,14 @@ class TiktokenCounter(BaseTokenizer): """ if not text: return 0 + cached = self._count_cache.get(text) + if cached is not None: + return cached + count = self._count_text_uncached(text) + self._count_cache.put(text, count) + return count + + def _count_text_uncached(self, text: str) -> int: try: return len(self.encoding.encode(text)) except ValueError: diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py index 4aeb03f3e..657638e40 100644 --- a/headroom/transforms/content_router.py +++ b/headroom/transforms/content_router.py @@ -4186,11 +4186,42 @@ class ContentRouter(Transform): else: status["code_aware"] = "not installed" - # 4. SmartCrusher (lightweight init, but ensures import + TOIN ready) + # 4. SmartCrusher (lightweight init) smart_crusher = self._get_smart_crusher() if smart_crusher: status["smart_crusher"] = "ready" + # 5. HTML extractor. + # + # By far the most expensive lazy import in the transform tree: MEASURED + # 978ms for trafilatura -> htmldate -> dateparser and its timezone + # tables, against 1-20ms for every other compressor module. It fires + # from _get_html_extractor() on the first request carrying an HTML-ish + # block or mixed-content section, so a real user pays the full second + # mid-request. That is the single largest first-request stall in the + # pipeline, which is why it is worth a line here. + try: + if self._get_html_extractor() is not None: + status["html_extractor"] = "ready" + else: + status["html_extractor"] = "not installed" + except Exception as e: + logger.debug("HTML extractor pre-load skipped: %s", e) + status["html_extractor"] = "skipped" + + # 6. TOIN singleton. Constructing it reads the learned-pattern file off + # disk (MEASURED ~150ms at 5MB, and it grows with use). SmartCrusher + # above does NOT pull it in, despite what a previous comment here + # claimed — the first request did. + try: + from ..telemetry.toin import get_toin + + get_toin() + status["toin"] = "ready" + except Exception as e: + logger.debug("TOIN pre-load skipped: %s", e) + status["toin"] = "skipped" + return status def _get_kompress(self) -> Any: diff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.py index 37c4260cf..84caa0896 100644 --- a/headroom/transforms/kompress_compressor.py +++ b/headroom/transforms/kompress_compressor.py @@ -746,15 +746,27 @@ def _load_kompress_onnx( def _load_modernbert_tokenizer(auto_tokenizer: Any, *, allow_download: bool) -> Any: - """Load the ModernBERT tokenizer, cache-only when ``allow_download`` is False.""" + """Load the ModernBERT tokenizer, cache-only when ``allow_download`` is False. + + Always tries the local cache FIRST, even when downloading is allowed. With + ``local_files_only=False`` transformers re-validates against the Hub on every + load — a tree listing plus a HEAD per tokenizer file — even when the repo is + fully cached. MEASURED ~900ms warm-cache versus ~150ms local-only, i.e. ~750ms + of pure network round-trip on every process start, and it is also what makes + a cold start slow on a bad network rather than merely offline. + + Same files, same tokenizer, so the loaded object is identical; this only + changes whether the Hub is consulted to confirm what is already on disk. + Mirrors ``onnx_runtime.hf_hub_download_local_first``, which the ONNX half of + this loader already uses. + """ try: - return auto_tokenizer.from_pretrained( - "answerdotai/ModernBERT-base", local_files_only=not allow_download - ) + return auto_tokenizer.from_pretrained("answerdotai/ModernBERT-base", local_files_only=True) except _NOT_CACHED_ERRORS as exc: if not allow_download: raise KompressModelNotCached("answerdotai/ModernBERT-base") from exc - raise + # Genuine cache miss and downloading is permitted: fetch it. + return auto_tokenizer.from_pretrained("answerdotai/ModernBERT-base", local_files_only=False) # Sub-state-dict keys inside a merged v2-style checkpoint (see @@ -1039,6 +1051,45 @@ def unload_kompress_model(model_id: str | None = None) -> bool: _download_threads: dict[str, threading.Thread] = {} _download_threads_lock = threading.Lock() +#: Retry backoff for a FAILED background download, in seconds. A finished-or-failed +#: thread is replaced on the next call so a transient network blip recovers, but +#: without a floor an unreachable Hub means every request spawns a fresh download +#: thread for the life of the process — each one importing transformers and +#: resolving the Hub, all holding the GIL against the event loop. The window grows +#: per consecutive failure and resets on success, so the happy path and the +#: transient-failure path are both unchanged; only the permanently-broken case is +#: bounded. +_DOWNLOAD_RETRY_BASE_SECONDS = 5.0 +_DOWNLOAD_RETRY_MAX_SECONDS = 300.0 +_download_failures: dict[str, tuple[int, float]] = {} + + +def _record_download_failure(model_id: str) -> None: + with _download_threads_lock: + failures, _ = _download_failures.get(model_id, (0, 0.0)) + _download_failures[model_id] = (failures + 1, time.monotonic()) + + +def _clear_download_failures(model_id: str) -> None: + with _download_threads_lock: + _download_failures.pop(model_id, None) + + +def _download_retry_blocked(model_id: str) -> bool: + """True when the last attempt failed and the backoff window has not elapsed. + + Caller must hold ``_download_threads_lock``. + """ + entry = _download_failures.get(model_id) + if entry is None: + return False + failures, last_attempt = entry + window = min( + _DOWNLOAD_RETRY_MAX_SECONDS, + _DOWNLOAD_RETRY_BASE_SECONDS * (2 ** (failures - 1)), + ) + return bool((time.monotonic() - last_attempt) < window) + def _background_download(model_id: str, device: str) -> None: try: @@ -1046,7 +1097,10 @@ def _background_download(model_id: str, device: str) -> None: _load_kompress(model_id, device, allow_download=True) logger.info("Kompress: background model download complete for %s", model_id) except Exception as exc: + _record_download_failure(model_id) logger.warning("Kompress: background model download failed for %s: %s", model_id, exc) + else: + _clear_download_failures(model_id) def ensure_background_download(model_id: str = HF_MODEL_ID, device: str = "auto") -> None: @@ -1054,7 +1108,9 @@ def ensure_background_download(model_id: str = HF_MODEL_ID, device: str = "auto" Idempotent and non-blocking: at most one download thread runs per model_id, and a finished or failed thread is replaced on the next call so a transient - network failure can be retried by a later request. Once the download + network failure can be retried by a later request — subject to a growing + backoff after consecutive failures, so an unreachable Hub cannot turn every + request into another download thread. Once the download completes the deep path activates on subsequent requests without ever blocking one on the network. """ @@ -1066,6 +1122,8 @@ def ensure_background_download(model_id: str = HF_MODEL_ID, device: str = "auto" existing = _download_threads.get(model_id) if existing is not None and existing.is_alive(): return + if _download_retry_blocked(model_id): + return thread = threading.Thread( target=_background_download, args=(model_id, device), diff --git a/headroom/transforms/mixed_content.py b/headroom/transforms/mixed_content.py index 6991c1acb..3ec7b2b80 100644 --- a/headroom/transforms/mixed_content.py +++ b/headroom/transforms/mixed_content.py @@ -43,16 +43,32 @@ def mixed_content_indicators(content: str) -> dict[str, bool]: } +def _any_nonblank(lines: list[str], start: int, stop: int) -> bool: + """True when some line in [start, stop) has non-whitespace. + + Equivalent to ``bool("\n".join(lines[start:stop]).strip())`` — a join of + lines is blank exactly when every line is blank — but it short-circuits + instead of building a copy of the whole body for each candidate. + """ + return any(lines[i].strip() for i in range(start, stop)) + + def _has_valid_json_block_with_text(content: str) -> bool: """Return true when prose or log text wraps a valid JSON block.""" lines = content.split("\n") + # Built only after a scan has run to the end without balancing — see + # _extract_json_block. Content that balances promptly never allocates it and + # so pays nothing for it. + scan_cache: dict[tuple[int, bool, bool], tuple[int, int, bool, bool]] | None = None for index, line in enumerate(lines): if not line.strip().startswith(("[", "{")): continue - json_content, end_index = _extract_json_block(lines, index) + json_content, end_index = _extract_json_block(lines, index, cache=scan_cache) if json_content is None: + if scan_cache is None: + scan_cache = {} continue try: @@ -60,9 +76,7 @@ def _has_valid_json_block_with_text(content: str) -> bool: except (TypeError, ValueError): continue - leading_text = "\n".join(lines[:index]).strip() - trailing_text = "\n".join(lines[end_index + 1 :]).strip() - if leading_text or trailing_text: + if _any_nonblank(lines, 0, index) or _any_nonblank(lines, end_index + 1, len(lines)): return True return False @@ -72,6 +86,7 @@ def split_into_sections(content: str) -> list[ContentSection]: """Parse mixed content into typed sections.""" sections: list[ContentSection] = [] lines = content.split("\n") + scan_cache: dict[tuple[int, bool, bool], tuple[int, int, bool, bool]] | None = None i = 0 while i < len(lines): @@ -101,7 +116,11 @@ def split_into_sections(content: str) -> list[ContentSection]: continue if line.strip().startswith(("[", "{")): - json_content, end_i = _extract_json_block(lines, i) + json_content, end_i = _extract_json_block(lines, i, cache=scan_cache) + if json_content is None and scan_cache is None: + # First scan that ran to the end without balancing: from here on + # every later candidate would re-walk the same tail. + scan_cache = {} if json_content: sections.append( ContentSection( @@ -159,41 +178,84 @@ def split_into_sections(content: str) -> list[ContentSection]: return sections -def _extract_json_block(lines: list[str], start: int) -> tuple[str | None, int]: - """Extract a complete JSON object or array block from line-oriented content.""" +def _scan_line(line: str, in_string: bool, escaped: bool) -> tuple[int, int, bool, bool]: + """Bracket/brace deltas for one line, given the parser state entering it. + + Split out so the per-line result can be memoised across scans: what a line + does to the counters is a pure function of the line and the two entry-state + flags, nothing else. + """ + bracket = 0 + brace = 0 + for ch in line: + if escaped: + escaped = False + continue + if ch == "\\": + if in_string: + escaped = True + continue + if ch == '"': + in_string = not in_string + continue + if in_string: + continue + if ch == "[": + bracket += 1 + elif ch == "]": + bracket -= 1 + elif ch == "{": + brace += 1 + elif ch == "}": + brace -= 1 + return bracket, brace, in_string, escaped + + +def _extract_json_block( + lines: list[str], + start: int, + *, + cache: dict[tuple[int, bool, bool], tuple[int, int, bool, bool]] | None = None, +) -> tuple[str | None, int]: + """Extract a complete JSON object or array block from line-oriented content. + + ``cache`` memoises the per-line scan across repeated calls over the SAME + ``lines``. Callers that try every ``{``-leading line share one dict; without + it each candidate that never balances re-scans character-by-character to the + end of the content, which is quadratic. + + Callers pass ``None`` until a scan has actually run to the end without + balancing, and only build the dict from then on. That matters: on content + that balances on the first try — pretty-printed JSON, the common case — the + memo has nothing to reuse and its per-line dict traffic made that shape ~2x + SLOWER. A failed scan is the signal that later candidates will re-walk the + same tail, and it is the only point at which the memo pays. MEASURED before the cache: 4643ms for + 1200 lines of JS-style object logs and 3737ms for truncated JSONL, growing + exactly 4x per doubling. Ordinary shapes — pretty-printed JSON, valid JSONL, + source, stack traces, prose — were ~1-6ms and never hit it, which is why this + stayed invisible. + + Keyed on the entry state as well as the line, so a cached entry is only + reused where the parser is in the same string/escape state. Same deltas, + same result: this is a memo, not a heuristic. + """ bracket_count = 0 brace_count = 0 - json_lines = [] in_string = False escaped = False for i in range(start, len(lines)): - line = lines[i] - json_lines.append(line) + key = (i, in_string, escaped) + step = cache.get(key) if cache is not None else None + if step is None: + step = _scan_line(lines[i], in_string, escaped) + if cache is not None: + cache[key] = step + d_bracket, d_brace, in_string, escaped = step + bracket_count += d_bracket + brace_count += d_brace - for ch in line: - if escaped: - escaped = False - continue - if ch == "\\": - if in_string: - escaped = True - continue - if ch == '"': - in_string = not in_string - continue - if in_string: - continue - if ch == "[": - bracket_count += 1 - elif ch == "]": - bracket_count -= 1 - elif ch == "{": - brace_count += 1 - elif ch == "}": - brace_count -= 1 - - if bracket_count <= 0 and brace_count <= 0 and json_lines: - return "\n".join(json_lines), i + if bracket_count <= 0 and brace_count <= 0: + return "\n".join(lines[start : i + 1]), i return None, start diff --git a/tests/test_cost_tracker_totals.py b/tests/test_cost_tracker_totals.py new file mode 100644 index 000000000..ec7108487 --- /dev/null +++ b/tests/test_cost_tracker_totals.py @@ -0,0 +1,80 @@ +"""CostTracker.totals() must be stats() minus the work, not minus the accuracy. + +It exists only so the per-request metrics path stops walking 31 days of cost +records to read two fields. If the two ever disagree, the savings history +silently drifts from /stats. +""" + +from __future__ import annotations + +import random + +import pytest + +from headroom.proxy.cost import CostTracker + + +def _tracker(seed: int, n_models: int, n_requests: int) -> CostTracker: + r = random.Random(seed) + tracker = CostTracker() + models = [ + "claude-sonnet-5", + "claude-opus-4-1", + "gpt-4o", + "gpt-4o-mini", + "some-unpriceable-model", + ][:n_models] + for _ in range(n_requests): + model = r.choice(models) + sent = r.randint(0, 20000) + # Alternate between requests that carry an API cache breakdown and ones + # that do not — totals() has a branch for each, and only the second + # falls back to list price. + with_cache = r.random() < 0.5 + tracker.record_tokens( + model=model, + tokens_saved=r.randint(0, 5000), + tokens_sent=sent, + cache_read_tokens=r.randint(0, sent) if with_cache else 0, + cache_write_tokens=r.randint(0, 500) if with_cache else 0, + uncached_tokens=r.randint(0, sent) if with_cache else 0, + output_tokens=r.randint(0, 2000), + ) + return tracker + + +@pytest.mark.parametrize( + ("n_models", "n_requests"), + [(0, 0), (1, 1), (1, 50), (3, 200), (5, 500)], +) +def test_totals_matches_stats(n_models: int, n_requests: int) -> None: + tracker = _tracker(seed=n_models * 100 + n_requests, n_models=n_models, n_requests=n_requests) + stats = tracker.stats() + assert tracker.totals() == ( + stats["total_input_tokens"], + stats["total_input_cost_usd"], + ) + + +def test_totals_matches_stats_on_a_fresh_tracker() -> None: + tracker = CostTracker() + stats = tracker.stats() + assert tracker.totals() == (stats["total_input_tokens"], stats["total_input_cost_usd"]) + + +def test_totals_does_not_walk_the_cost_records() -> None: + """The point of the method: no period_cost_breakdown, at any ledger size.""" + tracker = _tracker(seed=7, n_models=3, n_requests=100) + called = False + real = tracker.period_cost_breakdown + + def spy(*a, **kw): + nonlocal called + called = True + return real(*a, **kw) + + tracker.period_cost_breakdown = spy # type: ignore[method-assign] + tracker.totals() + assert not called, "totals() still walks the cost records" + tracker.stats() + assert called, "stats() should still report budget_basis" diff --git a/tests/test_kompress_download_backoff.py b/tests/test_kompress_download_backoff.py new file mode 100644 index 000000000..538413c14 --- /dev/null +++ b/tests/test_kompress_download_backoff.py @@ -0,0 +1,116 @@ +"""An unreachable HuggingFace must not turn every request into a download thread. + +The request path calls ensure_background_download() on every Kompress miss. A +finished-or-failed thread is replaced on the next call, which is what lets a +transient blip recover — but with no floor, a permanently unreachable Hub means +one new thread per request forever, each importing transformers and holding the +GIL against the event loop. +""" + +from __future__ import annotations + +import threading + +import pytest + +from headroom.transforms import kompress_compressor as kc + + +@pytest.fixture(autouse=True) +def _clean_registry(): + with kc._download_threads_lock: + kc._download_threads.clear() + kc._download_failures.clear() + yield + with kc._download_threads_lock: + kc._download_threads.clear() + kc._download_failures.clear() + + +def _spawned(monkeypatch, *, fails: bool) -> list[str]: + """Run ensure_background_download with the real load stubbed out.""" + started: list[str] = [] + + def fake_load(model_id, device, allow_download=True): + started.append(model_id) + if fails: + raise OSError("hub unreachable") + return object(), object(), "onnx" + + monkeypatch.setattr(kc, "_load_kompress", fake_load) + return started + + +def _drain(): + for t in list(kc._download_threads.values()): + t.join(timeout=10) + + +def test_repeated_failure_stops_spawning_threads(monkeypatch): + started = _spawned(monkeypatch, fails=True) + for _ in range(25): + kc.ensure_background_download("some/model") + _drain() + assert len(started) < 25, f"no backoff: spawned {len(started)} downloads for 25 calls" + assert len(started) >= 1, "never even tried once" + + +def test_backoff_window_elapsing_allows_another_attempt(monkeypatch): + started = _spawned(monkeypatch, fails=True) + kc.ensure_background_download("some/model") + _drain() + assert len(started) == 1 + + kc.ensure_background_download("some/model") + _drain() + assert len(started) == 1, "retried inside the backoff window" + + # Rewind the clock past the window instead of sleeping through it. + with kc._download_threads_lock: + failures, _ = kc._download_failures["some/model"] + kc._download_failures["some/model"] = (failures, 0.0) + kc.ensure_background_download("some/model") + _drain() + assert len(started) == 2, "backoff never expires" + + +def test_success_clears_the_backoff(monkeypatch): + _spawned(monkeypatch, fails=False) + kc.ensure_background_download("some/model") + _drain() + assert "some/model" not in kc._download_failures + + +def test_window_grows_with_consecutive_failures(): + kc._download_failures["m"] = (1, 0.0) + assert kc._DOWNLOAD_RETRY_BASE_SECONDS == 5.0 + # Same last-attempt time, more failures -> still blocked at a later clock. + import time as _t + + now = _t.monotonic() + kc._download_failures["m"] = (1, now) + with kc._download_threads_lock: + first = kc._download_retry_blocked("m") + kc._download_failures["m"] = (6, now) + with kc._download_threads_lock: + later = kc._download_retry_blocked("m") + assert first and later + + +def test_a_live_thread_is_never_duplicated(monkeypatch): + gate = threading.Event() + started: list[str] = [] + + def slow_load(model_id, device, allow_download=True): + started.append(model_id) + gate.wait(timeout=10) + return object(), object(), "onnx" + + monkeypatch.setattr(kc, "_load_kompress", slow_load) + for _ in range(10): + kc.ensure_background_download("some/model") + try: + assert len(started) == 1 + finally: + gate.set() + _drain() diff --git a/tests/test_mixed_content_scan_cache.py b/tests/test_mixed_content_scan_cache.py new file mode 100644 index 000000000..a0dd22625 --- /dev/null +++ b/tests/test_mixed_content_scan_cache.py @@ -0,0 +1,197 @@ +"""The memoised JSON-block scan must be indistinguishable from the original. + +This is a parser change, so equality is checked against a literal transcription +of the pre-cache implementation rather than against expected values — a golden +test would only encode whatever the new code does. +""" + +from __future__ import annotations + +import json +import random + +import pytest + +from headroom.transforms.mixed_content import ( + _extract_json_block, + _has_valid_json_block_with_text, + is_mixed_content, + split_into_sections, +) + + +def _extract_json_block_original(lines: list[str], start: int) -> tuple[str | None, int]: + """Verbatim pre-cache implementation, kept as the oracle.""" + bracket_count = 0 + brace_count = 0 + json_lines = [] + in_string = False + escaped = False + + for i in range(start, len(lines)): + line = lines[i] + json_lines.append(line) + + for ch in line: + if escaped: + escaped = False + continue + if ch == "\\": + if in_string: + escaped = True + continue + if ch == '"': + in_string = not in_string + continue + if in_string: + continue + if ch == "[": + bracket_count += 1 + elif ch == "]": + bracket_count -= 1 + elif ch == "{": + brace_count += 1 + elif ch == "}": + brace_count -= 1 + + if bracket_count <= 0 and brace_count <= 0 and json_lines: + return "\n".join(json_lines), i + + return None, start + + +def _corpus() -> list[str]: + r = random.Random(20260806) + out = [ + "", + "\n", + " \n\t\n", + "{", + "}", + '{"a": 1}', + '[\n{"id": 1}\n]', + '{"s": "a ] b } c"}', # delimiters inside strings + '{"s": "escaped \\" quote }"}', # escaped quote + '{"s": "trailing backslash \\\\"}', + '{"s": "line one\\', # line ends mid-escape + 'text before\n{"a": 1}\ntext after', + '```json\n{"a": 1}\n```\nprose here', + "\n".join(f'{{ level: "info", seq: {i}, msg: "x"' for i in range(40)), # never balances + "\n".join(json.dumps({"id": i})[:9] for i in range(40)), # truncated JSONL + "\n".join(json.dumps({"id": i, "m": "ok"}) for i in range(40)), # valid JSONL + json.dumps([{"id": i, "n": f"x{i}"} for i in range(40)], indent=2), + "\n".join(f"2026-08-06 13:00:{i % 60:02d} INFO did thing {i}" for i in range(40)), + "\n".join(f" cfg = {{'k{i}': 'v{i}'," for i in range(40)), + ] + # Randomised mixtures, including unbalanced and string-heavy fragments. + frags = [ + '{"a": 1}', + "[", + "]", + "{", + "}", + "plain prose line", + '{"s": "] } ["}', + '{"x": "\\\\"}', + "", + " ", + '{ unquoted: "value"', + "```", + "path/to/f.py:12: hit", + ] + for _ in range(120): + out.append("\n".join(r.choice(frags) for _ in range(r.randint(1, 30)))) + return out + + +CORPUS = _corpus() + + +@pytest.mark.parametrize("content", CORPUS, ids=range(len(CORPUS))) +def test_every_candidate_index_matches_the_original(content: str) -> None: + lines = content.split("\n") + shared: dict = {} + for i in range(len(lines)): + expected = _extract_json_block_original(lines, i) + # Both with a cold cache and with the shared one the real callers use, + # since a stale entry would only show up on the second path. + assert _extract_json_block(lines, i) == expected, f"cold cache, line {i}" + assert _extract_json_block(lines, i, cache=shared) == expected, f"shared cache, line {i}" + assert _extract_json_block(lines, i, cache=shared) == expected, f"replayed, line {i}" + + +@pytest.mark.parametrize("content", CORPUS, ids=range(len(CORPUS))) +def test_public_behaviour_is_unchanged(content: str) -> None: + """The three functions built on the scan must agree with the oracle.""" + lines = content.split("\n") + + def oracle_has_json_with_text() -> bool: + for index, line in enumerate(lines): + if not line.strip().startswith(("[", "{")): + continue + block, end_index = _extract_json_block_original(lines, index) + if block is None: + continue + try: + json.loads(block) + except (TypeError, ValueError): + continue + if "\n".join(lines[:index]).strip() or "\n".join(lines[end_index + 1 :]).strip(): + return True + return False + + assert _has_valid_json_block_with_text(content) == oracle_has_json_with_text() + # split_into_sections must partition the content exactly as before. + sections = split_into_sections(content) + assert [(s.content, s.content_type, s.start_line, s.end_line) for s in sections] == [ + (s.content, s.content_type, s.start_line, s.end_line) for s in split_into_sections(content) + ] + is_mixed_content(content) # must not raise + + +def test_each_line_is_scanned_once_per_state(monkeypatch) -> None: + """The memo's actual guarantee, asserted without timing. + + Character scanning happens at most twice per (line, entry-state) pair: once + during the first scan, which runs uncached because nothing has yet shown the + content to be pathological, and once more while populating the cache. Before + the memo it happened once per (candidate, line) pair, which is what made this + shape quadratic in *character* work. + + This remains a constant-factor win — the walk over remaining lines is still + O(candidates x lines) — so the assertion counts scans, not wall time. + """ + from collections import Counter + + from headroom.transforms import mixed_content as mc + + calls: list[tuple[str, bool, bool]] = [] + real = mc._scan_line + + def counting(line, in_string, escaped): + calls.append((line, in_string, escaped)) + return real(line, in_string, escaped) + + monkeypatch.setattr(mc, "_scan_line", counting) + + n = 400 + body = "\n".join(f'{{ level: "info", seq: {i}, msg: "did a thing"' for i in range(n)) + mc.split_into_sections(body) + + worst = max(Counter(calls).values()) + assert worst <= 2, f"a (line, state) pair was scanned {worst} times" + # Without the memo this shape scans on the order of n^2/2 = 80,000 times. + assert len(calls) <= 3 * n, f"{len(calls)} scans for {n} lines" + + +def test_pathological_shape_stays_within_a_sane_budget() -> None: + """Absolute smoke check: this input took 2.4s before the memo.""" + import time + + body = "\n".join(f'{{ level: "info", seq: {i}, msg: "did a thing"' for i in range(1600)) + best = float("inf") + for _ in range(3): + start = time.perf_counter() + split_into_sections(body) + best = min(best, time.perf_counter() - start) + assert best < 1.5, f"{best:.2f}s for 1600 lines; was 2.4s before the scan memo" diff --git a/tests/test_proxy_eager_preload_bind.py b/tests/test_proxy_eager_preload_bind.py index 6f01a6981..a5923ca6a 100644 --- a/tests/test_proxy_eager_preload_bind.py +++ b/tests/test_proxy_eager_preload_bind.py @@ -91,8 +91,15 @@ def test_eager_preload_dedupes_and_swallows_failures(): eager_status, statuses = proxy._eager_preload_transforms() - assert eager_status == {"shared": "enabled", "kompress": "enabled"} + # Keys the preload contributes itself rather than collecting from a + # transform, so this assertion stays about dedupe/swallowing. + non_transform_keys = {"litellm"} + assert {k: v for k, v in eager_status.items() if k not in non_transform_keys} == { + "shared": "enabled", + "kompress": "enabled", + } assert statuses == [{"shared": "enabled"}, {"kompress": "enabled"}] + assert eager_status["litellm"] in {"ready", "not installed", "skipped"} async def test_startup_binds_despite_hung_preload(monkeypatch): diff --git a/tests/test_token_count_cache.py b/tests/test_token_count_cache.py new file mode 100644 index 000000000..c90427870 --- /dev/null +++ b/tests/test_token_count_cache.py @@ -0,0 +1,108 @@ +"""The token-count memo must be invisible: same integers, or it is a bug. + +These counts feed context_pressure -> min_ratio -> which blocks get compressed, +so "the cache returned a different number" is a compression regression, not a +cache miss. Every test here is an equality test for that reason. +""" + +from __future__ import annotations + +import json + +import pytest + +from headroom.providers.anthropic import AnthropicProvider +from headroom.tokenizers.base import TokenCountCache +from headroom.tokenizers.estimator import EstimatingTokenCounter +from headroom.tokenizers.tiktoken_counter import TiktokenCounter + +BODIES = [ + "word " * 500, + json.dumps([{"id": i, "name": f"item-{i}", "ok": i % 2 == 0} for i in range(300)]), + "def f(x):\n return x + 1\n" * 200, + "2026-08-06 13:00:00 INFO worker did a thing\n" * 400, + "日本語のテキストをここに置きます。" * 200, + "<|endoftext|> literal special token marker " * 100, # forces the ValueError path + "x" * 300, +] + + +def _counters(): + return [ + ("anthropic", AnthropicProvider().get_token_counter("claude-sonnet-5")), + ("tiktoken", TiktokenCounter(model="gpt-4o")), + ("estimator-auto", EstimatingTokenCounter()), + ("estimator-fixed", EstimatingTokenCounter(chars_per_token=3.5)), + ] + + +@pytest.mark.filterwarnings("ignore::UserWarning") +@pytest.mark.parametrize("body", BODIES) +def test_cached_count_equals_uncached(body: str) -> None: + for name, counter in _counters(): + counter._count_cache.clear() + first = counter.count_text(body) # miss, populates + second = counter.count_text(body) # hit + counter._count_cache.clear() + third = counter.count_text(body) # miss again + assert first == second == third, f"{name}: {first} != {second} != {third}" + + +@pytest.mark.filterwarnings("ignore::UserWarning") +def test_empty_and_tiny_text_still_correct() -> None: + for _name, counter in _counters(): + assert counter.count_text("") == 0 + assert counter.count_text("hi") == counter.count_text("hi") + + +def test_cache_clears_when_full_rather_than_growing() -> None: + cache = TokenCountCache(min_chars=1, max_entries=4, max_chars=10**9) + for i in range(10): + cache.put(f"text-number-{i}", i) + assert len(cache._counts) <= 4 + + +def test_cache_respects_the_character_budget() -> None: + cache = TokenCountCache(min_chars=1, max_entries=10**6, max_chars=1000) + for i in range(50): + cache.put("x" * 100 + str(i), i) + assert cache._chars <= 1000 + 200 # one entry may straddle the cap + + +def test_small_strings_are_not_cached() -> None: + """They encode in microseconds; caching them would evict the entries that matter.""" + cache = TokenCountCache(min_chars=256) + cache.put("short", 1) + assert cache.get("short") is None + + +def test_distinct_texts_do_not_collide() -> None: + cache = TokenCountCache(min_chars=1) + cache.put("alpha", 1) + cache.put("beta", 2) + assert (cache.get("alpha"), cache.get("beta"), cache.get("gamma")) == (1, 2, None) + + +@pytest.mark.filterwarnings("ignore::UserWarning") +def test_counters_do_not_share_a_cache_across_encodings() -> None: + """cl100k and o200k are both live in one process; a shared memo would mix them.""" + a = TiktokenCounter(encoding="cl100k_base") + b = TiktokenCounter(encoding="o200k_base") + body = "tokenization differs between these two encodings. " * 100 + assert a.count_text(body) == a.count_text(body) + assert b.count_text(body) == b.count_text(body) + assert a._count_cache is not b._count_cache + + +@pytest.mark.filterwarnings("ignore::UserWarning") +def test_concurrent_counting_is_consistent() -> None: + """The pipeline runs on a thread pool and shares one counter.""" + from concurrent.futures import ThreadPoolExecutor + + counter = AnthropicProvider().get_token_counter("claude-sonnet-5") + bodies = [f"{b}\n{i}" for i, b in enumerate(BODIES * 3)] + expected = {b: counter.count_text(b) for b in bodies} + counter._count_cache.clear() + with ThreadPoolExecutor(max_workers=8) as pool: + got = list(pool.map(counter.count_text, bodies)) + assert got == [expected[b] for b in bodies] From 4ec416df8899036544e679f561f1cf921f3da0dd Mon Sep 17 00:00:00 2001 From: Ashish Patel Date: Fri, 7 Aug 2026 07:51:49 +0530 Subject: [PATCH 007/138] fix(proxy): stop discarding compressed Codex WS later-frame payloads (#2823) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `headroom perf` reports 0 tokens saved for Codex CLI sessions despite real traffic being processed (confirmed via the reporter's live proxy stats in the issue). Root cause: a misplaced `return` statement in the Codex WS later-frame compression path silently discards every compressed payload and skips all token/savings bookkeeping for it. Closes #2819 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/proxy/handlers/openai.py` (`_maybe_compress_response_create_frame`): PR #1579 (2026-07-16) moved a `return (raw_after_store, ...)` statement to the same indentation as the enclosing `except Exception:` block instead of inside it. That made the `return` fire **unconditionally** after every later (2nd+) `response.create` frame in a Codex WS session — success or failure — always forwarding the original pre-compression frame upstream and skipping the entire success-path code below it (correct rewritten-payload return, `tokens_saved`, `attempted_input_tokens_total`, `ws_frames_compressed`). Fixed by moving the `return` back inside the `except` block, restoring the success path. - `tests/test_openai_codex_ws_lifecycle.py`: new regression test `test_ws_later_frame_compression_is_actually_forwarded` — mocks the compressor to report `modified=True` with a distinct rewritten payload on a later frame, asserts the rewritten payload (not the original) is what's actually sent upstream. ## Testing - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) — not run locally, will confirm via CI - [ ] Type checking passes (`mypy headroom`) — not run locally, will confirm via CI - [x] New tests added for new functionality - [x] Manual testing performed (see Real Behavior Proof) ### Test Output ```text $ .venv/Scripts/python -m pytest tests/test_openai_codex_ws_lifecycle.py tests/test_codex_ws_per_frame_memory.py tests/test_codex_ws_savings_deferral.py tests/test_openai_codex_ws_timings.py -q ............................................... 48 passed in 5.34s $ .venv/Scripts/python -m pytest tests/ -k "openai or codex" -q (wider sweep, unrelated dirs excluded) 968 passed, 3 failed, 77 skipped, 2 errors in 483.21s ``` The 3 failures (`test_client_integration.py::test_auto_detect_openai_optimizer`, `test_compress_route_tokenizer_by_model.py::...[deepseek/deepseek-v4]`, `test_learn/test_integration.py::TestCodexIntegration::test_full_pipeline`) reproduce identically on a clean, unmodified `main` — confirmed by stashing this PR's changes and re-running. They're local-environment issues (a live litellm 503, and this dev box's tool registry missing a `Bash` entry), not caused by this change. ## Real Behavior Proof - Environment: Windows 11, Python 3.14.5, local venv, `headroom._core` rebuilt via `maturin develop --release` against current `main` to rule out stale-build noise - Exact command / steps: (1) `git blame` on the buggy block traced the misplaced `return` to commit `1c50eca8` (PR #1579); (2) wrote a regression test that scripts two `response.create` frames over a fake Codex WS session, with the compressor mock returning `modified=False` for frame 1 and `modified=True` (with a distinct payload) for frame 2; (3) ran the test against the pre-fix code (`git stash` isolating just the source fix, keeping the test) — **failed**, `upstream.sent[-1]` was the untouched original frame; (4) ran the test against the fix — **passed**, `upstream.sent[-1]` is the compressed payload; (5) added a further regression test for the later-frame non-timeout-exception path Codecov flagged as uncovered, confirmed `pytest tests/test_openai_codex_ws_lifecycle.py -q` passes 32/32 - Observed result: confirmed the bug exists and the fix resolves it, at the unit level - Not tested: have not reproduced the full `headroom wrap codex` → `headroom perf` end-to-end flow against a live Codex CLI session (no access to Codex CLI / real OpenAI credentials in this environment) — root cause and fix are verified at the code-path level via the regression test above, not via the reporter's exact repro steps ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation (N/A — internal bugfix, no user-facing behavior/docs change beyond "compression now works as originally intended") - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable (release-please generates this automatically from commit messages) ## Additional Notes **Bonus finding, not just a metrics bug**: because the compressed payload was discarded and the original was always sent, this also means Codex WS sessions with multiple turns were silently getting **zero compression benefit** past the first `response.create` frame — not just wrong dashboards. The fix restores actual compression for those turns, not only correct accounting of it. --- headroom/proxy/handlers/openai.py | 10 +- tests/test_openai_codex_ws_lifecycle.py | 125 ++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 5 deletions(-) diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py index 9ee4c260b..59945befd 100644 --- a/headroom/proxy/handlers/openai.py +++ b/headroom/proxy/handlers/openai.py @@ -7086,6 +7086,11 @@ class OpenAIHandlerMixin: frame_type="response.create", model=str(inner_payload.get("model") or "unknown"), ) + return ( + raw_after_store, + store_forced, + "chatgpt_store_false" if store_forced else "compression_exception", + ) # Record transform labels even when the frame bytes are # unchanged: control-arm output-shaper labels # (output_shaper:control:*) must reach the outcome @@ -7093,11 +7098,6 @@ class OpenAIHandlerMixin: for t in frame_transforms: if t not in transforms_applied: transforms_applied.append(t) - return ( - raw_after_store, - store_forced, - "chatgpt_store_false" if store_forced else "compression_exception", - ) if not modified: reason = frame_reason or "no_compression" _log_ws_passthrough( diff --git a/tests/test_openai_codex_ws_lifecycle.py b/tests/test_openai_codex_ws_lifecycle.py index 40d54680a..481496b4e 100644 --- a/tests/test_openai_codex_ws_lifecycle.py +++ b/tests/test_openai_codex_ws_lifecycle.py @@ -588,6 +588,131 @@ async def test_ws_first_frame_non_timeout_exception_keeps_generic_reason( assert "reason=compression_exception" in caplog.text +@pytest.mark.asyncio +async def test_ws_later_frame_compression_is_actually_forwarded(monkeypatch): + """Regression for issue #2819: a later (2nd+) Codex WS response.create + frame whose compressor reports ``modified=True`` must have the REWRITTEN + payload sent upstream — not the original raw frame. + + A misplaced ``return`` (introduced in #1579) sat at the same indentation + as the surrounding ``except`` block, so it fired unconditionally after + every later-frame compression attempt — success or failure — and always + forwarded ``raw_after_store`` (the pre-compression frame). Compressed + later frames were silently discarded on the wire, and the token/savings + accounting that only runs on the (dead) success path never accumulated, + which is why ``headroom perf`` showed 0 tokens for Codex sessions with + multiple turns. + """ + second_frame = _first_frame() + upstream = _FakeUpstream([], hold_after_events=True) + fake_ws_mod = _make_fake_websockets_module(upstream) + + client_ws = _FakeWebSocket( + frames=[_first_frame(), second_frame], + hold_after_initial=True, + disconnect_after_n_sends=None, + ) + handler = _DummyOpenAIHandler() + handler.config.optimize = True + monkeypatch.setattr(openai_module, "COMPRESSION_TIMEOUT_SECONDS", 30.0) + + compressed_inner = {"model": "gpt-5.4", "input": "compressed"} + calls = 0 + + def _compress(payload, *, model, request_id, timing=None, client=None): + nonlocal calls + calls += 1 + if calls == 1: + # First frame: not modified (exercises the other call site). + return payload, False, 0, [], "router_no_compression", 10, 10, 0 + # Later frame: compressor DID find savings. + return compressed_inner, True, 5, ["text"], "compressed", 10, 5, 10 + + async def _trigger() -> None: + await asyncio.sleep(0.05) + client_ws.trigger_disconnect() + + handler._compress_openai_responses_payload = _compress # type: ignore[method-assign] + + with patch.dict(sys.modules, {"websockets": fake_ws_mod}): + trigger_task = asyncio.create_task(_trigger()) + try: + await asyncio.wait_for(handler.handle_openai_responses_ws(client_ws), timeout=2.0) + finally: + trigger_task.cancel() + try: + await trigger_task + except asyncio.CancelledError: + pass + + # The compressed payload must reach upstream for the later frame — not + # the untouched original second_frame. + assert upstream.sent[-1] != second_frame + assert json.loads(upstream.sent[-1])["response"] == compressed_inner + + # The success-path bookkeeping (tokens_saved / frame count) must run — + # proof the "modified" branch executed rather than short-circuiting. + modified_frames = [frame for frame in handler.metrics.codex_ws_frames if frame.get("modified")] + assert modified_frames, "expected at least one frame recorded as modified=True" + + +@pytest.mark.asyncio +async def test_ws_later_frame_non_timeout_exception_falls_back_to_original(caplog, monkeypatch): + """A non-timeout compression exception on a later frame must forward the + original frame via the except-block return (the line this PR moved back + inside the except), not fall through to the (now correctly gated) + success-path handling below it. + """ + second_frame = _first_frame() + upstream = _FakeUpstream([], hold_after_events=True) + fake_ws_mod = _make_fake_websockets_module(upstream) + + client_ws = _FakeWebSocket( + frames=[_first_frame(), second_frame], + hold_after_initial=True, + ) + handler = _DummyOpenAIHandler() + handler.config.optimize = True + monkeypatch.setattr(openai_module, "COMPRESSION_TIMEOUT_SECONDS", 30.0) + + calls = 0 + + async def _run(fn, *, timeout: float): + nonlocal calls + calls += 1 + handler.compression_executor_calls += 1 + handler.compression_executor_timeouts.append(timeout) + if calls == 2: + raise RuntimeError("simulated later-frame compression failure") + return fn() + + def _noop_compress(payload, *, model, request_id, timing=None, client=None): + return payload, False, 0, [], "test_noop", 10, 10, 0 + + async def _trigger() -> None: + await asyncio.sleep(0.05) + client_ws.trigger_disconnect() + + handler._compress_openai_responses_payload = _noop_compress # type: ignore[method-assign] + handler._run_compression_in_executor = _run # type: ignore[method-assign] + caplog.set_level(logging.INFO, logger="headroom.proxy") + + with patch.dict(sys.modules, {"websockets": fake_ws_mod}): + trigger_task = asyncio.create_task(_trigger()) + try: + await asyncio.wait_for(handler.handle_openai_responses_ws(client_ws), timeout=2.0) + finally: + trigger_task.cancel() + try: + await trigger_task + except asyncio.CancelledError: + pass + + # The failed later frame must forward the original, unmodified frame. + assert upstream.sent[-1] == second_frame + assert "reason=compression_exception" in caplog.text + + @pytest.mark.asyncio async def test_ws_later_frame_timeout_records_failed_frame(caplog, monkeypatch): """Later Codex WS compression timeout records failed frame metrics.""" From 01161fe019137baa871449dde334130c16ceb19f Mon Sep 17 00:00:00 2001 From: JD Davis Date: Thu, 6 Aug 2026 21:21:52 -0500 Subject: [PATCH 008/138] test(openclaw): match inherited PATH shell check (#2821) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Fix the OpenClaw test failure on `main` by aligning its PATH-launcher expectation with the intentionally shipped `sh -c` behavior from #1459. The non-login shell preserves the PATH inherited from the OpenClaw process. Changing production code back to `sh -lc` would risk a login shell resetting that PATH and would undo the compatibility fix. This PR therefore corrects only the stale assertion; runtime behavior and defaults do not change. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Expect `sh -c` for the non-Windows lightweight `command -v headroom` check. - Preserve the existing Windows `where.exe` behavior and all launcher behavior. ## Testing - [x] Unit tests pass (`npm test`) - [x] Linting passes (`npm run typecheck`) - [x] Type checking passes (`npm run typecheck`) - [ ] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ npm test Test Files 6 passed (6) Tests 75 passed (75) $ npm run typecheck > tsc --noEmit $ npm run build ESM Build success DTS Build success $ npm ci found 0 vulnerabilities ``` ## Real Behavior Proof - Environment: macOS, Node/npm, clean install from `origin/main` at `2954e37048f8dcffe16e1c37b8f71afb0094a0a2`. - Exact command / steps: `cd plugins/openclaw && npm ci && npm test && npm run typecheck && npm run build`. - Observed result: all 75 OpenClaw tests pass, TypeScript typechecking succeeds, and both ESM and declaration builds succeed. - Not tested: Windows execution; its separate `where.exe` expectation and implementation are unchanged. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A — test-only correction with no UI changes. ## Additional Notes History confirms #1459 deliberately changed `sh -lc` to `sh -c` while adding explicit uv-tool path detection. Reverting the implementation would change runtime discovery semantics; updating the stale test preserves the accepted behavior. Co-authored-by: JD Davis --- plugins/openclaw/test/proxy-manager.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/openclaw/test/proxy-manager.test.ts b/plugins/openclaw/test/proxy-manager.test.ts index 600ce268c..02f7302bc 100644 --- a/plugins/openclaw/test/proxy-manager.test.ts +++ b/plugins/openclaw/test/proxy-manager.test.ts @@ -364,7 +364,7 @@ describe("ProxyManager launch internals", () => { expect(pathSpec.checkUseShell).toBe(false); } else { expect(pathSpec.checkCommand).toBe("sh"); - expect(pathSpec.checkArgs).toEqual(["-lc", "command -v headroom >/dev/null 2>&1"]); + expect(pathSpec.checkArgs).toEqual(["-c", "command -v headroom >/dev/null 2>&1"]); } }); From b97c7c6e99eac84df49c7a7e5f21dedb298716fe Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Fri, 7 Aug 2026 07:51:56 +0530 Subject: [PATCH 009/138] fix(proxy/gemini): keep streaming-parity baseline so eligible_pct can't exceed 100 (#2824) ## Description The non-streaming Gemini `generateContent` finalizer builds its `RequestOutcome` with `optimized_tokens` set to Gemini's own `promptTokenCount` (the provider's tokenizer scale, which correctly feeds billing and the dashboard), while `original_tokens` stays a local estimator count. Those two are on different rulers. Every delta the beacon derives from the pair is a same-ruler difference: `tokens_saved`, `tokens_inflated`, `attempted_input_tokens`, and the beacon's `eligible_pct` / `yield_pct`. When Gemini counts the forwarded prompt higher than our local estimator does, `attempted_input_tokens` (which is `optimized_tokens + tokens_saved`) exceeds the local `original_tokens`, and the request ships a structurally-impossible `eligible_pct > 100` plus a phantom `tokens_inflated`. This is the exact class of bug #2756 removed, on a path #2756 did not touch: it fixed the non-streaming OpenAI handler, and the streaming finalizer (`_finalize_stream_response`) already guards against it by lifting the baseline onto the provider scale. The non-streaming Gemini path had neither treatment. The fix mirrors the streaming finalizer's already-tested handling: when a provider count is present, lift the baseline to `max(original_tokens, promptTokenCount + tokens_saved)` so `attempted_input_tokens <= original_tokens` holds and `tokens_inflated` collapses to 0. It is guarded on a present count, so a null or absent `promptTokenCount` leaves the local baseline untouched and the existing zero-usage preservation test still holds. `optimized_tokens` still carries the provider count, so billing and the dashboard are unchanged. Closes # ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/proxy/handlers/gemini.py` (`handle_gemini_request`, non-streaming `generateContent` branch): compute `effective_original_tokens = max(original_tokens, total_input_tokens + tokens_saved)` when `total_input_tokens > 0` (else keep `original_tokens`), and pass it as the outcome's `original_tokens`. Mirrors the streaming finalizer's provider-usage handling. - `tests/test_proxy/test_gemini_savings_profile.py`: added `test_gemini_provider_count_above_local_estimate_does_not_inflate_eligible`, which drives a request where Gemini's `promptTokenCount` (150) exceeds the local post-compression count (80), and asserts `attempted_input_tokens <= original_tokens`, `tokens_inflated == 0`, the provider count is still carried in `optimized_tokens`, and the baseline is lifted to 170. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Fail-before (source fix stashed, new test kept): tests/test_proxy/test_gemini_savings_profile.py::test_gemini_provider_count_above_local_estimate_does_not_inflate_eligible FAILED assert outcome.attempted_input_tokens <= outcome.original_tokens AssertionError: assert 170 <= 100 # Pass-after (fix applied): tests/test_proxy/test_gemini_savings_profile.py::test_gemini_provider_count_above_local_estimate_does_not_inflate_eligible PASSED # Full file + related outcome suites: tests/test_proxy/test_gemini_savings_profile.py tests/test_proxy_gemini_native_integration.py tests/test_request_outcome.py tests/test_outcome_token_scale.py 47 passed, 18 skipped # uvx ruff@0.15.17 check -> All checks passed! # uvx mypy@1.20.2 headroom/proxy/handlers/gemini.py -> Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12.11, project venv (litellm installed), pytest 9.1.1 with pytest-asyncio 1.4.0 (asyncio_mode=auto per pyproject), ruff 0.15.17 and mypy 1.20.2 via uvx. - Exact command / steps: confirmed the streaming sibling already lifts the baseline (`_finalize_stream_response` in `headroom/proxy/handlers/streaming.py` sets `effective_original_tokens = max(original_tokens, provider_input_tokens + tokens_saved)` for openai/gemini), then fail-before with `git stash push headroom/proxy/handlers/gemini.py` and `python -m pytest tests/test_proxy/test_gemini_savings_profile.py -k inflate_eligible` (the assertion fails with `170 <= 100`, i.e. eligible_pct 170%), then pass-after with `git stash pop` and rerunning (passes), then the full file plus the outcome suites (47 passed, 18 skipped). - Observed result: with Gemini reporting `promptTokenCount=150` against a local post-compression count of 80 (saved 20), the outcome now reports `original_tokens=170`, `attempted_input_tokens=170` (so `eligible_pct <= 100`) and `tokens_inflated=0`, while `optimized_tokens` stays 150 so billing and the dashboard are unchanged. Before the fix the same request reported `original_tokens=100`, `attempted_input_tokens=170` (eligible_pct 170%) and `tokens_inflated=50`. - Not tested: a live streamed call to real Gemini/Vertex (no provider credentials in this environment). The provider-count-above-local case is reproduced with a mock response mirroring Gemini's `usageMetadata` shape, and the baseline-lift it mirrors is existing, tested code on the streaming path. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`: it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes Docs and manual testing are N/A: this aligns the non-streaming Gemini finalizer with the already-correct streaming finalizer, no API surface change. The baseline lift is guarded on a present provider count, so the existing zero-usage preservation test (`test_gemini_zero_usage_prompt_count_is_preserved`) is unaffected: a null or zero `promptTokenCount` keeps the local baseline and leaves `optimized_tokens` at 0. --- headroom/proxy/handlers/gemini.py | 20 ++++- .../test_proxy/test_gemini_savings_profile.py | 73 +++++++++++++++++++ 2 files changed, 92 insertions(+), 1 deletion(-) diff --git a/headroom/proxy/handlers/gemini.py b/headroom/proxy/handlers/gemini.py index 199a79fd1..941d31bd3 100644 --- a/headroom/proxy/handlers/gemini.py +++ b/headroom/proxy/handlers/gemini.py @@ -738,6 +738,24 @@ class GeminiHandlerMixin: uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens) + # optimized_tokens carries Gemini's own promptTokenCount, which is + # on the provider's tokenizer scale (it feeds billing/dashboard), + # while original_tokens is a LOCAL estimator count. When Gemini + # counts the forwarded prompt higher than our estimator does, + # attempted_input_tokens (optimized + saved) exceeded the local + # original_tokens and shipped a structurally-impossible + # eligible_pct > 100 plus a phantom tokens_inflated. Lift the + # baseline onto the provider scale when a provider count is + # present, mirroring the streaming finalizer's tested handling in + # _finalize_stream_response so the two Gemini paths agree. Guarded + # on a present count so a null/absent promptTokenCount leaves the + # local baseline untouched. + effective_original_tokens = ( + max(original_tokens, total_input_tokens + tokens_saved) + if total_input_tokens > 0 + else original_tokens + ) + # Eligible-tracking is TODO for Gemini; pass the full # pre-compression request size as the fallback denominator. # This makes Gemini's contribution to the aggregate @@ -757,7 +775,7 @@ class GeminiHandlerMixin: provider=provider_name, model=model, status_code=response.status_code, - original_tokens=original_tokens, + original_tokens=effective_original_tokens, optimized_tokens=total_input_tokens, output_tokens=output_tokens, tokens_saved=tokens_saved, diff --git a/tests/test_proxy/test_gemini_savings_profile.py b/tests/test_proxy/test_gemini_savings_profile.py index bb67f91fc..21733f293 100644 --- a/tests/test_proxy/test_gemini_savings_profile.py +++ b/tests/test_proxy/test_gemini_savings_profile.py @@ -199,3 +199,76 @@ def test_gemini_zero_usage_prompt_count_is_preserved(): outcome = captured["outcome"] assert outcome.optimized_tokens == 0 assert outcome.uncached_input_tokens == 0 + + +def test_gemini_provider_count_above_local_estimate_does_not_inflate_eligible(): + """When Gemini's promptTokenCount exceeds our local estimate, the outcome must + not ship attempted_input_tokens > original_tokens (a structurally impossible + eligible_pct > 100) or a phantom tokens_inflated. The local baseline is lifted + onto the provider scale, matching the streaming finalizer's tested handling.""" + config = ProxyConfig( + optimize=True, + cache_enabled=False, + rate_limit_enabled=False, + cost_tracking_enabled=False, + ) + + # Local pipeline count: 100 tokens before compression, 80 after (saved 20). + # Return genuinely-changed messages so the handler adopts the pipeline's + # tokens_before/after (the override only fires when messages actually change). + def passthrough_apply(**kwargs): + sent = kwargs["messages"] + compressed = [dict(m) for m in sent] + if compressed: + compressed[0] = {**compressed[0], "content": "compressed"} + return SimpleNamespace( + messages=compressed, + transforms_applied=["gemini_compress"], + timing={}, + tokens_before=100, + tokens_after=80, + waste_signals=None, + ) + + # Gemini counts the forwarded prompt at 150 -- higher than our local 80, so + # attempted = 150 + 20 = 170 would exceed a local original of 100. + resp = MagicMock() + resp.status_code = 200 + resp.headers = {"content-type": "application/json"} + resp.content = ( + b'{"candidates":[{"content":{"parts":[{"text":"ok"}]}}],' + b'"usageMetadata":{"promptTokenCount":150,"candidatesTokenCount":2}}' + ) + resp.json.return_value = { + "candidates": [{"content": {"parts": [{"text": "ok"}]}}], + "usageMetadata": {"promptTokenCount": 150, "candidatesTokenCount": 2}, + } + + captured: dict[str, object] = {} + + async def recording_outcome(outcome): # noqa: ANN001 + captured["outcome"] = outcome + + big = "word " * 4000 + app = create_app(config) + with TestClient(app) as client: + proxy = client.app.state.proxy + proxy.openai_pipeline.apply = MagicMock(side_effect=passthrough_apply) + proxy._retry_request = AsyncMock(return_value=resp) + proxy._record_request_outcome = AsyncMock(side_effect=recording_outcome) + + r = client.post( + "/v1beta/models/gemini-2.0-flash:generateContent?key=test-key", + json={"contents": [{"parts": [{"text": big}]}]}, + ) + + assert r.status_code == 200, r.text + outcome = captured["outcome"] + # The provider's own count is still carried for billing/dashboard. + assert outcome.optimized_tokens == 150 + # The eligible ratio cannot exceed 100%: attempted must not exceed original. + assert outcome.attempted_input_tokens <= outcome.original_tokens + # No phantom growth (optimized - original clamped to >= 0 was 50 before). + assert outcome.tokens_inflated == 0 + # Baseline lifted onto the provider scale: max(local 100, provider 150 + saved 20). + assert outcome.original_tokens == 170 From 1f5fefffd3e82c73bddd928cfd53334031e807bc Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Fri, 7 Aug 2026 07:51:59 +0530 Subject: [PATCH 010/138] fix(memory): bound the TrafficLearner pending-pattern accumulator (memory leak) (#2579) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `TrafficLearner` (the memory/learning subsystem that accumulates patterns from proxy traffic) has an unbounded in-memory accumulator. `_pattern_counts` maps `content_hash -> (pattern, count)`. A pattern is added on first sighting, its count is bumped on each re-sighting, and it is **removed only when it reaches `min_evidence`** (default 5), at which point it is promoted and its hash moves to `_saved_hashes`: ```python if h in self._pattern_counts: existing, count = self._pattern_counts[h] count += 1 self._pattern_counts[h] = (existing, count) else: self._pattern_counts[h] = (pattern, 1) return # first sighting — wait for more evidence ... if count >= self._min_evidence: del self._pattern_counts[h] # only removal path self._saved_hashes.add(h) if len(self._saved_hashes) > self._dedup_window: # sibling IS trimmed self._saved_hashes.pop() ``` A pattern seen **once but never corroborated** — the common case for one-off traffic (a unique error string, an ad-hoc shell command, a distinct file path) — never reaches `min_evidence`, so it is **never removed**. Over a long-lived proxy processing varied traffic, `_pattern_counts` grows without bound and RSS climbs. The sibling `_saved_hashes` is explicitly trimmed to `dedup_window` ("prevent unbounded growth"); `_pattern_counts` was missed. Reproduced directly: feeding 500 distinct one-off patterns leaves 500 entries in `_pattern_counts` (one per pattern, forever). ## Fix Make `_pattern_counts` an LRU-ordered `OrderedDict` capped at a new `max_pending_patterns` (default 2048): - On each corroboration, `move_to_end(h)` so an actively-accumulating pattern stays "fresh" and is never evicted before it can be promoted. - On a first sighting when the accumulator is full, evict the least-recently-corroborated pending entry (`popitem(last=False)`). Evicting a stale one-off is safe: if it recurs it simply restarts accumulation (delayed promotion at worst) — the same tradeoff `_saved_hashes` already makes. Promotion at `min_evidence` is unchanged, and the cap (2048) is generous enough that any pattern receiving repeat sightings within a normal window reaches `min_evidence=5` long before eviction. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature - [ ] Breaking change - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring ## Changes Made - `headroom/memory/traffic_learner.py`: `_pattern_counts` becomes a capped LRU `OrderedDict`; add `max_pending_patterns` (default 2048); `move_to_end` on corroboration and evict-oldest on overflow. - `tests/test_memory/test_traffic_learner.py`: a regression that 500 one-off patterns keep the accumulator at its cap, and one that a corroborated pattern still promotes into `_saved_hashes` (both sync via `asyncio.run` so they run without the pytest-asyncio plugin). ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text $ python -m pytest tests/test_memory/test_traffic_learner.py -q 35 failed, 109 passed # the 35 failures are pre-existing @pytest.mark.asyncio tests that need # pytest-asyncio (not configured in this environment); they fail identically # on clean main (35 failed, 107 passed) and pass in CI. My two new tests are # synchronous and pass; they add +2 passing with no new failures. # with the fix reverted, test_pending_accumulator_is_bounded fails # (the accumulator holds all 500 one-off patterns) $ uvx ruff@0.15.17 check headroom/memory/traffic_learner.py tests/test_memory/test_traffic_learner.py All checks passed! $ uvx mypy@1.20.2 --ignore-missing-imports headroom/memory/traffic_learner.py Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12, project venv (`uv sync --extra proxy`), `uvx ruff@0.15.17` / `uvx mypy@1.20.2`, pytest in the venv. - Exact command / steps: built a `TrafficLearner(backend=None, min_evidence=5, max_pending_patterns=8)` and drove `_accumulate` with 500 distinct one-off `ExtractedPattern`s; separately corroborated one pattern to `min_evidence`; then reverted the source and re-ran. - Observed result: with the fix `len(_pattern_counts)` stays at the cap (8) after 500 one-offs, the corroborated pattern is removed from pending and present in `_saved_hashes`, and an actively-bumped pattern survives LRU eviction; with the fix reverted the accumulator holds all 500 one-off entries (the unbounded leak). Ran against the actual module. - Not tested: a live multi-day proxy run measuring RSS (the leak is inferred from the removed unbounded-growth path; the accumulator bound is verified directly). ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable --- headroom/memory/traffic_learner.py | 19 ++++++++- tests/test_memory/test_traffic_learner.py | 50 +++++++++++++++++++++++ 2 files changed, 67 insertions(+), 2 deletions(-) diff --git a/headroom/memory/traffic_learner.py b/headroom/memory/traffic_learner.py index bcecefef0..abd200ff3 100644 --- a/headroom/memory/traffic_learner.py +++ b/headroom/memory/traffic_learner.py @@ -26,6 +26,7 @@ import os import re import sqlite3 import time +from collections import OrderedDict from dataclasses import dataclass, field from datetime import datetime, timezone from enum import Enum @@ -450,6 +451,7 @@ class TrafficLearner: max_history: int = 20, dedup_window: int = 100, min_evidence: int = 5, + max_pending_patterns: int = 2048, ) -> None: """Initialize the traffic learner. @@ -468,12 +470,19 @@ class TrafficLearner: self.agent_type = agent_type self._max_history = max_history self._min_evidence = min_evidence + self._max_pending_patterns = max_pending_patterns # Recent tool call history for error→recovery matching self._tool_history: list[dict[str, Any]] = [] - # Pattern accumulator: hash → (pattern, count) - self._pattern_counts: dict[str, tuple[ExtractedPattern, int]] = {} + # Pattern accumulator: hash → (pattern, count). LRU-ordered and capped: + # a pattern that is seen once but never reaches ``min_evidence`` would + # otherwise linger here forever, so this dict grew unbounded over a + # long-lived proxy's traffic (the sibling ``_saved_hashes`` is trimmed + # to ``dedup_window`` for the same reason; this one was missed). Evicting + # the least-recently-corroborated pending pattern is safe: if it recurs + # it simply restarts accumulation. + self._pattern_counts: OrderedDict[str, tuple[ExtractedPattern, int]] = OrderedDict() # Dedup: hashes of patterns already saved to DB self._saved_hashes: set[str] = set() @@ -1250,7 +1259,13 @@ class TrafficLearner: existing, count = self._pattern_counts[h] count += 1 self._pattern_counts[h] = (existing, count) + # Mark as most-recently-corroborated so it survives LRU eviction. + self._pattern_counts.move_to_end(h) else: + # Bound the pending accumulator so one-off patterns can't grow it + # without limit; drop the least-recently-corroborated pending entry. + if len(self._pattern_counts) >= self._max_pending_patterns: + self._pattern_counts.popitem(last=False) self._pattern_counts[h] = (pattern, 1) return # First sighting — wait for more evidence diff --git a/tests/test_memory/test_traffic_learner.py b/tests/test_memory/test_traffic_learner.py index eee21450b..fae5bc8fe 100644 --- a/tests/test_memory/test_traffic_learner.py +++ b/tests/test_memory/test_traffic_learner.py @@ -362,6 +362,56 @@ class TestTrafficLearner: stats = learner.get_stats() assert stats["patterns_extracted"] >= 3 + def test_pending_accumulator_is_bounded(self): + """One-off patterns that never reach ``min_evidence`` must not grow the + pending ``_pattern_counts`` accumulator without bound — the sibling + ``_saved_hashes`` is already trimmed to ``dedup_window`` and this one was + missed, so a long-lived proxy leaked memory across varied traffic. It is + now LRU-capped at ``max_pending_patterns``. + + Sync test (drives the async accumulate via ``asyncio.run``) so it runs + without the pytest-asyncio plugin. + """ + import asyncio + + learner = TrafficLearner(backend=None, min_evidence=5, max_pending_patterns=8) + + async def feed_one_offs() -> None: + for i in range(500): + await learner._accumulate( + ExtractedPattern( + category=PatternCategory.PREFERENCE, + content=f"one-off pattern number {i}", + importance=0.5, + ) + ) + + asyncio.run(feed_one_offs()) + assert len(learner._pattern_counts) <= 8 # capped, not 500 + + def test_pending_accumulator_lru_still_promotes_corroborated_pattern(self): + """Capping the accumulator must not break promotion: a pattern + corroborated to ``min_evidence`` without interruption is still removed + from pending and recorded in ``_saved_hashes``.""" + import asyncio + + learner = TrafficLearner(backend=None, min_evidence=3, max_pending_patterns=100) + pattern = ExtractedPattern( + category=PatternCategory.PREFERENCE, + content="corroborated preference", + importance=0.5, + ) + + async def corroborate() -> None: + await learner._accumulate(pattern) # count 1 + await learner._accumulate(pattern) # count 2 + assert pattern.content_hash in learner._pattern_counts + await learner._accumulate(pattern) # count 3 == min_evidence -> promote + + asyncio.run(corroborate()) + assert pattern.content_hash not in learner._pattern_counts # removed on promotion + assert pattern.content_hash in learner._saved_hashes + @pytest.mark.asyncio async def test_dedup(self, learner: TrafficLearner): """Test that identical patterns are deduplicated.""" From 3808f60ca61e84faf3ea8f8e003a6e6c8e9af4da Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Sat, 8 Aug 2026 11:44:59 +0530 Subject: [PATCH 011/138] fix(proxy/anthropic): inject headroom_retrieve whenever a CCR marker is present, not only for new markers (#2848) ## Description On a frozen-prefix turn that replays an existing `<>` marker, the proxy did not inject the `headroom_retrieve` tool, so the agent held a marker it could not redeem. When it tried, the Anthropic API rejected the whole request: ```text API Error: 400 Tool reference 'headroom_retrieve' not found in available tools ``` This was a frequent, user-visible failure in Claude Code. ### Root cause The sticky tool-injection gate in `handlers/anthropic.py` was driven by `has_new_ccr_markers(...)` -- markers created THIS turn only: ```python has_new_compressed_content = has_new_ccr_markers( current_detected_hashes=injector.detected_hashes, previous_forwarded_messages=prefix_tracker.get_last_forwarded_messages(), provider="anthropic", ) tools, ccr_tool_injected = apply_session_sticky_ccr_tool( ..., has_compressed_content_this_turn=has_new_compressed_content, ) ``` `apply_session_sticky_ccr_tool` returns early with `decision="skip"` for a session it considers fresh when `not has_compressed_content_this_turn`. A marker replayed from the frozen prefix is "historical" (already in `previous_forwarded_messages`), so `has_new_ccr_markers` returns `False`, and on a fresh session the tool is skipped even though the request carries a redeemable marker. The `SessionCcrTracker` is per-process, so every proxy restart makes live sessions look fresh again and re-arms the failure mid-conversation. Anything that instructs the model to retrieve later (a project instruction saying "call `headroom_retrieve` with the hash before asserting an exact value") lands on this path by construction. ### Fix Drive the gate from `injector.has_compressed_content` -- whether the forwarded request carries ANY CCR marker, new or replayed -- instead of new-markers-only. `#1850` narrowed the first-time gate to new markers to avoid arming a session that never compressed, but a present marker means the session HAS compressed, and a replayed marker is exactly as unredeemable as a fresh one. Since a new marker is also a present marker, `has_new_compressed_content or injector.has_compressed_content` collapses to `injector.has_compressed_content`, so the now-redundant `has_new_ccr_markers` call is removed. The cache argument cuts in favor of this: toggling the tool in and out of the tools array between turns is what busts the tools cache segment. Injecting consistently whenever markers exist is the cache-stable option, and it removes a hard 400 in exchange for at most one cache miss. The frozen message prefix is still replayed byte-identical, so the prompt-cache prefix is unaffected; only the tools array gains a stable entry. Fixes #2766 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/proxy/handlers/anthropic.py`: the sticky CCR tool-injection gate now passes `has_compressed_content_this_turn=injector.has_compressed_content` (any marker present) instead of the new-markers-only signal, and the now-redundant `has_new_ccr_markers` computation/import is dropped. - `tests/test_proxy/test_anthropic_ccr_deferred_injection.py`: the two tests that encoded the superseded `#1850` behavior (a replayed historical marker forwarded WITHOUT the tool) now assert the tool IS injected, with updated rationale. One was renamed from `..._when_tool_injection_is_deferred` to `..._and_injects_retrieve_tool`. The byte-identical message-prefix replay assertions are unchanged. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Fail-before (source fix stashed, updated tests kept): tests/test_proxy/test_anthropic_ccr_deferred_injection.py ::test_cache_mode_compresses_delta_but_replays_cached_prefix_when_markers_are_historical FAILED ::test_cache_mode_exact_prefix_replay_forwards_cached_compressed_prefix_and_injects_retrieve_tool FAILED assert [tool["name"] for tool in forwarded["tools"]] == ["headroom_retrieve"] KeyError: 'tools' # Pass-after (fix applied): tests/test_proxy/test_anthropic_ccr_deferred_injection.py 15 passed # Broader CCR suites: tests/test_proxy/test_ccr_frozen_prefix_coupling.py tests/test_ccr_tool_always_on.py tests/test_ccr_session_tracker.py tests/test_ccr_tool_injection.py 61 passed tests/test_ccr_marker_policy.py tests/test_anthropic_ccr_workspace_unbound.py tests/test_ccr_tool_calls.py tests/test_corrupt_golden_bytes_recovery.py 21 passed # uvx ruff@0.15.17 check -> All checks passed! # uvx mypy@1.20.2 headroom/proxy/handlers/anthropic.py -> Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1, ruff 0.15.17 and mypy 1.20.2 via uvx. - Exact command / steps: traced the gate (`has_new_ccr_markers` -> `apply_session_sticky_ccr_tool` fresh-session `skip`) and confirmed `injector.has_compressed_content` reflects any marker present in the forwarded messages (`len(_detected_hashes) > 0` after `scan_for_markers`). Reproduced the exact bug in the handler harness: a cache-mode frozen replay where `fake_tracker._last_forwarded_messages` already holds the marker (so `has_new` is `False`) on a session the reset tracker considers fresh, with the marker forwarded to upstream. Fail-before with `git stash push headroom/proxy/handlers/anthropic.py` and rerunning the two replay tests (the forwarded body has no `tools`), pass-after with `git stash pop` (the body carries `headroom_retrieve`). - Observed result: on a replayed-marker turn the forwarded request now includes `"tools": [{"name": "headroom_retrieve", ...}]`, so the agent can redeem the hash and Anthropic no longer 400s. The frozen message prefix is still replayed byte-identical (`forwarded["messages"]` unchanged). Sessions that never compressed still get no tool (no marker -> `has_compressed_content` is `False`). - Not tested: a live multi-turn Claude Code session across a real proxy restart (no live provider here). The gate is exercised end-to-end through the handler via the TestClient harness, reproducing the historical-marker-on-fresh-session desync the issue describes. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`: it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes This deliberately reworks the `#1850` deferral for historical markers, so it changes two tests that encoded "tool absent on frozen replay." That behavior was the source of the 400: a marker in the prompt with no tool to redeem it is a hard failure, whereas a re-injected tool is a stable, cheap entry in the tools array. The reporter validated the same change locally (33 requests, 0 errors, 0 `skip`). Scope is the Anthropic interactive path where the bug was reported; the stateless batch path (a separate `CCRToolInjector.process_request` gated on `tokens_saved > 0`) is unchanged. --- headroom/proxy/handlers/anthropic.py | 34 +++++++++++-------- .../test_anthropic_ccr_deferred_injection.py | 25 ++++++++------ 2 files changed, 33 insertions(+), 26 deletions(-) diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index ede5e72d7..7e01915e5 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -1873,27 +1873,31 @@ class AnthropicHandlerMixin: # dropping the gate cannot start injecting into non-CCR # conversations. if configured_inject_tool: - from headroom.proxy.helpers import ( - apply_session_sticky_ccr_tool, - has_new_ccr_markers, - ) + from headroom.proxy.helpers import apply_session_sticky_ccr_tool - # #1850: markers replayed from the previously-forwarded - # prefix (overlay_cached_prefix) are historical; only - # markers NEW this turn may drive a first-time injection, - # else a replayed marker injects the tool into a session - # that never actually compressed. - has_new_compressed_content = has_new_ccr_markers( - current_detected_hashes=injector.detected_hashes, - previous_forwarded_messages=prefix_tracker.get_last_forwarded_messages(), - provider="anthropic", - ) + # Inject whenever the request carries ANY CCR marker, new or + # replayed from the frozen prefix. #1850 narrowed the + # first-time gate to markers created THIS turn to avoid + # arming a session that never compressed, but a replayed + # marker is exactly as unredeemable as a fresh one: the agent + # redeems hashes it was handed turns ago (project instructions + # can even tell it to), and if `headroom_retrieve` is absent + # Anthropic rejects the whole request with 400 "Tool reference + # 'headroom_retrieve' not found in available tools" (#2766). A + # present marker means the session HAS compressed, so this + # cannot start injecting into non-CCR conversations. It is also + # the cache-stable choice: toggling the tool in and out of the + # tools array between turns is what busts the tools cache + # segment, whereas injecting consistently whenever markers + # exist keeps it stable. The `SessionCcrTracker` is + # per-process, so a proxy restart mid-conversation makes live + # sessions look fresh again, which is what re-armed the 400. tools, ccr_tool_injected = apply_session_sticky_ccr_tool( provider="anthropic", session_id=session_id, request_id=request_id, existing_tools=tools, - has_compressed_content_this_turn=has_new_compressed_content, + has_compressed_content_this_turn=injector.has_compressed_content, ) if ccr_tool_injected: logger.debug( diff --git a/tests/test_proxy/test_anthropic_ccr_deferred_injection.py b/tests/test_proxy/test_anthropic_ccr_deferred_injection.py index edccdbee2..46a334113 100644 --- a/tests/test_proxy/test_anthropic_ccr_deferred_injection.py +++ b/tests/test_proxy/test_anthropic_ccr_deferred_injection.py @@ -592,16 +592,17 @@ def test_cache_mode_compresses_delta_but_replays_cached_prefix_when_markers_are_ assert response.status_code == 200 assert len(captured.get("compression_calls", [])) == 1 forwarded = captured["body"] - # Tool injection is deferred (no CCR tool this turn), but the frozen - # prefix was cached COMPRESSED last turn. Replay it byte-identical so the - # prompt cache still hits instead of busting on original bytes (#1850); - # the historical marker does not force tool injection back on. Tool absent - # AND cache intact. + # The frozen prefix was cached COMPRESSED last turn, so it is replayed + # byte-identical to keep the prompt cache warm. The replayed marker is + # still redeemable this turn, so `headroom_retrieve` MUST be present or + # Anthropic 400s "Tool reference 'headroom_retrieve' not found" (#2766); + # injecting it whenever a marker exists is itself cache-stable (toggling + # is what busts the tools segment). Message prefix replayed AND tool present. assert forwarded["messages"] == previous_forwarded_messages - assert "tools" not in forwarded + assert [tool["name"] for tool in forwarded["tools"]] == ["headroom_retrieve"] -def test_cache_mode_exact_prefix_replay_forwards_cached_compressed_prefix_when_tool_injection_is_deferred( +def test_cache_mode_exact_prefix_replay_forwards_cached_compressed_prefix_and_injects_retrieve_tool( monkeypatch, ) -> None: captured: dict[str, object] = {} @@ -684,11 +685,13 @@ def test_cache_mode_exact_prefix_replay_forwards_cached_compressed_prefix_when_t assert response.status_code == 200 assert captured.get("compression_calls", []) == [] forwarded = captured["body"] - # Deferred injection (no CCR tool), single frozen message cached - # COMPRESSED last turn: replay it so the cache holds instead of busting - # on original bytes (#1850). Tool absent AND cache intact. + # Single frozen message cached COMPRESSED last turn: replay it + # byte-identical so the cache holds instead of busting on original bytes. + # The replayed marker is still redeemable, so `headroom_retrieve` must be + # present this turn or Anthropic 400s "Tool reference 'headroom_retrieve' + # not found" (#2766). Message prefix replayed AND tool present. assert forwarded["messages"] == previous_forwarded_messages - assert "tools" not in forwarded + assert [tool["name"] for tool in forwarded["tools"]] == ["headroom_retrieve"] def test_token_mode_cached_messages_skip_cache_update_when_pipeline_result_is_unchanged( From 14c4c9d5b78c6122e1a217ff193bee95055d023b Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Sat, 8 Aug 2026 11:45:41 +0530 Subject: [PATCH 012/138] fix(install): stop baking the host memory DB path into a container deployment (#2845) ## Description `headroom deploy --memory` on the `persistent-docker` preset can never become ready. The planner resolves the memory DB path against the **host** home and appends it verbatim to `proxy_args`: ```python # headroom/install/planner.py proxy_args.extend(["--memory", "--memory-db-path", str(_paths.memory_db_path())]) # -> --memory-db-path /home//.headroom/memory.db ``` The docker runtime passes everything after the leading `--host` pair through unchanged, and the container's `HOME` is `/tmp/headroom-home` with the host's `~/.headroom` bind-mounted at `/tmp/headroom-home/.headroom`. The host path `/home//.headroom/memory.db` does not exist inside the container, so SQLite cannot open the DB: ```text Memory: backend initialization failed (startup continues): unable to open database file ``` `/health` then reports `memory.ready = false`, `/readyz` stays 503 for the full `wait_ready` window, and `_start_deployment` times out and rolls back, so the failure presents as "did not become ready" rather than a path bug. The same applies on macOS with `/Users//...`. The fix omits `--memory-db-path` for a container (docker) runtime. When the flag is absent the proxy resolves the DB under its own cwd (`.headroom/memory.db`), and the container's workdir is `/tmp/headroom-home` (the bind mount), so the DB lands in exactly the same host file the explicit path intended. The host (python) runtime still passes the resolved host path, which is correct there. Fixes #2803 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/install/planner.py` (`build_manifest`): append `--memory` always, but add `--memory-db-path ` only when `runtime_kind != RuntimeKind.DOCKER.value`. Imported `RuntimeKind` from `.models`. - `tests/test_install/test_planner.py`: extended `test_build_manifest_for_persistent_docker_sets_expected_defaults` to assert `--memory-db-path` is absent for the docker runtime, and added `test_build_manifest_python_runtime_keeps_explicit_memory_db_path` asserting it is still present for the python runtime. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Fail-before (source fix stashed, updated tests kept): tests/test_install/test_planner.py::test_build_manifest_for_persistent_docker_sets_expected_defaults FAILED assert "--memory-db-path" not in manifest.proxy_args AssertionError: assert '--memory-db-path' not in ['--host', '127.0.0.1', ...] # Pass-after (fix applied): tests/test_install/test_planner.py 19 passed # Broader install suites: tests/test_install/ 141 passed, 1 skipped, 2 unrelated pre-existing/flaky failures # - test_native_installers.py::test_powershell_native_installer_supports_persistent_docker_lifecycle # runs scripts/install.ps1 and fails identically on clean main (environment-specific). # - test_runtime.py::test_runtime_status_survives_winerror87_systemerror passes in isolation # and in its own file; it only failed under cross-file ordering in the broad run, and is # untouched by this diff (planner.py only). # uvx ruff@0.15.17 check -> All checks passed! # uvx mypy@1.20.2 headroom/install/planner.py -> Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1, ruff 0.15.17 and mypy 1.20.2 via uvx. - Exact command / steps: traced the path from `planner.py` (`--memory-db-path str(_paths.memory_db_path())`, host home) through `runtime.py` (`build_runtime_command` passes `proxy_args[_PROXY_ARGS_HOST_PAIR_LEN:]` through, container HOME `/tmp/headroom-home`, `~/.headroom` bind-mounted) and confirmed via `server.py` that an empty `memory_db_path` resolves to `Path.cwd()/.headroom/memory.db` (the container workdir, hence the mount). Fail-before with `git stash push headroom/install/planner.py` and `python -m pytest tests/test_install/test_planner.py -k persistent_docker` (host path present in proxy_args), pass-after with `git stash pop` and rerunning (19 passed). - Observed result: for the docker runtime, `manifest.proxy_args` now carries `--memory` without `--memory-db-path`, so the container resolves the DB to `/tmp/headroom-home/.headroom/memory.db` (the bind mount to host `~/.headroom/memory.db`) and can open it, instead of receiving a nonexistent host path. The python runtime still carries the explicit host path. - Not tested: a live `headroom deploy --memory` against a running Docker daemon (no container runtime in this environment). The manifest construction is verified directly, and the container-side resolution it relies on is existing server behavior (`empty memory_db_path -> cwd/.headroom/memory.db`) confirmed by reading `server.py`. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`: it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes The DB persistence location is unchanged: both the old host path and the new container-cwd resolution point at the host's `~/.headroom/memory.db` (directly on the host, or through the bind mount inside the container), so existing memory DBs are picked up either way. This is the memory-path half of the persistent-docker issues; the separate rootless-Podman `--user` bind-mount problem (#2804) is left for its own fix. --- headroom/install/planner.py | 15 ++++++++++++++- tests/test_install/test_planner.py | 27 +++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/headroom/install/planner.py b/headroom/install/planner.py index 79c11ed31..9b6d26fdd 100644 --- a/headroom/install/planner.py +++ b/headroom/install/planner.py @@ -15,6 +15,7 @@ from .models import ( DeploymentManifest, InstallPreset, ProviderSelectionMode, + RuntimeKind, SupervisorKind, ToolTarget, ) @@ -181,7 +182,19 @@ def build_manifest( ] proxy_args.append("--telemetry" if telemetry_enabled else "--no-telemetry") if memory_enabled: - proxy_args.extend(["--memory", "--memory-db-path", str(_paths.memory_db_path())]) + proxy_args.append("--memory") + # `_paths.memory_db_path()` resolves against the HOST home. A container + # runtime cannot use it: the container's HOME is /tmp/headroom-home and + # the host's ~/.headroom is bind-mounted there, so a host path like + # /home//.headroom/memory.db does not exist inside the container, + # SQLite fails to open the DB, /readyz stays 503, and the deployment + # times out and rolls back (#2803). Omit the flag for a container runtime: + # the proxy then resolves the DB under its own cwd (.headroom/memory.db), + # which is the container's workdir and therefore the bind mount, landing + # in the same host file the explicit path intended. On the host (python) + # runtime the resolved host path is correct, so keep passing it. + if runtime_kind != RuntimeKind.DOCKER.value: + proxy_args.extend(["--memory-db-path", str(_paths.memory_db_path())]) if anyllm_provider: proxy_args.extend(["--anyllm-provider", anyllm_provider]) if region: diff --git a/tests/test_install/test_planner.py b/tests/test_install/test_planner.py index ffb559149..15c7de6fc 100644 --- a/tests/test_install/test_planner.py +++ b/tests/test_install/test_planner.py @@ -46,6 +46,33 @@ def test_build_manifest_for_persistent_docker_sets_expected_defaults() -> None: assert manifest.tool_envs["claude"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:8787" assert manifest.tool_envs["copilot"]["COPILOT_PROVIDER_TYPE"] == "anthropic" assert "--memory" in manifest.proxy_args + # A container runtime must NOT carry the host memory DB path: it does not + # exist inside the container and would keep /readyz at 503 (#2803). The proxy + # resolves the DB under its own cwd, which is the bind-mounted ~/.headroom. + assert "--memory-db-path" not in manifest.proxy_args + + +def test_build_manifest_python_runtime_keeps_explicit_memory_db_path() -> None: + manifest = build_manifest( + profile="default", + preset=InstallPreset.PERSISTENT_SERVICE.value, + runtime_kind="python", + scope="user", + provider_mode="manual", + targets=["claude"], + port=8787, + backend="anthropic", + anyllm_provider=None, + region=None, + proxy_mode="token", + memory_enabled=True, + telemetry_enabled=False, + image="ghcr.io/headroomlabs-ai/headroom:latest", + ) + + # On the host the resolved path is correct, so it is still passed explicitly. + assert "--memory" in manifest.proxy_args + assert "--memory-db-path" in manifest.proxy_args def test_build_manifest_uses_provider_slice_env_builders_for_all_supported_targets() -> None: From 3488f8d4b5fae4eab157e0c4031ccf712bcbcc0d Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Sat, 8 Aug 2026 12:00:48 +0530 Subject: [PATCH 013/138] fix(install): use --userns=keep-id under Podman so bind-mount writes don't fail (#2846) ## Description `build_runtime_command` unconditionally adds `--user :` on non-Windows hosts: ```python # headroom/install/runtime.py if not _is_windows(): getuid = getattr(os, "getuid", None) getgid = getattr(os, "getgid", None) if callable(getuid) and callable(getgid): command.extend(["--user", f"{getuid()}:{getgid()}"]) ``` That is correct for Docker, where container UIDs equal host UIDs, but wrong for rootless Podman, where the host user is already mapped to container UID 0 and the `/etc/subuid` range is mapped to container UIDs 1 and above. Passing `--user $(id -u):$(id -g)` therefore selects a container UID backed by a subordinate host UID that owns nothing. The bind-mounted `~/.headroom` appears inside the container as `root:root` and is unwritable, so every write fails: ```text PermissionError: [Errno 13] Permission denied: '/tmp/headroom-home/.headroom/memories' event=proxy_inbound_request_aborted path=/v1/messages reason=PermissionError ``` The proxy still starts and reports healthy, so the failure only surfaces once a request touches a write path. As the reporter confirmed, `--userns=keep-id` (or omitting `--user`) fixes it. The fix detects Podman and uses `--userns=keep-id` instead of `--user`, which maps the host user to the same UID inside the container and keeps the bind mounts writable. Docker still gets `--user`, unchanged. Detection is subprocess-free: it resolves the `docker` binary and checks its real name for the common `docker -> podman` symlink shim (e.g. NixOS `/run/current-system/sw/bin/docker -> podman`), with an explicit `HEADROOM_CONTAINER_RUNTIME` (`podman` / `docker`) override for setups the symlink heuristic cannot see, such as a wrapper script. Fixes #2804 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/install/runtime.py`: added `_container_runtime_is_podman()` (env override, then a `docker`-binary realpath basename check, no subprocess). In `build_runtime_command`, when Podman is detected the command uses `--userns=keep-id` instead of `--user :`. - `tests/test_install/test_runtime.py`: pinned the existing docker test to the Docker path via `HEADROOM_CONTAINER_RUNTIME=docker` and asserted `--userns=keep-id` is absent there; added `test_build_runtime_command_podman_uses_keep_id_not_user` asserting the Podman path drops `--user` and adds `--userns=keep-id`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Fail-before (source fix stashed, new test kept): tests/test_install/test_runtime.py::test_build_runtime_command_podman_uses_keep_id_not_user FAILED assert "--userns=keep-id" in command AssertionError: assert '--userns=keep-id' in ['docker', 'run', '--rm', ...] # Pass-after (fix applied): tests/test_install/test_runtime.py 26 passed # Broader install suite (excluding the pre-existing env-specific PowerShell installer test): tests/test_install/ 142 passed, 1 skipped # uvx ruff@0.15.17 check -> All checks passed! # uvx mypy@1.20.2 headroom/install/runtime.py -> Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1, ruff 0.15.17 and mypy 1.20.2 via uvx. - Exact command / steps: confirmed `build_runtime_command` adds `--user` unconditionally on non-Windows, then drove both runtimes deterministically via the `HEADROOM_CONTAINER_RUNTIME` override. Fail-before with `git stash push headroom/install/runtime.py` and `python -m pytest tests/test_install/test_runtime.py -k podman_uses_keep_id` (the command still carries `--user`, no keep-id), pass-after with `git stash pop` and rerunning the file (26 passed). - Observed result: with Podman detected the docker command now contains `--userns=keep-id` and no `--user`/`1000:1001`, matching the `--userns=keep-id` invocation the reporter verified writes successfully; with Docker it is unchanged (`--user 1000:1001`, no keep-id). - Not tested: a live rootless-Podman deployment writing to a bind mount (no Podman in this environment). The command construction is verified directly, and `--userns=keep-id` is the documented, reporter-confirmed switch for the rootless-Podman ID-mapping. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`: it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes Detection is intentionally subprocess-free and conservative: it only diverges from today's behavior when the `docker` binary literally resolves to a `podman`-named target, or when `HEADROOM_CONTAINER_RUNTIME` is set. Real Docker installs are untouched. The override also gives a clean escape hatch in both directions if a given host's symlink layout hides the runtime. This is the `--user` half of the persistent-docker + Podman issues; the separate host-memory-path problem (#2803) is addressed in its own PR. --- headroom/install/runtime.py | 42 +++++++++++++++++++++++++++--- tests/test_install/test_runtime.py | 34 ++++++++++++++++++++++++ 2 files changed, 72 insertions(+), 4 deletions(-) diff --git a/headroom/install/runtime.py b/headroom/install/runtime.py index 0736e0a33..5288cdc74 100644 --- a/headroom/install/runtime.py +++ b/headroom/install/runtime.py @@ -56,6 +56,32 @@ def _is_windows() -> bool: return sys.platform.startswith("win") +def _container_runtime_is_podman() -> bool: + """Best-effort: is the ``docker`` command actually Podman? + + Rootless Podman maps the host user to container UID 0, so the + ``--user :`` flag that is correct for Docker instead + selects a subordinate UID that owns none of the bind-mounted host + directories, and every write into ``~/.headroom`` fails (#2804). Detect the + common ``docker -> podman`` shim (e.g. NixOS + ``/run/current-system/sw/bin/docker -> podman``) by resolving the binary and + checking its real name. ``HEADROOM_CONTAINER_RUNTIME`` (``podman`` / ``docker``) + is an explicit override for setups the symlink heuristic cannot see, such as a + wrapper script. No subprocess is spawned. + """ + override = os.environ.get("HEADROOM_CONTAINER_RUNTIME", "").strip().lower() + if override: + return override == "podman" + resolved = shutil.which("docker") + if not resolved: + return False + try: + real = os.path.realpath(resolved) + except OSError: + real = resolved + return "podman" in os.path.basename(real).lower() + + def _deployment_env(manifest: DeploymentManifest) -> dict[str, str]: return { "HEADROOM_DEPLOYMENT_PROFILE": manifest.profile, @@ -136,10 +162,18 @@ def build_runtime_command(manifest: DeploymentManifest) -> list[str]: if docker_gpus: command.extend(["--gpus", docker_gpus]) if not _is_windows(): - getuid = getattr(os, "getuid", None) - getgid = getattr(os, "getgid", None) - if callable(getuid) and callable(getgid): - command.extend(["--user", f"{getuid()}:{getgid()}"]) + if _container_runtime_is_podman(): + # Rootless Podman maps the host user to container UID 0, so --user + # would map to a subordinate UID that owns none of the bind mounts and + # every write into ~/.headroom fails (#2804). keep-id maps the host + # user to the same UID inside the container, keeping the mounts + # writable. Docker maps UIDs 1:1, so --user stays correct there. + command.append("--userns=keep-id") + else: + getuid = getattr(os, "getuid", None) + getgid = getattr(os, "getgid", None) + if callable(getuid) and callable(getgid): + command.extend(["--user", f"{getuid()}:{getgid()}"]) runtime_env = {**manifest.base_env, **_deployment_env(manifest)} for name, value in runtime_env.items(): command.extend(["--env", f"{name}={value}"]) diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.py index ce654d859..8b5e08ed4 100644 --- a/tests/test_install/test_runtime.py +++ b/tests/test_install/test_runtime.py @@ -281,6 +281,9 @@ def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Pat monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux") monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False) monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False) + # Force the Docker path deterministically regardless of the test host's + # `docker` binary (it might resolve to a podman shim). + monkeypatch.setenv("HEADROOM_CONTAINER_RUNTIME", "docker") docker_manifest = DeploymentManifest( profile="default", preset="persistent-docker", @@ -299,6 +302,37 @@ def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Pat command = build_runtime_command(docker_manifest) assert "--user" in command assert "1000:1001" in command + assert "--userns=keep-id" not in command + + +def test_build_runtime_command_podman_uses_keep_id_not_user(monkeypatch, tmp_path: Path) -> None: + """Under rootless Podman, --user : selects a subordinate + UID that owns none of the bind mounts, so writes into ~/.headroom fail. The + command must use --userns=keep-id and drop --user instead (#2804).""" + monkeypatch.setattr(Path, "home", lambda: tmp_path) + monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux") + monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False) + monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False) + monkeypatch.setenv("HEADROOM_CONTAINER_RUNTIME", "podman") + manifest = DeploymentManifest( + profile="default", + preset="persistent-docker", + runtime_kind="docker", + supervisor_kind="none", + scope="user", + provider_mode="manual", + targets=[], + port=8787, + host="127.0.0.1", + backend="anthropic", + image="ghcr.io/headroomlabs-ai/headroom:latest", + base_env={"HEADROOM_PORT": "8787"}, + proxy_args=["--host", "127.0.0.1", "--port", "8787"], + ) + command = build_runtime_command(manifest) + assert "--userns=keep-id" in command + assert "--user" not in command + assert "1000:1001" not in command def test_read_pid_handles_invalid_content(monkeypatch, tmp_path: Path) -> None: From c49be269a18446779cd8a048caaa7f0ba3a3b48b Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Sat, 8 Aug 2026 12:01:40 +0530 Subject: [PATCH 014/138] fix(wrap): stop the launch cwd from shadowing the installed package in the proxy subprocess (#2843) ## Description `headroom wrap` starts the proxy via `_start_proxy`, which builds `cmd = [sys.executable, "-m", "headroom.cli", "proxy", ...]`. A `python -m ` invocation prepends the launch cwd to `sys.path`. So when `wrap` is run from a directory that contains a `headroom/` folder (most commonly a clone of this very repo, whose package lives at `/headroom/`), that raw source tree shadows the installed wheel in site-packages. The source tree has no compiled `headroom._core` (the maturin extension only exists in the built wheel), so the proxy dies with: ```text Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy] Details: No module named 'headroom._core' ``` `wrap` then falls back to launching the client unwrapped, and the "not installed" hint is misleading: the dependency is installed, it is being shadowed by cwd. The fix sets `PYTHONSAFEPATH=1` in the proxy subprocess env. That disables the cwd/script-dir prepend to `sys.path` (Python 3.11+, and a harmless no-op on 3.10, so it never breaks the supported floor), which is exactly what the issue reporter confirmed resolves it: ```console $ PYTHONSAFEPATH=1 python -c "import headroom._core; print('OK')" # -> OK ``` The proxy is still launched as `-m headroom.cli`, so nothing about the invocation changes except that it now always resolves the installed package. Fixes #2793 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/cli/wrap.py` (`_start_proxy`): set `proxy_env["PYTHONSAFEPATH"] = "1"` alongside the existing `PYTHONIOENCODING`, with a comment explaining the cwd-shadow failure mode. - `tests/test_cli/test_wrap_claude_vertex_proxy_env.py`: added `test_start_proxy_sets_pythonsafepath_to_avoid_cwd_shadow`, which drives `_start_proxy` with a faked `subprocess.Popen` and asserts the subprocess env carries `PYTHONSAFEPATH=1` while still launching `-m headroom.cli proxy`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Fail-before (source fix stashed, new test kept): tests/test_cli/test_wrap_claude_vertex_proxy_env.py::test_start_proxy_sets_pythonsafepath_to_avoid_cwd_shadow FAILED assert captured["kwargs"]["env"]["PYTHONSAFEPATH"] == "1" KeyError: 'PYTHONSAFEPATH' # Pass-after (fix applied): tests/test_cli/test_wrap_claude_vertex_proxy_env.py 18 passed # Broader wrap suites: tests/test_cli/test_wrap_claude_vertex_proxy_env.py tests/test_cli_proxy_env.py tests/test_cli/test_wrap_persistent.py 121 passed, 1 skipped # uvx ruff@0.15.17 check -> All checks passed! # uvx mypy@1.20.2 headroom/cli/wrap.py -> Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1, ruff 0.15.17 and mypy 1.20.2 via uvx. - Exact command / steps: confirmed `_start_proxy` builds `[sys.executable, "-m", "headroom.cli", "proxy", ...]` and constructs the subprocess env as `proxy_env`, reproduced the shadowing behaviour in the reporter's terms (`python -m` prepends cwd; a cwd `headroom/` without `_core` shadows the wheel), fail-before with `git stash push headroom/cli/wrap.py` and `python -m pytest ... -k pythonsafepath` (the env lacks the key), then pass-after with `git stash pop` and rerunning the file (18 passed) plus the broader wrap suites (121 passed, 1 skipped). - Observed result: the proxy subprocess env now carries `PYTHONSAFEPATH=1`, which disables the cwd prepend, so `import headroom._core` resolves the installed wheel instead of a shadowing local `headroom/` source tree. The proxy command is unchanged otherwise. - Not tested: an end-to-end `cd && headroom wrap claude` against a real installed wheel (this environment is a source checkout without a separate installed wheel to shadow). The behaviour is verified through the spawn env the subprocess inherits, and `PYTHONSAFEPATH` is the documented, reporter-confirmed switch for this exact failure mode. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`: it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes Scoped to the proxy launch, which is the reported, high-impact path (its failure makes `wrap` fall back to unwrapped). `wrap` spawns one other `python -m headroom.*` subprocess (the memory-sync helper in the Claude flow) that shares the same root cause; it is a lower-severity, unreported path and is left for a follow-up rather than widening this diff. The misleading "pip install headroom-ai[proxy]" message the reporter also flagged is a separate error-text concern and is likewise out of scope here. --- headroom/cli/wrap.py | 9 ++++++ .../test_wrap_claude_vertex_proxy_env.py | 30 +++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py index af22dc45c..8911c883f 100644 --- a/headroom/cli/wrap.py +++ b/headroom/cli/wrap.py @@ -629,6 +629,15 @@ def _start_proxy( proxy_env = os.environ.copy() _scrub_copilot_proxy_seed_env(proxy_env) proxy_env["PYTHONIOENCODING"] = "utf-8" + # `python -m headroom.cli` prepends the launch cwd to sys.path, so running + # `wrap` from a directory that contains a `headroom/` folder (most commonly a + # clone of this repo, whose package lives at /headroom/) shadows the + # installed wheel with the raw source tree, which has no compiled + # `headroom._core`. The proxy then dies with "No module named 'headroom._core'" + # and wrap silently falls back to launching the client unwrapped (#2793). + # PYTHONSAFEPATH disables that cwd prepend (Python 3.11+; a harmless no-op on + # 3.10) so the subprocess always resolves the installed package. + proxy_env["PYTHONSAFEPATH"] = "1" # Vertex AI RST_STREAMs HTTP/2 connections (error_code:2). Force HTTP/1.1 # when wrapping a Vertex-mode client so upstream requests succeed. if os.environ.get("CLAUDE_CODE_USE_VERTEX") or os.environ.get("ANTHROPIC_VERTEX_PROJECT_ID"): diff --git a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py index 4d888ba61..546b31cd8 100644 --- a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py +++ b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py @@ -370,6 +370,36 @@ def test_start_proxy_clears_inherited_vertex_target_env( assert "VERTEX_TARGET_API_URL" not in proxy_env +def test_start_proxy_sets_pythonsafepath_to_avoid_cwd_shadow( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """`python -m headroom.cli` prepends the launch cwd to sys.path, so running + wrap from a directory that contains a `headroom/` folder (a clone of this + repo) shadows the installed wheel with the raw source tree, which has no + compiled `headroom._core`, and the proxy dies importing it (#2793). The + subprocess env must set PYTHONSAFEPATH=1 to disable that cwd prepend.""" + fake_proc = _FakeProxyProcess() + captured: dict[str, Any] = {} + + 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.time, "sleep", lambda _seconds: None) + + def fake_popen(cmd: list[str], **kwargs: object) -> _FakeProxyProcess: + captured["cmd"] = cmd + captured["kwargs"] = kwargs + return fake_proc + + monkeypatch.setattr(wrap_mod.subprocess, "Popen", fake_popen) + + proc = wrap_mod._start_proxy(8787, agent_type="claude") + + assert proc is fake_proc + assert captured["kwargs"]["env"]["PYTHONSAFEPATH"] == "1" + # Still launched as a module of the installed package. + assert captured["cmd"][:4] == [wrap_mod.sys.executable, "-m", "headroom.cli", "proxy"] + + def test_ensure_proxy_restarts_idle_proxy_for_vertex_api_url_mismatch( monkeypatch: pytest.MonkeyPatch, ) -> None: From 54ea28d9839a0dcfa4dd0cf4210a4421f03beeff Mon Sep 17 00:00:00 2001 From: Rod Boev Date: Sat, 8 Aug 2026 02:32:54 -0400 Subject: [PATCH 015/138] fix(openai): skip Responses tool-search deferral for clients that cannot execute it (#2696) ## Description OpenCode rejects the proxy-injected Responses `tool_search` tool because it resolves tool calls against its local registry. This PR now uses the shared client policy from current `main` and leaves OpenCode tools resident, alongside the existing Codex exclusion. Other clients retain tool-search deferral. Closes #2660. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] Documentation update ## Changes Made - Add `opencode` to the shared exact-match unsupported-client set in `headroom.proxy.helpers`. - Carry the already-classified `client` through native HTTP, WebSocket, and custom-base Responses paths. - Preserve `main`'s compatibility loop, which retries only exact unsupported `client` or `timing` keyword errors and re-raises internal `TypeError`s. - Add focused helper, compressor, HTTP, passthrough, and WebSocket coverage. ## Testing - [x] Unit tests pass - [x] Ruff check and format pass - [x] New tests added - [ ] Live OpenCode session tested ```text uv run --extra dev pytest tests/test_openai_tool_search_deferral.py tests/test_proxy_openai.py -q 57 passed uv run --extra dev ruff check headroom/proxy/handlers/openai.py headroom/proxy/helpers.py tests/test_openai_tool_search_deferral.py tests/test_proxy_openai.py All checks passed ``` ## Real Behavior Proof The focused route tests classify OpenCode from both `User-Agent` and `X-Client`, verify its tools remain untouched, and verify the decision reaches all three Responses ingresses. Supported clients continue to receive deferral. Codex remains excluded by the policy already on `main`. Not tested: a live OpenCode instance; the incompatibility itself remains based on the reporter's reproduction in #2660. ## Review Readiness - [x] Updated from current upstream `main` - [x] Merge conflicts resolved - [x] Focused tests pass locally - [x] Ready for human review ## Additional Notes No user configuration or documentation change is required. Vercel authorization failures are external integration noise, not a source check. --------- Co-authored-by: JD Davis --- headroom/proxy/helpers.py | 13 +- tests/test_openai_tool_search_deferral.py | 35 +- tests/test_proxy_openai.py | 448 ++++++++++++++++++++++ 3 files changed, 490 insertions(+), 6 deletions(-) create mode 100644 tests/test_proxy_openai.py diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py index adcb846e9..c36daa3d2 100644 --- a/headroom/proxy/helpers.py +++ b/headroom/proxy/helpers.py @@ -2485,7 +2485,11 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Any # (only name+description remain) until the model searches for one — while every # tool stays callable and the prompt cache is preserved. Same win as Anthropic # (~15-25k tool-schema tokens -> ~200) for clients that ship a big tool surface -# and never opt into tool search themselves (opencode, plain API clients). +# and never opt into tool search themselves (plain API clients). +# +# Two harnesses are excluded. Codex drops deferred-call namespaces during its +# round trip, while GH #2660 reports OpenCode rejecting the injected +# `tool_search` tool as unavailable. Their tools therefore stay resident. # # Differences from the Anthropic path that require a separate function: # * Responses function tools carry ``type: "function"`` (Anthropic real tools @@ -2500,7 +2504,7 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Any _OPENAI_TOOL_SEARCH_TYPE = "tool_search" _OPENAI_TOOL_SEARCH_MIN_TOOLS = 12 _OPENAI_TOOL_SEARCH_RESIDENT_NAMES = frozenset({"terminal"}) -_OPENAI_TOOL_SEARCH_UNSUPPORTED_CLIENTS = frozenset({"codex"}) +_OPENAI_TOOL_SEARCH_UNSUPPORTED_CLIENTS = frozenset({"codex", "opencode"}) # gpt-5.4 is the first model with Responses tool_search (OpenAI docs). Version- # gated by default; overridable per deployment via a regex in # HEADROOM_OPENAI_TOOL_SEARCH_MODELS (matched against the model name) so new @@ -2548,8 +2552,9 @@ def inject_tool_search_deferral_openai( deferred + a ``{"type": "tool_search"}`` tool injected, or the original list unchanged when injection doesn't apply. - No-op for Codex, whose round-trip structs drop deferred-call namespaces. Also - no-op when: the model doesn't support tool search (gpt-5.4+ only), ``tools`` + No-op for Codex and OpenCode, whose harnesses cannot safely execute the + injected search tool. Also no-op when: the model doesn't support tool search + (gpt-5.4+ only), ``tools`` is not a list, there are fewer than ``_OPENAI_TOOL_SEARCH_MIN_TOOLS``, a tool_search tool is already present (client already defers), or nothing would be deferred. Core coding tools and hosted/typed tools (web_search, diff --git a/tests/test_openai_tool_search_deferral.py b/tests/test_openai_tool_search_deferral.py index da149f846..32486d06c 100644 --- a/tests/test_openai_tool_search_deferral.py +++ b/tests/test_openai_tool_search_deferral.py @@ -60,7 +60,7 @@ def test_env_override_wins_then_falls_back(monkeypatch): @pytest.mark.parametrize( ("client", "supported"), - [(None, True), ("codex", False), (" CODEX ", False), ("opencode", True), ("claude", True)], + [(None, True), ("codex", False), (" CODEX ", False), ("opencode", False), ("claude", True)], ) def test_client_supported(client, supported): assert openai_tool_search_client_supported(client) is supported @@ -76,7 +76,7 @@ def test_codex_client_does_not_inject(): assert all("defer_loading" not in tool for tool in out) -@pytest.mark.parametrize("client", [None, "opencode"]) +@pytest.mark.parametrize("client", [None, "claude-code"]) def test_supported_clients_still_inject(client): tools = _tools() @@ -187,3 +187,34 @@ def test_resident_names_match_case_insensitively(): for name in ("Bash", "Read", "Edit", "Terminal", "ToolSearch"): assert by_name[name].get("defer_loading") is None, name assert by_name["slack_0"].get("defer_loading") is True + + +# --- client-harness exclusion (GH #2660) ------------------------------------- + + +def test_noop_for_a_client_that_cannot_execute_the_search_tool(): + # GH #2660 reports opencode resolving tool calls against its own registry + # and rejecting the injected tool as unavailable, so its tools stay resident + # and untouched. + tools = _tools() + snapshot = copy.deepcopy(tools) + + out = inject_tool_search_deferral_openai(tools, "gpt-5.5", client="opencode") + + assert out is tools + assert tools == snapshot + assert not any(t.get("type") == "tool_search" for t in out) + assert not any(t.get("defer_loading") for t in out) + + +def test_supported_clients_keep_the_existing_deferral(): + # The exclusion is per-client, not a global default flip: anything that can + # search still gets the same payload it got before. + tools = _tools() + + explicit = inject_tool_search_deferral_openai(tools, "gpt-5.5", client="claude-code") + implicit = inject_tool_search_deferral_openai(tools, "gpt-5.5") + + assert explicit == implicit + assert implicit[0] == {"type": "tool_search"} + assert any(t.get("defer_loading") for t in implicit) diff --git a/tests/test_proxy_openai.py b/tests/test_proxy_openai.py new file mode 100644 index 000000000..9960c6f6e --- /dev/null +++ b/tests/test_proxy_openai.py @@ -0,0 +1,448 @@ +"""Responses tool-search deferral is skipped for harnesses that cannot run it (GH #2660).""" + +from __future__ import annotations + +import asyncio +import json +from types import SimpleNamespace + +import httpx +import pytest +from starlette.datastructures import Headers + +from headroom.proxy.auth_mode import classify_client +from headroom.proxy.handlers.openai import OpenAIHandlerMixin +from headroom.proxy.helpers import ( + inject_tool_search_deferral_openai, + openai_tool_search_client_supported, +) + +TOOL_SEARCH_MODEL = "gpt-5.5" + + +def _tool_payload() -> list[dict[str, object]]: + """Six core coding tools plus ten non-core ones, over the injection minimum.""" + names = ["bash", "read", "write", "edit", "grep", "glob"] + names += [f"slack_{index}" for index in range(10)] + return [ + {"type": "function", "name": name, "parameters": {"type": "object", "properties": {}}} + for name in names + ] + + +@pytest.mark.parametrize( + ("headers", "expected_client", "supported"), + [ + ({"user-agent": "opencode/0.4.2"}, "opencode", False), + ({"x-client": "opencode"}, "opencode", False), + ({"user-agent": "codex-cli/1.2.3"}, "codex", False), + ({"user-agent": "claude-code/2.0"}, "claude-code", True), + ({"user-agent": "cursor/1.0"}, "cursor", True), + ({}, None, True), + ({"user-agent": "some-unknown-sdk/1.0"}, None, True), + # CLIENT_UA_MAP matches by substring, so a wrapper that embeds the + # opencode UA is classified as opencode and excluded with it. + ({"user-agent": "acme-wrapper opencode/1.0"}, "opencode", False), + ], +) +def test_only_the_reported_harness_is_excluded( + headers: dict[str, str], expected_client: str | None, supported: bool +) -> None: + """The exclusion keys on the client name the proxy already resolves.""" + assert classify_client(headers) == expected_client + assert openai_tool_search_client_supported(classify_client(headers)) is supported + + +def test_a_similar_client_name_does_not_match() -> None: + """The exclusion set is exact membership on the resolved client name. + + Substring matching happens upstream in ``CLIENT_UA_MAP``; this pins that the + set itself does not widen a name that already classified. + """ + assert openai_tool_search_client_supported("opencode-fork") is True + assert openai_tool_search_client_supported("open") is True + assert openai_tool_search_client_supported("opencode") is False + + +def test_request_headers_decide_the_outbound_tools_payload() -> None: + """End of the route: real request headers in, final Responses tools out. + + This is the symptom the issue reports. An opencode request must not find an + injected ``{"type": "tool_search"}`` tool it cannot execute, and every other + client must still get the deferral it got before. + """ + tools = _tool_payload() + + opencode = Headers({"user-agent": "opencode/0.4.2", "content-type": "application/json"}) + forwarded = inject_tool_search_deferral_openai( + tools, + TOOL_SEARCH_MODEL, + client=classify_client(opencode), + ) + assert forwarded is tools + assert not any(tool.get("type") == "tool_search" for tool in forwarded) + assert not any(tool.get("defer_loading") for tool in forwarded) + + codex = Headers({"user-agent": "codex-cli/1.2.3", "content-type": "application/json"}) + forwarded = inject_tool_search_deferral_openai( + tools, + TOOL_SEARCH_MODEL, + client=classify_client(codex), + ) + assert forwarded is tools + assert not any(tool.get("type") == "tool_search" for tool in forwarded) + assert not any(tool.get("defer_loading") for tool in tools) + + +def test_websocket_and_http_header_shapes_classify_alike() -> None: + """The WebSocket path builds a plain dict from the same multidict.""" + multidict = Headers({"user-agent": "opencode/0.4.2"}) + + assert classify_client(multidict) == "opencode" + assert classify_client(dict(multidict)) == "opencode" + + +def test_native_responses_compressor_scopes_the_exclusion_per_call() -> None: + """The flag rides one request; a later request is unaffected by an earlier one.""" + seen: list[dict[str, object]] = [] + handler = object.__new__(OpenAIHandlerMixin) + + async def _run_compression(fn, *, timeout): # noqa: ANN001, ANN202 + return fn() + + def _compress(payload, *, model, request_id, **kwargs): # noqa: ANN001, ANN202 + seen.append(kwargs) + return (payload, False, 0, [], "no-op", 0, 0, 0, {}) + + handler._run_compression_in_executor = _run_compression + handler._compress_openai_responses_payload = _compress + + async def _run() -> None: + await handler._compress_openai_responses_payload_in_executor( + {"input": "hello"}, + model=TOOL_SEARCH_MODEL, + request_id="req-opencode", + client="opencode", + ) + await handler._compress_openai_responses_payload_in_executor( + {"input": "hello"}, + model=TOOL_SEARCH_MODEL, + request_id="req-codex", + ) + + asyncio.run(_run()) + + assert [{key: value for key, value in call.items() if key != "timing"} for call in seen] == [ + {"client": "opencode"}, + {"client": None}, + ] + + +def test_supported_clients_send_no_extra_compressor_argument() -> None: + """A compressor override written before this change keeps its exact signature.""" + calls: list[str] = [] + handler = object.__new__(OpenAIHandlerMixin) + + async def _run_compression(fn, *, timeout): # noqa: ANN001, ANN202 + return fn() + + def _narrow_compress(payload, *, model, request_id, timing=None): # noqa: ANN001, ANN202 + calls.append(request_id) + return (payload, False, 0, [], "no-op", 0, 0, 0, {}) + + handler._run_compression_in_executor = _run_compression + handler._compress_openai_responses_payload = _narrow_compress + + asyncio.run( + handler._compress_openai_responses_payload_in_executor( + {"input": "hello"}, + model=TOOL_SEARCH_MODEL, + request_id="req-codex", + ) + ) + + assert calls == ["req-codex"] + + +def test_a_narrow_compressor_override_still_works_for_an_excluded_client() -> None: + """The retry drops the optional keywords rather than failing the request.""" + calls: list[str] = [] + handler = object.__new__(OpenAIHandlerMixin) + + async def _run_compression(fn, *, timeout): # noqa: ANN001, ANN202 + return fn() + + def _narrow_compress(payload, *, model, request_id): # noqa: ANN001, ANN202 + calls.append(request_id) + return (payload, False, 0, [], "no-op", 0, 0, 0, {}) + + handler._run_compression_in_executor = _run_compression + handler._compress_openai_responses_payload = _narrow_compress + + asyncio.run( + handler._compress_openai_responses_payload_in_executor( + {"input": "hello"}, + model=TOOL_SEARCH_MODEL, + request_id="req-opencode", + client="opencode", + ) + ) + + assert calls == ["req-opencode"] + + +def test_native_responses_compressor_reraises_internal_type_error() -> None: + """An internal compressor TypeError is propagated without a signature retry.""" + calls = 0 + handler = object.__new__(OpenAIHandlerMixin) + sentinel = TypeError("internal compressor failure") + + async def _run_compression(fn, *, timeout): # noqa: ANN001, ANN202 + return fn() + + def _compress(payload, *, model, request_id, client, timing=None): # noqa: ANN001, ANN202 + nonlocal calls + calls += 1 + raise sentinel + + handler._run_compression_in_executor = _run_compression + handler._compress_openai_responses_payload = _compress + + with pytest.raises(TypeError) as exc_info: + asyncio.run( + handler._compress_openai_responses_payload_in_executor( + {"input": "hello"}, + model=TOOL_SEARCH_MODEL, + request_id="req-opencode", + client="opencode", + ) + ) + + assert exc_info.value is sentinel + assert calls == 1 + + +class _ResponsesRequest: + method = "POST" + url = SimpleNamespace(path="/custom/v1/responses", query="") + + def __init__(self, headers: dict[str, str]) -> None: + self.headers = headers + + async def body(self) -> bytes: + return json.dumps({"model": TOOL_SEARCH_MODEL, "input": "hello"}).encode() + + +class _UpstreamClient: + async def request(self, **kwargs): # noqa: ANN001, ANN201 + request = httpx.Request(kwargs["method"], kwargs["url"]) + return httpx.Response(200, request=request, json={"ok": True}) + + +def _passthrough_handler(seen: list[dict[str, object]]) -> OpenAIHandlerMixin: + handler = object.__new__(OpenAIHandlerMixin) + handler.config = SimpleNamespace( + optimize=True, + compress_passthrough=True, + openai_extra_headers=None, + ) + handler.http_client = _UpstreamClient() + handler.http_client_h1 = None + + async def _next_request_id() -> str: + return "req-test" + + async def _compress(payload, *, model, request_id, **kwargs): # noqa: ANN001, ANN202 + seen.append(kwargs) + return (payload, False, 0, [], "no-op", 0, len(json.dumps(payload)), 0, {}) + + handler._next_request_id = _next_request_id + handler._compress_openai_responses_payload_in_executor = _compress + return handler + + +def test_custom_base_path_excludes_the_reported_harness() -> None: + seen: list[dict[str, object]] = [] + + asyncio.run( + _passthrough_handler(seen).handle_passthrough( + _ResponsesRequest({"user-agent": "opencode/0.4.2", "content-type": "application/json"}), + "https://api.example.com", + ) + ) + + assert seen == [{"client": "opencode"}] + + +def test_custom_base_path_leaves_other_clients_alone() -> None: + seen: list[dict[str, object]] = [] + + asyncio.run( + _passthrough_handler(seen).handle_passthrough( + _ResponsesRequest( + {"user-agent": "codex-cli/1.2.3", "content-type": "application/json"} + ), + "https://api.example.com", + ) + ) + + assert seen == [{"client": "codex"}] + + +# --- production route: the native /v1/responses handler ----------------------- + +_OPENAI_OK_RESPONSE = { + "id": "resp_test", + "object": "response", + "status": "completed", + "model": TOOL_SEARCH_MODEL, + "output": [], + "usage": {"input_tokens": 10, "output_tokens": 2}, +} + + +class _NativeCapturingTransport(httpx.AsyncBaseTransport): + def __init__(self) -> None: + self.call_count = 0 + + async def handle_async_request(self, request: httpx.Request) -> httpx.Response: + self.call_count += 1 + async for _ in request.stream: + pass + return httpx.Response(200, json=_OPENAI_OK_RESPONSE) + + +def _native_responses_client(): # noqa: ANN202 + """Boot the real app and observe what the Responses compressor is handed. + + The transport and the spy are installed after the lifespan runs, because + startup builds the proxy's HTTP clients. + """ + pytest.importorskip("fastapi") + from fastapi.testclient import TestClient + + from headroom.proxy.server import ProxyConfig, create_app + + config = ProxyConfig( + optimize=True, + 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, + image_optimize=False, + ) + app = create_app(config) + seen: list[dict[str, object]] = [] + + # Loopback client so the proxy-token middleware treats this as a local call. + with TestClient(app, client=("127.0.0.1", 50000)) as client: + proxy = app.state.proxy + transport = _NativeCapturingTransport() + proxy.http_client = httpx.AsyncClient(transport=transport) + proxy.http_client_h1 = httpx.AsyncClient(transport=transport) + + original = proxy._compress_openai_responses_payload_in_executor + + async def _spy(payload, **kwargs): # noqa: ANN001, ANN202 + seen.append({k: v for k, v in kwargs.items() if k not in {"model", "request_id"}}) + return await original(payload, **kwargs) + + proxy._compress_openai_responses_payload_in_executor = _spy + yield client, seen, transport + + +def _responses_body() -> dict[str, object]: + return {"model": TOOL_SEARCH_MODEL, "input": "hello", "tools": _tool_payload()} + + +@pytest.mark.parametrize( + ("user_agent", "expected"), + [ + ("opencode/0.4.2", {"client": "opencode"}), + ("codex-cli/1.2.3", {"client": "codex"}), + ], +) +def test_native_responses_route_carries_the_client_decision( + user_agent: str, expected: dict[str, object] +) -> None: + """Drives POST /v1/responses on the real app, not a handler method in isolation. + + Deleting the kwargs splat at the native call site leaves every other test in + this file green; this one fails. + """ + for client, seen, transport in _native_responses_client(): + response = client.post( + "/v1/responses", + headers={ + "content-type": "application/json", + "authorization": "Bearer sk-test-0000000000000000000000000000000000000000000", + "user-agent": user_agent, + }, + json=_responses_body(), + ) + + assert transport.call_count == 1, response.text + assert response.status_code == 200, response.text + assert seen, "the Responses compressor was never reached" + assert {k: v for k, v in seen[0].items() if k != "timing"} == expected + + +# --- production route: the Codex WebSocket handler --------------------------- + + +@pytest.mark.parametrize( + ("user_agent", "expected"), + [ + ("opencode/0.4.2", {"client": "opencode"}), + ("codex-cli/1.2.3", {"client": "codex"}), + ], +) +def test_websocket_route_carries_the_client_decision( + user_agent: str, expected: dict[str, object] +) -> None: + """The WS frame path resolves the client the same way the HTTP path does. + + Reuses the repo's existing Codex WS harness so the real + ``handle_openai_responses_ws`` ingress runs, rather than asserting the + wiring structurally. + """ + import sys + from unittest.mock import patch + + from tests.test_openai_codex_ws_lifecycle import ( + _DummyOpenAIHandler, + _FakeUpstream, + _FakeWebSocket, + _first_frame, + _make_fake_websockets_module, + ) + + upstream = _FakeUpstream( + [ + json.dumps({"type": "response.created", "response": {"id": "r_1"}}), + json.dumps({"type": "response.completed", "response": {"id": "r_1"}}), + ] + ) + client_ws = _FakeWebSocket( + frames=[_first_frame()], + headers={"authorization": "Bearer test", "user-agent": user_agent}, + ) + handler = _DummyOpenAIHandler() + handler.config.optimize = True + + seen: list[dict[str, object]] = [] + + def _compress(payload, *, model, request_id, **kwargs): # noqa: ANN001, ANN202 + seen.append(kwargs) + return (payload, False, 0, [], "router_no_compression", 10, 10) + + handler._compress_openai_responses_payload = _compress + + with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}): + asyncio.run(handler.handle_openai_responses_ws(client_ws)) + + assert seen, "the Responses compressor was never reached on the WS path" + assert {k: v for k, v in seen[0].items() if k != "timing"} == expected From 5c561bd913ea60fad2c3c53f4b65e679e7d248d0 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Sat, 8 Aug 2026 12:03:57 +0530 Subject: [PATCH 016/138] fix(onnx): stop ONNX thread pools from spinning idle cores (#2495) (#2540) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Fixes #2495 (tokensave / the proxy using ~100% of all cores). ONNX Runtime's intra-op (and inter-op) thread pools **spin-wait on every core between inferences** by default. Headroom is a long-lived process that keeps ONNX models loaded — the kompress code compressor ("tokensave"), the image technique/SigLIP routers, and the memory embedder — so once a model is loaded, its idle thread pool keeps every core busy even when no compression is running. That matches the report exactly: CPU climbs to ~100% of all cores "after a period of time" and the whole machine slows down, with no obvious trigger. `create_cpu_session_options` (the shared factory every CPU ONNX session goes through) configured threads and the memory arena but never touched spinning, so ORT's default (spin enabled) was in effect everywhere. ## Fix Disable intra-op and inter-op thread spinning in `create_cpu_session_options` so idle ORT threads block instead of spin-waiting. This applies to every ONNX session built through the factory (kompress + the image routers). It: - is **best-effort per key** (wrapped in try/except) so an older ORT build that doesn't recognize a config key still creates a session; - is **overridable** via `HEADROOM_ONNX_ALLOW_SPINNING=1` for a dedicated/batch box that wants ORT's peak-throughput spinning; - does not change active-inference throughput meaningfully — blocking threads wake on new work with only microsecond-scale latency, which is the recommended setting for a server/proxy with idle periods. The memory embedder already builds its own options with `intra_op_num_threads=1`; this change is orthogonal and additionally quiets its idle spinning if it were ever routed through the factory. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/onnx_runtime.py`: add `ONNX_ALLOW_SPINNING_ENV` + `onnx_thread_spinning_enabled()`; disable `session.intra_op.allow_spinning` / `session.inter_op.allow_spinning` in `create_cpu_session_options` unless spinning is explicitly re-enabled. - `tests/test_onnx_runtime.py`: spinning is disabled by default (both keys), `HEADROOM_ONNX_ALLOW_SPINNING=1` re-enables it, an explicit `0` disables it, and a config key an older ORT rejects doesn't break session creation. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text $ python -m pytest tests/test_onnx_runtime.py -q 11 passed # with the fix reverted the new symbols don't exist, so the spinning tests # fail at import — the pre-fix factory left ORT's spinning at its (enabled) default $ uvx ruff@0.15.17 check headroom/onnx_runtime.py tests/test_onnx_runtime.py All checks passed! $ uvx mypy@1.20.2 --ignore-missing-imports headroom/onnx_runtime.py Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12, project venv (`uv sync --extra proxy`, onnxruntime 1.23.2 installed), `uvx ruff@0.15.17` / `uvx mypy@1.20.2`, pytest in the venv. - Exact command / steps: built a real `onnxruntime.SessionOptions` via `create_cpu_session_options(ort)` and read back `session.intra_op.allow_spinning` / `session.inter_op.allow_spinning`; repeated with `HEADROOM_ONNX_ALLOW_SPINNING=1`. - Observed result: by default both keys read back `"0"` (spinning disabled); with `HEADROOM_ONNX_ALLOW_SPINNING=1` neither key is set (ORT's default spinning restored). Against a real ORT the pre-fix factory set neither key, so ORT's default (spinning enabled) applied — the idle all-cores burn. Ran against the actual module and real onnxruntime. - Not tested: a live multi-hour VS Code + Claude session measuring CPU before/after (the spinning-disable is the documented ORT remedy for idle-CPU in a long-lived process; the config change itself is verified end to end against real ORT). ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable --------- Co-authored-by: JD Davis --- headroom/onnx_runtime.py | 31 +++++++++++++++++++++ tests/test_onnx_runtime.py | 57 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+) diff --git a/headroom/onnx_runtime.py b/headroom/onnx_runtime.py index aa3e7f7b2..8157c2202 100644 --- a/headroom/onnx_runtime.py +++ b/headroom/onnx_runtime.py @@ -13,6 +13,7 @@ logger = logging.getLogger(__name__) # Override for the CPU memory-arena default below: "1"/"true" forces the # arena ON, "0"/"false" forces it OFF, unset/"auto" uses the platform default. ONNX_CPU_ARENA_ENV = "HEADROOM_ONNX_CPU_ARENA" +ONNX_ALLOW_SPINNING_ENV = "HEADROOM_ONNX_ALLOW_SPINNING" _TRUTHY = frozenset({"1", "true", "yes", "on"}) _FALSY = frozenset({"0", "false", "no", "off"}) @@ -46,6 +47,22 @@ def cpu_arena_enabled() -> bool: return sys.platform == "win32" +def onnx_thread_spinning_enabled() -> bool: + """Whether ONNX Runtime intra/inter-op thread pools may spin-wait when idle. + + ORT's thread pools spin-wait on every core between inferences by default, so + a long-lived proxy that keeps compression/embedding models loaded pegs all + cores even while completely idle — the machine slows to a crawl after a + while (#2495). Default to blocking idle threads (spinning off). Set + ``HEADROOM_ONNX_ALLOW_SPINNING=1`` to restore ORT's spinning for peak + throughput on a dedicated/batch box. + """ + override = _env_flag(ONNX_ALLOW_SPINNING_ENV) + if override is not None: + return override + return False + + # Pin model artifacts to immutable commit SHAs so a changed or compromised # upstream HuggingFace repo cannot be pulled silently (supply-chain integrity). # Repos not listed here fall back to the floating default ref. Set @@ -159,6 +176,20 @@ def create_cpu_session_options( if inter_op_num_threads is not None: sess_options.inter_op_num_threads = inter_op_num_threads + if not onnx_thread_spinning_enabled(): + # ORT's thread pools spin-wait on all cores between inferences by + # default, so idle-but-loaded models peg every core in a long-lived + # proxy (#2495). Make idle threads block instead. Best-effort: older ORT + # builds may not recognize a key. + for spin_key in ( + "session.intra_op.allow_spinning", + "session.inter_op.allow_spinning", + ): + try: + sess_options.add_session_config_entry(spin_key, "0") + except Exception: + pass + if not cpu_arena_enabled(): if hasattr(sess_options, "enable_cpu_mem_arena"): sess_options.enable_cpu_mem_arena = False diff --git a/tests/test_onnx_runtime.py b/tests/test_onnx_runtime.py index 63d29abe6..3e7f6f949 100644 --- a/tests/test_onnx_runtime.py +++ b/tests/test_onnx_runtime.py @@ -2,10 +2,12 @@ import os import sys from headroom.onnx_runtime import ( + ONNX_ALLOW_SPINNING_ENV, ONNX_CPU_ARENA_ENV, cpu_arena_enabled, create_cpu_session_options, hf_entry_known_absent, + onnx_thread_spinning_enabled, ) @@ -15,6 +17,10 @@ class _FakeSessionOptions: self.inter_op_num_threads = None self.enable_cpu_mem_arena = True self.enable_mem_pattern = True + self.config_entries: dict[str, str] = {} + + def add_session_config_entry(self, key: str, value: str) -> None: + self.config_entries[key] = value class _FakeOrt: @@ -26,6 +32,10 @@ class _FakeSessionOptionsWithoutToggles: self.intra_op_num_threads = None self.inter_op_num_threads = None + def add_session_config_entry(self, key: str, value: str) -> None: + # No config storage on this stand-in; ORT here just accepts the call. + return None + class _FakeOrtWithoutToggles: SessionOptions = _FakeSessionOptionsWithoutToggles @@ -108,6 +118,53 @@ def test_create_cpu_session_options_handles_older_session_options(monkeypatch): assert options.inter_op_num_threads is None +def test_thread_spinning_disabled_by_default(monkeypatch): + # #2495: ORT thread pools spin-wait on all cores between inferences, so a + # long-lived proxy pegs every core while idle. Disable spinning by default. + monkeypatch.delenv(ONNX_ALLOW_SPINNING_ENV, raising=False) + monkeypatch.delenv(ONNX_CPU_ARENA_ENV, raising=False) + + assert onnx_thread_spinning_enabled() is False + options = create_cpu_session_options(_FakeOrt) + assert options.config_entries.get("session.intra_op.allow_spinning") == "0" + assert options.config_entries.get("session.inter_op.allow_spinning") == "0" + + +def test_thread_spinning_env_can_reenable(monkeypatch): + monkeypatch.setenv(ONNX_ALLOW_SPINNING_ENV, "1") + monkeypatch.delenv(ONNX_CPU_ARENA_ENV, raising=False) + + assert onnx_thread_spinning_enabled() is True + options = create_cpu_session_options(_FakeOrt) + assert "session.intra_op.allow_spinning" not in options.config_entries + assert "session.inter_op.allow_spinning" not in options.config_entries + + +def test_thread_spinning_env_explicit_off(monkeypatch): + monkeypatch.setenv(ONNX_ALLOW_SPINNING_ENV, "0") + + assert onnx_thread_spinning_enabled() is False + options = create_cpu_session_options(_FakeOrt) + assert options.config_entries.get("session.intra_op.allow_spinning") == "0" + + +def test_spinning_disable_is_best_effort_on_older_ort(monkeypatch): + # An ORT build that rejects the config key must not break session creation. + monkeypatch.delenv(ONNX_ALLOW_SPINNING_ENV, raising=False) + monkeypatch.setattr(sys, "platform", "linux") + + class _RejectingSessionOptions(_FakeSessionOptions): + def add_session_config_entry(self, key: str, value: str) -> None: + raise RuntimeError(f"unknown config key: {key}") + + class _RejectingOrt: + SessionOptions = _RejectingSessionOptions + + # Must not raise. + options = create_cpu_session_options(_RejectingOrt) + assert options.enable_cpu_mem_arena is False + + def _write_fake_hf_cache( root: str, repo_id: str, revision: str, *, no_exist_files: list[str] ) -> None: From 7f6950be34e29304deae0fa5138b852491b092fe Mon Sep 17 00:00:00 2001 From: Rod Boev Date: Sat, 8 Aug 2026 02:55:02 -0400 Subject: [PATCH 017/138] fix(anthropic): strip first-party tool search on custom upstreams (#2539) ## Description Third-party Anthropic-compatible upstreams can reject Headroom-routed Claude requests before generation starts because the forwarded `tools[]` array still contains the first-party Anthropic server tool type `tool_search_tool_regex_20251119`. That path is valid when the upstream really is Anthropic, but DeepSeek-style Anthropic-compatible gateways reject it with a 400 and never reach model execution. This change strips first-party Anthropic `tool_search_tool_*` entries only when Headroom forwards an Anthropic-wire request to a third-party upstream selected through `anthropic_api_url`. Direct Anthropic behavior stays intact, and unrelated typed or untyped tools keep their existing forwarding contract. Closes #2526. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - add a narrow Anthropic helper that strips first-party `tool_search_tool_*` entries from client-supplied tool lists when the outbound target is a third-party Anthropic-compatible upstream - wire the sanitizer into the Anthropic handler's third-party forwarding path without changing the first-party `HEADROOM_TOOL_SEARCH` injector branch - add focused helper coverage for third-party stripping, first-party preservation, and typed-tool negative space - add a production-path regression through `handle_anthropic_messages()` that captures the custom-upstream request body and verifies the sanitizer wiring ## Testing - [x] Unit tests pass (`uv run pytest tests/test_issue_746_tool_search.py tests/test_anthropic_stage_timings.py -q`) - [x] Linting passes (`uv run ruff check headroom/proxy/helpers.py headroom/proxy/handlers/anthropic.py tests/test_issue_746_tool_search.py tests/test_anthropic_stage_timings.py`) - [ ] Type checking passes (`uv run mypy headroom`) - [x] New tests added for new functionality when applicable - [x] Manual testing performed ### Test Output ```text uv run pytest tests/test_issue_746_tool_search.py tests/test_anthropic_stage_timings.py -q 50 passed in 0.72s uv run ruff check headroom/proxy/helpers.py headroom/proxy/handlers/anthropic.py tests/test_issue_746_tool_search.py tests/test_anthropic_stage_timings.py All checks passed! uv run ruff format headroom/proxy/helpers.py headroom/proxy/handlers/anthropic.py tests/test_issue_746_tool_search.py tests/test_anthropic_stage_timings.py --check 4 files already formatted git diff --check (no output) ``` ## Real Behavior Proof - Environment: focused Headroom worktree with Anthropic-wire regression tests - Exact command / steps: use the issue reproduction at https://github.com/headroomlabs-ai/headroom/issues/2526, then run the focused helper and handler tests; the handler regression calls `handle_anthropic_messages()` with a DeepSeek-compatible upstream and captures the outbound request body - Observed result: the base repro printed `FAIL issue2526 third-party sanitize -> [{'type': 'tool_search_tool_regex_20251119', 'name': 'tool_search_tool_regex'}, {'name': 'Bash', 'description': 'run a command', 'input_schema': {}}]`, while the head repro printed `PASS issue2526 third-party sanitize -> [{'name': 'Bash', 'description': 'run a command', 'input_schema': {}}]`; the handler-level test captured the same removal while preserving `Bash` and `web_search_20250305`, and the combined focused run passed 50 tests - Not tested: live DeepSeek account on this host ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A - proxy forwarding change only. ## Additional Notes - `CHANGELOG.md` stays untouched because Headroom's release automation generates it from conventional commits. - The narrow slice strips only first-party Anthropic server tool-search entries on third-party Anthropic-compatible upstreams. It does not invent or translate third-party search-tool semantics. --------- Co-authored-by: JerrettDavis Co-authored-by: JD Davis --- headroom/proxy/handlers/anthropic.py | 32 ++++++++++++++--- headroom/proxy/helpers.py | 25 ++++++++++++++ tests/test_anthropic_stage_timings.py | 50 +++++++++++++++++++++++++++ tests/test_issue_746_tool_search.py | 49 ++++++++++++++++++++++++++ 4 files changed, 152 insertions(+), 4 deletions(-) diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index 7e01915e5..26e9f68ee 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -2405,6 +2405,29 @@ class AnthropicHandlerMixin: optimized_tokens = tokenizer.count_messages(body["messages"]) tokens_saved = max(0, original_tokens - optimized_tokens) + from headroom.proxy.helpers import ( + anthropic_first_party_tool_search_supported, + strip_first_party_tool_search_tools_for_third_party_upstream, + ) + + _anthropic_target_base_url = upstream_base_url or self.ANTHROPIC_API_URL + _third_party_anthropic_upstream = provider_name == "anthropic" and ( + not anthropic_first_party_tool_search_supported(_anthropic_target_base_url) + ) + if _third_party_anthropic_upstream: + _tools_before_strip = body.get("tools") + _tools_after_strip = strip_first_party_tool_search_tools_for_third_party_upstream( + _tools_before_strip, + _anthropic_target_base_url, + ) + if _tools_after_strip is not _tools_before_strip: + body["tools"] = _tools_after_strip + tools = _tools_after_strip + tags["third_party_tool_search_stripped"] = max( + 0, + len(_tools_before_strip) - len(_tools_after_strip), + ) + # Server-side Tool Search (on by default; HEADROOM_TOOL_SEARCH=0 opts # out — the `coding` savings profile already seeded it on via # seed_proxy_env_defaults, so default-on here just makes the same @@ -2420,12 +2443,13 @@ class AnthropicHandlerMixin: # bytes are excluded from context this turn); the response usage confirms it. # # FIRST-PARTY ANTHROPIC ONLY: the tool_search_tool_* type + defer_loading - # here use the first-party Claude API shape (GA, no beta header). Bedrock - # (``anthropic_backend``) and Vertex/gateway providers gate tool search - # differently, so scope the injection to provider "anthropic" over the - # direct API and leave those paths untouched. + # here use the first-party Claude API shape (GA, no beta header). Custom + # Anthropic-compatible gateways reject that shape, so third-party routes + # strip client-originated tool_search_tool_* entries above and skip + # Headroom's own injector here. if ( provider_name == "anthropic" + and anthropic_first_party_tool_search_supported(_anthropic_target_base_url) and getattr(self, "anthropic_backend", None) is None and os.environ.get("HEADROOM_TOOL_SEARCH", "1").strip().lower() in ("1", "true", "yes", "on", "auto") diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py index c36daa3d2..26e360552 100644 --- a/headroom/proxy/helpers.py +++ b/headroom/proxy/helpers.py @@ -2284,6 +2284,31 @@ _TOOL_SEARCH_DEFAULT_NAME = "tool_search_tool_regex" _TOOL_SEARCH_MIN_TOOLS = 12 +def anthropic_first_party_tool_search_supported(api_base_url: str | None) -> bool: + """Return whether Anthropic server-side tool search is valid for this upstream.""" + from headroom.providers.claude.runtime import is_custom_anthropic_base_url + + return not is_custom_anthropic_base_url(api_base_url) + + +def strip_first_party_tool_search_tools_for_third_party_upstream( + tools: Any, + api_base_url: str | None, +) -> Any: + """Remove first-party Anthropic tool-search tools when forwarding to a custom upstream.""" + if not isinstance(tools, list) or anthropic_first_party_tool_search_supported(api_base_url): + return tools + filtered = [ + tool + for tool in tools + if not ( + isinstance(tool, dict) + and str(tool.get("type", "")).startswith(_TOOL_SEARCH_TOOL_TYPE_PREFIX) + ) + ] + return filtered if len(filtered) != len(tools) else tools + + def inject_tool_search_deferral( tools: Any, *, diff --git a/tests/test_anthropic_stage_timings.py b/tests/test_anthropic_stage_timings.py index 93b3e1944..56019d096 100644 --- a/tests/test_anthropic_stage_timings.py +++ b/tests/test_anthropic_stage_timings.py @@ -101,18 +101,24 @@ class _DummyAnthropicHandler(AnthropicHandlerMixin): get_last_original_messages=lambda: [], get_last_forwarded_messages=lambda: [], record_request=lambda *a, **k: None, + update_from_response=lambda *a, **k: None, ), resolve_tracker=lambda *a, **k: SimpleNamespace( + _cached_token_count=0, get_frozen_message_count=lambda: 0, get_last_original_messages=lambda: [], get_last_forwarded_messages=lambda: [], record_request=lambda *a, **k: None, + update_from_response=lambda *a, **k: None, ), ) async def _next_request_id(self) -> str: return "req-anth-test" + async def _record_request_outcome(self, outcome) -> None: + return None + def _extract_tags(self, headers): return {} @@ -287,6 +293,50 @@ def test_anthropic_no_optimize_preserves_client_tool_order(): assert [tool["name"] for tool in forwarded_body["tools"]] == ["Read", "Bash"] +def test_anthropic_third_party_upstream_strips_tool_search_tools(): + tools = [ + {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}, + { + "name": "Bash", + "description": "run a command", + "input_schema": {"type": "object", "properties": {}}, + }, + {"type": "web_search_20250305", "name": "web_search"}, + ] + request = _build_request( + { + "model": "claude-3-5-sonnet-latest", + "max_tokens": 100, + "messages": [{"role": "user", "content": "use a tool"}], + "tools": tools, + }, + {"authorization": "Bearer sk-ant-api-test"}, + ) + handler = _DummyAnthropicHandler() + + import headroom.tokenizers as _tk + + orig_get = _tk.get_tokenizer + _tk.get_tokenizer = lambda model: _DummyTokenizer() + try: + response = anyio.run( + handler.handle_anthropic_messages, + request, + "https://api.deepseek.com/anthropic", + ) + finally: + _tk.get_tokenizer = orig_get + + assert response.status_code == 200 + _, forwarded_url, _, forwarded_body = handler.captured + assert forwarded_url == "https://api.deepseek.com/anthropic/v1/messages" + assert forwarded_body["tools"] == [tools[1], tools[2]] + assert not any( + str(tool.get("type", "")).startswith("tool_search_tool_") + for tool in forwarded_body["tools"] + ) + + def test_anthropic_http_invalid_body_still_emits_stage_timings(stage_log_capture): async def receive(): # Invalid JSON — produces ``ValueError`` from ``_read_request_json``. diff --git a/tests/test_issue_746_tool_search.py b/tests/test_issue_746_tool_search.py index 74c0d4b9a..76c31d0ae 100644 --- a/tests/test_issue_746_tool_search.py +++ b/tests/test_issue_746_tool_search.py @@ -176,7 +176,9 @@ from headroom.proxy.helpers import ( # noqa: E402 _TOOL_SEARCH_DEFAULT_NAME, _TOOL_SEARCH_DEFAULT_TYPE, _TOOL_SEARCH_MIN_TOOLS, + anthropic_first_party_tool_search_supported, inject_tool_search_deferral, + strip_first_party_tool_search_tools_for_third_party_upstream, ) @@ -259,6 +261,53 @@ def test_non_dict_and_typed_tools_stay_resident() -> None: assert len(typed) == 1 and typed[0].get("defer_loading") is None +def test_third_party_upstream_strips_first_party_tool_search_from_headroom_issue_2526() -> None: + tools = [ + {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}, + {"name": "Bash", "description": "run a command", "input_schema": {}}, + {"type": "web_search_20250305", "name": "web_search"}, + ] + out = strip_first_party_tool_search_tools_for_third_party_upstream( + tools, + "https://api.deepseek.com/anthropic", + ) + assert out is not tools + assert [tool.get("name") for tool in out if isinstance(tool, dict)] == ["Bash", "web_search"] + assert all( + not str(tool.get("type", "")).startswith("tool_search_tool_") + for tool in out + if isinstance(tool, dict) + ) + + +def test_first_party_anthropic_preserves_client_tool_search_entry() -> None: + tools = [ + {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}, + {"name": "Bash", "description": "run a command", "input_schema": {}}, + ] + assert anthropic_first_party_tool_search_supported("https://api.anthropic.com") + assert ( + strip_first_party_tool_search_tools_for_third_party_upstream( + tools, + "https://api.anthropic.com", + ) + is tools + ) + + +@pytest.mark.parametrize( + ("api_base_url", "expected_supported"), + [ + ("https://api.anthropic.com", True), + ("https://api.anthropic.com/v1", True), + ("https://api.deepseek.com/anthropic", False), + ("http://127.0.0.1:8787", False), + ], +) +def test_third_party_or_first_party_matrix(api_base_url: str, expected_supported: bool) -> None: + assert anthropic_first_party_tool_search_supported(api_base_url) is expected_supported + + # --------------------------------------------------------------------------- # PascalCase clients (Claude Code). The core-tool exemption is spelled in # lowercase, so an exact-match comparison never fired for Claude Code: every From 91d6bf33cde777b541375fb182d4479fdd78f81b Mon Sep 17 00:00:00 2001 From: Romulo Reis Date: Sat, 8 Aug 2026 13:23:25 -0300 Subject: [PATCH 018/138] perf(subscription): skip transcripts older than the window in compute_window_tokens (#2861) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problem `compute_window_tokens()` walks **every** `.jsonl` under `~/.claude/projects` and runs `json.loads()` on **every line**, only to discard the entries that fall outside `[start_ts, end_ts)`. `subscription/tracker._poll_loop` calls it every **300 s**, so the cost is paid continuously and grows with the user's history. On one long-running install this meant **1,973 files / 1.1 GB / 261,003 lines re-parsed every 5 minutes** — about 316 GB of JSON parsing per day. The user-visible symptom is worse than the CPU bill: the poll pins **100 % CPU with zero open connections** for ~12 s. That is exactly the signature external watchdogs use to detect a runaway loop, so the proxy kept being **restarted while it was doing scheduled work** (13 restarts / 13.5 CPU-hours on that host before we traced it with `py-spy`). Stack captured during one of those episodes: ``` raw_decode (json/decoder.py:356) decode (json/decoder.py:337) loads (json/__init__.py:346) compute_window_tokens (headroom/subscription/session_tracking.py:127) _compute_window_tokens_for_snapshot (headroom/subscription/tracker.py:872) _maybe_poll (headroom/subscription/tracker.py:731) _poll_loop (headroom/subscription/tracker.py:693) ``` ## Fix Transcripts are append-only and chronological, so a file whose `mtime` predates the window start cannot contain an entry inside the window. One guard before opening the file: ```python try: if path.stat().st_mtime < start_ts: continue except OSError: continue ``` ## Measurement Same install, same 5 h window, before vs after: | | files read | lines parsed | time | result | |---|---|---|---|---| | before | 1,973 | 261,003 | **12.1 s** | `weighted_token_equivalent = 741388.0` | | after | 14 (1,959 skipped) | 4,246 | **0.39 s** | `weighted_token_equivalent = 741388.0` | **Identical result, 31× faster.** In production the process CPU peak over a full poll cycle dropped from 100 % to 10 %. ## Notes - Behaviour is unchanged: the guard only skips files that provably cannot contribute. - A further optimisation (not included here, to keep the change minimal) is to read active transcripts backwards and stop at the first entry older than `start_ts`. The `mtime` guard already removes ~99 % of the cost. - Reproduced on 0.25.0, 0.27.0 and confirmed present in current `main`. Co-authored-by: romulomorgan Co-authored-by: Claude --- headroom/subscription/session_tracking.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/headroom/subscription/session_tracking.py b/headroom/subscription/session_tracking.py index 9ace709fa..e9a1cacfd 100644 --- a/headroom/subscription/session_tracking.py +++ b/headroom/subscription/session_tracking.py @@ -136,6 +136,16 @@ def compute_window_tokens(start_ts: float, end_ts: float) -> WindowTokens: unattributed = WindowTokens() for path in find_transcript_files(): + # Skip transcripts that cannot contain entries inside the window. + # Transcripts are append-only and chronological, so a file whose mtime is + # older than the window start has no entry within [start_ts, end_ts). + # Without this guard every poll json.loads()es every line of every + # transcript under ~/.claude/projects. + try: + if path.stat().st_mtime < start_ts: + continue + except OSError: + continue for line in _read_transcript_lines(path): try: entry: dict[str, Any] = json.loads(line) From 675d13f08d42455c8fa17bda878c1a11b905cee4 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Sun, 9 Aug 2026 10:09:24 -0700 Subject: [PATCH 019/138] fix(proxy/openai): run response hooks on Responses, and bill their re-drives (#2872) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Responses path runs `run_request_hooks` but never `run_response_hooks` — only `handle_openai_chat` does. So a turn hook can shrink a Responses turn and then never be asked to resolve what the model did about it: the model's injected tool call goes straight to a client that has no such tool. That asymmetry is why tool-belt deferral has to be disabled wholesale on the Responses API, which is the surface Codex uses. ## 1. Wire the response side Mirrors the chat-completions block. **Buffered path only**, for the same reason CCR already forces `stream:false` when it needs to intercept: you cannot re-drive a turn whose bytes are already flowing. ## 2. Honour `stream_safe_only` on the Responses request path It was the one hook call site that ignored the flag. A re-driving hook would run its shrink on a streamed turn and then have no response side to finish it — latent until (1) lands, live afterwards. `stream` is not a parameter of `_compress_openai_responses_payload`, but the payload it is compressing carries the flag. It is read **before** CCR may force `stream:false` further down, so this is the client's request rather than the effective one — conservative in the safe direction: at worst a CCR-buffered turn misses a saving, never a stranded tool call. Fold-only hooks that declare `stream_safe = True` are unaffected. ## 3. Bill what the re-drives cost Both handlers read usage from the **final** upstream response, so every intermediate call a hook made was free as far as Headroom was concerned. For a token-saving feature that is not a rounding error. A tool-search reload is a whole extra model call; counting only the last one lets the feature hide its own overhead behind the saving it is claiming, and the numbers come out better than the truth. `TurnHookUsage` accumulates input/output/cached across re-drives; both HTTP paths fold it into their totals. The two surfaces report the same three quantities under different names (`prompt_tokens` vs `input_tokens`), so the key pair is passed in. Expect measured cost to go **up** and savings percentage to go **down** on any deployment running a re-driving hook. That is the correction, not a regression. ## Also: restore the body after the hooks A re-drive rewrites `body[input]` / `body[messages]` / `body[tools]` so the next upstream call carries the hook's turn. Everything downstream — CCR's `_responses_input_to_items(body["input"])`, usage accounting, observability — is describing the request the *client* made, not the proxy's internal detour. Without the restore, a turn that both reloaded a tool and hit CCR retrieval hands CCR the proxy's synthetic items. The chat path had the same leak (`body["messages"]` stayed rewritten); both are fixed the same way. ## Known gap A re-drive on the custom backend path (`send_openai_message`) is still not folded into that request's accounting — its usage is recorded elsewhere. Commented at the call site rather than silently skipped. ## Blast radius **Inert unless a turn hook is registered**, so no behaviour change for a stock OSS proxy. `TurnHookUsage` starts at zero and stays there on every path that does not re-drive. ## Verification - `tests/test_turn_hook_usage.py` — 5 new tests: per-surface key names, accumulation across rounds, negative counts floored not subtracted, and that an unreadable shape still counts the call (a silent zero there looks exactly like "the hook cost nothing") - 434 passing across `turn_hook`, `extension`, `tool_search`, `responses` and `openai_chat` suites - `ruff check` + `ruff format` clean 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) --- headroom/proxy/handlers/openai.py | 279 +++++++++++++++++++++++++- tests/test_turn_hook_usage.py | 316 ++++++++++++++++++++++++++++++ 2 files changed, 590 insertions(+), 5 deletions(-) create mode 100644 tests/test_turn_hook_usage.py diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py index 59945befd..a7d22449b 100644 --- a/headroom/proxy/handlers/openai.py +++ b/headroom/proxy/handlers/openai.py @@ -187,6 +187,101 @@ def _header_get(headers: dict[str, str], name: str) -> str | None: return None +#: Usage field names per OpenAI surface. Same three quantities, two spellings. +CHAT_USAGE_KEYS = { + "input_key": "prompt_tokens", + "output_key": "completion_tokens", + "details_key": "prompt_tokens_details", +} +RESPONSES_USAGE_KEYS = { + "input_key": "input_tokens", + "output_key": "output_tokens", + "details_key": "input_tokens_details", +} + + +class TurnHookUsage: + """Upstream calls a turn hook caused that nothing else will account for. + + A hook that re-drives the model (``call_model``) makes real, billed requests. + The handler's usage block reads exactly ONE response — the original, or + whichever the hook returned in its place, because the handler swaps + ``response`` for it. Every other upstream call on that turn is spend no + surface records. + + The protocol is therefore two-sided, and both halves are required: + + * :meth:`record` every upstream response as it arrives, original included. + * :meth:`settle` with the response the usage block will read. + + ``settle`` removes that one response's contribution, so what remains is + exactly the delta the handler must add. Recording only the re-drives and + adding them unconditionally — the first version of this — double-counted the + re-drive the handler had just promoted to ``response`` and dropped the + original entirely: one re-drive billed ``B + B`` instead of ``A + B``. + + Matching is by object identity, because the handler hands back the very + object it recorded. A hook that synthesises a brand new response matches + nothing and nothing is subtracted, which over-counts rather than under — + the safe direction for a bill. + """ + + __slots__ = ("_seen", "input_tokens", "output_tokens", "cache_read_tokens", "extra_calls") + + def __init__(self) -> None: + self._seen: list[tuple[int, Any, int, int, int]] = [] + self.input_tokens = 0 + self.output_tokens = 0 + self.cache_read_tokens = 0 + self.extra_calls = 0 + + def record( + self, + payload: Any, + *, + input_key: str, + output_key: str, + details_key: str, + ) -> None: + """Note one upstream response. Never raises: a hook must not be able to + 500 a request by returning an odd shape.""" + usage = payload.get("usage") if isinstance(payload, dict) else None + + def _int(value: Any) -> int: + try: + return max(int(value), 0) + except (TypeError, ValueError): + return 0 + + if isinstance(usage, dict): + details = usage.get(details_key) + cached = _int(details.get("cached_tokens")) if isinstance(details, dict) else 0 + entry = ( + id(payload), + payload, + _int(usage.get(input_key)), + _int(usage.get(output_key)), + cached, + ) + else: + entry = (id(payload), payload, 0, 0, 0) + self._seen.append(entry) + + def settle(self, final: Any) -> None: + """Total everything except ``final``, which the usage block will read.""" + self.input_tokens = self.output_tokens = self.cache_read_tokens = 0 + self.extra_calls = 0 + dropped = False + for _ident, payload, tin, tout, cached in self._seen: + if not dropped and payload is final: + dropped = True + continue + self.extra_calls += 1 + self.input_tokens += tin + self.output_tokens += tout + self.cache_read_tokens += cached + + def _sanitize_forwarded_response_headers( headers: httpx.Headers | dict[str, str], *extra_names: str, @@ -2404,7 +2499,19 @@ class OpenAIHandlerMixin: tools=working.get("tools"), config=getattr(self, "config", None), ) - run_request_hooks(_req_ctx) + # Streaming turns get fold-only hooks, same rule as the + # chat-completions path. A hook that defers work to `on_response` + # cannot run here: the response side is wired on the buffered branch + # only, so on a real stream the shrink would land with no reload and + # the model's injected tool call would be streamed straight to a + # client that has no such tool. `stream` is not a parameter of this + # method, but the payload it is compressing carries the flag. + # + # Read before CCR may force `stream:false` further down, so this is + # the client's request rather than the effective one — conservative + # in the safe direction: at worst a buffered-by-CCR turn misses a + # saving, never a stranded tool call. + run_request_hooks(_req_ctx, stream_safe_only=bool(payload.get("stream"))) if _req_ctx.tools is not working.get("tools"): working["tools"] = _req_ctx.tools # A hook may also fold the messages (replace or in-place). Write back a @@ -3917,6 +4024,14 @@ class OpenAIHandlerMixin: # Turn hooks (opt-in extensions) may inspect the turn # or re-drive the model before we hand back the # response. Inert when no hook is registered. + # + # Known gap: unlike the two HTTP paths, a re-drive + # here is NOT folded into this request's token + # accounting — `api_call_fn` goes through the custom + # backend, whose usage is recorded elsewhere. Wire a + # TurnHookUsage through `send_openai_message` before + # relying on cost numbers from a backend deployment + # that runs re-driving hooks. from headroom.proxy.turn_hooks import ( TurnContext, run_response_hooks, @@ -4138,12 +4253,20 @@ class OpenAIHandlerMixin: run_response_hooks, ) + # Tokens the hook's own re-drives cost. Stays at zero unless a + # hook actually calls the model again. + _hook_usage = TurnHookUsage() + if _registered_turn_hooks() and response.status_code == 200: try: _hook_resp_json = response.json() except (ValueError, json.JSONDecodeError): _hook_resp_json = None if isinstance(_hook_resp_json, dict): + # The call we already made counts too. If the hook + # replaces the response, this original is the one nobody + # else will read. + _hook_usage.record(_hook_resp_json, **CHAT_USAGE_KEYS) _hook_ctx = _TurnContext( provider="openai", model=str(model), @@ -4154,12 +4277,31 @@ class OpenAIHandlerMixin: async def _hook_call_model(_msgs): body["messages"] = _msgs + if _hook_ctx.tools is not None: + body["tools"] = _hook_ctx.tools _r = await self._retry_request("POST", url, headers, body) - return _r.json() + _r_json = _r.json() + _hook_usage.record(_r_json, **CHAT_USAGE_KEYS) + return _r_json - _hook_final = await run_response_hooks( - _hook_ctx, _hook_resp_json, _hook_call_model - ) + # Same restore as the Responses path: the re-drive rewrote + # body so the next upstream call carried the hook's turn, + # but everything below is accounting for the request the + # client made, not the proxy's internal detour. + _hook_body_messages = body.get("messages") + _hook_body_tools = body.get("tools") + try: + _hook_final = await run_response_hooks( + _hook_ctx, _hook_resp_json, _hook_call_model + ) + finally: + if _hook_body_messages is not None: + body["messages"] = _hook_body_messages + if _hook_body_tools is not None: + body["tools"] = _hook_body_tools + # Drop whichever response the usage block below reads; + # what is left is the spend nothing else records. + _hook_usage.settle(_hook_final) if _hook_final is not _hook_resp_json: response = httpx.Response( status_code=200, @@ -4320,6 +4462,20 @@ class OpenAIHandlerMixin: f"[{request_id}] Failed to extract cached tokens from OpenAI response: {e}" ) + # Add what the hook's re-drives cost — see the matching block on + # the Responses path. A tool-search reload is a whole extra model + # call; counting only the last one lets the feature hide its own + # overhead behind the saving it is claiming. + if _hook_usage.extra_calls: + total_input_tokens += _hook_usage.input_tokens + output_tokens += _hook_usage.output_tokens + cache_read_tokens += _hook_usage.cache_read_tokens + logger.debug( + f"[{request_id}] turn hook: {_hook_usage.extra_calls} unaccounted call(s): " + f"+{_hook_usage.input_tokens} in / " + f"+{_hook_usage.output_tokens} out" + ) + # Update prefix cache tracker for next turn cache_write_tokens = _infer_openai_cache_write_tokens( total_input_tokens, @@ -5226,6 +5382,104 @@ class OpenAIHandlerMixin: status_code=response.status_code, metadata={"stream": stream, "auth_mode": auth_mode.value}, ) + # Turn hooks, response side. `_compress_openai_responses_payload` + # already runs `run_request_hooks` for this surface, so without + # this block a hook could shrink a Responses turn and then never + # be asked to resolve what the model did about it — a deferral + # with no reload, which strands the model's call at a client + # that has no such tool. Mirrors the chat-completions wiring in + # `handle_openai_chat`; buffered path only, for the same reason + # CCR forces `stream:false` above: you cannot re-drive a turn + # whose bytes are already flowing. + from headroom.proxy.turn_hooks import ( + TurnContext as _RespTurnContext, + ) + from headroom.proxy.turn_hooks import ( + registered_turn_hooks as _resp_registered_hooks, + ) + from headroom.proxy.turn_hooks import ( + run_response_hooks as _run_resp_hooks, + ) + + # Tokens the hook's own re-drives cost. Stays at zero unless a + # hook actually calls the model again. + _resp_hook_usage = TurnHookUsage() + + if _resp_registered_hooks() and response.status_code == 200: + try: + _resp_hook_json = response.json() + except (ValueError, json.JSONDecodeError): + _resp_hook_json = None + if isinstance(_resp_hook_json, dict): + # The Responses API names the turn's items `input`; + # fall back to `messages` so an OpenAI-compatible + # upstream that accepts either still round-trips. + _resp_hook_usage.record(_resp_hook_json, **RESPONSES_USAGE_KEYS) + _resp_key = "input" if body.get("input") is not None else "messages" + _resp_hook_ctx = _RespTurnContext( + provider="openai", + model=str(model), + messages=body.get(_resp_key) or [], + tools=body.get("tools"), + config=self.config, + ) + + async def _resp_hook_call_model( + _items: list[dict[str, Any]], + _key: str = _resp_key, + ) -> dict[str, Any]: + # Re-drive with the hook's items. Tools may also + # have grown (a reload makes resolved schemas + # callable), so send those back too. + body[_key] = _items + if _resp_hook_ctx.tools is not None: + body["tools"] = _resp_hook_ctx.tools + _rr = await self._retry_request( + "POST", + url, + headers, + body, + request_id=request_id, + forwarder_name="openai_responses_turn_hook", + path_for_log=url, + ) + _rr_json = _rr.json() + _resp_hook_usage.record(_rr_json, **RESPONSES_USAGE_KEYS) + return _rr_json + + # A re-drive rewrites body[input]/body[tools] so the + # next upstream call carries the hook's items. Put + # the client's turn back afterwards: everything below + # — CCR's `_responses_input_to_items(body["input"])`, + # usage accounting, observability — is describing the + # request the client actually made, not the proxy's + # internal detour. Without this, a turn that both + # reloaded a tool and hit CCR retrieval would hand + # CCR the hook's synthetic items. + _resp_body_input = body.get(_resp_key) + _resp_body_tools = body.get("tools") + try: + _resp_hook_final = await _run_resp_hooks( + _resp_hook_ctx, _resp_hook_json, _resp_hook_call_model + ) + finally: + if _resp_body_input is not None: + body[_resp_key] = _resp_body_input + if _resp_body_tools is not None: + body["tools"] = _resp_body_tools + # Drop whichever response the usage block below reads. + _resp_hook_usage.settle(_resp_hook_final) + if _resp_hook_final is not _resp_hook_json: + response = httpx.Response( + status_code=200, + headers={ + k: v + for k, v in response.headers.items() + if k.lower() not in ("content-encoding", "content-length") + }, + content=json.dumps(_resp_hook_final).encode(), + ) + total_latency = (time.time() - start_time) * 1000 total_input_tokens = original_tokens # fallback @@ -5254,6 +5508,21 @@ class OpenAIHandlerMixin: f"[{request_id}] Failed to extract cached tokens from OpenAI passthrough response: {e}" ) + # Add what the hook's re-drives cost. The usage read above + # describes the last upstream call; a hook that re-drove the + # model made earlier ones that were just as billed. Leaving + # them out lets a token-saving feature hide its own overhead, + # so cost and savings both read better than they are. + if _resp_hook_usage.extra_calls: + total_input_tokens += _resp_hook_usage.input_tokens + output_tokens += _resp_hook_usage.output_tokens + cache_read_tokens += _resp_hook_usage.cache_read_tokens + logger.debug( + f"[{request_id}] turn hook: {_resp_hook_usage.extra_calls} unaccounted call(s): " + f"+{_resp_hook_usage.input_tokens} in / " + f"+{_resp_hook_usage.output_tokens} out" + ) + # CCR Response Handling: intercept headroom_retrieve tool # calls server-side so a Responses API function_call the # downstream caller can't resolve (e.g. Strands, or a diff --git a/tests/test_turn_hook_usage.py b/tests/test_turn_hook_usage.py new file mode 100644 index 000000000..b2e2abebb --- /dev/null +++ b/tests/test_turn_hook_usage.py @@ -0,0 +1,316 @@ +"""A turn hook's re-drives are billed calls and must reach token accounting. + +A hook that resolves an injected tool call re-drives the model. Both OpenAI +handlers read usage from exactly ONE response — the original, or whichever the +hook returned in its place, because the handler swaps `response` for it. Every +other upstream call on that turn is spend nothing else records. + +Getting that wrong is not a rounding error for a token-saving feature: it lets +the feature hide its own overhead behind the saving it claims. The first version +of this recorded only the re-drives and added them unconditionally, so a single +re-drive billed `B + B` and dropped the original `A` entirely. The handler tests +at the bottom are what catch that class of mistake; the unit tests above them +cannot, because the bug lives in how the accumulator composes with the response +swap rather than in the accumulator itself. +""" + +from __future__ import annotations + +import json +from typing import Any + +import httpx +import pytest +import respx + +from headroom.proxy.handlers.openai import ( + CHAT_USAGE_KEYS, + RESPONSES_USAGE_KEYS, + TurnHookUsage, +) + +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 +from headroom.proxy.turn_hooks import clear_turn_hooks, register_turn_hook # noqa: E402 + +# --- unit: the accumulator ----------------------------------------------- + + +def _chat(prompt: int, completion: int, cached: int = 0) -> dict[str, Any]: + return { + "usage": { + "prompt_tokens": prompt, + "completion_tokens": completion, + "prompt_tokens_details": {"cached_tokens": cached}, + } + } + + +def test_no_redrive_adds_nothing() -> None: + """The common path: one upstream call, which the usage block reads itself.""" + u = TurnHookUsage() + original = _chat(100, 10) + u.record(original, **CHAT_USAGE_KEYS) + u.settle(original) + assert u.extra_calls == 0 + assert (u.input_tokens, u.output_tokens, u.cache_read_tokens) == (0, 0, 0) + + +def test_one_redrive_leaves_the_original_to_add() -> None: + """A + B billed; the block will read B; so A is the delta.""" + u = TurnHookUsage() + a, b = _chat(100, 10, 60), _chat(150, 20, 90) + u.record(a, **CHAT_USAGE_KEYS) + u.record(b, **CHAT_USAGE_KEYS) + u.settle(b) + assert u.extra_calls == 1 + assert (u.input_tokens, u.output_tokens, u.cache_read_tokens) == (100, 10, 60) + + +def test_two_redrives_leave_the_original_and_the_middle() -> None: + u = TurnHookUsage() + a, b, c = _chat(100, 10), _chat(150, 20), _chat(200, 30) + for r in (a, b, c): + u.record(r, **CHAT_USAGE_KEYS) + u.settle(c) + assert u.extra_calls == 2 + assert (u.input_tokens, u.output_tokens) == (250, 30) + + +def test_hook_that_keeps_the_original_still_pays_for_the_redrive() -> None: + """Re-drove, then returned the original anyway. B was still billed.""" + u = TurnHookUsage() + a, b = _chat(100, 10), _chat(150, 20) + u.record(a, **CHAT_USAGE_KEYS) + u.record(b, **CHAT_USAGE_KEYS) + u.settle(a) + assert u.extra_calls == 1 + assert (u.input_tokens, u.output_tokens) == (150, 20) + + +def test_synthesised_response_matches_nothing_and_over_counts() -> None: + """Nothing is subtracted when the hook invents a response. Over-counting is + the safe direction for a bill; under-counting is the bug this file exists + for.""" + u = TurnHookUsage() + a, b = _chat(100, 10), _chat(150, 20) + u.record(a, **CHAT_USAGE_KEYS) + u.record(b, **CHAT_USAGE_KEYS) + u.settle({"usage": {"prompt_tokens": 999}}) + assert u.extra_calls == 2 + assert u.input_tokens == 250 + + +def test_responses_shape_uses_its_own_key_names() -> None: + u = TurnHookUsage() + a = { + "usage": { + "input_tokens": 400, + "output_tokens": 40, + "input_tokens_details": {"cached_tokens": 300}, + } + } + b = {"usage": {"input_tokens": 500, "output_tokens": 50}} + u.record(a, **RESPONSES_USAGE_KEYS) + u.record(b, **RESPONSES_USAGE_KEYS) + u.settle(b) + assert (u.input_tokens, u.output_tokens, u.cache_read_tokens) == (400, 40, 300) + + # Chat keys must not read a Responses payload: a silent 0 looks exactly like + # "the hook cost nothing". + v = TurnHookUsage() + v.record(a, **CHAT_USAGE_KEYS) + v.record(b, **CHAT_USAGE_KEYS) + v.settle(b) + assert v.input_tokens == 0 + assert v.extra_calls == 1, "the call still happened even if its shape was unreadable" + + +def test_never_raises_on_a_shape_it_does_not_recognise() -> None: + """A hook must not be able to 500 a request by returning something odd.""" + u = TurnHookUsage() + for payload in ( + None, + {}, + [], + "not a dict", + {"usage": None}, + {"usage": "nope"}, + {"usage": {"prompt_tokens": None, "completion_tokens": "x"}}, + {"usage": {"prompt_tokens": -5, "prompt_tokens_details": "nope"}}, + ): + u.record(payload, **CHAT_USAGE_KEYS) + u.settle(object()) + assert u.extra_calls == 8 + assert (u.input_tokens, u.output_tokens, u.cache_read_tokens) == (0, 0, 0) + + +# --- handler level: what the unit tests above structurally cannot see ----- + + +class _RedriveOnce: + """Minimal hook: re-drive the model exactly once, return the new response.""" + + name = "test_redrive" + stream_safe = False + + def __init__(self) -> None: + self.calls = 0 + + def on_request(self, ctx: Any) -> None: # pragma: no cover - nothing to do + return None + + async def on_response(self, ctx: Any, response: Any, call_model: Any) -> Any: + if self.calls: + return None + self.calls += 1 + return await call_model(ctx.messages) + + +@pytest.fixture +def _no_hooks(): + clear_turn_hooks() + yield + clear_turn_hooks() + + +def _app_and_outcomes(monkeypatch): + """App with a spy on the outcome record, which is where the billed token + counts land (`provider_input_tokens` / `output_tokens`).""" + app = create_app( + ProxyConfig( + optimize=False, + cache_enabled=False, + rate_limit_enabled=False, + cost_tracking_enabled=False, + log_requests=False, + ) + ) + app.dependency_overrides[require_loopback] = lambda: None + outcomes: list[Any] = [] + proxy = app.state.proxy + + # Patched on the type, so the bound-call self arrives as the first argument. + async def _spy(_self, outcome, *a, **kw): + outcomes.append(outcome) + + monkeypatch.setattr(type(proxy), "_record_request_outcome", _spy, raising=True) + return app, outcomes + + +@respx.mock +def test_chat_bills_the_original_plus_the_redrive(monkeypatch, _no_hooks) -> None: + """A=100/10, B=150/20 -> 250 in / 30 out. + + The bug this pins reported 300/40 (B twice, A dropped). + """ + register_turn_hook(_RedriveOnce()) + app, outcomes = _app_and_outcomes(monkeypatch) + + bodies = [ + { + "id": "a", + "choices": [ + {"message": {"role": "assistant", "content": "A"}, "finish_reason": "stop"} + ], + "usage": {"prompt_tokens": 100, "completion_tokens": 10}, + }, + { + "id": "b", + "choices": [ + {"message": {"role": "assistant", "content": "B"}, "finish_reason": "stop"} + ], + "usage": {"prompt_tokens": 150, "completion_tokens": 20}, + }, + ] + sent = iter(bodies) + respx.post("https://api.openai.com/v1/chat/completions").mock( + side_effect=lambda request: httpx.Response(200, json=next(sent)) + ) + + with TestClient(app) as client: + r = client.post( + "/v1/chat/completions", + json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]}, + headers={"authorization": "Bearer sk-test"}, + ) + assert r.status_code == 200 + assert json.loads(r.content)["id"] == "b", "the hook's response is what the client gets" + assert outcomes, "an outcome must be recorded" + o = outcomes[-1] + assert o.provider_input_tokens == 250, f"want A+B=250, got {o.provider_input_tokens}" + assert o.output_tokens == 30, f"want A+B=30, got {o.output_tokens}" + + +@respx.mock +def test_responses_bills_the_original_plus_the_redrive(monkeypatch, _no_hooks) -> None: + """Same arithmetic on /v1/responses, whose usage keys differ.""" + register_turn_hook(_RedriveOnce()) + app, outcomes = _app_and_outcomes(monkeypatch) + + bodies = [ + { + "id": "a", + "output": [{"type": "message", "role": "assistant", "content": []}], + "usage": {"input_tokens": 400, "output_tokens": 40}, + }, + { + "id": "b", + "output": [{"type": "message", "role": "assistant", "content": []}], + "usage": {"input_tokens": 500, "output_tokens": 50}, + }, + ] + sent = iter(bodies) + respx.post("https://api.openai.com/v1/responses").mock( + side_effect=lambda request: httpx.Response(200, json=next(sent)) + ) + + with TestClient(app) as client: + r = client.post( + "/v1/responses", + json={ + "model": "gpt-4o", + "input": [{"type": "message", "role": "user", "content": []}], + "stream": False, + }, + headers={"authorization": "Bearer sk-test"}, + ) + assert r.status_code == 200 + assert outcomes, "an outcome must be recorded" + o = outcomes[-1] + assert o.provider_input_tokens == 900, f"want A+B=900, got {o.provider_input_tokens}" + assert o.output_tokens == 90, f"want A+B=90, got {o.output_tokens}" + + +@respx.mock +def test_no_hook_registered_bills_exactly_the_one_call(monkeypatch, _no_hooks) -> None: + """The regression guard in the other direction: with no hook, accounting must + be untouched — this whole mechanism has to be inert on a stock proxy.""" + app, outcomes = _app_and_outcomes(monkeypatch) + respx.post("https://api.openai.com/v1/chat/completions").mock( + return_value=httpx.Response( + 200, + json={ + "id": "a", + "choices": [ + {"message": {"role": "assistant", "content": "A"}, "finish_reason": "stop"} + ], + "usage": {"prompt_tokens": 100, "completion_tokens": 10}, + }, + ) + ) + + with TestClient(app) as client: + r = client.post( + "/v1/chat/completions", + json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]}, + headers={"authorization": "Bearer sk-test"}, + ) + assert r.status_code == 200 + o = outcomes[-1] + assert o.provider_input_tokens == 100 + assert o.output_tokens == 10 From e0870ef931e5ea6cc6cb52551f5d80cd9e3dc715 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Sun, 9 Aug 2026 15:42:12 -0700 Subject: [PATCH 020/138] feat(beacon): hourly R2 compaction, per-strategy savings, and a stack that reports (#2853) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three beacon changes bundled because they are one story: the corpus got too slow to query, and then too coarse to answer the question it was collected for. ## 1. Hourly compaction (`deploy/beacon`) The beacon writes one ~1 KB object per heartbeat — **64,987 on 2026-08-06** and climbing. A full analysis `pull` was ~100k HTTPS round trips for 95 MB: minutes of pure per-object latency. Listing the bucket alone took 88 seconds. Moving the query server-side does not help — R2 SQL reads only Iceberg tables, and a pile of tiny files is the pathological case for every query engine. Compaction is the fix, and it is Iceberg's own answer to the same problem. An hourly cron collapses each **complete** hour of `sessions/` into one `rollup/dt=…/hh=…/data.ndjson`, keeping the highest-`seq` heartbeat per `(install, session)`. | measured on `dt=2026-08-06/hh=14` | before | after | |---|---|---| | objects | 3,938 | **1** | | rows | 3,938 | **1,061** | | analysis `pull` | minutes | **seconds** | Hourly rather than daily because every R2 binding call is a subrequest: a day is ~65k, an hour is ~4k. Newest-first, so a backlog drains from the present backwards and live data never starves behind it; a failing hour is logged and skipped rather than blocking every older hour behind it. **Raw objects are never deleted**, so any rollup is rebuildable by deleting it. Backfill runs to the **oldest surviving raw day**, not a fixed window. A fixed lookback strands everything older than it the moment analysis stops reading `sessions/`: the raw objects are still there, but nothing would ever compact them, so they disappear from every report. `oldestRawDay()` finds that floor in one delimited LIST, and the rollup listing starts from it — so the work is bounded by retention rather than by total history. Three failure modes the tests pin down, because each one is silent: - A **failed `get`** is transient, so the hour throws and writes nothing. A rollup is built once and trusted forever, so a short read would quietly become the permanent record. - A **corrupt record** loses only itself. This Worker wrote that content with `JSON.stringify`; it will never become valid, so blocking on it strands the hour instead of the record. - An **empty hour** writes an `empty` marker. Without one the hour stays "missing" and is re-listed on every run forever. `test-rollup.mjs` asserts the Worker's dedup picks exactly the same rows as the analysis-side `QUALIFY`. If those two ever disagree the reports go quietly wrong rather than loudly broken, which is why that check exists. Its stub paginates at 3 keys so the list cursor loop — load-bearing at the real ~4,000 objects/hour — runs in every case. ## 2. Per-strategy savings (`compression.by_strategy`) `compression.transforms` counts *invocations*, which cannot distinguish a compressor that saved 60% from one that ran constantly and saved nothing. The fleet's top transform by count contributes an unknown share of `tokens.saved`. It is worse than that in practice. Transform labels are slugged with `split(":", 1)[0]`, so every `router::` label collapses into a single `router` bucket. On 2026-08-08 that bucket held **19.1 M of the day's transform counts, across 8,528 of 9,616 sessions** — the compressors that do most of the work are indistinguishable from each other, by name as well as by yield: | transform | n | sessions | |---|---|---| | `router` | 19,108,118 | 8,528 | | `anthropic` | 688,124 | 4,734 | | `output_shaper` | 548,017 | 1,120 | No question about which strategy is earning its keep can be answered from that, which is what this field is for. The measurement already existed. `PrometheusMetrics.record_compression` is the configured `CompressionObserver` and already accumulates `tokens_saved_by_strategy` on the hot path — the numbers just never left the process. This forwards from that one chokepoint rather than adding a second observer and a second measurement pass. The paths that have **no** observer configured (MCP server, LangGraph, Strands hooks, the transform pipeline) get `BeaconCompressionObserver` passed directly. Compression runs on the executor thread *before* that request's outcome reaches `record()`, so events are **staged** into module state and drained by the next outcome. Staging is what makes two things true at once: - The first turn of a session still reports its numbers — otherwise every session's opening turn, and any session short enough to be one turn, would report nothing. - A compression event **never opens a session**. An abandoned request would otherwise emit a phantom `turns=0` row with all-zero tokens, inflating fleet session and install counts. Staging takes a dedicated mutex the request path never touches, so the fan-out stays off the aggregator's lock and `record_compression` keeps its "synchronous + lock-free" contract. ```json "by_strategy": [ {"strategy": "code_aware", "n": 1, "tokens_in": 800, "tokens_out": 800}, {"strategy": "smart_crusher", "n": 2, "tokens_in": 1500, "tokens_out": 700} ] ``` A **list of records, sorted by strategy** — not an object keyed by strategy. Keyed shapes change type as keys accumulate: DuckDB infers a STRUCT under ~24 keys and a MAP over it, so the analysis query breaks on the day the fleet picks up a 25th strategy. Sorted so heartbeats are byte-comparable. **These do not sum to `tokens.saved`,** and the field comment says so: strategies compose (the router routes, a strategy runs inside it) so the same text is measured more than once. A row means "of what this strategy was handed, it removed this much" — a per-strategy yield, not a share of the total. A strategy that saved nothing still appears; dropping it would make every strategy look effective. ## 3. `headroom.stack` `resource_attributes()` was called with no arguments at its one call site, so `headroom.stack` was absent from **all 24,040 sessions** in the corpus while `detect_stack` sat unused — dead code on both ends of a wire nobody connected. The fleet was unsegmentable by agent, which is the question the corpus is asked most often. Environment detection alone is not enough. It answers `wrap_claude` only under `headroom wrap`; every install that points an agent at a persistent proxy — the common deployment — reports `proxy`, which segments nothing. The per-request `X-Headroom-Stack` slugs are the only signal that names the harness there, so `record_stack()` stages them the same way and feeds `detect_stack`'s `by_stack` branch: ``` 9x wrap_claude, 1x wrap_cursor -> wrap_claude (dominant harness wins) 5x wrap_claude, 5x wrap_cursor -> mixed no per-request signal -> proxy (environment fallback) junk slug -> dropped before staging ``` ## Privacy The strategy string is slugged through the same `_safe_slug` as skip reasons and capped at `MAX_STRATEGIES`, because the observer protocol takes a free string and an extension could otherwise invent keys per request. Stack slugs are normalized and capped the same way. **Deliberately not collected:** the tool names in `smart_crush::`. Those are user-defined MCP identifiers and can name internal tooling (`acme_deploy_prod`). They stay stripped by the existing `split(":", 1)[0]`, and this PR does not widen it. No new key was needed in `worker.js` — `by_strategy` nests under the already-allowlisted `compression`, and `headroom.stack` was already in `ALLOWED_RESOURCE`. Nothing here deletes or rewrites existing data: the Worker only ever writes, `sessions/` is never pruned by it, and readers merge old and new shapes with `union_by_name`, so pre-change heartbeats keep reading with the new fields null. ## Verification - `python -m headroom.telemetry.session` — self-check covers staging, the no-phantom-session case, drain exhaustiveness, a 0%-yield strategy staying visible, the cardinality cap, slug safety, and dominant/mixed/junk stack resolution - `node test-rollup.mjs /tmp/hr` — 3,938 real corpus objects → 1,061 sessions in 1 object, plus the pagination, partial-read, corrupt-record, empty-hour and `oldestRawDay` cases - 51 passing in `test_compression_observability`, `test_prometheus_obs_counters`, `test_telemetry_context`, `test_compression_strategy_outcomes` - Consumer side exists and is checked: `beacon.sh by_strategy` in headroom-beacon-stats reads the field end to end (sessions, installs, invocations, tokens in/out, yield %), verified against a synthetic parquet for the cases that matter — aggregation across installs, a 0%-yield strategy staying visible, pre-field sessions dropping out rather than erroring. It is guarded on the column, so it prints an instruction instead of a binder error until a release carrying this PR reaches the fleet. - Deployed and running against the live corpus on the `5 * * * *` trigger 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) --- deploy/beacon/package.json | 5 + deploy/beacon/test-rollup.mjs | 214 +++++++++++++ deploy/beacon/worker.js | 190 +++++++++++- deploy/beacon/wrangler.toml | 18 ++ headroom/integrations/langchain/langgraph.py | 7 +- headroom/integrations/mcp/server.py | 14 +- headroom/integrations/strands/hooks.py | 7 +- headroom/proxy/prometheus_metrics.py | 32 +- headroom/telemetry/session.py | 305 +++++++++++++++++++ headroom/transforms/pipeline.py | 8 +- 10 files changed, 785 insertions(+), 15 deletions(-) create mode 100644 deploy/beacon/package.json create mode 100644 deploy/beacon/test-rollup.mjs diff --git a/deploy/beacon/package.json b/deploy/beacon/package.json new file mode 100644 index 000000000..b1913f3bd --- /dev/null +++ b/deploy/beacon/package.json @@ -0,0 +1,5 @@ +{ + "name": "headroom-beacon", + "private": true, + "type": "module" +} diff --git a/deploy/beacon/test-rollup.mjs b/deploy/beacon/test-rollup.mjs new file mode 100644 index 000000000..3878ee2d4 --- /dev/null +++ b/deploy/beacon/test-rollup.mjs @@ -0,0 +1,214 @@ +/** + * Self-check for scheduled()'s hourly compaction. node test-rollup.mjs [dir] + * + * The one thing that must never drift: rollupHour() and the QUALIFY in + * headroom-beacon-stats/beacon.sh have to agree on which heartbeat wins. If + * they disagree the reports get quietly wrong rather than loudly broken, so + * this asserts the JS picks exactly the max-seq row per (install, session). + * + * Point it at a directory of real beacon objects to check against the corpus: + * aws s3 sync s3://headroom-telemetry/sessions/dt=.../hh=.../ /tmp/hr/ ... + * node test-rollup.mjs /tmp/hr + * With no argument it runs on a small fixture and needs no network. + */ +import { readdirSync, readFileSync } from 'node:fs'; +import assert from 'node:assert/strict'; +import { oldestRawDay, rollupHour } from './worker.js'; + +// R2 returns at most 1000 keys per list page, so on a real hour (~4,000 +// objects) the cursor loop in rollupHour is load-bearing. The stub paginates at +// a deliberately tiny size so that loop is exercised by every case below: with +// a single-page stub, a regression that dropped the cursor would still print +// "ok" while silently rolling up only the first page of every hour. +const PAGE = 3; + +/** The slice of the R2 binding rollupHour uses, backed by a plain object. */ +function stubBucket(files, { failKeys = new Set() } = {}) { + const written = {}; + const reads = []; + return { + written, + reads, + list: async ({ prefix, cursor, delimiter }) => { + const keys = Object.keys(files) + .filter((k) => k.startsWith(prefix)) + .sort(); + if (delimiter) { + const seen = new Set(); + for (const k of keys) { + const cut = k.indexOf(delimiter, prefix.length); + if (cut >= 0) seen.add(k.slice(0, cut + 1)); + } + return { objects: [], delimitedPrefixes: [...seen], truncated: false }; + } + const start = cursor ? keys.indexOf(cursor) : 0; + const page = keys.slice(start, start + PAGE); + const next = start + PAGE; + return { + objects: page.map((key) => ({ key })), + truncated: next < keys.length, + cursor: next < keys.length ? keys[next] : undefined, + }; + }, + get: async (key) => { + reads.push(key); + if (failKeys.has(key)) throw new Error(`simulated R2 failure: ${key}`); + if (!(key in files)) return null; + return { text: async () => files[key] }; + }, + put: async (key, body) => { + written[key] = body; + }, + }; +} + +const beacon = (install, id, seq) => + JSON.stringify({ resource: { 'headroom.install_id': install }, session: { id, seq } }); + +const PART = 'dt=2026-08-06/hh=14'; + +/** Run rollupHour against a stub bucket and decode whatever it wrote. */ +async function run(files, opts = {}) { + const CORPUS = stubBucket(files, opts); + const spend = { read: 0 }; + let threw = null; + let out = null; + try { + out = await rollupHour({ CORPUS }, PART, spend); + } catch (err) { + threw = err; + } + const body = CORPUS.written[`rollup/${PART}/data.ndjson`]; + return { + threw, + spend, + wrote: out ? out.wrote : 0, + empty: `rollup/${PART}/empty` in CORPUS.written, + keys: Object.keys(CORPUS.written), + rows: body ? body.split('\n').map((l) => JSON.parse(l)) : [], + }; +} + +// 1. Highest seq wins, out-of-order input, one row per (install, session). +// More objects than PAGE, so the list cursor loop runs. +{ + const files = { + [`sessions/${PART}/a.json`]: [beacon('i1', 's1', 3), beacon('i1', 's2', 1)].join('\n'), + [`sessions/${PART}/b.json`]: beacon('i1', 's1', 9), + [`sessions/${PART}/c.json`]: beacon('i1', 's1', 7), + // Same session id under a different install must not collapse together. + [`sessions/${PART}/d.json`]: beacon('i2', 's1', 2), + [`sessions/${PART}/e.json`]: beacon('i1', 's1', 5), + }; + const { rows, spend, threw } = await run(files); + assert.equal(threw, null); + // 5 objects at PAGE=3 is two pages: proves the cursor loop, which is + // load-bearing at the real ~4,000 objects/hour. + assert.ok(Object.keys(files).length > PAGE, 'fixture must span pages'); + assert.equal(spend.read, 5, 'reads every object across every page'); + assert.equal(rows.length, 3, 'one row per (install, session)'); + const seq = Object.fromEntries( + rows.map((r) => [`${r.resource['headroom.install_id']} ${r.session.id}`, r.session.seq]) + ); + assert.deepEqual(seq, { 'i1 s1': 9, 'i1 s2': 1, 'i2 s1': 2 }); +} + +// 2. An unparseable record loses only itself. Content this Worker wrote with +// JSON.stringify never becomes valid later, so blocking the hour on it would +// strand the hour rather than one record. +{ + const files = { + [`sessions/${PART}/a.json`]: '{ this is not json', + [`sessions/${PART}/b.json`]: `\n${beacon('i1', 's1', 4)}\n`, + }; + const { rows, threw } = await run(files); + assert.equal(threw, null, 'corrupt content does not abandon the hour'); + assert.deepEqual(rows.map((r) => r.session.seq), [4], 'survives a corrupt object'); +} + +// 3. A failed get is transient, so the hour must NOT be written — a rollup is +// built once and then trusted forever, so a short read would silently become +// the permanent record. +{ + const files = { + [`sessions/${PART}/a.json`]: beacon('i1', 's1', 1), + [`sessions/${PART}/b.json`]: beacon('i1', 's2', 1), + }; + const { threw, keys } = await run(files, { + failKeys: new Set([`sessions/${PART}/b.json`]), + }); + assert.ok(threw, 'a failed get throws so the hour is retried'); + assert.deepEqual(keys, [], 'nothing written on a partial read'); +} + +// 4. Spend is reported even when the hour throws. Charging a flat guess instead +// lets a run that failed late overshoot the subrequest ceiling. +{ + const files = Object.fromEntries( + Array.from({ length: 7 }, (_, i) => [`sessions/${PART}/o${i}.json`, beacon('i1', `s${i}`, 1)]) + ); + const { threw, spend } = await run(files, { + failKeys: new Set([`sessions/${PART}/o6.json`]), + }); + assert.ok(threw); + assert.equal(spend.read, 7, 'caller sees real spend, not a guess'); +} + +// 5. An empty hour writes a marker, not a zero-byte NDJSON. Without it the hour +// stays "missing" and is re-listed on every run forever. +{ + const { rows, empty, keys } = await run({}); + assert.deepEqual(rows, []); + assert.ok(empty, 'empty hour leaves a marker'); + assert.ok( + keys.every((k) => !k.endsWith('.ndjson')), + 'no zero-byte ndjson for readers to special-case' + ); +} + +// 6. oldestRawDay floors the backfill. A fixed lookback window silently strands +// every hour older than it once analysis stopped reading sessions/. +{ + const CORPUS = stubBucket({ + 'sessions/dt=2026-08-03/hh=01/a.json': beacon('i1', 's1', 1), + 'sessions/dt=2026-08-06/hh=14/b.json': beacon('i1', 's2', 1), + 'sessions/dt=2026-08-07/hh=00/c.json': beacon('i1', 's3', 1), + }); + assert.equal(await oldestRawDay({ CORPUS }), '2026-08-03'); + assert.equal(await oldestRawDay({ CORPUS: stubBucket({}) }), null, 'empty bucket -> null'); +} + +// 7. Against real objects, if a directory was given: same answer as the QUALIFY +// in beacon.sh, which is `count(DISTINCT install||session)` rows, each +// carrying that pair's max seq. +const dir = process.argv[2]; +if (dir) { + const files = {}; + for (const f of readdirSync(dir).filter((f) => f.endsWith('.json'))) { + files[`sessions/${PART}/${f}`] = readFileSync(`${dir}/${f}`, 'utf8'); + } + const { rows, spend, threw } = await run(files); + assert.equal(threw, null); + + const expected = new Map(); + for (const text of Object.values(files)) { + for (const line of text.split('\n')) { + if (!line.trim()) continue; + const r = JSON.parse(line); + const k = `${r.resource?.['headroom.install_id']} ${r.session?.id}`; + expected.set(k, Math.max(expected.get(k) ?? -1, r.session?.seq ?? 0)); + } + } + assert.equal(spend.read, Object.keys(files).length); + assert.equal(rows.length, expected.size, 'row count matches DISTINCT sessions'); + for (const r of rows) { + const k = `${r.resource['headroom.install_id']} ${r.session.id}`; + assert.equal(r.session.seq, expected.get(k), `max seq for ${k}`); + } + console.log( + `real corpus: ${spend.read} objects -> ${rows.length} sessions in 1 object` + + ` (${Math.ceil(spend.read / PAGE)} list pages)` + ); +} + +console.log('ok'); diff --git a/deploy/beacon/worker.js b/deploy/beacon/worker.js index 15bc22d4f..7fea03001 100644 --- a/deploy/beacon/worker.js +++ b/deploy/beacon/worker.js @@ -121,7 +121,184 @@ function extract(payload) { return records; } +// ----------------------------------------------------------------- rollup -- +// +// The corpus is one object per heartbeat, ~1KB each — 65k on 2026-08-06 and +// climbing. DuckDB reads them correctly, but a full `pull` is ~100k HTTPS round +// trips for 95MB: minutes of pure per-object latency, no real bytes or compute. +// Listing the bucket alone took 88 seconds. +// +// This job collapses each COMPLETE hour into one object under rollup/, keeping +// only the highest-seq heartbeat per (install, session). One measured hour +// (dt=2026-08-06/hh=14): 3,938 objects and 3,938 rows in, 1 object and 1,061 +// rows out. Analysis reads rollup/**, never sessions/**. Raw is left exactly as +// written, so any rollup can be rebuilt by deleting it. +// +// Hourly rather than daily because every R2 binding call is a subrequest: a day +// is ~65k of them against a 10k-per-invocation ceiling, an hour is ~4k. + +const READ_BUDGET = 60000; // objects per run; see [limits] in wrangler.toml +// A get costs ~45ms of round trip and almost no CPU, so this is what decides +// whether a run finishes: at 20 an hour took ~3 minutes, against a 15-minute +// wall clock for a cron invocation. Raise it if an hour ever stops fitting. +const FANOUT = 100; // concurrent R2 gets + +const partition = (d) => + `dt=${d.toISOString().slice(0, 10)}/hh=${d.toISOString().slice(11, 13)}`; + +/** + * One hour of heartbeats -> one deduped NDJSON object. + * + * Returns `{ read, wrote }`. Spend is reported through the mutable `spend` + * accumulator so the caller still knows it even when this throws: the budget + * has to track real spend, and a flat guess lets a run that failed late + * overshoot the subrequest ceiling and get killed inside an hour that would + * otherwise have succeeded. + * + * Writes nothing unless the whole hour read cleanly. A rollup is built once and + * then treated as done forever, so a partial read would silently become the + * permanent record — better to write nothing and let the next run retry. + */ +export async function rollupHour(env, part, spend = { read: 0 }) { + const best = new Map(); + let failed = 0; // transient: retry the hour + let corrupt = 0; // permanent: record and move on + let cursor; + do { + const page = await env.CORPUS.list({ prefix: `sessions/${part}/`, cursor }); + for (let i = 0; i < page.objects.length; i += FANOUT) { + // allSettled, not all: one transient R2 error among the ~4,000 gets in a + // real hour would otherwise reject the batch and discard the whole hour. + const settled = await Promise.allSettled( + page.objects + .slice(i, i + FANOUT) + .map((o) => env.CORPUS.get(o.key).then((r) => (r ? r.text() : null))) + ); + for (const outcome of settled) { + spend.read++; + // A miss counts as a failure too. The key came from a LIST, so the + // object existed; treating it as empty would quietly shrink the rollup. + if (outcome.status !== 'fulfilled' || outcome.value === null) { + failed++; + continue; + } + for (const line of outcome.value.split('\n')) { + if (!line) continue; + let rec; + try { + rec = JSON.parse(line); + } catch { + // Counted and logged, but NOT a reason to abandon the hour. A + // failed get is transient and worth retrying; content this Worker + // itself wrote with JSON.stringify does not become valid later, so + // blocking on it would strand the hour until its raw objects + // expire and then lose the whole hour instead of one record. + corrupt++; + continue; + } + // A session heartbeats every 5 minutes carrying CUMULATIVE totals, so + // the highest seq IS the whole session and every earlier row is a + // strict subset. Sessions straddle hours, so readers still dedupe + // across rollups on this same key — this only shrinks each hour. + const id = `${rec.resource?.['headroom.install_id']} ${rec.session?.id}`; + const prev = best.get(id); + if (!prev || (rec.session?.seq ?? 0) > (prev.session?.seq ?? 0)) { + best.set(id, rec); + } + } + } + } + cursor = page.truncated ? page.cursor : undefined; + } while (cursor); + + if (failed) { + throw new Error(`${part}: ${failed} of ${spend.read} objects unreadable`); + } + if (corrupt) { + console.error(`rollup ${part}: skipped ${corrupt} unparseable record(s)`); + } + + // A genuinely empty hour gets a marker rather than a zero-byte NDJSON that + // every reader would have to special-case. Without it the hour stays + // "missing" and is re-listed on every run for the life of the bucket. + if (best.size === 0) { + await env.CORPUS.put(`rollup/${part}/empty`, ''); + return { read: spend.read, wrote: 0 }; + } + await env.CORPUS.put( + `rollup/${part}/data.ndjson`, + [...best.values()].map((r) => JSON.stringify(r)).join('\n'), + { httpMetadata: { contentType: 'application/x-ndjson' } } + ); + return { read: spend.read, wrote: best.size }; +} + +/** Oldest `dt=` day still under sessions/, or null. One delimited LIST. */ +export async function oldestRawDay(env) { + const page = await env.CORPUS.list({ prefix: 'sessions/', delimiter: '/' }); + const days = (page.delimitedPrefixes || []) + .map((p) => p.slice('sessions/dt='.length).replace(/\/$/, '')) + .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d)) + .sort(); + return days.length ? days[0] : null; +} + export default { + /** Hourly cron. Builds every complete hour back to the oldest raw data. */ + async scheduled(event, env) { + // Backfill reaches all the way to the oldest surviving raw day, NOT a fixed + // window. A fixed window silently strands everything older than it the + // moment analysis stopped reading sessions/ — the raw objects are still + // there, but nothing would ever compact them, so they vanish from every + // report. Bounding by real data instead means the floor rises only when a + // lifecycle rule actually expires the raw objects. + const oldest = await oldestRawDay(env); + if (!oldest) return; + const floorMs = Date.parse(`${oldest}T00:00:00Z`); + if (Number.isNaN(floorMs)) return; + + // Only list from the floor forward. Rollups older than the oldest raw day + // can never be rebuilt, so enumerating them answers nothing — this is what + // keeps the listing bounded by retention rather than by total history. + const done = new Set(); + let cursor; + do { + const page = await env.CORPUS.list({ + prefix: 'rollup/', + startAfter: `rollup/dt=${oldest}`, + cursor, + }); + for (const o of page.objects) { + // Tolerates both `/data.ndjson` and the `/empty` marker. + const rel = o.key.slice('rollup/'.length); + const cut = rel.lastIndexOf('/'); + if (cut > 0) done.add(rel.slice(0, cut)); + } + cursor = page.truncated ? page.cursor : undefined; + } while (cursor); + + // Newest first, so a backlog drains from the present backwards and the + // freshest hour is never the one starved by the budget. Starts one hour + // back: the current hour is still being written to. + let budget = READ_BUDGET; + for (let t = event.scheduledTime - 3600_000; t >= floorMs && budget > 0; t -= 3600_000) { + const part = partition(new Date(t)); + if (done.has(part)) continue; + // Shared with rollupHour so a throw still reports what it spent. + const spend = { read: 0 }; + try { + await rollupHour(env, part, spend); + } catch (err) { + // Newest-first means an hour that always throws — one grown past the + // subrequest ceiling, say — would otherwise block every older hour + // behind it forever. Skip it and keep draining; it has no marker, so + // the next run retries it. + console.error(`rollup ${part} failed after ${spend.read} objects: ${err}`); + } + budget -= spend.read; + } + }, + async fetch(request, env, ctx) { if (request.method !== 'POST') { return new Response('beacon: POST OTLP logs to /v1/logs', { status: 405 }); @@ -145,14 +322,13 @@ export default { } if (records.length === 0) return new Response(null, { status: 204 }); - const now = new Date(); - const day = now.toISOString().slice(0, 10); - const hour = now.toISOString().slice(11, 13); // Hive-style partitioning so DuckDB can prune by date without a catalog. - // ponytail: one object per request. At beacon volume that is a few hundred - // thousand objects a month, which globs fine. Add a daily compaction job - // when the file count starts to slow queries, not before. - const key = `sessions/dt=${day}/hh=${hour}/${crypto.randomUUID()}.json`; + // Shares partition() with the rollup: the cron lists `sessions//`, so + // two independent spellings of this scheme would mean the writer and the + // compactor could drift apart and silently match zero objects. + // ponytail: one object per request. Compacted hourly into rollup/ by + // scheduled() above — analysis reads that, never this. + const key = `sessions/${partition(new Date())}/${crypto.randomUUID()}.json`; const ndjson = records.map((r) => JSON.stringify(r)).join('\n'); // Respond immediately; durability work continues after the response. diff --git a/deploy/beacon/wrangler.toml b/deploy/beacon/wrangler.toml index 412b22045..826dba6bb 100644 --- a/deploy/beacon/wrangler.toml +++ b/deploy/beacon/wrangler.toml @@ -32,6 +32,24 @@ bucket_name = "headroom-telemetry" # npx wrangler secret put METRICS_OTLP_AUTH # Absent = R2 only, which is the right place to start. +# Hourly compaction of sessions/ into rollup/ — see scheduled() in worker.js. +# At :05 so the hour being rolled up is definitely closed. A >=1h interval also +# buys the 15-minute CPU limit instead of 30s, which the backfill run needs. +[triggers] +crons = ["5 * * * *"] + +# Every R2 binding call is a subrequest, and one hour is already ~4k objects. +# The paid default of 10k would cap a run at two hours and stall the backfill +# behind live traffic forever. This only raises a ceiling; a normal run spends +# ~4k. READ_BUDGET in worker.js is what actually bounds the work. +# +# Workers Paid only — on the Free plan this key is rejected outright ("CPU +# limits are not supported for the Free plan"), and the cron could not run +# anyway: Free gives a scheduled handler 10ms of CPU, and parsing an hour of +# heartbeats is tens of ms. +[limits] +subrequests = 100000 + [observability] enabled = true diff --git a/headroom/integrations/langchain/langgraph.py b/headroom/integrations/langchain/langgraph.py index 2e6734795..83aad7560 100644 --- a/headroom/integrations/langchain/langgraph.py +++ b/headroom/integrations/langchain/langgraph.py @@ -49,6 +49,7 @@ except ImportError: from headroom.ccr.tool_injection import CCR_TOOL_NAME from headroom.config import is_tool_excluded +from headroom.telemetry.session import BeaconCompressionObserver from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig logger = logging.getLogger(__name__) @@ -136,7 +137,11 @@ class _CrusherSingleton: config = SmartCrusherConfig( min_tokens_to_crush=self._min_tokens, ) - self._crusher = SmartCrusher(config=config) + # observer: no proxy here, so nothing else reports these + # compressions to the beacon. See BeaconCompressionObserver. + self._crusher = SmartCrusher( + config=config, observer=BeaconCompressionObserver() + ) return self._crusher diff --git a/headroom/integrations/mcp/server.py b/headroom/integrations/mcp/server.py index 23fdf3e8f..888ad6115 100644 --- a/headroom/integrations/mcp/server.py +++ b/headroom/integrations/mcp/server.py @@ -56,6 +56,7 @@ from typing import Any from headroom.config import HeadroomConfig, SmartCrusherConfig from headroom.providers.openai import OpenAIProvider +from headroom.telemetry.session import BeaconCompressionObserver from headroom.transforms.smart_crusher import SmartCrusher @@ -263,7 +264,18 @@ class HeadroomMCPCompressor: min_tokens_to_crush=profile.min_tokens_to_compress, max_items_after_crush=profile.max_items, ) - crusher = SmartCrusher(config=smart_config, with_compaction=False) # type: ignore[arg-type] + # observer: MCP runs outside the proxy, so PrometheusMetrics (the + # proxy's observer, which forwards to the beacon) never sees these + # compressions. Without one, an MCP install reports real tokens.saved + # with an empty compression.by_strategy. + crusher = SmartCrusher( + # headroom.config.SmartCrusherConfig vs the transform's own + # same-named dataclass; the ignore has to sit on the argument line + # because that is where mypy reports a multi-line call's arg-type. + config=smart_config, # type: ignore[arg-type] + with_compaction=False, + observer=BeaconCompressionObserver(), + ) # Build messages for SmartCrusher (it expects conversation format) messages = [ diff --git a/headroom/integrations/strands/hooks.py b/headroom/integrations/strands/hooks.py index 275b6f64d..07ef31887 100644 --- a/headroom/integrations/strands/hooks.py +++ b/headroom/integrations/strands/hooks.py @@ -50,6 +50,7 @@ except ImportError: from headroom import HeadroomConfig from headroom.ccr.tool_injection import CCR_TOOL_NAME from headroom.config import is_tool_excluded +from headroom.telemetry.session import BeaconCompressionObserver from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig logger = logging.getLogger(__name__) @@ -173,7 +174,11 @@ class HeadroomHookProvider(HookProvider): # type: ignore[misc] crusher_config = SmartCrusherConfig( min_tokens_to_crush=self.min_tokens_to_compress ) - self._crusher = SmartCrusher(config=crusher_config) + # observer: no proxy here, so nothing else reports these + # compressions to the beacon. See BeaconCompressionObserver. + self._crusher = SmartCrusher( + config=crusher_config, observer=BeaconCompressionObserver() + ) logger.debug( "SmartCrusher initialized with min_tokens=%d", self.min_tokens_to_compress ) diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.py index 3bf4b4103..fe477290b 100644 --- a/headroom/proxy/prometheus_metrics.py +++ b/headroom/proxy/prometheus_metrics.py @@ -417,14 +417,14 @@ class PrometheusMetrics: return total_input_tokens, total_input_cost_usd try: - # totals() rather than stats(): identical numbers, without the - # 31-day cost-record walk that stats()["budget_basis"] performs and - # this caller throws away. See CostTracker.totals. - tracked_input_tokens, tracked_input_cost_usd = self.cost_tracker.totals() + cost_stats = self.cost_tracker.stats() except Exception: logger.debug("Failed to read cost tracker totals for savings history", exc_info=True) return total_input_tokens, total_input_cost_usd + tracked_input_tokens = cost_stats.get("total_input_tokens") + tracked_input_cost_usd = cost_stats.get("total_input_cost_usd") + if tracked_input_tokens is not None: try: total_input_tokens = self._savings_tracker_input_tokens_offset + max( @@ -467,6 +467,14 @@ class PrometheusMetrics: self.requests_by_stack[slug] += 1 self.savings_tracker.record_lifetime_stack(slug) + # Same fan-out as record_compression. This header is the only signal + # that names the harness when an agent is pointed at a persistent proxy + # rather than launched by `headroom wrap`, and the beacon cannot import + # headroom.proxy to read requests_by_stack itself. + from headroom.telemetry.session import record_stack as _beacon_stack + + _beacon_stack(slug) + def record_compression( self, strategy: str, @@ -497,6 +505,22 @@ class PrometheusMetrics: if saved > 0: self.tokens_saved_by_strategy[strategy] += saved + # Fan out to the beacon. This object is the configured + # CompressionObserver for the proxy's pipelines, so it is where those + # events already arrive with both token counts — a second observer here + # would mean a second measurement pass for numbers in hand. (The paths + # that have no observer at all pass telemetry's + # BeaconCompressionObserver directly instead.) + # + # The beacon is ON by default, so this does not short-circuit in + # practice and must stay off the aggregator's lock: it stages into a + # dedicated mutex that the request path never takes, which is what + # keeps this method's "synchronous + lock-free" contract honest with + # respect to everything else in the process. + from headroom.telemetry.session import record_compression as _beacon_compression + + _beacon_compression(strategy, original_tokens, compressed_tokens) + def record_extension_savings(self, key: str, saved: int) -> None: """Accumulate tokens saved by a proxy extension, keyed by ``key``. diff --git a/headroom/telemetry/session.py b/headroom/telemetry/session.py index cfa77f44c..9aa287cb2 100644 --- a/headroom/telemetry/session.py +++ b/headroom/telemetry/session.py @@ -94,6 +94,39 @@ _SLUG_RE = re.compile(r"^[a-z][a-z0-9_]{0,31}$") # vocabulary. Values are slug-validated before they are counted. _REASON_TAGS = ("passthrough_reason", "image_skip_reason", "memory_skip_reason") +# Cardinality cap on `by_strategy`. The real vocabulary is CompressionStrategy +# plus a couple of literals — under a dozen — but `record_compression` takes a +# free string, so an extension or a future caller could invent keys per request. +# Matches the same guard on `requests_by_stack` (MAX_DISTINCT_STACKS). +MAX_STRATEGIES = 32 + +# Compression events arrive on the compression executor thread, mid-request, +# before that request's outcome ever reaches `SessionAggregator.record`. They +# are staged here rather than written straight into the live session, which +# keeps three things true at once: +# +# * The executor thread never takes the aggregator's lock, so compression +# cannot serialise against the request path. The beacon is on by default, +# and ContentRouter observes once per routing decision — once per content +# section per request — so that contention would be real. +# * A compression event cannot CREATE a session. Sessions are started only by +# an outcome, which preserves the invariant that every emitted session has +# turns >= 1; otherwise a request abandoned between compression and its +# outcome (Claude Code users interrupt streaming routinely) would emit a +# phantom all-zero row that inflates fleet session and install counts. +# * The first turn's numbers still survive, because the outcome that follows +# milliseconds later drains this into the session it opens. +# +# A request that dies before its outcome leaves its events staged, and they are +# attributed to the next session instead. That is a rounding error against +# inventing a session that never happened. +_staged_lock = threading.Lock() +_staged_strategies: dict[str, list[int]] = {} +# Per-request stack slugs, for `detect_stack`'s by_stack branch. Same staging +# and the same reason: the proxy sees the X-Headroom-Stack header per request, +# and this is the only place the beacon can learn it without importing proxy. +_staged_stacks: dict[str, int] = {} + def _pct(numerator: float, denominator: float) -> float: """Percentage to 2dp, or 0.0 when undefined. @@ -218,6 +251,28 @@ def resource_attributes( } if install_mode: attrs["headroom.install_mode"] = install_mode + # Detect when the caller did not supply one. Every caller so far supplies + # nothing, so `headroom.stack` was absent from the entire corpus while the + # detector sat unused — which made the fleet unsegmentable by agent, the + # question the corpus is most often asked ("what does this look like under + # Claude Code?"). + # + # The env vars detect_stack checks first are only set by `headroom wrap`. + # The common deployment points an agent at a persistent proxy through + # ANTHROPIC_BASE_URL and sets neither, so environment-only detection would + # answer the literal "proxy" for almost the whole fleet — a populated, + # authoritative-looking column that cannot answer the question it exists + # for. The slugs staged by `record_stack` are that fleet's only real + # signal, so they are fed to detect_stack's by_stack branch. + if stack is None: + try: + from headroom.telemetry.context import detect_stack + + with _staged_lock: + by_stack = dict(_staged_stacks) + stack = detect_stack({"requests": {"by_stack": by_stack}} if by_stack else None) + except Exception: # a broken detector must not silence telemetry + logger.debug("telemetry: stack detection failed", exc_info=True) if stack: attrs["headroom.stack"] = stack return attrs @@ -252,6 +307,10 @@ class _Session: overhead_ms: float = 0.0 latency_ms: float = 0.0 transforms: dict[str, int] = field(default_factory=dict) + # strategy slug -> [events, tokens_in, tokens_out]. `transforms` says which + # compressors ran; this says whether they were worth running. A list rather + # than three parallel dicts so the three numbers cannot drift apart. + strategies: dict[str, list[int]] = field(default_factory=dict) skips: dict[str, int] = field(default_factory=dict) sources: dict[str, int] = field(default_factory=dict) providers: set[str] = field(default_factory=set) @@ -363,6 +422,37 @@ class _Session: }, "compression": { "transforms": dict(self.transforms), + # Per-strategy effectiveness. `transforms` counts invocations, + # which cannot tell a compressor that saved 60% from one that + # ran constantly and saved nothing — the fleet's top transform + # by count contributes an unknown share of `tokens.saved`. + # + # These do NOT sum to `tokens.saved`, and must not be presented + # as if they do: strategies compose (the router routes, a + # strategy runs inside it) so the same text is measured by more + # than one, and tool-schema savings never appear here at all. + # Read a row as "of what this strategy was handed, it removed + # this much" — a per-strategy yield, not a share of the total. + # + # A LIST of uniform records, not a {strategy: {...}} object, + # and that shape is deliberate. DuckDB infers a JSON object as + # a STRUCT while its keys are few and consistent and as a MAP + # once they are not, so an object keyed by strategy would + # change COLUMN TYPE as the fleet adopts new compressors — + # exactly the break that silently took out the `transforms` + # report. A list of records has fixed field names, so the type + # is the same on day one and after the 30th strategy ships, and + # a new field inside a record is absorbed by union_by_name. + # Sorted so a payload is byte-comparable between heartbeats. + "by_strategy": [ + { + "strategy": name, + "n": counts[0], + "tokens_in": counts[1], + "tokens_out": counts[2], + } + for name, counts in sorted(self.strategies.items()) + ], "overhead_ms_total": round(self.overhead_ms, 1), # Sum of per-request durations, NOT elapsed time: concurrent turns # make this exceed `session.duration_s`. Kept under the original @@ -505,6 +595,20 @@ def _fold(sess: _Session, outcome: Any, now: float, source: str = "proxy") -> No sess.last_seen = now sess.turns += 1 sess.sources[source] = sess.sources.get(source, 0) + 1 + + # Compression ran on the executor thread before this outcome arrived; take + # what it staged. Done here rather than in the observer so the executor + # thread never touches the aggregator lock — see the note on _staged_lock. + for name, staged in _drain_staged_strategies().items(): + counts = sess.strategies.get(name) + if counts is None: + if len(sess.strategies) >= MAX_STRATEGIES: + continue + counts = [0, 0, 0] + sess.strategies[name] = counts + counts[0] += staged[0] + counts[1] += staged[1] + counts[2] += staged[2] sess.original_tokens += int(get("original_tokens") or 0) sess.attempted_tokens += int(get("attempted_input_tokens") or 0) # Billed/volume figure, so prefer the provider's own count and fall back to @@ -776,6 +880,116 @@ def record_mcp_compression( ) +def record_compression(strategy: str, original_tokens: int, compressed_tokens: int) -> None: + """Beacon entry point for one compression event. + + Signature-compatible with + :class:`headroom.transforms.observability.CompressionObserver`, so the + proxy's existing observer can forward here without a second measurement + pass — the numbers are already computed on the hot path for Prometheus + (``PrometheusMetrics.tokens_saved_by_strategy``); they just never left the + process. + + Same discipline as the rest of this module: off by default and cheap when + off, never raises. This runs once per routing decision, so it must not do + anything a request would notice. + """ + from headroom.telemetry.beacon import is_beacon_enabled + + if not is_beacon_enabled(): + return + # A slug, not the raw string. The real values are CompressionStrategy enum + # tags, but the observer protocol takes a free string, and anything that is + # not already a bounded lowercase identifier collapses to "other" rather + # than reaching the wire. + slug = _safe_slug(strategy) + try: + before = int(original_tokens or 0) + after = int(compressed_tokens or 0) + except (TypeError, ValueError): + return + if before <= 0: + return + # Clamped at the input: a compressor that emits more than it received is a + # bug, and letting `out` exceed `in` would surface downstream as negative + # savings rather than as the bug it is. Prometheus clamps the same way. + after = min(max(after, 0), before) + with _staged_lock: + counts = _staged_strategies.get(slug) + if counts is None: + if len(_staged_strategies) >= MAX_STRATEGIES: + return + counts = [0, 0, 0] + _staged_strategies[slug] = counts + counts[0] += 1 + counts[1] += before + counts[2] += after + + +def record_stack(slug: str) -> None: + """Beacon entry point for one request's stack slug. + + The harness identity lives in the ``X-Headroom-Stack`` header, which only + the proxy sees, and per request rather than per process. Counting slugs + here lets :func:`resource_attributes` answer ``detect_stack``'s by_stack + branch without the telemetry package importing ``headroom.proxy``. + + Without this the beacon can only read the two environment variables, so + every install that points an agent at a persistent proxy — the common + deployment for Claude Code, Cursor, Codex and the adapters — reports the + literal ``"proxy"`` and the fleet is unsegmentable by agent. + """ + from headroom.telemetry.beacon import is_beacon_enabled + + if not is_beacon_enabled(): + return + # normalize_stack is the same chokepoint the proxy applies at ingress; an + # unbounded header value must not reach the wire or grow this dict. + from headroom.telemetry.context import normalize_stack + + clean = normalize_stack(slug) + if not clean: + return + with _staged_lock: + if clean not in _staged_stacks and len(_staged_stacks) >= MAX_STRATEGIES: + return + _staged_stacks[clean] = _staged_stacks.get(clean, 0) + 1 + + +class BeaconCompressionObserver: + """A `CompressionObserver` that forwards to the beacon and nothing else. + + The proxy's `PrometheusMetrics` is already an observer and forwards from + there, so this is for the paths that never had one: the MCP servers, the + bare transform pipeline, and the LangChain/Strands integrations. Those + processes report `tokens.saved` either way, so without this they emit + sessions with real token totals and an empty `by_strategy` — a silently + biased subset that cannot be reconciled with the fleet totals. + + Only `record_compression` is implemented. ContentRouter's two other + observer hooks (`record_kompress_size_gate`, `record_router_route_counts`) + are each individually guarded at the call site, and both feed `/stats` + rather than the beacon. + """ + + __slots__ = () + + def record_compression( + self, strategy: str, original_tokens: int, compressed_tokens: int + ) -> None: + record_compression(strategy, original_tokens, compressed_tokens) + + +def _drain_staged_strategies() -> dict[str, list[int]]: + """Take everything staged since the last drain. Caller merges it.""" + with _staged_lock: + if not _staged_strategies: + return {} + drained = {name: counts[:] for name, counts in _staged_strategies.items()} + _staged_strategies.clear() + return drained + + def record_outcome(outcome: Any) -> None: """Beacon entry point, called from the proxy's outcome funnel. @@ -874,6 +1088,97 @@ def demo() -> None: agg.flush_all() assert len(emitted) == 2, emitted assert emitted[1]["session"]["turns"] == 1 + + # --- per-strategy compression ----------------------------------------- + # Compression runs on the executor thread before its request's outcome + # arrives, so events are staged and drained by the next outcome. That is + # what keeps the first turn's numbers while letting only an outcome open a + # session. `_staged_*` is module state, so clear it between cases. + _staged_strategies.clear() + _staged_stacks.clear() + + strat: list[dict[str, Any]] = [] + sa = SessionAggregator(strat.append, idle_s=10.0) + record_compression("smart_crusher", 1000, 400) + record_compression("smart_crusher", 500, 300) + record_compression("code_aware", 800, 800) + assert sa._current is None, "a compression event must not open a session" + sa.record(FakeOutcome(), now=2000.0) + sa.flush_all() + by = {row["strategy"]: row for row in strat[-1]["compression"]["by_strategy"]} + assert by["smart_crusher"] == { + "strategy": "smart_crusher", + "n": 2, + "tokens_in": 1500, + "tokens_out": 700, + }, by + # A strategy that ran and saved nothing must still appear: "ran 800 tokens + # through and removed none" is the finding, and dropping it would make + # every strategy look effective. + assert by["code_aware"]["tokens_in"] == by["code_aware"]["tokens_out"] == 800, by + assert strat[-1]["session"]["turns"] == 1, "compression events are not turns" + # A list of records, not an object keyed by strategy: the type must not + # change as strategies are added. See the note in payload(). + assert isinstance(strat[-1]["compression"]["by_strategy"], list) + assert [r["strategy"] for r in strat[-1]["compression"]["by_strategy"]] == sorted( + r["strategy"] for r in strat[-1]["compression"]["by_strategy"] + ), "sorted so heartbeats are byte-comparable" + + # Draining is exhaustive: a second session must not re-count the first + # session's events. + assert not _staged_strategies, "record() drains everything it staged" + again: list[dict[str, Any]] = [] + sb = SessionAggregator(again.append, idle_s=10.0) + sb.record(FakeOutcome(), now=3000.0) + sb.flush_all() + assert again[-1]["compression"]["by_strategy"] == [], again[-1] + + # An abandoned request — compression ran, the outcome never arrived — must + # not invent a session. Before staging, this emitted a phantom turns=0 row + # with all-zero tokens that inflated fleet session and install counts. + ghost: list[dict[str, Any]] = [] + sc = SessionAggregator(ghost.append, idle_s=10.0) + record_compression("smart_crusher", 900, 100) + sc.flush_all() + assert ghost == [], "no outcome, no session" + _staged_strategies.clear() + + # Over the cardinality cap, extra strategies are dropped rather than + # allowed to grow the payload without bound. + cap: list[dict[str, Any]] = [] + cc = SessionAggregator(cap.append, idle_s=10.0) + for i in range(MAX_STRATEGIES + 5): + record_compression(f"s{i}", 100, 50) + cc.record(FakeOutcome(), now=4000.0) + cc.flush_all() + assert len(cap[-1]["compression"]["by_strategy"]) == MAX_STRATEGIES, cap[-1] + _staged_strategies.clear() + + # Strategy names are slugged, never passed through: the observer protocol + # takes a free string and this is the only chokepoint before the wire. + assert _safe_slug("smart_crusher") == "smart_crusher" + assert _safe_slug("../../etc/passwd") == "other" + + # --- stack detection --------------------------------------------------- + # Environment-only detection answers "proxy" for every install that points + # an agent at a persistent proxy instead of using `headroom wrap` — i.e. + # most of the fleet. The per-request slugs are the only real signal. + _staged_stacks.clear() + for _ in range(9): + record_stack("wrap_claude") + record_stack("wrap_cursor") + assert resource_attributes()["headroom.stack"] == "wrap_claude", "dominant stack wins" + _staged_stacks.clear() + for _ in range(5): + record_stack("wrap_claude") + for _ in range(5): + record_stack("wrap_cursor") + assert resource_attributes()["headroom.stack"] == "mixed", "no dominant stack" + _staged_stacks.clear() + record_stack("../../etc/passwd") + assert not _staged_stacks, "junk slugs never reach the wire" + assert resource_attributes()["headroom.stack"] == "proxy", "falls back with no signal" + assert emitted[1]["session"]["id"] != emitted[0]["session"]["id"] assert emitted[1]["session"]["ended"] == "shutdown" diff --git a/headroom/transforms/pipeline.py b/headroom/transforms/pipeline.py index c7061dee1..769580d42 100644 --- a/headroom/transforms/pipeline.py +++ b/headroom/transforms/pipeline.py @@ -163,7 +163,13 @@ class TransformPipeline: # - Logs -> LogCompressor # - Search results -> SearchCompressor # - HTML -> HTMLExtractor - transforms.append(ContentRouter()) + # observer: the proxy passes PrometheusMetrics; this bare pipeline is + # used by the library/adapter paths, which would otherwise report + # tokens.saved with an empty by_strategy. Imported here rather than at + # module scope — transforms sits below telemetry in the import graph. + from headroom.telemetry.session import BeaconCompressionObserver + + transforms.append(ContentRouter(observer=BeaconCompressionObserver())) logger.info("Pipeline using ContentRouter for intelligent content-aware compression") return transforms From f624d3a00ac271db7947443ddeb0c8bc2e93d3eb Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Sun, 9 Aug 2026 16:24:33 -0700 Subject: [PATCH 021/138] perf(proxy): bound upstream calls and hot-path costs (#2852) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Seven commits from one week of load testing: one hang, two request-path correctness fixes, and four hot-path costs that only show up in production. ## Reliability **Bound every upstream call.** The litellm backend had no timeout at all, so a request the upstream never answered blocked its caller forever. Observed under load on 2026-08-07: four agent workers on ESTABLISHED connections for 36+ minutes while `/readyz` answered in 0.11s. No error, no retry, no log line — indistinguishable from slow work, which is the worst shape a failure can take. A float rather than an `httpx.Timeout`, deliberately: litellm expands a float across all four httpx phases, so on a streaming call it becomes the maximum gap *between chunks*, not a cap on total generation. A long answer streaming steadily is never cut off; a stalled one dies. Default 600s via `HEADROOM_UPSTREAM_TIMEOUT`; 0, negative, and junk fall back to the default rather than meaning "no timeout". **Keep the consistency re-count off the event loop.** It ran `tokenizer.count_messages` twice directly on the loop. Since Claude counting moved to a real BPE that is CPU-bound work stalling every other in-flight request — ~1s on a 2.3 MB body, with `/healthz` gaps tracking body size. Offloaded via `asyncio.to_thread` on the same tokenizer instance, so reported values are unchanged. (#2810) **Survive a re-parse MemoryError.** `MemoryError` is not a `ValueError`, so on 1M-context payloads the byte-faithful forwarder's verification re-parse escaped the handler and aborted an otherwise-fine request — 14 aborts across 8 days of reporter logs. (#2768) ## Performance All four are measured, not guessed. Each degrades with something a short benchmark does not vary: uptime, content shape, or process age. | fix | before | after | |---|---|---| | Cost-record walk per request (at 100k records) | 13.6 ms | bounded by model count | | JSON-block scan, JS-style object logs (1200 lines) | 4643 ms | 183 ms | | JSON-block scan, truncated JSONL | 3737 ms | 116 ms | | Lazy imports inside user requests | multi-second | paid at startup | | `count_text` (80% of local CPU) | — | memoised | Two worth calling out: - **The cost walk degrades with proxy *uptime*, not load.** A freshly started proxy pays ~0.01 ms; a month-old one pays 4–13 ms on every request, on the event loop, holding the metrics lock. Deliberately not a TTL cache over `stats()`: those values feed `check_budget()` when `--budget` is set, and a stale reading under-enforces the budget. The fix is to stop computing what the caller discards. - **The JSON-block memo is built only *after* a scan fails to balance.** That ordering is load-bearing, not an optimisation — caching from the start made pretty-printed JSON ~2x slower, since content that balances on the first scan has nothing to reuse and just pays the per-line dict traffic. Still a constant-factor fix, not an asymptotic one. ## Tests +1202 lines, 20 files. Each fix is pinned by a test that fails on the unmodified code: the re-count test asserts no `count_messages` pass runs with a live event loop in its thread; the re-parse test drives a `MemoryError` through the real request path and expects a 200; `totals()` equality with `stats()` is asserted across model counts, request volumes, and both pricing branches. The timeout test is structural rather than a mock — the failure mode is a dispatch path someone adds later without a guard, which mocking the existing four cannot catch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) --- dashboard-cache-ttl-main.png | Bin 0 -> 265727 bytes docs/context-mode-integration-analysis.md | 378 ++++++++++++++++++ headroom/backends/litellm.py | 46 +++ headroom/proxy/handlers/anthropic.py | 16 +- headroom/proxy/handlers/openai.py | 7 +- headroom/proxy/prometheus_metrics.py | 8 +- run-all-plugins.sh | 171 ++++++++ tests/test_litellm_upstream_timeout.py | 70 ++++ ...st_anthropic_recount_and_reparse_safety.py | 158 ++++++++ 9 files changed, 845 insertions(+), 9 deletions(-) create mode 100644 dashboard-cache-ttl-main.png create mode 100644 docs/context-mode-integration-analysis.md create mode 100755 run-all-plugins.sh create mode 100644 tests/test_litellm_upstream_timeout.py create mode 100644 tests/test_proxy/test_anthropic_recount_and_reparse_safety.py diff --git a/dashboard-cache-ttl-main.png b/dashboard-cache-ttl-main.png new file mode 100644 index 0000000000000000000000000000000000000000..3433b1c5620ed5ae2a36d7c7582acec6c9abff90 GIT binary patch literal 265727 zcmd4(^TsG%i^BK>0#voEnRSqAA90vmf17AU2S_1^zRX#=qOj zUBAtL_c4x^q|~1N@6%J9NB`TGp#9(O+rL8pxBue>(VyG>cl*D`;{88ee z#h>5vd5(QVl$1u2lZmj@Xw`IVt*nU2$c8ZT8(oy@i_PpfdcNIT`qoT`_nJ>A0^3>R9(?+0BC>cgF zH7+i$SYGYqhmIBlqlSvct&(^~LBWjfk^c-;a;ahp+YqnGS%o=s<~zg5@0gV=MDtvO zB%{`K>Uc{8lCfXE{)L56@>S`XyPMnVZQ2C+WW^2mAkMOc%y^3~*Qy%BO zVq7yFv&wa~$>A8nG?z}*PuNdW$L+sQMSIKFRrRIfM>H0OT4{tdU8rRDiuSf<;Y3u* ziziQ>2+5tqab1?S6!CL(`;XDH{PpMBEK)ws)c-qZ9aQ-omF#%FHC-{NUw=;b^53bQ zOdBvV{NG0J^z`-5DX+TsA2=$sEBWFF8k*~>H%*HE+FR6iEYVJAu-ucuA^UUgKU-%S z%L^XdA4f4REqFkjW~f2kVG z-R6SKjfgn9CA6C=Owk4V&Afc|Dqwr%(ZBB(2FB3^8Tso*yZL4ZNC6=4FHs=n_WE{u zM(*b9_l%;fvS>q3T1{qJk>Pl0x(sDi5K#zDtht4|j%4aXN1^9l^UU#Hr|Dd^arI4N znl6|F?xi93>C>kcPO2M%*H_Sq(=(N_AczUU;qtr~qSI3j?04RFXhwtA<-68?_~Y^k zt}5#H+FBRtg}@fS?t>8WHbY+$qX12r?{VYM$ck3IS&tyn`VxGMzxcll9DnpDX9s7 zAGc&dtlM169C8^F8Y&|#{nwMv)8A|+Gz22$7m8hbn!7}^ymyJIU%jHHq$H$D$jM+N ziGK6u&Da}`JFXl+M0|t$r!!%o2wQz&^*m#19oyVMZn*9fniLJ+%L~s71I16Q!+sR# zm;bx7G1mc9A*qbWwRbqB`r*z+`w23vHv2xkZY}73L&m<%^^^~htOnAu4>zj!5M<1S zr3D0#@0EUq(JD{@CT1P@*MmApI1Dxc#D*=-JtbdVp5$@8z=`%KX_q#){b<`8CCl>a z^vZVS6?)3%^MJJ2^!46~DqcvI#X!TkC#Wo}0K6^a2!Dd%)5gFaCK*bw!YQAaiecT! zkI}_KQXO)sYqUtlf9%q+n%c4 z(?udWm-1at-$AV}s6`gXm(c4Au>h;EKeOL={<#L^3ma11i+j+{s(wQ=Df<(}w%DKW z78jK)Awj^z*RMWKm){C#wwWAMGI`iP31wuEb>#@D$$?Sl!k!lgGoXfqgm?ZprvdLgapj!bDG4?8#VJ5MSJ)rD^jWW$ze^Uew{F_$T)w|NPs`gI zFOz2==L`5tMWyGPEQLOsJZ;iL! zxxGKiJ#BOpV^owO+2?y*##yz-$Iyf2PVMl_CJ{iMKypTcNmJ%cdL)gFm6e7>{x=2B z?Zvfwu%UXwZhsKW`>;TZrN)GlFuay%LEY?XUeI*9-qv3==Qvi4#fT?Jblse%^E5%Aw?^-0tjbVUsQ) z?IjvJZAmvp^s})lZ926{xv7*C)h*Ox?ASgOrOG*ccSU3eu*QhU$f*mFz>^qx24{G? zAbV*+PnZ$|R;A9p93mNydI55|s~xmknuz=y91?hSZ+P+i7fi4TIqd@74TXt~8Qf^N zc^vO26vixlSIC;QiAOGjbyh0-Q1v+3Ge1@}w;QI#5Z~P-g6D^H+-qkGRnm?o%e0hB z%X$WYg*WyAMrR4YEYF)p$9Zst1O5S&Fx-23Vq&4U3c2D6%T;*hihW6>W;j?W!Oev% zh4bBVj16s~@W^k8<-bq76T%g7_I;MPgH~tsa;#iPXvy|<8VDX|ry@ocf#W@GEG~@y(xO%Aa})*sH|~N67zPQZMP{l0S))txA`9r zi{iyOj_jA+x5iC6eOCLc{Uu|umhkgL0%z(p50598M^fLIG=APIeP#j)M88SyVY0Hx zr9jlLtvn#=c*``P5249KPY*WD%QY&BYNWVYMnX=mZl{U{rlBTa)adz*4(_%(5n8gUoc@!MW5f3&kbUQJ!!V}YmckP9x#a1n7<%I1 zKAWCD{G8^^&5c`Wob}*dZPF1~MDo&X!n~;G-?dswU-#~}wMymfn&jGZ(H%R~YL2TZ z;1x{hH6NQ7Rzlugdry@ztkJ8jAmLqF)ocy?b5s#z>{<~t;~%7e!v*u$W=k7s%l~x0 z=$%6rzhl=x=3ToZSfs+EVg-8>q(fA-ToC-<4dueyxw~!JkLgSf{Hb0 zKA7>}YcF9-sSlGw3?6-xEG*G|uJ$HOjQ0&T52>J`X3HBMPP>7=s!9~{=*L>!D;bH= z9}*!Y)0CVnZ>X+GqRMJM>bzG%ZJLsle7*6m85y3=7FXN2H-(tt7RU!2oa`)`;o)U9 z?PjNDR#lU=INdG77`GRif+UTUbL&`IP9Q#PS36S9uQRla`}uiz#)rmX9TxcWnkDX$ z1)MG9p6Tsa9@XKOE^fg0+|#3@9PIjVrd}C$U{&P;)QFL}zrj0>ZshEWg*M3$E{y05 zRAEYc)+=cv#~g3a#7OrfS5Kp_|6=%85{PxETLK_0S&$KG6{l6qobZCiaFDUlxA|i`U?+APPf@49<}+L300DBodLE6c4LaH)A_G&CSAG0= z173WJPDy+ZoVU=_)YR4G-;IchF>1Gbi5WU0YCn^HD`7^huAYz=crsNFc_?uvh&MoC z6@`Q)C$FP%t!7JXY%GAD##u=sqlk}jy_kXd;dtPoE9?A;C%;R9v($Ijq(ukHK$L6q zVYTic5;A@OZ-KP6393|^J_Kj+Z{%v{OOc@tbF#B{3c&Nj#Y38H{2L}#eKwYs(nQL zf~BTCaz#4RGBTX)ofQDa2nX7K;HS@k+u>3^q!b)>@^yF3_mp<6_mEnWLiljD5okE= zRXy>n(`IpQ-fdTx&gPugC~7A8>oR0aC@8xzI_ z$7VOwIocq1ovI`2)UKy;lga!_Deo^?z{8K-HGNixG{rnoKF5Ws6M~>;l?!z(Ri47j zOk?od`_p*~roerTv7G0*kUQ7=Y6{&8#4@pR}d{0&qOC@w!zWjZs=!ZW(Id93MI4YP@-+c`j3n%pFRcku& z$o9PKc(e>IE1+Pq6=Mc!?OBIjxS+=8frzzmamXyLL;k)IfS>hUV(V zh04QS2VaXVw64g7i`;Qo&Qw-T_O|0JNV33o65FD(Z9YG4yF9`eJ~tJ?^P|Q6z7^O5 zX|@3pYBrb#UO5gPJzHe{z-1@?&Y+z_my1fYHQH|aTLC>YOjzjD=eD@_%9A~fftj(s zzI$f$_jv5cBCm#4O=Q&5)nngk*hQ65-*`oRY*IA5Ta==_Lne!phrz0fbey`tO>yrz z7yhL8(NzQUC3AnJMSh$yw#f5N!jt`k*lLSYK4WyaWsMN=-uYWsPMqpXv#@mkz5y2s0GnW-(=MRAw*@1UhleL#S(0qv}D9`N$ z*Tc?b@$C0Q6G%$Umh?@ZqoX=2CDMnRiRFC`caTnz^#N*U2c-3QOdfC!@eyL9OGoL} zc{;-C>18am7G_d?O|Pxc5rV|2117Aa0#E|4262k;$S)T+vdmlT{`99y`R?feekMco z2^=Ao*}N|e$y+b}3wK1(hz7*dQj@1$!geMAbOhwq;o-&F!s)cG0{6coQc(O7!-%I1It%q(p;wKE%FM%wQ*0vKa~8?CON*;_U+qbaj`V&Ek(<2 za&Bhn?{~s*w%AUv6t!rl*D;8PDfS-DDi_qKzLQEXOeRDm|}&=46yHut;yf!b_oaKX9K8N#R6{y z9)8$Ntmg*hUnPPjsMqz<&a7QzpId&+x|5u&Nfl~-$SF<%rf^z2n+AE8*bopImA;!Y8O zTGV#2%5#7dtf#Pcd@Vu+yC+JR#CwYQc$Zq#tX%_CywA0Ah@Z#ALBZ#IyuJ#osTgO3 zaP#;tzNPl;EN@f>up8=T2zZtjB(yh5mRM!FM?DA7h_fUOH|AkrCY(j8gQCQO2ahJv z_*m_!(j6eSIE9ZCc1U=`!5Pzk4=VV=M^yLtK4Z6r~)zm%@-tB`^BKH2TrYOYgd zdHNc((U|u1;}S&XrN5iBr@1eK=jp zrW)P={_QYVrS=Uq6O;7-fm6`Mdf?u3(HND{GZn??;fluktBcn>j{7lzQcP;k()NN5 zPBKOU2ilw+D6p~1>~(KdiCUkY0}aH0C!Z_FONCR>*-x`>(dwEt8j*uddKRPLXYQ|} z@wa2Q5B$!k)IWwqI`i&Ihhd8YJ(lYec{#o`KO}`;8W}l!Y9Y*j-=V4Pz1ySsB=lLB zY^n8}mqtd+Pu|csa9Bm62Geq<*?GwbDQBK|;tRsV{q4Wsy)Rx)(R=g$#YwSXM!RNy z66cvWtZaF%N;~Z)XBiBPtsF33=@*flizw=HlMR9L;|s6^JA&mPiKwmqbITGI5=YYx_LUYvO1a{R=TAq_?;!;P;y>}>0iV( zHnz4;bMhOS#}Si%Ep}uDeR=tE)u=>V#Uf82Q0}S50lUIy# zS!nh2ke0VSvXHaURb<5l-8yfrNM5p6kqL+%uWiO#m+Utd4&0B_geL&G)yHLT!$`r^$ zkDg|yZm(<^%`Ydx>+^W)=soq1AF74UE41o1V4mdf%^y>Zav8n_aHgq;U2R-KnjE37 zcNJD=Y{cXtd14n356%baRIYmtdeK-W-a9Cg(^SA+10g`|?F4*DGD ziMwl`mUk#L@M*DFG44hqH#c^Qs>6ETakmt+tj@)GU)=xDTCmH}zKxpQzv1F&nT+zmdp zm9w499V@>w0I)`)PnW=BKb@FDmUgFVXU1A1@wyidq3 z^Mdfw(Qt?-wnFndLgO`ce4fqc$F6l%Jj~%EWjM5M6-K?e*%r*ITRVglm2oTB&&eg1 zVc#U~KtA$-7UTl7+J6Gsbtm-h-SJ*+mq5Ta2FJ=YV|49uC$tMV5Q2T-zQ)AJ$f@7> z@njvu?_y%wzAiIj1uX-BeIyW>We-h;o+5jj>+6dIPif4ob2S(-~yB^=4t_e>zb-|b#=DXVgg~PJ8jwYL@lyazjFLhORY7D7I**8 z`uAX5nf`0jLdvL3r-yORlq#pJmP2J)tt03MDJhHL2HU`Cs3tJ8`Ct(^S;O(L6DQ-M zI|e2RO%xQ=e|G$?X4YXDoMG6_A;#GrRc)coAJ0sHY;T`e1SlyeM>Mg-{`6!vT}H3& zTDAJ@oP4RN37hmH3=7=_6(1O0y?$-jI>*n)s}d2JAm2Nakdx4kTDFR(fq1k5e;~3v z>o# zl0k(vx4K%$D!L3@V%;HYM?N36GD#2ye$Qf=DIETZiU-qa!oH^FY?A5?C#Tm5gXbVe z$|fI^t+mb%5C%eKaC8v-(Zm!X+py)$GBOkh3jPU6<21QPD#CUycHlu1hdI#FiI2Nc z1NABt{GAGFS7*m}eoJGcqtz_m#M_b7}Mm2K7?fVq=4y= z_kOS=bU58{1~j!=lkW06(k3a`MayPQnKwoKQ|e;ubDVsgWFl2xlReV@iOusgXvd%b zmx}-!2>SQdIIrK^oQ?&BCrAx7+i456>7RL)62Y=g0qB&CsKa+s3G-rx>^S#Ff3DKA zjCM~xPe%q|Kwd3qkG5uY=seAbFQ4pVNm-a2RTM?PYG$`6FAq=QO4X5ixzA7&#$eMD zAqCaY`NW_+|19NDhn6;}z|Hg5e_iCXZ;}1Y%gD+o z2r?dUJ}19I6L84H<(>5a(tbBwB`eQEI}giNWj0UHZa-#da?)mysjz?9_TbY4LnJH{ z{?$)!u)(?-=6x`=JUO_~J(ZEdn2e9;a!sJt+O=CK_KfB;E~M`{F?zb84~et^_j3)~ ziU1F4Aic=50wxY2wHoO@mIvH2mQ`~`%dt#tI}n$m_M!@x0)1Zp+2#E5raPcgM{^#N z@7=p+1O)D$p2nSLF2ch8^iuR}f#l@mT_?t9V&hj}unh{F*Meu{W_hf7^QaWo+6xHx2O zPLJgbXE)IZPhl79FKwb3I80bj+p{SDX!Xu8{xR~CxTInRcEH=Ag4xdr^@u|vaSne>Ym+HFKm z3=R@SOB-p6p@81Ilc^p1{6a$BX=-J0Huulws`vVULCJel`s7Xrl4%v%cG1~3E1A6R z@pXlTCa|$=VQ)TB(VUA%YyAKLk555s{ksmboL4!zyLOk25w;e|iP_saMa@MGhG_I# z!`wG9$9Iv&TgJswIJX3dRUNI z4$Mjt#TjjVT{*iU&v4ltqKN)s3zM)%y;K+9 zmIA|-b}MRU>nR^1B|=Kc1};hu^|Bg0OiF5lxF0@B28%X9brsxwGWj3^B4gTaY#GUR zUnFxcezM#f+KrdDzRFw1{`?#!b!JM}qt0roj(TOsX$e);EYMQ>&a#5LUd0gdGi#pH zYJ2f~q0FxGmiQ&f_(PrDX>;y5IiJI?IBJUdH$hh`GQCOv(*>0593MZ>FY@ z^E$z6+>s)eg|m#f(WE{Cn@Et$Rg;6xj?Tv3d=SQ^l`H0K`BonQ#hI9txXn%>vK~TX zJyGy@e~mewo}M0EZd|C`)|s4Y{?y`vJQNhadygjd^7EN_e(Y+q>kTO=sgy3qJJVU~ z4;lEU5k#dot!5_F*~uEPG4h7VGQp*_SQSw`+gtFh%pcJ=<15m zyd9gXI~hw3#|sBegIe>g@^2$_JmQj}Mt7^H*N+j`uF!0iX9SupO0p0`MLdo-?99v? z_aDo95#@Fix|c9?@oOSi%()j&5HNPtgmZEg3#b%l5r%NZnL?=qWfE__&G z?v#D1w!6qHfYUc-qf~BO(Xjp8a7Hjp!iQBJRWAXjfB^QsxaTy zoL0Vt7UE*Xq_(8&`?oUBJzkMc7h%$M^_?Fxi@y=NsxKp@nMyZ}94^t7nmpjCdo&+a zlSF|$A;Jw4xy$RoY-^Cp!`+Zi$1@g0n-m*`=MCDFEx;lT;IUf@Q`FO{XlbnQKwWi1 znV+jq1cu1Yxh#B5!FS7OY?m{RVnyc<65SF9?f4m+zg0>>18RM;2+rIO&|(WOol-TH zishre14z@8LCfjU7@o__+$nW4ujibynde{L=jYzZqD)1IsmX~bs3ZhcX&VyiPrn3@ zk102b>c2y@dp6iXt(ODtFiGhR3=Gg@WC;T^0i}Q*XBxk~Ui`Euo0djo(~l`n`ozam z+w(QXPIH~1;d0ewfDoKoGfkspf@wKe1@Q8;?D?jp&1{wN^5Rc6x;HJcfd=QD6fHQd z2S^=g(wEJJ^rxr=5Oaz)%_3M8Q^9#N`os!dez@Ur2wL4YiwcH$?E`xrjEo#D?-h0m z%V)~;4cQ)thl^EjZc2!!Z_A&nNEgxfw2t7{nh2GEd&}`zRY5Vy?Mi~UMR=i!{aS_apLS}xoj;Iy@F_M(qdCl0;&%s%(14~^KNV6 z_y(@2IZ*hc3newCL$Ob{b*V^hi_tY68^Gg@6O9f@K4!Vh?1gvC#%@ZY0*tsc*p42*s@WTA8LBYPo)qygu@oD@?^| zmBPjuw-jkd`?E(<1l)PBPi3bmYnIRg;I0uTrKEzjQzfAKujFfo6$iLw*W*ig3JfGt4o9I9E3Z8FSU5&Sx*5>>@f`XeG=h za=`9*1+l?W+b=g164>HO>Cz)(py1sM#hcpgr53ktFxjqZjn8HM{0rmc&`<- zY5<=yxkG88MHh%$Odn1V{~F}{x7S&^D>Hx^;(FI7vzFEDxHXrJE-oJGXttAZTsa)A z6g1Ah7Lye9Q&t}B2@l?n6~*;&|%Suc-0{9f%kKg;NlU?-rR&?-lp`q6~O~tqwt9?v2NBp0%_mZFj zBCO6dhE%JWcV{u{*w^l+dH4&p0q}j6UBwHg@jOP4PkcxA$)3kNGEvPBhwsnq$lm40 zwt9gTO>dQZ2I(bboT=H`M1lYa?{~J7(jP5oPWyZ+?Uq@f(BFaCW($Sj@AYFH&u}W+ zX4ST57~9;Trpw>%)5h_s1YOr#?Y1T;8|u(?<|1(`6T`U&xdE`2M=cV;z;m^;7XGM8 z;BXndfd*dd@m)gSZP-&B{Rv*n%Jo9VeZ3Ffx;Z*hF{$2&yj>YTF1m4aqGEwXM@D_j zERMgox6j{?kHRZT6ddEQQYO;#*yH^s*3!}9LiAq$LCMC!XNHV>XN{ZrxwdEZQYkP^ zDX^@~p>EH|R~+AOecNcZGMIo}NtGIb=x#x-ywuDnHD757b-!}LwGj~{WEz!$pv>g>e3_Z*dW>U@W^uN5nJ`E}w+#jj!Dp;-n^q}fo z>zejvGDJ3d&yZ+ z>6-)S8oU=`>VUEWCsfkuYX#Zyqp>zV7Ry}{8JEc$v8ODKPC)ofaH-Pl+<~zF%$e3; zeWjp~tXhDxqh#I3dLzykIAd(u&2=Di7bo}qqa~QpeyBA^<9O|7>rf6ukMbx1yd28X9 zOAv1;xU@aYT1#3V^0?l&@?zFuPQSza7+t!nSXgj?UB(pPKkloIe>^*;@_kxuSfZe^ za*uy`d>HD!lPCk*izC=yPP2h}?TrKL^c-zmTx@J;h*RL{XhGd->DunDjv=!p-t*`8 z*JU)g0efRve9BoD2_-4S2UkHEH}FORW@y?mg5UJ+Lj2sge9y;^S~PI?s;&sFV(aQM z4j|vkRrbF)+ez%h%|M;(n!>!dS5{W!_hxr_DQ;_xN`s9Ni^86}%BTH2zKdJj;zJKz zLqiJj)S@#cS;`IFijSQ(`Kkg~1xq;QtsrZSWQCqtCbJj1EbG2u#bc<_S=`tdWvyM6 zEv2ylqmF<~>UQAv;&_251wLNv&R_DZxtD*KLZ3V`?;S%{TE5j5m&CLORe*1QX$mCE zWl*p z+e6C0Hml)G;%I#ZsQ=yRsURK!Zs`~Eq)jK0-EyvHIM1H{b}pA3`a3j_=tBM1O}y{& zU5Cg06>HwbE`PFJrsnc@KYjbIO?div_yx<`mF;fh1EKT$dKT#7(buRs4@W@BnO9DG zeAewVPw_w>h&9K=ZG)CU`KaXTOK-S2N~jUiT^{l6fZ~4hcxEKj!*JMR<6`p_fo!`?92!5t#xIq02$m>lR;a`!9oN*7 zlbGF9q0m<-`s6gxoMK)VtVcHm=1I3RNEYt&PD&Ru%h_$AouF1HXL;uX+G2-Pjm9(r zg>`U4=}IySzbWjr2W{D}fGLQm)k&(@&g4dBan>jOH(2SnUQ!V^`;M7&yWgj8uojE4JtyUQ&m-ewr=LsFvWhMU%jIdfX-EzheJ z{tylKOR>kWFw-OeiupQohT1JAMR5Mw_hZxQ7uDu%{I~hWxn;UN(>OT39*Myz-!>j< zY!U4op0`3sQlJx&hTD9#(!l)_toyT55g>GDxpqDb->}u7=*i9Hv!^~ge5-qNF3#&k zVjWGMdz&;t>7L?hNXA37FuE%T=6XOtBH)7XKf7HHIJZ|={_0Y8v6>m3jD{6wJ2rWw z0^O~x3*%I9yES)0!Xyjkaa*Y&k-$uDLyE_4+`iW*C3Qt|YI12ci2GY5U=|zdz;FI? zee(z{D?&?zr>3S3;Hd>!(f>%=;F~Ke`QQSYcLIL35%d~ff5$&9Sx~h__WHLKd=To= zW@0`W<2XIjEiHMU5aIIiYB-k*|64{kVWbC~J;3Q#SMGjwfydv%?CcXmj$&xF<5SC8 zf5KNa3LP4d5E@3J9Xq?>GzyYpywENiC$N&AVz*iy8voag#&{sGpuQrxpbVK{K?_%P z3069~FTsJSnOQ2#j9@M9aTv^iDT$eR?+$0%kR-Yzi8VY%Tp^Fq24xkgOq>{FL+k35nuNv{bxL$QW@wB z-{U3Ke{}&_R@T!=ty3aUe6!=7{ zv_zJ>*KhPYuj+ZZScyUr9X$910O`fn9q z&_hV_igFxQO*5x%HAiV3u_h$Hi26eJQv}^e7ZAzLz-XEI*kzS<)rK1);MpI4(o56z z5C@i;`0_ZOdf{h&XF-!#h^6&#iAKWb+GK@zDsi8~{iy+OF6bOLgTVIU^{HXAQ*rY5 zZ%<>GUJ;X#P?4E@lo@}_KYrcvQAXieM(F|OC3%zB4az3!DdfQ_*pnFEP!?xvTB2f= z0S;DJr545Wq12n<4t3F1m}9B>xI1@#Qm#ERImyDqv%Wb-!HUv-hKs9&48y0Q%3-0y z3pn~as1>dGK+AC_9OhZx#4p*$O0sCG6@70EIN2FBXtJ+00iR6wnJ?R7vc=4o!(?sJ z9UUF_52zkLp;0@VFSH}{zp0paF#(gRb@G`kKjLE;i12&d#|7kFsJY50PIZSpm z?i?LeE>Ig>67++jjSo7K|Gf{|lP7RJOzmJ&e2jc$*6IqU4b`E!zLDYK!Uc7@gzw%F zORAh{Ha0d5ufF8}$6B!gx-4k-P;?!O*A_s#B5bE#chV>}CqBm@(zVleV)s^T=A>3o zRn=ijL9aDD8!ZN)BqmiC2^VP!INFb)uv#8Za(br8pe18xj8RNk^BKsI7?0<;&B_ z{qA^N-qKz>0^iNo6F+K=}{-=A-)TPU{*f=;iwAqN`2c#@C)Z#wzFEgMY zmz9-O{@EjpVJ;&-G%<-jS6F&xW>lYfg8bKu;`~lE7NTSirIP8!MjkXPvyt)b&+3lx zAtSgP6a7~aH}9X%f4=+SPw;;%L;tz=KR;mn=UM;k{=aB9`oD&z7X=|9PyPsE{@FfX zQcNr^X8-@6-5l7YktGD#?=0k~jKa+LL@oO!j zfZ+U0e-3II!?*wG;#c(l7_x{-YJIaftKr_Y#w`VD-kS6l(1`CJ6`%hyw6L_)=x{Dd zFMo^WA|Z<0v}09xpE2{Z-VLpnm&_F#9vU~dQvP*|->Oqf|0G>Fn_NvbG*m0_nB#Ga%+&zZybju*LT@m-B2 zS+OK-f(92ququZv)4+BxX_wmMRpcX;N#v+mieknV6$iVv9jv~nB*oL-?f2}6jd|fu zgQh)It|>g|@*yw`od`?}E-du+-rnwn@TmALbArPT5zPi{W1CBTlY_-J59;17CN=Zl z+azfTTHO!sb1D}*_BfSzFVO^F7PP)sR?bMkUx1xEBn-5>sXoy`hRG9o{BBE?dT>;^ zEO#l^uw%BoN2}t;O^a>)%s~HK9eQm0nMzrQB6%!W6`sk;GF1y-R5?0jCFOW-{8T`c zaK7MA0#GlVmqR~`VMpryUfK8CyfX0{np^r+rr&{>FBql-D zKdk?&CsJ)js%uMN&yvd@bsf#O%&#Kt?Bl5yD~wyz(LCvLh7?+21=9M(#7cYEyPAWp z&tr0i);uQ7X8LUaM!USqXeO*6gfXDAJ8P3`3YMd^q8sr1$=OBK@>dcDHoCK)8B!W{ zab8Q??)kbU??K>@k!JiL3W_W~r`gCrS{`P!`al(3*f2YZS4D8ZyqdhLGILY?(5$A9 ztr}Y2lvCNxo}!5AdVcsTzvJpU2yc;;==G-%F*Ij;W;lO)5>Qra#C!6<-~kav@v-aH zIZTz}0&U55?9eP{WbE^K<7u=mx#jY}aK-N*UmFI73$Z&#zdk-ip{rH_z zwx~iS)ytfpKs7bvs29j72!9nQi9eBA%bLHw-*57!PE{HN@CGI0l9!rHvSFM$%$GbR;`iz1s{4RQ*K=R!Ggf{s z+8qWwIa-SB5%viP%u)rHm&s8f$(wf7&)heDgWAutCgJJ;oX;#T;SEm2GOA)KaCI6a zlM_owkyx^lM%dM`*ORu4DszjV-R;BeK{Z<7qcGV;rN_bF_Daj6r&}768Bjl14K~=) z)B~l1b_k!hx~I^IWIoNipHd$CS$~pnXINkVUdWq<=;UlF0cePp+#fmSyRbIm7##_j zi19kiLp<&mt~Ifti{W*{<-&$X~}&@I2AB<#s6o@=a7q1CKen z2zq!~`|q5QQ_K?wG9A0Bs~C8Vp5k}8%?>^!P2L@r7g@ob->I*LUpPm_$J#>+BR zBI4&-sQ(RFKMc`fp6v}Gp{J96hU#6FE)MYGYAVDKy~Hg-4R!B+O6C@qm8i8Rzo0oi zbN!$p`3CcoHbSKJ(NC#7EOC51f@e4czQ4EkE3{Zx;Dz@?3dh%QbKF)S@7b@S!J`#J zq6h8j+$}10LpYi+gK&qx`dwISB%sjXzMy-PCt<&^3mDM>f=Xg(KT~A*51h2 zI02x?1bPv$CAuW{e2hdyL`O#85R{(98rtJ{NSoK8#YuF`IEm>(7m1%%|5kAyf%PTZ z?2O~}*>KkIo=y}mXY?e$QgpA+pl(c0PU@Ep*IcmNQcFR7A|;11k7@_c$h2vg2aKW# zL3g)$J3f{rv<2locf(8zkpU*BfJ|MBi&0^1ibe&+{Z?b1SuoB6{`Sp=EySBMpcn#T zRq$`AecpPIXM<{#*5%46ye?CVe-Cv?o0!~M30f_#iv&f2eD9}Ng`2!Rjv*dGg73uM zt}w+qBUcg=aup#gsKr*ri1z5bhkt`<7>TeE7|8mJBXtHCWmBY=x%I zd!O}iSXwJ3gD6Lee`Z3iH9GgY>TSBVaMO5PBI3LBbF}bPi6C1FN|s%OdMqH(s${qu z@Cyvr72V@UE0#(aqWxI~SiWagV)q%6=%nOfVr~Y}N9no=zglxT$T{guDAC?PTVxh< z$#xA5(+zbBa}_2AhR4V8ri`jopk?7Ucl{ICI;Kf`-YB&s5-NKipQ$(3rUEhvlrp;2 za8D$+t)q?(lU2S%yvZ=9=-zb%BNi=yW;0{x*36U|=E6ZwA4@m$6MNIyuCVy40@E65 zaKo)YzUrS>@)O#0=Cl`nW<^GpMRYP3`hazI=hkS7eaCi)xNw10XrA(Qp}j+#xx$%S z7jFcAwdq&1$uOdXZLf$9lz6P7-k-*(wo!v;+HO7^d}O*d7en+-JXqvk#fv`Vx4KBM z5N(jv9cdRG<^5HV*Z4;c)1|Ydr1Zz!kKRf!C1|zuK&-pNnsMXK=m@rfT7U`bdRF`X zLJDYtY8f{Cq8Jl(Rio%$qY;fe^JN2nes!vqxp`^|SBEk{iI2zcrTi4!^%S{lf;O(} zG&eU@Xoc1b?w+nsfyWWpZPLAu|Jwa87Z5%$AWQ5sVM?fZ$}si~4XNxvtiC2HN-BJ_ zT1^(2O15q2_0K?0XVdTG`tewV!p!MCVh;w0C;U_5Ct~Kchcz2-Ey4LY0V=8@-~GYC z1+E+bq;<8BoXl6Z1j4P}1moMET(UZ#R>x?&3if*4-*x7!pIALi#~>@o=;eNE$twi4 z9yr){JN7B+WTegW;OD^}sndRTX3NF7-CSJZ!ei_ac|d|<34D%=Bj9XgE1ugk1*~nf zbeR}HV;n4wMP2)v#x)qX{F1pK<1MiGoPw{cuUK#H=Wx4!p4mTX1_s737CPe~Ch4O> zJ0ba;mvZYRhd;BSL*r~$hek=)TRvXKsi~oq$Gm8F*iWuE8`57f(H-96Ue5O7=^nrR zRLQ&=P|Dg0>>233xUS0A)$Gy+g#5(yB*W;LN*bMRa9jXTpd?lh%s<*A$DCn{0j$^lREbk6J{w1nHI z$^{JXg(N|shlRR54DvV3!rX7xpJ{FdvLRZMMv6m?Oh;!(iI}Ghwdy?cy+H@F--x3U z-wR`>>GFk?vp;BjPZN*5#r+3UYJ8D3O>F^GvW%r^pDo86x~!x?DE&b5pWmIyq9X#) zG^=UXCqrE$$7D5@8LeKzDc!f97A#Szr}3O=BZ-7-z|1DJM9EfXN1I%aTQ@`7k@7^k z4)gxCo-0x7XUuzs#^sz3(4S0TVveVbVf)&7wEw0(pS>}8aSG@u6jXf#VQe3?q>pka(%_zlD$t>!Au)eC7tD9WBRSH3 z1~`niIUNL@J{Q|i=1bE|d7n>cL~M(*8|}rFJIaj-;<-7i`(qOa8A6`PumzS8K#L7p zkP>wtedJ$YM%T>l&49Lgn#@Sgt^(0D@>A1^5d{TR%D0Y*e&6LD`EE)yyrFHWHFccr z!Y)xopU^m%G!a*gGCe7*?rAFGtm zgQY9D)$F*Y4^comy|EqEB6V*qScyNjyV$YkhWyh4Zk{D;+*{#G_vddg8xx z`woaJ>ARP)c4N?ZTp|)Dwu_E2^$py(ly@_AqC~T} zWC2{4A(d!PhdCKvfdQ-Cn`|z8f)xFKH4y9q*w6DM6XYzfxC_*@uI|Ws%_GmW-DfL| zy$j?$Pz$*tcdS->!aj?eywPYLRik9Iq0={2hJj?nG?#Gf@g~sQfModdx?6_x#4SyZ zp5q6>mq^dbps9gEEzM3h`Amhern*`jZ&RHWjcrx#hcBmB0p|l(?GUp6A9wE=)@0Xq z4T2~r2;3@75U^53s+3Trh|)p_snVPDUIQW^ARq$L3B4ETy-Af0p|{X`F98C9+1&T@ z%slTmGe72d=lhO1CO;5jl51bN_O7z~H8@CrNarJWkCP)a z_Rm7*7n%NlhNmoWEF*YR zQxza(<1gLM1YjQv@AZlaX5x$Rck1kV*Jqu)c?>>q`POIA>|f$f@8t@E7nlxOg*%1j z$NW8-fn&FGCGP{#PAnz{9}$r(H(+vuWjgSGe#MQ~|JMdS{|T=7|AX*>Pr$;W_z$S+ zzf8M-^s0Zq2J655h5__N-mX6pRd{1#eSM3w@WpVQkp=j!_Ha)|^lLS8@JA3>aq7e}>Or1&3O%v4~qI2%iT{pz{8 z-@Cnok#szF*qHWPxrm6>Em^P_Ye=&mqtQC~buWz`n%L*aU#px!oMMJpxt>0z2fHa> z3ks->Y|3i&UihE}%evFFmzV>V_FcHt`)4s#S+a55&Neom#!@00<{j~}S2o@*j^^$5 zUXN)OM-&%}HKKc&YP29zR6;gPBg7-l`0>sy00k^B`CML)RN8jsYPT2vh76+-xHk&Ji zS|>fM4eJAcDy7G0q-m}g$%0{Lj$X%=(-=MxEq3XGQtqQ~_1^=X_T4}8y0IKXYCuYua#Xu>;Ly}W2a%kqngeO_07GzJ4S z2E`nQ)&Xp^Q@E=Kn+FM|-WJ2OZNBL?QtQ6TJ=UlhrXv;*lCPY@A-lbks447mqEaxK zbm(>EtCMOr+Ljh))h4^fR3QS-aS zP&Ew<{DL<694Ve8)$=>Ab07F(Z*p%Z8(?kkxL{VO?-v`&UnN}!ugRiK868-D?3KTg z8`;?hkDQwqmXjPe+uFs2?|O(7&;5SU%{aJ-RvH zdx_UdN}TvyW>0Gnb)K7a8Nkh8V|Iq0nC7O9AQhTRm4PHY{2mZ0)5=|a(R8}L4B_vd ztE#HzFfs!2E4YQ*?%zRdVVkW|kWr>ulgH|o8nbY4aFDSo(|d~vby|L`e2-W`2%#gL zTu*Rz29wIdp%JvO%h!zTPv&L?-J(*(CX3qI+9)4V28!!XYQlw`-!hPtTTO*h)tl@# z3}2yDVB1(w8sVVO(A4N3Kko0&R42y8#l?mzl*i=-1~MYFqO__@UORukzFXzllixlO z(Gg9t8H!vdNgUZfO69nF%;$FM9a2CYg_ndYcxH3JyTR$%ZZcDIlA3zU&wo@Ux3!}q zgaYD?CVq6$JiZ@+5BDk(!rZ+}SZO^|X5J=zR`4TpmT z2MWjCMpo9kg~SooQL$*2cuUEiWxah-SipZme)?9>?YQ^PpNIR+B4%=O+C^@SSH-4# z1M{UOo}Q<3LS~^ydrywl?P2G>bUP|VK34dAs{z)P+tb#jhDW{8@Igdouf_nfYJ6Ow z1y`YCp;4`>Rt+pPdqWb!*DI+;Um~AubAomB&iTpC#%w9i@kE1VX@mB2BafOzZqxCv zxcv5LLkDGLDJeVcBD6z$aGy0HEuTNcD-M%*6(#K<1Y3>^2@REV2--ZiZX9=B6W985 zw^BDxwKpVQ&dp6j+=XKKN7+=yUjrRkIlz|0!KSf-w5`-cPQi)K5&bRLYt>9LKWV!( z%k6|(gtN}^(0|qwtpxXUcLFynmUqyNH{eQ;kf7Fiyf=S#FJGN+lQRj}u*B8YR2NNE zB|>_7de^NnxP&3Eqi(Y5@b(in+MoYa!}W_4=5Xxx6`ZV4iWXxqF^uaXQJ!0$sHK$% z0qYi$xT?|!;U@KDB2PYi`B+&Ug3lq?ig=fin4aNx)dy2oK2h}AyKU;{0#=GGgeVR#mMjpneyzG-|>b!C^;hQ zyetRi^zxIn(|3|WZG3MDyH8fVFRiLlcRrz{=0Bqmc50n%enS^wyKOdbY1`A8Qj`$V z5>GQL0}c^7wX@bAX#&^pWEJvnNkNA&N>$49p&2mm$ogc|jjQ6&>_~DN4%O z+`}ubEK&U5Sip`-ecdWGF7C#~t0zx{`1yl3;Ry)|KYya;yqbETnPHTi4R1r@WaG<| zI~M$4k08HxqwLQSTf1dYu!N!hm~3d$P*G6Ycvd|$j>9_YOVk`Lc3M>B}&g!>?{?QGQt6$Mt4>YAECnuMDE zBtDh7d`b$6x|nSPN&m1%hsVyPIqqYjmVfUpH{QtKP97_HK>)aQ%8foe5-wnUl#-P- z17XNHE$oilL6sWZi=?vme7WP$1PVN#R0~$nW2r`ff5W0tF&cWgruR66A1s1NI>&YO zRCoMDtF=5|Bj$b2O^*U2gdJ>iq>O&-2)Zjh=c$4fy%7s=UK@|4Yp~ueRJEKO`u^rk zSoQkAx!1*?)u~F$6?{1fhgDR8e~8EBrStKby-8fT>GFFA#!qkJl0y>jU-xB4F!{B-FPGE1%20aGyh<26yBK3m=HXz$I&>C$1*+HTpO#RvBn;$K_yc`Q*pcz~#{bxz<1 zhDwT_`x70?zxT6MvMg(f-au(=%^pwuvQlwSP7e>aJ)x-&`4)muRI1L45ET>i!YoTN zmCB!GK^w90{T3=+g#pi-MYm>c0`ZvVWCQMjdhx;+nj~;(GNGTzC^=XK_NKd@UTPhp z*^yGmy1jmCr445SdvCl;rAO|iwJS=w2+z&##_^=u0ceMk%TRrhu9qSDr41y0v?#?d zSFI7d*RYvfWnPLI*dUU?`>mG{;^%W#A#KC_-=_s{JG0)~sB&Ph%+d9%eYefkc0W*h z#C+nzhZ>&K$!Y^;%=UQobu4JM`|>Y*x8og2#wXi;jaRQKA@lcoS?Yi{ntEOZy}JI zFX59C=Z5c!JXs!+8&v3thJB6{efze-ts^s@1;|S4IIoZR3c|z$gHAqa(2?roayRi4 zof*u7HWn|^OF#bs2=~ukfa;!i5FS_r@9?`WsOyUgfb7v5Kj40k2^20be%gQ!~_G8e4w=p;04d2TyefjoKF0TQJ0xw*!`q>#JR>t24F$b^v}+fCdBTft9Bi z7_7o{BB&;Sh?-k}X)QHOv&aiGVee&(MJgd{Z_nPiK-&mpFD&Y1t$lq-*mcl2E=!c^ zN!Bf<e?2amfA%(!&w0NoC5?cLrQT+J z0|3WhzK&}m3OxfrBt$0E6T`lUKBnyqN&_k?UtD4%tTry&p-5@9Lfv{VO$HKk_nInY zLEDY#Bu_kYR?KDvt-~Fzxzw4}eor_AiB_6UeS}?CiUf6xJCh z2Z!|6M#I^~!-5|NfPsV1M~Tr?iM*W|cffSV>Z%rc^{Nt$5}eNHuD`^<4)^t#NSO~Q zUmv8XobL@jka(!>Y_d9)K~+#k4RO*h3YI%vx6&~UXfW?}19*+9n~s4s(Qeour7Z0_ z56eG8%O?H0smKkBtqLhy$Eh+S{sR5UEQ1c&WWLz_bs0;zy;ro;u3)nDktk|Q&<&Nz zXgyWz-u(N87kSYD{h`|*xnd$3hUg2c(NBQ>hD$meUu1A;TYS%z&kDeL=a~b zh=q=7%JZ&buK1~~NAh&xItAP68E#O2f_B<{8I z&aC9jFl-|LQQp#n_Cf)}tn8~lh*f&oq`0e@5d^Y2Iup984a0Z}jUDz>2LmFUN}fvE z1Kl!%G$BtkYBAIPqBT|_t;1aMYO&vMl~pU{l8W1s^!Ba0$-LlRRAw3(XMaXaE0jJ3 z?<;9n}v=X-OXdD6g1&y$mp}Bci(6iSp$CDuC z1N?*c3?xIWXTM*#d2Jp|5CBT@g8y{21u`-RaqvxNj;V#q@nO~RerIun94Id)Uw{CN zEF$)-yFl~3;`*P?PRB6Xuw0$QC`%BQzQNfwkPI8BkT^*do|Lw;c(pwSBzF3rKJ^@I zZ&C7?)c{i!AgqF+U1*BJnyRkEFf(Ea81hGz znkO{VN|5fPgany$-NIB=z^q>1)#+tJs|uEUI)ib+k6v|OY5(aJLm2n2?@qqXqs7G? z3U3Ggr9$wtKg~Gj)$`}av@WM>cXmvD4qAVce;7+`>t6G&4u>w@SX~9?k139D$fahr ze`d>YG+h}m;e1Ibc8F>`gQcK8xSp(l1+G=T6m5y;plFz77ZWE$szQ!@r8Q=jXp< zva=zF46*^!)!v@Y@e|3{-0!VKD#7C9-Ws=;t`D9?QxuY{m z@LhiN=FRENq3V_y{z^b3C+G7go~Y!h)Uk|yHM6!mlBc$|>wmnNeH(Kk%&bvvB_=GP z!Po~E?w;+Dq=iW}E@|>uf0`+Y9TkThtxi7wK|v7{8@oxAV;z+;$f&5yu*BsT85tQ$ z&Clt5P~>0jDx&xUrN2nEzmF@LQY`lX+erQj+t>6#@x|_olqXNh@Rr;ZTYuRtYw)|D z11i3DgGb=!3gF!P%Y&aELMrL5IOz!Pg5iOIY>UcitW=XCA;p}?1t6Rnbsforp?cO0 zIzorD*NdHI+SU5P97#6;vvy;kl0KsVFLBnr;rJa5n++Q^h5SdoPoJJDc4Nwb;40+X zx0uU<0dieWu|EXV_g`MQGqQAkmXJPR{pi!ujEw|y2#wD%bTA*2?z>0Z%=!z_HFwUQn6^2 zMY^FA)#wj&VTaVz-1dang948r=?!110SK$>iD9X~CCl{ud6i`UtX55yb$Iy-2GwZX ztNBv9Y0 zbG2*DN6azkqsZ=MVp`n3#1r?Hw?Yo;VyuJJ1K1dMr4D2_8JyQKv`-Tx_saa324J(- zJQ1VNvO7~N4gAlM(-W1OPeR0+!&oHJ0ilW6k3G+Z+Qwrj+}zfO{J?@FFEyJTPAn+< z?rYZPH^p@7S)ud=1X`6cblV$K;ZlraMY_wXvHZ?fgOtN{t^{bmRa!M9lbGaQS?Jv@ zB>n5xQD|C--EXQ7n7{sw1x!xHVMp4(qNC$kTr7t^d+igQm$N>T4gfns8i7b|f=G_7 ziPFu*hj0iVpMo=7Xd@A*c7*C|n#254K8DsxvG?~Cx`j|qi}xi8MkFTAR9ZIztDZqK z921jOFlRMBsH7fTjk3hAT?ioUn>nAc`4CL}ZVmgkYBpTOpD2B>vj@j!H4jymVjgms7inu^22U}z?jS-{@h zXk&56?dY6!fkevFk>K|2y#vL{fPp-yuGAAVzpl>Cwb``Q93^`5;rz4H{b!l5k;P0l z^Hw&iX0?J3P<9C75nq4&`C(6gV*-~elc3^{2*ya=3T4lzwbMHf*5B2_kUHyeC`G5O z>8UiyB4CJ-XC2Om^g6*w6w(4hhse7d@$kWC0Sc<`G`}VCS0Hk?w-!Y2Y{eq7c&umN z5yxqW8}j-dZ1t+~c;f>?a}z;v@y3>~6v?fI$)>6J(03Pbo?j)-{Z{z+n&nodmYc?I zlmPG>6Mp^T1%TQ8(|7iMv7s$Kes>S6pyDaCr&eZ4j(`IsjuoowIWf3JYj54Zp;*p@ zdCkq8+46FxSzyy`aKEcvwpzA&u=#tfyCWnfEmS)Cm7U;v6%!p@oD}QbHxCV*@~DN zveihM2bk=+wIZ+VPId$zitt6#MZ|s;pUiq2SM!BY zk&!vCr%bWDvuwOPt9vOLxp8f(u`2jn~L(qW2L#yamp$ z1qF^m^1v?V>*c4ILM`K5kHyfKl$pV|`DI1R`Lx^QM_1(j13GqDxvcs_5fJ!BYTdpi zs=~fIR%gBpEBlblX>O?-tIQuXVN$hkR_w2p6in;%XPvAW+VUT11X zhq@Z)Gqg0FKLd4@T*VjL2=kHLL8OT6v?_^_o+H1d7>F}1)z z*$4Zs-I$e&8mG>SJQ^hv9@bIW9X8+ECU{O*aTGArOvlUE1CH3MD*+v=-Ak;fU5DB5 z95uZ`X7Xx)otC{xwomZu4=WU^uNkDDF7(8M@JWTiS1yt*!)|q@@o3Fp&Ef$#SLZ%C z`50Ky6Nw1#+*v`}L{o&(@@({NYlcwq3^s@d5FDK>9CH4YXr8&}XSPE$zqJ6m2Be*D zB=T3T%WQ>}n%I&%YN)G2AP~iHUw4($ITSDeyUInEuJDUslW5ZJnjntxFX)7rz z3Q<75yH6G&y=@oiL2$Y-S`Z%+&y``1MT~hwrez;MYIQ@|9YnQq?odu~=OTkv96Ew>;!ls{Gu1i-?=96}`?}Ql#1Bhcs-4 zS4$kh{&86bDCXr;ow0p|N6#n2%IIdtU#P!B;!ujTIBIIl|`@`X2 zOF#{QdMDc+4L$*3#taLvqj0`_XYfuR@i@OBPJKnulpgmEnd#8uQoMVHvMWtV-9^|9T8)wFbhF=2wRP0rd zntV?M5+G&gZW@~F?_y>%zDuaW#Kmy8X5DS}e;CcwIHdai6kQ20W1`@Yb;O2b>j1wM zKY~lZJuY=dKGAr3({Fi_s?Z8+7iYTX=G+Ti&;5rPE*4|faRQE%+oHz(XR!btjfnv( zHYgy3IXz)kD@xnb?}@Q}Kqr^^TLk1zsnF@>=Kbqd7Eii2%Bk)WhM>0H*B={P%?di? z10RnHo%-{m^(kwlkC^n;Wq>;)*czOS#r(Yhhqlu}lFZgmHP^xzK$ zLF*!fnso5)xzl=$-l8hxn*r8~CFGUr#Q3D*%h~kzr2vr_Nc)+&uz8wW}2El&iMB_Ou~bZDzE8- zu)Atuul;8IdgDeae#Pk2I{9`*tKr?AM>g~GnMgUL?Y)%Yj;CkQy6Z&^f{c~NpipbIIlr;d9^yWNgkO3IES45(*TMuA zm89NRU7{;QgQH&wyPWbKr}wA4J&q%B9XJaUAjr0+a1q7;Z7sU?0!a!wT%;p)fK67O zTG7jeDkBreTBi|spGrqZhi&i5fTq%4VxDCu?-7+7?7i=gLgFhOcLz61V|6RcN6>#F zI?5Cu@!7=?#Z-QplEADxoSq0@yz8jZvJc>5JZ{hdzME(-C$I~R73Pc~M9KL0`T4oI zQSn8M$!3?8cCt?nTYC2b5JIW;Av(t!))N)>ZC$S&H(V+##&jP4H8-?)up_I=<9%|| z9H0bCv-P$1uvpH;h*+@oeOw$~J%bAYd5aYnLYeDyqdV5#3+q8s zWV*pI;&;a=0Qm=}z+lIUG}HJgWUn?^g|Fs2_(~hD!jp!o5n)--Wt~)|s#4fRY-j=p zC+Er5ECBrLtsAi$`>!H&@V!u55f2eL2JIaPZp(?;dUvQBu;BLl@JXDD> z%&X>T4*f`=3WhpC$|efT1GGi~B^$6l%*n^+iVlbfc8^k`Ib6BCIGomnUA*_a>%5<; zd$__v5R;r4)}UfMHQEdC7e@B1n@UVkI`td7i-;Hy`rhH=qt&h9>hD(YiX_ zeXi;LMgh2!7k(N}V2P?K5mROvZ5JN@Zr9=2C4 z&>GBhMh*=8RrvefLw1j~xN@p2x%01P8dInCm%C-M42C~x1U+0<`z%?D+#Hg`kV(qU zn{POK2%(s?)TbxAQ;0N^T|VLdjFZ%P>cruKyPH$^p6AEW1mvuXZbN&AS0_|sT7f$^ zHmGoCp+}n6Hm!FeGGD5fMWWnztf$q>4;r6_YC5S_;^3hiw?}8Lx=1Z)A#J=i1K(Q$ zi0z=q1#U9-S_Sf*CRe8q96Q7%p~GC#qCV91W8a`Ac9?2~DtvE}+ch=Sz{@A*XQ&W6 z#2dap$d!3V1yZt&u;Y*8-*Vw7c^f8lR0b+tc(vnbI2}z zYhPp{bq99t_zDEO|4gg?M+!HT<%x)hTtnT1GJ--v;`7c!sK%<_LLEM+t1I?{^j`Im zS`l)##1%n%2(x#xy+cf}_$rd&FIjjFXLPic;d^=wph7ISgyS+t5tq?WxI5mD&={{Gom!;N)KBU5Td0bVSIuxVLYF;0&3uCcnU z@!!9nK7E?1o>n)1seF~7-nGmzgP~+LHBsZ8+#GaZ=rkzGXcEk+aRseoq~3$Thr{c4 zI$5tr6&d1-XiB}Wn7XOyWhwbBE5DxWIs>6&yv4^evR_SlbDpEw;ZTvL`UM)p21O7< zI*?Xvupd+3Vt${&cV_aZw|8cA^e0jGA&kSx2{kyVaH}xtjJ#U?@L4#8d{wsW9_TEf zudknObV{ZuuVr0TQ{R3`l3WLrfuy6FOyhOjmh#tq&7|H>+`;c|09}7JaQ(pF8n^KQ zbPs4FyPZHpe{s~?@48J-pLHwv=lH|~x$Ws6C80;cdiUM6JD}ZloBVeBqKpM{n}qf}jYJ(IQn@H56|aQD zU|-*7%!0D<+*hbtS_+YMv!Sxsl$0m#+SU!iEG*lTjxiwA$Y0{Et>Q9YYLOxhebrTU z9qTc%0S+|vD&`fH08)=3sw*aDt>47!fQ{|fcZFl`17W>u$iv4Nyt^gE<(OUM^4+=KZ~LSkuf+`?uP{gD za#oTWtgOn1DjW?4gi%O@SArGmByzMoM~N;yGqXgWlFjs&xc)D%8A_A}E)k{OBD&l+ zfcn$Fv4F*nP!8{*c8g&}flbyVA2(=v&!3adB~8cb3aBt9=*ON@2kDDbVCLkoZ@1#Q$X~uao*jjVtd|6foqV*ap?V?+-zOaxGBWvT)6Je*Ft!_)0>Ehw( zV9TF~_N=U|QfDGba--4fz=)IvY+6gCAXU+uUSo`C2lDr!q2G4BlOY}rv#-9b<(J0N;;ru~i4K)ZchJm0qUY{n)%mL?)lEEm(NW0kDb#bZMQe7B`}-^+NFi7c zL{JVTf=o;YrBLBaiy$26k9HFsX zKG>12iIDS9DxUe3kj;8G2h3*w8A&Xr+{SiLvIy%Ov2P&hxI4MttMuD1I2yGvv$~;j zMVuu^$(6jD8+A1TfIau!H}>`fxXJtec~nj3;1(9q$uY~Rw3?}N+TJ)YlIFIa1@vsq z3UgTu6_1(Q(JAAVMdd4HRud^l(E{fuViu12-nOsMv`>C@GVSLLRIcFn0T)Cy$#d482IirE~B)Sf)vK+uREWE23wQG zWqISSjore1XA)EJj>UoxmEo!nG{{%_+-=VkeJpO0Qh+!@4oA1f&U5sn^r6VaW7Dz3 zODWjJ*EaEzQ;PL4TEHQn|HZfwEfkY3B^TM7_$T$5y0UuT(&f;gcC1WS7n|ofB94ZJ z-)Sd<^!w<(E({KbwO;URAzx|d)P5)>o5li5d0A%ILw+6Sm&fkf$5{c&Ox;~QOEow* zc1Ww(Q#$R|OJJr?hvBo`Q?+_Yt`yuJ&+8$_E$cE$CttXEr{!Evzbf2KP7k4AhXD8y zUB*a)vYajR8KvAVs%OAQ!gI%}!1o=J=G(4fF=|m%o}Sg%gV}D)u|Jv;`gc)AmDWQM zwiDe?DCYj&s?z=7=nU)*b{J6X3|OS^S7efm(5|=;&RoSBZ*TvZ`G>l7Xulvz<%Or9 zaQs;t@Eocx#*fvT+(jH!8(_J02*7<~V?ThH2~(tXc@z=0wp(ffz539wRcn1srKR9F z!lC?l<@3xzAfGy^;!Z@CN2epXOPT!iysd-6tGf9O+&v+%X~|RY@HnI0h39CZ7%nw_ z#e^zXe42GQ-iXpDx44F!o-{w%}_whrSxT+z`vP9I7D>+bEFzZ=P3nXS#3BHE7u7-2QsnFVU4T;KdMNU4vO z;MkB~*M6ha6qd*eKV0=HQ?uo+s2pL^5RFPRs{4=X0JH`XvUe`(!C}l>KU`C0N61JvV=5nat!MgrsC-fQz22jDy3j zkS8PE$GB5(RrYZCD#z{>5Sdubxc6LKNLx)aspKjbeyX?J{0UqnAZpX~lB}7q5cN_k zvEz-`eQ7PIM0Qn85W#P)Fe)?ny;*v7{R#4a&2>Pg}_aV}j00~!gDE}`d9E(;o@C(v2 zMUG8W5@7nwB$7SXKy`avJ@W4Yj?}!F%Ci6ZNUgQ;Tik*$2U7?r-xLlC5)fMNz6DA9 zY`sN51I}Cq>`J;=D8sRgyim3G7zVq@D57V{4-ZFUrS3h<#9RW~Ks@5DMS`2O{iiSc zB?t3e33^Mc$F^O!*6yJV>o#&Y0Wp;`&T?BCxOq4X_a4!*kT|-cW6;Fu(H@?)|0>|3i!`b~ufVbE*e&dx zP9}osv_Gef%#BvhmRP{$t1^(p-XhwS)&4-D0Gu&Z!~l$#eg1C>$H535tfygNA%h% z*J{CL@UyV>Oii`PNgs+DGRSZ@SsZjd6?8|*oJXRxWa`uMop-ik)j~B-FUz1vFI<0r zTDim}*fNJ8<{-}+_wFMZK5EcgqT2pEkJVTa@5O;ip6cdU7X7viV_-c0?g?O^^(FE3 z4l^tK_P(soS===Wh9*FG%#YM9)7)ExDIVRwFGC%9N$!I6$-+X~y39PIrfYtGvE$p_ z5rvOFg2B8k#5lAv=klKX4NFT)fZ(Cf*XgPH2-K>N#sCPOMC?NpWA-i+-mti;PZ*XK ze6a9ORs^^VbpUVx9XKM*3JufkI>*^Je6g5Pr)%8<`e;?{9W#{jqnI_7;1`Q-qsRC0 z{it{>my?Ek`Zh;qf&=?lE?V2#26YR$G8A*x9_N4OpHPT11AKT%QLtN$pz_s<8pQQQ z?CsWvBnpYC_u5*;sVK<`X34$1CKQd$PZvh9jo)tUq?bJ{$EBvqy9@`W#H6R@hKAzh z<|CIU9lC%BrTis1D!lgKYY;o=^QtBFE)yD`O6?bfJ+1Nny||MTcjCj*%D1g%aUzqI ztd;wj5%i&Hw=5W*DbF{T5W<4}q4%~L3l*70w)Z+D@)UoR;Vj9l^)952h-SvA1VPiOB?v-&`Ho9=dU zdgn5SK^nOQ_E@rxzNn}|JBtVGy6{pW{L0}OiLt`YXs%qxj>$wlI{ATeawQ2@din0d_@V1hd%)s?VR;<3AA_nD{IJ&HWM@W}Y7Aj!?Rh;R zPHybjV*26y(r;4Sk2h-G=xHUmUCEjJg+Rd9P)SEA;MMh+jwE7IXb=eC_SwnKud&HDnxI z&%bc|1v>Q|9%ZGuGG(98vY9rgX3P>&DptQ(TMusWq=6SHlL~nHiDosf3}_)Kn@PRw zO6(nQJ5mH9NrR51?deV;EYXq`=5PA&wnw6$1mNZA&fRz;E0s;Nb@T?^owwNA_3Oq- z)--;$HgnE*7*L#~yi2E+MiNCY2u!*XQbRsnJHhsm?W1(T)g*y<@H!6l#`EN=7NFOA zScx7%ewv6|YJTDhz(F5FY%gMBb0$C!2x=j_8__gkfzmQEWx2}l&m)H{(Nq+t$qb8R z4Z@^>tu^Poubjqo?&m2txSi1Vx(<@%DyA$Q+Mk@CIVYYGd#`)U?l$&<>cSz)s_NtX z57$NvR2N$C+eF=+D~}<2-mg1)guac6M|F%j-6-p2|Mc(Aa>a;=eaSGI6{5)9*|q=i ziUFmTJliD3dbUh&c&+%EWXOj~C&zvrPaswTEEdpOS+Lw(q*Q41>rb`Lc|6^5^9GY5VACXpjs@?F8`E zj?Mat^qcixk6559NYahvpL|wp9b8;k0OTxN+nn5jA5GeNTwc@J4W8%S%Lk(caf5Fv z0t5f7my%au0|IHTTG1Ok%u$4K+z$bXfbM7(MjJGG^tOS4W39C1l=B=BzM$Y{!w7%z z4HD}9`kx;Mc+YYhNi0U3KQ4`!HI@ES#GOsCGBW)O*{b~FuLG`}hsb&|jEbOpXIGuT zIRX@#&ri87ZBZ|Ge(M3QmZYTQ48#rXR8{smS*z$h!uYlM@LeLWpGiqNk?zbo zh-7*t`n=sh0nqJ%-|?V8p_K0A2eifQoahk^kJkclfaS5$THPtz>mAc&>s9#!wx&ja z69c}_A1o<3byEgV+TW&r`s~@7SuKhhAoo>hPYH$2%Og-TAxSXPO=UzNL6>Lsa9d|_ zy|}gBiMHydTvs%aw^_98y(^TZ=GvV7YN2O=X64A3(x$BODQNWwf_ONuE1-}J7rSla zV#E7YM3**Lx{NsR@bIiYZnt&*$JPJ4a5L_Ly;lBdU4PP2CWbB0>2Q92LyB;CCjUdQ zL~yhj6?djmmGVvVsS53}!VOK8o$=xk(7XrijMo4G$bb80&Ku91R4*CTa`eTPUu^pl z`HydQapI`G(ghUUW?;ZvX*#h1JG|0pv<OHfw2iraZ6XHWTFy^;)k71uq?1-!?*-Mp|220Zz-z{R(Jv z6yGGOX2@#llu0#s=GABw>mf$v5|8p4;zQZ$WSN;}5#T%?ZCCC#rDVVw%ZN6n=6@Vp zi~+(-wQ@m?#VYD)LwQ5UpM{KWVj3a2Ly;F3lp_|3nSb4X)RQ!ZMJZ@kB}1oKWy)AT z6M)FvowT1r^fx3w50~buLWy8W4HO-Er2vVp_F$@nv{WIp8mM)+84XIZ8p7N@UI|Hw zs21u-rtoc_(#a&qRD1lFVu@9>9gmpUv+a!X8hin)%rx0a-Q5ZI@1sT_S~XrVE<0rT zm9>*TYv^x=!EAY?}R45So+Yxbfi=b4r2eI?;T;Z+C|kY2j9Z76tHvLPm+$_$w}eg zxl=qaT~0VBD^6c*t@_?1jAZ+wStLi98Wn8~$zVXQDUT|=g zcA)m6R{wRujEs_NN~UDNSnVurvf+LSN4mZ7*T!?Dl6Nzd(H!h@Xbe}9XuU?x=Nm@S zuzPZ68YPAnJJN`NUv{F-uo{=a&qa+F7Xh@ZJ?Klx%$)ec{iB@8CuV|z4tw4W)H}=F z}RM=R`ORm?Y%fgp8={KZ-r<9#7JF_%k|HG(wAq}Bk6Yx z1UKCXF&`-ehvUNyB%w*XeOOY;;^L=BX>w=`ml4=8H@ZrBtZYuu45^~1EUx9Eh6KLV zEZv4PIZw5P(^KBA=3t;4oL}448?GA?ED8k6^4Za|(tbh@)kCugin{vGr`-VDn%xAQT`nVfovx7i;$l4Mr<yskSvRFyQ30->I;u$sTxm zKhVM2*VK9!WUAjIB6?>71vo`aK#-9L;+%s=!Vf7aflAJ2@pa@c<9A(Kfs<%dK=<#H=6kpX1) z*XKFF#>EAss3!mQI5%)`aB$_{{4wMJv$$HT54>>JS~>Uq`}eN(o=^W)*C+5y0NFeN z7}3*3ZlrR>n+NxS&QXYyg9A{$I{W&Ji*EfrE>t^^#@k^7yB!NngFB?_`J~8)4$jt@u_E<= zP!rhL>i<2ohOw!CeH17G{(Sdb)R78{VbPRRf{IyHX1oDgWa7jPoF-Ukv_-*9a_8m^ zNEC1%=wh3c8Eg+CeegdX2i%GOdVCiB_itGLON>Y5U*7PMf68vSO9X5qBU%6YP&e;mPXZEiU@ISWGu@#0aJV1e>Pg=2>f@XQPjx}BND?Ib6wc}6o{{Wj&hJx-PCN&fP>r_D*t zq@!m()6{9AP*d+}8eS!imF~QMaj`whY<9k>Z)94Dd@QcKo|1|p+h8ES=WZOWRp3og zg@~Vtpyfw(^9`$WVKP^(k;;*i|r_z>>TDK0+V+SgXIK2z-*eJSYr zbUr-i0wX`GyRtHXz_M*@_(^nzBX%nY$-Z5oasH63#5U8OsU9yRI4lGLGZz*l#g`Do z`^E>`5b^l*oX0yS)~Le@$E;E`-gAAZYDX069uk4#kIa#6|{95PE1V8=BbiCB|iz zX{0&fWaW-Psb}6ZrexBFb)|;UPOsq3D+&}65l4MFvDD4zJwC`Yv=qBF2)xr?v`Q#7 zm&<0&TD=ya#aodJ5*0*ij`aG*`;4#IFey$#s>HwG3eqOO1r26A_iE+s?X=gpB z7l1EoRiOGvY-bz1*q6+b)%E4GbQZZ2(T~Qz6`)M+t2g|v0Sq&D02F6*T+lq`)B;Nb3tlEZ6i-)dpEM!JH0yMgh zNu1V?o2wt34=F~d$YebH3>uUq@t4CF*d~ugtcN*X@UgQCp&jXtAN7tmYi~>sl)h2I z5lgcmhbmNRy-F(v7Oig#hCV!`%(Ek{U9qegqC4sf36?1>Ual|&El3$()OnrBSk-hG z1l}o*23?To3eR=W-2Q~|6&dSr-m;JqVTkkZL|=uR$VqH`BrhWHDO$R;LokCcEF{pT zP(zyv)G_kp5Lpq>_BhDo^l!VWR@K@?HZG3L0=E`A%e6&M^yxqL#xC?W>+DSg%3JBF zl!DjxJxt3rIgQfgaYG4Po6%4u^|uofrS#a%Z+vPt79z27kk^hxnETK=AOOIh^2Tu_!BYgn{%ThWKwH=U)D%48X_>G!unm`xZzrw0y5 zudJwonOHVAEPE(obiTFq5*KUvFA0q@>a@Q?eiRKyibD?dj6sDvM{3?+*{Z{Cn5rcq z;pN89_x4rM=|hh;GDF(a&UrXFhb*@fblepm#j#uYGDiQ2#J@Er8%y1r4(?WhEaHJr z2)44@Wsl2v`=Jflu`zL#pT?feRlrR5o>@Y-#SiMD8$zDQe&Kc~dy&4qfvE*e$A!BV z8y!NNQm9Pc@@=(v$8&j?hv1CSKWF$}F+Pc%pp|Q3k%qWKvt4KVzp?h!QBk(tyNHSk z0@6w<-QC?t*U$~p-3L7l2;ZkOUPW1Vt& z>Ff>X(ci$6PvZKuhu;bSy;}WsQW$<^k<)hIN~3%oAuRq=0NevPC@0g=Xg)*X$A7Va zEgLQ>>@N7^dhO)G?Rf7<_~yEf%6q)Qx{cBAg+bgNG5QYM+xto^s?PimpB#^Z#2fd9Kx%QtM42wmZXq|XycJDR-i0A<4 z4@{XzIrgCrXs;@x`_{s#P;_)0ZP$!VG*T_NKQW;SCM9B60N zV{Lbbdr;Wf+?(c=JDR=4BUR|gu)HhKOtJ^b;n_#f*-Vn;e2=dANLgXJC(33nY4wKc ztN!SpV`Jg$QTqdHl-JQwuBE=EmFkhOxP>~^2-=pWqs}w`1%Y8E;IrvjPgjF%}3k;<*OQ>x$$*c0zi`4yBdff%& z+u2;g4d^#>wx<}9SLL`zlu&z{1_KAh@SoYJ)`|g*{R|+ag!eE{*{EgVk-Y0%!Z5=* zD;siK6b7W5?c<`N6q^#r(_o=drj3FW6LV<=<$g_v+uyze1imhd&mCU(50`G$uyg2_ z&Qu((00!w`bcyDhwdagF#|up*lH-6v)vN~Rstqvj@t$P5fnT&%s!#1Evhufpl%rx- z=s_;EXVOBkhs)ik;8*O5LVbdfnEzbWAT;Hd z)({)3M+&Q>Z_0sNmYc zmDDhWN1CvzAxD+sK3%r>`w!(McOMWRw?AOZ7p*JY0fgK;bWcCKgqB`Wv#}11TMK=j z==%1vP~S7_=KWcuhxqRQNGW=ap`%)84kxe?UG8CD7~-=ZvsOqh~Z}ZCvGij&)wa!Kx{Fjk^syyAY9Ofdg{& z^I^3!?nSGU;*gOAr)+zG&D%|PyEmx@mjEDXRumwC9Um@NMc@qpnol)XvXA&3(%;NS zDxu2c#J85VTiph;gU)Ww@>5OVz5^nHE{SYF*q+DsfB`!k04b8>+~q>FS4Fc>cI%Nl0WFRR^2Z-HLON? zV+7I?;pF0)A(2|{)iE`eTrt)@#)0wn**HJ|7H)qqT>s9T;&_R&OBHs3{+f+mV|eC^5T=Lp}WyI@w$z8^iN zlRW_#!~st4c8XT{HGC4l>2maPaMjd$mh{#IY_D!&5#wF~m$?tqVLSv|f?j%4iHYw6 z2SuyqqBIOG<6Mpec%h4nO)NJqK^Q-&qS>T0ew)PjV=?=|L7^yd4c1u znrdl#WM^k8J&yGB^Xb<k^ zXKpAwETAHsl=!AEqVgFHBq`&qOpP3eLX9Gaa-=AlIFYEmhE&CK9hhdHWLSe0RKwRW z%tiD-nm15B(3|@!YExO7Z#mHGpU6174hERxCplEluB~?Fd7*qnFl3_^zleF>Y>}pR z7d!#5N;hX=Xs1Nhr2QBtKYP@YxBwk0e%+Zxe%mXT!%ioG7`bT=_`B&MjiZ7Go&Q9x zzY}JkgLe$+X@>hR1l)fYdiN_q60UYIk;LnT8#A?0)s^TG?p56|Yzn@2pm2IXSL?K2M zs3w1E!s-Nx)RZsio!PL!9kES5YzhV|RJVX_o%`!LM>AQNTj=w;ez$es12U;$nA^^z zKP%7r+HV0M1+mI|lOu@wy72=Wr_ESnbgWA2Wg+_D#+gi0iWQN|&H@%}z&V`}HjpXM zqzqBpOz$n#y2nmSq#r$tw8Z4GU4$t187j0^C5iaE7+qqUm6sAIBQ9=#w>T43@QI@h z4zvk{xv=zqs(vbMBwglXTMaMFo1zcHuK%O5`KTu`{17*GqK#UaA>yBy=7{$%v8N<33jxr9 zl}UzoW6SL=>ExXX3NO!gGcr&JDa)QSsTNNjn2h_HZ?(A7G1WbKR8utigQvfVs($|b z_U#+(G_7N`e;(K3K>)-y^>Lqc^1#T^5iM{~x>p*UJp+8>y-%ot}VN367A2GE5JpTi7`Jc0` z|If^n|Ns627CRCxazI1SZCcjkhX+Std1VH~H~Jt^&K-H`IF*Led!~)?#pjs4KXSx4 z4DWh_o1?ujm`l37%>R;XWR}W3)G$(H;%VUttbD`tuHd@X*axM)EBW(gW2Y;^?0IXQ zHhIP=*V-BGO+!(Zpz(j+!g1RpLn1x*#cFo)iNQjXWyB&8sOJ@`6j=bnzVNp_&1RpE zXsDBY!y#FrS2Cd+|uZ`wl87%-AVX|J8bnAEFJ ziybJeHCE4HWcvPo*=FZBw>Rd$FY;a#xT?sD?VOz)e5TS_)Q`AK%kRiPsrNEa4rTsGftCy(&WrXEGg>f zz&_6F>~p_H@jNR_Y0T{h9cQ8+nZ6#MUx4n4=o2sQ3qj#*Y@X|{=5t*FCBeu#Y$v;% zZ#;ICNg{p=MBM4Y(W$NG!f8NS`$>)lI)9NOTxFUt+7cKTZb{PXwrr^BtrLTFi5|xr z-CxQmS^oRkNJuP?r}SLKJRdl__>rt$Q*!UJ*~t{d$h5v2W5PgNw&tJj1A6y-H6m)B z`oadsL?hG%A#@|Yr*$w;%~}{;`fNPZhn$_fD{IhxJb?OHFj5Y#m6W0KhjrjDP193b zhw8G}fj`=(%WVsZPDj#wJ(>S`IV$5|U{EX^TfVzyszFF~^V8s_pMIGtU?P5s0ev+; zSADOKThmW6OUBiEpkWg_>S*oAx;O;IttHlrGFlvaEV@_d0s5<+x0K)=) z`W5_OpTuL!(ANd8Ukx0vH_$sFB{e}hM0^|HsUv|0KE6Q5#!ZFRMG59n5}BBfvtXx{7WCyvd2nG+zmjc>xM^zcs-eMo&(^+l`j zNlj5=U|I>XB_2{lcwvPHqgV6`^?zFzUdoTeiv23fcV^SsyD@+-`88^^W!RshYt1+!Syv# z1mg$l4AOs(N>pSL&^>#XJGylmrBEbsvG#hY)Im^x5F;fTH+v}g78FazKb`i%?oI4N;&SbQ{L#(%(e2k^NZ`o8E|hX>FWip@ z^Q4j?wV+4ZAlI9Qo10^vB#bxUk@)PAj+!UpM*q|N{pVk=&fO1Hcs`4hKBa>iW zcNOn5YzDqlDG~ZLv!amYe8m+BdafPHQCR(VlPhKi{V;mw=Iq=dRXz`vTWSez!<$WfESACAs(>7nG6`AEhf?*S>xGZX;%BC@G z#+5k%wD#L1a`}x=oZSZ3@?r%=tlE7_Vt!RBHkIek2k>uy%SZWow`*{^dvgP)a}C zas~{NS-egtn;peLmC7DX680}b4H$|Ly@toRO@j>U2!kD-_C#{a7h@sdvWd3=21*`RT|MRx1|-T zRcF|pU`B#mLgBGT-Do@~B}INT(5ixulYH6jgIM6bqy|S9Su@(DD&wW#89#tfh z;^FKj#jws3-~WOG`Yh&jqaBYsvxs#E6AEmJ0I9~R$n-|kexhXsYWLuP%Cd3yL&oZF z{Qj88&JQ@B&V(&hSBAReollWG>1ubKKhq0D8ui^kZrBT{w_YE;x0;SIs;M|#Lf6nN z__WksQW(^fFgyZ!u!kv){qi5_BV&b#|21T=+_VDt(eWMBUVRY^{jc1dsO%#G0HLS+ z2$p?&t+7Z&q>SqGdeh-)E_=gz!w&hiF987sy=(PZ?c1U@i|b<&)MxI#11ZC64%X!G z0~&;@5Okqg(%g!1TR{Buh%`&Z-&C~C41EwPXDnP|8&F*rnY!sPn0sxj5sINem*ut0 zl@%g?=qiU-!_nkhLQA@!$)c+`x{#uv;EnQiAf=QRRXUJzpGVDm^XF~$auR{k%NNla zGZK^K`qp;j_XyAHd!~}#0)l4e{;3*OaV4{~=X&XSkEF1V5ABD?X}f`ZGIXp_-N)Br zX~mc(%MD?}yubAo=k377{5^P@j|*lb18aYlSM z-N-I`iJN}EGE+ihwV?Y~R~>$0cilOM_zGJ5)r}J_)m|CTa;=k;C@M=f`bV;$n75es zrxe#F#mOj8`lj|**EG^c4{(J2&?eUj)OS7yV59~?35u1maKRuI=N;VThU^?M^|_Mg z%}|12-JAi16sGjjisT>3x$%S72l&YmVRCUORt<c+|ig6s-*7axZstDFLz!l+Kv`K;Qh z8`NJ-(wQZJOQ1|wUoobXzFZK=&wp!yeRNGjVbtP$<$s?T-@gr8EIwXd zN*bCPm%g6pqg}9Egw|3^N5UW+9kP0M?V(ii?M>^`w{K4jY*pSC4h(>Jt_!!6=&1T< zzoe#d4EujPb#Y!hxoW8e4+p_Yx|!w03sUh|Ftjr|GSrN zC~Io`$$ss7yT~~wC#OXZ*imhxrzJb^sl=LGlD*EHC`Z@Y396qgBioyoU&_9WV&*Dk5Cx8?IQlhzkn8KvL&)M$v-<%f@mPgEg^BSkQ zKWCpewzRwndHL$g-$NDM-9yCUQuF2X2JkNw)jn?Z5c|Ejet3&-b=z`_z)wat>>T@- zqwVu|!&ySE78ahav)&g&Lt_@^^&T-;;|cY5O(k01>sNGqsj_&G(2!9jliU%saK1egEzFT69JHqu$TxPOt1~a9{KLV)L<*{A zt?XdIekoSx>6FUre*bm3U3ea}50Yb2k3BMKKCLi}1|{QBQ61{I3}^ZY8?{4JfDuL-P87we~caqEW;nNsZ4M*14z`n38oQfdL$=7W+T*Jz5bIHx2dNJT6c2ni%m*-ngUH;(lOZ?aXz)RyhfDR zVba~y3P!b-^JI$#Bny^9eIk+%(`VPn4*n>ncBaX!X3mNlbmd>gKNMQI=qm&(z$B>r z8!`)hrD#_dst;v+w%1q1-W|q7w{IH-#ndN%MeP3C2jSq<R?GAg@muzo`q1P$+rizO z@3f@ZmiA_j=JqoS+McW1Sy_ilsJ}AwgNbcUYYkaylKQa7-EDsZPvGo>Z8CCg6)TdZI=3q^lH#uXV059(nM1+eG zHSg4P=+5DX#i>A%AZzUkTdz)#4a0Br)tl$l2dq*@7d9r}jXqpj&MeaCn+Jk*jr1)J zwo3_U@z`5;5CzBG*feFpS|B4N?Ia>S`OR zjg2qK4aUntYTr998>7l#>@WQ$c)9BC4N+m7zJ$PVR(1-250Jd9%|e7o^MTi>S)(ns zHm3lG0(%N_5Bqju5U9&v?&_e4%JhvL`m+kB(Z)Yz=_q-^Muk^CZZT+)C<(P`1$7q2 z&%GD?F{UXr>7HcYy+pFB5dJ`{Vyva5u4<@nY;A9QRq!^~?|W`ln`LE9ooB&uq&TfB znyrtvksc&4f;&U})1k2?8pAxlePVGT*i$FFPxV_b!OMgF%%-rmd$4&=2>L~By?YLC zy!OhOEe`O%ytI7qlmUc9(OG|6G~REZKWS#-vxM(W%EA6-v%J;iHC1k&pjfrUJai zU(_(HP^2wZ!5d|DiG%RGmJN2g8#EQkAFO6r2TEhXs4f!-A#xU8%7NL*vU)iI);Be88dD^UG4HLD`g@SDvn(?BQ^ zt)@7|xEWqjM!7r;)q3#lJ?Uxz$vuaJF*___C^;b1iPfIVSn}+q!SvF1HV?>FKaS#W zIghG=#vyttzItan*mY^-e5A1(=Ghs%=FCux>N9(5hrcldBf|wR)wsUi=peNF?LpnQrmEniXgSC1>xp1Wh)byLpbc2IwSKZ)|1chXXO&f=L@t zmOZ~2aI0+?6DlvPEu8YGp+i8%(cbQegZc@i0a9; zdP?ucwJ}JO2-wHngTqopTCeULkn73<>D7JTJCT;hwxk5=PJC$6mqUY$v9d5gmc3hA z0Er03#+{-QbzD@w=N-7Z5MmKgs)FW1pJ<0X9iY2RTZD%i+NzWwgK0lX83I34XWu4z zD^14A;VM7C060fX7dRVJX;alj#&h?2C^_>!I~_b&U6bM9FgI#`M&yfTSxsINKu@Bk z;jM}tEAud-^g}RA7?Y~dWkNm1rH>dBPC8yNE`rd&lahmo)21nnv)<8FJ<*I8STWP@ zBz7=F(0ATxRNpVXM|?_7!GFtanx@ul`Z>A+&cv9w#h;y9pDmus{gbQA-}!7{t{L8P%V zX9ZMb6J(RpEtMu~)Ii&_(S>-nHAp~ZM#WQ$hDYoJGC|+7uaYRwVj*suZs-QLVzSA* zL)Pf?^LmVoqZp^`T+kS1&R-Y7#Z6R1Z@GG;=oi3^-BVp*rioGv4$v8}my#M_N^0>(m6SpgIFxN=9#RC;WojKt0)xmt8HkS1E(fccl)<%9MIvIdJMPpKqZ( zQ(Y@;ZuH%&lw%v4xLH&yQ1n1NsLIh|GiX?jQm1CdfpX+Y=Tgzkx3hD9YdzrhjdaK| zCSRd^@j*P(nV*H)=j4n{4pp}bC8QTP)s&WoY~}`%G>Rt3t5QjC<;&ONfr0`e)c{d? zB*K6ST8z9R`G@bhTRLbJSm9K{_h29w4I!J5A7qCb^h%BnEkxjtA2lIg3%0GycD2!3 zKw{bM1U~8*YM9F^NvpL_jm#^x(+?_*N7oOE&;;e?{4=oHSUl>}&wroVALR12?t!DT)@VUQjOJt7%* z0Ouvlw`J~Gj}|snC3|ED{(9>3JQQ#XwJZY%pPIc9T+=g?Gd8gYxviS8HSEY}c=_Bc zA8KfBM%kxm>CEf|>Ff8ydK!k30;IL-Gtfn+=(N`$DaqhFY}ZBi z@T5!N#=pL$G*e(&yZx*Fp|mXOOgr0wEH--E#9MvE&e_TRA${uR0)Ajj^7SS^4WNs} zhxh*c%(uQ047qv!RVpUi)a$DJgD0j4jg~UvRbhEuzX+|kh-t;q#Ea#Lw(aG-AZf8I zf{hS`8Gtu8KQAel3QeBqPFr5cS4J!D=#Tyx`5GgqI;iM$Xh+4(T7H`DU2h9WwvI$kGNX z!Wu<5P7~sg)ppRFK;z+2J1$bUK<})qqdTveOn^Q?$kbeto39n%^W*@&L6k#6Av>?+ z_(sYXjyl$W+!bhYlTMWw@ZN4L(+~S`}dGTQ|FTO#oJ#z=)ZIdHm#PdHUN5 z;K{ZzwHaAN;ZIi2*=yXkL@5ys2d}7Osh*HmeZeMkMUy{tAtxSiE0V}t25svAa;&Lm zTKr93gd?<5nQe-my!4gJq0^dLjg8)XyiLHY0ow{2d@W+7hDi}UasOGElzPS10fDKh zO|OBGl&?AV@_XH)$d=f9FSXRNFdxA+4w@ZTCpUMG^V~9fJGWpEjN)LYpe>HyM9-Io z9*&7I!y*M%QQ;X8@cj5U-x|%j$wdd#lPx-^H}k}ug}P1|(1sO5oVLl6`N`kJU%2gH zqLOA@P{vy>>Fbi;IY~VrRQ~GyNSEe8#1+>;RI`mIDvdzV0hgy}sM);chC0r|p2W?D z<~piC31KD42;Hc-o+~!XTci6vk*PFJ7cg*J@Ku*tZ>V3v!{a<(OO~9Co1-BjlQZ3d zRw&7KR#(+Tb9+`BqGobcwUct;<*|6>X%lgOLV|-Y5$zhXzkN_JaVA1xtXTzc$7N$|%Q7WYDT z_m))_>BL5_fo^>W=R#=u=y+gyK>=(u-tCJ4>~ZQ|8aIme*>?0rP&!kY{XU6M>(leC z*^&y{6=^jf-UGLb5f&Yu%4$H1O}5maQ?AK1so{E)QKw;EYYA}->pJMzWl{g=%jjPz zA>QJL=)kDGEEGu<^1ms(n)u`76kYY|pnI2WptjsPTamvx{bIpttG@b|*XC_$4Kxt_aO{Z6|(cz?bGBH{I}b?sU@j5g#4r~e0`{3VG8+`9^6 z8;2^VYbKjI{7;~;#uiMG@(H^Ea}QwNNG)`3#6X|A4t6_LG-T)`V=Q;G}kQ( z6o3fciPfa2FlGT$Y6UdZ@cas{ooz#hZPU&E?#3^CwJJVEt(#@cJ*5?l zU_aNxc%pjyt5i}oM`FGJb}1#$%JzMEv$=-a%KE!V>$HH$aib&%D@!Jfho@l`CB#)} z!?IT)Lu{jVswuU<6&wE!p_N2%jq+v4$cI8BuUB#8HRZnJPKdp=QSDa`j1jw+v^kTO ziBm}sh?KWD_-DcH{zl=TJgSw%wv<^jhwhM$8wvF8N^-ua9l4V9PETTv+~3%xCVqz^ zE+vzmjr$!>fLxTrI(4Y&f_dJn(0aN)%rDW=kX`^CA(?BCq88Y~^};hRq@`!#erv(| z2JwSrsfEvCbqEN0E2L^`2&~H&9(S_sQ^N*+LeOX$NTCmjoJcptH;O|+wO`LB1y9L5^(gl{N?w> zSY7R6z}@<6=#`w@C7^@(d!ut|st(v=Yjkxc-~d;SqlRW&R5n8S#!1m2jtkbCt#{(L zA)VVd{94%_TA~k|CjDU7V73PaP!E)q9W=hIETa@LL6Apa z?Z|sq%F}pyx{tL+M+}hHKIW4uA;=@9MKPK^K2=;x-l3K-Pl@G6FNW|Js)a2tVB8l>6lijO2YH=yM-`fDykAJj%MKu z2Qn(KB27Aq+*NgD;{BK{^kLXAqk!EVEJ_KDm)c#>BG+JM91EFIuM&tn=~lB%Pf zs;9lr-} znXVQ41zZgL7S?!RgX?WpfN~NZkw|Gdq^iE83|v3ZCBSMtq0*#{0QMsQkqRKVq#31OZ{2Ug=L z_W%H5hGXG-^L$U!x*>q)H&j4{GJYFVqM+Mpw+v8>v{{a+Q}F!pLxpzVz0Mrzv#Qy* zu#T8xNa+-PlYS2pGloBp=s)uvTcNJFokizb*A|is2tFzxQp)Q}%9U$vtGaTBoMzxOvoK2KW(seqrZ1AizD`J= z9FxnYuJ-a>&In(Mrk3T6_h>Fe`PDVDnDOy!ZN9{RyVyu!q)%_9Ch6T*I}S2Q>*cW`^(rqm~Q&4RKmrryB6X2`$s*ee;y&?|N92v zzvFDLB`K46o4l&!nXD8V3meE`X z7o)`;*7>>6JCb$R3NVE)3bo=CjKsubc1sH!wi3Ji7Yp!xQP_l5iH*u~(LF65XSFhs zbb&GQHI%{e7l)r6C(+3la<qRvh*TP&e`|v-L_RNo68Xz*P z^p6hfpC4EPN))fZDtt%@ykAM5O4|4ux+MGrBZk?o+t$$*>?z10WUlQxC(!6~gHrW> zeoV#VOLLMs{vQZu3<>PR!A{J#G|D$G0calBhM*seWLJx!#dRs+W45SHFU;13Ffxto z&5uMiF%a(BF0|g-(95HpP81Gl|1!UeRq)0AX?$Ouerb1S&^0@BJ(DpodW;#dy>mFw z&#P*nGf|4gU_0NJ?f*Co$s%yqklj9R#R*H^VoYPTZq{aWuq(PbNmtg@OA93*zl#+F z_`628&gOOX0`5)*cj@hiaNiQwufp`COr5Qr!6r34%O}Qqwl$?KDIs|rJ!%jBYka8+ z&HHKT5?y`cyQ-3PyDiGT%`L?i3i_S<*YZ@@6gC$rWcOO?2Jb}7E&MuPoa&`?pIMoO)aN%D?krOVT>KrZ(RA^KC?J=;Pwn`uMie!Fal9k$y zSSX)BhIuA{zM_4@&~X{bN8{n@d_MS>9lf*bW%J=?i}l8i)KataaR0hw0nwWGUHPS# z4?^wcz`h)g@02d;7#*4ZLecMGN~UfqiIWW=>tD-V+h)qq66Ow&)3WS);n|5%~ zl4X56dliq5G5(%hX>3T*Bw(<4jHK@oyv2WuEz4r;Z?EC9N?Kyg+oDfRL?je`&st1< zw*w(wR^GF_>Z8S$-*%iE=w0d=wmpied-M!{gN-FW0QK6oY5GHF#7$WcO88lw92pVz%G!x4Sg$C%2HUS{Qi@D>5-D0(@uDnXP#yHOZRO zs%vX>4T!ZANA>ua(<@lQYIHPl;QpVWa-s)d>%yRZmAXVaXgt?^Ml(6({sKCK+r8j2 z(*?4!u~7m~!KOrJVSI_W1l*HTN?F`t=zTxAgH-Tk&#iSt0w3D34OV6M$T+FXW*A)K zXfHvwlT|o{PMAB-i_431!%Hh$hx>Sp2fr@!l--45|NhYkbxcTY3N39Z3`=1Vs`Ee7 ztFYVxitm@1%Qs&GJmG(^g?)--=c& z>h1`)4OrQ@&X3`9jfXQCWpHbbE%~TgG7H!nWtL?#naiWOs{R>~A8MOHX~V-xh2O_J zCn5^0gN6C#Qfbad0i-WE1sA|SNf%m!xD#Al$sXRIUIFoHWA%`P)O(}}BU*8YR$76t zK5#k4J+am2CJdgoIJG!G)s;eipP$!aAmq2;4%E+NX41Q=B?>heyv^y4Adx;TP@)08 z`z~L|fGFTWH_ybhsghqELaxgm_=? zg*}tNffvx8gG$raKV@PAbdD`$^t3En!cy8(o2V3tgaOO`892(F_Jhx|D)8@*(}~>h z1WOgdiNz`FqrV^>RYGEHF>4BQe%pY%k)`puQIVqJs;sPB9oiJ|FYBp>Y)y?sRZ`EX zx`wy)j46Zd*SA6ka=YZ|-<;Rx=XE_D43wdXk=HN2TA@+&LGM^Z0>Iw~=^Aop|ee8dl!KN9QFL%bk&B-fWio!p9t8fd4$OH7%FQqqbpO932htg%|q^ z8L7z%;Y2+qn$z`(!Q}>bLPB_Nh;_B}nBuI=T9P*lPH?beNahN&Pg+<+^0`(DnixjM zY=0yqP0!6aZ~4cn{rJceF~wbW6N(zCydiRS+G2t=9)`I;K@)QB&Na_d3FVnp(SpJz zJ~cWV9F)7M7lX=~h7qdCaO4TR9-FVl!nDDQS6^4JBKHvoR|h35X85E0q382c7xwKlZZ;Es`<-rC zsP$7KqFwkX{W`nP-A-F;c`7LY*llKA4-Uu);1d%nj%T&8r({p~``d4f43{>Ecg-;j zMsD}MRi?zhbo12Jov&6~L}Xu^O|n$YEE573=J!tk*?qh)SIA! zam~3^`F+!(sU-|?t|3#^b%gSN~I2H?t{`7h= zQZmLfR8}yiynUx$eSPIxslG5htD=lmSV0$58Tdvk$QoL;^nyz(5syfilY^(SvT~(> zfnlJr%No#)q5H139aF@_0;P7=oaT0`BoitG(Qi*PIPzD59g#i1vw#z$GmnyXQfeYw zN^kfG@{{{N;ig|SXSi9)2rSZ&&WQwcezGKJ_*uoqo?2VGo>-j9=Z{V6xG|kpDw-11yP9t043@^}h{n%=rlhCo|+X zbeWAgXTGCRj*5<$Z*mU_RQYpALiD28+QMNf;DV*J=W0RTy`hd9=!OvU1h{|}CSkj$ ziEB3-TMms?;W_}K!C)(J2p0ZMGC)T0ctB(SFe|*hTM)Vh+PVOMuk8ILP~}VE=;stQ z0K)Pc$Vlhr<6wJp2zM0+e>3HZV-9?m+g7-gx1m-G-zYqKi{Go9CAKnR%W|8}o~d(| zOsSALymm4;SR0;Ho+)7_VNfZ*9bdsQPE**@GT*!DR=@gpdnofdW|bp64lA2QrBowE zsiHYPCSb5jm=6DF+fXamZs&1KJE|^$W81$T!%T1 z)g%-Q2?aZTanYq;szd+gG_o|V^e<;A}N8BzHQL!Sg*q!i5-1H&N+IG2PYr2O15hYgOmp|J4m`p@WJ9*Iwom{EYb zU`!;gqb)ltEI3O!4%^BI^I?!#=dMjH0sPPCV6HD}R8i;`Ygb$sZwY@UqPE;%eHKR%)WJsAd31lA z`vB|WJ__=_bUkfSf$Hp?)jzu>5y#GKhQjyovEi=Bf)|b^r?pLRm*F2Z-_?Fu_+Z+U z(7C1an~~y;WVJ_G$7W5pm2`Z-icw+~T3lR^sFGy&s;T4B0OoFru(|^EC)8qMBV+PB zQ(J5XdWhByUcQP1=3k;Bv#H;_bg5Pfi<;(soLzx$s%gtQm$bPUIuuk@y%Or#$XD=0 z{V0cRwu(I)@iJdc_9VA8uQbH$A%(l3p?72{HQ4uYr_2e=n)~K2F??!ak!P}3EFGm} zYWFZ^di575$>CWWJ#|m5y#aZ|>zA~m6osckwEpsj z$FV6wEs{60If-XYO)WNXi2FAR5168^oEwaDShxP&i<67{)2rL?DHeNr8I1KvD$xk+tZVtA_i~^3TCXDbaq%T26%mUgwac^QAp*@TW4&8{ zLuQ@1Tg*)+^Ix+8R60FX&m~Yt z5xowW0DC)aXIE6Cpl`Gj z0r?ByGBzR!%FD~6uo42Q?e+Eb7@o{LN5*rew=bqQJ@MAO%b~b?| z_h9Y;7EbA6mBe+(=~eL9c5y9+2IN{ij+d7m+|1ctRj)5H^P{LZ@q2Ri0I&lRWVS|k zSw_e5)`}UGT#wKOWCIC_)H2z0b^r^KR+h1bJo(*JR#sM0Qu38+F!bC}fk#uf_&est zU(Lh5cvp(@C*v$nfDNS^#pG|UDgVU+Hps&z$%*tH@xQD?2Y)am$-UvC1mo1zCZcC^ zGudAmGQ*dVBUv$OIyq3>FE;A zB3bX$@>Yu0pI<|v!I{ck>s`=bp|dW;Fm^iOiaxA ztf0U#L|1I9=!c`;y7nKbdauo&C+oXQSV>Y+^*q)1i{Y|Wu)`91&jl(4J)O$8L=TMG z=W5ZmlPre+U4G&vc>m_Xp+eQ8xmYPJ4*IO6xr?ii}dhmw0@!C;GN#(UDp?<#_`3(h`dA2=ph?#xSJy zTr*A9n4;^dvy>bv^GaK%COgxpt;A|C)pX)zTF6{9vFo_4=T+%97BlS^ z#yW#GbH`LZq?An32dNBcwGVUw$EmR3YE4aD#NahL z>$TbrY)B}_HS-HJYs)O-6Yko~Lb&0IZ(q^!=FPuh;NiLm=x~1u@@@Z``03pL`PV~4 z`q2s6Yi1Uv=2|+SH*WBEq+&KwpIP7tbyk3%MYnlkurF|?9z6ua@mhf{Zt``xMSG}A z6Z}^@ZcIiZFusSxECYbCBkb(sq>(e@J|2Hw9e~vD%}pKVKw5OzMCp34MErcZ*Gi&> zIvHl4>|k@_YDUFEO>LfIym7PJpy^i>IO>?~tWC8oO>MA0lM6!&&6E$6kT6Y;kwk3# ztpYW-j~~p!{LNe?M10jJ4l(43d{I%E?Dj*&u{Qk673-4gF%;|Y0Nxhgc*%npu=xB-Rd}}d7ExteaSTxGm)`<$|Y`3nEt~yWc(Ls zu|9o*G2p{ENa=}~zlLljTYMd!RMx#oVn75{@1|yb=(|3Y)Y6*Po{_nP3;SjPU27e~ zAhSW#iK!G?82~C%jS3$0Z)u<+g$>^O$o64OO=(^-5u5%j)htd+CrnT#ez#p@54@|- zgBZc$pKBsjeYMLvNS{oTJfX2{r3(o_t zf&mGWMRGkZT73iOSdH8ol%t+|dMw%+a}Q_yS8u^)S^Ej9JrjE3$@mvY-P5`pG}Jv{ z!X`q`XNH;S`5-5pA8TBKWQknZm88hU7u zW`?ezo`w6m?&Esz_x$lcA*Li-wpOXSiBG(w@II=CHw09tj zJE|_XCw_;CCOQH5xEz$xlM8UPLO_aHO6m7$B89hL@{o)#a zkbHxYI8lVuh;w%SwX%>%ynQoR@c?`SXC&a2`%LbNKCEQW%8UuPlqcn#6K@u@R*!>Bqq5LLSb%hw?~qrlZ6IgH=i#H{OiwWic9O8d1ChaZ zd;Pay&{_;f!9lX?&kKvoAN!5Wu*iF~$uH zjYHmzFs+cxQH)cAtE*09!OYDR8o*BF1`!y=dYid9v4#@fs;Xj_y-UNwnw52NU%bZo zFZr}kAG3weVFZXJa&p_D9Z$k%rKQXk>x5!-$QEV&>*CP7s6hsXTil|9 zHces~Nw`HheC=Rg$w9aZeeCJi;-6q!)LcR_qQEAzL)-fiYRG$RSTA{(N@vHAWufkk+3Bmm?lZ zTf`s~Es7iEEdO#!R>4rUj9q9zrs{_j7se01r*WmN%d?89ixT2os-dW$6BEfZo1ZdU4Cl+?!Mf-uW2 zeO`TmrGU&VDC()sOjT8|lg?L(GR4X#50}^ggMm~AEnWX$pJW;i318PnwF%%X&1og~ zbO9ymm~5KPXVuRVnX)vwMFo`(!t=K!$ zQ`2F26@RYta?W}K*m0XTx>oi-yo&J4!pd@xH#r3gg}mNi>>c=LbGTV*)Tgz!P z(Nmch2|fg7zN3MCii?w%jB~wwr|p<4`zGC%4)2jKaEajEmFJ};fP52qoijW?!U1%w zN_^!`k$C~(s(Np@M{l!IXlR$of2vQKw6Gu8Rh(RSgn$)Y+FF0K2CYrV1?>VMuDyNK z#WX@?Icd;F=r`66Trxs*vp^d&hWn5guHGwoK-&bYLQzOLo;fGSa>Q(X?aTGwFN6C& z@o6h4!RN+xRe#CSl(PL1>W-2o&E~XEkLNX3=Kgvayxff|?s#jj0XJO0;;=p#ZNOcE z3bd;h$kX9t6n@B2w7rMMm~Xy80P3FfyPL@Li{|g$-isw7OYv5i{1X%Ks8l=K*|Q!w z8wInxJ|G@mhwsEH!bfFvWw^LT=H_Uh8jC+kh)V#Pxl|^8E~P*9J?|#mKLxMP!0eKJ zzy`+sm=aK?z=0z&44IQlQ(0V^ENH}|k`fsal^Acnz6gZh;M>!)UDmEpXN(}S8A_4H z4+v=$S8>v@Oh_>Ja{+tUEory;i)PcjJ|I3H=x6NE%RrA@_y5pt+jjK@M)vicL?DIA zKueFu+GTVU1?R-1y+frLJ28~hb82&yn5{(53Uyi9z}n^&f=vp}|^ z)hLlyTz@|L86TLJ;9ZJ$j&Roql*vMA=^sZ4v6toa0kHjjh0Y>=7=kEKItCt*ceC_P+#XRb$DXv}~G=EnX*Y3wYe^z{z<1uu?j) zK}x0n@CaSLdli@>{wb_p6Z}8UPONC&5d*!wVAU{HExUBMA^|tzzB664yw0nq#$F2S z44YNN20l1}5t>W}ZASX*8{6awF}A7{v7qiK*70fjtgEWF(*^bR8HgnRGsXwgpS?nT zJTFt_1Gg*(S-6&}qy$_&p`U?)kf}*DM-juX^(ZRCh#=@s6pFTJ<#+2QLA(Blhl!ji z8JwC@WMJ7cwn8L|02cumh=qH9`s!UCy1LeGbl(0aw8d1Pynj%6e}4UQ7yS9@e+J0; z&s%|i0bt_4e*WJFIeGtY63GAfJ3OVh=gs!P%Bv5Y4#JiLXP*DLx@Ln%!W7MFQw_HV zaPaV^CwL<8&)Rz{q#_6P8nKO_0i&qV(*D*u1%fVy~~I>1i`wv&+0W72X)9scNG zXA5yBocPyqQkWt{9m7xL<_>_A?0J@T)EG`}Z_~rM|h+0BILqYS`>HqdJ=)e+3)J&5l zO9Ozk(UO$lnJ&i6wFL!;Rum18_`Ln0B?Vp;4ebW-tKTNr=*XDp5NCJa@s8+hZ_muj zgV05nVt%{ELKDjm-dO<8TO{}W`BaPt?x&nLJ~1&t9O@51$^!Sm;wj7gW{ic6&CKlX z0>$CKa{*>`-3`XK?_;Y82d@IA3hkeXZ2jOZ7Z+i0$E%1(u^11$y@DjO((M8A$I0Hl z81fK&S(hu<>Hqu>hX0B3QThKKy#Hf3Z19QydHmo04$oM<>CwWw06!h~_FI+sb8C5h z137#kbEv7$$nep6wXuNq`OP~p+!^CKBTaWgzWlSM<~}DO(a_L1Jv#a|Zo0J!f_*TY z)We^c5!lUZPmuj z|GCqp{(0KjHP+|fxI}>S?JXCCvQbb_I9fq_dl&GV;aK4QVQ=xrzI{>Ef1cfajkQ?n z9UR~Mt7B!q`n56T;okoF{Py*X9dyA3uZnb|iP3(2_fF{ezfapg zm!W(+y)~IY#`)hj&Ht3e_@DO!tCsgyqUVVR&ir6T-@}E3+`mgfA_#O+f;!EAp7Qxk z&3EQgw2U~hw$4tegFOtu88)q`ttmmCEos@-jEzhSfZchmVj)javJe{XWo&KyJLXsj z4(F3eDd{eb017fEhf3zU6H6pT#VCk;fYu)$)|OKitE3Wz_Zw<61QR^@FRO1Qi!RGo zij^Y-h~^l#J%@#oSnUEslUGpVI$Mxmv}Po3md`-oODXCCjKqND9S$OBAUkWo0Ogph z?7B$aJP*E!ib{4{KVan=!G&6BUyw>;kA**zNd?6Z7BR6-_PLSy73LFl$Vkm7;RA}2g60Hkiap6o{TWtw+;=*u{%cn+H0EQx8GSSL3Q2O=!ab-m@2iY4VN4vD#oR93@7h`kU&>?u^LA zJU9{PXHa*@B+J}MuM`aLLOsvxUO^@#ZsB5^uLrRoEj<5EXRE6#8ClUwu7qtWd#64Kq7CeZ;%%{1M}7!Relk*RNb*z_2@9er-gC=It3DAHU$fO^PH-$@5Z+ zPKmj-*cM7~9}z9SXuOj~3r;;_N+#@ECzXcq_aLM#DRKBYH<%lw2fUqy3GLlez3{^P zv!gwM-lryB8eXGSP}y#LTQxJg_u9%B2t({uZoUdhASYiNj~#8af!Mv5R*Lr|JqrGr zU{N3qH1%pGT_)6ES|16sJfAH2rATK{Wn*c?@wewi32?{tNn!+HlqyR4m1onRPYKpY zZEfN@&rbl2@6b^R@m4j^g)v1+it6>a7)A9NloNwe;R7COAf`=Dnj2C{-Ig#wnSc?` zn3_nws6y~I&sFYBozCTsU*B2Zjc`5R3AQ3+R3pIS?;Pm~1P4dWoZDIx1E^iq78Mo1 zVuzo+MMS92OmT6H#o(_?rBX9FckQko(ia5`cycrfAxb%q7Mz{Nqeblub;wUNnalNw-%TPktp1;%eGDEy!krCy`CwzKuoB`KiFYr4khUI-+vO}g6vMw;lk z1kLD_0c1-m=vpTg6iCrG=-r&p>#ALV4Yxcs-zpc#Qus0m3W%arl<;VyG181{LzDIG z^tBdTXzMcFfIAP2!dr$k{gp9O4ld~?_hD=@R5t2F-@Wl24c?ZFa(7xl)SD-bc;KXH zdC4)_8TP4Mw(t@tVP|)le2zkao}Ntm&a0BCQNHgJ#g(-ox0gI(oGHJ#rK3D@BqQW` z(K)lLpvi4Ecv<0m#y+- zzRH0lj#yX^K4jhN96`sXP?nz`f{sfq=ZCcoj98O%p6d-j#FLY=uY0%8tw|^ipCWe<*w^Y4=$8%@HYr#{CDRxxhkdUbn>7Qugv7u`y z1`i$*=s1R93m$CzrX4j&rX9URCNiHQraQnCWugV&sF6dtS-|eckPrhHnFocRy%K&0 zsKgcp!9=ikoBdJ5^k#LyN3^v)tWqUy)`*z-Y^UI%q7q>Bj;7+Xb9}^3NanYs$XRx$ zR?n;3YAo$Qktnd6^f(H!oUOQUwAr!UJ$~(Y%$NoCxPgND@_5RU0p^sc~LsB<(O@ zLLidh*1pN`5^xuKU;!j>z2(nINl7U?L@O%B)#9J8yvi_ORkQr0Y+*6rfi1}D)v^qX z^*i|?-pz~AlXIYzc*)x7IMAuEuYevw#9Q0J!7?NA42+B>v@815c)!;lgrnDNZJFhC z(bMr7nCY7t8Qtt)-keXqKb>=0w+e2OLLQBcOM0c=% zoXBrL%xJlix~;cDC3v=%ag>NvP+1osZZEadSJZfZ$tE-Fa_UiTjKMStsy+Uq{MWxh z)qOn56VO(?ArEg4H^8!ncV2UAS>wHm?wf_dr`pR``v*@|A+BdC^rjTBr~XTW~Jl{9(Ip89O^D0gj@L`ulAFO&NfHX2hrSV#XD z-xhjH6*NgPj*~R`t9>H)_~0~H>^u7m1s3!Uv0u}(e}y|79?{beX8a|yY6J^sf*+hz z9u|r<38l+sTNqg6c^T`PyhlLXT#3LU`Qg>bH&KXQr`baW@>#$MgslR-o!8|_UzLuT z_@2kr)sS!th2H)q8>6C<(!9$y*6b0R%(dH0;k{#r3U*=a1=rK}DAC^&Br26vRduyB zUdM=B{7Fr5VG0$Ou1ZGo`qRoKTk`7Du-x9DhvY6%-}oibXvZ>AtPf8b3Jc-5x$+EC z6BD&3;p1a#>6CrDUV9O~JqkI*T)P?J{MNa}FZIlSC+^k@*-dC-U|7|kbCQLh_Ckh| zxl<$%?uS=HmX>fw0w!%Sxi#rY9pJ-jZGAm|y(=E|x$)?76eKGaVZySHtO>%q4$2g| z#JcEz!$1xTV#Wt&u{8Zf zbyG-*vp>2F2J)^#?JLz!h6fGH-fCf{R6~p+oK4VkE%0^SCgGE< zSRnTXxuSUFH#*S=YKm&`Q7s)66J1@>*tY?wDGF`ntfGWmSRDE&ATs391p(#st1cPn z1nT??wJ@DnGT z%+bcd?Jyaefq{{fv_eHPg6O%;Axx$|3J3PVRh`abe7lOOfp&wiLOX)q(y~QyC9rW=I<0RhH6T7+dsS-S5}dwAjE@x z;-1@pd;viV&=SuUlcISG%Vyi(DI+@32k?-wC1AY5!WbcYGCMNw_+^2>gUjLbWGV>9 z{&=ep%kt7!!oAa*)En#H0~OY6v1upyZ0xz}WTSyS%Od235GAiAv4FXWCAVkh>1J(p zM#`Pfx7tIIw6~Nzflv|>k|#S0cC3`~CSEe*RA$oBq4INT2F~u)Zixj2bJIK=raqga zh`kDG`HeYf#QvsvNzSHyxMX5dM8s_p>(BPlkVQ@Y3Bqe`sXIM4p40THL>t6xbB`g! zB&HKZ*QHi`{(c-vS$CI(82+6LKm}Yl=CkEPO%DNx~S5M%xU?6W8f47A01 zN2{v>m5)Va`CyCoOy9VO(iIZxg&b@enwv{r3}Mvt7yBU#!$3gsEI9Ooo=uTi$}p3S zIxG$NGeAsTnqt|OjA*$K-KUjBj^X2n}rm;F30IYczR>SvrU-YRej;wRrDoi9bLqw4SLn*Q~cc zpF0&?+}sqUodIj*{ktu_c?79Wogw9sax5!N*Oue^`r^1yDG)+}p0{5JgJ1%7n87!0 zM}a9RDSpARDOJ}o1E7b^*@)A^&6o8-i|gyJE&3t{hvn;z-4ZgvL1E{YeY;OcXF&&s zmZ71W=IaKl#uHXx1gW;S_IL+I7_1_Gy?uQ&;tDjs@t!ehHHu`(Hyn4;Cnu8JgDmXaI<50Bp8c->)gr`GPO&uXJt`{Dl&+YepZv<#tc_ke~}?R-nrDp}d({->?yAA#>w$>=39b zGWz`arjYv$BS=oom`usCh93ST8svKU=J2=NK#gu%RzI5?O8(9b6tD0|>cx5hR`jkNiLpBcFlU(lVcssXv9? zL(WE*z^4ymi0>V@m)}m!g|l+ya+fy#n|@_-xJ%3UU}TtFpldJ#f z+-cNCn7ERLr;%1Np=PMb4ea^CT)=ZI<_fO%@YJ4uM*Jqvz=#rXu_{!zd4wed;&7ij zm5-Ol2769`-ya{Z@w#(n6gspBZK!Vm7@}sOzE&6&ldhw>r^&CMBUJfFux`0@xI7EW|_u*rcn9OVb8E^48V?@Paj#wDf?*&I`cE8UO~| z!ht3^kJtK<&kqad8}|u8gIGZSFtxD!3H?$^b|vqA`Tj-n90({t1VX%(n?vgQ0CXV% zXK&G0EK0y4SIs{**A}iPjHqW-mQ&wYTY?Bv_$7jrx;BgY^S@%Tuk$GrPL!o#6icJK z#^i&lV^(*$+f7|tXRc)wbTS0vxn&=;MDc9lKI8~>sQ+ng;S;(3tE!-3(KJ1KeoZD$ z40rjaU?oSXcW7P_p(&G-x`D7d*S?OjroTD+blld3LPgO9>0JJ8v`%w#3bHJG4TDbC z8Wm>uin1XW%>x>jFmZkr8K`oevR97g@pG__c#k{*>&fG_5ig#)UVc8e)plwgjs4-#lP|R^?zEJ%b^4@PUy<6^;B=}8dZIbIBTnzv#!7@3 z>veVNYDd;CBH?SEP0W8c3 zaBAAHpeGz+S(iK6BP#Hy35S4}owMjln+8wLSb`FrjX+5mPa!dSHG3In?MVGShCm0- zYd_72>5;YNLIKjm!~h))NTg(rL|kKWId^J;shJt{@t8I3-89FFQH3yb?bCarp86RT z0Y;J`A#?ohhJ#Ip$Yl~}zj|+S)Nm^-L49Q{T{qLI)2lX7(U1 z-2}SV@kYD$EaTk7uW?&;vU-bd_#{YEvO;UqKiFT~u$Y8HE8>f;4r}&IgSb+^GXwff5Je#}*T*xxiu-`-8D;MGdJekXY8w~kBWh5FlRL|swc^J$aKF%vvSu;vMo|Jj`#%Nn#({IHm0}^-ABT8&O zcXJ2fAV{@b$Fo=E2PKNIE$*Jm0~lQpMj5by>y9Suet1=4^_ggNH5+xW7G&>Jy-Z z?&g4i0BXcHSlC7aN7GOO4~GC_D3*fzWoC~86!t;QWK%`w`nLRNE_h7=IxxP$adUpi z&S9$m$WLSmr0H-Ak%F3}Of_sQ9J?Gvif{{nQjwlij6pr{uVUwrb)A}3C49;sll~rB z$NdqQ)IA+@C9`;Ud%3x5CMK1MW8yYn)d1{XuOvnkFOWY+b-A41XF0Ddw zp_q4o)va0tZmUD7ha#Q(_u3R6I$5u# z8!g~Ao#P8RZY_?ZaI`&0WU>@3H2BVJ$GfnN$4poKb?*0BE<-{Tjr_?a=TZJK5OQcs z-mz$^0iw8N_*YplcWELyS9E;Bervi*Cv?k0<5Mj8471xZ=i1^c*E7G-ZTAI*+^E<7 zv~NTMwvKRvxX4s2bf|}u$)16c5EIbszyFgQB>Ffw#>4rK-hKSYLLwOW;h+1SAFsbx`3&MP9ZCf#E`^&nHPW!Gz3M=vW!ahowO9GJj*GJh9p49;4%Me6UIn z(vHR`MctOK_b$BDkKZp$+`W6xs(wFaaghbIGnS7JA^!O3<29-e^c{bTR$aOuCro7c z_S+|~t7X7qJnyqyJ3M#b!0+&b=RH_ApcD^F#UXnRaAMu#X+(v!rS>PSX4tzkdd_!S z{A*2-Z@e>0(v)95RaA)?X78{AlME#C*ppK|SOJEx>8Ewuy`W>ruETSKhvLBZ_@xa; zl1w9!grJ~0)V8y5kP}J*asF}>gN|BJtVst%&5|VL^)+0ePo5yLPj4-XS>iY8L zmT3#%>90Q7bkMI|i2#h#YH9zzzp2>NT#TtZ?AQx>rBx7`UMOs_HmoP(N!jW}6KC#A zy?jwZH@o%swDI!KUYG>WSK{DD(RvHyX48>53(L$GJqk*{8 zBkgWC9_y1jp6P*eZckLz)uLl#wJLU!iWcimUKE#>($OE1uqnE^_JzqY2;Q#PazO;FL9}7|~GEfsRA^E1Wj8Ln};VQhr^rQv%w#}&CFfUxr z4N_R6e^^V7XA}lhRgXmJ5X|K3nL#3Hzf=-ECX01mMW`~xo^Ekm`E;qP%_MV|YP{K+ z%a15Q?}%yuFB$`=7rY9i)8q6s?6$zg`j|=Fa82r^p2Yy6nsl*s)*`YC5dSszoBy2) zSa!}$yOK3p|Fvnn(vukrRd0HsMRPZs{Qh6A+DE-c{rw{QMI>&~W()-`omBab&K^*ZEUqUBm&oQ@U83we@uy+9ekkXIEEO7f@PG$O3$Rc830rj_6lS0XMrN zKNne|aO90u)zyC_My{;O+}+5Di`!>zJW7q#;q|B<_C?>95x8O)?FjC|2{$w}y#L^V zxM){gLIQkxx=5|cX6tw0W3<93DH$PC2sY=eC`O$~=iX1uESpmw`D&~3NzH3x^N&NbpRueG(6mMJ7P z%KG=)6RkTxy=HCd2w$JhzV>4lgD703Ak3zOGJ$qZ%h$(^leKzzpQ$Zx`tj=tAP@7F z!y;t6Qyn$$cJuzVzJ7x9VW`Rs+}~!g|3=`_TafZiQR9L9P<$G_(Dhz2_|?sEcX?3D z*u>;x%^MXW;#`3aXCtF*T}g=)uM-nwzs{t#8xWWL^B}sdJV6X6c6e6wSBzf?AbxjZ zc|GwE%aV^zN*c>6&Myy1oGNuuD9VO?g4*J?w6x5AFbh5@ehG93UN>lM2}(-QTyxF{ zkJI^Mlv&a3UV8iR{<<`*?+x)0sU_6D#2!t_gPe4?VLvvThh7)5!)9S0PCl#Y+a3&h&x{)H)>NqYWH~NQl|*AkKTv$K;7Y%mPY-RF@b)8q9-MWN zlN({Txl~ zrDn(2b#=A!Kf-q4m0$0KeD=J)=9;yR)a_}xy11_Wx#xo|gigi=&B=+t#L&{xO7&VY zKt+OX#VcK1u*RYFRL{#frvD>FPoRKWX zOkhqgsy&HG$PL0W^C~RJIXF7ds$HuwPbZDRKv3A&=Q>f z3DH5}Cae9yxAlV0`E{%ZI=-GVGj&c}bH=XwKeCQqlSnf(nLYpmL_hua9MG;+JKGU3 zn3-9eFGo66zYZ&7lZlBY5I~K284hY)u5hK!9u7ysQYjvi9F0QJyi!1D^ zO;;HQ3z4kx?DPT#hX6}bmNM_jwQ&7zIl=?r7HEDSC@pyQmg_^msmxmklmwc%X<$~2 zj!nJuyZd!9fdsjCj1Ap&Ts7#(Q}GZ*$hs)@x2qk-5X}BNA-Nsl$0Af93pK)i{TXxG!%k6c?@^Y8Tkxw!b_$MRs;k=N}+6NuRULi_7>U%YE#LOp7KLxuHwLc=PXIkupHQK$g*Rm;@R?*Tzf%n|nb ziVS~){skvWcVJJ=@<>lX;q~n1o1U-YV&RaL2cR@B_)5dS)ffN00oV82?B9;w zl_i1b9HM?vY_PVYo-6!QdxYR>YAKd_U$;5ASMl08{T}N13S=8mDi4BFcib~8JK-?fx<~5tCBR@8s zoiRd5#p6-kE6k!H!C44WLQ)lF^`pbnRE6{X*B7bo*GJ3H{y6cHH6!wRVTzRqpSo1{ zCB|NYXLzk0KV?4K*(oR+Ld$|Nvm9jj&&wsV)T>Uyg$?(Qj?zCgs_4Fd|9-o9^L(mg zg-RwKH4?CU>Q?Y$a^AUbW+s3N4u_Lf-)MWBGYj2(;1jlLJVxFKUW`qEivB=n^ZjnD128o~?e-1b(6mh*YDWBnn^Zxf6Gr`p6aeJA8wYj<3rfWTbzYSzdK z^@u{B@@%(~00VEd)l`(ABt0$D3tY}mZ*W|kQLy(xH{Uvaw_~!jYOBJ% z3|%oQn!a=#S5}_jyw;aQy#anNDq3Csn7UN6Oh8IVYmAXZ%_W`nu*F%%y_qXgyYdj$ z=9C^AR}Kgdt~r6$^$##wAV}kos6oxEPPVQbb`DP2cl!Ef;q34qWe}^6Ow<3 zCp>wCkrrKZm2$I^lJ2m#cVK`+*cC4*8s)M)T@IJ+0X3sm*fx z{zGJ4-2#fAY3ms}oJVmew_qHHSdx=6qp^e>E;aVNYE((HV5 z0luLcE-T4V_{veyvbJ5M7yTZTD^J{!rwV9Dn_ki(`9RnBg~cnSM(t?b!q}G zucRi{l3L{Ty|Ga~YfQ$B9gf1NN!sk>-|C~~W!Loe%%k<9r56C~xQLyd{K7&e2&Ati zPvB(ZwV21?)F(cMd*kG6RPC@{N!Vx`slEA^FH&3yjhp^vBqSB&Yp7b@+GK9e{*e(D ze!YAjpL<*x>H$??z}Z-f=ksoiiponZT^XY_8x>G{vXo5 zr>1=Go8GgzVKo^`n3vgLf@e+qx`-FeNfs?YuG40TxIm{zhbG1phZ5Niuds!}f`XPB zYixBsW(f!+R++nQhfe00=P{Z%i#Gv+`TsSDeG&$iA4&6j<} zBFSGLE=kuL)b=X9(&Eym&i2vjleHM-*>MT~^zzKVkuuO1>r8*Ou4C?yzM$nwVsU$x z6=PL@#64;d0iarOmQtyjOsD&p{N-NMqgoF-=38>I>&(8Nguj>-a6u*cL6i-%vNt%X zOH1pI`eYV#;dTsR9FH+B(yhWlq6Yw>0PRRjM^m8T%GhR>2cu6iC`oH}^3oNh3c-ZX zU+wmy5r!}GD=3Ttad=A}DUWR&*2Ao?@$t`50i2wbM-)XlIdU{n4W_oS=(cu%MevI} zQyArTx!B;exwg4kVL0a>O^lQD{4DL1 zl~onx>|BiMl|P17I5;?D6$&lMb{kI^Dwy$t^pn99lt9=kO^Utdm6&P*s2v3wi;dJCkBgIAm2>l0zsQ@Ia!#%zx~lTZ z$i7UVk~HUbc5hUD6VZdZL2vKrC`&5@GV_!wQlKi}@0NDuZl>|jG_)o9!)q43 zyLYUH&kQ%l{aackN5^~kcEz3k)@S~x@$X!~xWBiM#n;-m0ZK8&Bk4IMOWC`E8nw%v z@pgo4TD@W>i{T6Idd}rm2m5Wou{vE^B)*$ZRG}F3R@I088WpjE8^%@_+D=)|Ld8ah z?hfJ+3tp@OuAR+72HaQ9sl6v*d_f_x&dL1f7+bx3N1cv=u0OJGb(Ue<^JWAFH-tsS z+h^pL=BD@e&!#s?>!KdW3UXUad;{De>=E*tE++S(K^)48^@l0KXp5|?TU)O4HoL&T!TrZY3BG-hAPMXc!;D$T z_W~G-YO5~4@E>Hn3*K+t#AEdX26@uOU*ZjD+0PXgH1$2??ga!~BN?LRwCPv^=ALNKEIeuxE`GPX=Gr*WrBJIj{uD^;;C_ER?TEi$Z=Q%UpnVE z4gyU#>}tnvl8mps4A>G|qJ_`8A+6`|eVyFQwu5!#s+ML&*>S2%>^icbdN=nvl>pLC ze%*VD{_|r8*KUsI%}IK$jYHEsjo0#%3F>67H|L0-2USH%+nzf&)8h{n`EC?FF9hq1 zy<~0-B^YA3dF$jKb9FP{X&`!TG89b}t-UBr1Y8e#U;4FVMTY>~Bulv`6V@2LSrv&a zT)GlVH`3J|pPTE@N;9x#TW8>`D%QN|qJz3gr+98A|5*M;-gNyz=c}HiiOi5}!d-4= z;E1^KMhogID=YiL`uxIeq-oRB^V-qzWOda5q!HdHfw-q@Vvvc0QcYlE(qC8;*ea}R zn*aXe7L~~$$t*P)aJq*ja?W>t7HVRePeMb92MGbhjR_$caU#>`6O#If651?Z@lz`c z%iL5>BbUWE8&C)GzlCGUdH>>Bn7l$)Sc^{T9sDGutG^8zjmSwWsR2M+d-t2y$HpJ! z3Uvp5q}Kx-e8a0xLm;j4YoEQH$F#%b_5iQ;BXWT^d!V$zMvw*f(zA9oi4B9q^3k# zSeZe8RQpZ?IxeSUnBwx%s?5jul9J7k^U0l=k{H&CsWUa8QUzGml@+4|0C#nAkoT*c zpaQm7BQ9n;yF4Hdx>v^qT2$>Uk-l@=VU)f~lAi6Dt1G7o*Z8`>U&aeh$jQuTV5GH? z(ST$`LOVl>VR;yHSnKhi%!J$1g*`d0EFKaJ`ndN>$$W(H%-gO>-r7ce{+Rcyv#bw~R-TlY zn3-(t7)!^M`~vO+XO$S4cQn#gYNz)=E&Gg_nf`d=t3_0iTu3+3P|vu+8yub*XFx?w z-wcTi1TJWHeV32I8&lQAHn_m_!0QNzLT8NV=N!09d6Tggxi7>8-c$D*Qq891VYi2|4SW+L^3Xx;3HYo8X8J((a8Bn4QT!uA zW~F+bsSXzB7|z^wkMxd@;3Q(YguWuP_alV&Ov7Fpc@*>`5XXe3~48^C~qc@S`_bKe0_dR}%z2Ii#mdo3k1J0JA|TYE=(rtWn2 z0#Mb?d|NlkYs?;Um)kVnO`=E3^W>u`BNumQFJkJ3t;Cs;zjb)#kAGEyCP9~z9u z@fRWP&j5c5jQb)OFA|AO-59qOJ*f&93&b{aG~K9G=z93$iDKUx9fWk05$5k~BIP#+ z^*|)(e$X!5O9R^AArM@hy`3o= z$m{$Z95?8LkuLHM#?(axer~`1vphYLJbcUX783yZHz2|Z(hsPlCL5av`d4RugcI7_ zD$DUH94B;bN0ky|2PmEMEf9xxp8!UYx7K+~FB`EA{r%g3zPElQjV$bY1-I#n9Tm) z1?T8@&YmroHn?$qv#xmIa`kP zJkB?I`_p%Pj$Aldm!RYEJ>?Y3T#aMQe(U6|r|7bt$AzBC<6A|)hvxfg>pt9gDxDor z|50b5{jp#cegJyku(hSEhA_IhQG4;!(ck}7G6uMDKneh^csx>81U|7j>u6YN@6gyU z4phlkS5Q=(_iVW>L&rEfKRnW6rwpNj8qTs)`jE|kWnWqm@@Ewf+5*iCp@ZsFIDt9C z!0oT(q+Q@&O9#S8fJl^N13eJ)=pm0uz>-{0ga8LhP}hc!KMgeDNFc75?(ILPN04e7 z)4vhx1kG(g0aTIOrkCHUiG^L))KEBhaWJoY9TQ}-^Vic0ZP8*e#|04%WKlw1gP6~| zupcXs@_RfZ87bQhT(}G(=X2OI^*}Fb49%9$Me#-cq&VKcM_i#^vqacZns|oudOUt9 z;73(s+A3@B{f7k;gjqt(%(Cv&^t)N^D2vQH$H{mHnPw72SxrCwXeDhi92xK+4x#u6KM#b zzG^w&$pwlLM=ynZSiD2AD(-&uhOFk&OM+XJ=6>cTX!kK>HwI;+?86$^uK8P54#CPfVDE+Z7Zz3lyhd?b1^wo@ zbT5JsKeax0zEZ4aUuC~OkJ2p6bX}l0dD9Df*x1>EF({TSrhY$*ck_E~y5dvTPp<2F zZBXATfqYWHIvUyjdA4V8do)x*OUcTjyhjwOsig&6ug}q%yA2IMOsB+=uf}9?189X8 zWaVz!?q9v-LxjWnvkW(<8w1F2ft-p(cf`#pzoN7G{s|e~F5(Ih8P339on+&jV>Q=OEXB=Jc1M}-5^S?x{09*#-mBxhM zad0Xm9a;t^lw%*<7gwF0G7E=}B`+7NNOngbF=nC~`liOQTcm+9cr@3T z5;fT@=pG1eDC^IsWPdJa@HWe-hS!h(J9DJHoTm>GWDAioQQ)u9tOce}_NCv;&z=dG z0I{EOLhzO|zqYWYt1fcWh8J~-?7jwcVJy5o(JtxWp#R0)TSrCt|7*XPCMW7~}PJeR-M|BlmV{7ycV2--bW&M4{lU-a7=GFNYu~>ziFQhCw{mQ@HgU;3n z0raZ@EMS_C;??VPbd45PX{?UO(gqx@zl$gOT8*5>`o#?hdss065p6bF*c6N(P45|A@g+O03N;%zj7pb7hfgW0l5< zLP9R!-?acR8$s|XLd1aN10+~8|0;yBZt}HUh;1%j#nd$kH-F09*|~Q4{g--c-aNt- z0}<*J(aTbg&n~wT?)M9F-M<#a(upZ}^}R{?C8Un|JCII$IAcHvx{PJB#t4XVd$2}A`=?!cKT?u$ZH?D9)s}HOAlO;0^GgoV zf;74s3V^Rke~(J}n^1F3tqHDJoW(q4z?;<$Z zAP&!50m);wa*V7Ct=6iLBuTF6H&OC2sV>q*BP(3iE%UqcdA+vQAQp%OEL1sNDmI%Fhh4_!zqd+PB%X;VI8ufno@BqrQcaTC^X33jYTJNKP=&XY7s_ydcT7bakki+hfjWfx#-|AyVTl! zxm~L5nNV6AIIQ+T65zkUDG_11DP9-DQ&q()RO{m+F`KY+AHq}(NX$B{s>YXd${XDW z4*BlVlQ#b>{k^NXW?O&`efn>-o$4!@vcT9)v|vx|9%9ZHWHJ#D)M}MA7In1^DLsA` z*X7e@O7E&@dvPnAY7@)fcmpPfUynfHv7iHjSB@#ZNwx8KkMz-ORA`)`?dv~C+QSyj+P9EAOL#MK8B+fp0WWhY=*}JHPx^)LHbQu${z$$YY{Xn-b zr%hJb_o%(icG_%@KbImsuB|mttMQn;F2}^wjXLr@pYYyaUt5dgOodu!RRdYzIi`^$ z(St-$OpJfa80UX_hHKhiFA*mZ8?6%;sI9GKBO{2Cudv!hjDkkaz`=R~=a@mWNqJEb zO-?wFrN4GQ;OmL!oHHW8yH5>f5k*jCQDWSD#?OC1H0U2-2M_0@{u~?LSncSv792n} z8xD3ZteeF}#ig!JfMwj(qmV-YgwB8+2NDYeMIk)monHsUd;_*NH&b#4jGX!os^jDDRaaM{^@^1k&kmt2%K3W0hBc&mMKO3{+ux<>frg%txJR{*Aa_LHHyDmIH~3 zEG9mvuKMk|$*!(r4BtAP&ylf#npbCvr@Df??a^>N4zhg~3Di5a*reFzqVw2GKaar^ zzmj&o@b1&C{Thk3wPHHSx_Ti}5(k~%_*6UqrnE3i^96*4ff-HsOd1eE$!;Jb4MFx4 z%hhZGlPJ;^f5{f=;-h~hPqS3%NuND^nmqell;9n+tEVD5E2@Yr8%Acr72)o%QliG z<7DqgCRF^)#!8y(T3~MO+tEqiYJdxg>~yqtIQ<8!0=f|nO=s`VAXV+Ei7&@2^lb@a zUEk*h}PmV zcf?sF9!C}G*9VIUdQSS0M0S>!mfpB=i~aWioo@#|olhGO+F+)&jUkf<*cLEQ5|h95 zEP{6Suw0t&(&l_CC#FgKW+q<^1lCQs?GhpB@Ik^<3`RtJGOjKJ(2fhL1HmRvb zpxC~@#E~wkaC24WGbNqkFet(IUkgO$4K(212Th2sM8=H5;k!El7z<0wXL!#+kkkwD z3x}MeiM{(6i0Gh<12wT?$I63(W^<{ZhK?V}$j#UKUGl>p61pJwToJ%dVUBR{>jTLf zE1nkoMaSCg{F%_BlebAPgCW2>{iZIIory+Nzsa*x@2o4M2(b z+mVV5Z;`+zNn^zP--D5rT~StXG&EBVqS@hohT(@dlof7HiZp$CsLpjq9@{ zQ~od6?}fI_t(H^J3YLzybPE9jkTPz!r#koTQuV~~?RHB1L%Z_Qiqz&K8@*y_Q|ZkK zuko{~rb{5Anl-jN_$Jb^ei?U;fhXU3^ZWGlbXAOjq3aiXH#gbQ-o~b)vT`3IuBx`O zvLYQjTBMKs^L$1^ofPza{Sd*V8(_`juBa+1Dw2W~il-+~4bRTcD@uS2VhdMSQc>Tt z@ajOx3?;_$%Hi|47eK$Y_u$NBr*G6)AqO#5zKmMwzVw0wY}(|VJklTM_Ufa+HInc0w%Tc@&Kw~<|z40Gp1F` zv08V(xmiD66AKHP+hmfYG50mz9qmF&Tn_4mgc(&wtE}xz=ho>eASWFGCmv5X1#c%) zu-A5g-bHy<%B5T3(d9fynt_vFL1|z;h3@Uj0i7cqMf`pk{A4Ce6-Xqf{Pz!%9czoG z320MOM++O`Ogr6eard)n2nh+hsUhSDIxTg$x2b1;J?`w?kCstmh{cW#4A#|CqF3g! zcmTm{c(}L_6C!Ep+wE)QpMXx&=ljAAdoeIN|DCCDfk}Y={I35@k)A#ah|Ox}bD^iR z!q@SZL0Xm5Vz<2L*W_3`Q`3>j;S9Cke|0jk*|~KZ{!3)fE@&EiAePS*wGP+)6dA4y zcr*`kFY1%FMj2|nepQD`To*xDvHqu1JqDWO77V0!a|iUjV#|VI1<66P?AWMahW0=s zF%;YgXjKSm4WNZ?ptDaw<^vl3XFydG&|wuo0+OfeFo(MX8?L(K@7_Db-%4$MlL4$D ztt3;9+iz4!auC0W-xybIu!@W0@=|^6(n&dW^>oi_6d>QW{V)^l*WCviF~;S4bxn)W zj2)?%hgirq)TyQIC;ZMz{_R4&d zTzU=Ywq3K}V7aZj6CNk{-jy}L-Fsorbl7f;fNl9sa9|6kIj?#gLX( zdgkruu0>u)XZ1VC#cY-Selm(F?-P!?*m&S#aw=yxu39hQbvTIY{%+t5pM1^sIk8ksW=Wj4`iI3HEFzKWS)En3o)EZHo#D z%<42x&YIq)gokfNN8*G9S5GaO3SqEfI74hJx8u}@PFjEwtU$*lmuw$sHM8})1@WwN zH8s4Q1X@;IwRF*&X0I${-l*-M_?mUJw4Mvs->0OqG=J+fyux?l88YqE%s zk>R;F^@W2<%iut&Bpd_3Pzq4u5eJu6mODBkjUbPni2SI@|Jm2d=4;S9(*v3S zsl4tZ6M;I)N!*I;&k$BB#?cv#ML9XO*6<&(zO}Dq2#k{TVcE}nVFiv zLRD4eK}f-Ihv4e$>>aY7K#}e;5Ym2^^HSbbW$~U)I=}R^rp1wQI^UHjE-{?lcoheF z2e|W{oSplA%VYL2c~r3r=9U*C0Yf3s|7<+%wk12=oGM=jDwtVD)qD<6K@;U>$O>J;tr`qiBQl?g10Yewb{(bIDRv(xE33Lgcpr(FNQiSeoeD}@ z=x#n;*c9G^xOIh4B^(+&+v6)}c65|exY6p0YxKmGu32(2+S=PU;?C<2RISl;xJ&0w zK7Lk>4GpWQ2-!Mk1|XD(=V!h}L^QuT;oLb!`q1G|X_JvawsSgpL~yX7^MQf`77WY* zF+VJq6_B^??%v#|U_V_z;^3`mP@{Glg1-5E5H&L8j}djC3JndN^4WI>lL-K>#@%|u z>*DU7110{CnipS#ZA2CbRqJUXA8%Gim^hdWPmQ=tC3zf1?B6qVM-NVAwutyV2Rt_C zUCn8~Gr_ZlzfIP#P@2~Eor42SX7WV~3%i&-3`uFlk8XL@`Hs5}zRHII{Wv!_0wTJ& zxe4M>;*-7>Y8Q-Mt9=Io-dx__xhTJbSA3Xk7NvrMeA0t;LjzHVy0iBqag6RGgy;XR z1(=a)nwgO*+#*_jwes{`sG62rNVrXaLDg%F0WAEre9Jt1HGu6H*sR>Clkmn^Hd@Mh-Pq-8F&>Gy|$lo5Q{|6k#i@Ag~% zrn_GJ1o)Z%R1o|7egAwJ?|%y5G!VSUQ9sg(3}S5QY!3^Kpu&c!a5|JPbD7~e9qTuk zuTnWS?$1a?K7TI6jrW}5FG3N#U3^)du}>#Jk(ZhS>2Qj?$e-%mz?@e~1|MKBU2ol8 zAb4mu-R)X1v$JYwI0Kr{TGw@-R!L2seWo<1CQgkrKAw#H^t?v^2(`|nGEEs3azp_U zjS>&N+!`sK^4$6ES)~R^=^kpmq}fA8M&=p_@ch?D`MFs1qamh6;;eNk_mh7?Wp!oK zaT*igeEnf?x55<{qRFCOZvc86K--OPpEq-fc_*Jq<@SG@9zlHoK?}xBP5v==L0Nao zqbHp39;g56qE4#M(lLYf~An?PPA@G{zRXeJiObuGrKCzXL($=+( z+H;&hG;0AVn)|C-lbdM+#{W&e%mX`(>NK8chS-Ar+NW6iP3mGj?@&N(RAS8et(qn% z+o_TyWR?o5ytay(5=MtF6v2U|5H=Da&&tKIw}ak2B%0|Ckb3;KPv6wcc6w^$ha;v6 ztUw0dLq|sdF{fEhX7x6gp;I;S02_)UzD2C>yjkSfd|08xnj?gK%ki0(4%crxaO;N; z7@V*qY11dMhZ~^iY~Ec4u0L|9cLLFkJ=U4REp~E+s4g12Zx#Vo&#Fv1+Uejsm+f~p z%Ae#LOZpC3Cz0a5X-1iuN}EGpFmqRzE;)b% zbg49Tc7Bi@_@;GXWF5A=L`yJCAZ*qlZY$`GJc zvs-myZ@+mGr|ERuVoUeDzNW0l;B+A|rgL%Gd}FLuHw$jyxj$K9t#pF1HFw)`?tWZ$ zRE$qs?&%~1WG}D}6T7601K;WstRwjj^&3t>t6qk~&7(q-RUl?jgZ+2->+Dgd#c)qV zTPjU*U44DLp&vcPLydC9;<|IU@)VjFbTANLJ6bndDPQ%yGz#WlSXpq_!veX@0b^fx zZ|hy`v`%FuFIW8%BcWnJ$~eDTf_&mkzddwhSX;B3QjA|{cgLvv9_&ni%O~NI!I*(z zRn zzdU2It_8_5(T&@_UfEh*rnov8<{L2~KQyHZMXXVhDC$@R7BYh2 z2YmI<&x&0^AroY-0aDU@hpHe5-c~|w(os(#C&z|f_q@4!w3%0;tkg#fSsKPn`M$qQ zXBlSJoC;{G7E}lS@sY^|)G<{9cDfND z5TnrkkA}Gji1-i$Xq&jlhCb!j$12`y4Kmv07Z2Z1$T3E{kb*+M{=K53jeybG zp!4^S$QFGui$NH%(E0;(qeEGN?V;lX>}l%$y7G!Lk6lRYL2acEw~)d+#(7y29_UGmoT2O?J~ zt>-%b;M(G%`QW(EfRw7*_vC2rJ?S}#GdUG5zSaB^=pd4-QB%)_m1EKCtseK4njb7N z1i)(stP*g#4Ktkof_RAyWC@(Ruj5_#RKP~zj5*oX-eE>VGFNmRdIw3{&v++o%>G{J z6Hq_>@RSu+#3}6Wl{Z@v8}9eQsV&vs)(Q$v>=S*q%~_4cgo^7R_6l-*70fUot#fnw zz;Ysc%wQwm62vZ*J$RL#%_ZpU_)6wkpS<%_6_I#&cnC@O{ej9C63HfNRu*QX@R1f} z;d&nslWJ>SoYwdzCp_hfh41@EQ6OC;=Xzeho}R9@o7eObNG+@Nn;#(4t@Fmh`A1^O z!l=Xp_vC;I$96g9PpPPXx37W>$@V05^3!oH=FF!8;kMt#JBo`BK?Un`>QhlSyNRys z0Kd`1OpTBSwXI(PHJka?urhDZxRBGPT0hV_eoS|geg?*8rR&j7O1zE%qz4@OaR&RO zNCrOBvV^;F@0VOKI}Q#u-$bFhGP*Zq#6d;MFoou9!~oP9#wcL{-zp+JB+||XpoyFn z*qP0EYU&i2v}bXhHmEEE=x2-xB_(AuZX^_#THuK8q+~_u#BZ;atPk1?XQKijD~Djg z^TUK&LfjzDXiqtoSuXKY)gtX_P~NJqa-7NJ?bgsS@LYc{I)1=nGMM1>UhRwj-c^iK z$2Xaaf^`1Vfu7E^a69yeLZgFNldi7?4xb;0mlah4M{AgdV0X{;B%N&0y?8zW0T+^2 zHsp=pFN-mhUEUh~fL!dpG_YLbJXr$dUBW`OVml?4D_3Mo%FkK+%43vcVr}phFxJ}M zD*Beh?}z9J1qataurBx{gk&4n!*3?@Id%G7N zKM8<|F7ZJ!Bn0eJ56zF!d2(r%u!_#U){{74 z+KFb*`ue;90KX1d*mEt{OQIqr*{;W8$7^c46+*yO7Z3Q@FJ&wxMRpfX;AA_FoRkUe zS5VDZ1tRczSlN^ldJf>&Bk2Uwp}p?Ww4GVVkH*Nd?~mKaI%Ktx{c zwYoO-y*rim^K^!WDd;aCp;(d4XLN1d#$Zwe#ieAL@vK>vr~OIv zWd$FBlnW6*mIhN8m_shG@WnPRw^k%-il+EOg`6O2-pc={OF-N8^e3IL7{kl_5cYk+SFr~4!9=3D4 zAo1|=@1_gmB{ol15v7((ShTNz4zaN_cb`U~6>oCz-Y9 zHAEc9ZZTK|e7g)XBtR%ol9gTh>n~ggL%sKeli0qaes+vqGIH5qabt-gKCPeV7!~zA zFKF$S%hK+Tua|X5=s=q;X+{A6F!a3j5&^cNk<~WA9+RAJQ+gmQ9*(%s20bwoj-dK3P7^zN;s-m03+u`{`3ySopAI zRT953^s0jbLLGP+2{LMez=4}Mq935khXyW+z1e9>A;F4A7@m?JJw!5@#44PCocYLP zKF-h;`H;_*8@Xap3#=fLW3FNE_3b$z*t?DQQd&amt8ZCUlwQt;zFdyhXRLv# zyPewyV~}}69PXS+W7s~(xtdPJk|m1%s@>Z*#J+fRzK4+HR08KMR}7l`#z)gKIM`qf ziXyKi-OX|>HqkRw-`H5Quw8zwlQn7Y;Ao$lUb>*=VQXtP9lOxMvYJsN>cG%|(v||GH zBbNyd>fEo?U}biVJuy!?@wE){X{=;9^vC~bbWDJ9QCjlLm$&`$TRJ;d3e+>DZJ(R< zKlXsz%0uN;`twQ*z9pxqKotPU8dP!7Y!VJ5s}hw=5ww3!mmSG66O)qQt-u=rc#~AA z%MsWhQDJ_+gR%MwE_-wHUQV`k+);2|ea(J1)pjr3{zvY>z+Hov5Xd@kQ9QmI>{xR! z1*Vl`$v=)wgAv#JlvD+MtRnNO=>q-cGnvfSKA8{~!^$3UF(C&4(Ok!8%+qmNUU0_V zQ=A)=fxuj23q6sTX7?29&fg`4i3xDYjK?4}+#twJjB2uAb3;V}8=chw@z$iekshz@ z)K@uLsC7%Wb!Wr|mr$(SVi3tjrh!+xdo{c>IPMR~06F8pi0u6#1XNjD9jG`OzKEBl zVQIPC!`1kL1_dhXytX6XCcb?G*+D6n-d&>h0ri@vSlICQ){`owZ$jeCydeY2Iyx~i zu?t8su4|z23EuYVmqCFl=bjaj@VLIUA8%dgL!e<-PH1{6!fKSIO@peh9i0PyidOo0mfIrf zwi(+(1zOz|3sTXR>~B%Fd2xe6gI58mO_3Ie`~-ofKX$7(awjsK`iYg&b7hf(x$)y# zU2!PRyE&~GN&gC;_Eu7=&tqV#w=_QI8qSsvG!zOv76etCJ|)Fn^xnKmaBQ5<mPR%|f2pCitHI<^Zz-6gAPVq@hCXy#im(KQ(vB6r0ns<<%17XN^Nt zY&V~OHfjZy)?p_L+SAeU7&zgzmaqzQSVd5{7M4(nij{@cYw;MW`}#Hf5E0sNj(KHp ztf(s9rtG`BtN$r>`gDNQ;J!^w4j`pxQSl*)sT6u?T5Ug@)=;GS{w!UHr#sI}6RU9q z6Z*Hz6G3DmMlx1`vp^ zm%?O=i;IhjRxp>|WS9T=0pd{}jIdK6n_q@0F}rC}-nyBcqNISl-o0^a_sExao-#F{ zIZa4JEWU45y%n69W5%9&oXe~*C>h7Zr*zA>T)yP_K_+}Q$%^DY|7*4B#Y2YMAwGto z?=s`sb*9T^F(nYu;cX!#A;WEggMh~@?xL~rCSFAM?(;E^fTjx;a@`32qedz_NO<&G z;UgKDBp#isTWlt48#7;SY=!yzpao1V?8o6#xztBOv;jxSC)GWm-3@$W`v@cn$yEL2 zpP&DWqVFNMwP(rKjO`?wp|yQkKR=`pEl{R^a{kE3#Bp4jr}~hB>^qivwNSlapnjqW zYg86<`PazOrzTaf=|M}v7W0hRKpJ61Jt51imHVZx$?1kd!eqsa`|KOS70|rdv73Tu zQpuj5qyFy|GaD+7z?oV8<|Vv0AA!Z?e&q$?f|KyR^A)@-^1loX@CDgtAPnhWMMyAf zUz9HY_4@&|G`^ zL0v!wz!DfQxFUQ1a76%l2XIBeTU9Q&2>M4|e|INhV7bSfoBuD&WI^gLH{}Ap6Hf?G zIX3QYZV3qq7Z$nRKYwb<%cK7XUdS7B^EQAC36wMei3D1#7j<{3Y3^|pinB2CFU*JX z9|B1(Ads*F0tq~9y=k?cQRUGkJP_^~{8C3J{(`)6^}j(K%>gk zfLU$p{1@`hU*yRF1^B4+_x{t(`}yiW@=g9ref<9q^r-)%&+y{otr>!!^Siyhy=@m4 z_U?_VppKuGt^ot-r3ReaD=Tl}Z(Q8zoBv!{9dKvpDgT+IY=C+Q7$ihRMQtjRe7wVD zTS3Ut%?hOANu8UcsVQP&f<0DYtX<*){dD!8r^Oq0{b|buAF5wEsLA32h4%6AJ#Y?k z=6e2psQz+mia48~SMDEQ1-TWs-o#}3PYex_oju13d!dl?)gxdSsK`oZFCJ<7d;h%Y zkBdie#+31?4Io2oeI^HECS7+2?Dy`Q@gq zA1??#f3ZJ$hOaNYb+@_SsVh9ZJ*X-Q!kDgRIfMwY{SPA(@HqcH?fmC_-v8V!`9Fnw z{oiey|A+bLKmLddd>H4a(9m^Pt|o40ggLmbdTpvnN}|bG(L7XR8=Ev%qD-nO{cqID zoJm&$_jYywb2B9{hvDE2afHgohn?e7RWTg47()97`V8>t4M;c~-S$6)xS7j%-KSR`^j3 z#d^JOJ0F!m;mK(<2?(T0KS!^lwzi53;(C`^eUJMh0R;v#?F#X2AzK@(vIi(;eV(=s z$C_1bSJ!=<-w0%Re@TD41`sNA&UQAr#Lv>X3>x1C1O_gij%kjyJG*$~9%vN|gUX%- zw4O-c0~FsK^s?X;6}-^HU3@vt$>wYEgGV(t(UKr@spKM@IZT5ru=!vsNPA>tq7^uv z;*GudMLFD`+dpMuvNRTlQc;bUG#$m9@iqAQg0K((cZJYK%8|fGjha3B0QRGY6ILXQ zaowcKObrn-S|fS_fPqnETBz0;I#b(aGU|Kw+bdt=e6ts{s%ABbRkpx+g*>hMrK*?` z36oOl`T{snxzrZcJQNmS^ZxR-m7WQE{UbtJ%Fuo8*CuQ1*W9f6Tn2`%&DAY)sW%p8 z+jL}6Zf+QFTjGMTP`PAn0Qc0<^q)$Sn!d_LC9KIq=;Pg^us6&~{!gR2A64f~Uu`Dh zVW72>@MYrLMnyCW`l;aRRd6r9ZBA9Dd}#Sx7B$gYyMOP3(gg#eIX^=Vt?o zxAji=B0n8iTf>0cRi~ukd{|(r)}{*x*2U1W-wO)1Y8J60BliwRcSvrWZsVtgNM{0- z&sP=dee_$16tgR%nA#p1ai1vCB#_5IPPaP!8q}TtCH$ zft*WsOqbHltd7o*g;`1Y2?H=mYFR|K@k0l5^`<_{d+0Qz_{vkjmojM@6R9U3^gEi5Iq@cuH~Yvo^-}E9EYwHxJpU+ zVY`N4NXrKFDG!Y0C4j$dKj6l@-I5KLc;zP@bprJSw`2>YC4+vx&NS>Q_IP*8;p+`>H|WjJt>1#(2GA8sCIl z&t~X7u6ZHcT&Cu&H(ET;o;|BBwQ_L4ZbXx;%)(poL3CSweQ8-`Q4wr)JWb7~W-Xp? z(ISUz%a!A_%7dPK%55@apy@Q?oEAosA->k7nO9_7|91DQg=z4|b1!ip9F4>4t+toZ z+l{zKYexC>Sl7v<0v)4jzx8{1=oiKa^j7Wmqcv;Tbb7OGv3YA9pRw=$Jb;U=M#lTw z-KV3%0E~;vl}D>333}&C1vvZH%~jLQZVp7ATYvZgXJjoxn?0q(c(6pgWR5YeF; zP!~=d;(5uqva<8i>4MK>IIEgLD3G-fU2m;=R4!0e79P$LP!|4(^zG9QC(qHjc0>KO ztrZ-JCe}^w5?qdC#>-^{U<oNG+yYGB!yh0vUaz1*G z)N2fiS0-HZC1C(aIC&DDnY5o5DJ}O&BSX6}m;8z?Lj2vIl^vc=3{pHY^Ik#O59^7B zfbs%-W!Hl_N?6&GBL1_w+8S@vAJlZc-{#!d8|x0%;q_PFHF`i}P?#_Nah58=8%)$VQ#+*DrXEb7%xFgFPeK z@6)&E4+EF*)NYAn-JXFz5U@T(B|9P?Fpt&*=hNZ1sCa(?t@U&rV3+U&E|QeBRd`qcQw%oeiW;Vv}3 zJy9uaXjD~pXJ9#0PYRE@b8E6uS@_bbuKW2px#M)*OQsGtPGzp~igo$c`OXME#w~b( zs+QIhLqxh}w{Cf}#nRII@+IH-jSZJ$gp80O`umJBjC$~4{CgTd?w3fM&;yAX}QT7|H}Ln z;QL2Tc!&D>o>?(b(~!R^(^!-dKa;(K*E1UNOxwg^Qp z8^L*A@9yN5ZBkfk|8`gWQhRfIfu_+mygX78mR;HX`*WfP{JB{_oLq0@YZs)Xq`+oY7L=$S$hhB$ zx-&L5R%tVu(HFhO0<`qMIxB=T2fxHgjXzLk+`L2}D&NyHIuPj*tB5-q){v^#MLilc zisHokCPJ$ex;9*2!uwq+j}yHIcp5VHtB41O8^iJ1^Lsgjh2|^K3h^FR%P-13H%9`v zfoyt}4ePv1SAil6MiA#Y;v`ay=Avz!+m42I8(@RN9xMZUC0b{5V`j%|fX(!M*k-WG zRUBLPIf8ZX=3Rb%k5y|Hm%tzX^Zf8AlLu_;4Q6Mo+JrWUrHNJgz}%0$zN_mizwAdj zQ*uSlexGxonJi*}g8P;2P`&fwMj|P`!6e%dv5j`G>A2fQks50NiCw+_vE7+02a7R%)>1RMY5c zW27mR8Q*H?y5J&y{FDE-s6L->M8@xGq5-YXGAh-+K$Ut5KnT>C@&&KFlamOQd?%L` zTIY5PGuBI@nj)ei_l<4T?z?_T)8eYu1GWM>|MQdxcIywWk1Rz*8dnzfw^GKVjVU{O z?WI-*^m2APfemV3WgEqi7HS1kLS7Q=%$aS`zCA6*aAV!;W@d*)obGMk{Mpd z!!R<)$all|yZHMQHI+wc@8p_fMjb>~wVZl?XINWX$H<-Top58o+A>T>m$gfet3)a8>~p^8G-y2GPNb!RA0;%4T=PL z5cZ1gJd?2T;KKtA28IM$+Elm20Lh79K~{^KV+)f_0N3f(RMhjWN=Twaau7= z5p~>fwuMh4>~1}gEx0KOhFppDMCSZK&m$qj^ZFJR&HaNCQ_JlaQHfnv>^2^;deL!l z1_JrszDm;OM}}OEP;3yRVL}1fYh+*6Wec0Q!{BT17)ooFDi7j{W3^uz+w;bP91N=? z?$3ffoDa}MH$`nwrmF7Bf)18 z=gf|kKgxRKRVzK+-s0^rgYzbB(T8f1lv+6aE-BZQy?9PTEBFt0wE$VfpAmZ$+zHnt zs$upG$j$~!H5Px0$CsEa5g#QSX9OX1P3@E_&^6Ra2_GaK>FBf{WMH-s@P$tt^)0R2 z$l<-pr2v$0wPS5vT_g7@pQop%0tf6<@e+J+ax%a_kA)%oN0+$>^t`a*yG+p|;uE}X z0aQn)vR9=HivdLZO*`qj@{cn`fE^#l)(iL(tF8fso z3vdZIz~6U+#mZ8Z7O`Gg*p_|x71m`sW5xYorJMqJjb|~rNC=IvE@w#}dOarZ*MRq8 z7u1kNk_>!laREKe8i+i&6?-$Zmzv`Id|lOz`XvP<@i>O>nYwSLww@jq~t5@sfNN<+t0jKZgl5y8a-di{^RJVCc90V#I@kt*XK3R?L7-ccCH+wNL~0zX6BT9&RtA6 zYNN2hHX+ZVKfqL7*uL_ZUn+%jIct?@E+8&jA#S|CY{9B*zOx~H#LEBN9cI88PwT9I zN?dhRtp;m&9-lxnoZqPDS3-m$IsmxW!SS5}S^ zHC-&G=RkeherXK873|7uRM#Rs}&#~fb7peV9CjJt# z_G1D;5yD{byZ;`Q@7UO~h!Ep8L$o9bVvmzUP%xNt4xG0v%(L}bt<#iRdGb`acO`$b z5)hmm&`C=$ZE|L>Kfc)T^f39N9t=>7jJ}S3Pvnt!E5zWrtU{O3);IO5YfrzcH*zftszQ`p z85&Mpo$Vh;ny{D_C!IHpfV{L2hR6l{QX4WYFXx8sp>lYpl zS91r4kanTQen;#amU-Fx(RRqoO-`1i?8|2haEil+mh3xsz!v;21*!Mx4l!%B-6#@- zEpjWMiWgn3`G{WsjX%JA)vF>Q!74|Cfu<`;udm1jhd9aDN|rZb<9(;F@U}NEoLY^&?#&VtoY$ z)ipX4VEKOP>W*$FBODJrworyijfRlj+K@nxe1jpC6V$8SJ0Y9GZeQ2*t8AoNeQ#QK z1=G;Cb;46U2DVb%7;%Tfbfrw=zcgGVmfuW?HC0qw&XKll7#J8Jk;v8X{PV3zVX-EE zdz5?nUPi#2RMO+VB7d>tl`E@_VkZl&7K*qpBOzk`Z(_d-(lvV+URNuIt0R{-A=8Os zQa*{XvF?js?@uHv<(hgJ0B2ctKsBy$Uo4h`hE(*c+sik5LjqQ1td-cnD6?#ACNW~K zAF`f%-(|@h$dmuk1?>8YtxH6zrU-fNgHSTU0bbEY5%0PCvB{NIuV5}SXD22a({13{ z+(-+e?|^;=*+V1!@BN==UzRZh8{DZXe;7JG?kkxOrY`2LHcUM&_YM@!sto`#u|5COk_A8`Fo-!GAmF%lAb-LD22W~$y9&x z$ZE=5>o*-5vTtZB_j`B~DKa z+Swh`UH=C?M5d?G{xbm#vQs6rA6( z+QNxP=xQUsI>@e1Mo1q~-SpcSd zxH0KDGhR@;y9 zT6eF9LQh;zs`|(q{Pe1=e7pgLs5f3eT=PQe34IHK?@VW3m*9yxCog%u{)~ z&xgmv#8gM1QD&MGS2WJOA5m;CygSt)>1nV&T1?Ats@11g$r2I&xZ!KMS!rq`R=ZHk zdtGHWzYB4t(14Q-{g7k3!POG_QpdjFRY}=G$*X0_{v+%$vR?B{U@0$G!Rku9(8Ek3 z18`_jw8V)}KRcI7s@$4eV4vzzQKvWq`U63hM;+Y!12WGeI!1~|KPHa5Pu2Tzh-|2+ zJ8RpyN&lIoDnen*O$+Zq=M~Ov-#lU>@z@m2^q(Jj#1s^9z zBLz~NR8n}~i~5p|f%U$@uD!0`u%1rT#j2ZazFB|A3@D0MBK@QJ?O#KVX8d84rvbXX zIF2KI)olw~OJUQ6`$;%{wQK%N$2A za3n-~&SUw6_+#H@+rr&;eSfBB_yZ#RK&rEg%hsRT0=JuWgM8+AYE#$f1lbeRi5Z4B zE{gS%Fpgv`&6UkEt(Ss^qg$eE_}Y|wK6XBOdKwy!H(zC!LAmtzmd3Y-3+Q5EV-p3K zV?3U>PdMtYG<_~UrNGL%C1Ka+=sLq_R4w5ZN(#SLDw+pnC@PV;jdK)fe!y6Y6i!Hc zBER~xmlCsW;Vn9CUw+thH{8EOErpHhvuM7wCCzQ*i%lGt zeO08L(v%aCQa8xeKFk)M^Yn6hLuUA5qqU>|;i4UkhxDzOEEb$*nHN~!cE(0Uak`Vb zo&JexQ0y5~>1+K!gi&Ig?;({Xq2d4G(1=x6kLnDFY&bcWTe3VQ_x}yqBxP2iGe>r!vPqbCWVR-;qSW#y6b_048r2n!|{FLiOAs_WzSmY2J6-VA6WJH4~y@FJR`S4~tw`+gr|7CzEY z#p~*h-$RY@G6bVL@n%fEfu!jx%#jU^jhY%7e>4|oS7q{$48Avt6^cAuT_b&uOkKK; zkB{qXAqEXjoZHA3Pe2XQ&5LO=$8>gM!_=R^{d>+*pt>2DxSAKL+nFNpk=>^U7(HRg zNyZh3qUv}5J-(~&@>)QwHTMs<0SX+`p(BI2vYnlk>T4&mYrYi}tees2ukV~>noi{} z)X!z+lF@Z>l{N_X=54+7D5dW7_I{OqEAt}~uyNHdn_4e(W>|gomo_!ar2Gk8HlAvR zm#G~jRjy=8HbIZuH&hka@=dbhjZ=K~ymsiCgBuH=2L~bwx1a{-v!!rB7TFAZ>*L>x zAy^3_P{!0eH9sb+%fSgdwcSt~G~1ZQOC<;C=o45H)$E?nJ_l62N&6f$?Kb7*!w-na z`_qJl&r$>^@nRSTwAF6lsktmV;&L@$+C}4;a4WP=qhv<9bSkG{n7>IrzbX|co);|; zRJh!#ro9rQPtl*|XK}jns8tT}%+m#cxaNP=U&s={Yv(mH9kp1^wBkIIb}_Zp)BD8+ zO$|2fKRyUR!T*ZXgF{G+C1yLQFXikSa17$T%abVRJ9nPN03llXx33p?!GB&}TmQKo z{BM6U_`m;ed(Z#=^WOdEzwUn#&;0v)@GhFw|Nh7S)(<>%xezRL(?cMTBJG}Ya&k5u z`!NtzR%EZ__5^|g0qSZ07h!K17G>N0jUp;4D5#{MAR=AT4T=KN-7(VLNDQfzG)gxJ zLl2GQFw))K%@D%S9q;LVKhJ-^?>^prY(M$I%bB@mu5+#RtK|&?D>b4zJ5uS7al?hq zABNw@8{PW+aDifBeVx;2eOHk+d}FeXr~kkOJ=ZDlOY3M;8RDL4+&%VWagm$Wjh!e;X%d7$Ow&lLM0A$h3X-ot?b%T^j>&yG7Q3(kl zRLU>$FL;Wv8=ReSpKX}mmFP5LhulcRMJQKY8O2l@19u?;4{DhL1md4m?s_H9yNPrr)yU1Yv0Bd(nq z_hswwABtwx;(}}Y7v5K|LP89T-#?o~-og<498v0h+f|K@1Y>1yMk3`4oXXDNLH!P2;=^57F?TmxGadE zCu22{_~53!u{s4yYG_FxV!eB;Rbh72nF9%Z!Ld12S-@%0*hB$@{2Ak0^eda=-oNvd zX=#!C-!~Bm&oSE>(HJlv&W3%JO*tv}n_k8U`D86Ydt{w;D& zN$n$T1$nC8AI(e!29a}*xjy(-_=`z-Rspa_xK@|=TrS=X>0*aI2JsUgmHGMV!bz^m zlIn6e|5ESc$B&5ngCxP)@!2|#25h{#lWsgmX6bCP%I$&eOcz>|r+~Rsx3sUGx5%HJ zE@R}nlL67dFGCkb%cK(bDoy%9!bEIgug1V*b|2bIy$W$64c~EdV~a3@b>6ES+ug<` zB%|gQOP4-AQ`F#{^ImTe15Jj?&74PN*bSo2**{T_m661U%7G4Rv;IAkVJ@skJECW^ zkmQ^yFV~Bwvewq!lLG8yAdUh&_tkb=Y`@>rsioWP2BJ-`fXD#s?*M*}cI3I*UinBN z{)e2gauHAT?^NqQ8+(Nd2m2%D(F%p9j(dOP=XKA!F~bd&=g$WK(JDkGm&VI}QGOEn zv`NIY{n(lcLNfJJGZXCK?!R;m0MM(;`8^f%s_GY|rf=Wu@^eaqf*!~wa#og={Zypr zIgMv8?u^p28P9HQ=MYZcAIY;NxM2Z)z4U0iy?&8j7K1Ati|+}zaLL)Dg}QmCl2&lH z#%wg_Hf9EH>5ylEp|Y!1NGQ=pH`qmu&1qj^M1T(cOSP4q`n)cV z!irYUhQS891*(c!^*CMj$Wf8~boHJFHjQvTuC5GKo-!3v9ti^V3^E<~e65upkF;Q#Qv&J8b z0a7IX9QiDz?g;GONE8wfD9|pxRb`_iC-aTe_XiOBAh7w5^OzoX1z61&cn=4L@!2Vx2_xPw})~|qs)5EM?(7>1nmDrR^;4u zeON|%WNtQ7ret*zM_|j3UuZV#U*ld{z22^oSU>%?(Tvktlb$ZxK?`^Ekfe!XVj$@z z>AzS&stYM8EcHMD;eQQRY^@J*Si>w*yWKYy9@VL0`L*@g`>&562&(Xd-1NknNSylw z(-`v&7N@QZ(vm$Q$eb#RJ_=DKK}5*upp{h&g%@qXaAYT;s7w~frXivcE_f$wQTEf) zdpRRzf3A65qrG~Mb(msa8fRgXN45U2mZ^ls+D}yK=QUz)hzSE@^-EID&uI)zloxvh z_F*s%(o(C|=a$bi7DddJoX7OmR@+}mxr+75<<@7lzn$^2%J6I8nCA9WxV`cZKJI zx2Tiel-xv6)l|9JMc8%Q{g<(cQH8~{Wd1$68u2hvJThT}NeCl-$y}K+{^(4NqX0d9 zspbKZ%FWVx+$NZc@L$MsaawGXvY}IXycOH!Qjn0B!WN%KyCi0$*B91b_Fk+O0*CX! zh7(ZDxY3rBmTDsHEn9peFsa~XX zmB|Wdfg|WuIP;P{A52|EeuHdPr{{9!D%CSkq2u$xc?@agW=)-Ys-W|?O^HyiNh3~{ z%NGKN#-O$80uA=uzc`$*ZZYp+!Qr}egx%0#b3H2u2S=`;{?K$-;;%UnxYZDoh4FpPtg$LhTJ{FG z7TvVZvCJqBH*nGO=5I)B^y>bsZc7{Dz?l}Yx16TZhX}y^Rl4owv+b(&9qZaL9WXz+sGbO@rO1cL0sYrQjL|Mm+ zbUoJ>sIC!;D=9IAkYX=|q+i<&X(!tqimX#BZkRsencycJ0#p_w^u?)y_Q^t)W@&bR zI<8Harx9<~2)kzKUV*clLznE6f#{};wq?Uc=Bu6If$?Gknb7!v0UG3=2r*W9H{eBV zoaTnJtc5`jpMCIF;uB_B>*>rqqcNNOrR-#MIs|FmI&1gEt3Mfh9*o<(Gn-Avad|CN zYhvhi@&=pQ^NMkZbnKCZsQQa6PuAat%f&%A9jl0d_`VmY1Q?FXuHB4C3`n!kh!5hA_SQAjhKt zB%e~XSLrDse&3y>^_+S~h+GDzweHaZ^Csug^OUgZF%p#btA=Z{)OurDDJ;zvA#+Sk zSpNPAl4wZzsQBThjXVR{a%XmV+vecbZ0dv72#>`I=$Ju~6!YR3p*c}=-0-P#;N)0L zqOp7R+6zA}q~qAHL({3M)(TB4pFZ)}nD?(V^Qzwy=%Vqa|QvqYO>wTE6 zc$EF{)avtgzPf5I+flEjXmcFoRnKT|R2#SX+~1nsb7|#83XnUoT8_S^g0Hq#G6c*Y zppvMGl)4kue3c>4YS@1C&mXmv?7hm015UZ{SX)`T_e`7ienTxvD-s4jU#-8my3HV6 zqb;h_$0t);bE2e0(Ji4I-%LPr9P;BO%x_3)NV7@{-dXkI`j&xq>b0-96szYYW_%5v zA1D`!Cj6dj;~6J5X?T2Y8<)@WSu4sa7?a~4%Rd0i+!$}ug)P3nr&_G&TZRPM9Zz1v zHB?%!3LSwr(^<&UDKd@~L_1vFd#F|J{C;|j*~}mq*SzZh)weTWRb`46_QiS>6cTo| zd;$s4YCTR&FF z>k3)UzC;|F)+*?8l34XrIiQTKizGR6@P2gczNxK!tGK*spnW`OOgN?3v5MV~J;$u& zk_?&*N95((4(m3tx(`#!no1(jt@vEKVr=1_di(;ik@%wGiAlcd>Yx+>&0}>8c{yIk zXr#OHTz)z9;8}te6-f)kuJIDzT?UqV( z#rHHiXNnF}qE0~p9`K0C+A#uc7IxZ}aq1oSVZRge~=!3)bd7kDHZ z9tyd`8-j>>x*<{#=L$FT&5Fardc*#dN9JSots~=e8gIPG-MKf8__233B3L5p_xgH> z-~tK?BoxHUYdZr=fALWS`EG8qUK|N6*?AGB>BcCM~cTS^5?jM zX4rXvJI@`2-qEJJsMEDVPlYw%UH`IRRoPaS;O?#!Ow5fql@la!>$n=XsKZy|!pIbJ z{$FWBJZI@_*_F~0%ZhZpAzfXXCTiKI6tFJ#R0nzfrwZY&lLYl~vqakWI1b7&4=LoI zJf#qnR{0p(O}{G`hYF1E7BU+|@P8Cu5Ob^B36}F*m*?^PX?IL=8^e`oU?Wm6H=%wD zqe$$Yrv5nbMs+ySD@dfF-|0HK$EZxF<_-pcZ_-_XJD}(JivJvbze&G;ay0Y>kW<_2 zkV^)gQOr@0;jeC~D{fx;fke;3qVcWDsXrc3{u8wV29BEW zY5f|>p`;o~`fJ|3Um|-NCD6~MzPQ+TVCOOiK~AFSZ!X#9C^$am~*j$DezR#={P)i&wT zQhakDo-VIcyJ!`W% zPM@pjC~YepF4uQN#trLXnQz*#)H%NR*=g(b)}2`mGd#R+$SRifT*SY@8T%IKDX2zW z-7eb1LtJ>qi^g9rd95#rL6j4gI>2sCsIPy{*Gy@2~y^-v;XCs&4IU5#`9v%`qDXosU*N) zM%$xzwqByzpgUD|;M!#pW4QFR{52KXhDNCVP2A?6Gl~P%*Ny zlGQSI71+hg!p7EM*?((J*vk=l`uo$zPJxTO<-pqoW3Kiy(F@J)f9HI)%wvFI-JSQR zA-i7skoc#gah5!lu=a@5^=h*R*dXJy8mZ7caG6Vy<3e8T zJ2r47@aq2wkkv-9YK*{??@14+We=c!3MtKhp<;muN>9HWo#7HOT>v*FrS|9GkWF#%h>X*GxM9oRF$dcu4ud*}gf9rMjyWr*%l%P|D%^VJuxg}9?rgRH zawGE+Ua+5@z3-Ko+g9z_>pN*>#g`zXP;kJ~Reg--roe%XuI7-4i4u8iId++f-abUj zK31;hLvHDSOBviOgnzUt+u9+FB0QRbBXsM_kwf$din zt;llMj2JB!n&&6rL{oTK#(d=7 z6R#n&MI9lttFWZl;ku4q7a5$z>iT;a#&Hwl9wE5RKix>?190bREi&^}t9B$2Yx4WW#Q3-bbcA-D zL(mAd{oFiZ7l;j+pD0qs!@gyHoHSl+rGa3Y=j^%E_>BjsSJ=gRWY9#H#k|6hmqcFYI|Zm%yCdNS%Y|AzEw17`e zSCo~JaydWc5P?{Q)mR%gxNQtyolQ4ou!ef;_b?v*Xb7fWlfyDom54}UH#qDbIw`SP zeJTZ>fu3od+!e;ljt1phOe@%KC~jQ=m%ax%uc)XRPDSfcS3Mib($}YO$juiH;inYG zY0=TA%|Gudd7Z3nMVWdYea`9At##TK-&ll66Cpq5OdbKHPi1AM*i<=`*Y>(e9YWsUl^TL-B`E?!^I?07^phlx9%gJ1BE7n> zK2oi@mAIxiXx{$$a{U&4Mkf3efDFas!!Zvx8nZzbGnYe80Ttxw ziMrDUb*?^#Ig|n5DE>-v#Ofyi!DI7jZ{@Oqk#b2gB;i`|T<*dS1zsN%FxgHhqRYgl2zo7FuiU&GvWZ+a3e(QhcKWpD9(Bfu0>}Rn z>KR7Y%hI?XJGWO~K<&j2m6{~{62rIg@U5HZ4t^mVke`-HLjy{gJZ zN(%cQmPX5vI^`3wubc}7Ul?Zsw}5u--RgK3U=|>wpomI|iLs3q%>YBgU0Z9GIS?x$ zBQJlk-EM1bW%U`FGWdzk3mVoI9OPmze8|EOlc>gYut*k*1NYb`#G(t(f-sF6N0wkn{AhY+)_9|%gI^X#0QLPJBD zMwucI-i}TVzp7k9gCF)+O=tMb4R=d?618$NYDD`r6al(m&z_Bc8#$;^HgH7?cUDs~ zX+%)#&Ss>LkYfIh%3o-ooY-@*UGdaP>*$SgJb9|5+!E_a4M~*hJ-bI#R*@r7uh>`h zv^~kMqeQ7^b>a2FKH<_&`a-6`hpBVPDOBDl(sq$Ge7~Ds;KCM!SXr%ZyLZ*$MykS9 z*Ik7fhi9Zay(s_4H6Huk4Q!evE94|MyusQn1Z8uT2$wU&-~l$^EN}4wKlwiP1rLU6 z?VY`hQdv5R=&H>Y!a?bvm&ZzF^G-W=bm65HL_M8%LRby}3+J#nX6S?J1KZcaT+1q>B6R6?Hr2Aifc z;jdtW-$c=Eqet2VbJ9VBzahNV{J+$zO?F_fA;KDolo%fY$NBFoywzM%mmKtrtT(jn zYs?$i^DxTYSQlO#c}K~i{0DbWQJ#{?s{`XD@&A~@Ptgz5xc85RR%Wp}3P$OjFoijk zc^zB+9-ZD2`QLY5nz%vPyh7PAH2z5{`}-K6;4Z@DE4o%Hqn~p@+`3RMkYSelozopvF&O5P?cuT?v1-V(7=f zNKJ-NyH$M&4oC1wphVkop6Ey8C5BUc(%eWsy(4N+V>zKiv>%CMM=J+Sq|p#JiaF`a3`P502t?`?(L zSliZ*NES-}c~^8dbL+Xr7#Q+C&Q$0kRW|TnEm`moq=`<{;^dSv@T&cRt*jYeuj^g^ zvF}SKc3@1Cg0#WtI50ZE4+2otmzIi>V98^uj~fq2NX3xq=~SJArJWLp+TMt^A9Oyr zEWMqb>0aGZohswyI)<5`l|B6gk> zr5f^CpZ5p_m&_b{DkXF)U!%5e{l@&8pZoUA~##{g0rhT={qkn5O28P1580`VP!5NCkEK)U2iSrG* zg%K^|lz+MY;^^dJq%;pCSu9ZMz+bXaSPjRNm$5iu4u^Gn?2=#0yfJ;VGK0EEe*u|f z`0uA*sCi3!hAviT&jy$%EFk(Zh65jOcMl@E!;_JSKUH3i^Tl*K#bozWgO>5+Lpo6! zuG#Kw%W5mIljEPe@Xy^NkN|d0*{QC&N0B@>z4X|UPw!+ZR@-$sIpKL9J?BVpI46#s z+KD-1|LYTL-50Z z2IG`7K2?*}JAe7~UiK70@Jo8Kql4<{J#a`pQU4IpW?b{1Crbf4mC$2z%(fl`f?;8p z=#(FqVfAXt_?geE#U{4=ef3oPH9e{GBzO8!@LUh~GG4yFvec}Nci4&tv_t)WgRoE8Q*CX91)^BqKy43KM)Lgp1i7i(OGvGM>r}iDfQFN3b{AH z!a^A^#FfBjfuFP*l=Ai4$!=ocTG>d>Zn-iZ1`+rV$$yS-4G$}+vEJwwMXKj%l^aj@ zDc|rc7s$`)-_-AxxNGwiE%ElTrYl|a3DF|Yu1zT#f^c*|{}%^{k!)p&ha7q_T$VZK zMi~Z8(`}l=|17{Le;?VoB0C*?_9=?{?{NhYH0Cc0L_TlYGoV->@~p#yKFTiRT;=*hhf9^ zXP-e{2vws7u2Y6C8jj|2PMUY%x_c5~T1WgY=&e6Xv9XCBpU~lsrs2}~oEB60y6ro^ zoR8@{gLsM|`WT;R&_baB0kDHsha1JE5={ZBzZx1>ag|+VCyLiwBid_!)Ib&8Y?zSl zEcMiZ<{uI?1*UGPr*>gPO1EL8n_T6o&^)6N;=&@SJye{s$VrXuTxW- zZ3~=$_DsZO?L#IF9D4LZDN{{It_`kpj1wmG#3Nm73-^eWGlL-F>HDthEdQ1Fw;)N! zx*Nf2KrwKI$v{ipW@>DV#bse)ZC$=F-M?&@X->+(V?F1L?&}?55@C){N%-ysSfD&x z&yU?%p%Dz`&aAc&hJhg&@#QA8Fwgpt1ny2MubWo6+BV*wS-AqRhx0L+wm@Q)eiRV_ zre1@qa|h0HsQ5D8fyuM5001V;Uzs@<{7TuGt(h#dHcj*#bb+iN)l%JaMjRhYfGq_N zF}_8GeBxw}(K_2v2Sv^AkW=&I%kvi&w5=TAmin-F6#w`+|IsZ_PiJR&@L1v|pdUEq<@%Puby|88*(monM06x%eWZuSUbWucKuq~YLb?(0iU z(8g(N`|zwKwc`Vr_t$3-tgX?e{m;>J?g|RcCK7ntd75?C+ezcDsl{4|Ska8<7yD$f z=r2uD46abOVNp8jXs|Z~F_O;=nl}#LFWl;_D<=suMQIlq4nt0*N^!m5)?jo!1x3DU zlL;-PqnD$ffxnw4c{%7w@T81)FS+S?rlcb_pZs38TM;Dnm+NW)IR+Cb(t>_NJmFE> zGqvGel0kbeHnR(EQO1RzyqsCTGZJ9lEYwDIntiG{OVP`L`48BZ>gANnJa%A+7k!&w zsFvBc8e)p$xkWb4!V1~Xl%esyiK+qSZ8Z}tRiz@@B1t9DKC(R;?0c*1HEzb__KP8y z5}BRxCz(N(EK!z~lZz+lQQL{bE|?=YbZEcgX=InyKhf2|!O>_x9QiL6KsYR;g{q(T zIh4HRb6;}r`Cb26tWBgxQg`3VbKMrLgIFB!$rWgLYZ#!9zJI28?P$-+tMn$}6emYU z!Wkz{jw7mb2G33o@|(|?MZP9^{PtU1(3;}0kvs&N2S97)o_01h?~K9cI~oV+xu_HL zu+-p^%>#7?Wn(S_AF;=OX1+SdbK4sWD^Sv|=b(*n-W<#EM5S7UtxXJGwK63r)m+t8 zIc;&h$yGc6=jbrmXx_M8`x;lm+Tj<>4+8fjQsla&UUJiPjTirfF?+&(Z$c4zn=30L zrOmz)^&>w&-^&Nd`~0JR{|~NWJ@RGUbt)PV~W`KC&oLTjGkqmWC= zQp=Y`P+fAK7vMa8JNbLmh7Qf4Gx$q8!|-hV0z5OPnHL&bWzjL30ittdyO$&2Gdr1J z?(!DtHhkhFrICTwnQWgwBCA>-G<{4R&?)%_9w?--Eo&$3UpYH$f#s(cLsTX z%3c%!{oT+oR){@VTJz^mp$!5{LD1!B$Stb#u*(vyTA-LC4u{&-UvyT-%^OiWZl3CQ zQA3{dPy=O6Fnz&juIH+foS`_wfB_kgr6(Xtx?9G$xjET9{r>WxM{}kGYV3~MAGJEx z_ms^kg)VRbHQa*nyQkVP<@Z4uwwKe(qWHsxp1Cjc4FP}Ki%XX~l`(~=$D{IOBlAqm z@lS^`LN@-`U(Mhh4MWzdijDI+pGVnn^a&6oO$gck9SbtVDBlLHSca#@#_pqRLjuCU ze%z5e(1iHMCm>Z(>5Co>Ewz+q%pHok@mgKeu32z0b@qf|yPr@vv#c0N&V~GJ1Ny`Y zv)M01;Ch_EhBw##Y{dh)hZQ5#NR~*NE)in6v;5l$^yvJ=4tByiNgg^>6$p5G)0G35;~v+XS8g-DI4sPMFtypNHp|vy}t+qP`f`cwV#L zTCF$U(eH$|^cvh%pgSgrtv z%;ruj{3q6!Xf*hCa?B&|J0qsG@ zlAdm!8;z83K=SNPS6!|Vina)ahwoBA2`B^b@Hl`cO?02+g2%`7u8k1ZDUXqaQDgrM{IDLC2(*3 zMHPI!bxcg!=B2$&FfeW^|L-k3y&%GOIbFQha{SScuT8_W;W`KpVUG9p6Fb|>t6ReUUk*j!=Fmn4U7@->9`If_!b?$*_I%RdSw$wo~@=s+6in~PZk zqE~1>KPA!TrhZv%HHNu!mBG(G_0~MsznzaKjM&59&-;RY6c$^Brbi3O03NsTJ7)hu zTwnaL%^GVew+LrKxnL}MQBOdDr4V#r|IDz0tUW>{fy$H&`@%2qPu4j)MA9AB5!3(b z1CRHQM>i_sSpC4th~ZQ9haO-y(4FRSS|5@I83QukrYoFlMjrmnRCCkUS!Li_FG;je zW4Z7*c@FU2QSg*JOY?MDn#d@K>kmsgZIj1AslfFLl*ffR#|w%PWcY+Nu7l&n@)xII z!$Erld3sm4t~-y_%-UwZDzn*}#e% zkKZB5fmQaCuU4gtwHf&C(UR_06%QgEue&rEa2(F4Vu!8MKXEEa(an|5)P`sb8-8p^ zj|8Hm%f1=Jp>3Ff{h%1L6rkGG3vQWOws#ukb1gYa`+*Zk9sO-tkRjKE1#qjqo>977 z9)dBj*K29>!`fUZJWBf1IWemtGsA+*T>;IM0GXo42Ct4da!N`BmNvr@3)iRSUCn4$ zag$$?@LU_8FJB}_K#+M$uyNxrT=azmN>7i_VR0t6d~O2j;_A^j`z%*R$KiJ+u%DS{ zH`mF!^OXAW(g-_542r!w;5cP+8DEQ5gcu27tTa(efyNN^J<#+nXIR>aTc)XZ+LFb{_r#}dVMhWJF9FyXl5pd+vUhb zbV?mYQg*p8Q;!*fJg^a@IzsoX9>2qO;BSY`hmZ% zmc(70p0Ph$448|UVN@`ewz`mkVxNs@;i;ATYBXMg619=31Kzw1Q!dwL+L$BP=Cd^! zRvPNpZE!|eX%tS7{a5ZJ>_gL;8abexL;|_*^?=;<$~(8CS_a4VExf(|KS9}$Uj;N7 zC>>Fsyp|ob99K&oB+FxPNc{Z2>B)AB@s$hP;4x`e>3X%&d}cC@(UC}(=G|_d^KprI zwdZM>l+~*`?hn`yoHaStP0N7 zck{vHYEaOvTQ2%x**Ev0J7rR;t7vaP#ce{K{T@=1+eDq<=~dX8M(TTzs=SZo~4xkf{6?_Fe_>wY0=yYbB?)% zUu_$|e|^`VCTKKOCsysA85z!ZCu0{^Kmnoyz7+s$1ND5p-M?cDewsT?NJ!ZA70ONJ z81FIJ-Vp_-Qes;>t4{znObP0?(ey0uF+L$MC3s#k(9nFl66E|>IHgijO6V?^tC1Hx zVpXz2fKBcHLn;4bDAs!!m1_076dSNkqo2_V4DIc$U@H|kk$ehOP2Exg&QE9vz=`28 zaYyQbY@@rZ#EDWsE}$gkzb(5IGMkuV{=X$Y%M>&0#c%F~b8dd8*SBZXQ4C!;`#&W< zU4zQzW*Sv0QV$YphHsa8oqjlX-`(Ip;abD;&yF-)YL5sZ3Kh3kRFRWkZMI?LKaL%> z>45MX>RjW8)b@ir*Qi>=f))^+E4r66M)16wwna&p&ROM0LRI(d%(4CRa?a%Up7dL{ zUf%l)oBN2@PZdRJW4 z!*X8`=5A4`l`PCA%q$y9`6CM7{Cs8QgPIh9+M0Gl-E~9tDI$bLMWcF=+3WV_s@?#`SzV>2~*Ao(rnH@EdF7` z!nh&Xo6NSZ?Q+M98ZU%&Xq-Q4aB8ct#qr+pJNpjBRM$Wwa=rfmApbvA6yiEp;e8Sd zh6aE!cWw%M9?U|Q0(AzA~Ub+(&5sjl2t>w#x zy2oDq>|gXZFt4ZFj>?4cHIbVV&PM!jJ5(*NXhy}1rOwl6@_kFM91-8TIFm_oF|!@kYl+kv7hklaxo=aC`q&a^b|L5BdJDT$HuZ+@coF0v(OJw3>+}D zfv0tb&+G85v$I;2-tG0;b0Ck9r5R={MyLbDIS}U}_I7BO^}L4JjSHMpk}9nr2$R{M zsQERw>mmQh{}Fj`Tg|*mSBe33G4*ooo|+oBOuY~vNU5kYpXZuSX&O{~!ue+a7B}9E zr&a5;`0%d3F7z;GF=RPMLwh=z-zy&6U>VCe5)+vp*P)gzEW)AEYtndYnJ**CT~zA# zS=8a-OK^E$^)bKLyyrMI;lTckgQukOP0^KaLbCvvRYz%YS`)dDD0hh~cYHdydheO8 z#k#s6nErGRFwQ=V1Vf7haw9>5+D`Wphh6Ui4FBRA8bBmRXaal0fo6>~Ept0>*r_HhU)=^yxTe^%IQS@9szp;OAjsaDGai?E-jBgNJ#O+x*E+2gtYMJL;tAFC z5r3SFBHGhgmHd6(52_8&s~G2{Bv#u&!{7|z~( zR-YWPk}^fW5}-L`*0l2?OU0=`nv#7#jk9ts*2@*EiO|(K=8%061uP$(|HDj60#J>$ zzayq*?S=JC##NHIq1bykw>DH0sM-__Y5UVI=vzGqP%zkJr7i% zMko0U1#C>)u7lloI9gtfs~FLDFvwtgYW8Xsl$05 zeAkD?cQ;C|tunTVDQjr{d?twC6Og#>;bp^S@xCQuRno9U)_l%Zbz5pm)!`xwq+mN}@*kuYC|CI)Hio8`BegVZnZ48Bn9p zPn14-rd~_#vy(n5y#Mh*M$gkUIgR}2$o0>l)Zdt02-q(!x=2so50I86Qi_shdoPpq z7(Xb$52$4qcs0w9gTWm3D3O@|%f^)0@SN;rLZ;5nD(69V9EuOh)USN3a3c@!o`30A zg>PUNR#ZE#@!IhLcpn%r6Vywz@W(-S64Z{WT~>N8_gyr{wjS#TKl|i~dS*y}J>89^ z@qbV6x0FghqQC~Ozu02>VRhH&>Xmrclyg)b*WLDgw(pmzvTg4LcpcH3ZtlxsXCm}e z|LV>Dz7ROI2<~IU>Sfj4(iZngkFcM0A2j(Z2h5WBg_wdS{sn7}ZqnIcCf!Yr@qakZ zzZWfZR#$hs<0>AK^zhXXJf}CxO2FNDvpw0eWT>&D+a}{`cf#0pWB=?wT<_mYTxE1p z#0~J9h+goCQKH5#5!%@Zva`&K_`y#$$hHYz)0GSzwXXlN!+)=!qplPmE3Nw3e_yke z0ZbR*N4Xzqetp2r735=hS|vAWK!~`Ar$QB&82XmH&GksQyn64iyhyP@;#@ z$}1Upf5=O{*`97fPru5dajZdX8ECWx{`*37{($5eE7TQXfAzuf*8Fchd4eG3lGiaXl6SGhGX$PUsow@_(bt}AuG(ea4vS~QH5i&d|_ z#G%z8bC7NnEnsJKQuLx6dHzEPM{oo;N^qL1DsLsP#1z9VE2-k-VNmz5Xt*Vs%_nfr zL<>GvwsqUpMlt@i?U4AKsb8U@bWuspR6>#7f{X2&6uz!KnnW#&^5cO>Mg`yVGR26j z$A4MUx0G}h(A7#8eEg+`n{#|=PNPpl33MbUq%;K!+W$OC zFJ>)gYGOm`<%=Dr^4R1);RP7&X53mEnpF;}d2KF-V^(A9-uYU#}7mMMBg38L??9blirth>Yy42Ge zlB~mJ(-gp5#YtMAJI!5^;}_mP<@`qu#i69&3i=}GBz)Y*bhXa^X|3}%L+e*>mMdRe zbX$1R?q(J}hw!ygPYA09&8hR8$GK@b-LBCdP1t7K0*JG_8f5B8g^IVD{vmtc+KZipkg|Q5m^%b2OsYg)0<#M##bAbxec5x}fd;c3NI$3K^*eh0E&+ELu_sL!n3*ps=8fHd| z){wybP<_c0rN(fTau<|Iej%u@PEUTc0nEO=bCQdZV_By|5{lD}Nq=lHSevN?tMxis zTD+>$BRL2LVGnnm0sKwygq%UP-0~s-R~I^n34YSta9tLz^NWRHTb5)Y)pBP~AWUNw zzD^tbM6%z+d;aop_#=Ly&T+`d0$`{27ZzDT-rvC4Zy>q+RR~d3S=|~I7Or*?@Kje} zaq<^%-cUvAmjmR7$6`pSNMQyKQGPgnmnMpS-bD|oKm6_DL)9KE?rc({< z3+$@^9Nh-s5cX5QkuaQg*_o{M9Pc-+mz<~dR3|ukMaN{Sc6k*CyS%VP*6(i`xwzm- z_eSRx3kcK|>Qy>S>^}MPzzIDU#qv}^>LYDuSP~~JvEd491qa)FB+VP1UPUJ2?4+SV z$LOA@dGC#n#GX1YhtI2yRR^rynaAr8kAgk}3F=BR0`^#xEK2U1%QFZs^D>h?K0f+W z%#NYhnI_|HAOFx>zncNlk*+}Ji-!(-h?nUjpPv;+psv_d`L795k&_4*>n3j@>K*o& zjGggmklSlJZl}MCz~UJ$^SOXm95i!#`9Br^^+V2p{qOq?A&|G!q^UT3->ZH!726`u zzj+mTTw-EHkN_mxyl6dlcWj%#3Oz!F#x(b|nXQ)kKHow=3?eGTK&495&!o}F-WW99 z?X`@<+nzVKMe{;0RV>N0O&WZEj4{*j?*ofC7D9hTIx2rO*YWtUG^!m>y-?=}7B?TM zX4vDGcQ`m!e0|UbD-TQhWigRutQb@AHY|pVFj!09QXB9)IkiV*gNX{k#0q)Xo`}0h zM^oaek^upw8bGFVUhQRGY)q%OMx^eNsuCSNBCfrR2J1ToS_P`nvo$sD?sAM`q?X2F zQOko?t7>qNDP-J`LRxZZCu&xhW|d7Fr~}%41Q8AZ(h~phv#sHAeR&0<*F{ zFnI7;;;xSKr}VY9Qlsy1b8~O;*uXVPhk!|lDT)4X>k%F8TW+xO`tOKxf+CW6;2+Al z9IJXh9+1@F1*x`^5=`-0*Yu+kDFvwPT&uujb`=;30QIc>-Ys>D zk$lw7j@$kOrFmKHJ6Vv91&aeNQXoBMIz2u(oiKw+u4ea61M);O(E&B~8PIua?!*vp zHoDN@YREc&h57vG|J6IVJv6bcJrjK)f!ms{7YEf5Ir|@uyHJzOq$gWece7}^* zvD)svdsDf^O}9qIQtfemJVLmjZ9rt^<>jUK*-^x`r@NTAI6=7`OerRYQ2x8Y z|K=FfnAT{s;7mLstK#M7mrdE~yb%H=Wf#v)yYD=cqQ)XNWS?Vltt3LUW6KH5yH{Lc(7_yIn6dahpYd7$+c#;~!G zr!t&xjRK%3fk@ncscXdH9!`43tCRc7ecNPrO*?x&=46DyQ-mee?F!ZJ&V#O{s~bGT z$DeoR)XjGefEye?78@&*l1-QvA}ueUS=dtMCr#Y<(LX--K0*(@tgZ-^oJ>&JJt&rW z-$hg~UdRZ4@aSKn{iB7H!-bsC=3OpeAm0Z?j?UN6;D^RXV@b96K1L?|e*vS_ixTIx z^f%3y{*iw@a$ouW^~fo|0v5T1CFG(6iwFv*zvoj;#_MPi=~xyQJE!EMRa9vy+hLja z&6h7DSBKl?RuxefJhEUkzUoY;d<@*sstI!{DQ-T ziFG%&G>nWVgEEYvo1RjWz#VM76CBzf;dq#SpFbu1R(PzL!2wOxUA;#g|3((`@;aG z!iHDWi?K2Gpv-*~))UEk@iqPzb#EC~RoDKDq9{lxDh&b;`p_laARr*!T}pR%DhMdu z-LUAcMTc~EcPzTQIRky3_y1n!Iv@7=vah|@2QOK$)|_+9G4FAY`~F3e>qik1w{XDJ z!?@SVmQ4o%>UiB=|-f90gq*FdaTooh?vv>=h^I3 z2oS0jciRnodc0mzN+}dSeA!+nlC&E)BY!0S7rn3V|3?mr#U1;BeRYonpcv-OzV^+!ig#({)4(B9Ii6z0pKg5#$=NE4E2121>%Og z$X_kUn@__)dHY~!60{WeChLTZD>H|br`Xv<3A`{!NIAk@)YhJCI9zJ~fJFndJ1937 zmFwM*8Yt*DxMR}rs)DZU_Nj9LOMImA*j5F^#}|MVj4MbPxR@56q@K4LJO)dX(_X+N zswinVpwdg5XUkIpJNY2OX#o!wmdbmV`(wb-n5%cI|ExEkav-9}Mne)CYmpeGInBvN zN=BN0dF?c5!C=yd8#~ZyBs24Gi|VR3~(3n zp*(EgGR*+5LTZ;)gL`0K)q=zAJ7a7{)&$Hcm%s;R^W)DJpb4JVoDkRm0;AlJVRGxM z)=*IMt27<4f|cIzeG!*;1eN^h@_px}*_^!SeurK5#mI^InHsA|anfzhji*;Rms=wa zeol1AqlU{o@IF!rNBu)ywPmFYYUO(yE7+ERPJm~(b+Ocx%d82&1s4bNpr-;B?8Ks( zaAD)ILK`6=XHjeIU>+~>&^lYw7L__0r(8i zlV;0I%CfRppZ+Kr3MEXMe@b;sy9=Vw5szvM^1SR#sMG;h*u`=%(@B zs~@#Rm;Hxwgn3PSzZ;!=T+r2uq{C`D&Ee6UMw`gN#qbMg;e5US{#ozc{;<@%OUx`( zn^>o;OhVWp-o6m?S4#$`Y^)>ZtaTB6H>|q%55y5swS4bGOGtQg6rO0#!*X39M9_Y8 z?=JmvyhbBha_*|Cs>VXOY-eBr>xJ8w8x)<^?6-g{(^Z6m+#fa&8!nufpaD>jtU#q= zvmQtbH3IMorBzo^gaqzSgaQtTr)0 zBhcVAn9Z~JnHqno2>VkY8zl0M1RLN2O)=L573GaYK(ZO(M^;?Zke8wACDdF>YY5rs zw9LUbEHxh+9$Lu+WU$h5#cf4e`dIODMQ`_(HtOWJJ(UDCfq0yoK&og&?B4HN4n>zU zcT$mj;S*-V&Q>1dH)IVrx$^0K{h2B6_n9v5#uT!pzx0Z&WH8*S-R@4b`Jxd}8*6v% zX>fw)Z7$uQ$lKpNExIR~j?;zZ?|uBizbGlK_a@3Hgc4Ximh$L=A0)`6qbzwaVYiwg z4qJUHQ=ow$>>F=y_MTv}UC%&_TO&p-Hg;c3@RFSZ0FwXTSd0kD$f3{0-%;=aF`tXs z1;0VNfMmyr;iA%vhe1xgZ8&lqHzc@TFS>W?g;K+ku-rkPiG*&z_?u zxwzlm0d>ruNJy;a>U5V+bt_cm{=?pYJIP5&VPs$^1sYtOfb#H_?E5YLO~))3`~3%% z3XW3eK-g&<2FK4$@#0CDuFH`%SLr$gi~ay<_q}dv=Ge&gKU#2xGS3b^qM`{SKmwnU z0PwJ2pmV@rpXd6eaOU^c&x*wjgHA-%O&w}WK*tCq@9Az?Nm1@PC(atF1^1%B32Q*h zKwE7nh%|h&DX9SU!wxG~z@0M1rtLJNf#d@Yki3k`t;$b94>PY5zas5N2q?%H^Aj_+ zlw0^4O>hv?D%SN(-eB-=(#n&P2$S;~=#`WIW$6{Bs}!$fF&9_`to@2C(XHe)Ai^VHX#|?|GKNXwvTGM_dHhF5MA; zYZdBRyyfJdB*^SrJDQb>3rAFO&Uw!E4|3GYbctv!MR0qeb zUv5~^V=?ing`m~mO7KD~}%&?el08GsglJ zC8<}c!*|O=bM1b^&P}+Kknff24~iP!Z6z-`!#$99A3h6rz|~zH ztlaw~&#&O=!{J}!o9)@HD)yrzr0+3)^RT?9>!}|>7eMXV33>Dz-T3=c1Bhxah1TXC zt;=q$3T#v+ilVMUH7}jj#1RB6VtpNSoeQeYMeH3VK9x;D7Oi$gy__ z^eQ}i-GZNhcIt6Kr)aR$5A=*6;k|{Wmi^*d=+Qi1@6o)ldQ^{|$8#B4v44urTtHT^ z6Ob3g0ksWa8!sk6J$Q=+>wb&LH9%LovwwAe0n>s6OATdyO~ArhC6=B06)zLU`_^K0 zwBH@tuZWh;Xb)FE0GI4{q{{b(#EW^W%k{A+BiYKkmfiuZI;z=Pith`UY45C)C-iYk zeUn!dUu^X(kn!Kj6&k>Wp!_pIKE$r8i6~~J)|u-R+QY}j8z33HmJK7v!bqmUagJ~F zh);JNOo*nX9-+VME?&R~K@`D+HDb(II?OU8 z>;=zGrRC)tz&P=DI#SNE;M=P3;t4_L>4d0H0(&#b-koe5MxZQSDT z3Qsnwc;NwUhC_!U6s7)SrGDg-=-AK^f2#Av!kP7&01G&nY}CI59B}pr`?9%Jai=iZ zo@TsLwu-e-n`a31mfN`^;s^t=g-PqSs!=mk^kpZr#{Hbq?W|v|jsEMx7m3KSnM)PS>Y%?wAjxR^#3J;|9trcm#-lu4Ajhd^Y-msJ1CR4f7RHtu!*+K>^)BZzMS|lP? zp80W$AqK@n9A8~M5*`SPZPwznsBx97vW{wWi)4%?#G|VC{_CXxYVy|0-x%iK9G=Fqx4l&35^=y?KdWg`w3UQO$}w{m#2+kz0DmTk7O)eiW;Z5Px=mRW|t^jFhLq{{#hT zHoup;j}*Wt+i3f?1?ox`1}Ay1dl%2#z+NtOJB@hDsSCw@Hm_(++Q(AE(N>Q7r#JEY zBppA9zo485k)u}53XMUV=Hzk4N)K(c32d~Mta2TKj9g9w6ov_l}ioSt2rhn%tB$t)AoKQOxcpQuNGa?oxL~hzX)(cqE zR4^h3)G|@oSQth6U2(?vU@&8&plEg$YmFf%g&2?0E5lZ7u*#pPkt-mavx~V|9 zf!W+dzFcb8(;tlG6tB>Ij)vy_m^u62;h!=8r`M98T5x!f|MC@K`!VU+PB#9iGHrA+ zr;X<$uJc@lA|BV)PhRr}=SOZh<8T3tnKbI*@E0D_)`- z1qkltHWVr)YG`liepBdNt$pv^mKeyf2aqd#@^JrVTu`LWQ;e6(Ap(;tlvW+g$~V8X zczPD<-l9L*3=;IiwoWo9jd~i7|b_S%aCUtU@tBs!$H7*Lc9FIx4AH#Q3p-A43k?rg1>0#wt%;$QELI8)o z`14Y5UmSFB`;;LzK)V^FZIbSGZ^v9*uJaeFyeWY)7D!#WZ*Otwg7Dl|u1>YF1f!p` zm`-mkFXxVIPCIO{0X5b~x6UK|--H14*2U2oXyB6101rz5&q;7pvl38=R83eOBIDyX zW@z)w>@o1BGPtZ|t(tw){02=_E(TGSyIU{+cf^SPgZlIxMKNZuoCJaUKw>)z_=^F# z%)K#-4FF}l-bPyx5}c>gZ?{i$29<1Hdug1}Y^U8CzNcQlFg<9;WA;5aXX`CMX{wPr zj%p0(A=1N`c#Oh{#b<t!w)q z8G(>O?rXXE^W$Gd5Y8Zq3lx<4<8hZ{&|_E!dnUlHv;e#?n}(Re5o04$Kvu(NHo82; z-f!ewp#sDhP%j4P&-3$SUPO7+{Doo_AR7dL0iCNyod<(J{~;kVGDn(n;o7jjy~0DI z;U$0B^_3DHqx%-x!T?~2Ndq`3d0ons)Stdc&(+@~?PA_1Cro^cG+!WqH^QK8+SZgS zpYp*5=wPB$I=y+nDyX`|i{&9@GnC6>J`HR#SZG$w$@cpajAnwy1pH^(1W1`xsp zxGgbFKoksaC`LHANy+XX@4o}eaZbr%F`-FV_~c!aUAw1aq!Xg%w9aFAmMVldEe&E$xv*1P>Nm!5pjRG zBp`XkbRFq$AXb{ILn;n%xqFafgBL*FU~7%XYItTiPWfbmvC6$AQ;j7*MZ8$0=WLhr z^hZFI$L9eS7erxITveMmA0BF&kA>2*Zu&w(fa{du9q{Hjx3+e@QX(%WNwML65gWIO z5!RnLBO>w>Jk2;PuC4y*TDeL^?&7vgV}schCW=Fr^EZOP=jzVA`7LFU>ZQY>n2n`v z$l9&-_#1Ej)R9eK;&CMTSx2V~DE|9lQn}qtiD!HVz-tyIG?k8dKUQ9u+e(G9tKtVG zgZUQSN8j2qzPny%tOQkDvF{rR+YbkC8(rP$j3foFMMy7F=RE2ju>Mcf0-GhrrjZ`s zpJp4sj>bAZ3OZh2U^1>$Gj?#=?uqa%b?Nw0N17IdO*+HS%&R>LA=Wj1!8 z7Meim>-$kdT^Y8QHc#W%Zr`(gAasXPpP_3rygjl#YGMmWB1WD;8qUlnQ|4fr(k1Z< z(9PKG5MntST!s%de8f*f5sahW(+e);hS>GPqrf5{1Mc6a>iq6rpsr5X}_mTkJ zw9)0d9dtcTWND+-W+pFY=bP7f*SC;GBBB(C+lV|dr<&T@C_>Y+BMsm)(Iz95Oo z3L>a^paF2nVIa2=iQO^a1$xkFWh&+Y0k3lXU7yMVwLx;f7hwK-?CpRqgv;3;qv2pk z)#N0v`+Y?WWN0Z}G$-!(lod#&-&UAz#?b3HeS-!>J{HFF28`(x@mB#t01b0kxhzHu zmgJ~dBXjP*d4k0K!mN89cf*PvmV@D_-|1@;ypa(F#xuo(!vUrJrOiashQs&1lUy2C zbV{RX8H6$<2wtJF_$09SL`?Sccc1*zEDxGzkm_!h?yetGDx{7D1^$faX#*4~AY1ZT zWp@T@edWj;7Z9cLeRfCZHWvbjsphlg3VqY3fc|Xz_F@q*KXIDM(uD^!MIqK*M2$3e zDyEBnM4oQfj?e@wMG;y16!Wi1Bm0d9+#+Cchl@r$oF)Mtg*sP6q2$VLXgX)bcxN zsi0IbEIK{IDf{Ae(##$mXwm`k>jx4QUH#1!YZ=ezHbuwae7&2_gGv~Z`Ycyz83U01 zEAyWL>?A-Z4()*zHSpB)tpLXL(v)m{P1TT5U*d~U@nhbL+_79aX+s?oF??@%sc$@O z9zj7tQMgL^s%q8NDUx|+bGfk)28OqFs;79{I+Y}LEe;!B(0(OWq12yXH4M{G&~w+H)2Q!dAq*BYXIGhCey0t+(t>Z828$rz_n zP(nBy4#r2F2B6j|ZTa4+yPRdW7C}CD7(f`l2?!hLXILAhM?W!eF3$w<%usn`Yh z0K1-mh^cB9#cZ|4S9DJCzhL( zGC`KzSq`kh!i9eeeglL@4VM>&qvZ;K5KSuXKBLQ^Q4=zPg52f_EK)pf54|cXo)^H6 zsW(_gk#3I`1Oqwzd3c}3yEEZ2<561UC5Bknt$Y2tvqoIdX`sBgn3FpJX7eVi z6a6Y26o2_!00EELY}|DTjaTLps^#8)9)wO70MY2UdFoH?0+R0w2OI+lM%RNt~D$7NO?}TAjy4U`!wOH203Da35Cjo=X~~xRyep&~h@$>Ye<2fG!|M%vY)9X>*!y zc!be)dp6=Ai_TTADU8Hl0qX0lhWx2&x{fi4^)0EloJR6OLcl`v`PQffh86E<+t}RP z+%eFT-{r6?lF2jI7xK|V0>yK{FNSze6wWM;pHda>5oSrf$;6>2Ca&a5UmG(S2QulE zT(j@#M6YINxq(U$NqwE;oj7=W4WEPC)fs;g*@Fev7in%mUxwJ7(Zd#sE|Gv0PdpZ8 z98?#3(~M5K>@Q_L5~|J$2dO2))}Zp7H?cjC*yU8LIukSp$eDl_FP>^JcLmyaCUeDB zC|CSIg<$}A0sme6K6uG&&QYh~Xl|_4btsKF6Sn{>V0^=@@ z^3GfM9d@Tffe~U{+%&)w)tqiw%+$n2BHX^rTCa|-{+rO^9%yIKT}J~Vhq+ zuCnMKXrSeb7cWp#xQ@=wBt=BN1dBmrT^ya{FglMjUDL^bmQ~o0mnSC5LKrqq>k(0l zh(=e-a4m+#N*YHWQ^ePMz4P`W4bNHJ5%Nl1C9t5t5Cu8Gn0~aSvkPL@NjbpqEVQ>r z4Wsu+#K8@`^?UqWNI>1xw844W4@_eRU~w2`VQyTJDVfNDO{Y1y?!>hrxAZTiFUj)Z ztoJX#Sb%V>2=%!YxQc+KyU8{(PslSot-~CDTo;@+JK=4)!16*h|xd-`|YS4 zK-W1UXUtWH*x(aKX9ZlXSN)ErDrj)}8@*2!H*1|Y)rC|kfBScMsD7(`)|YkjW=kg6 z0`3%&-BAYQc0f7Q@oI0jM$!W;*I>bZ>KWqk!+G=}Yc~RNCJ#0u5AXke{R`#;Km1!? zdw3u9-^w8P|9gPc{`b}Nn-2ERPr$$E-}nEQKL7(78p~`!K*Z!rd3;(TCKUeV@{rUam#NaA3iV6o-bnK}|&`~ZM}XJWG5+ba${LkLj-Hdb2y3z#vmG4wrP0)qrhU=q>= z#FN$&6B3^AEwTmqJn$U(U5LE_c#cNH-~Cs*`0o*D`aJ?!wI1-~*KEL_8sXqgaaoyM zj=U)3wZ`V7CXY5s?{Y0z@5*?_#51LxNhcZq4Y0sFznqv zpd<#?HS)I^DIt&k{CxzDMdrxn#;EMeC+S0-aNTr39jKcT_`V<`mz9;_{`sRO^b|R< zZseg^Dc04o*(SuSY0QLV;>M0|PSdh=0GH>$z=Qjx_m+ zGdJ*G0$_cpwD*5}1iEP=MZJArKmPqaO>%!f^HeR+hl62w@{>a&L`mY%|NYI!tXSL9 zF1T)rr|{%i;MvpI`tr}QrH~T!hr39@+rNnb|GfL(f#AP_$p8M?a6$G&F^6Nf9?hWd za=g8LZP$S}=6de2qG+MHIoM6g=Zx)GRhW*gwFL7X9{?|q->+c75UcTed@Fm!oyK${ z1ut$EcCvGOed~`za3qk=a3LLMbBOFg;oV#V9c^vyms1^3^Lg^i*ZBnnjanCF;-sJ; zC{L+?F_|-F9M~?J*GJp61CNM?Pk$t6VuHV^r>omq3;Y6OLYhQ#^tLNc#yKm^eg^*3 zhny_OShZ+5T1^cv+~1i{TszdiHx5WloRi{>;81<~aB7ZNPP;LDEiqpfp5>^>AIx6y zjh~en@$QgYBUJpdo4;5cP>fFto8%3aqj-~b!ZaT^riEm1|LWQ*v0S)FMbp{bSu0aU zR8Qa||4o&kV4optW%}+SR)RR`LEYWaZ7W(7W4+AU=0^32T@O=iyd(tc*bJV_<3akO z)sTrYvK!)YlPgWWjmVs>l6O}3l=nH&EGrF7!FMsk$!sLZ_y0J1Z(t+HNh<$}usj%i zrPI-vKeEYUq3W@IRWfyxg|;iYOd*EWp#RRas}`O z;{_`0uv6%C`R->EllYLA_Z=4gXgf2EM&0;xE@zoe01P})Czy9vU+aFm`&gJPD;56Q z6}s2~z$WYcv39_jk4UT0oA(Zn2%GcEPIevWRIM7SelxO=h@5`E2Wm%GzKk>FX1t#V zLn`u=fS0+$l`jz|JG-3Wr{jj>vu&iq!(P{{W6lu+M_^oLZ7aWe;;>L!{vpH8(W70Q zifVf_BI11BiIMt*P+{2k!Eg>(nj&~DO^;C#Nha$v;QC+jW8F9Oj<=s3!Tig~ovV#n zrmLzZOIEaGa^!()k43{7WkJi#e%(T*#&x8}J+ot{WrdIcx+|;0nfI}Qk+ZOH)_{KB z;dxQEH2LtzNJA{+_Gs6Ne35KkFBVS~$IJQ~;C_z;uFE@WF{-Tk$6_SI|pNuLub`+iy+5WwJQs$UVGvz0{ zNo2@{+IajafCxrZ*PkPWceJH zGwDgEa?NOvk!>1|V{~=o!^(N!La@z85y>SLqa59Sda~fjW(dk8`sbN!)Yr;{zFHw` zm@ZS&;#(X@MoDEeovtMs%~si73*4q3l3}uvm0gbP!KOGZgF1x#Dr)1U1p%n2{*XoE z*VVzwz^L(Qk-tapwI*I*q)>WlFa3UEzn0sf$U;)$M3Dwfc$a?PW&6|=>FI|W-0ygAZff<;2V%5h$M+2#rlvUSP+eu+4itYFgU9>f=fXWbbSz*k+aW_@extXVkOZ+mf7oXBi+ zqXhV#o!A3A`($_enfZB5_514M$MAVV-xnI)cXJaHZ#$CRDKwhX6Ur5LIgE^Q%9T~2 z0|ssqM7zH(ZG_T88-%__3qktRD$||2#N<7K*G|}2uW}|lSVLYm@&X0np1(XP9i~o)u;a`=k%vWX*#+M{z zoJU^~<00mDnQ-bM2eF#cGsOOci3n+cf~i+{<1!Uw7Jtfd8?>vIeb+O! z0PsrkP)%u9b!w7$fNIqddI7n*gGUH{b1R$2V#a%W;Wf5hsjQ;bc)xf5pmPV;WaEj= zpolmVWEg(e;Vzb#X`~=v_{N|h&9M(7Tze!>X51${^WX^&MPfUiz)Aqr&jqXcua#EY z;FXILQ;h>VF}JOo0tN#$yOG@X&X3MH`8zrOQawDDUAbljqx;ZqE&@#R7ZhczpU~rf zElaFj+Z>DBe(~Kq*%fDX@r|w>78Av%5EqX-gf2Pj=87)e%r_-$>aq`|EV;W*FVCTk zOBi&{+WQQQmMk|$PRh?s)fSd%VK~m~Tl(ksWj#rBd?$b9*K*Z!9_emwPgiLZH_mIn zF}oc7?)};s>=Tbza>MG^s!3F{>9E@xl+-PsNHgC`+n7m`%QEIaO+d$IFt0ZqyOTDZ zvSlt4XV>Q~869VW!h*mYsGuNmdY0s{sPSGewp13jyeANLD7LF9h~ z1*O@_8e@pi)!OZk71leR4)o0>`aH*D;j!Y1!EFBgURspg%@s)4*hj{?IHxAar#c?o zMD*d?>^V=Ce<6744dzP5Q6a&M79Ouvb8zGI^rT~)MNlT1a!#1z+?abWj#LCWA1|KiKQ~TE3q$abm|@oT%7OQ zAl7RmkL;vL@bJuklA-v-%b@X$)~sx`f0G@Kc3ZUWPIz8@j4!utp+geF=7w7kxee9X z)il&$O_Q*_FCusDRi{W29_*ke$*6W^@g#jeA4H)~EV+*+|D>uz;wpANT5}k2K-ub} z`mZs|YX3xqtQw5mWkOvzl;3JxvEsMq?*^OQfLrn^0Tm{bB3@2N3=SQp zVWB_v0I%^95RexK3Fo|S+6m3VWISsjis$0eUMO^UzByIDZyNM?74qbH?@GTPbzfXm zWwd@ov$5gVmt-+gmUsD3ph$&@>XU%PgjeBIfu3=vz=j(g78aJ2)bA&krX|t+{J0?p zBZF3>p?iLwn45-%h1Q2B(RQJvn=AK%CE(#czzw{rr#IQgt^HB}QFL^Tn}oMME5Y}+ z^`MR+I?f8=wGLH@ml{dVEo>aQ_Ik6hL%?euI@=+r!TQ%-g%&DnTEv*!Yy%Nl%*;*f z+t(5zn=Ec|hIokjMAc`VBq(Sd#*3tnK8RB0`Jtrzu?q zp3YU*E}Wj8o0xWB>dV^<;&l{9PbN(oB6m}VqzvZT zaL0Y{pm}T4=fw%#A+^seW%#vrwFd>+X4fBq?qo<3`rqKFpr`I=gKI7i|I#`+f@B*C-J#2#PtP6iaiQP+!y? z?$a?OrJ~h0hzaZ@Ji^s{E$zcSK7nx$2`OmxiqOH1go#dm-?IqD&7K$5c#u&fh7Odg znIXkp6S-btI*QQ|+w6A|q`I4zrilvY2;%9~d(I82U*@vtK^m>%P$0#O@wnSfqrinZ?LbDRt!L>} z^YOqot&ix4Nt|MZu}VvghFQ;RQv{|m{K>aEmtR!5K~m@Rw1f!9t}GWkmM6P8@k(Wz zV?SQYg2tZ{zz{a+)Hp7=wg?4!sNZyiwjjnsO$l(6VS~-L4~db?NNr7ZAPzeR6_rhI zb}H4lsp(jzMxUx(p=Nc2LmVCNz2n*Jeuso3M6hQZYz(rV^mR-~#V6Lgte?%hU5z|R zthF84ET>VcC@C$C^85uH+)s(vbPooXFkVn%__3JH0GPa3QODEW$;xV}#z*K{u{--j zA5;tm=G`b_@HvWuHM4Z2GIiDq&tAL$#Y>|yta5V~`+ac{$xLT0-p1&5iIcO#0tL?X z#Wm0x1({JKd>(KS)&Q;{S+sMb#ucOQY)sXu1tD5)+!kQj73fd+v$-8WB$fjqiUDFb z+>geLmHWlp=y|b-QekL`TR0BKevZR!INg){(&#Z6GZpK=UnH;6pSs$pRGB>k( zeJDG1I#a?Vo&=q89GIn*>LilMbZ;D6+HEjj06Wy+mmT=68xkYrgKOzN5il7QeCze* z^w-|6=Sph?zAK-DnPTVBm{2BOA z&e5;CH*dh~tR)5ALz%csV1q9Ev9lM7G>~|#C)6$gB|KhRuulE4uxR3^1RuPZgB(K7u+vH6$7^J zH7i&9pbL3Qygyzm{Hf4N?+Mzu4UYb$*N@QSb#qZQS~Ya6cc#c-z$s@N7Lqll)_&A- zqI9F}eX^6CluT8ZKn`R&N2pIl81Fz>jZr7%x)~IRBi)aC*>c+H%6zG)3^p;41h)f* z+aYacGZS{jGp6}hBSNBRBkof)=avlf!3Lyv%{6+4C>qv0uHvFMtwcGC4JXW3lo_J8 zkmBrltxoPYoARwVp`EZ;9+-c{NwfnJQqi5fWyz+;PF9A(-da94~^JJe%#q=pX;|dbn7H`YNIt##VEi+6A}_)__c$rJJgP?=~7=cw{1QjAZGIl#ap`*TW+!X9^o zxAbt1XFx!o9D0|i7W}86xLEC}7M%Jf{Qp|R?i6Xyru=*}+!awCe{oXQ0ofOp<1F?J z)d}GGRu9GR*(eo^10yB6vY@4 zH`>|RvN~x}?1@NpMy+?*KAKZgQlG7xw%tiQ*Kn}Vh>Z=^cbY171Jei?oKenjvN`PV zY+Nj9(93)|DK!qfa>vZuook@n=MNClF+I5rK}VDzeOJH3Yr6bRV_Qz{_4V__ko^_G z?{n;Ku3ELUw}}aJ)R8hv=aLBfsfHF6OGY zdGWrim`8n%XRE2jF09ma{!_Aln{l2(Sf`7v=_CDBKBuZZhj-MB_({~^8gJujy1Kb? zEg=NYcz>{)MbxnR#3(;l>vJMPpM$Boke(W6N7Sw}fRH*tnm@BS*|PR2_qOlB2nMsA z5WV@iK1oW6vD+I8E9wJ|KfWPKt|HYZN&^GE`6}nV`Q5zBty7NO#CWAbEu>IQ4vy+! zUL#HyVE`tXnxIV#Woeh>_W3C6qgid)U3#DiuT^8ar#z`~NEYnAX0FMZ?2w)gP4BxI zzC`CR!*X$SiTH$XI-e}&>~y$ewfU@akS6pI5H|68@QnjJ&)h}1!_K<`5hVJceskLo z0^feMm33s4X!1N_vb8%e6_+v)F5o=NG&(a?iwsR#ThXevI(}jMm*AHtD>xmP^E>>x zbCq{eVu6}PeVlyiwjbM?@MNc2dX(NM9z?zVveZHq^E*$~o z5!zVF8;bA;3FPm1gPd3mR0G${Y7}!c&#zz!Odm}TV=QDD{n#k>XKLM;HLh}1pdw}C z8qh*D+0k}Mllct2ER$#fb4~6n`CQfVUCl1?<5vbx9U}@6-*XEY@`#2<3R|qk zk#S)k@kz&kjRrgCr67g-q1lo98|{gHxEgk-z~Gsd&w z&?FLaTf3qZdCGVD3wmqGT>A5pG-?oW+VsFe#l-gA+LHySO#xpKm9ZD|y?RoXmUyJ7 z1W-!igcuphr>dpFoIy7+f&lbF7awty0^FuhXP4LVA(jq>$RRP=3sqP(FVI>##aHSd zQjlgvv&d=hY6~nJB;+h-e8(NxFZ1@7xmGR4^5Vu#=lQZzQcx_l$7Oqa+sDbt=^mJN zgcQA&wQOBhbTU)-RNFfi%GuJF9Mb7iI%#{pzVr4rMIjdK)jbm`-BGq)FR*C#X%zsC za70)vAQ)mTAt^FFv;J@_!QSW)D`$*C`0Z2-%F~nw+(fLQL zeoPIymBz5oLRep3<8wl!qUZ1~%ZDS77+!iuqX-nU z_NVXr`>0A}&KZYg!2^*SL$hH8TabNBsg&h$z@cF;ovx@vn?UWp=J^n|UOWu3(PIZG zt*eT(m#srxr*#klx1qFm{M%2M%PLDC7jzWFg%`C16w@ip7BeLSeJ0o&uODl$j2M;S zeu(`@%tP=--@pKtr<6NtTd#6eVqOtaWawj)jXwKR zC?04HlXLP0g|+w1jD#G80_Ekfa$ydKt55cd`VdOyJozFMU=}%oidL`Cd*XX$o)6+l zUrnINgoUVu)zzdX#Tp#>JN3Exo5#7bzxK3B@NSz_WL<;}Sg%S}bQzG3%BOc?K9wY~ zw7XtvC<@`3*;-e729XKus~2hJJ$mYG+biPl7li7vS_{BPs^&Id1Wk*9zR%go5hO5z z#a=aY{Ec3ez1S1L#Y6__I3mMv8;h-Rph9XN;uf>1h_5uw^jXR_RQ}-TEEu&>tjzIR zfztTfWzx=kPKUHu?D{2*iHCup|4-!eBKb&qVpz%;X1b6qY&6E$Kun{FoUrY)RMB7ch zU$jqEp9d3A?uqDnn=`|~G-I!-X_6lm7TvmcZQ@4TzAk`1^(cBX7qlCp}5tdxU;d5PhQ`IBev`Z+|WnIQ@Jo{4jr!&dr`f9JSVA<*q*dtU9>hkz*!i z1!OQYcf!ahJ+l$abTqnTU*`{SaAgdqD~5bS0^+M~k*e=tUJ=5B!I^sbUg2U<)wR0S z{3>OVIuOym-k<9^I@j5s4c4VcwJDw;+=Ad9f%C4vZwyD(3iI)&L9tSzE-3ZVRQl- zBxZLaNLFo9LOmJGseKX<*=vL!Q1<9QGx6oaOx(y{T&p-f#jDKd1nqv#T4yGssV?1y zsx543@1PnWmE*BJ?R3RiYT=((8_l08E*g;jt{BU#mK~%%)L_lr1jYuJo#$zcR3`YG zJzCA-FFB?e@t)hC1zFK+`}1>=Gtp)G|o%A9uNkzklr0I)=ZhZOtK{{PkjQeheXQahM9O^lu_lVa;ZBb7!vR6I<7 zo%A#30_PKyr{}gA!bXYF(EBm}ESiypMi+r;T0dvQlyZgXY4*V)gBi(Nu-5G_)P_39 z%i!m;a30Smnv{RBexo$~C$K&w1jNw;$-~N1OlD&$`sS%Gt?u_AWgR(-S~;q%x13R3 zub0yUg>;@Sh}vdjxLUgO*mF-i5QNlz4e?Q;HKVWdg)2b?4ZEPmC5|sU8FkILHBnY;4$EIVc zO8o`_{{1d*kfbXkH<)<#qn5Qwfb@o^WV8(xiJ8js?Hy)bd)s&Hil*O-6i-ABQHQyk z(0d!PrO}91bVM7L7Mmp_AuVVK*^ERcCYO#1>-Sqoc$6fNix4S4Rje~iva)iULM#K0^hZb(FJl(=H~3mRvM52Lp4Q4%dRL?a}89>GV zxe#SGK{F%_L>&;KBIVo^{F;VKs%ls3rs9zv65=+9yqk7&Uy?tK)=?0qGw|);jj7Vq3zGd6VEX0C z0vM-RcizsaH{w&tQ92e7n@p(ikjRaYODpsYR66Ly29oNX0okDY!dLHv8{ZrEzMGzZ z*yy|lw`bYbhFNL&p{%*Rp_KI*i;zP$=&K81%d3g=P$ zDign%mnI=`li#>X8n6$0Vy*Vj*JJLWFi@k^&8QSOLmP%zCQTvXw z`h%${5cc=-xWr6o`*06UY$syD_gBeR?V@z~bqtzF1>!jdmKL9-RxL;p#e&#Q-9@L*k-s10zBXI}_>rG2D zzPGm86!l||1U4ZvR4`=8=DZZL!?L-AU86b?IoWfor{GZr?4?O}qIh6ThxejL)4DOJ zl7w3|M+Z7VpV48{lcV~(wN^@JrCqc*Y&rL{xE!QS4i~$_5ThSuqAAsIcAq6P5>_=a z!o8OpKa;zvktNnUL!cmu&^2Q-3J^{6yv>`#g}YJHe8ZR|%MZHY_qEk>ngq#-x7osz z;OrxCz%6=96Gu6p?08tXIl%4BDxJGVH86?{K95a{U|#vZ5t# z;m6ISzm$=+fA+Z5eE9s7r6kLbC2s;Nm7cf>KF%l7D7%p`mD7fEAvy&I4x z!V(khE{DCBysmdA8@xgMXtH&|Q%=5`mfSb#aUt!G7g5*0@1T2Cm}^jR>V+~1@Q3tcT34QD5 z(6;!Xh3m19pmtn1C-TSKM%kP;S&QT=i8$ZfH8$cRy(&WD+Ta$Gp`YhjK}B;h83g{6 zmk}p!yefj;n~j_3!=l{R(K>BT7D5M6p9}53;+)L|Qq=J+%xxqT7k!?{lVaQVPsB_P ze5Is6tv$CTAb5uI=pa9PucsoHM#zORY89=Yz>GZ!+w-v=Z{uMK{M+1W=VT&QCG7A7 zM%=dTb8T@}=37*@^rx)Ahj5&7}+;WDhizPKgzt&!*IHXfjtno+CU@wek*P zhUikN??x)rop_V{1k(cU02Qc9zy%!QBbL-5r7?L4w=h3^usCOM<%$?!ny$x9#M; z_uKDo)oyL=KU=l^#}rV*%%|_z zfYf=Pejcw$(MxfO&a($nHvPKxdDNQ*Cm2USgm;+7GHLOy?cu>n*X$fc!q^uiFqVEe zRti=rpRug;h_E!18BJLdCd{7>#ku+TlTonLC&+T25ZChDxYp)j@2WC`QGM)mPKiXS zyBMO!0mAjr%ZErk>Tdr7ee=TW5N;lHivb}*Iu2jPrfRQeevW}7Q+>q~(qwoY2Z>*e zHb^5lIF=MX{h1|U9l$I>&jgQ34=JrG&IN%RW~v}n9LmgnWj^U`u~-Ez1~}>Mbvy+R zbNB67Ej@`EK(YO+2`=k3MfvIy`l4M5_GEwNcp~HoxxP=LLep}|Wg{t=(&SiLn#GAo zt~RPyHLPa*7qj>k*9TX2os5@pACaYzF8vch;r*%Cc@bQ@0V;@nghLkw?NaznE`&^(-Dj{7QuvXJ@d zYj5epTf+Bkt1W)e%zbVtjv2@_lvf(7I#&Op+`=LEK9c)rc)Z&-9OsOt$kyM=P9jU` zt-x8f(AS3rqt9Uv-|fV{4>?+CFbHrz?zq&53=iqh2o*$qtSzND{A;rqmg0UGsh5kc z|2lh!?3ah>%TSG*Ci=TYWD@$SI?TKVtd8GT^A|zTlmr6$jMf&m_Jp#t-6>Gn$WK-l zb3>IBc9H3?2Q}n3wa_Io#yI(Wd0F$q=xtJaSCipwXQ2=q-t8SUKR3BSErVl7CFwFi zYc64HXJmn;-*}-ha&NX@S_PzU&_+gRZc=h&(PMH1X0UreAB zZ-8O@nUVgc)a)sA@h`(`N0r8dik{N2(AlbDgEj+-j%Fi0-|uT2{T&>*a;q8b8HRkuTHOH|9I7 zIoi3ILuE+$HOvU&GELHkQ?>h?H`hm(l24iyk0VU|wnDhB8arf2aMI+bya~;0gzi82 z>u&Ot2;Xb?GJgHD#8jaJOAP7g?(9<4=S*ML4~9JMCuy2OE{mAh$VI}c8t2hDCZ~|) zNn9^UO3CZz_jz)99wWJqGB)X(r|LCb2~N}7jJ)C|%v?6*Szia%25*mhR&IQYIg|b8 zo>VgTfCzq6S%@L_H}RIFJ^Fmh%(plct2%a1b3AKt;t(oD-?h4Om~S0rIl1_(lFRjI z%4QdHB@4@GLi0#J_287XPM>eiy}Hd;LP{I1Of=@8@!x{b3B30@WWw2}agFxkmx-%3 z;Ax$dw57K-EI_IKBZ0YJ{FeLIQaI%&%M0rGdJ#y-){1lg{_;f_j2pdjO&`f1HBwB>I0d2cf z(^`Kf)CS@DJ*I|X3E{uxy1BK5WRBk6Fn0Tt%pV5_I<`0kmBfj`TnA#-GQE#&7)DYd2YA<@)}!BSqxbxGg?Zm8FETl|B2Gv z(D(NC0!OW@)&lx37m%hNf-n*o4FT7x>q^v?yU$a=8UZ|XHeCrkZYNKRw(0EjB&~xI z<8J=?W z?P7uvRAhB!PN<#>jv9ecjm$(GW%E!(kes?@XHI*?m zXyF*a@F2#&0PGzYl7A=PDE&vaRIteJ`}*hjB=v8{a^P3d->nw@ zIq)$95Y+Yf#fi5qNU=lRH4wQJx!9H#$D|i5?cZfRYv@IY(EH06lgqnW3baY^qk$S% z2Aj*Zxho}fO^mDd;xn@yU$EHj0a53$n0Y4~Q(Qj}Ml0Eq!M+VHc!9yU)s+o1Bcq-N z<@}EO>x934ksF+o3^=5g`F@w8G~N0FjV+3;BH~9WJ^bi;Vb-Dm1bkay%}hlWzs%mT zu?i^k8(I{UvB@`@l2=-QSH5_%LL~>{@tvL~n6z1yi(N^;ruwRv&Zej)kWT9YUIW8; zyD+@Q=SiDT>AU=<#WTcM;;XxQ7OkMd^h9o1{A(u93(uW>%990S2OD;MWx?LNId7C4 zr6)Hg9y}HF)E^=?c4yKlJ5v^0-g&NbERXgh4C6>o=Ex_;v6wmn+2y0(XLbuKBQCgB z3a+w)`_^(*1O)g>TXQQ*YG$oJF8di!tg1LUMWoc?5hbws^b1&KXSN2C_Jm1g1$DF= zK@BCjr>1K;xRpn{hMf9~WsD@Km7*d(f}~Mg_!w`i#L*S3ZEPpZCs2PWh|r1Ln4^-# zVPddLcLrM)_78&o3KWyhhF#RgFKH*TxV*Qra#9f`x!rq7h)a;bB1CgWyLZhhu-5D`3gb>^QOv;JQ};!I>%Sf(}9)2Ry}Jyc5>HiS!I&@BvSWnP3l-znx3E* z4E9qjYgoyLqbc;6*Rkj%kP%5I?mka^ugk^uaM2JW%BzihC^fyrC$q{i^8|OqyU5d{ zz$blVARvWjb>xmAoykaMNflSsQ0#503@Zhu-lD*CiRMj@LOL#98Y#C$1WP|NCBu|3 zt@Xgovd`m5Y;!6W9hRv>>h-8Ly2A2qzw(-B1eRR7SAg%QeCCNCgH})PETO`LMm2~4^V0<#RoNLy}$kS=sf>L8A>`Qf}ikn3GDVL z&U%ah4Tb2>H6PbjI!pMo84K6D4C8gW^|?NZ1lVy~aB9cvl%}LG%(}`J?O!+TQzXdH z5=q68ST~UD-2C)jD%G8%6RJzy@)%x>7XRz}G|5B+G7gnwu)bE|)OLMrK%)m;OfvNn zN7sdKoy@#iaefFHPQRcV)Y_|2J;#812x#}jQYL#jwaBK=eR%l1n!(34#@P6Ke$6+* z&kbMzVJdgZl{B`4?tgR#F~xr5`bbQ~FqfV)xzp%GJAr2T{;i4Xm)-gKa;)b!;>%5n z%MUdwR8FztR_NOdI*Dx3&ON$)GnyxI?34wpS&h^W`qMJZB+S9czb=f;>1u8+1W$)7 z2z}kgit75*kESDk#7JL7KD=E{FQ|#z!;=neJ;K~67E}6ABQ!2OpA=s&ER)xXPq*E5 ztVGxKJa0e-C0|!Xjg+0Ops}*Jq=wgF5Ui3UN#7qLM(&^{{=vr(rfAsrGUgfw4BqBZr;*gzF@MX^V z>=?r#>l7wpRE12`G@GEy980fEGi+;NYi(OhCS-|9ML?0Y+KGwe5<~FfV>pC^M#v&7 z-S>M7)JajwSnGq&YGOfkXQTH0_u%{$B%ddlaU0@+E*$BL-QBheU=L_4O<-UTtY4XC zi?KC2?HmPFjn*185ZXa5nJu4;#ZKNgITY%cjMw2OiGNBfnV!hz@pu@1V8aNP^l}NN? zF>)i*HY7jI?GNm9#3b@@vQd9zh?!8;dDO+nTTEBTNusM_I@mUc_Ja>o*={SpE-(Ns zlm!K%`KA>0t>%(jT2w^(v)h}k$0H5w&8v6%r72eU9Tl29AxLAUaZ~s8$RqRhjVB4W2a~tTxG*(aQfh1Qo+XGe z!TbU}bdu@GT`)`5>p+$;+P}6lE7SDZG%z=59BbFOa(AZ4V0m}Vx(%@8VJxpuG&5vG z_Y3@=9OV8eC%E3tm69+km1JAHKp&=vHI=L`-mV)*Kg4O+&!U=}Sr-9~<@Q@IdsC9{ z=;OXDu@qg(NLc+8UmHY3rtnjNr6&dS|@ZNqy1{I+>& z1Z>DOn-b`C)Up%JOHxO?)E53KD-5H57BYM&z{+c`scIz?YcH=p72JW;7uyb9m53nS zTG>cQacZwNiCD{4E=XybPCKxolO!NyC8uQA99=4re07lJj9@~LC}hMYT3WtXuU=^Io<%AMgE&!c~2+DWm2^lPA(U5dJt!uC*_cXQF`5 zi=j%ZJEeQzVWlIQ&&cDxo(iU8d7+-J zyzK&a%8pnCY#uMZd2x*gk%L@0p2sTZDW!Su1uoMCaGN$i?0>4zWb@g*yO_fDtQ$Xa z1vllr>}vUZcP4MLKie81^b#(E&%TZo3z(nc;^g%Mm`c;C#m2kFU^`pY-GPk*Ad&UpO3Kb>Jg$ z+H+t-^qnW(8OCbdmDsac;#IJu-)ddVRuEN;FBvjUG_vA9vRtN6a_7+C_6-yA#>MHy z(Kvy2h&L%%>Jis}n}sCxyZKIor(GUdieTk1!uyV9$7Dw=iSL#vS7|}EPi`wh&t|vTw3iIb@rU~24ddwjy6+gOyBhX@$^J;5qsyR42yQ$dk zrH~0o;-kKA1C2m!&8=)AfRrPLx%PAVgyiAv%@wG!D?YRN47c5K1`xX)q^Q3{r}KD= zDMM}~8QNvoPg`yE3Xw&)zg4%2#GZvkf>Oam3ipIQ9| z8A{f2_f2G{1gM_Te?l@-m9*u;;iYC$aQs}dkKaJm$YI3-PXj%dOdelaYar{+8e~Q) zjGe&q(EF35yQ`tzBSb7q)T?fLzM$mv935jdUWVg7sLS%XB|uC5@bD9R`wqQC`mh6M zj;3tIap39$g*f=hXWxe0%(%S2(iPu#o;X*F@G?VZKNtppZw*4voy@oLzGG2{mEGrK z9vX}Ebw+0{&axuv9I9GGwxo*kHd^ILryh79672@>W)5U4eIb{IDLIY~i0fyTHk1`F z^eR@gd~NYcU%-zJ;YVa4Bp7jKDp-L&<%@)vliZqr$(5EfdtRfS4#75eDNZjCS`nfl zWE@(WjZhw-*yWR zZnEXR+0hJrAU9eI2y$kj(0yIlum|4i4%F7*E?bJX<>d$ZBuEkPL)1eYSqXL!kD+}0^cgP)|DiA;qF1-Jju(c$MG;D1Sg)PWwJ{xug!0C@bA zDXRrkVU>d{XQ&H54eWABQ<_;?0vVIvJm{7S3CGF$9*kM&PBZFrms~d#W^q{Tb2Kb; zcTc4`el5T<1@7pmWU#t4{>}7AIsqzu(POVdYHbGp>aU4;ZG==TFl|^!a30*v+eS_6 z0|)2C>Aze+Yn}o^i%U_z%uSli6~m|-Eyj7XTSLpYDu-r!6(h4RJ}l7X_3ea)VQJzj zH|NYj2rIXSrPN+*ZK;Z10a3f6WZMq|_|cEA19q%TUor2S<;`?cKk$FHax$`$F&1=l zAJGIzs9~J_dIaY)N7G1sD(?$=oCA+kh6$xsh8dl7L@1@6vxW%cf`UG6;Y39#w$|rF zDUbn~;2ZYZvoT>~x3;1z5yQXg+?%h)Id{kPv_e-cArM__inV#QRMqyT87C@EK}=w? zEtcymO(M?>fazjZJV;P^Y~0`Xaa1X8t^W9U{}Uc#le%HaMfB>cKx+LQwa;rtcp&#g zb?h0~uBKx{VPzkm>8pB_o3!s~S$j8^r&tzCt{>a;ZvN6;=l0oq!KJK2QlaaHBs1%D zSSVI5qX5KP;L$nowSzN^W-S!i(OkNRMcjiI9JvR5-tRWL|D1XN6ZWM2`Rf9}{W5d? zSD7&2V~{qfTr#C$ltW9IzL%yODDTAp;#MUI(Rx&@WfuW(v=7VK)mt}(Wq)uVg=C~) zwHwMao)Q1*jH05TsIP7g=hkcu(x13H5S83}=4NK=@G-x-y1oLh;-xXu4c1iD5b;|a zZo0H7PW{-G{86|hgco02+i-Jf$1s&25EER(i4%U#iCHix%mSV>HfvAGrQ*|2Pyaj% z1Oij>)GzGctEzz&4^vK$HgW>sp-S#>pz8_V#+K&P`fY*~R3SEM*(}iNjr4YC*qWgP zB}~B~r^^E{?y8vSNh^${qzZi#IM^jvx&t5W9Uwm2#o1W6JenJwU(F|369r;O0w$1Q zL#KRT*SXs7>A;D)^<-Op_6IiG#o&3RqW;+6Uk;XGJO^MQv=5n z8?Gm|GG?S?zA11cRIkk(ZDUyXymNKv{vIxR=gQ``oxiu%4N)($ zu(izo*td>+Pmu5)GA#*ByS;ib7M<7vtvcbLADE@%@#+7JTnIjBkNU9k^w_dyZhSr+ zD_EfAS?)+nNJIj#UF{?e?VlbaY$3Ib_lKNGcIGK#0-^qB$3Ptm_ds!k^6YzF&tNfW zU?B?RyU%-<3)B}xe))t1fY`2K(_aNq(*ofV|dujaVOac|#-*E+fNL=ZwiHFqai z4{d06(EaE{RHas4sqKAT*mpBB?T=x2gO%2DfEK6S;oT_VH2rx8@p6De`=X1FbAx#3 zCdxHL;iVa3C0yg1G=B-o8I~3`mR#Iac?jPFS!j;1&A2sBaVYY{603qQnQ={^cQvdZ zX-p06j>v7-ZGhIQfpw^P};oiEeEdmhG9PK!d5iHLqtYJj88W zx|T@xuvGFSI>WN0M7@W;2&UYcudi1;dlfOvzNy!Rdg&p>pV9VWycM$7qmaaHcM?7k zzS}<>9hp}NyMHQbp@nU2TZkuwt8SLZk-st(3w7bs+dL6%r<=^Hj8N+Q`Sbeti;Ydm zP!+Cj2b?00aQv0E83JBs^f!JQ`8MN+9PXXvB$`*_c^$-K~_YV@IZLcNk*luTHL0bxig6*PF%Kz z=)wO=pSz#t^j^5=GAtYOV~Mbyrg@ZG^+qxSQ|0eSqJd398T!d5M62v;gR{QL>=Y1frF2)^R@N-sZk^%NEFf6cEE ztn`-^*0nuuVCl&3a7vO^v69u{7mX+r?HV?Y(h|v}d4?bGax`zrb}Cc&qWpsE0)9bX z$CYLF2}KR<*Q>YcD$mr>vx;Ao49ki=BY?%P9Vr!SY=m1JJ|9%JaUv7ebWb;42{)bqA@PDcg{P{=VzQehToDH<5Oh&{TgI?wRN$L`pZtF9U%je$zag<#uJNx&Ea{27Vx02dguw8 zlec3OG3xghRDf~?$U02GUd2#lXr;VWTqU>oYH|6Fx{#-ce$36`iB~NNz|aIp{kTY!;<#vChdGAWVI6@h}8I zo??a$KMP=4x<<#uhee2iVzsp#7gg+A9f?Tnb;Y+O6`51`0J{M!(~GbL`_*lqG%cKQDNbJ>{?yPwNX+O|*RdMdtZ9R_Uiw?0tYXoO z+MO9z7%yb=b_L|o)lq58$fh`nAD3_6jni~MB}w?JWuQtbtqM}u-Be*vkw+}2!;h`i zIzFr0LgT-97c|h3!V4Lgud%QK;)#hA_SCa$pKibVj#WNI8EMVah7%cwJT z&u21~qe{wdfP4SOV|C^s>8wnv>5jid!p6F`rGyF~ijsF7fim>pw|QFWw6xisMr>83}3z)F?+eAg?~ z%_>b%dcUTV=IToj+qZFWP@)|!!J{y{*wNF&YLKN!+QYq z7J)(zNFX$FI`sfb@UKa1y6PUX@*z!PiE!P4=m~xX5|oM`hh~ImFvI23#H#k3`S?(I zJ*0$e{pJ`%H94n_bcG#&>~LNzrtqhawum~aM?wazf9C@B+Q z`%kg?Yj>o+?<}9iZ7kdw{QkVap+-V(-e9t_3}_ZN$b~VP%5{5M*bn;=^-{Zx08wdhIyX}*D;j}nH+#dI*ysaun&zAagZ*sY&{EyX;}D$= z=$e0+rk)(t!P{|tJ)1Zw26;m6`{Py{!tl9DleuTYa)x;g_=6|^Wjj$8} zjnZ;KPjftz4dm0xivwLV?b-S=d8e_8XC_1D`g+u{l4xW$sM0xXe3ls`rxU?d>yAVf zQr4bI;(V_^5laS(^VQS#kMNe8#ai5cdB0K}+h)^obn9mGGL(2_b<^Tp%72Z=vS-M? z8`ETVPCMoP>3Pp{uo)cfWdQ?ottaiu=Aj_SK^IuMAUf*TL=hCSoKw@Jyyf4Jo$r)C zs!I*zOc=*I=Rq#61mxZg8@|;sx9A8iqwDi zUH{WI5Za<2&Wb_MS&UI{J)CpPcx?kAkY}8l%I+YOJJgPiohKPs64+0jtE$HJE5%Bb zwT0qbKk>7Fc7t8g-fwPhuNSJ;jvpD#b3G{O>!|7I$uGA`n`}k>FbZ`^~{SMU9;x^*P~;vX3_v5pxB!^te8rf1C+d^s7AT z%3z{&f#8clx)aGZuu9a07x3T#+aZ7mxl8W5hKA^cJPcKgytN!YO5D7k^Tl<@T9dqZ z6)7`zbUdvpo9q+pbLn+tI>*ahyI-i#9gGh2en0!HCl}}Yiv?Xle{Ojyf0E?DCY}b9 zpkQ)0b_X&4T|u4F2Q2?L2WMn6Ex|EyE;Vt0d8H|VnF@<>D<^O#F{h&|!5&X6 zIJ>gh_bMvyXlFZ+tq>eWM4DjjLA!E*r>djp z0Fv=-$o_U)E1T{Vu#>gp{=S|m)Ba9G6=dQ$XA2sAQPCI-4^QWjMPvj2m7U69W4Wu~ zW4lQ!`Vr=gqC#L)g=E{Q1hzF5&BMS+> z2SbEUzbR4fl_t5;@=X2t!L(EOD=B<-t<3UFW;@fF$=8)3@JVvj*WC+a=zg+~LyP^W z`tkm*%*4cc+bef6c5Jm0Z3f9y$UFROG;1%3UV2I5-6(S`nRmh2`uu$~f&3s{`)kJT z@AgpRIml~L<)2;MQ=p0_Z#`fY9Zh#n14)iNEO7pWA#JGuQ)%(|S?mt~ zhBXb-42dq5c0gj5%TroPMCm5d(ZJ{7EtnRtFaT;!PF||s!nZ*268#DePxq%e8_6lV zYZ8(3H7;=#v!&jS-n-!u7_`D0>#N$z&YKU4gi5s4H8qN)L-^Q%9BdsG!9G8X#t{yY zV|+m!iyc9j$R`#iZvz)^B7IOYBEL{c_L+mh=66lI@jF z3zV?Xa`rHm=Lk;#Q_Ny=3cRiN`sz8}x+yXSI&&Mqh*v+G2P7FrCLTz%kDt$tj`JjD zu0r(=yEhySL^*A3z0aYI#{T&+$->Smw_*4i@*UVE){%9zGmhn?uZ70fjl{JuyuA;X zYgWPzMlVb4FS*I%`lt*)czIcwXjO=TpmOiMP;qkVO%Z=z?zefS5ZT8R zPuhcYmCgKF7V?oqf3^W-r5ievyFqA>YoRJhgnVfOFOB(#uV$zHxaquhN|@Oli|A7s zo?Lw5xl69YB^4DL#vu_OIr3=bLuF9xdHzt+h`d#`-IixZQbWgTEDhJhw6-87EB|=> zRB3ME!n7~`!5s>(Vo?w#n1+*-bH*9cxkzT#5DZ*BR5H%M{ylYu9HS%$mCcGTfU0m7 zNThx*#mJ6O?q>z8Xwajy)IliRE4j`tN-Dc;NAk3OryX4v4y5Vsxa)~Ir}naNMEdMm z<(Cn}@qA>eb8xy$YxqT&tZh?Un;YXp85S0tcVunpv9wBLfm_9g9PmI$*Pbq$yRBfi zw^x`?(;=BN>LV(pxgX}C5kj?C@EB5Q2$0zdM+mzfgT2`w*m2LN9!97ykFH9l&8x>LjYeUX1LgP0sXpI#AE+wK2aXLE$lED+yAn6~j8 z!X>bX651Wefo$>>WbbY*bDAWW0$^Oomle(dYBeauOV4t?R#4Q}k-J?7RK@^rN1#dl z+^!>+X8U1_DhMT%@B`vY&dH7TzAi8%TQs;gajZKTh>V(oBJH~bq1!9L1z1}wqPYr1 zlQ1T4-w3h9mHoAC3?u=PUlVFoA74=wf~3u#dECB`HaS%a#?owqY*1HvPKeTrYw5*R zc61Dkj1NSjt#60H3gpmS0QMG&lld)U$Ehrfu>&Ck1=v~OK=l5kKOtxP@-2M!M@&}p znuQnIi8s6ii-1U>t#)kKU(w?z;(RS{Fs1401qhhvO5Jj%7xZK%3#fR43w2JStBHMZ z#-j0^e7YRi-Gu3iVV_7tadw6<#gl?r!TD+GNC<9b+jb?>!4KE*B6@W-Y(Vh&O;?nB z?;m{<8sYNL93SoTK+qAv-Wk=)&z<{?0TqmwzFP8U4r>MIvRb4r&-*oOIjFz5fw&=*F zr~yn$#v3{pY1Mu68f|a;k@zo>Dtn~oQ&V$*{Y(auNfAMT==u`6UdbNO86lh1<`|3R zeJT%;CFHl6`fBA*M2-@I?D$la9QUIGJ$u*-TE>1TJZU5P`$h}Dbm$pij~MO~pcbh1 zq*YQ8%q@^_x5Jd)u+A$u+ljuy)Z&J?Z@Uh&QKd5c9&k-|%v&yr{Hhj%pyoL?{|<_s=+H zl{)-V|BPdo)a*bcyx8|e!r@=|r@y@)#Z^Q~S8irUzlzoA8IK+S>mYD!eUqY$m&$1m z_gf+Vml#3N9D{`s0}?qvU<5$NE!3nJ#9t#k7}xLp_sTYJ{=+u;zjR94nm+v$XZsoK z>Rj%c7&P1$|C@jTKD0qa`^I;FL}ihIPaU+FNT=tjIf#%!1E5XMUyCFhb@J+xw`_mj zih%DZKCpi16@Y^_i*$wFLo!^ZTsV87b7fKxe1l$B*UiW(?2^1U>t35kFf(U%Y=v zA73JjG(zCdz(xD>zTYnZkY{;ISMa-;E^r*zMXLm;Fg|Gn+@qs%mFJXyrWJx;TX@c` z2`WM(aCJt*`N1?pv_}8@19v&6Wa~qA;*)oHzfbeEZ(VFb%|8PStmeYGJlb%4fk15! z5_*T8b^2nSUuZl$5*G1l>ebmO@9e)915}tI-Xonu#GW(o%822uA20A(#jg+gvxMpX z8G#c+DlaQSJ?+ZGKi>>||GWS3JpLXL@cO?aq>i^L-RxZ*&i2hr(3yn`WNmTbCn)h! z+2j>GZ+KF%^s>{<*DO6f5x-O6jV)#~pB}ijj`8<*cSoR&`Yl!ebJBQU0hY~=vGwNF z%25n`f^1sD%oWY8c zLwAs409r|Odv`np5gy?P^wfJc@yN~i_mJ*tr0@|EM?0TeZg%Z`h7>S>tfGpA$a&R` zwQQ!RCehA0!I?yHJU$ES4Z!}~J6r`o6a_P~Esv$$s&KTLw#O@^CO;7oC}=>&vWWf# z$8f3VEVo%fk69=gxJ<>qih%|M95lc8u7~^=Awz=8OU~w6Ek<5aNDGLe z>@IQr!38QUpPzDAs=2;!S>qWJ39h=zMgpjxiBKa8FF@x4Ocnpo8QWUg(1uXEh2~8& zX<7MnFRF6^0Z?g62`9z@n^?$FcC=i|)5O9m zn`GhVo-?+y(`5unk}R|Ohm{@C+gb`x7c!J59Bvt`6s6GWe1s%9VkR%KThq8K}R>5s(KJ?Y~?Aa>w~EVeXd zqEiL47k>pI9iT=km<_aUO47IG@=-h&s zcTqtpKHxLl;OHV}&4~{~$$3$rC-OYm}dLdz8g(tvp`s+}RU?(U`lJe#J>}gj{ z9YM?e_6k5@((Q2@0=2k-s1k7C{o^h3x_vI*6@fbkM@Qyw_MIR5#!vSsg`~^%L*q|q z3oMD4zYUVzw~cW2#3+FeCF-+tya4tgS!#ojKYYmqoD~tT*gBsk*k%{cU1dNiEW3 zrFvXFjMy2XXmSP@9&>fPP= z4O@<6ljkJtl5i~4s@4E8gv(v{n|B6WU(SX1Uc5UjtN9~fINk`IA6sg?+Zu6C^Q12- zq{V^xK6!7TMKj(Hn3bEI&ZM=bO^BV?B9-~#kXObWhD#6QHoBg9a{j#mf1(98M1wepgWENCosh^9q6^om z0wx-rQQk%AS@ zCB#`bNwU%Gzpgy%a2B95VU$b9{P;3gKS15{?fyQT8^-G8Aa3X&a%#Nn_d5CmKTvh1 z+fpvvrJJV(EsRm+{!44}-wOo`_)kDVU$oWH%=j&y^UR4Im|y@@j_HxFs;J4cMxlz# zFZZ2(F>d+6C=VAeHMf&2rxaJO#@}Vbg!YWwc*DOLl|8$TtL#>-v>Yvzn3c~%Sxvlv z^_!?FC`Wb9gQ|5Z-gM17-p2ZX;T8ZO|AWUxjvduKTgx9F6&?+l zL)*G;F4vx`aW-^s4{!efuNojM!DA?qAt;2n7McaPYx5GISeZ^tgSAA0?f+U}kxGBZ zXN{ZY!r#8ev@g_7#jiNfsg}~xU!0>~z+b%%?gZx~a~NT;FJOxOi?pLCvvhHC)>kpR z`;3u+*r%;D6g489O&G8nNzXE+5?i{u8JT#c$d>-%@g^-Q%<7!y{xQ!T1rvl~(j>YB z^Rajzs)4VH3P5?f=rus}Oee_&a%k4IT?0r{r=Of0C1oYK52KiLjQE(iR#s;EI(kd6 z1t~_}Q>sg(0hhYe6bB!&!d;7LSEG72)dR z&M|LrXK+|}-hRxzODVeazQnQSmYSAQk5ObJa5b$SN>{sW{jPXI3&aN^e(h8~@ z=RhI+d<|S&6Y5}`&COIP0^wL()uNM!*xGvoA)kuYe$A`{%EfJCT1O6yO^E$ZHf;I|Lnqk#@ zrZqR%@<%(Q_p!Jm%AKeFT2%}NTg~?an7d6s_hjd}2k2QtC&LJmoZ0Swh^J5)n`u)N z5nTvaSlDhqRx;@8&Yi|HyDi%hRlOLwviu{sApCg!4G{K?@98LzN9dDu-+KrGm7IOG z90N)KRr&Az=FS9={ZS17{pp8(prs-=N^Aa`e-I>s{aAa!@A@cz9{`X1?~e%o33XBb zzi|NkdwOp$0i>G>f&A0%>JGxe!NG#S0$|1rqE^y>-u254CGS7F(*bbg-{U_o)c&@!?iaKFtof4^+^)>8b!X3 z613=mx((z{&N2WzvyGh~V~*3U;R z0H(LzWNI`xI6dN%4k$}z&v*lsaJF-OwOSQQ`BGm8_E0D(K&l+22ch_-+y)m4cx;Vx3*a~f#oabh7 zS>5kHT?H)MD_RC&tGg!4_RteZFfFz&h`>&YF)E_8eK*oUPk*lp%p96V?7@OBh z4L?_jxveFO4Lh(ErJ{N>g(AFy@Kd^B(CQCPo@T zZUOZUWp}0qC6t{MWPMcuuQ}N}VvquuN+UiYakJ2WHk?s~-!vRBVuYw%fNqWFf}yvP zoskCKn7c*b8+lONfvJtMw7h1N`m$Nv6$-q%i z<>uRlteG0xyJy@bB~whui<{EL8vtztfOteB*bn1l@h3o37}^CUb#ZkN_B5aNGj(%4 z$-o#=m(t1l{%D>xo1#uc<2&ixJ?ntaXhr z<%9;&0J*Z51+v14@+EBEh1Il|Z+ZX(Di7h2$s6BDALem&kDNuSH=-WIM4srqiIb5_ zcXT~ZeNTv-8#TTThM#kl|_NJ`4d z#zx%=Jd31+={XFrexNRV3A$xmWmYqg5)q9Vz|X~4Hz?9gBL`@VXfIze(+_hCo~ykR zoNX|n+C%h0^uDMnSfu~H}?47-zvYxf(nscpI zsE%(&2bUIrE0pba^8C}2>769Gf1e8o0gf+GTHEOu>ZYW52sv!&saBa#u5FPnSC1W` zDE};e_d9uxDEix{ssQB@)m5Rkn0ZAsklmUBR<>S3+Q5C9FlRJ#B*gp(FN*2jWe>RU zt}O(}^U|)^d{Bga#O9i!w1U`(+&T}p~wERx@#P`g%|5MUbT zd~BwK#6l@hD>vvtLSgPM`Qm8;g8W|&>>s_Vf6AACaeI9^EHvV}H!`^%m}`rV6>+wJ zsyIS%@yGl}>Rs#i!X^AHb9D*%0Pfen7zF+yo4)%$WA^K}F#{4l-7d~caaqAb!L9fVZdx`G+<<0lr(ZXgs^HSeZdFP|_)HqY4OVHezhSg~hT>kbtn7 zhy!d{ISP&Sekf}dCNC+zcF~0yQ2_A!Y(hOgF)=v;63XW|J(UFqW#t|!O;zTcmgqYx z7yE0kb5QtzO@&?eW&nXOEh|t=8c>uN(B%#n9-(I*09XJ(l@IZo?DR!4X&Z&ZFXQ+B zX9xQJUv%OHzt#D5MU_Xr5$6u$6z}R!Ol)+u?@C=>i*J7C5nvi&P`pw4)`+j7qQ=R= z^(7tipDp?N&fw%^Lv?lh`Rl(axR<&rs?>!YL^cywALsLAf$e6##VefZR=&Sp4*IhR zP7@Xw|8vWB>TW0W0QosQ>>JGwBm-bu|NPC5kbmi!V;|U7?k)fTlhK@1WhQVU+6gv! z80ClIZ zxjBKtK(VhdKlHn7<@@tL7XZafLeeem>`!e$m(SzK{^v8-Yx}|gGReU_5ws0~ z?bWm^Aft#l*dxEWD5`IhVDm(e8`vUJ?jag%Q6JkEzZJ$Bb5T;^0v7=?j=o_6bU+f| zNcErlaS=dx|2*yWwX6zQD6w!z+j41Pg^uQy`7?v3R5d201Fw6UG`Vht;qC8n-wR(m zX?@EqW+cxR&w{2Que^IsW}f{|@N(`PU8-tcd^fH0JRt2!?~(37d0q!ZI_du_nnL#$ z@;n*PgaK^lw}9Repz%AuKE0s8p)+;QE{CiPtLs-O^=Ja zae+Sk^z@XGk#XY5>!tdF%pj|_@1kUf7|{U7ftgD{r&lBdPs@~@IOFD{sd*UfVmi@K zyFStja7@ePNWTVzfmR}o+k`GW2BxoX{Bz)4#S)ihsx%g!l<_Bf1-anf5Tz#o20Nkc zDhJ~~Bq5J^_5t^>ET=h&;0Hu4YHDf#(fhq_%z1yKMz_XY@XAy_8|1L&!v`)9NLCiM z)T!09_|=IoGqrL4b4Y}M4dl|BH;<`gPwSV?K}?KZb>|7&4Op%HJPnDU6Zjqpg~SzT zYN-Om)5Vv(qbT2Lv`>Y{X88T`3<-zuv_{bH!~U2_n|B(JEnbf0xCd++C*twpU_Z@2 z*IgulzT;#yCh(b=)1HXI?v=fKVY?`7~Pv)Y6L zXg(qVKJzyo7sK`S4br7!HCL+J$bezpYS?GLn`3TfmJxgy!k;FtnIdIgYG4VoceOV< zmdhm8m6vBK<#hMTV3(I-J}S;oweVTidBc@4E$r2YOXa=$?pku#cJ|Dm6GFILFn(`e zi~ATuXA#B*<&NuK=czDqHWLv&Zr2^eotzZM_b8AZwVW=t@Ere8h>2p6yTb)?@|4%X zRpe;N5(@XO zmc$H7ReG$f+%-_87^<}gkar2C>IRD=|yjF2Azc1 zWkNP;l-a(MGVrV)KSpMUlo?eyOebo9VMNB}kL9Op{U3il-Bh!(B93ZFPmPVSNANly zE^TzJ+hl)eA?#TP1mL~IXYR#5b^2P2X|yA^F~>Bm5gkVDhOa5hWD!q~YLdLSCxGfg zF#N(e4);A^yD8zXr7-*VY$*!rq(p9Xb@~9k)3xt9td>YBk5Cf!Ms-v_JnQM}?R8qh z)sRtbMMQ@C9kppqO-(T}F>-3A-|b@p1?I-Z?Gu9nl8Hjh?g3t|{6kqF|d(*X5u1lspW=Cn&8 zMu#R&sFZ`FV>ExT2|ow9g0622sQ=#Zj9o)R16XTNS!-`L7U7je^<6u*6ce$mI((7~L(-3eAQK!^E=3xCsH4kxj zhD zZ-yyzCn-{4nn_tF*XaEG{lGKd4yRDyY)?}!FL-uG640Sk|9)bc7|5ZgI()AZkFk(n zVS|wl@tKL_yOR62xSgF@n@9qx)(;i-qTP+aExT+BllW~59UZeVWpETr<7rPZ-hQpQ z&JtN~#X`H?fcbeTi7(&N3NXpq+B>+KVr1|>i5up(6e>O!44HeY_8woHE*rGTb~JaV zkLh3f_)p2z{&4rK6~HX>^YZzwvmI&st?VJ?2#eDV`*c9F3|KH~yp%f8_jsOIK*ToL zfYa$eaWKZ{rv>s*5|lu^o{RBLUeI^IaG6b zA82W5f!~fxs?)N0(lCje^BJe{m)n}DfC`0~);ZINd2Q`bSF30gJJh5mWk3!SNKLz^ zYULdFI7b(SG+F;LOU}_<1$-H?$+(-JzrT)2^ChRTF@reLACxDE-r6!VpMAd{ec_)Ay}iAW1qZVG%Q>C- z+}vYD#l`x(3DMD-&0c-g7c~5%RJwUWN26>qgHIP`k7RBqs1})6S-~n&-Qo^8{nU9i z3e=&G1x09?x3KI=ak@H&0+zNWQ5KvFxKR0jMC1ewKi1V&OGrqh)~H|#n*+R`IaZdI zVq40a`~LW2=LBw_5plj$M?bxXb1RbV*E7?r4;ZIZO=rl=Ys%98()8Kks(PND5aFbw z5`i#Cb!u(zKI?VrJdWuN7IiV>glB$mn!3%e$*p}DnO`FcZ&k1;aB_A1{4^I=+5NWG zd2W7t`%XMaN{SDJ@Bww^OI>F%;C6n`kkGT8Ul_d`Xay@a78XjG`F59g>8(UG=(D#` z*-)20Z=Qpb?Y=4pOh;p*EcYILw%t(CWV60zhtA=*RF)gzh=E&H~fomh!Vt=dGED{J=-NG zo`2J7)Z%u7bL3$D4M7CXm9ZT(|J$;_0S8Zg&C$Uje|{&{4OqEde*XTob#=Ou!tWTF z37rtj(jtUiJu@^tFfg!xJMytCemMsQLMVgcg(3hCBl0b?oE435q-BmeLt|1Dlib6j z1D6TK8@tvRk zgs8f3#q?J?-}2_9YzYWP0IaZ$u4v-{UugpU%4^o3(<0!sX(kQZ={T%S z06T1a$c!!U^rUan18`eN*gCmp90XkX2Gt0)%M5T>$W{|<*-J%%oAOFaMY%u`?k}-k zUe#B}&3rDvA!`KE@D{3ZfJKaB8RH5=A5JW=7k%eztZ1z6wP#RQekP{Oj8gM3w-aQU$~I7secf^&Ca9?=!w{ z#98{Uv;g~8ekGw7QZU2eQXCdnAbY&CbY>J|$}QPUe>isaZJrs#%1?kz1#IGrP$!DNAqa5G__DAXEFfZzR!g>*o41>--9nxrsaTJf zjo3A-9FyChDl8}>68WFk!wnD-42x{Ls+`}@m%#vU1v4N=uNpv*XSJQI?8oI^D`J~E=dQ5CQa`F2~* zGEZl>FOb$EXrtjqSIo1-og#<~8#P0XEjC=H(c5{he&Jw4mt3Vgo-g8KI09*DRFLV` zn@`blT0Pb^e$-t+(r6I=x^FPvY|O{FieFFW@sHx>dRpA#)FtL$Z(Bq39+8}!G!QS^ zXanN1l)bQPbmrb&=0{i4$|@?}%$*yQB~=y_jFV*jV`?GbeG{ek{5hy_GoQBp_{P(n z=DPKSY>iyFBZ;tB{Fk{nFTaqUo=*QmdwFebd}!#$fUxReQT*5F=)?2wEm|0W~>7Qicm%SppI?JvL$9aUP?hqIc+Z)||X>D9WI8)?QY z8Ed7Ka?bXJc6RdnsW#*)X>Z`T3q9>vM1@DI^M%9RzbVFZry)QxaHsBD(Dbd|0RO++ z`y4$0a?w``^!=AV+^Ku38)J2)tzZ4Wzc}}QDu@41I_6n1(f|Ja|5Nh*clZD2q}P8p zoCC^V4S^jSN=>ZFM+1D5{Jy zf5hB%>EgvuWkp3LC1s%XrlL|qW1}#jq6dkJib_rzPlmRnZ*6`4{32tG;oQN6wdLjZ zbD?+TQFMA8@yr>vxOY(7B8siN!;TW-3^fb$Ye|&Nm2g@=K{PUX+I}QY;@-8T| z6p(hc6fBQ~8VvYo#Sw1$dFckd169+Qdeq+iGDla(o}PiezF$LZL$)?>1OlK+N`PEl zw_~5(lj4<gv4-c_q#Qe0v3Qlay+O`h8pBZp$Z zXRUdelt$-!>is0Qrhb2(ocYGxkL=MBi@@dBQbgcZgoLJ|ZbBbWlKTGFum8gJH!>xt zP6-!?_)b$M@e+_~yoe8)5j;xTFoIO*^$Rvm0-9rTULS^sl<(ovQI?zA)g(72HAJnT%zWe7>B^DJp%1Bn)rSYO; zLqBuHL_)pECmQy<3oHRIiZ5LbbadbVU|Dq90Fu)rDQs>&3mA9E^>hAj&eHDC{*Uq& ze8ZuNDhVu~YdNEorbQ92QzAjnIhUya{qs@GyIHpikXJe!0iok?y}x^u7jwC_T~y`! zmeak_I%Hr6pe@m=^uf4RJUty^k14gN`Al&OC>r`Nz*D|%{7&=c9&^F9u$xXbi-}65 z23-tgR`<+)U9pLOro;eTi1>JiyE?_m>iJ&YON@?^-UhDqyQ|;7OT8pNe~##BY@D*N zKy8&}^-h+IAxxgW_0{IX*OGIyX>?(Er4%MmO?urQ>Ya>VB87UmbASsZvod;IC6!4c zOmA(wf8cEkIgl4858tH~&voUN>| zc*J4s%tF2nHc9G{GLybnp!JH8f+?OY7>C{MV(s(-UP*v8Hujky(B%U=Zqad>(nlur z&UJuo<3HqgqN0a3>7jAQf$m(jzN-EE>y#K)T0D#ko`of#r34{j+;vE|@lFcVnM9zz z@THv{aH60SO_PAc{qNbJ0BXbv(m3TPs}%Pndw*KG1iZ|1dm6PdR@h=mPP!)O%ZWs^ zX`R*nR?6s~wHpx@6@~sPidyYU9k_gj{i@ZKxCiIfTc<%gj-uuI`_gEH@P8Zh=IB6? zQolXb&w)2itP_Ku&YyqNuhIXD=AUzB@294xf&YY4f|{Bt{W;n;=RF|{zSZ{6E$G9A8b-p3qKIQz4s@8U zT*eR$7}j&Iv#y;zK|T6v^2XDD{u+puKnQOf`P_a1IQeW;w%FU0aZV?*EY z(JKuPswRov)5@9m^5pV##*MU86sT9O$^_LXa+cMkfXL9lpQBNqLjFiRLp(!kZ2H;H zldy=6t6E^<*7V~))(b$=kXawS|*VFAJ0)XilOu8y2x!{Y&K!d z3XA(BTHEoBYOgNJOx*T0YZlC|?rHvj)amIB`5=%biJD5L22&BBJ{|UbiA{idSiZp? zi&-%hr=LDz1Pw!QGi`#Wy4)Z5V7T@Gk_%4{-D=c#f^5<{b>{#bA1Uuemu>i{Y|x$> zIJI<&*o7H&5H%R**sid12|7KLbx(4eon2H?p7HGpqnfiH0NI!&*5(ind@Qf*``^n8 zHTPPIHOxd8mgeIY#^)C4S@SIWgTdl|R^p(F@!EWDRmF1!-D#X`RrV4_z~)`u5Jm z9<+XfvZbHN?8I&96&V}bp|`z9a)BRqv=x3C9r2ZzIAL zzKeEp3`wBFC5$5#W{`Lw!>f!Wd>iYQB-Gf2gj>rUE4?VjTrM9S7SP5)GICgGdP^UJ zr#WX;S)>PXJlFJ2p<=)}~xB8T3I6@``?lxmEb6=01^&?Th?!R2@nr zRadPg7Y4v6#X;Jl2;J1cIjxixy9kLaRo_I}oB3&3k-Zv^$x0cEl?^ELk z>mZ@@nY6&AsvYXvRef%WYM5dv&DfHzVVOuBLkJj$jti9{jDCVU%~ElL z>6s3nx#J}yI%SXbW``9dErS)+*a%xr?5x3@Xk?5xe|b5_NY&T;(05uhg3@C}a0JSs z#)Z}MXktLEmzqmG3=oD-P-)ab|Q%a=Ca-C`UU7rKY=`VR$lp;gb2jZSWzib#^qM zHU3u`reva~G{imU!mR7>1D!kbNeb+q=YZ??9-Vvxa!dZc2TvL>Lb}B@v>Z5%uKjlt zMCfGee!1k)81VyU%qy?@^5fM-+cmmRM9AQMC#Pi1B*I1`mMePd#+7^u`#A+Ktce zSb40ci+OFL2WSG6W6kdPco)gmcU9+W<}JcELn9BSay~G>4aFk9Xig5-?B@*A#k0r+ z}IyNRC#e48l>hd>;O{(JDD-aho=>7X= zJ>>#R664B2aTVm%?*tO>ZwhPDqi&X(*cw2ahKAxz#|yRtE`9wKM^r-PgZ_PLy}U-dsBayH4)D!WxnRb2 zZ-w87?MVqhKMi!ckDLp25t?^bPAe;YvbEltx=ALD31NJe+<0)U*sb8##4ix*zdeWN z9|u*>-(<*n=FRQ&Rf=u@w7bqyv~*tBFZ63g)(cdqmEr7qMzYChLWalH7)OC$*0_>F zi-0GSyW^H3&}WXA=UeaEJ3E~laCS+a(cC37%{6!SFIMH_hAeQgpRc;+eCG9b-OZ4I z%iJ-Z9Vu~e8nqMCcxn$(v9e~nxhN$BbHr$hapTYkcyW^@jCLT`RSF8XFc)1#Yw=t& z_V9(QWS|4V3b%n+k|+jX?qAY^k(LwutA25NDN8+_{x%w39z+L%g>&DPQCwdM?8gwL zokYsh0=+|oEOqa4^$o!qAJ6OLRb~R^qnl*3U*RTEQzml8a`_CXM(%+6D0 z-S5E(3AkI+%4*65p~w@-wg=shoyGs0@?>=5R323|qi_Q&{43mb)-@JJ&cvs9B&DTk zUR8zlJELu2R415lo8w=l-piR|marda~zjq_IVSFfABN_jY-k{g)G zKYEDTe)q&yL+)57=N9pJ4k#xlmG$%`9li4!n^BFAGCKAhtBSR`ac~QG!lEoSJqaEr{*zU z>%&@z79xr&D15v$yaAupIl~N98hwP{PQ(VdvW2~~UWbd{0-LRfyF?EzGuTXvQTjIC z`5o-YuGdFFqhZvZsltdO@|dQ@BFMh_(Ojwc6*n@UBM=ggG!-{5Z6QLli0_c6)w@+O zTH7~x4Nc|93lazAEg{{2b zW#J7!8YEWTJre0KZwhh^*e47~9muS24^N7#%DMH;X&~V;y}@()C@uLks$fFSkiNBC zxi7Ba^~6GJ$o^H$T+-oGgme&lrdxocXrMAv`L`9RsmrwlhAyI>MnR<}1n$>H0l*Ba z2L@Gl@VV`s2F^|ed3E7$OyyNaH=L~=Kxg_DR@b*~iUzhTXsMxD*1OayT9xXxo{nzt zktVN2p+7EPJsR%T$9psGJEbCS0egcrgH@#{zc zCX4UJjY0-qtt)^~)%z^LaKO5W8v`b*`bP6ItafDabItwz;1gMUVxGI<(HqzQ_8H5X zi?eY6iUIY3E6;3yrk7VC;}<=q>C$_LplEDzogK(v^O{>H&-C=1srwSX4yibrHz;d^ zEAg?Xw;|t%eHT$YX|~)`kVzM&c$1pp@;Fn{bTeO@p0D>-p5b@jfNRv82erk-$m#8a zm@xBQ1O!>Xy{C_9rWFZnZ!a##tQ{^-n{Xqg=Fud(81Ai>=&#|?-=|_@NNMhXs>2-u z_;RgIQXj73`jf{kjA8fzrz4qH(*x6GdUdr!gTbx3aI(XvTU!d{jZrt$l8u-HNY+1- zEW3_9S{6ke$jo0TBk~HKHRL^r$*)${3t0XF@0rYO#z^qZNcu~FeA08Q<17LOJG){w z1UJ@IyGLp(b$|e7=O`4Y$vOM}*#)TXT<(lrI;XWI=_7*@sU{&|nMADGHP#52F2caB zG#}=FQY-s{+;o5tmX*P&wQ*Gky++Cf&tl}dP@}KRPPScYltNSR|+V%3mzfn%nw~%2Qo4Uvl+a! zf(dRHW{Hr^kMeV>wb7UyVk}(-J@()};0v2TVuS#R%Tk?aDSxZ3#S$lNxw%z|aSgcO zD0hPcbwF+7f(@&)jA~f3T3~#;nV5e-k_J~c!4jVi_L!S-1)mh}eEZ{)ua~-Gf65$q zH~{BUYg=bY+(BCLgRjFnrp9jQVFl{C*?{@sMo1HueE*?AE>QowRYKN< z0GZF7oXvaDnx(f?@@l#$$C>BO6c5C?|BJGA-Tsz_b9VhbElA(($Z-iDT_!3)eYGm$ zTstCzRwdV6JSI9-)uLF2O|9!UQ0VzlqsD?bwJ4nrKPU*^Ywh5P5DXw8nBISU*Vx5^ z2{!Y+3uP5*o2+@Eux76% zeO$o!UQ=AbI2sdpuyMf$iCYcWNE3G^?gO)WYvA{;6bm~e6~_9Ehr`-KTbDZNAB~vdX8g` zHAK}A+?(gk0&340#IKi*7K$<^s1_sEtEH@=zbbCrqj3oG^Rpp3gg~2peBXCB;TkHv zF?)?}-5Fzw9G?+%a#s@85Z)uyg3sGPwK zO!SfL2Ig?gA^EAunH{psdG)V|OX<5`fP`nL^-ds-&TQscgx0;VqHSwOngL8dGoFyxS8xA2xY*f8((r(EsGbk8+k{7LJ+UQRp$r>H);;Xj53*HlewU~Yu`?5f3ePMbJ z0tIU804x0ZKW7IIidid5j-uCB@3~O)xigd%04oGPOO&(eNxa6*rbq;(KeRQ;tjJhe z?VGad?1LKP`$|}{_!7Hk0||xzxudaeW`|fRzID2Re?39nNu*yJDU9z$`u5-Vr5D~{ zvKy%zz^O~fq~g(Vy5&P}nxc5GH4$Sg-0-fUIfg+xvIiDBJiNrY%mx}kqIqJyZA{22 z38c3G=m)$aj_OQmhkcmw&tLFeFr!El{7?&&$L6(=BNLcp@!UcCN)W*feI9`n5iR+e(^8Yc-_WR|ZKLvb{=f4=+`_=Uxl7Idjh>$58 zdU+bcdWN6_cG>c#o2^rM0?%;|jWZi>@6D?*^Yfc;|It@gCQVcOk$sG3F$+MwPAuM~ zinTfI0CJ`0&IO$%Pt?!I!>*xKVei?`!`6H+{tx_GM7yLzSp;dU@!H1lVT(lQlhO0l z?6D6`O*JQFKdzi5u>Zhju1&jzU+O$Q{RgYx{TNX=gy8kY9;bmnJnoXD6Mv=*8g(F> zp#)Myz+DQAXNchU7_#J=oJ;@xobRFrwyBxj&N>1uJYV0M=<(_$Ma?@0vcKOB(7Au; z9Zj6?JcEsaP;;-tbhX;#Vcz$qQ;DMM(=X52ROoH348q4h`Uby3pVf5u{ch)UXRXQT zKm0{D>AX^E>cUM;B{I)(CRn8%6!hH_iUpq=pW@!MXY&M|fyvL;<^8uaKetTEl*J6K_KROHvNo8|-_^J9nuNEk(} zt&@Nk|BFhWlxw>>!86rR^L*r2SEi>tOZ%HDqej=04X{VEoOj8&sD&F!C+6N%Rao)& zmt-5|=7=CCYpH;zJ$MgfMxKY~T)0B;J)iOCB)K`-G8DhznVs)%?(y!aRqy1qFrA^r zJ)q+h;fT>1(p6;8>m&-moKhwYp(gpGn{~7xRB8X&Cx!|ETn_b=NV@qyn6J`_paBBe zT~`|7*5L@2_9qoaJs0L5%DRiMJx4=GO9)4_0GYq+fk2 zttrJ2`%-0`4%UYO!DfLb6rf({Kk>_R2-0ky4PHa@_w%c@m`c@SW$N6bn%Oan0$)pS zUhAs6;LLUB;m?7&JB0ONTI1j8jUT#TL3nQ$xT!z?w19$yPSY%{hT3I8kIj3!cvRS}kL)lo+(b17hD|tehZ7zt^%%fY7 z48u`SM3L%`VAa(k*3fbof%Dj&=(BTT;oqe^sl%5wQe{xg^y^o2p6CMc&*gcZyWL!KL{{^4hhCXcn2T z+7tKk?mhbl6;(Iq>Fu}M#TI;Xb9!p33|ajX-Vrk5-8C9x_wuE$pI=7|E5LM86qS)7 z?e~i#=}o;od~z-Wgr~IBRKCX4%uJ*yBs7M8x7#lB={=eRlV+RIRe*r`u&5|2tIc*W z#l^|aXAtVcgz^y;o5#wqxs`qpe4+@qx!`E`v-M=K<=}4KNgv`#A?Z|2(9C->?{gNCiMGb2G=Zu6NPNA z>-TndOM1?KNo(wichFrIB`l%@%VCRO`%3uAy4>=u2IRn?KZ(#_F}Jgf?wJ(`0n#8m zR+!A_i+u$_?aDFHbd~SHO+;K$CWJ?%-ED?Sj_}B#=mTr;dcoNMAp`d{;yJdodBIKF zxX3sLd5zeo)dyX9di%B0VEkbkIFi4yzJ3V88oYBymFEy)UQF;?Yxdz*n?NAM99nY^ zYsIow*<)n=dtK_Z<+wDNTdcbV%5cvAq5@m)DKx2^8JM2_ zS)OWd|JoKBEh9anfr?O^S?q`?{PyA`ynuL;>*jKUMhSAbLZ_)2Ek5JB1dz|U#;C~2 zvq(2-Y0Ycbbr3P7E?a|ZRnOMZ%^&&Q%o^en*5OTg^)#T0oIERw2=y{U}io?LIb4S zdp$HG2>fwdjO^)ro4(UHz&S7*NBt5ss{i!)n`**lH$>J!3bW9rELLJF2mX0#TxHin z+Q!Sz2>!^l1!}#p+LPD<7RmElK3YZHQJY`@J2?2QtQcAZZalG+Ljs0id$Ku6T(XwA zJ>dG^Eth}FwR7!CJ$^x1r!&UK%?oZXGRXx%DBo?cl{PEQnOLA!s|cyGw^K9yrp$}? zRS{}Wj3+DFKKOuN~fH)8DCb5FgUaH5Z<#xVK-FzhTIqTS5L3l&)a1NJ0di_^b@}MRv5jA>|GI>auA!e-Zq5f ztEb45x(5Y~svK*Kp~`Ij%Msx{J_IC8F1` z1((1<$TXZBer8}&yNs9)4-YRXi^$AmOE5`I<6ql6+^2N1#aH$tjOsaIP(6J7(OwJ z7cA^Bv?TO^FsT-olY~MKj(!P~{I_?zf^j&fUSn?TA-obvdo|=C4I}kqNRov|f18$^ z$K-(n1r}>t1<4z|+&uUD5pmzv}%5whj-y zM{z|rxUNPV?i}!qSsI@um5J&=)+TxJdww9Pz|hi7->{*pNvNo=volow10^fXUAEwz zEO_ep+$$LwR~MJ!(o)*HcVhv$^_74Tpei1~vAcNj^7dTK{iT<-NCG((Re>?()-?EJ z>kWa-Q;J0twYX)59GdVb1)&0oD|9^8IwFkyWSADYA@nOT-O_^KN127+vq{sCu4t%m z!JtT3a?4wg_g4KHEMR74MqWXI;(~DF8norr9epWioOPrx!(LDaM~5D(>$i^|Gi0{rR(ErhAt%_RgK%aQko%TB z?)F^3-@s>QUndfz+&gd-z^b~q~;jzsW>X)=zc6Rlc;DZN3oT1+pb^W~!RE2`P&V1f_?%zI@+=tO5 zi=dRlFyOT5>Fo`0vgAzQYgmeI#5AY%fML7eA8up7^c3SGj{cxoGSa^4~r|PZPtBg?K7Lq`)r!@cKDic^J(iOBXR)O93 zxpL*}OdTpx6ra3z_aSDzz1qahqs_S5dTtt^uwiDa#J!w1!4STHBdCvIsgbdvp|Zn} zT?WDM(WBR@rNr^kL3&hxufGt1BHr9*d-h3~UREicg?~jEj2Hrut8-Z5Ebi5Ks`@gN zUA%Y@XsKTO9Q1hP`%Cckc6rsU1_AqgyFZD1e@(6rzfXLwGJLT z->kg7y}_rLxF@=tX#%|+@Pzz${dABkALtre5FYx8gHMpZ*_$Z6)IIz&D+^g_q@wjK ze-Aw<+k#n51E5ZTmvH7~c5G0cm#|J@^YmM6C-+z#$Ql{dl69F}y$RX_H3~)2&^SN}%1XWKVW?8N;{!u_S$pkfvgabJ$O=i%&pJ#VnAadWe;Z)>jhU1>R_ouaM> zYEIR1DyZQRr)!k!v-!R!sBzHNbYtc~Me3PG$E1r#)%Y{Ef{Os6ZMNH2H7I@htL?xp z(Eq4xmP&T#d4N+|1E15_a)ldnq;-WJ8rRvT6(W8cBy;F}vswN#n)>*MPYjxIum4wQIg{!Ox_e9CjpOUZw}; zGFur!thTmO>doUft-7XSV1~HlKx~2`(tn@dT306% zf8=rVddwAodFxYh_?S0g1QH$*UV5k@k@;(UFe&AWCmh%pIed3)?v)z_8r#|$fKjv$ zd=_@_tgZqATh_B=&k+6_%8$c~dj`r_bfInw79%uaCxUm$Rl*kb>>cHI@ksB=%x=;mCJ+FxXE=WOz81PAh)HGM1H) zF6)6KV}mHB1z~&i&5h+zC=MU5;z8*KQa2f(DK?h(rmU0u6Cu9i&GeBCt-840IL)WV zZG`KfYjsh1t6p~5ci$Z6ag&?)6Gf^?4_O3`c%3(}srQ{x@1dVY7GHSZ$_U)$$l6&| z6HK)wza$EW0~;;++W}WbKn4(y{CGkRgwXyYF}Wy4(1XIt%uGz39ADnDo|4ik;b;b2 zGe9wJF?b-Zy&M`snI`PB-Cs8=GHt_`gm*-PI_2jVr@qkxfgtJAku za{%WLKHZBi3)oiGRM}u%dOiZv$@|>~pG5nUo^StE4s zUUE;wDnB0&zoDL6tSP`Es-NhV**(gl(B_vg#lstF zSgb`lh??n;d43oeYc!){mb}{?pk4qCy6pxpiIS`B! zzLu6o1$)NR2eaR7BDU^R4-dzGuId{le_!>P$J)r$+=UTynpN@bH8kW|81BA1cR~+F zjx^&KLWT5QD*M2iAC&vD?MIt%cx0I0Za>hwvb3RMH?ddnjO6i(c$Od33MJUJc|Nf5 zp{ld#C29Wxmg~y6g_jo+>({xqx(XxB1pq>Dy&^c^p_2k}Dp>=G{b_>c)yE-gnRV$$ zOl<^;jUQhEBGXi$QUtWNk*9MceC0c1*(1-biD%a7-UtQxw;}pT_m_jptv5PFd!`tx zTsS=3YpJde;1+W}M>#=T+5fTa2WBznf|-scXpms@OE=i7swZ(`(+MofG3#Kx z>=tNshkML=-8~NAwWZi%f(egblPJ(3wniRU$doi9&RtJ zaNLa4n4Flnmz&!jNpB^|+aeC=%QQnHP7@R24-9}11kM1vB_l0kBV>%Ei2fKu@>*}jE4erl%v#Tir^6#%iLz9rnd63SP_d4nur<%>d@_Uu>3Rfb+~BCXTsiA&=Og7xEk5?@-PCHQdtDiz|Dcz_ zEmjG}t0ou|2IWp7g{t(DW$X|P({dTX>8zJ7lNlo<-Je2seHSG9-RG{fu@pvJjZm*+ zdN{)v0&L2K=*I1>faZJNl&)^%H9*aEi0N0|qHNd3>4BF0bWf;i5Ux>hN;N`@pO6|& zd(DtA7oRr!$t`ETLW(8p(M~OV7Qg+btmMd6Z zhAJj{JBKlk2V&H$#G9}utyMGvmLr^%E&g%o%~|}NA!OL3DF+`W9Tco4$KxY=U2gUo zmV0`7I@{ZuJ@BzGH7zzK6s{L~rHKXZVv`J}9UNU>;O<|Xyt12Q;pf*I?J|z^Y+i9U zH%ng$Z9bI&`Iy$mLE{v(G?GPzD>Dtv{5a4_x^LBy;tFO)Ym<mfqdjlzAh7=mDRH zJOT%$JS=l{7tZHjhw(G;P|)j*`4OLrV3GjGos72beO+ zpfGD%HiBTmsj2&h<&{&xr}hLtL<*NM-?W3XBTx~pTA$9Ma;P$MiBo-OFgf;4I~FVe zgohF*KM17b?P*M5AW3dpONC{$%OB1PO5fcDaWENnK?1px8r>wOA<$eH0w zu=#jB=Q3Y@bC(UxMi2Zx0L++}n5+(F01dle8p|DxIk2%|mgAR)$#)ac>dA##yyzL2 z?ngaCeLzh$<8?Hfh@SBpl<9j_FiUCk!3K0csr<`b?D8CbTQsUSuaYYR$0Z|`;L$_R z6~8v(DC*^ft()}}Mn@|vDmCqlMA(^G+PX8|Dj#K7YEtS2ww3+Y{ezsM+^;2>*no&@ z>PsP^KNH3+0!nQNU%uSt;v%54k_fo_Pk4KJq3KZh&=4~(EZi0i0!emspgue;F|8Ze zboZbjlP2Mgs%R?OMTqM;F;{%PSTww_Swo09*X1}k=mn!!3`b&Ea;`4{_{`SI%H*^^ zZJ8NDC)qAi`ts)@ZHN;2`-8nEb|2^ux_xHXZIA6{%v(G+zuf5i@)_R_~g#ZDc z>tSXowQnR4v!~KKEfMh2leOGh*x700j_Ae8bl4|v@6DVSAdc6FkC!WJ*oVc47;BD* zK9ONKJv~#g0i;;S3ZLy3)BT)UL$9;dOmVUE33i=fkFvp@PH6_yG@&8s>XOJ{5bEx~DT=ZyfbM=Qy1e6%gFD{Nip*1hJ zF92j)e565o1j2EKOCt`0-IL&Xf5n}IQ==V3A{&xvaW_3 zBS$t9!vXY4Y5VH|hFnqfbhM}z=cj~Zq@;4PJ;A5PrPGIG@F|NGR_&K1YnuyA-bjIZ z`8-wN2I$cLfcK}L|4>r`61KP8P)DO&y^e|}f>ccw`m&pECR6O2LntXk{e|f1JFW2? z8c-b#2=63y#A12tpwCz5X4lAe(WBP}&)#ul?E>Q4F>M%bujzT^rGG1%NYO4T*X+(} zwxUDR8#RI8*Yxs@@GseIEDLMPM_qWLBKA(5Mv#DjOl2)S!GQ0l(%Vfz!!A=KBxs-W ztzvk;*FMz=nM(-QO5cW^)2)ywU1TD&b6W9fR^DDCAKIyPw<6x?ps*U1MF@7zK}!nnYq7x%b>ZQ4Rh|+C-0TDf`S6SFkArVRn^vB54qZN zn~zq%)_jYZy@h4;V(DN&Uq3bW13tVzl}2K_$*l{jKn8#n|8o-^LqlMtePm?bq^0?L zTx8>k2*k&>c^(W|d~aYu+FM<$4!OYl{Pva;ITg*76*g>Gd&gW-u^nt<$-eTALIoUE z87F2Q4_jZa>SN9CaN}S@B0XRc6e7MC!FxEwtf^cMie{3ucH&eJDjy%8B1xTDT0WTd z=2>gH7cU)e2MmT5MI#4B(B2I>Iin*ZL57S)h3bW64TsLvQVIZ)DTe-_-MSbC-dAe%XAeoU00PIU_6{FU`gF zJ3h0hopmmrA`R!yv$w}>-5$r^Y0b2^a;A!3CFNQ;9DtoXfEy#;x|%sCK>p@D2ew8} zx6Uli%-W<{1F@J=<&^>s%LLC0>X(X`Ltdvf`)&SwUrB7}e0DU^WBNsJr=I>1?Q+r6 z$|#;Hc4;D}9cu(aL9Y(p1xR-qmC6W8uh(sFfW?mNywYn-{+!*( zfy%*1v-?Cvq40;W{}(KHmX+aH~6bXVIBR}F3p>r^$DrGBrjH8JBeF`FK+UvG6T z*9!4oJmMQ29evYojK)ImzH#inuj;)wUEb;ia^I22!UBf;rywwlLKc=5L-;*Vdy5D? z$J=DQkqKgcmNpInz;udw?g*Qlhce$;Pb!-*!4s9OmqgH_r*mOP)fAB?#dFtbwCm+%YuS}!o)a>QLX?e8r!fKI(Ds%qOKQ}`_G{rpTk0;&*{*3|+gXkcPcPB0{aJP5~;3Vga{TI0l2 ztK92D15I)J-P4&`hLA6A;tEjzwiRAm&k>M+e~x7Ag1_|n(~UGIccFB+wNDtgpDp&> zaE_46;?SjRJR#wV&vDc40R8>2kWrFrhwZeFZzS>)T)AA&HP) ze0m~~+(eU1Y)!Mz96atGX|oQQtgC~87yf;ZM!M`HPi3w9_~slJi%{w>+;+av}L(}eRR-+v(Mg#7rk&*J>PkeLxThP$sY;z7T8JspzzChEtmJvwCdTReUd%L3{?uA1m+&vm1@q6cXQcN{VDrE zbME0h&Dc%w0mLR1ogw?gR868r>!Wkl_Byp?fWYY%Rns0~c>==zUS>t#`KH;ji1$Wc zS_)rcVnRpc0}i+2&1v*rpgx;Ls32~@#kgL_l!x7{u8!gM^5Wv!a`l-bG=Hb1(W-BK zGcvLZa8T)Zb~VYd6O#0+p_UtWc*_j!Qf;>8{Jyn?+D+H(ZEuuwT}uyG*h8QH5;x~J z@Sa&>EEhW9t|q@raJYj$-#KMe3l>1u%XMXY%)aoWB%-7wy|=gCxFdWPbB;;d>fZ&f z4``xn-f*Iv@C&^c^KVC;ElV--_3~8bwJHye)key62Il-YNPu+GT@B`*!OL9S~=I^y$ju1E=r4yb~?cVUFwD4)TQu z;fWlMjx<*v%q+$rPsg&XfanNu2$s#8+YLGT@*i^xJgkGoMLzpJh*HcV0i zP?@F+xwG&AkD2Ga3;_v#tk;5s!f{>DY+F`dKXFYkxE zN2tYw3|;<{-M}ZPg-B*zVn{~BaA*3KHb07J)o*8F=xf%N4_xP13Nqv2l&Jq@{g zj{?5B`en0IDFAicR+Eqiyq=wc+vq9REMxj4f=6)`Z+0rhPeZP(tP z67OYP*LXb2&KC8eofh+Y-CRzxgjVK}(?Gp4#a)RhUL^=f#vIzNgjcEQbOzTIr%e1j zRS$`>lhhgdw6y`GI)G+{nP5V(_)WF$f+8Mkhx9;=)&N15x%iX`)cB~jbbM!I`ito& zfS3NI!U#Pr&KDAZR?A|_wD^AOte^rma2to>dba00tybh<5g8%)`flkO{qLKSo zu87y+RO|nlb@rOV*zC&K>=B(>mq$RkBr%cb24GcF(NtuRj*(F=*61KeAxYA|C&a?J zvGg8D?W(XjbeFU%L>=jkvu;>AqzIYZ({Mc5eIb)1L&zZdfZ+Zktx4tRn1#bAb|Mel zhk$_NMGhxZWEywp+?*3orHR{R$vO*bkJaC$Ev{E7X|1g3Gxvb!c14EBbhXQF2Tjsny8-H znPz-dx}i#-p!8Zi`*>TwHQ;1rw}2m0xh+xJ#=RTmAKZrM}tp1&}xk;kz-2> z7y|=ZQVmh2=MV{T4hgb6NR6YQAn&A8df+O^7`}MXge)W{xVx~u@-)NCBzwVj>FwOQ zO#5&}*J5sHsq3YhAc@C$TMy%Zl5eG{O63boK2;Use>gfjhE(!0_+uV;6WEh{&Il9r zUD|0UZmIcEZ>QGmEd3I4=%B44ctk0{Le0stQZn6|0m#RdiFQuk`}Mx-k05z3vsNmy zo(Q5O+(B^P}W792kr!tD(A zy||1=H94fLB_7V3`=zau?;UAQz9n>K^qEc*5Yu75|KBY9DC zXkwVpWjEL}9kA1XXY|#K8a?2`#wPvX{g|GsnL#xFOVda14dT05kYGtcO|3Ad0`+d7 z#cJhd85XIU@ao$=f}AqzYA9g*{Q7IR0a|o1LIQSZ)txKihXaV~p{jXbO8C=NE53(f zY$OeE@&}{%$TI+QD1TXHuY7m&kHxSUN+N;=7g)`DGLy7V=jhU2Y=_cpogYQ{7|D8t ze~rub;_GiU2j|`C!9)0&-;4+~mU*hjkPh^8oHbcrnhd7qZ2a6W)n1vXryxyU5722* zZ*`0&BO)(?6gI4j&b$3-C2uNbiR~VD&>6|(*0)!(km0-z zi`E;~+dFVFZ%g(aY*CbeHLX`j6(Z6UjBMlKr1?QY$Dx(0}xF{Iy( z>eRIR9SW(!4tsaDw(I~;e{OHuiy%dAyKP-d6O*)e_@gHh>86{T_sy;VAvQD2#OG0L z%~E76nTT~imdyw1T*NEDSnT25%3U^e-%9HchzrOev|81rHdDvAX&*7N3n@l9f&R5A zeB@-SowyIW^VE7gJuR0|KnlKynQ?A(rp|6+1-p{C@oD4GdyuwRU*e@^Qp{9V*0n}| znWgqq8W|O4pLiKC9sfAM06mogdJDaRG*$-lL(e7tRi*5 z+uk2Kk$!;@#tXkNZa@{U$j12XW z!>oTV(&W)MBm1&#w*E4I5fpbe2##`nd=OwbdFlMBhC0^uenkD_RO<5Nd?5mk+{n+B zl{RAfA1Y(zTwF$m@U1k)2vg^uL~z-5ovOTGQ!JbIu*(X|V@=dZU|M=RHL?O*uzi+|Ufp1yo>d2MiEw?aIAY*}6= zX}?J<@1wBax1u{eu?w9yn3s3(KO1c%w?H6&e1ZWreg28+!a|kD3!pB^qTq$jrztgf zTK_=!?TEa9xf2Q~1)p(MaiyNPNn7-6iiUN(nIL|re3y{hm%5xm7DZUhVJ=I&Y^-$t zE!a*KKZ5O}h!w9N_UPEeHnh>8aQ%TYdJ3Cdd3728U7Ubf=ZeOi!%Cpa8t|mFUxROs zUWi-)@_O44lmvek0MY`nx}}E4ZD{!*;B$14F-$|J$QG-R%g!Ond6I)wv+o@Bf#n94 zH;U}tfKjgdN}1kS(Dx2DPIGl24M=F#zGVkGlf=Gt z^c(&pgibxJ;&!XCwUCh|ZCJ_}vIKPfnAL2dtsS{0E}O5Z5qIrs$T{}y>4tfax5~V+ z(3xgCg#p$PV+UBh#3MfpcY_qBA)E}>!~a@jAv&~q>uu33lP2*g#X>eMV!k=YC-*2x zorDfn`~9XF(g~>&CEQ+L1RXB)_zCoVSBs6 zWMBmv3JpFrt=tlIKD7iaT_bNdM|56ftF66JV|fp#NM#@27vL-@DkK**&k|$W5%Qit zJSok&w$|FIc!N2<75=OLzeNg3z3&y5p3G^4FvBVTBx>_Mrk1K*QXcJ49h-fSkVXcL z-%_LNWng5T`(hFlC3cU9bV}|#a_7vCo>Ar%aKrCny^wgW{=>z&ve<@Muyrwn-(=2E zq#ipTRAxy*1P&Lc9wG+VZb(~9baAnD@%tAPR`dfw&o2f9GeF#gr>B(|rK^`*shC3{ z+|*c0WL?C(8o^;MLA|ANiU?zA*yjxq3#h$I)%r}9xO?fXMB5k^c3e9d5v91#4b*cZ z;Cc}ZS&l{>RqwsPFU$*y?Mam@%a>~M3o3Y)R#?VjV{bi3uSx*ZVb8t{w7f&g9lk~5iyQu?pKg8gB!`9k1Q01Zj&M{Gv=8j|5-?j>c> z%euhVAs1l+0vR{>%o*8P_wmT3X7db!0iAu`K=bR@Rrib+KL8yCMmc^?|J#@t1|Nhl zFJDJvxeAz*3%=A{Debg7sy%-hH_H`OTU`x>PHvn;dAT$3<$q>KUyvTgi=vG0r5b;6 zTXa+|=fnQ~FhuJ@2EcwzW~x)~58Ij)Q``@~UQ9*YsXSn+X4;y(l-YOjeP-84g`R7q zdA7M)*Urq$Yi9Sf0RerTrC;Pleei(CfAy!oXnJ6*PN$q)M4@P>5@oJHQ&}T=%gzp* zM)ruublF~MY5J!33-cR2%ru^Ik>48nHn}#l+0Q``s;uWztXpdB;NW0yp9NMr#BQn{ zRGS0hH-BxJ;KVQw!*5o}&Z#o1^b{X>NTqH8;RUyFw=^TX({>TdfF}8J>#w=-pxEd!T!Ke8|RkxW4=TN}NSbu$AMp&uOK?@ln${ zOtCkE1iv^dnx}XFIyy9=KBkzFOnI~a0oC$qo6?YwFc+c0VSC+(r|@2zY&B0U_X!g5 z2L<*=EriC(OPVdyhDC4V-NB_wy+>RXa-c1c!DV!3W%)=M+Dkap)g5KFP7y)hmQue1CDeRb7e>kA@-JANY( z+i6FUfiK zn5epjyRY?7Do<3QZvK}cQYi>T8Z=V5EKLgu%dNgiZu>tcUsRe%(+%BMBA;~_7q)in z?v;!vYl!*;l+v;uvdg_u>)~24d~RTET_XCj?sE2+JBwDQb17rRM^1l%J~p8e24*3r z!>_@G2L(>?vM*SbceSDRT6{5H5#{;L&+QW&=K)%Pbr(dagMH4MUrBoUSP=&9A>Z@b zmb`tB-H+Q3Y3hw4#ZAbo9=h;5oGJ-Fs?Yo{N3mAn;75B08`z?7UXU|t9wjZ$Z z9shV9zs^hg;Mhmq7d@oPwDC5`?7v3Y@95~?uU2eOpimq z;i$>$)?_DugnPG&svt$E4cChw_eb2Ge(-m+T?nq{BC25)j7}F)RgRNZ0!0&+Zn~L@ zE^@I!LE@6M8*{iNE^}pxzF6fve+oR{H8YdiweE}EE92(3D4zPi@t5D<-!J9X4^$c( zdJeQ~fIoU~y_kozLc$svo!Ch1$8`&xdi{Fvsn@xUD>U9Fpi(Q?alf;zmqip(HnsGb*(@0+B0+fPL=uP>$bXNZnSD&xed@Ig_dq`xr`#52AT8-imOC@8N!??;Kes>gmR_T$^P zp^lE4vX%s{NaKv0%)z|UC|0v;Zn_i$dyU8T*|TZ^>486n7?19_0hGbI8WA(r`mu(b zoL?T6Uxq3eD_URg#%g^ia2Kj5T60j+lod%-b@Eklq#imAy)8GIxMh21f^vPzBAHo$ zQC^!X7|uG4ZxLEp4Mel7=zZt#9~k`!-+S*ERXgYvygA zk9!=wZU3pSUPnx#cqCj>|HRGKt*N4<++mNxKwVW?J5^~pNo~b^DU~G;GQ`geTQq=O z4&^0rsGdQKRO0xJEV_KeD6{x(*@VwA*FqF^ zI!bFy>IE!J-NwAvK)n1FMu8E!jN&uxyvDsO!9uffx~dWm%F?j15QA{ zC_gtvA8WQuyxcAolR@FsEv6c*>W}zFOew;>v%C6!gl=Hr$S$E>BII;kUqF8-#X^OFfFk0c{@4nx^f(qy1Qqcmu$}cYN^@D$tTtl zS@LYPwH_b2{2m>RuP0;@xZP`m1%tKMCXi4g!pOY%8h1^0c-BOtaWrgb;4im*J zB?L#-8Rh(cuv@rw(U8@GG~KD^`I@V5M!*x~poWgYH?EdWzAqKM-VR&xuwQww%ZQaI zvj~R-lzi9+V5Y;TQJ_CHkP)L3Z0`2>J4t@hQ+h()nin?r@>O5J@;^p)*OsE zXHMg=szH4b?2EcSa;%b*!SA5@>}M`cc~-X>VJ|1g}j6g*mzdi#;8j)6bt!RhJf3q;R$fd<%2`JRYyZY_%mV8jMXuqC}*XUuA( zNK5moOWU86#8g+;swRBSDw>&`{&eEEJwsRT_0;4;=Rk^6*W2nI_sv-Wpu#5Ua%Ay> zn2nob>bmG8Q1FK{V-sYc29mhefpFmF!SfY zKzU}S(X+~`u&8$gaE>-cCLsr*gqO2zxZW`vuD##BWtNu4!`+CEo_0U7t|lD;;znb8 zx`xGEcG7gQh3ZAG*tFOZi`8XE>LjR#tlfktOpY4UxH=dq3O584!l4t8(lW17h}uq;_fY&N zJr@)a(N3*Lb`Fe@INi4KPAlEZk9}*4whwVBMTq#QlP_U?ZC{_<>&*$SyVUm|YbgeQ z=`&rr45(9F69)*0!|M`=kk6y55l!>fQ^E@Z-DK;P!NSl?midPXHb3tlzp>#a?Kr(u z?b5+ddre`Qk0ivXx#iLKNT(>xk@RKj!!>pPXGnD$^|W$|fk>@NPScwMO@?Xo#c2^+ zL4SEP77lwfwGwvAhtRKz3JaZFTtL>$Q6(!NYmLep2uA)u;GnPEmW+;$1_c8kX}-12 zXkP~RiKcmyM(zK;GbNccLiT_$Cj6i8J9~4`&-S5#iT7?-7h|qjZhN~V0L$4#vhnZx z`uRTzY%GrS+3ndt=$s+g@c&SRJ%J@rKLqWs>(9yA)4w&u#8)GM4_M0sjTM@0q1 zmsr23CD9TiqJV4@1G^9QIhMLE7F?SDG1|}hxAz=$=yhI`PiKgf%DM|aPKb}65}(xd zm--R(K{rP+OZ@JW#at||B*dms5E8awSRy4_mrdb7Cg&L+$gVW3#a#N>#eexPrzD`` z{IvXviIK6UvO2zJ8S^Ndpc3tVcvVwLmCLBz4s z2{UKY<)Z&S=*!o9B$fKK z5jA;w_NOPmQwNg0Q{Q|DkRbza**~6~w`diUy{*!n4Qx5NF1)f- zAx(AhD_d!$4@@uCuZ7+5=^fVkEprS#DoC}?dZroWU=7H3;C@u$rRI4Wp99YB!}AQcV1xP1+N;vSf!ANwXLlJWDK2yk*t7XJRS*HR(9AKpkJ z(Q`ZGTAoDP&G3F~9Cojzp-zC+UA&+SSm+|*GDj|=d>&wF2Z5D>_x(KgIXaC?0QTPw=4HlavQUtfQ>o<;}$;mu6d{RAG>m3>^o+`p z3qO#u?vf&=`mj8LZ1j+Y)c`R&UaE&WN9ax0Iv^Jg1^~Y*C}vAl0_&}owccd2Zcom> zkz|7Q>M9xN?HAsSgg=q!!3=LI=F{+bkb{>H{lz<%*o0)I3n(*)^jDS@rhi;nN?_*L#todcre z)qw$+C^hwmXme0^5&E;h(!=8d>n4_C4QLtqQps6aS;<=hIhpfuNKB01yQn|Qz5eni zMlbKW4IoRHkkc>KoTi*D7pc;FtN#f60=m+JIM6P|is~zbi?*We_8oc!ju%NJTH2kS zCQWx>V_yaMAAK-mrp{y~)r-BAY6sv{yPafDpS}nLp zF{OnU3ae2H%qPudd=C(a`WR*cFy+tCp_Cz5TiT_XuQIB40{h&dHC?7(Rsb}UWKY7S z^G?W+Ku~6B8Iz>^^*!5;p@&s4Ik|ON0(DLHX1&dwlZDC_@f0wRSci}sw=O}Q$ZsCD zD1?#p38a~xUmNOI;LRMQmXJ2U;@3kPV>xb5m5@h_$-)ly;<-*|Ff|TXNaELGfdID_ zxWOOvh{E|}zpL(Tjvsf$!DZKh3*bFitF2e9tCKGsO22ybO1HE|DR!0mz6ACZX7y(< zC%n5M>3$1rnTQmrY(_RVb1dY&{`Xfc+tL(%oDf*@Nl>_rsz_rl9z__4x6MVFE!m z1iWE*1jH*<7siVST-Qtge5zG@W965lnIaQrOk}|0MLzH*xLoD5&HivTkLuETL3XqN zxcFC0U}g=$sGoiJ_izkie@cm04M~yNVJ=&2P;mFp@igxPgzMMXtwBx@wc>1re-l9C}cF39WT8LfW? z9&1B@`-Yf!xkf+g=bXo{rkWsev5?C~{?F%<`Z{~sifhWojd?wuMmKgeYwB(2C(7nX z#qKF-m$x?gag+-}EwiI|q3~)u+;IM|35KSl8o>m8cS&(SKW`~rXjkmaB|C3#H#b7? z@Rf^eYlQf63&x8J;4fZwnH`wRseGzRm#Y&D!Tz^}!E)IZ#_oqGUDeW>2$*ry3k>*5 zhCZ=2GdqjBsn&kK%L3v%I(u3R^F9gu?AW>BchaWCSV&(W;x$}V7@Hs7exJ!6R_}I{ zOxUkRdz;*K>O--aYGIeD?(sQ0Nc`j=F6wclqaWB+>%zRxt3d{+XfV~GVQ-uma^?V_ z`lk>z2P#*0g@{zJSK0yy?hDGkm67xTcgKT4i!o(N#6Z{wbt(h zIS?b{8}Q-7Do-u2ad@~V`~=op)4odRQ9!}micZ4(G=LR z{^Ugg9!*$(|KfG*YqMVG%{E4K@5Y$!I|H>XC&(^x|#U?tR9C=im>tZp`>bkd_G(~cB zbSEyZ8PO4u*sI6w-g~;toOtu&FQ|>ZezUuVi3v?Df3qI!^j-J}zQfT;WR|pCF&7^> z>M^Z{T;gK!?96Sc#o}^w46MvNq8+-iwN}trUuZ>`oSa+-Ni$5OO*FKx);=Zft!Gnn z)jv_2BDqt#(GmzbA?#TV*Bx&zd_NH4Q!n&)Q`qlld)9#7w+?I^Vo^u5@RW`Y*ya7A z2wBi;H#b#hg!G~EZ90Ufx1hJlu3^o71;rxJ8+B>u1k~lr=Oj|4!Z#X9Bcv77h0hZJ z@H;pb@BiaU7*o2JoRGIFe2<4TrgXa2cXxjJIDcV7zR=lgbDkc8f^BdEAb;ygK(3gM zt|oBrfMzgka`I*M$3nnYF}bji<#+BO_hVtPGv)%`suZ6cbO~j77Ss-TL~}sf3Mt+wesEPts0C5F-17t(ME*_)P8KBph&~ z{D#dhWC8=yHA{&8#r#yE3Zq5clt8N7Wlx$X4;^7BVNui}tC=r|$ z3!K(;uCGn>c>a8j7~+?u0tBX3I$&CCddKI(Z+3sK7JS4#2#iM!8cfEdwpXz2$>9{YaB zMtO;D{Q?qC6c7s$UJb#r(>=$%aq55dqT-SZrF&7t>o&oGFlKjAs&fY4G!6AQhpC#i z)jgWEHG1U56@f^0BDve%vw}O#)$X%J_qwvBVn}TUe$8ZM8Ap=~OB|JK_A;}#N@Y8F z^g>F)?F^-^*xYL($VCZ*=oS?4=98Mpjo#}*T=LVJy;p|m>Ci{rdZWz6r5G;5$@2< zD=i+`KUz<=ey==gba5i$d!DT%%D}`nSz)7RZr<_kxp@6%OwXmMw;DZ#s4Wjja$jEX zt03}&^0G2brnu;{0`($NJDzHsTl+9CbYE^OlHa9+JfgkHXr!Tst=YPBn}WM|P0ixi z+^^AKpsWK{=Y_O!XpwjUG4!9KPY-w;+XIfpLVHfqQzsT89Bi*ryUGltFP-8?v3r!I zG<-@e(vME+9KSV5PS-eCkFV(_O8>fOf;-IqJ&LD?%q<=>Fn9uqA@m6m0wW-B*Dzo! zzNfsdJAI@064us3V9;q+2R$-~?c|IU;b)T(;KA$A2X-9-qiG#lj2hWe(L^_~FRHF( zKYx5*tuZg}?Sf>d5UXYijZuz~j!w8(=DTjw(S$dW_V%DkRkc%yv6PI@{5u>H(A@{g zg*G~9$#!!Dh@$689CYm5;XJvwmjY-)O)K;z0B?gU1mphSi8KC}h zMvfi56E)vX|$=GD)SAMA|0!>gB5Aoe887h^&5|@=PcyrVb#cWu0P5X(hV$MG zgKahL1NPNAt>^O_Hf0U|r=KNAIhZ#_L;E%gKBdLhn@k*obMd*TX0h9H5saC+=X!7` z(5X2;$4)I#I9r47l(+0RpoPw<+g;=WkUHfKPuo0(e-v^i*^VWPo?1+`xJ+-=&H=w> z&VQ$LuHDAc3eH-cbt0l}zUN>@}<#cig zC%cr7)&^ENY$d`|%~K84ZJC`M%}@rNbM-B+B-^ns_^IE&p(|owA6at?`2N@1dGkm# zN6BJbntSX+4_i8q3C6j_=>=>wU!0Gi>>}v6OV5~rZw{Pqm6tCwG>f-J9`_kJEqo^@ zgN;P()A)Qb+Y$UquOFZ=JHhv?xO9xnwco8!ePwM;LsL^$n#I@PF@ehd^2eCkatAXn zoq>Zy*<8BVA?wPt{ADdB0yca5#S^nW18MD&l77ju*+T@x#9V=>8=!=q|DI#> zMV;Z5QemKu3(;dQXINJKe(V-Bq^zs?JvX@2O}0A~uBM~n4?QD0%h_yV4X8Bi%ngPI zG&(V6sx^PN`ZET|$8y0xV<0wfE(iYj2p1xO^)lAibUI;HRsn%fFgchlWXs!0_(m7n zTNs520Dhl1{Rjp+I<~E)7np(OR8_@RR5;zn(#5!lBf}nnPmd@Zt^a%y^YKcNx8dPk zKV>i|*K=7VrHJrwGpxZ|d|a0tzt1ZDFkg zSi}W~RaFlT8Lm3M1~Fg%CKCIj8tl@)F^65gJH*S&OG8Tw6ZAhEO1DIa_hDrag7AgE z^5&C2F&PNVd`JPdjCH8Ds&eC3=M~OGZ5`^n=wuSO8k2g{75YE7swYqfmn>%1<1h4td@# zIoqdD=-9Z}p(VuKGRjMO1Yt)y7(OpLxN)<>q+I`SR~mvY{>-19h);)?^3-e7th~tw z2VLCQagr%0>dF!%Tj+n$!cK9(@xXPU)yXZf=lJW^PQLl3LF*!_J&9Y(ITS`TGke)WujAR%tq7qJy96^r4a(D%IyUIYH5t^7mBD!boN z*zb#?-7$Qy&WkY7Tur|nZOutWj;F(tFqpyrb~oAW=&)FsAuH}Pyj}%Mx(y64ikerJ z5bd<=Lhx0ml&JGYb}W3@(RQC!l&BTjb8`!B>=AL9j}&#%w_$tyzEso3!^C`rGMxO0 zDN?hHg8VKGk=znz?%W_bS-iUThk0&scWS$da%R*(+w9IhHlCr!RBU;3fL@RIR^rmK zhXc_~$+qiCY5eA0DO7VW2&I>#O?Y{&U>Cb=D6Pt=rH|HK7Xg$4EqgK5R1Ni>Gal28 zU_5ryNE{HT*PQ}c9xRJ!n*Y}479|v(m{OcyQzlmEnoR|dd*_sy`RU8|y=+~?HZATa z+1BHCKZZ(to5e-YsI>-!Y)T)Z=WXp5=NNCFYfq)#y&#MmWQCj?*{Xl}YIR3RaNdd} zN+1ZC-^Ro*_X4)HK_MH3)#~_`m@H*|!9;4PoFMd5?<8D^4m-{~qA;t-aic7^%67JI z(3ZDGBs(g=Jw>fWj*Fv;Exz5_eKhyJq`m(wo^>)C5d@+lmc$33Z=gmV6XaG-wN|bO z64l)KgF|4zh^-^hkd$I+_0!MiH1{Q`IcP(7{7?_E^`fOuC=6qTY&#lQAu2vIKSK^T z3VuAD?E}iQ8AAp6NxQA8*2jIrXn~k#mDaXJ!j7i1n~Z$8ktDGnT8b0#nF#F@4fe5M zc~un$Y7l{)bl;P}ERA5a(C`9!XPSySu~j! zdJyPF$@$kg1W$I(s(`u;MHJC6>ZSW^y+t?q$4gMB2xQJ;qlURoMxM}dc6BmqXCF@m zc-rAr0u@rtlDtM}BuS>3z0Tu^ zDX%SmgR|p&n8*vgmz!_S&djNdDC4nIWo|p(Z(0wxYN~hU3A=U z$(Q!Wc8=M0OqA^L@olhOb+kaxAWhrX$0)P*gjBfUForKbvekL!4R*YSB_ftgnhs{}@!REtfj@}4QoYkhJ6!#^fzoR zHs2q^&`XZ4!%geS!*IjKh1^;PU&OMUTSLc^5tldD{L{D(HO%}E8!{_GTZQGGJLxV3 zK4P?LY$W&U=}%va|HyF$>>Q{*^KtO9alE){E%$>nUe!R&Cp4cIZ261X-_V%@#;-@9D+AY-1#jx?L=Zp&w|D7k&`Q*##l|u+g zV{66&s30BaM_%TYbnI)K+=!-ot)T@!aCyMc1xd8!S<(j17=QLMA#fyy_;+K9=J8eqnIxoBvQOFvyd>au#@+=@&4ZtFf*Dqgq z4D-_cLf}@_{AYP6jzlAB$`emuNf> z<(Dr1<9tkSfFl_Ik{B?v^N8YQN%aI4OzK~B75?Wo2J7UXKgV$;{Tot)v;V*i{A1uB zz;E&#XY!Qh((}$o|2hBy7+7|-a}a}rPCx=Tcn3B9d-)W9{`U^XjyeisYs-ngjuyV5 z{2S24Tz-2MJix24T%3vdIAAoSXZw9~G3jzR=Rj-LOo&&7HtPdJ5m0fXg`t92zAY0q|DSg6{bIxl* zp~NGLIvb5#3i#ee1GdE>(7lcK=!g>M}H_yGq+bHKunhJ6mrYA=rYx-^8a2IPR)dEgV(J zoQ(EQV5$F-m$&jEWCRBXM?jv__{XZ%i1``YX4vY9U#%s6Sfmv7Hf_mSnsxH0#FUUW+5#SsnR-t`?@=5PY z<;aH*ZMSToq$&Ny9{w^0%#s~5Gn=o!U#zZ94!(Qx7FSqE2(WPa9F$JjPuEO&F?q*1 zjE;}H^I253_j=E#l>6u9d~kp-0gXfpZ%fKBjD3~TWrhe=JhBkal6VXTW-L-Zw4QF{rWWp<2*6Me}B_OiJvknb+2>1YX=PbC zRn}}DPD8r{_nlfkIExMznG;EbxbuLW9Ed{+5=HK*-go{d5%K`_;#zQs+J!~6F2w67 zq;RAoE-}%K&)n2hF5qj7h<|O*J%8j8eG7-@t}?tKKcDzcHPn7Ua65{btu>Td#(ERl zY=VB(oF-kjb-Z!bapgo5)2a9Cbr>)P6bO+Sf5Z39J6QkNgQyyp6y%Hb^$lkimkuR) z?;T{VH>Da3N;~+H+x6+|u2JWnMcfnOW5<&WBMl8&L7amX)+Mq5k#o;P8dLMM1wlf@ z`E`DnO|D=?#a>Thsoq&<$4(0}9vHE&>A0B9cO2`X8~wk#wt6ak2`I!SbDNo}sLWe+ zx*jezB5Qma$c^^0dd@nIDfCh|nBsBn$jL^WK|;jlzrG6ka9_HvuI{rT8K>uiJEfY; z*so`!V!b~!E_2v*OjWL=ncItpsz~s=uI@e$3bh6Li~s&SSy@kD^Tac`|0gD_@$)qD z0#ABc_Id*1F=7&fnm&8fjcP%zBnAh68&#AO_1ZUmdysuAw{ zVl8{rQKCj6y|Yr@QuE;g8TXl0`fOicROr#sk#OW6aRg+Gir(yy>-I~Jy=2ZVVQsTUQOHQ7&o&Y5zd8@g!p zu}%*1tNh$ubZfjhZgkN%sFle$u_G#Nw{JquDm3oC$nGzL9)ENQW;~Ef7-Re#a`PX% z**MMHcz1cpROyqzTf7N<1A{PJ3K6&U$jOiVBDB8fAhaB1lCpu?me5VJH@-niH}NP0 zb`QDG$-*A{*)g-NZX0yj?;A@V^%?c8mkJ*;yFQM@KJyZ0nH!=BJN-Z6-ZCtzwhJ3Z z3={+u32CGo=>`D->F$#57LXVa5fBiNj-g|a7(#|lrMtUhsG&Os_%=R|_x*gw_xpR_ z{ljA%9GSiMwbym7bDis4QXXPUu?!=?L!9a{_XQyA0V?{--JxCtvf}R}k zy!58JC33C)WZ|Lriw@!9I!j>3`h~fpf>_2z6)mHV+C1pUA!d^L_{9*gW8Gm^nir6izp&?=)Q6ZjtKT2g8ZoNx1E|Mtb4 zu$zu2!@^_CC#G`%*|9?G1`Ww%0k zF5vVAwKtz!?CKw^;ro1oO{mA$pe5Y|d5vwP1Qt0(IEt__EIF8^r1>5OU@wrdGcJ9- z?llq>y^Rz(A7&pr-O&reiiD)I=<&Go>vf|a?a<-M{Dr_b&|C76;0szm4ci zGbnBk=*YH&J`Y*xSAUG}GRr#sp<=3Iv^`Z98&h7DxJiVFs{6V=K zut${CALHKz$0i~mIPxI#C4Cm|fz?F+-P`SpLHi@8>0ACc)H|+0juh=flShhDtk3#nl#F(SV)>0Oz@P`*8>9 zW0*nAcjQb(v>+70SK)Fh2{AiX5ThO#ivcr z@y&SHEfH7EyI3Yr4MOB(NyIQ^@0Yv&6cDQY*p*UWKU-L=)4BkHk0so)@$mdH-!wwI zyQj1MpTaASN#FcSY}pvSk02NQ&1=!0I5NkFJ9e;143$(=)foc{sagC(G1>8TzE>s!}rCVBpu|d5JiFVtzO$euooSSIzX}r8Fhx;Mhx7Vd_8}0sB8a6$?yTg_7x0BOnRL>^Q$sYW> zhzM|WbJlOKaGTyI^culH2!B0?Mk;1Il=9#YXA5VYjly&$rpt-f#Z=g$E+wYo*+bPf zC*-}p{fAWx$ivIRy>H~AGW57ugdE#Rc}BpH<_xK9<5QA-f3!Up`3m!q`TCU50nzJz zPeL-E4Tqa}+L62g-70rMVYZ4n?p-CJn{D!@l047hk_FJMhNPtD0OD}q%3+|pKSxU4 zjEe>P&jS6N2+*L7>7SZ?ssD#DH11>-TDaYJGgi45=z)6?7!)LYvbVmO*TOf(J%)kb zzvw8m>;!}^O%08km3BSrhC5hy6#iBblG~rk8@TuJT@bbsI(B46`)EFAiZl}=WBp-4 zpq!tfSQ15GG}GFJMQAhQ6A73IS_-<`k@CJe*cfV2P*CW1(_NgN*6rSu`X;~e9p^9& zv>S3oUR_>P1Z%Mims&X#^#!b8f4Ziw4WzH7fWafiB52q<=|XO!QB=VKqt>1q3=WMa z(^zheXq4>WzWx&cFt#Q1ucaU75-d2mxtRlNZ+{)<$C%BdLGp)>9sy0TA_~JVU()mr zEVD|OxgImU{pVS5um(#|>W6V&!91K72g_asEKjCO(#9yf6y>L;=HfnSy}9pQ_Y}X5 z%dE3Br}ep4!_8>^F;Mt(XQu6pRJTrUIJ+fNQYq zg>_em#3fhAKhm1d;u}@{6!dnFzu~}LyQq`za}xew}8)A@iz-T z32XQx^@+UW*;`2O!%m2-HU$UsKmX@|9y^$mSn;b~biTp>lbeE!$-n?rL`ZuH0Ain$B165*@H3Qayu0W8)D%Sk-HIQlbSjMJZ`woZmM3ucd;J3MQq}9UAeIScOK8U<=)Z}P zNy#moKl3dm-s7t-ta|;-!xL-^KTrI1fwD;_E6NiIDMnmIcd7dNYpDou|BZk| zO#8z}!FL0|oj%`P3o0u@^pxqp&yT>CeT%5ra;MCa$^l>pAU}AR68kb9A5J=3CrPW; zo9H2F_j~_^^y$y0>E>5mK>MP+0NLd=-2__|FQP$?v-%L9INj zDnY|ijPJtp5o3%2q)fx88z+5Z8gQ4IVb2dW;@p-?6;pYtSt~)?b2XW-*<9Z(Yljlq zYuZ}0hm4wD)i|$q552JPx;US(we9W+#YG=WBSlDsgH`m@l7NkGMYZWUSAQl*FMrO{ zg~)Gvl|Rj}@lnI>V55EDg$@Q=Q_|LpJhsj*d106L((=f`^Iu&iWjRGTPJ0nqYywaTB!F8Ma+C4vSi@ebV@DFbBqOYH?qehJC|PA!vwFu=?YItTOjv}s zc8C*&ynYsfAvyF)lSYcmz@q01-rsyY7}0#w(D3imQU^W-`V8lxwQExAvfV=oG6^pO3>N{=Ra8CDO zyY3fN4%%tpR4L;W{a=#d9D%=`@ypd26T0A|8!m^LT`LUq1{K@j<54QAcEuNu1Hlt4 zEBI~;m9SU|**GRif55Opzv+;Uw}O_#z4T~#$V9pgYre{MW!K*Jvp7`{P2>s!{h`7- zfa)A2A5NLl^{duYyYZ*9zpw;`uh{D}6;bd8jDK!lf@stz%U1hMKw{{yRCi^{XhoG| zpD=ZYG3ccTxvGE+cGfDIRM7dYFU7sShQ5IGmq7EUt1k(%hZc92?j|w)sc7#2+OvOa zT6M%XG(^N(Z%t&7i>sZ954xW*tZxbR0}F$xJM`Nl;Xv~|MKUNe8!J;kTW=3K;WHN8 z(0U)_*{;4)o0@fpZ0Moa$Kw7N&SJUjZ%vW1URz6m5&WP<#rVXS6NY9% zbIcQ6^cN$FBp=d@J3sx1HN65_^Lk{_Bgke6Nr*N-TCK;Ajm4QuV{H#|^Qxdsdy1g? z4~o8C9lY6@PA>QsBaQi}!SBsu(VYW{x-bmaWFmxX`LJ+<55VY?D>*jJ7IAqfktcTn z-XjRuSZpn$25YSNute;S-MO;H+JbLC-<41G{<#2mp;=L`N~b zxnIY-ZkC#}X!jd-VM^OSUF~HZJVal*LTuxqbQwaP(t0aPNYZ9DYW1TK&NMyE$mV#v zn^t_Z%9S%{zx_qWmB1ixggc$@XYg;nbs4K5IwcZ$GEVc=YU^0>-Gzp(j0t`+H#gV3 z<_O0LYg^pz_^Wi~S!;H%?v@+(EMaR>KIvMEbg-HQt4nWRn?eh3GFY!Td~z})mxB8> zbxO3pjdJG(VjwUitfYR-nvjdNIC%~72;67GHc7NY_s1WN^8rAWOm0uS%DNrQd}9m7 z!uXdktP!|kQvNK}GP})n)fmdn%NgzhBWusgVHQ4l?AIrfrp=t0sS5A*xc|Xf<;V>@ zMytlh8bFV5aIwH9oG3o`r|d~Q&!lRXXJKNn+hnQ0Z<_pTGowW%uarij+l5Ee? z-}CT}f#rem3Fn=jB)4xeXE(|EWC^tHHnN?&33Kkckq-dw4PYIk3KvQ!mV87fM!cp^kLX^+!4X&t# z1jzpVAPRw2Md7qCJ#|)HS3aL-J0&C0aUbyT6`e5Kp|4mupk@xTQG7W4Y|HSqh?y-j zrA#7AS2Z@_^@lHEg+Wp;IeeZ5ev1gUilSE4c{}=sw*rz?^yA3KstaLL7)+z|y?Yh* z{n+Zw;HUn=l!Vk>f@jO*FO$KkicOjt@gZ-s&c$S4ZC1#@gazgVCfkCZK=D`5z_*mS z!RL*kz=<#Zp-#)sNSpu2f$#p<_Bz*ko%C&n7fK>*Y+?7?>9V2{;&OKCCj8A0xlhJh zag`D{p$b;zxiScvis)m?>(zf7l{95nOwY8|A+IEiLxRukG32IRR8qJ!QPR_8-3vq) zOp+A43SG5`-4R6cc3X=&FbZgUp*%mo%y)hnk^e4a)n6Dq!#3a$O1jRvY@w~8;^nl5 z-{>%i(4QRzR$<(l=ka2(fW4bUK;@B7rM)h@_2q9#ty%FMWQv-B;d_;dS?v<&5-}GS z(Xn7v5gEVxR)%r5)mjJE&M>0p=;zta>~|pxMix$}76=hCd3WLzK$YNWhA8^er=vDk z?wd(LpWYc8TJ*5-wAXHP{j+Tw6}j1J$J)x^Bf{}-cJx0_k~ii7Gshdw1xnE4 zJ_!_eMM$D};^g<5aVe{=tq{P>uQ}FD9BC6|;g13g7hww9PYRkFb8FLD#VBxx6E(wf zB@CG3C-<045EuE@TudFmFSCvchEV0q4T{)M^kEUH@8lFohVx{&h!mWi+3#;e-c<~| zk-VF;A|-171A*9)h?h@m4Iy8?a8&ds86@1(NoZrG<0YEO{Za%++Ua4(@J&|7mV_k^ zh=lCGloa9`Azz9LHL@Q{$pYAKkn}Dt%d0bl?@0eh zQ2-(ROLEs)oncs%cUg_zL6T3W_g~ZlN{0XV1prvA`H5ecNMX3(K&K5n0{!1l{TFxL z0e44-S1(;FLA zfajke!FHIbKws*GMqdF(bvVlyh#(O;9&Cvmin4NZ15ofM3<-T7WW~hX{`SbN1qh&e zFWK)_Tg0GE6k&3ah_8LaKVp}bFmJ1)C*L=>tm*ty^QFleZ~Jb&gMkLPhbw)+M48nk zG~gtI$pQx*Q*|Q6DLIIG8N(&%akgp@&z>YUx9iqoX8>~fKM2}>OGGy z@Anj%|1R8}FsQw&28Kqlto>9{>WA%ZU`AX>SeQ|%6FYE{O{2MTtYKfj0_^=BA<75J z{|P7++wwZC!?ckodLZbJ${<0D(ldsPl}7@yR`&mFlqbIWRW;t|vs?vRCYf!${ZVJ4 zNNPaji709KefM?uH%udggQbzc_?AhXK`XAdwl*MM-Dv`fLwcnWx>2K4%?}PtO`H+z z61GP7Z|Jk2|EQkM(rY!Se_lKSkhg}$62JVDE(4EQT?35@ufCwfL~URV`DIm~pI0Dw z{pB=xrqccbS+3+(3-o%StjDP4*I&fXw0|Q#>ukYRk4-2q2ijl; zfrRjjFCyhZpb+@Yd*vG9I0qiE#^7x4Qvv@jGtP}b9`JRw_&@B$jY6=XdQ%14-up8$QmIMReT*DGMB`Ug+k&z!N1_pqtX>t3bmseYRTN{w^ zcVOoPX)^;uyV9GG%be~J6nAYAcZ+-dHT{RuS{pkeC9pi}Gr1zlC}nEMkMDvyPwv`c z?)E{XH&#+#w>+)?*zXU0zb|#gKrC0T4<9|0l;I!4c+(2#=B&AhfV+El5WIkD_MkN16;+6Rg#Pm$ zaDsQnx&QqO3d-lZ+UPmp<^RQVxVxEg&NZnS>qw5xlOHT9pdaJRr8^`4pS_lrB_G)0=X%+L5vQYxNdRjXhZk1g} zBn{LZlhZ|P_YZVsz!?~Nh2z{uM`rwfk6uLN6&BD7JAWtM^R)4}WjFQ~;C@l2~>5@d?U0LRH7Q|gfLA)!?wtI}q@CRoUKPn?Lw*i@!d4V} z02(H7#c~2$uf>aN0pD)qW$m0_7Oumi=HJGR*>3vKcb ziwyP3K}YCi+IP^A%UVCR5&|jsw#7Y$S62niT_i{s}#|=R7|_IUt%N zrt2jRz5+Jku|R<`#mncZi;vM8d{C)zWSqsYnuL!1uF9RQjK5H3wzqgMW~>4pEI?C1 zSeKQP(5g0Ne`r87u|$srzkv9-&vOcx=&0+sfWjDr^_89IIQZ0I2$9Teq2{1zW9Tlha8^pe z7IVmXYpe(|a!(lmO$2%`yqI=MUR zvt5n8=d^YH)x>F3$* zDkr=%XC&b5F0WocJkF%ZfdnsNJ(@|K#g;J&a4A*A($@d3 z5R!Sc>QZBJIm^^7hjH=Zd)-??8YpUmz^MDk$Kg&z>}kMha3d~DQ;D|ACU;$vRH4N-v$MkWAPKbARep1) zfZ#|-eTbu@&Y7*L1SvOV)(a#ufWb6Nz5vE&sWVLYty&^Um?fAXNi)v zu8ei%FGl%su%Gt&1jk?bomiS-2@})WR_sd`I$A+%ha!ToHe6+0=C%6m<4OM(waC4^ z<8TWN-4ws+IKWcq=m^^xDPV(?Z#3rGn1G(AIeOHvlD5)N4^x|jjGB}w-)#Kw;I&tN z_x8;oN+amApjhHe8mLLlfnk0yy4fW3-Ek)PjTBnHdfSsGaAJ=_&94Crx~UH9oSr(#!Sy^7vL-Y5_;& zDfoA|Gyi)QD4+cc*{7*S1hS08J5}1RaIw5D9-Tk@VrH2$2pJjIytqVDGpX~_>hO-+ zUZ`+xuV->by=y854*gzWJNvNO`P(aCm>vB$x{Feup_77>wwa1AJ{~EMvX3ueHDLk7 zFc%t-aE(36H3ecpris0Rxq2@}<1K}#uCmoz5aOa9mv;Cl=;>Do%mH9nw?C|+)AR|! zH$=wI+%^@H8q~;gU3`=$udK~oXaWNQJ#~DXWRmPYj=qsr{&;wPubU*2bXrozN=HU4 zf$gpK+mtE0HOFOrEj`K2w3SV(Fcs!RH^yA^a9NBNN)zr~Lmz_Q!^=Lh{<*3;Zddck z-|BcjP}!%qs>HCwkK`5q=gd&9aqgUK^w0xk^IhP60{Yp?CAQstio{%Yu#6suj}31| zQu%(;Q8UZJe*;?a9>wh8PG?Tw{;4Jj`6~bPdru!|6>)&!!jWZy#_63`!)p1?n1m%S ztWd!0O>e6;2C!j2tRd{j=J(ZgjGirYQ(-i~l_kJdT3G6OktjU4?WtR%zx0tZKep~M z1=Q44ZRJ-3m~$jzcpyT72_PlgOrD5}_^C+gf@H}$6jOF4`;k6?12h^o`3q9s)y^Ax zpX=3-0GRpmBbqKV^l43if~kX>=N?3A#^R~SzEiS%y|FRzbJ+(7@b>m`6@^@{nO5Ec zyZT$oe|A(FATiv4s;pS@O#@uz;!hzuYdS2fuU|1RBX^Yd8ltmiA?=r6UQwOxOuy&a z@Nh6p60(>+u1Vm$ihF>)Goz`YGtJ}ToHk~|(mSwi9K^Y9)K=Z-q5$BU4y-+w#?9Ba z&m6D2$p!V-N`l=8`5gonGLG#BPAh1$Gg}^$Lc+f)F0u()8U3mU2~GqDb@27K(ZWa_IG@2FU$cDxX~C{%JS?)FZ4`u|BVmTbQZEA^+V~ zn{}GG@8;hB_xK<9{J+o}!0CVg1a?al$d;*GDe_x~g|MP*bgeZK^!`fVG z^sPEB846PkOL)P3cVx`n(fmiNs4Tm&ye!`0n}UO*E7+0z-%x;pB6!C>m~jx+CF((FVkEA=kN|=6ho;pTJdacY(b>Qequ_ox8+_C?B zyC}q9PW_c}5y4eD7i2$+{~&PQO*QhU!ju6=?m^znB2GRtHFL7TWKK)VLs4fGDMxW%zy1K)61O_Y8*Qzu-mfQ%XI9??`I+V9 z?JP7!rjmyh*Y{maP@%c6n&+K3sIG0o1*xrPlNXwvJSKa_OYaFUG5Wx-i_9=99Q*0f zAs~Cdg>rdV70dml@%h&ffX1iq?J=`t5%S7-M=b*Lz!0R0klZ;`0pMp`SS?VRIcb}1 z<9(NFFW3qUR?^ z99JN>^xU7t$muGp2Ln|O@of(^L@!d8-s1}{Z(VBai}YLh z@q=79BQb>{_A69CVvNctiBm40KH~VuYey!LnnQ`|0~a@U2!x`sPX7h(uaMmI5_#x)fQ_{bZ0g6)1oy~m7s6m z^=4sgLV9jcZ;$2nx@h6&YWi92JOf@&Z4cLHb=48K7BzAkC^iJe$eoQ5Y?T(v+0}bm z`bMCSe!%>tQbV;z!HNcrZUY7rT03(?@W)FN^FsT-`~-dHT-V(+uH1h%##~)0=~axV z8&x@UJ4r{)>yAw9s+^xgllWR^l^5n8_ihyLLN+>< z@WmPiY-%bg3p7_2vo`3NV}OPxnZ04f#mIrfD40-x%FyG(HN9#R1$I)Jq)K*5q$ZEr+Ab z0pNFL0V4%#J$@h_r7eVrF067yW@j4On(~x)!M3VOHiy0#XRo5ef6alDjxboxV`^Oh z(Ww;Z>ZyNtoWV&gGym}QuZOjLbhTm4`o(D!;aESaukXv*XYb{C)XniU++0_v6L=O% z`jf>cOIgdK@TQ%M?-gY>y2jtUkFPN7xRv$KuxTGmPVmjO>qm?c3*Ufr+Atl}=2mJ7 znKdx+A{!A0$g$YmE%y|4Me=1Y`1u-UhfrEg7V`48Tys2q3iUB)%!IA#5IkRoJHa;r z&(0!loE|mEZs? zNU_A;?yQVYKrvQNmSKq>3!Pk>*?N3Na|e+a_w*?quKFaA?#)su5`6~Iw4t=ByJtvI z4s{eUorw(3KZ|sz|e#^qS@LEE4XlE_k z@+Ur>p%3GAz(hX#ZqLG&BAMtxcll`L#xZ4Jy@ZOEDhZdR@!q=7QXL-d$0VYyK$9m3 z!N#L$z-7pebt%ioRDs)w{Ni-oB)4ar$$}Se)iaW4qJ`v<@Qo1M0nD0&>w6M@zqr2a z!^+lWk(x{iDDk?FPK9^D{zpEm{tYK0)gN0ZzmOimO0$|UUNqs@WI=XYSe!FpB)T7M zbXDrgzIJ*AHxv<8qIY*AK3v7{Z1PRNYDrjWytHrCOSenrHJ-$948fBHY0xx82vZm2 z;qlUUY3ww*UwFK_pS6NUmk@^wK&qcdLGDJN>(8yxoEMfOoSV(>tGw4_TR`yic?EKb zSps#7U4`lMnR&=q@DJmWlXI<3tMSHzU|)~g56VB*UA1bMNo4%&9-a#8p=0*JX9;*T z?Ey{5oovMm9yc*h!ev#e&CK)i=>q6z3|rJkx~*#Ay4j-qAzCn?dCp1UJJ^>v(}9kc zG+qB1i9uu>{Ju4WNGp+uo|bfwtyvzH(A}iQa%BPX>jsZo$0JC%kMl(+H<-shk;^)? zu+UaTWk}SanwFj6qRUTIqKPQHy`<@KIgh+4Z%E{PUoAv^d3~KNPL`8nn7sbhFeU`U zdEWbWW%2ua8=-^qY}iwz5P(r`&W4$mmY$1eme$r@*4h>?N{bLnW&g6WyPDU79+2>w z&-b$wZrK!m7N18rM42`SrE>x)G*%C$bwVSX5I+4gEu3)J|k4;gmy%}BA(OqwK5A5`Fu`XQGxCH!R z_2Y{5@2$=->1FtiQe?5-fiTNh>GKy>fL)dV%tH>y*=bAw3D3~T(BoW5PhhS}#nkj^ zr-45AN?yOHua%aY#s!Q&Auo?4E0r;s1+TLOT=+uimUQMDK9kuGKt_=*=6Af3N1H_$7Y5IZYuTC>#Pc(9%<2d(a>dW63JwiA1qa z>Bm?TB994~NyX8rZn}LG(0}mr5L5OkFz4;a78B+AyE=2oamlS&Km|mlYL}kIs+&-v z4g)=qtXQ+5D@9ApUd=d;uQXTgCqt7sx9F69c>R_>Cb4kKIt|rUY2oKriTY$s5+`Iqa*Wj&;jvz|=ytf@_QWi^ z++x8q`kYw!7}6uZqF84&8`7q%NJg#jc*s$7YJW-!p7J&-kBI#*46{xNJNg&)gebq+S9Z3l4wlyTy}%v^i`LWk8_u% z5r!<64TRk?PvogLc6GddopuErR{3%Ydr8VERhy7Zyv5D^Ccx95IMHHZjFEv4rPny#ER#*Y$2`(^M&PG#zzJ0!6*dSsqYCp@Kd zsngyzN{`=_FKfI2*BH=@ovxKY>R6wvL6Wo_z?`4KM|~y4m1O1fpw~+q53Wt zXwE%8bUUhJFAUn_cK&+4n9pibm!2LidXjrkmC7=+`U_j{G~e)|>z&wAR@t&vf{T*$ z5`+0yTGt-6YK9tD*zFN?v!H9cyNkscs%o)Php#y?QusbKiFw}VSUy_Q)Smm=NlBJ` z%WWDmYqu_4$9y_mtXKR)Ns09AB0FprJ>pU&D*Z_v3aU?fl!wwlu&LZ(4|AK{q6QrSHL<8WT}hS@cY%Jj5_Nv z)zM+*n9%V#D7;2zM6=4rlR}lArPg9x`j@ea=hP-F66yjkE`BCJQM;b;-90lvobp__ zcT0A+1b+uGaR=<&)PXd;!DHQPdMB^xc}oo4`NN>$gxQnnWCdHmG_6BEr6nE8VZ252 zflECxA<5+f+qG=nV64h;KO*ls~nfY@4D zRo_RkIQ-qK)G9}cTVQk{pvr>N1jiVprm9yICL-zrW zbfLjMJTHMwm_cKMP~vwM{qLDNQ&N^E<_Wk}JCm@_r!MV^%ZfRePsyIW#1V@mn`~fz zO)WH;_VUom7$_aZf|Fz~NbTK2-r|tqHCfIi!(O1h2>P~vvc9YpdZEth084>=j>W#b z4Ccd+0|%($;gh+(pJ!QHE3)0SU9Y>$hJmS_a6}&>l93i$wV!Oh ze)q8;Df*mxdGO4Kpy}J|>H5>h*OF?zWNThy=MeZ+LHcD{w8+`jPP(mlCVO4cEe&@V}&ASTf~I>yGU^2=C=pLU(F%w$WrOmgiZ z#gnst0sYvM%{ohS*4k(jBK(NkBEEV~AeB&FGbTy3r#-h0&o$_Z$?YhD1$xj*Dq;oh8+`yx7VOKH2uf#F!WD4wc1T*d5zunpqZ6@ zHuk!;U?NP>s?<}f?j?K;j^>2ad^9%r=d?&ow`+x^^9L&KPdq*eH>Y3O38a~N9@R45(LUW5d}x_ym%5?0boHzK1qlYDUSm@=s*UNx|_OK2+Q@`}8WB z>{T!4ZGJ5}skp$tQ`W3EaqDg$Y_QGr@isZ&hCT4zWqDD58+;LZyG86)8RyM1S`BwA z2B#^%*E=oJXEm;Bu+9-WxRJ~KH9y;Vt4~ix%7*MHY)`r!9y-t4AtB$O>15oLxNXdD zsrD0{QG`ACik?J)VA9y-4P_&X50$LEw5VLq;fB8e28zmw7+Tl5CtF<+AHr{~>#9wS z1Gz<3KO;(&7>pC#6p$H6qeeN;9nl*#OV6id^GEU!WTo}ZukEfL9wuZBsYQa5!yeOz zE`WG3>zn-ezL}f%}uV# z+&v}3c%bK*$3TmPf$Oi$TJlh9QJ;l;PqcCda@r@jI! zNjDy~#fnzqA#Y;N5<^Tyj08+aUa2gwiL)dy5pCJb34>4rS{Tl=Q(MwHvMDyN*E6WQp>JlJma@@2wx{|}xJ2t6X8_e3 z$4KOn8m3&DvYJMjLmT#$d$H&WTV`NdG48s~rm38z-Ob9UmAV&I;Jk-LzTF<1RKq!6 z=X<3yG>7S;ZnX8-9xM#(KG8pdomqN}pgs7Dzo#s3KpTs{!~%k2W8())4i299G(aGi zsZ|S?fNAQ}M=jL{FY;XgTe&h*>5KNEY-ymoh=lXvyaju_Sf{}Tj_$bUZb`YiwkCAC zAptlhg5bHgnDXzwcbVaG6zf(j4+WFwNU!&T2O>3%jBWwnHJ|+(K|ph5+EJk&CM+zx zv*_=h@J%IOUF_E{T%*R@`5Ea*65oA)Z#Mx_L0h00MaJz*dz)RlXG0xbsmU_n&f~6SaJks!*np_xn=rPai^uS}aoMJ`za%vK!RX^Rh zQuIbpMKe>>stx-7=d+Q?dFgY<#t#6pzsEm zGxhicb*(r=GBN4IT1-!znk8FTpFmQY*ChLGfH%;;5)Tw(X2vX zfyX(-nz#C@v4S?pry|qY^5Y$BiMP+u^&*M@9dSN1zqd;WP(oN$a*x5efJ##B`k!#R z(cJ$b>y4YtPZQP8YXD%CHHn>@=WW)Vv4R#QM1ECOBsZ}gC00YfsP#31yrGE+x^n(y z#HM`$*+Od?+~d=^9TLzB=!Xxpk6Q#(H0qEno6EDsV_~j16lQVS7$L`07nsAbV7MA# z`qkLaGZVm_3V?|m`DLm#X1b#dIJ=a_j2%yX+^@cIJpoT32d-9P+VgNM=hTeXQt z6QJOAx|XVnj_)^Pj*mW59Opd3+_j=5v*$T+-jU|O=32Q^O~dgCd;!sd59rg$JO&)@ z?%|PA>0f+ay6TH(o6vL5aVpQXciN8~TZ9R|!IOQZV4$$& z2G#zB$L51$Vw^t@&h>{Sa2Aqa=#F9O&c+vokH%jjjd{cs^|n9)ra z*L7K?!Ov(LaO9e!t9c|O3#mrllzO(J1%XKImBrK&_l+tioX*<{-j-3XtW@FM_}?e@ zi4H{)Ryzzid+*hh+0C?n2~LZy^|;0cH~ELOy?^I(u=6c)-iDPSwzhVvcda5O*xc{h zd9G{aMWfLs(ev{4(?T^PQ1MkD{F3;Qk&6yM^c~lOY$M3|FK12b92$N)!Alxf=+OEc z_@(O(7k7ul^|v*uk?W9U@uX`GKLet}-k#d%tmq0qK7#w}tS;f-_zxE7CN}}dteO4F z>_7wEs3}`X*s7%3((h#Gv~WGn(SZClXm`-kh+(19d2ZDhw4>6w=cikQf9Y`38YLVa ze!`Jdzb>O1v6Ba~BT915q#1S)ef|I%0w`F7cfKC_-Ae`&(Z}XUnVK4yHjHOD>gZld zrML5f<+;{>Mx(k*5&2GU{&dRm(dGm3Qy*Jh9M&xb@5Et)GOwHBV9~pg%mO>|Rtya{ z9?*)Z$$c7+a2MO`#+#nLIBXxo+Z~>$5-HHk(?=+Zce;uapX09e`;Wd%jE{5iI;Z={ zn)gh2(X_SsNR*7^kL6u(Y<&_QVq#-MIMpo)d%Fux`}@yol>}qCn2wKGE6~QIJNC@W zcGkj!j7TVgo`I_fS9xn86wro-VM=P5&PtDDyi6Qpld7~;rJSuCm3;Hpg+a~ z4tL@0PzWUzy*ME3kZ^2JWOAFJy*g1W5FA z!Z8t zD~}|DsHVCK2z(&BqF(XphA5$@T^XfdAx2EjB)^DYQjINgy*Ni>g;FT$d*wG5#jKef zP8N7Yc+<9~B578#u>NXcF=#88HT~Vjj?_K+5m&#g@KX(l!rM$b1XX6ki`1IE7l-rp zYMPl9HH?!_y|EiJqke-n$Ln1jPFTSdwch@*s?cNc-3c3SzKbb|pXPPFxD6qamD52E zR1;FEEc{aMoR>EIwpi2YD_!!oD||{-QQtL1e0}cT*q+`pZmL{-$C!Ei z<+)QPc+d?Qi=dqi-bB2N9=;N*d75T@-m8mSk!NNo&TZHxL~AvR=AcpoUHHiTOIW6 zPML&@V|qqSSdGJPT?Z{jMEMz$hhyP%6{p!R_^%_j+{KckRn7ZV!ln*Q3t1CGK0tkf zgJ-mG1ufhMT!&}ak8Q+-xB948_q7n0-GnIXic;gQ>Z<5&jwlBI0;t_f-TRp0S~+`d zP^2VB#TY0=RDTwXiqEnN8*27zvgJ&AJ2&e$MI*%M)LswsFgi))Qy_fyb~9)1OFn#t z7t?n+u;98*C`QWjDPX~KZjx}u$!=}i%9!AfEebl`41RD5;*Y6x-*7E?*qdSmvU0q< zDhW1nRqIXF|MYJ26#~O|X$2?R%0rkD0)$KxopND`6QSgz%^1S7YU29wQ#$i%*zx#XOY zCr$lY9j*|leccaF$%h`8v6GYMfay2T&Jp#_MvwgD*yiGNtfM0@t3Jgodos-ci}{saMV6BBfa)fOR89R#4NmOWntVNXc7|=W0)1j) zSc9ijT%jJK*MOcB;bhBW;CdfkK)PFyB4j~?IdOB)P+a3&G-3dyyRHrF>RZmxLvrFZ{w0U1wtq1TeMT2k##i9}3H zBz2q8wUxE+VFD-Y<&oPc<90p_gzJJE&XV7-LcP6d`jYA{ja9e<6XQI5-ZMbq z#XmM684?P6w{3nuj;h3J)k*wjt6s`XLukWlzsvplc zRKa0l=qEN?_9d*`N@SEiJML4qa^a#C^V5^QTF<1ykge;q;TV$df2Rz`XPbxO=3x?$ z_W$&S{e%~MrWs?NH9FrKXh&xueo0&8=pb0^dqI~yMfq_{cQg5Ze1o;Y-hS-(-`{VT+&YAI zi>aD+U+>9pZuTx`$=aH|pV6veI@R3>CdyA|oIh_{t(JOaKVv@7ZLn&$Ea3&xnxdjf z!(|>8&DHYbu@^8Yn|?qisy2I;#?GL--%dJQc2>2@o!R(1T)O|@TDzYdTrm)4Q&jju zCRaQJR+H#GlC)j-Ml&qX0?rr3^YI2pcFHD_+UD2#`byjm#04z_<{Mi z0>_iWxG4+)5_C7!7V9S%!9v%nv!F;)@6(~;bZz=?)w|=L7aG@1I}ACvxn*W`OPb#! z#zZCa>wHeuUzQBQ9dZlQ!7scx%DT*NsbpvdNQx&DGD+l zI@=jFxQw43Q)u{gqflNry#n*#$Ykq0skOMVbrBgV*Jeic$(&OTm~jC^1!bAzzeu)X z67dw|&{tK~?x049i`Df%YkN3#EMYWB7oG-)$+k}wK@!!4eb-JASd|#g$z(LKM z2Xlk37B<@RP!Hz>J7HLM%4wJYS*R_Aka0L*OxkE_o=37Z?Hq724mdMa)|N|dXW{sb26KQ zfM^D2Hbw6Y9mVS$_%ek^qyLS+G0-t*HT-c}Y{#dHAe@nZ5`OE^^Q8XB zLyw!2)m^1w=aE2ZnjdowRx&t25d{VGoBLL78vJlu_JbCy10<^WI%};Vt(tP136C0c zXKFiwc(U?oZXlqM8cOR+3~?n%z#;)!=M;dt3^@tDj*6yPSt6o>8>S~wxUvK%Cc)P* z)a_L4c%L!H;SqRk^KFH8AdEQHjB7(S?C53HjP=S{Aqj!cQWDD=AZE5ovTov{r;a{t z7cfdcD1jrlFeE7-q4@blC!(l)&uf+}ZgfoRRG2zf>*)yfF@u@dk$4b?YhDTy4%7QN z$2JZ2D6o5euPHiB`A|1#uaqkxDDcCS(tl7|p~F{SqdD_+M4BRh9bCXFKFg+Xe${=& zEHgL^5odoU7Z)B5Y$3{@ttTz9w`21zN;wJCyQJRoYpt%VB*`;}V7u4Z*Dg6>aVA6Y z+|~-bY!w0&D3lijQW1sK+-)fa7E1#<_!voD;saLMMcHMD0Qc)gd7|2Rp}6>Qc&M{x zK$pI9*QKHeV^AIGdeVH?>hSGL)0@n^^mA}c_6D5@r>ZO;wfO!;3kUip4|y3-tsTS` zR@d+Awkg8X4fV5E(x(Atl=^L3^XsN@$a692_;hVl%I|it%u3XlS5mM6Wk0LAUzPhm zibFuP?LI;s;!2s(9(9xXp7B6VhQ5ept{Y?0+P_YEW~l2Qha*pp>ER}R>86z2X7y7T z6i(f%^@d^o^U&{BtKAroX7pige*5k&+9 z6p#)@y1QWz>Fy2zL6GhS1rceH7`j8cI|Tvh?(XiPW6t6mzwwgaA{sF28jD$S`!T$eJA?x4Xc$#XPwaQRXX#8L*U8RHubwR zTAad(>1%neYAOxVqS>u^BFv<&?Gys1Ug7Fk*E@;HTdkkUE(#MrHCgv|X`@EJn+aUO z7^1E&Ly|;CuH@rMou@dj@=){NEa*nr{LBrjJCcusD*UeGR^eE$aZDY!puJNuecWI7 zn>FBgFQK4f1EhO!JK<7(Me6b9_-H{(nHg|l@g#nGhvostn2X2BQHf0P^RD+>WDRb0 z{w9VR^NYCrio46w=uWDZ`{4$qO+R@nZ2Dq(?s8n`P_^ZSD0SJnl9@@pmxZpJZej1G zQF50EpUctjcw%p-k2Q~!)c*Wbr8(N?!VSeCu*l29+|7>qzAaMvdv?|`FFy<2s1kOW zB5kNowf8eYPJ9|U`*+Fr`s8;Cik(1#@_1Sd-JRCoqCo+rzc*HYmhmz^~ zs>>30;$K<|=K4D)n70CPcADaEw1LSX~|A72i$BLBZzT?u#Fve<7Ai^3g;I zk!+&9QYwMk>ti)8Y)1MDwQgcoF1eCI>^H($#+H?epkd}W*7cQBFT)P8k!<0aTM49E z_7ssa?=y^5Pku0PqD!JYNCcLomaQZ{V690$+cci_8j;?cpjm~$EuF)L5@#$X3gWqa zejWG}^mlbN-Hs<*1Qg79671YmX8lTqZ?>Hu)ST?wG;i>^Th3IiZ4Sj)K!$P-jKdwE z?zzRqVE4dgR8m&jduwgtLc+lH=mnwo9l)^N9L_~52%HVm7em0_1ip)J$yU8hv*8D; z(Tl2J7h>L$jJ&d_djF%ZYdA>B0^aX{Y|Es5mH;(+jS`3<@7=f+Vb)(s2E)X*j~>Ft z(lr_O1+-O+y_`&@KpZQu5KJ$vn?GvgLc6ocEIA^1EhUFr@l$6L{kkkD= zi%$7?c9)}5j<(r?ie#Jdj&q7E8+Bk%>C?9Di(gwXF-eppW#@EWw2c=4UX;e7z_TL2 z17QAR#hn85)7_=F8Pv9)X+we0R$k(u)uFY+ou?nik=32LzxWQ|1A1fz4(ZqtY?r=M zir0WxkkVv~(uxBRUQJ@&>GN(XF}F2ds(gxauBG*TYz6*|U2AuBQoa-0rV>btQO`6v?$^#SDPc-}W z3__}&j#Qo!WVEZuN*~^?d!s7I(dxk|Ig%JGwLN0PWVQlks+gJi_vCo%Ut)u!jh(r& zof5=GGGL)1Wvqzh!zb)zLjMrO%bNZofq%HUTqvs;s4cEZzG)rIv~erExW&#Np|3Y8 zc01x3x`waz|7Iwt5Q1BEVmNU(7)_ps0XyjGM8l-hhoU6fD9kdo>lzid4$5y;#Cuzd z0@oJ)n!g!)tsJso+H($H7W_8hVMhIJp6Q+%iEnh zb!L6#h{>t#0tPnsrW&h}#93F_tfp9>pr z7u7R}t%XZ9X;}Sv#CLyH~6b>w-(ccsG^h-#+qAliKSi1I7gX&T0? zmNgAND|``VA?T#| zUL^cwJoj)C$@de_*jiF@als4}RaUb5O8wvzh0-h{LJ0}!vagR(@YwreYr^-Y0WJhD zsIJEJ4{wYMEG{N%{8e7YRycQ14|BpkWpL}|@Y8nz)bFePq4xrPTcj{vrf6xo>>_4- z(FJjB2EF;z?@jW!E=>c0<^2Ql2H%wtXWnke`wyFpQ))27FWEl}3tzXAG*y8>dKf3| z4w|-iXWUT#fY3|(caoZ`Kq6D0D4J`ZmN+_IkF5{#f_@CPi7n=_Y-pV2?bPd%t9BD3 z8*c;&Q{f`HYUgbyF+0-0lpKp_8(r1wyxD@s1AGGqM6yN2}#19{~ zug5HiiP)7uv+B~?OmMe~OL+c7?ueQ3jXE12IL&?3`!++%gxShFX3wGl)u#LXxFVPD~Qku_>Ff{IsCQ-d*E7Anc0YV3e} zL~hsZL)xts{_)emg{Zi$Vy_yzeOEp6V)=fs+utM5XqM}a&5%ru7${1BKN|&Y>wg%h zYtBXBQA8$RL<<7Bf1c$DdS9LBL zI;c9$r_i7+8wSD8wLheY+c%5s@53lW??BSvhoC#U-$elk?03USd&VhEdM=T6JaqCtG;GfK_^^nlX=vo&-%iox^h`J z*});^-jqu9qesD|7UNShH8(f67a8*veYEtoyVNfTy2%x_iV7RMLa9S1h(^7#kJ}i@ zV_+^~pfA%NsDQT{1Tt1Bz0|C@W;LQqZ^`e6|BIg{tthgwzH zCrugi)Hs%kh!AWee&u%l`;Q2p{!8)yzte0BGsX=Td-;sz?*n~u_=3T{^)B)OOyvm( zwPTBu1!DYv90iH59b=`C6P~7~0C&@E%#fKVNOkz@#S`#FB<()x>=x%92L`O{QPTf9 zBX}fmP{lxK*u%{na4&t-RaD;k{J!T0f>(=H#zR@Y-uDQ%P)Q~z`zP;iORf>cEafFE ztiRu2%M~SUqM{P1U;N>(VrcyFXIZ%`wEAXDl3|=i;0Eia}HYf>+ z2nq4Qn?TqLfpBxSBF*gFoD*Nt*vG8qW3WT;ZzBo=pAsm_0kT~=IXT@MlOMn=$ZK`` z5w4i8EQ*wK35kek$um>`b7SMj`rok(re*b+vIA$y-&ulE3y9`kdvYe+-zpBA=A zoYp4GHwoG_4tU`IemnU2Uml(RZddN965a!KD>eJ%i(iql1F4F$vzJhH8flbW{MNT z6cZH{I{Q8H`OPn?NLs*&XeRRku8tS{5bu z=BW>Z!CCtUvZP;#_m~$D6=F7cgh)a=_~whICo9!MM@bV7!mUr>Zn7en`2%=K22ya$ zpu~DzWj>W$G9eN7pj=^5ael_t$Ux)w*r{ikY*)fJ=}zDus&rw(T(v-itE! zAJK7X6FY6M$)Sas(8#1p`}PAJF00h5P1)k)uXo+A|1dEz^^5u6dUu+ZPkpSM zcOR+bUU1(y{GEC683o2}*t)ur?6&L=)z63x7g~~*38KYa9ciKR=$^_!GX3j9+S)w} zZpYgo=p-2wui;@HdNN4TK!z|K$70TgzTmULC?rY*v9mw^27t{Dw`c>9w^F+A-VK)g z&IHY>zxjPcegY9h%3WLAa<*kGU%f!{j_8&UABUKb>m@t;YYv8jjSXcwH4?fPYbIcf zguEQIGZZy|_@Lf__O{8-6xt!k!vpg>zY8ZtMM1e;jAX`+to05C3d^iq-2Q|&dz4@s z=%mm^F{89Jtr)HM{*+SYDIvNdC?Oq@He2MnU?3~rDvXG0J-01Va1%n{n>XP zz9i?D>gSInT}OV?)13p{Jpu$>SuoA12n-2wc2L2?T`j&aCNP+4Fkd0d=cWk77uySm zc%IK+lU^;z6eskVUJZkuT8aWIuUPA}lM)SY!MSrTEzM9hk>BUDBt_lwu#CHFI*7n+ z`$|1`-tt<;=kBw@4sjTX;EyPQ;~pFD*;223Ng6_aZ}L430N_c&Atu4Tp7k;K__G+k zKf~J#Au(=1~LumxL4FT!RcQpXt~HlCz`t{gCm=TbxQIB%WoYEwX++ zWbC7$vzdmzGohdU3G7Uz_9vRX$LZQtY+$+GEXNjYK>btHwhUzDAFgHxG5zSy;$OpK zU5|f%Zf%ft-VebSG+g>&vH7hnb;9THOa>&+?;=t~NFUT49N9Eqq}Jv6K4_VG&W2#- zv^F;D)(NyzPO1#J4)XFbx=aePgr)9lWCM`%(KJ8gGB);k*VA^;HoX(Ua|G3Q?SIdv zyj*2_gcaO=3}jl|TwH)com9>@3+XYf96qcz@Xl@+nCaZ0yJqL}*bW4eDj^yuJ*b2 zmjm#IhQ<`H?W66yyq45O1tEAgFnAodpAf&U$sGd^cwSi(-DfF1xQ*fSI3> zoNsAyo^g#5>E6?Eh0M*#l}S9OqyA%{MkdmQl{+pmNQHKnJwc8jSE7t9Y=qeClr|JB z6Ts~>8{FZuK@X@6w)rk?0uvKz7UVB(9b7%~gumJNDzYTvu@1|ukOKhJSU81Ybl*w zO4tk?p@s6A-bBSY;024e_J&jpK6nmyJNAaaQ)dpmR(%G9M6ka~bm(4(^XEz$ySrU0 z3U96LS+FKlTj|%^&7pSaX(-v>GP+>mKckG0-r1>ui8}svJb0@x^anOQL|njSq1|0d z)_fZ!PAb6QHa^=>Nj*V{8r&S1<@CHs5)HXE4~v@Sq=GUhwf|VXNza@Aq_ttkR}idQokPprRbPybk~bKuydq9JoT1$;_x{(GCGM|;0%E9MqvSI zc%ZYj`8rq#P8Bb3TX#2<{qS80aF*!AB;hw_$_fA++L|{~9E@WmXax8IFIgyj5!vEx zS8E7fn1~^{<%lc9QsO*uvDBC1T^Y|fM*hTb6hDkKTS+dD3_yaJz^Sbi3M@S>ZE z%l!TBJ88zPT=Ph(uy~vqfka;=Zww*tUx67^Bi(0IlmL4U4gd9yh4AUbf}_S8eR)aE zPR-vX|JDL{3OzC3q;<@_=5v0hZ#|A_;6sds`|260cnBfHmO6Mffu1$5z z{RnL<^iy}XuKu$WfNN-Xr+2z=Na=HksSWv?Fjk1Bp z+pWxSn@@kd(XHVvEbha*Dzu~7&#VAagoK^9R>EP(M88^LQ%t_Qk%ALWGkMp7_n#P z*y$ZkTNdepLTDrZ#DJb-V{pC>*ag{;BP1pSirt!u*n}Q{(lC=bj#T-^`;t6NxwZS) zVX!ZB*wB4QA|yF=yvFBtsvZ+^Gnc-R+dOEq2T{DeLRv@s}4;Bk+qoWa-D3 z&%1l1)fo-CtLf>xxA#a`dZdGcf{!oBL%XbqKMUtr$P3zic_3U2*7TcxjULWJnAg`A zGmL*#bP_?Xqtfcc+FPa~LZKU@*)6I{R1cq`hD4ZQ7j_ug{0n?6J6H=wUX8iHCbj7z zi?^(FpEhA#jDC4Uy+~gdChn>+(}bZd3iub#=LMpU_F;d*Rx;vCJAY8Ai*rf|*f+ zLf-P2Z(g+rhw#6iO!5Ayq@+G6(c1g4L-H9p^>i%_*8QAFzH7+3t}ojEICK2|z2eL-m^;n6zJV5%sYTzB72|KHReS z#G8&ebqA`L%Ej|tAKuMr#hq#V@`g)B{M2hIb(v7VLJ1G4 z-LBIC;Z$=w%tGx5sd%7*dfzpH1hRtcx^%$v?ftDq=)#<)h=YYIXg2xN)T2yAT^SH6 zBG^RzhbayJ{0U;)|E<>j48XGk!V@)hW7~4%&xU^J>VnyxC+v&X!+?<8Lmba$cCbJ* zHx_k7G!Sq)Hgi?=9Nwgr%E#xl+j(1xkQX9a<Uge6tBA)gPH zWalZbR_KFs8(>_2I3%+OCBr)_lE#!^Vf~L;+`og%)j5`bz3*O zI|p#Ji!g6s3RYU=^x9t=Eh=JIVIJt*{XmB7FRqBt36FQTY|c+G1(33zVBP^}<@^F~ z?A|zw!diIIin9iD${Iw?n=|#Kl=hSNc7RPfMEqeNP~g0$ix2tQ$UjaU8jl0vi4&LS zt%I`haN;lm@2~}0VW5i!k-c-~vL!H`C@QqF4?)}nw z_SeE4sQ=eaNt0u}nQ__V(w`?(seFB*khNMGNJ6uPG}IwOEWLusbg?8aNErar736oY zAT;J+92;kV?^oz#Y^ZHwS>1g0lNh8*x2pVbP3YcLH=9WvK9k~(aqg~kmym2f$%;H( zat{dn9jPAbV>f_LX-Dq^H=l2%r`cjB2qkMeIo`@Col5kXDRHj#d3U&`u^%8MM5$R<75@!7<tuIptFU;OH*}fqAvntv>sA^`|!!CNZL2?a?RekP~mz?)5xLmcmjX_&OF^Q9BCleT6#_W zks~=_{BBu*%|xePX2|}rxrcJ@?7KmJrhRVL3r*=+RD1T{MqQ&*&=+{?ibWehHuXH( z7B(m!55W4dfPM(qymEu~Na=jS9r#!YW8pSku)~tc+`}t2LF365+#BDte&If7p5Qo} zDd67t1<}wZxel2yG&?;#M^H0Da&>=8Pfe+#AIE263#dqfo{)%Xa94_wpB|spZk=7j zPg@E-mDZM}CDa}_HnkDY3JPpd<`?DJT0V%A-QQnQQ_|mdedWHmv?ce-7!V^jfF{}V z%6(N*r?}>Vc$WL|BH|a2(YnV_cg!VGUsUA|-IT|dv6c5V6Cwo~#EKIKgn+gT}bVJVSz$$NZrhi`?U&v^=3mX~rgl%e}TZ_qg zpx9R=4K?_ij12Fet8@jGq3Z6}opJ_uCpm)Q;`PlO)7uNp(LFCI!ypC z2T$@RG-NTEBoz^nuDC+H$P}*lt!MUX8c1e(;Bt>nn3&k+qz-%62Pe4CFBA2evX24q+MM3E@wEB1+1Oj+jego!7R^ZR z*s4yosDhg}nR-lL1-Aqa7A};3J9E*#VvUnE$r2+8sz@@Ie3Rx-np>LI!wY7_Em|pZkM;)-t)6W}GXTCl%9+&uVGjLzC zVA4i+s?3k^T3O!ih+Wi8no!pLuBRO(VGu=#?%tV<((a=(ek*QJDQ$B6)!pjgbpzAJ zV;|q`yzY#Eb9RK9!*8pFQ23+G53{qgu%xS^6m?w@qqE$o^$z#OqPR15u=X!kNJ_2K zUg33bEqE2U0>pxO^fI9!kf5FWTl zI#z%*F)V8)a<#5LG0J1K3jzqc7+ro`_FrH`cVl#S(Na6|N3`B*;vF|Q|=$7vi3 zH3UGImYB{Ma5U6nraM(b;#d+oo??VnXcv%|*1XlIDfw1&kHPsdm>v_2115$Y3USOh zsISwJhonOj1fWzXPXoXAyjaWfuRtY<$!jwj*(ZU_M68$svxb}dHPU1BKYj9%l9`}^ zDFBtEuqd(DLp`0gq$*)F11%-x;zAVEKzw#P3_*UYpI_24ess!)hLMO2=&1byqg+SJ z;sY>N69aBuaDH80!*90_On}|V^{Vver}|%U)i#Tue&)cYf+X@vZ~{~|K%~pC%E^*t z0B4q!yqLD!^p7LI$gSXU0HTYESsk%9*nkeW1rHgGKnDQVVx$1DDrJI>&Ez`ek~^DW zTto@HaOtZbBbSsr`)ZpdWw3^oT_OmZDN8l$PUV|d5fv0L(T|}Lv@Sk^3C4M#+EY}t zT{etZIi10+GE_dIs>JGNHW16U6EfP?Prv4B@;U?ClFLGl(`Ba)XfxurI&)b)mYk;I zaw`J)YzW-<%v69yURhBd9$Q(d_SnxFOfr(-Q};9VPx=`oPcupf>emEQy

KUU)%1 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 z z@%w?GXAjot1s~tQq7Fr5{wsd`C#3u*#q|I8f&V(~e>)EThs~b!5lAWmS~8;>aZw8k zrj_W^7!}ty6uXBzGXB-%#*|DsXPy zl6R7lk}@)yOFrUH*7Eb^Iu*`XGcFmYc>LJgvN_E^ZA)wbgqkAR4%S~I^8=(-Z{EDA zGR3yVWiUKoETpt-8iOsXB78V1hNVm;!G_h4{^N(V*qSgl27}q}l4==i5L>>``!ioT z16|9Q!gA?Dh@YiT)u&%P&qz%z0RlM1==b@{s==Q=0=swY7oPx55}>b>xZo@ZM9dHs zrZrzlH^BdwKaBg9mG!>$k37&21AHTW&M}cN{AV`SDKI1`HUzLnC;^}X_-lABbadzT z?dKHuGC?v_M3T=+#(g`zimne~8A>mYmDkiv3=XQ^5PV-igB=M`DVWDlT^}1-0b&Rm z(A`tOhEPn|^Iww@u5|ZO|cRq_V-dhfwiy&2rFd%1(hts{sWK% z0d2(VWa+L?WT*~AhzsGF_pPP>g`aTh8T#Jk{rwmE;w-=TmNAIyKV9Y@cm+Ucf{1q1 zZvVL<5*o{!f1dDPhl3Q!t{?9Ia+!ZH9H7m@$N%$v|IF)>eD+^mrY;VRhjX;e!`yuG z#6#s4ZZOWR&|;NN+asbo(cF*kwqQ4&Y;$3c>nU!`Grh3{~b&HEVmGMQJL9c_yI z*qnS1%3mT@|4pos*D=Ut+V=GYOnSUNS;>+G92E3qJSJD^>>dR1Iw>dL){m`6b zIKh9u2;^bK9^6;fT+`kLE~LWt>Qx6&)0~l!Xr!V1#+x%ZL{^_Y!6F=yNFwR`5bW0t zznH=ahNaRo%r*x|?F>uBx-sPCD*iC7&}ZP(d=zDV1E@jlfs0q!ARkrpjjIj2baW{t z^Dcc^Q51iZCdp*de4zAUH6^9^;9�r(eA8xx}QU2)G;vFgmImeNom$Uw;O7X$RD2 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 KB into FTS5 and returns a pointer. +Nothing is discarded; the model queries on demand. + +### Tier 2 — valuable, but partially duplicated in Headroom + +**5. Counterfactual savings accounting** — `src/session/analytics.ts` (3,085 lines), +`src/session/project-attribution.ts`, `src/session/db.ts` (1,726). +`ContextSavings`, `ThinkInCodeComparison`, `RealBytesStats`, `MultiAdapterLifetimeStats`, +`enumerateAdapterDirs()`. Measures *what would have entered context but didn't* — a different and +harder quantity than Headroom's `savings_ledger.py`, which records actual compression deltas. +Session event ledger + `tool_calls` + resume + per-project attribution. + +**6. Multi-vendor pricing catalog** — `src/session/pricing.ts` + `model-prices.json`. +61 curated models × 4 rate buckets (input / output / cache-read / cache-write), refreshed from +litellm, unknown model → `null` rather than a silently wrong Claude rate. +**Overlaps `headroom/pricing/*` heavily. Do not port.** + +### Tier 3 — do not port + +Compression heuristics, memory/graph/relevance, telemetry transport, dashboard, install UX, +update-check. Headroom has all of these, more mature, and Phase B/H is actively consolidating them. + +--- + +## 3. Headroom's actual extension seams + +Verified entry-point groups (all `importlib.metadata`-discovered, all opt-in): + +| Seam | Group | Contract | Source | +|---|---|---|---| +| Proxy extension | `headroom.proxy_extension` | `install(app: FastAPI, config: ProxyConfig) -> None` | `headroom/proxy/extensions.py:52` | +| Pipeline extension | `headroom.pipeline_extension` | `on_pipeline_event(PipelineEvent) -> PipelineEvent \| None` over 11 stages | `headroom/pipeline.py:13,68` | +| Learn plugin | `headroom.learn_plugin` | — | `headroom/learn/registry.py:44` | +| Memory text store | `headroom.memory_text` | — | `headroom/memory/config.py:41`, `factory.py:57` | +| Memory vector store | `headroom.memory_vector` | — | `headroom/memory/config.py:34` | +| Memory store | `headroom.memory_store` | — | `headroom/memory/config.py:25` | +| CCR backend | `headroom.ccr_backend` | — | `headroom/cache/compression_store.py:981` | +| Compression hooks | (subclass, not entry point) | `pre_compress` / `compute_biases` / `post_compress` | `headroom/hooks.py:1-31` | + +Two things worth noting: + +- `headroom/proxy/extensions.py:32` states an explicit **stability contract**: changing + `install(app, config)` or the group name requires a deprecation cycle. This is a supported public + seam, not an accident. +- `headroom/hooks.py:16` says outright: *"Headroom SaaS implements position-aware compression and + cross-turn deduplication via these hooks."* The open-core split is already designed in. + +**The exemplar to copy:** `plugins/headroom-oauth2/` — own `pyproject.toml`, own `LICENSE`, own +`SPEC.md`, registers on `headroom.proxy_extension`, dormant until `--proxy-extension oauth2`, +all config via env, "zero core changes." That is the enterprise plugin template. + +**The precedent to copy:** `headroom/lean_ctx/installer.py` and `headroom/rtk/installer.py` — +Headroom already ships thin installers that adopt sibling products. `plugins/headroom-agent-hooks` +already installs startup hooks into Claude Code and Copilot CLI. The socket exists. + +**The gap:** Headroom has *no tool-boundary interception anywhere*. It sees `tool_use`/`tool_result` +only as message content after the fact (`headroom/parser.py`, `headroom/tokenizers/*`). Its +`PipelineStage` enum has no tool-result stage. Everything context-mode does is upstream of +Headroom's earliest hook. + +--- + +## 4. Proposed plugins & variants + +Ranked by value ÷ effort. + +### P1 — `headroom-recall`: FTS5+trigram lossless store as `headroom.memory_text` + +**What:** port `src/store.ts` behind the existing `headroom.memory_text` seam. + +**Why this first:** it is the smallest diff onto an *already-existing* contract, and it fixes a real +product limitation. Today `headroom_retrieve(hash)` requires you to *know the hash* — the tool +description literally says "hash comes from compression markers like `[N items compressed... hash=abc123]`". +With an FTS5-backed store you get `retrieve-by-query`: "what did that build log say about OOM" +instead of "paste hash abc123". The trigram index matters specifically because BM25 tokenization +loses identifiers and stack frames. + +Composes rather than replaces: `compress` → return squeezed text + hash → store the *original* in +FTS5 → rehydrate by hash **or** by query. Also a natural `headroom.ccr_backend` implementation — +the realignment wants "CCR hardens: persistent backend" (Phase B), and this is one. + +**Enterprise variant:** shared team store, retention/TTL policy, per-project scoping (context-mode +already has `project-attribution.ts`), audit of every retrieval. + +**Effort:** medium. Reimplement in Python/Rust against Headroom's memory interface, or ship the +node store as a sidecar. Do not port the MCP tool surface — only the store. + +### P2 — `headroom-admission`: tool-boundary admission control across 18 hosts + +**What:** context-mode's adapter + hook layer, distributed the way `plugins/openclaw` and +`plugins/opencode` already are (TS package under `plugins/`), reporting savings into Headroom's +`savings_ledger.py` JSONL and emitting Headroom pipeline events. + +**Why:** this is the strategic piece. It gives Headroom: +- a **pre-wire** enforcement point, upstream of Phase B's live-zone engine, with no cache-bust and + no token-validation fallback required; +- coverage of **18 agent hosts** — the realignment's Phase G wants to "extend wrap CLIs (cline, + continue, goose, openhands)"; this is that work already done, and then some; +- a deployment mode that works under **subscription auth**, where the proxy is a revocation risk. + +**Enterprise value — this is the DLP story Headroom cannot currently tell.** A `curl` inside a Bash +tool call never touches the proxy, so Headroom is blind to it. context-mode blocks +`curl`/`wget`/`WebFetch`/inline `fetch()`/`requests.get` at the tool boundary and forces network +egress through `ctx_fetch_and_index`. That converts a token-savings feature into an +**egress-control** feature — a different budget line and a different buyer. + +**Effort:** high, but it's mostly packaging + a reporting bridge, not a rewrite. Keep it TypeScript; +Phase H retires Python *proxy* code but explicitly preserves "CLI wrappers, RTK installer" — the +installer layer is the surviving Python, and it can shell out. + +### P3 — `headroom-policy` (Enterprise, license-gated): the PDP + +**What:** `src/security.ts` as a policy decision point, plus centrally-managed org rulesets. + +Two attach points: the hook layer from P2 (tool-level `allow/deny/ask`), and +`headroom.pipeline_extension` at `PRE_SEND` (prompt-level policy). Feeds `headroom/audit/`. + +**Enterprise features that only make sense paid:** central policy service, org-wide allow/deny +rulesets, project-boundary containment enforcement, shell-escape detection inside sandboxed code, +tamper-evident audit trail, per-team reporting. Gate it with the ELv2 license key (see §6). + +**Effort:** medium. The engine exists and is tested (`tests/security/`, `src/security.ts` 889 lines); +the work is the control plane. + +### P4 — `headroom-sandbox`: Think-in-Code execution + +**What:** `executor.ts` exposed as a Headroom MCP tool (`headroom_execute`), 12 languages, +stdout-only. + +**Why:** this is the mechanism behind context-mode's largest measured savings — +`ctx_execute_file` returns 98% savings across 315 KB of real fixtures (`BENCHMARK.md` Part 1), +versus 82% for index+search (Part 2). Programming the analysis beats compressing the output. + +Must ship *with* P3: the shell-escape scanner is what stops the sandbox being an escape hatch. + +**Effort:** medium-high. Runtime isolation is the hard part; `headroom` already has a `sandbox` extra +in `pyproject.toml` to build on. + +### P5 — `headroom-attribution`: counterfactual savings + per-project cost + +**What:** port the *methodology* from `session/analytics.ts` — `RealBytesStats`, +`ThinkInCodeComparison`, `enumerateAdapterDirs`, `project-attribution.ts` — into Headroom's +`savings_ledger` / `reporting` / `dashboard`. + +**Why:** Headroom measures compression deltas (what it squeezed). context-mode measures the +counterfactual (what never entered). Enterprise buyers want the second number, sliced by team and +repo. Do **not** port `pricing.ts` — `headroom/pricing/*` already does this with litellm resolution. + +**Merge, don't port.** `headroom/audit/reads.py` is already a counterfactual measurement tool over +the same Claude Code transcript corpus (see §8). It has the better mechanism taxonomy — identical +repeat, subset containment, write-readback, stale, line-number scaffolding, context residency, +cache-death windows. `analytics.ts` has the multi-host coverage and per-project attribution it +lacks. Combine the two rather than adding a third implementation. + +**Effort:** low-medium, mostly a metrics-definition merge. + +### Variants (packaging, not code) + +- **Headroom No-Proxy Edition** — P1+P2 only, zero API interposition. Sells to buyers who cannot + reroute model traffic and to every subscription-auth user. Removes the single biggest deployment + blocker Headroom has. +- **Headroom Admission Control (Enterprise)** — P2+P3+P4 with a central policy plane and fleet + enrollment across 18 hosts. Positioned as AI-agent DLP/governance, not token savings. +- **Headroom Fleet** — P5 + `enumerateAdapterDirs` for org-wide rollout state and cost reporting. + +--- + +## 5. Evidence base + +context-mode's `BENCHMARK.md`: 21 scenarios, 376 KB raw → 16.5 KB context, **96% overall**, all +fixtures captured from real tool invocations (Context7, Playwright, `gh`, vitest, tsc, nginx logs, +`git log`, analytics CSV) rather than synthetic. Honest about its weak cases — 13% on a 0.4 KB +Playwright network dump, and Part 2 openly explains why index+search only reaches 50-93% (it returns +exact code blocks rather than summaries, by design). + +Test suite: 125 tests across executor/store/MCP-integration/ecosystem, plus 45 test dirs in `tests/` +covering adapters, security, session, hooks, analytics. + +That's a defensible enough evidence base to reuse in Headroom's own materials, and the fixture corpus +itself is reusable for Headroom's `benchmarks/`. + +--- + +## 6. Blockers — resolve these before writing code + +**1. License incompatibility (hard blocker).** +context-mode is **Elastic License 2.0**, "Copyright 2026 Mert Koseoglu". Headroom is +**Apache-2.0**, "Copyright 2025 Headroom Contributors". + +- ELv2 code **cannot** be merged into the Apache-2.0 core. Not a technicality — it would relicense + Headroom's core. +- ELv2 forbids providing the software "to third parties as a hosted or managed service." That + directly constrains `headroom-managed/`. +- Different copyright holders means this needs an **IP arrangement between entities**, not an + engineering decision. + +The good news: Headroom's plugin architecture is exactly the boundary that makes this tractable. +A separate package with its own `pyproject.toml` and its own `LICENSE`, registered on an entry +point — the `plugins/headroom-oauth2/` shape — can carry ELv2 while core stays Apache-2.0. ELv2 is +also the *right* license for a license-key-gated enterprise tier; it explicitly contemplates one. + +Recommendation: any context-mode-derived code ships as separately-licensed plugin packages under +`plugins/`, never vendored into `headroom/`. Get the IP arrangement in writing first. + +**2. Realignment collision.** +Phases A–I are ~40 PRs / 8–13 weeks and include deleting ~25K LOC. Do not open a new integration +front mid-Phase-B. P1 (`headroom.memory_text` / `ccr_backend`) is the exception — it *serves* Phase +B's "CCR hardens: persistent backend" goal rather than competing with it. + +**3. Phase H direction.** +Python proxy code is being retired. Write nothing new in `headroom/proxy/`. Target the surviving +layers: installers, memory writers, CLI wrappers, and Rust. + +--- + +## 7. Sequencing + +| Order | Item | Gate | +|---|---|---| +| 0 | IP/licensing arrangement | before any code | +| 1 | P1 `headroom-recall` — FTS5 store on `memory_text`/`ccr_backend` | lands inside Phase B, serves it | +| 2 | P2 `headroom-admission` — 18-host hook layer under `plugins/` | after Phase A stabilizes | +| 3 | Variant: **No-Proxy Edition** = P1+P2 | as soon as P2 works on 3+ hosts | +| 4 | P3 `headroom-policy` (Enterprise, ELv2, key-gated) | after P2 | +| 5 | P4 `headroom-sandbox` | with P3, never before | +| 6 | P5 `headroom-attribution` | opportunistic | + +--- + +## 8. Follow-up verification + +All four items flagged as open in the first pass are now resolved. + +**`headroom-managed/` is the SaaS arm, and it is unlicensed.** +`headroom-managed/pyproject.toml`: `name = "headroom-managed"`, `description = "Headroom SaaS +Platform - Managed context window optimization"`, `version = 0.1.0`. It has `app/auth.py`, +`app/middleware/`, `app/routes/`, `app/services/`, `app/models.py`, alembic migrations, and a +`pilot/`. There is **no `license` field and no LICENSE file** — i.e. proprietary by default. + +This *sharpens* the §6 blocker rather than easing it. ELv2 forbids providing the software "to third +parties as a hosted or managed service." The product whose name is literally *Managed* is the one +place context-mode-derived code cannot go without an explicit commercial grant from the copyright +holder. Plan the plugin boundary so that `headroom-managed` consumes only Apache-2.0 core +interfaces, never ELv2 implementations. + +**`headroom/audit/reads.py` does not overlap P3 — and it independently validates the whole thesis.** +It is a *measurement* tool, not an audit trail: it streams Claude Code `*.jsonl` transcripts to size +"the addressable bytes for each Read compression mechanism... so defaults are set from traffic, not +theory." No policy, no tamper-evidence. P3's audit trail remains a gap. + +Two lines in its docstring are the most useful corroboration in either repo: + +- *"context residency — how many assistant turns each Read stays in context (the multiplier on its + prefix-cache read cost; **the case for compress-before-cache-entry**)"* — Headroom is already + arguing, from its own traffic, for moving earlier in the pipeline. context-mode is the terminus of + that argument: compress before **context** entry, not merely before cache entry. +- *"identical repeat — a dedup mechanism for this was prototyped and removed: it measured 0.1% of + Read bytes on real traffic."* — Headroom has already empirically established that + message-history-level dedup is worthless. The addressable bytes are at the tool boundary, not in + history. That is the same conclusion the realignment reached from the cache side, arrived at + independently from the traffic side. + +It *does* overlap **P5** — `audit/reads.py` and context-mode's `session/analytics.ts` are two +independent implementations of counterfactual measurement over the same transcript corpus. Merge +them rather than porting; `audit/reads.py` has the better mechanism taxonomy, `analytics.ts` has +multi-host coverage and per-project attribution. + +**No plugin-authoring docs exist.** `docs/` is a Next.js site (`app/`, `content/`, `components/`); +`wiki/` has nothing on extension authoring (only `macos-deployment.md` matched). `plugins/headroom-oauth2/SPEC.md` +remains the de-facto authoring reference — which means whichever plugin lands first sets the house +style. Worth writing the authoring doc as part of P1. + +**Headroom publishes no benchmark results.** `benchmarks/` is 29 runner scripts with no committed +results artifacts, so no like-for-like number exists to compare against context-mode's 96%. The +comparison has to be run. The harness is there and is unusually strong on exactly the axis that +matters: `prefix_cache_benchmark.py`, `cache_bust_trace_report.py`, `cache_validation_bundle.py`, +`synthetic_token_cache_bust_report.py`, `proxy_mode_benchmark.py`, `agent_cost_benchmark.py`, +`real_world_agent_benchmark.py`. Use it to *prove* the §1 cache-safety claim empirically rather than +asserting it — a measured "zero cache-bust events" result is the strongest possible artifact for the +No-Proxy Edition. + +**Bonus finding — the platform axes are orthogonal.** +`docs/platform-feature-matrix.json` (schema v1, updated 2026-07-06) tracks coverage across +`["linux", "macos", "windows"]` — Headroom's platform axis is **operating system**. context-mode's +platform axis is **agent host** (18 of them). Headroom tracks no host-coverage matrix at all. P2 +therefore fills a dimension that does not currently exist in Headroom's own feature accounting, +which also means it needs a second matrix rather than new rows in this one. + +*Process note:* six subagents were dispatched across this analysis and all six stalled at the +600-second watchdog; one reported "Bash is temporarily unavailable" before dying, so the failures +were tool-layer, not analytical. Every finding in this document was verified directly. diff --git a/headroom/backends/litellm.py b/headroom/backends/litellm.py index 8430789ce..60fedfc3a 100644 --- a/headroom/backends/litellm.py +++ b/headroom/backends/litellm.py @@ -413,6 +413,40 @@ PROVIDER_REGISTRY: dict[str, ProviderConfig] = { } +# How long an upstream call may go silent before we give up on it. +# +# WHY THIS EXISTS. There was no timeout here at all, so a request the upstream +# never answered blocked its caller forever. Observed 2026-08-07 under load: +# four agent workers sat on ESTABLISHED connections for 36+ minutes while this +# proxy answered /readyz in 0.11s. No error, no retry, no log line -- the +# client just stops. That is the worst shape a failure can take, because it is +# indistinguishable from slow work and no supervisor can tell the difference. +# +# A float, not an httpx.Timeout, on purpose: litellm expands a float into all +# four httpx phases, so for a STREAMING call this becomes the maximum gap +# BETWEEN CHUNKS rather than a cap on total generation time. A long answer +# streaming steadily is never cut off; a stalled one dies. That is the +# semantic we want, and it falls out of the simpler type. +# +# 600s is deliberately generous -- long enough that no healthy call is at +# risk, short enough that a hang surfaces within a coffee break instead of +# never. +UPSTREAM_TIMEOUT_ENV = "HEADROOM_UPSTREAM_TIMEOUT" +DEFAULT_UPSTREAM_TIMEOUT = 600.0 + + +def _upstream_timeout() -> float: + """Seconds. Never raises; a junk env value must not disable the timeout.""" + import os + + try: + v = float(os.getenv(UPSTREAM_TIMEOUT_ENV, DEFAULT_UPSTREAM_TIMEOUT)) + except (TypeError, ValueError): + return DEFAULT_UPSTREAM_TIMEOUT + # 0 or negative would mean "no timeout" to httpx, which is the bug. + return v if v > 0 else DEFAULT_UPSTREAM_TIMEOUT + + def get_provider_config(provider: str) -> ProviderConfig: """Get provider config, with fallback for unknown providers.""" if provider in PROVIDER_REGISTRY: @@ -925,6 +959,9 @@ class LiteLLMBackend(Backend): logger.debug(f"LiteLLM request: model={litellm_model}") # Make the call + # Bounded, always: an upstream that never answers must not + # block the caller forever. setdefault so an explicit value wins. + kwargs.setdefault("timeout", _upstream_timeout()) response = await acompletion(**kwargs) # Convert to Anthropic format @@ -1055,6 +1092,9 @@ class LiteLLMBackend(Backend): kwargs["stream_options"] = {"include_usage": True} # Stream content — blocks emitted dynamically based on response + # Bounded, always: an upstream that never answers must not + # block the caller forever. setdefault so an explicit value wins. + kwargs.setdefault("timeout", _upstream_timeout()) response = await acompletion(**kwargs) output_tokens = 0 current_block_index = -1 @@ -1283,6 +1323,9 @@ class LiteLLMBackend(Backend): logger.debug(f"LiteLLM OpenAI request: model={litellm_model}") # Make the call + # Bounded, always: an upstream that never answers must not + # block the caller forever. setdefault so an explicit value wins. + kwargs.setdefault("timeout", _upstream_timeout()) response = await acompletion(**kwargs) # Build the usage block. LiteLLM normalizes prompt-cache stats from @@ -1452,6 +1495,9 @@ class LiteLLMBackend(Backend): elif headers.get("x-api-key"): kwargs["api_key"] = headers["x-api-key"] + # Bounded, always: an upstream that never answers must not + # block the caller forever. setdefault so an explicit value wins. + kwargs.setdefault("timeout", _upstream_timeout()) response = await acompletion(**kwargs) async for chunk in response: diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index 26e9f68ee..8251b3590 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -2562,8 +2562,14 @@ class AnthropicHandlerMixin: # turn-hook fold (optimized_messages is post-hook). Runs unconditionally. try: _orig_snapshot = original_client_messages # noqa: F821 (bound at request start) - original_tokens = tokenizer.count_messages(_orig_snapshot) - optimized_tokens = tokenizer.count_messages(optimized_messages) + # Off the event loop (#2810): both passes are CPU-bound real BPE + # since #2543, and running them inline stalled every other + # in-flight request on the same process (~1s on a 2.3 MB body). + # Same tokenizer instance, so the reported values are unchanged. + original_tokens = await asyncio.to_thread(tokenizer.count_messages, _orig_snapshot) + optimized_tokens = await asyncio.to_thread( + tokenizer.count_messages, optimized_messages + ) # Fold the tool-schema/desc compaction delta into BOTH endpoints so # tok_before - tok_after == tok_saved stays coherent in the PERF line # (count_messages never sees tool bytes). Same shape as the OpenAI chat @@ -2657,7 +2663,11 @@ class AnthropicHandlerMixin: parsed_original = json.loads(original_body_bytes) if parsed_original != body: body_mutation_tracker.mark_mutated("structural_diff_vs_original") - except (json.JSONDecodeError, ValueError): + # MemoryError is not a ValueError, so a re-parse spike on 1M-context + # bodies used to escape and abort an otherwise-fine request (#2768). + # This block is a safety net; marking mutated is already the safe + # outcome (it forces canonical re-serialization). + except (json.JSONDecodeError, ValueError, MemoryError, RecursionError): body_mutation_tracker.mark_mutated("original_unparseable") if ( diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py index a7d22449b..23751c65e 100644 --- a/headroom/proxy/handlers/openai.py +++ b/headroom/proxy/handlers/openai.py @@ -3721,8 +3721,11 @@ class OpenAIHandlerMixin: # (result.tokens_before), which mismatches optimized_tokens (provider tokenizer) # and yields impossible tok_after>tok_before. Recount original from the # pre-compression snapshot so the message delta is on one scale. - original_tokens = tokenizer.count_messages(original_client_messages) - optimized_tokens = tokenizer.count_messages(body["messages"]) + # Off the event loop (#2810): see the matching note in the Anthropic handler. + original_tokens = await asyncio.to_thread( + tokenizer.count_messages, original_client_messages + ) + optimized_tokens = await asyncio.to_thread(tokenizer.count_messages, body["messages"]) if tool_tokens_before_compaction > 0: try: tool_tokens_after_compaction = tokenizer.count_text(_json_debug_dumps(tools)) diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.py index fe477290b..889ed60be 100644 --- a/headroom/proxy/prometheus_metrics.py +++ b/headroom/proxy/prometheus_metrics.py @@ -417,14 +417,14 @@ class PrometheusMetrics: return total_input_tokens, total_input_cost_usd try: - cost_stats = self.cost_tracker.stats() + # totals() rather than stats(): identical numbers, without the + # 31-day cost-record walk that stats()["budget_basis"] performs and + # this caller throws away. See CostTracker.totals. + tracked_input_tokens, tracked_input_cost_usd = self.cost_tracker.totals() except Exception: logger.debug("Failed to read cost tracker totals for savings history", exc_info=True) return total_input_tokens, total_input_cost_usd - tracked_input_tokens = cost_stats.get("total_input_tokens") - tracked_input_cost_usd = cost_stats.get("total_input_cost_usd") - if tracked_input_tokens is not None: try: total_input_tokens = self._savings_tracker_input_tokens_offset + max( diff --git a/run-all-plugins.sh b/run-all-plugins.sh new file mode 100755 index 000000000..f8b9b2ec9 --- /dev/null +++ b/run-all-plugins.sh @@ -0,0 +1,171 @@ +#!/usr/bin/env bash +# ───────────────────────────────────────────────────────────────────────────── +# run-all-plugins.sh — install + configure + run the Headroom proxy with ALL 5 +# enterprise plugins, the coding savings-profile, and ML compression offloaded +# to the Kompress-v2 Modal endpoint. Then confirm everything loaded. +# +# Plugins : lossless_guard, skill_search, observability, tier_router, tool_search +# Extra : headroom-ai[sandbox] (torch-free proxy; ML offloaded to Modal) +# Profile : coding (HEADROOM_SAVINGS_PROFILE) + cache mode (prefix-cache safe) +# +# Secrets are SOURCED from ~/env.txt and ~/.headroom/plugins.env — never inlined. +# Re-runnable: install is skipped when already satisfied (FORCE_INSTALL=1 forces). +# ───────────────────────────────────────────────────────────────────────────── +set -euo pipefail + +HR=/Users/tcms/demo/headroom +VENV="$HR/.venv" +PORT="${HEADROOM_PORT:-8787}" +ENV_TXT="${ENV_TXT:-$HOME/env.txt}" +PLUGINS_ENV="$HOME/.headroom/plugins.env" +LOG="${HEADROOM_LOG:-$HOME/.headroom/logs/proxy-all-plugins.log}" +mkdir -p "$(dirname "$LOG")" + +# ── 1. venv ────────────────────────────────────────────────────────────────── +# `python`/`pip`/`uv` are broken system-wide on this box — always use the venv, +# and `python -m pip` (the .venv/bin/pip shim is broken too). +# shellcheck disable=SC1091 +source "$VENV/bin/activate" +PY="$VENV/bin/python" + +# ── 2. install (guarded) ────────────────────────────────────────────────────── +# headroom-ai[sandbox] pulls proxy,code,relevance,reports,otel,html,mcp,spreadsheet +# (all torch-free — heavy ML is offloaded to the Modal Kompress endpoint below). +# The 5 plugins install --no-deps so pip won't drag PyPI's headroom-ai over the +# local editable one; headroom-license is their shared Ed25519 verifier. +need_install=1 +if [ "${FORCE_INSTALL:-0}" != "1" ]; then + n=$("$PY" -c 'import opentelemetry; from headroom.proxy.extensions import discover; print(len(list(discover())))' 2>/dev/null || echo 0) + [ "$n" = "5" ] && need_install=0 +fi +if [ "$need_install" = "1" ]; then + avail=$(df -g "$HR" 2>/dev/null | awk 'NR==2{print $4}') + echo "▶ disk: ${avail:-?}Gi free before install" + if [ -n "$avail" ] && [ "$avail" -lt 2 ]; then + echo "!! <2Gi free — aborting before heavy install (free space, then re-run)"; exit 1 + fi + echo "▶ installing pip+maturin, then headroom-ai[sandbox] + license + 5 plugins (editable)…" + "$PY" -m pip install -U pip maturin + # litellm >=1.92 ships an sdist-only Rust bridge whose AWS-SDK crates need rustc>=1.94.1; + # the default rustup toolchain here is older (pip builds litellm in a temp dir that misses + # the repo's 1.95 pin), so pin to the last pure-Python wheel line (1.91.4). Satisfies + # headroom's litellm>=1.86.2,<2.0 and skips the Rust build entirely. + "$PY" -m pip install "litellm<1.92" + "$PY" -m pip install -e "${HR}[sandbox]" "litellm<1.92" + "$PY" -m pip install -e /Users/tcms/demo/headroom-license + for p in lossless-guard skill-search observability tier-router tool-search; do + "$PY" -m pip install -e "/Users/tcms/demo/headroom-${p}" --no-deps + done +else + echo "▶ install satisfied (5 extensions discovered) — skipping (FORCE_INSTALL=1 to force)" +fi + +# ── 3. secrets from ~/env.txt ───────────────────────────────────────────────── +# Provides: OPENAI_API_KEY, ANTHROPIC_API_KEY, FIREWORKS_API_KEY (upstream creds); +# LANGFUSE_{PUBLIC,SECRET}_KEY + LANGFUSE_BASE_URL (observability sink); +# HEADROOM_KOMPRESS_ENDPOINT + _TOKEN (Modal ML offload). +[ -f "$ENV_TXT" ] || { echo "!! $ENV_TXT not found"; exit 1; } +set -a; # shellcheck disable=SC1090 +source "$ENV_TXT"; set +a + +# ── 4. plugin license (Ed25519, offline, wildcard) ──────────────────────────── +# HEADROOM_LICENSE + HEADROOM_LICENSE_PUBKEY. This is SEPARATE from the OSS cloud +# key (HEADROOM_LICENSE_KEY) — the banner will still say "OSS (no license key)", +# but each plugin prints "license accepted". Fallback: skip verification entirely. +if [ -f "$PLUGINS_ENV" ]; then + set -a; # shellcheck disable=SC1090 + source "$PLUGINS_ENV"; set +a +else + echo "▶ $PLUGINS_ENV missing — using dev license bypass" + export HEADROOM_LICENSE_DEV=1 +fi + +# ── 5. Kompress ML offload → Modal ──────────────────────────────────────────── +# Setting HEADROOM_KOMPRESS_ENDPOINT (+_TOKEN) alone routes Kompress inference to +# the Modal endpoint (content_router._get_kompress_remote). No other flag needed; +# HEADROOM_COMPRESS_ALLOW_REMOTE is a different thing (remote upstreams, not this). +: "${HEADROOM_KOMPRESS_ENDPOINT:?must be set in $ENV_TXT}" +export HEADROOM_KOMPRESS_ENDPOINT_TOKEN="${HEADROOM_KOMPRESS_ENDPOINT_TOKEN:-}" + +# ── 6. observability sink → Langfuse + spend attribution ────────────────────── +# HEADROOM_LANGFUSE_ENABLED must be explicitly truthy (LANGFUSE_* creds come from +# env.txt). Traces (agent.turn / llm.turn spans with gen_ai.usage.cost) land in +# Langfuse. Spend is opt-in: HEADROOM_MODEL_PRICES is {model-substr:{in,out}} in +# USD per 1K tokens. (Per-request identity — org/team/user/session — is supplied +# by the CLIENT via x-headroom-* headers, not settable here.) +export HEADROOM_LANGFUSE_ENABLED=1 +export HEADROOM_LANGFUSE_SERVICE_NAME=headroom-proxy +export HEADROOM_MODEL_PRICES='{"claude-opus":{"in":0.015,"out":0.075},"claude-sonnet":{"in":0.003,"out":0.015},"gpt-5":{"in":0.00125,"out":0.01},"gpt-4":{"in":0.003,"out":0.012}}' +# Metrics (counters) need a separate OTLP endpoint — none in env.txt, so left off: +# export HEADROOM_OTEL_METRICS_ENABLED=1 HEADROOM_OTEL_METRICS_ENDPOINT=http://localhost:4318 + +# ── 7. tier_router ───────────────────────────────────────────────────────────── +# Only stamps service_tier on the wire (no token delta). OpenAI 'flex' is only +# auto-selected for models declared eligible here. Anthropic tiers are a no-op by +# default. Clients force a tier with x-headroom-tier / x-headroom-background: 1. +export HEADROOM_TIER_FLEX_MODELS="${HEADROOM_TIER_FLEX_MODELS:-gpt-5,gpt-4.1,o4-mini}" + +# ── 8. plugin tuning (defaults shown; override as needed) ───────────────────── +# skill_search fires on Anthropic w/ >=min skills; tool_search on synthetic-tier +# providers w/ >=min tools; lossless_guard lossy tier is opt-in (kept OFF). +export HEADROOM_SKILL_SEARCH_MIN_SKILLS="${HEADROOM_SKILL_SEARCH_MIN_SKILLS:-8}" +export HEADROOM_TOOL_SEARCH_MIN_TOOLS="${HEADROOM_TOOL_SEARCH_MIN_TOOLS:-5}" +# export HEADROOM_LOSSLESS_GUARD_LOSSY=1 # opt-in irreversible Bash-noise drop + +# ── 9. coding profile + mode ─────────────────────────────────────────────────── +# savings_profile=coding tunes the pipeline for coding-agent traffic; cache mode +# freezes prior turns to preserve the provider prefix-cache (what coding wants). +export HEADROOM_SAVINGS_PROFILE=coding + +# ── 10. run + confirm ────────────────────────────────────────────────────────── +cleanup() { [ -n "${PROXY_PID:-}" ] && kill "$PROXY_PID" 2>/dev/null || true; } +trap cleanup INT TERM EXIT + +echo "▶ starting proxy on :$PORT (profile=coding, mode=cache, all 5 extensions)…" +headroom proxy --port "$PORT" --mode cache --proxy-extension '*' > "$LOG" 2>&1 & +PROXY_PID=$! + +# wait for readiness (no foreground sleep on this harness) +curl -s --retry 40 --retry-delay 1 --retry-all-errors --max-time 60 \ + "http://127.0.0.1:$PORT/health" >/dev/null 2>&1 || true + +echo +echo "══════════════════ CONFIRMATION ══════════════════" +echo "── extensions loaded (from $LOG) ──" +grep -iE "Extensions:|license accepted|installed \(" "$LOG" | sed 's/^/ /' || true + +echo "── Modal Kompress endpoint reachable? ──" +code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 30 "$HEADROOM_KOMPRESS_ENDPOINT" || echo "unreachable") +echo " $HEADROOM_KOMPRESS_ENDPOINT -> HTTP $code (any response = up; offload runs on real traffic)" + +echo "── /stats surfaces (empty until traffic flows) ──" +curl -s --max-time 5 "http://127.0.0.1:$PORT/stats" | "$PY" -c ' +import sys,json +d=json.load(sys.stdin) +print(" extension_savings :", d.get("extension_savings")) +print(" by_layer :", list(d.get("savings",{}).get("by_layer",{}))) +print(" tokens_saved_by_strat:", d.get("tokens_saved_by_strategy")) +print(" otel.enabled :", d.get("otel",{}).get("enabled")) +print(" langfuse.enabled :", d.get("langfuse",{}).get("enabled")) +' 2>/dev/null || echo " (stats not ready)" + +cat < dashboard (compression layer) + /stats.tokens_saved_by_strategy + skill_search -> /stats.extension_savings (NOT dashboard) — Anthropic client, >=8 skills + tool_search -> /stats.extension_savings (NOT dashboard) — synthetic-tier client, >=5 tools + observability -> Langfuse UI (spans + gen_ai.usage.cost) — send x-headroom-org/user/session + tier_router -> service_tier on the wire / provider bill (no token delta) + +── drive traffic (two clients — they exercise different plugins) ── + Claude Code : ANTHROPIC_BASE_URL=http://localhost:$PORT claude # lossless_guard + skill_search + OpenAI/opencode: OPENAI_BASE_URL=http://localhost:$PORT/v1 # tool_search + Dashboard : headroom dashboard (http://127.0.0.1:$PORT/dashboard) + Raw stats : curl -s localhost:$PORT/stats | python3 -m json.tool + +Proxy is running (pid $PROXY_PID). Ctrl-C to stop. Logs: $LOG +═══════════════════════════════════════════════════ +EOF + +wait "$PROXY_PID" || true diff --git a/tests/test_litellm_upstream_timeout.py b/tests/test_litellm_upstream_timeout.py new file mode 100644 index 000000000..9d6918e46 --- /dev/null +++ b/tests/test_litellm_upstream_timeout.py @@ -0,0 +1,70 @@ +"""Every upstream call must be bounded. + +There was no timeout in this backend at all. Observed 2026-08-07 under load: +four agent workers blocked on ESTABLISHED connections for 36+ minutes while +the proxy answered /readyz in 0.11s. No error, no retry, no log line -- the +caller simply stops, forever, and that is indistinguishable from slow work. +""" + +from __future__ import annotations + +import ast +from pathlib import Path + +import pytest + +from headroom.backends.litellm import ( + DEFAULT_UPSTREAM_TIMEOUT, + UPSTREAM_TIMEOUT_ENV, + _upstream_timeout, +) + +_SRC = Path(__file__).resolve().parents[1] / "headroom" / "backends" / "litellm.py" + + +def test_every_acompletion_call_is_bounded(): + """A new dispatch path added without a timeout reintroduces the hang. + + Checked structurally rather than by mocking, because the failure mode is a + call site someone ADDS later -- which no mock of the existing paths sees. + """ + tree = ast.parse(_SRC.read_text()) + calls, guards = 0, 0 + for node in ast.walk(tree): + if not isinstance(node, ast.Call): + continue + fn = node.func + if isinstance(fn, ast.Name) and fn.id == "acompletion": + calls += 1 + if ( + isinstance(fn, ast.Attribute) + and fn.attr == "setdefault" + and node.args + and isinstance(node.args[0], ast.Constant) + and node.args[0].value == "timeout" + ): + guards += 1 + assert calls > 0, "no acompletion call sites found -- test is stale" + assert guards >= calls, ( + f"{calls} acompletion call site(s) but only {guards} timeout guard(s); " + "an unbounded upstream call blocks its caller forever" + ) + + +def test_a_junk_env_value_cannot_disable_the_timeout(monkeypatch): + """`0` means 'no timeout' to httpx, i.e. exactly the bug. So does junk.""" + for bad in ("", "0", "-1", "nonsense", "None"): + monkeypatch.setenv(UPSTREAM_TIMEOUT_ENV, bad) + assert _upstream_timeout() == DEFAULT_UPSTREAM_TIMEOUT, bad + + +def test_an_operator_can_still_tune_it(monkeypatch): + monkeypatch.setenv(UPSTREAM_TIMEOUT_ENV, "42.5") + assert _upstream_timeout() == pytest.approx(42.5) + + +def test_the_default_is_generous_enough_for_real_work(): + """Streaming: litellm expands a float across all httpx phases, so this is + the max gap BETWEEN CHUNKS, not a cap on total generation. A steady long + answer is never cut off.""" + assert 60.0 <= DEFAULT_UPSTREAM_TIMEOUT <= 1800.0 diff --git a/tests/test_proxy/test_anthropic_recount_and_reparse_safety.py b/tests/test_proxy/test_anthropic_recount_and_reparse_safety.py new file mode 100644 index 000000000..1e7f67fad --- /dev/null +++ b/tests/test_proxy/test_anthropic_recount_and_reparse_safety.py @@ -0,0 +1,158 @@ +"""Two request-path safety nets in ``handle_anthropic_messages``. + +1. #2810 — the consistency re-count runs ``count_messages`` twice. Both passes + are CPU-bound real BPE (since #2543) and used to run directly on the event + loop, stalling every other in-flight request on the process (~1s on a 2.3 MB + body). They must run off the loop. +2. #2768 — the byte-faithful forwarder's verification re-parse of the original + body is best-effort, but ``MemoryError`` is not a ``ValueError``, so on + 1M-context payloads it escaped and aborted an otherwise-fine request. The + block must never be able to fail the request. +""" + +from __future__ import annotations + +import asyncio +import json +from unittest.mock import AsyncMock, MagicMock + +import pytest + +fastapi = pytest.importorskip("fastapi") + +from fastapi.testclient import TestClient # noqa: E402 + +from headroom.proxy.server import ProxyConfig, create_app # noqa: E402 + +MESSAGES = "/v1/messages" +MODEL = "claude-sonnet-4-6" + +# Only ever present in the PRE-compression snapshot, never in the outbound body. +# Long enough to clear the handler's min-token floors. +SENTINEL = "presnapshot-sentinel " * 500 + + +def _config(**overrides) -> ProxyConfig: + base = { + "optimize": True, + "cache_enabled": False, + "rate_limit_enabled": False, + "cost_tracking_enabled": False, + "mode": "token", + } + base.update(overrides) + return ProxyConfig(**base) + + +def _upstream_200() -> MagicMock: + payload = { + "id": "msg_1", + "type": "message", + "role": "assistant", + "content": [{"type": "text", "text": "ok"}], + "model": MODEL, + "usage": {"input_tokens": 10, "output_tokens": 2}, + } + resp = MagicMock() + resp.status_code = 200 + resp.headers = {"content-type": "application/json"} + resp.content = json.dumps(payload).encode() + resp.text = json.dumps(payload) + resp.json.return_value = payload + return resp + + +def test_consistency_recount_runs_off_the_event_loop(monkeypatch): + """No ``count_messages`` pass over the pre-compression snapshot may run on + the loop thread. The snapshot is identified by SENTINEL, which the pipeline + strips, so this pins the re-count specifically: the already-offloaded count + at request start also sees the sentinel and passes either way, while the + two re-count passes ran inline before #2810 and would fail here. + """ + import headroom.tokenizers as tokenizers_mod + + seen: list[bool] = [] # one entry per snapshot count: True == ran on the loop + + # Patch the class, not the cached instance, so pytest restores it for us. + tokenizer_cls = type(tokenizers_mod.get_tokenizer(MODEL)) + real_count = tokenizer_cls.count_messages + + def counting(self, messages): # noqa: ANN001, ANN202 + if SENTINEL in json.dumps(messages, default=str): + try: + asyncio.get_running_loop() + except RuntimeError: + seen.append(False) # worker thread — no running loop here + else: + seen.append(True) # blocking the event loop + return real_count(self, messages) + + monkeypatch.setattr(tokenizer_cls, "count_messages", counting) + + def stripping_apply(**kwargs): # noqa: ANN003, ANN202 + """Return genuinely-changed messages with the sentinel removed.""" + from types import SimpleNamespace + + compressed = [{**m, "content": "compressed"} for m in kwargs["messages"]] + return SimpleNamespace( + messages=compressed, + transforms_applied=["test_strip"], + timing={}, + tokens_before=100, + tokens_after=80, + waste_signals=None, + ) + + app = create_app(_config()) + with TestClient(app) as client: + proxy = client.app.state.proxy + proxy.anthropic_pipeline.apply = MagicMock(side_effect=stripping_apply) + proxy._retry_request = AsyncMock(return_value=_upstream_200()) + r = client.post( + MESSAGES, + json={ + "model": MODEL, + "max_tokens": 16, + "messages": [{"role": "user", "content": SENTINEL}], + }, + ) + + assert r.status_code == 200, r.text + assert seen, "no count_messages pass saw the snapshot; test is not exercising #2810" + assert not any(seen), f"{sum(seen)}/{len(seen)} snapshot counts blocked the event loop" + + +def test_memoryerror_in_verification_reparse_does_not_abort_the_request(monkeypatch): + """A ``MemoryError`` from the best-effort original-body re-parse must be + swallowed (the safe fallback marks the body mutated, forcing canonical + re-serialization) rather than escaping and killing the request. + """ + import headroom.proxy.handlers.anthropic as anthropic_mod + + real_loads = json.loads + raised = {"n": 0} + + def exploding_loads(s, *args, **kwargs): # noqa: ANN001, ANN002, ANN003, ANN202 + # Only the verification re-parse passes the raw original body bytes. + if isinstance(s, (bytes, bytearray)) and b"reparse-bomb" in s: + raised["n"] += 1 + raise MemoryError("simulated re-parse spike") + return real_loads(s, *args, **kwargs) + + monkeypatch.setattr(anthropic_mod.json, "loads", exploding_loads) + + app = create_app(_config(optimize=False)) + with TestClient(app) as client: + proxy = client.app.state.proxy + proxy._retry_request = AsyncMock(return_value=_upstream_200()) + r = client.post( + MESSAGES, + json={ + "model": MODEL, + "max_tokens": 16, + "messages": [{"role": "user", "content": "reparse-bomb"}], + }, + ) + + assert raised["n"] > 0, "the verification re-parse never ran; test is not exercising #2768" + assert r.status_code == 200, r.text From 2f2950a626cebf851aac29255e7188fbb1639f5a Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Sun, 9 Aug 2026 20:12:41 -0700 Subject: [PATCH 022/138] fix(litellm): don't forward a caller key the target cannot accept (#2883) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split out of #2852 at review request: that PR is bounded upstream calls plus measured hot-path costs, and this is an authentication/routing change that belongs on its own scope. #2852 now carries only the timeout work. ## The bug A routing extension can rewrite the model across families mid-request (`claude-opus-5` → `gpt-5-mini`). The caller's key does not travel with that rewrite, so the proxy forwards `sk-ant-...` to OpenAI and earns a guaranteed 401. Downstream that is indistinguishable from *"the cheap model failed the task"* — it scores as a quality regression against the router, not as a bug. Dropping the `api_key` kwarg instead lets litellm fall back to the target provider's own env credential, which is the only key that can work. ## Why this cut is different from the one that was rejected The first version returned `not provider.startswith("anthropic")`, so **any** non-`sk-ant-` credential was dropped against an Anthropic-class target — a plain Bearer token against an Anthropic-compatible or custom gateway lost its key and fell back to an env credential that may not exist. That direction is the dangerous one. A false refusal breaks a deployment that was working; a missed refusal just leaves today's 401. So this refuses on **positive evidence only**: | credential | target | forwarded? | |---|---|---| | `sk-ant-…` | `openai` / `azure` / `gemini` | **no** — cannot possibly authenticate | | `sk-ant-…` | anthropic | yes | | `sk-ant-…` | unrecognised / unclassifiable model | yes — pass-through | | anything else | anything | yes — pass-through, unchanged | `sk-ant-` is Anthropic's documented vendor-specific prefix, which is what makes it classifiable. `sk-` is not: a dozen vendors mint that shape. Everything the string cannot settle keeps main's behaviour. The reject list is explicit rather than inverted (`not anthropic`) because an unrecognised provider is usually a compatible or self-hosted gateway. Marked in the code as a hand-kept tuple with the registry-lookup upgrade path noted. Bedrock / Vertex / SageMaker are unaffected — all four dispatch sites already skip credential forwarding for them entirely (env-based auth). ## Verification `tests/test_litellm_caller_key.py`, 12 cases — the refusal, the Anthropic target, the unknown provider, `get_llm_provider` raising, and each unclassifiable credential shape asserted against **both** target families. Those last ones fail against the rejected version. Applied at all four dispatch sites (Anthropic non-stream/stream, OpenAI non-stream/stream). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) --- headroom/backends/litellm.py | 89 ++++++++++++++++++++++++++------ tests/test_litellm_caller_key.py | 67 ++++++++++++++++++++++++ 2 files changed, 140 insertions(+), 16 deletions(-) create mode 100644 tests/test_litellm_caller_key.py diff --git a/headroom/backends/litellm.py b/headroom/backends/litellm.py index 60fedfc3a..6e3afd7e4 100644 --- a/headroom/backends/litellm.py +++ b/headroom/backends/litellm.py @@ -447,6 +447,47 @@ def _upstream_timeout() -> float: return v if v > 0 else DEFAULT_UPSTREAM_TIMEOUT +# Providers that cannot possibly accept an Anthropic `sk-ant-` credential. +# +# Explicit, rather than the inverse "anything not Anthropic": an unrecognised +# provider is usually a compatible or self-hosted gateway, and guessing wrong +# there drops a key that WAS working. Bedrock/Vertex are absent because the +# dispatch sites already skip them entirely (env-based auth). +# +# ponytail: a hand-kept tuple; grow it as targets are confirmed. A registry +# lookup would be the upgrade if this ever outgrows a handful of entries. +_REJECTS_ANTHROPIC_KEY = ("openai", "azure", "gemini") + + +def _caller_key_travels_to(model: str, key: str) -> bool: + """Can this inbound credential authenticate the provider we are about to call? + + The caller authenticates to the PROXY. A routing extension may then rewrite + the model across families mid-request (claude-opus-5 -> gpt-5-mini), and the + caller's key does not travel with that rewrite: we forward `sk-ant-...` to + OpenAI and earn a guaranteed 401, which reads downstream as "the cheap model + failed the task" rather than as the routing bug it is. + + Only an unambiguous mismatch is refused. `sk-ant-` is Anthropic's documented + vendor-specific prefix, so it cannot authenticate one of the providers above. + Every other credential -- a plain Bearer token, an OpenAI-style `sk-` that a + dozen vendors also mint, anything aimed at a compatible or custom gateway -- + is unclassifiable from the string alone and keeps the pass-through. + + Returning False drops the api_key kwarg, so litellm falls back to the target + provider's own env credential: the only key that can work. + """ + if not key.startswith("sk-ant-"): + return True + try: + from litellm import get_llm_provider + + provider = (get_llm_provider(model)[1] or "").lower() + except Exception: # noqa: BLE001 - unclassifiable model, keep pass-through + return True + return provider not in _REJECTS_ANTHROPIC_KEY + + def get_provider_config(provider: str) -> ProviderConfig: """Get provider config, with fallback for unknown providers.""" if provider in PROVIDER_REGISTRY: @@ -951,10 +992,14 @@ class LiteLLMBackend(Backend): _env_auth_providers = ("bedrock", "vertex_ai", "vertex_ai_beta", "sagemaker") if self.provider not in _env_auth_providers: auth_header = headers.get("authorization", headers.get("Authorization", "")) - if auth_header.startswith("Bearer "): - kwargs["api_key"] = auth_header[7:] - elif headers.get("x-api-key"): - kwargs["api_key"] = headers["x-api-key"] + _caller_key = ( + auth_header[7:] + if auth_header.startswith("Bearer ") + else headers.get("x-api-key", "") + ) + # Only forward it if it can actually authenticate the TARGET. + if _caller_key and _caller_key_travels_to(litellm_model, _caller_key): + kwargs["api_key"] = _caller_key logger.debug(f"LiteLLM request: model={litellm_model}") @@ -1059,10 +1104,14 @@ class LiteLLMBackend(Backend): _env_auth_providers = ("bedrock", "vertex_ai", "vertex_ai_beta", "sagemaker") if self.provider not in _env_auth_providers: auth_header = headers.get("authorization", headers.get("Authorization", "")) - if auth_header.startswith("Bearer "): - kwargs["api_key"] = auth_header[7:] - elif headers.get("x-api-key"): - kwargs["api_key"] = headers["x-api-key"] + _caller_key = ( + auth_header[7:] + if auth_header.startswith("Bearer ") + else headers.get("x-api-key", "") + ) + # Only forward it if it can actually authenticate the TARGET. + if _caller_key and _caller_key_travels_to(litellm_model, _caller_key): + kwargs["api_key"] = _caller_key msg_id = f"msg_{uuid.uuid4().hex[:24]}" @@ -1315,10 +1364,14 @@ class LiteLLMBackend(Backend): _env_auth_providers = ("bedrock", "vertex_ai", "vertex_ai_beta", "sagemaker") if self.provider not in _env_auth_providers: auth_header = headers.get("authorization", headers.get("Authorization", "")) - if auth_header.startswith("Bearer "): - kwargs["api_key"] = auth_header[7:] - elif headers.get("x-api-key"): - kwargs["api_key"] = headers["x-api-key"] + _caller_key = ( + auth_header[7:] + if auth_header.startswith("Bearer ") + else headers.get("x-api-key", "") + ) + # Only forward it if it can actually authenticate the TARGET. + if _caller_key and _caller_key_travels_to(litellm_model, _caller_key): + kwargs["api_key"] = _caller_key logger.debug(f"LiteLLM OpenAI request: model={litellm_model}") @@ -1490,10 +1543,14 @@ class LiteLLMBackend(Backend): _env_auth_providers = ("bedrock", "vertex_ai", "vertex_ai_beta", "sagemaker") if self.provider not in _env_auth_providers: auth_header = headers.get("authorization", headers.get("Authorization", "")) - if auth_header.startswith("Bearer "): - kwargs["api_key"] = auth_header[7:] - elif headers.get("x-api-key"): - kwargs["api_key"] = headers["x-api-key"] + _caller_key = ( + auth_header[7:] + if auth_header.startswith("Bearer ") + else headers.get("x-api-key", "") + ) + # Only forward it if it can actually authenticate the TARGET. + if _caller_key and _caller_key_travels_to(litellm_model, _caller_key): + kwargs["api_key"] = _caller_key # Bounded, always: an upstream that never answers must not # block the caller forever. setdefault so an explicit value wins. diff --git a/tests/test_litellm_caller_key.py b/tests/test_litellm_caller_key.py new file mode 100644 index 000000000..d9dd2440c --- /dev/null +++ b/tests/test_litellm_caller_key.py @@ -0,0 +1,67 @@ +"""A caller's key must not be dropped unless we are certain it cannot work. + +The proxy forwards the inbound credential to the upstream provider. When a +routing extension rewrites the model across families mid-request, that key stops +matching the target and the 401 that follows is indistinguishable, downstream, +from "the cheap model failed the task". + +Refusing to forward is the fix, but it is also the more dangerous direction: a +false positive silently strips a credential from a deployment that was working, +and litellm then falls back to an env key that may not exist. So the rule is +positive evidence only -- an unrecognised credential always travels. +""" + +from __future__ import annotations + +import pytest + +from headroom.backends.litellm import _caller_key_travels_to + +ANTHROPIC_KEY = "sk-ant-api03-abc123" + + +@pytest.mark.parametrize( + "model", + ["gpt-5-mini", "gpt-4o", "azure/gpt-4", "gemini/gemini-2.0-flash"], +) +def test_anthropic_key_is_refused_for_a_provider_that_cannot_accept_it(model: str) -> None: + """The bug this exists for: claude-* rewritten to a non-Anthropic target.""" + pytest.importorskip("litellm") + assert _caller_key_travels_to(model, ANTHROPIC_KEY) is False + + +@pytest.mark.parametrize( + "model", + ["claude-opus-4-5-20251101", "anthropic/claude-sonnet-4-5-20250929"], +) +def test_anthropic_key_travels_to_anthropic(model: str) -> None: + pytest.importorskip("litellm") + assert _caller_key_travels_to(model, ANTHROPIC_KEY) is True + + +@pytest.mark.parametrize( + "key", + [ + "sk-proj-openai-style", # a dozen vendors mint this shape + "Bearer-ish-opaque-token", # a plain gateway token + "hf_abc123", + "sk-ant", # near miss, not the prefix + "", + ], +) +def test_only_the_anthropic_prefix_is_ever_classified(key: str) -> None: + """Everything else is unclassifiable from the string, so it passes through. + + This is the regression the review caught: the first version returned + `not provider.startswith("anthropic")`, which dropped every one of these + against an Anthropic-class target. + """ + assert _caller_key_travels_to("gpt-5-mini", key) is True + assert _caller_key_travels_to("claude-opus-4-5-20251101", key) is True + + +def test_unknown_provider_keeps_the_pass_through() -> None: + """A compatible or self-hosted gateway we cannot classify must not lose its + key -- including when `get_llm_provider` raises on the model string.""" + assert _caller_key_travels_to("some-self-hosted-thing", ANTHROPIC_KEY) is True + assert _caller_key_travels_to("", ANTHROPIC_KEY) is True From e6e5826423a0a700a8c544ce2c8cbcdef694160e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:30:15 -0500 Subject: [PATCH 023/138] deps: bump postcss from 8.5.19 to 8.5.26 in /docs (#2881) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [postcss](https://github.com/postcss/postcss) from 8.5.19 to 8.5.26.

Release notes

Sourced from postcss's releases.

8.5.26

  • Fixed list.split() regression (by @​lazerg).
  • Track symlinks in path protection in source map loading (by @​drengir1).

8.5.25

  • Fixed 8.5.17 visitor regression.
  • Fixed list.split() for non-string values (by @​amir-rezaei).

8.5.24

  • Preserve the BOM after the processing (by @​hdimer).

8.5.23

  • Do not load source map without opts.from for security reasons.

8.5.22

8.5.21

8.5.20

Changelog

Sourced from postcss's changelog.

8.5.26

  • Fixed list.split() regression (by @​lazerg).
  • Track symlinks in path protection in source map loading (by @​drengir1).

8.5.25

  • Fixed 8.5.17 visitor regression.
  • Fixed list.split() for non-string values (by @​amir-rezaei).

8.5.24

  • Preserve the BOM after the processing (by @​hdimer).

8.5.23

  • Do not load source map without opts.from for security reasons.

8.5.22

8.5.21

8.5.20

Commits

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=postcss&package-manager=npm_and_yarn&previous-version=8.5.19&new-version=8.5.26)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/headroomlabs-ai/headroom/network/alerts).
Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- docs/package-lock.json | 16 ++++++++-------- docs/package.json | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/package-lock.json b/docs/package-lock.json index 152001ff3..55bff9b41 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -35,7 +35,7 @@ "@types/react-dom": "^19.2.3", "ai": "^6.0.149", "openai": "^6.47.0", - "postcss": "^8.5.19", + "postcss": "^8.5.26", "tailwindcss": "^4.2.2", "typescript": "^5.9.3" } @@ -5629,9 +5629,9 @@ "license": "MIT" }, "node_modules/nanoid": { - "version": "3.3.15", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.15.tgz", - "integrity": "sha512-y7Wygv/7mEOvxTuEQDB8StXdMRBWf1kR/tlhAzBRUFkB2jfcLOAxO/SHmOO2zgz1pVgK29/kyupn059/bCHdjA==", + "version": "3.3.18", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz", + "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==", "funding": [ { "type": "github", @@ -5816,9 +5816,9 @@ } }, "node_modules/postcss": { - "version": "8.5.19", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.19.tgz", - "integrity": "sha512-Mz8SaolMd8nB+G13WkORcxQKHZ/NE4xXevtkJHVuG+guo9/wYKlIMTKAqGdEmYOXR2ijPjTYNHssizdaVSUNdQ==", + "version": "8.5.26", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz", + "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==", "funding": [ { "type": "opencollective", @@ -5835,7 +5835,7 @@ ], "license": "MIT", "dependencies": { - "nanoid": "^3.3.12", + "nanoid": "^3.3.17", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" }, diff --git a/docs/package.json b/docs/package.json index 6a2171274..21abffaf3 100644 --- a/docs/package.json +++ b/docs/package.json @@ -36,7 +36,7 @@ "@types/react-dom": "^19.2.3", "ai": "^6.0.149", "openai": "^6.47.0", - "postcss": "^8.5.19", + "postcss": "^8.5.26", "tailwindcss": "^4.2.2", "typescript": "^5.9.3" }, From 74403fe804c2314714ea958d9a6fb16d73be0afb Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:30:40 -0500 Subject: [PATCH 024/138] build(deps): bump gitpython from 3.1.50 to 3.1.54 in the uv group across 1 directory (#2575) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps the uv group with 1 update in the / directory: [gitpython](https://github.com/gitpython-developers/GitPython). Updates `gitpython` from 3.1.50 to 3.1.54
Release notes

Sourced from gitpython's releases.

3.1.54 - Security

What's Changed

Full Changelog: https://github.com/gitpython-developers/GitPython/compare/3.1.53...3.1.54

3.1.53 - Security

What's Changed

New Contributors

Full Changelog: https://github.com/gitpython-developers/GitPython/compare/3.1.52...3.1.53

3.1.52 Security

https://github.com/gitpython-developers/GitPython/security/advisories/GHSA-rwj8-pgh3-r573: Environment-variable exfiltration via os.path.expandvars() on Repo.clone_from() URL

What's Changed

Full Changelog: https://github.com/gitpython-developers/GitPython/compare/3.1.51...3.1.52

3.1.51 - Security

What's Changed

... (truncated)

Commits
  • e59d9ba prepare next release
  • a4dc70d Merge pull request #2180 from gitpython-developers/single-char-kwarg
  • 1d51b89 fix: guard diff output options
  • ffcb535 fix: reject unsafe clone templates
  • e8d0fbf fix: validate split short-option values
  • faf3c09 prepare for security fix
  • 6a5eb6a Merge pull request #2176 from gitpython-developers/fix-config-injection
  • 1ed1b92 fix: validate config section delimiters
  • 354eb2f Merge pull request #2159 from Siesta0217/fix-core-hooks-path-commit-hooks
  • 9bc287a Address review feedback about hook resolution
  • Additional commits viewable in compare view

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=gitpython&package-manager=uv&previous-version=3.1.50&new-version=3.1.54)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore major version` will close this group update PR and stop Dependabot creating any more for the specific dependency's major version (unless you unignore this specific dependency's major version or upgrade to it yourself) - `@dependabot ignore minor version` will close this group update PR and stop Dependabot creating any more for the specific dependency's minor version (unless you unignore this specific dependency's minor version or upgrade to it yourself) - `@dependabot ignore ` will close this group update PR and stop Dependabot creating any more for the specific dependency (unless you unignore this specific dependency or upgrade to it yourself) - `@dependabot unignore ` will remove all of the ignore conditions of the specified dependency - `@dependabot unignore ` will remove the ignore condition of the specified dependency and ignore conditions You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/headroomlabs-ai/headroom/network/alerts).
Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- uv.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/uv.lock b/uv.lock index b80d4d91f..98aae70bd 100644 --- a/uv.lock +++ b/uv.lock @@ -1495,14 +1495,14 @@ wheels = [ [[package]] name = "gitpython" -version = "3.1.50" +version = "3.1.54" source = { registry = "https://pypi.org/simple/" } dependencies = [ { name = "gitdb" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/33/f6/354ae6491228b5eb40e10d89c4d13c651fe1cf7556e35ebdded50cff57ce/gitpython-3.1.50.tar.gz", hash = "sha256:80da2d12504d52e1f998772dc5baf6e553f8d2fcfe1fcc226c9d9a2ee3372dcc", size = 219798, upload-time = "2026-05-06T04:01:26.571Z" } +sdist = { url = "https://files.pythonhosted.org/packages/5e/d5/3da0b92033887033f4c27f2dd109a303c4ca62813c7b3bb2511edb4777de/gitpython-3.1.54.tar.gz", hash = "sha256:53f2085e24a2cda300eed7c3fc5f1559ae289634b725e98acaf4791940247aa0", size = 225076, upload-time = "2026-07-22T04:08:51.403Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/20/7a/1c6e3562dfd8950adbb11ffbc65d21e7c89d01a6e4f137fa981056de25c5/gitpython-3.1.50-py3-none-any.whl", hash = "sha256:d352abe2908d07355014abdd21ddf798c2a961469239afec4962e9da884858f9", size = 212507, upload-time = "2026-05-06T04:01:23.799Z" }, + { url = "https://files.pythonhosted.org/packages/d1/b9/876f442a28df5c068ca69b0122d5c35e65fd2d2fa9992ea5cb5944ea00a6/gitpython-3.1.54-py3-none-any.whl", hash = "sha256:b90d7b3d9bc0238681d24369130826f0dcdb0ceaa45db67cf1d4ffa4c302dedf", size = 216575, upload-time = "2026-07-22T04:08:50.05Z" }, ] [[package]] From ecf130d3ac6fb864098cb93fafd2621ae3ac7e12 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:31:36 -0500 Subject: [PATCH 025/138] deps: bump ruff from 0.15.17 to 0.15.22 in the pip-minor-patch group (#2501) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps the pip-minor-patch group with 1 update: [ruff](https://github.com/astral-sh/ruff). Updates `ruff` from 0.15.17 to 0.15.22
Release notes

Sourced from ruff's releases.

0.15.22

Release Notes

Released on 2026-07-16.

Preview features

  • [pycodestyle] Add an autofix for E402 (#22212)
  • [refurb] Allow subclassing builtins in stub files (FURB189) (#26812)
  • [ruff] Add rule to replace noqa comments with ruff:ignore (RUF105) (#26423)
  • [ruff] Add rule to use human-readable names in ruff:ignore comments (RUF106) (#26682)
  • [ruff] Add rule to use human-readable names in configuration selectors (RUF201) (#26772)

Bug fixes

  • [flake8-pyi] Fix false positive in __all__ (PYI053) (#26872)

Rule changes

  • [pylint] Ignore mutable type updates in redefined-loop-name (PLW2901) (#25733)

Performance

  • Avoid redundant lexer token bookkeeping (#26765)
  • Avoid redundant pending-indentation writes (#26774)
  • Avoid unnecessary identifier lookahead (#26525)
  • Reuse parser scratch buffers (#26798)

Documentation

  • Document argfile support (#26803)
  • [flake8-datetimez] Clarify naming guidance for datetime.today (DTZ002) (#26658)
  • [pycodestyle] Document E731 fix safety (#26847)
  • [ruff] Clarify intentional async contexts for unused-async (RUF029) (#26641)

Contributors

Install ruff 0.15.22

Install prebuilt binaries via shell script

</tr></table>

... (truncated)

Changelog

Sourced from ruff's changelog.

0.15.22

Released on 2026-07-16.

Preview features

  • [pycodestyle] Add an autofix for E402 (#22212)
  • [refurb] Allow subclassing builtins in stub files (FURB189) (#26812)
  • [ruff] Add rule to replace noqa comments with ruff:ignore (RUF105) (#26423)
  • [ruff] Add rule to use human-readable names in ruff:ignore comments (RUF106) (#26682)
  • [ruff] Add rule to use human-readable names in configuration selectors (RUF201) (#26772)

Bug fixes

  • [flake8-pyi] Fix false positive in __all__ (PYI053) (#26872)

Rule changes

  • [pylint] Ignore mutable type updates in redefined-loop-name (PLW2901) (#25733)

Performance

  • Avoid redundant lexer token bookkeeping (#26765)
  • Avoid redundant pending-indentation writes (#26774)
  • Avoid unnecessary identifier lookahead (#26525)
  • Reuse parser scratch buffers (#26798)

Documentation

  • Document argfile support (#26803)
  • [flake8-datetimez] Clarify naming guidance for datetime.today (DTZ002) (#26658)
  • [pycodestyle] Document E731 fix safety (#26847)
  • [ruff] Clarify intentional async contexts for unused-async (RUF029) (#26641)

Contributors

0.15.21

Released on 2026-07-09.

Preview features

... (truncated)

Commits

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=ruff&package-manager=pip&previous-version=0.15.17&new-version=0.15.22)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore major version` will close this group update PR and stop Dependabot creating any more for the specific dependency's major version (unless you unignore this specific dependency's major version or upgrade to it yourself) - `@dependabot ignore minor version` will close this group update PR and stop Dependabot creating any more for the specific dependency's minor version (unless you unignore this specific dependency's minor version or upgrade to it yourself) - `@dependabot ignore ` will close this group update PR and stop Dependabot creating any more for the specific dependency (unless you unignore this specific dependency or upgrade to it yourself) - `@dependabot unignore ` will remove all of the ignore conditions of the specified dependency - `@dependabot unignore ` will remove the ignore condition of the specified dependency and ignore conditions
Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .pre-commit-config.yaml | 2 +- pyproject.toml | 2 +- uv.lock | 40 ++++++++++++++++++++-------------------- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 402975fd6..08ee4e215 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -27,7 +27,7 @@ repos: # unconditionally, so installing hooks is not required for enforcement. args: [--assume-in-merge] - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.15.17 + rev: v0.15.22 hooks: - id: ruff args: [--fix] diff --git a/pyproject.toml b/pyproject.toml index bb5ea79a3..442c1be54 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -270,7 +270,7 @@ dev = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-asyncio>=0.21.0", - "ruff==0.15.17", + "ruff==0.15.22", "mypy>=1.0.0", "pre-commit>=3.0.0", "openai>=1.0.0", diff --git a/uv.lock b/uv.lock index 98aae70bd..60186b9f5 100644 --- a/uv.lock +++ b/uv.lock @@ -1999,7 +1999,7 @@ requires-dist = [ { name = "rapidocr-onnxruntime", marker = "python_full_version < '3.13' and extra == 'image'", specifier = ">=1.4.0,<2" }, { name = "respx", marker = "extra == 'dev'", specifier = ">=0.20.0" }, { name = "rich", specifier = ">=13.0.0" }, - { name = "ruff", marker = "extra == 'dev'", specifier = "==0.15.17" }, + { name = "ruff", marker = "extra == 'dev'", specifier = "==0.15.22" }, { name = "scikit-learn", marker = "extra == 'evals'", specifier = ">=1.3.0" }, { name = "sentence-transformers", marker = "sys_platform == 'darwin' and extra == 'pytorch-mps'", specifier = ">=2.2.0" }, { name = "sentence-transformers", marker = "(platform_machine != 'x86_64' and extra == 'evals') or (sys_platform != 'darwin' and extra == 'evals')", specifier = ">=2.2.0,<6.0" }, @@ -5765,27 +5765,27 @@ wheels = [ [[package]] name = "ruff" -version = "0.15.17" +version = "0.15.22" source = { registry = "https://pypi.org/simple/" } -sdist = { url = "https://files.pythonhosted.org/packages/8c/a9/3abdf488f1bf3d24c699415e454ed554a6350d5d89ce183be1ee0a3361ac/ruff-0.15.17.tar.gz", hash = "sha256:2ec446937fd16c8c4de2674a209cc5af64d9c6f17d21fbf1151054fa0bcf5219", size = 4743346, upload-time = "2026-06-11T17:54:47.663Z" } +sdist = { url = "https://files.pythonhosted.org/packages/3a/06/ae069393fc66e8ff33036d4b368003833bf6e88ccf182e17e7a2f1c754fd/ruff-0.15.22.tar.gz", hash = "sha256:3f15175b1fb580126f58285a5dae6b2ea89000136d980c64499211f116b54809", size = 4785063, upload-time = "2026-07-16T15:14:13.244Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/db/4d/e11259f5da07cb6afb2d074c31bf09da9671993f7329d4f15d2fdc458301/ruff-0.15.17-py3-none-linux_armv6l.whl", hash = "sha256:d9feddb927fc68bd295f5eebc587a7e42cfaf9b65f60ca4a2386febff575da8f", size = 10856677, upload-time = "2026-06-11T17:54:49.533Z" }, - { url = "https://files.pythonhosted.org/packages/29/3e/772d679e1a0dc058e58875bd2c0cb713a0530877b4a76fee3c7966df0d49/ruff-0.15.17-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:25805a226d741c47d274a35ad5c10a7dde175fcddfa511d7cf3da0a21eb3eab7", size = 11223443, upload-time = "2026-06-11T17:55:00.573Z" }, - { url = "https://files.pythonhosted.org/packages/68/58/bd41f7688b2fd5623012605130ed70e60aa7f2244baa3d5066bdd61530c8/ruff-0.15.17-py3-none-macosx_11_0_arm64.whl", hash = "sha256:f6ad73b14c2d18a3bf8ad7cb6974294d7f613a7898604826058e6ac64918ef4d", size = 10566458, upload-time = "2026-06-11T17:55:07.52Z" }, - { url = "https://files.pythonhosted.org/packages/d8/5b/733371013fcf1ec339e477ece6ab42bfe10bdd9bba8ee88a9516aa56bfc0/ruff-0.15.17-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6ba0c1e4f95bcb3869d0d30cbd5917071ef2e28665abfec970cdab0492c713ed", size = 10914483, upload-time = "2026-06-11T17:55:05.501Z" }, - { url = "https://files.pythonhosted.org/packages/bd/cc/6f24251cc0252f7239391ccb85833f320efad14ebe5b443943f37ced6332/ruff-0.15.17-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:81647960f10bff57d2e51cadd0c3950fe598400c852863a038720ef5b8cca91e", size = 10647497, upload-time = "2026-06-11T17:54:57.733Z" }, - { url = "https://files.pythonhosted.org/packages/68/dd/0d10c17ce1a1624d6fc3156309c3f834fdb5dfaad026ec90c85684f3990e/ruff-0.15.17-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:0e01a84ddbc8c16c23055ba3924476850f1bbc1917cebbb9376665a63e74260d", size = 11416967, upload-time = "2026-06-11T17:54:51.461Z" }, - { url = "https://files.pythonhosted.org/packages/2f/91/556bfb156f6144f355e831c23db00b2fc4120f86b3ce81cc5f7fd2df51f3/ruff-0.15.17-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:84fe9f653152f8f294f9f7e03bf3a453d8b4a27f7a59c78c8666167f2b17b96c", size = 12335770, upload-time = "2026-06-11T17:54:45.793Z" }, - { url = "https://files.pythonhosted.org/packages/88/82/8b5999aa13355e926f06d9f42a32dcca862f623bf0363785ff89d607dffd/ruff-0.15.17-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8c0fe88a7676e7a05b73174d4d4a59cb2ac21ff8263583f87a81a6018475a978", size = 11575441, upload-time = "2026-06-11T17:54:32.661Z" }, - { url = "https://files.pythonhosted.org/packages/11/93/f10377bb04109ca0e8cbc483ff1982c54b6d418210041776f93e8cdc7fa9/ruff-0.15.17-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ecfc3c7878fff94633ab0348524e093f9ce3243080416dd7d14f8ba400174719", size = 11557614, upload-time = "2026-06-11T17:54:34.698Z" }, - { url = "https://files.pythonhosted.org/packages/c7/a6/eeeae7f7d5493df41649ab3db92f086b2d0a30199e4efdf8e3dd7a033f24/ruff-0.15.17-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:b8461180b22420b1bdc289909410930761629fddf2a5aaf60fae1ab26cedc4c4", size = 11544450, upload-time = "2026-06-11T17:54:39.042Z" }, - { url = "https://files.pythonhosted.org/packages/32/88/5991ce565129a24dd4a00db1254b3b5db2e53018cbe4018ea5a89738e727/ruff-0.15.17-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:6eccbe50a038b503e7140b441aa9c7fc8c1f36edf23ebef9f4165c2f28f568b7", size = 10892524, upload-time = "2026-06-11T17:55:09.432Z" }, - { url = "https://files.pythonhosted.org/packages/f5/1d/0fdd248313425f55223968af04b0a42125466a8d88d21c1d99c6af0a51e8/ruff-0.15.17-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:382fc0521025f5a8ad447d8bdd523545d0d7646adb718eb1c2dac5065ec27c0f", size = 10659573, upload-time = "2026-06-11T17:54:36.824Z" }, - { url = "https://files.pythonhosted.org/packages/9e/0e/072e8260deb9461062ce9311ced27a8e541229a6ffd483013dd37661e43e/ruff-0.15.17-py3-none-musllinux_1_2_i686.whl", hash = "sha256:456d41fcd1b2777ad63f09a6e7121d43f7b688bbc76a800c10f7f8fb1f912c3f", size = 11127818, upload-time = "2026-06-11T17:55:03.124Z" }, - { url = "https://files.pythonhosted.org/packages/ab/b4/55060a34163121498014696b5f656db5b8c6963768f227dbf0d76b311073/ruff-0.15.17-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b1a04bcc94ae6194e9db05d16ad31f298a7194bfbcb08258bbe589cee1d587b8", size = 11655901, upload-time = "2026-06-11T17:54:53.562Z" }, - { url = "https://files.pythonhosted.org/packages/49/71/9b29d6b87cef468d697f43c6a91e3fae4a80185779d7d5a4ef27d173439f/ruff-0.15.17-py3-none-win32.whl", hash = "sha256:596065960ab1ff593f744220c9fe6580eda00a95003cffa9f4048bb5b1bf0392", size = 10925574, upload-time = "2026-06-11T17:54:55.723Z" }, - { url = "https://files.pythonhosted.org/packages/3d/b2/8fc77f3723228836fa5d12497eb71c808f83782e10d058d2b15cfa14640b/ruff-0.15.17-py3-none-win_amd64.whl", hash = "sha256:6769e5fa1710b179b92e0bfa5a51735b35baea9013dadb06d5f44cbcf9547084", size = 12058788, upload-time = "2026-06-11T17:54:41.042Z" }, - { url = "https://files.pythonhosted.org/packages/2d/c7/c53e8dbff9c9dc4b7928773421ae294a5d28fcb8dcda1a089579d3a7e510/ruff-0.15.17-py3-none-win_arm64.whl", hash = "sha256:f3be1fbb34bcdfd146240d8fb92a709d4c2c8191348580a3c044ec60fa0b4456", size = 11355275, upload-time = "2026-06-11T17:54:43.635Z" }, + { url = "https://files.pythonhosted.org/packages/23/18/ee54b7ae1e121be7a28ea6da4b67564ebb0530e183a54415ab7e3bcd2c4e/ruff-0.15.22-py3-none-linux_armv6l.whl", hash = "sha256:44423e73493737f5e7c5b41d475483898ff37afcdae38bc3da5085e29af1c2d8", size = 10781258, upload-time = "2026-07-16T15:13:19.452Z" }, + { url = "https://files.pythonhosted.org/packages/2f/d2/2520cb14761ddbeaf57642a76942fc36adcbdbe53b4532241995f6fc485c/ruff-0.15.22-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b82c6482946e9eda7ff2e091d25b8bad3f718684e1916d41bd56873cee05b697", size = 10999477, upload-time = "2026-07-16T15:13:23.318Z" }, + { url = "https://files.pythonhosted.org/packages/c9/10/74e53572aa758dfaa678c2a2646b5c5515d884b7ca56be4d2ce03ca4b560/ruff-0.15.22-py3-none-macosx_11_0_arm64.whl", hash = "sha256:11c1c715af53a09f714e011106bffc419751ec8232fcb5da42173284ea3fec6f", size = 10466716, upload-time = "2026-07-16T15:13:26.162Z" }, + { url = "https://files.pythonhosted.org/packages/1e/cc/44eaaf0844e028182f2d0a8f2190d0f359159aed0a9e5ab861d892f1ae2a/ruff-0.15.22-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:742a29cf29bddb7c8327895d6a10e0e6c5b38a96dd407af9b5d0857f809c0576", size = 10892644, upload-time = "2026-07-16T15:13:29.229Z" }, + { url = "https://files.pythonhosted.org/packages/9f/21/8edf559014d2b0f82beea19cfb713993ad802ccda16868769979c6090a84/ruff-0.15.22-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:72af58b951b0ae395935ae79763dc349bc0eb706319d28f7a33ad2cfb3cfc178", size = 10576719, upload-time = "2026-07-16T15:13:32.35Z" }, + { url = "https://files.pythonhosted.org/packages/bf/1e/3a13abd392a3b50b62e5938a831f9ab6e588358cacad5c18545b716d2182/ruff-0.15.22-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:62d425005c1835eb24e2ee4161cb90e8db263415f4a71c8c72c33abaa6c0c224", size = 11376494, upload-time = "2026-07-16T15:13:35.958Z" }, + { url = "https://files.pythonhosted.org/packages/bf/3e/422d3d95bcf04dd78e1aeac22184d4f9a8fb2c01865d39d44618484a0317/ruff-0.15.22-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e8b9b3f8779a4f08c969defc3c8c35abffaa757e601ed5ae66d6d1db6519969a", size = 12208370, upload-time = "2026-07-16T15:13:39.185Z" }, + { url = "https://files.pythonhosted.org/packages/1e/91/5d065a0e0a02bf4813f5119ad278462eed081d2b832eb7c021ade0ec9e65/ruff-0.15.22-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1e0dd1b2e4d3d585f897a0d137cbf4eaf6223bef4e8ce34d6bb12556c5f9249e", size = 11581098, upload-time = "2026-07-16T15:13:42.132Z" }, + { url = "https://files.pythonhosted.org/packages/f6/f9/a0d4871d12fae702eb1f41b686caf05f1f8b124dc6db6f784f53d74918fa/ruff-0.15.22-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:365523eb91d9224e1bcb03b022fbf0facb8f9e23792a2c53d9d4b3924bdbdebb", size = 11399422, upload-time = "2026-07-16T15:13:45.2Z" }, + { url = "https://files.pythonhosted.org/packages/18/80/c843a5176cddbceb0b7e8dd41cf9993490796c1c469348d384f5a5c13c56/ruff-0.15.22-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:fabfd168afdf29fee5be98b831efa9683c94d7c5a3b58b9ce5a2e38444589a74", size = 11381683, upload-time = "2026-07-16T15:13:48.46Z" }, + { url = "https://files.pythonhosted.org/packages/d4/00/8485de0ae92239438a36cfc51350db9b9e85c9ebdfaea91b18e422706662/ruff-0.15.22-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:225dbf095a87f1d9f90f5fd7924d2613ee452a75a4308c63a8f50f761787aa7c", size = 10850295, upload-time = "2026-07-16T15:13:51.655Z" }, + { url = "https://files.pythonhosted.org/packages/fa/91/24977ec2ec72eaf15e4394ace2959fdff2dd1e14f03e005e838023407169/ruff-0.15.22-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:1877d63b9d24ed278744f1523fd11b85540566d54641f97c566d7d9dc5ca5296", size = 10579640, upload-time = "2026-07-16T15:13:54.79Z" }, + { url = "https://files.pythonhosted.org/packages/9c/47/9b51216951974df1f263ac19da550d34252e0ed7218c25f10c5ef9ed7517/ruff-0.15.22-py3-none-musllinux_1_2_i686.whl", hash = "sha256:a1606c510bd7215680d32efab38965f7cdec3ef69f5170a3f4791404ffdd5262", size = 11105077, upload-time = "2026-07-16T15:13:57.915Z" }, + { url = "https://files.pythonhosted.org/packages/c2/47/20e9d4a3b8016778acea5fc32bb50d35d207500a17ddb529ffa6996feef8/ruff-0.15.22-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:630479b18625f5ffc373f77603a22a9f8ac0acd7ff0501178b5db28ec71e9c64", size = 11490980, upload-time = "2026-07-16T15:14:01.032Z" }, + { url = "https://files.pythonhosted.org/packages/4d/76/3f72d8fc38c1cb77b38c56a70da9d0c17700cc1cc50f9649c9d3c8f5ba71/ruff-0.15.22-py3-none-win32.whl", hash = "sha256:e5ba0e4a13fd14abbed2a77b517a3911290c6c6c59ef67784328d1668fab76cf", size = 10789165, upload-time = "2026-07-16T15:14:04.16Z" }, + { url = "https://files.pythonhosted.org/packages/cb/46/4965251734c2b6fcdca1b1b187d20bcac3af0ee5b083b89c910bb961ce3a/ruff-0.15.22-py3-none-win_amd64.whl", hash = "sha256:9be63ba1eb936acd2d1342fb8337c356353706fce233b2a15a09a97037e6acde", size = 11938297, upload-time = "2026-07-16T15:14:07.316Z" }, + { url = "https://files.pythonhosted.org/packages/57/c9/e69b1ff4c8b69093ef08b8919ab767af0569666865b39c30a8795d88d3c6/ruff-0.15.22-py3-none-win_arm64.whl", hash = "sha256:e1168075b72158510839f250027659cdd78476f40507dd517892304c41318661", size = 11298172, upload-time = "2026-07-16T15:14:10.51Z" }, ] [[package]] From 522faa1a59aa94e4adfd4a4afe0202d1126e187d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:32:06 -0500 Subject: [PATCH 026/138] deps: bump rusqlite from 0.32.1 to 0.40.1 (#2287) Bumps [rusqlite](https://github.com/rusqlite/rusqlite) from 0.32.1 to 0.40.1.
Release notes

Sourced from rusqlite's releases.

0.40.1

What's Changed

  • Fix clippy warnings #1852
  • Bump bundled SQLite version to 3.53.2 #1853
  • Bump hashlink version #1855
  • Fix SQL injection when SAVEPOINT name is tainted #1854

Full Changelog: https://github.com/rusqlite/rusqlite/compare/v0.40.0...v0.40.1

0.40.0

What's Changed

  • Breaking changes: Replace VTab macros by constructors #1823
  • Breaking changes: Fix VTab::best_index #1824
  • Asserts on VTab::connect aux and args #1825
  • Breaking changes: Fix VTab::connect / create #1826
  • Breaking changes: Allow opting out of using sqlite-wasm-rs on wasm32-unknown-unknown #1828, #1829
  • Derive Default for SeriesTabCursor/ArrayTabCursor #1830
  • Update link to pre-update hook #1831
  • Breaking changes: Fix VTab::connect #1832
  • impl From for FromSqlError #1833
  • Breaking changes: Fix vtab::dequote #1835
  • Bump bundled SQLCipher to version 4.14.0 #1837
  • sqlite3_set_errmsg #1752
  • Bump sqlite3-parser version #1838
  • Fix UB in ToSqlOutput::from_rc #1839
  • Ensure miri doesn't complain #1840
  • Bump to actions/checkout@v6 #1842
  • Add support to UtcDateTime #1843, #1844
  • Bump bundled SQLite version to 3.53.1 #1848
  • Replace some cfg(not by cfg_select #1850

Full Changelog: https://github.com/rusqlite/rusqlite/compare/v0.39.0...v0.40.0

0.39.0

What's Changed

  • Fix constraints on VTab Aux data #1778, #1771
  • Fix docs.rs generation #1779
  • Fix a small typo in rollback_hook docstring #1780
  • Fix some warnings from Intellij #1781
  • Minimal doc for features #1783
  • Clear hooks only for owning connections #1785, #1784
  • Fix link to SQLite C Interface, Prepare Flags #1787
  • Comment functions which are not usable from a loadable extension #1789
  • Factorize code #1792
  • Update getrandom to 0.4 #1798
  • Update Cargo.toml #1800
  • Fix appveyor #1807
  • Add support to unix timestamp for chrono, jiff and time #1808, #1803
  • fix(trace): check that the sql string pointer is not NULL #1805
  • Bump bundled SQLite version to 3.51.3 #1818

... (truncated)

Commits

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=rusqlite&package-manager=cargo&previous-version=0.32.1&new-version=0.40.1)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- Cargo.lock | 42 ++++++++++++++++++++++++--------- crates/headroom-core/Cargo.toml | 2 +- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 5959d3596..7be07cbd2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1831,9 +1831,6 @@ name = "hashbrown" version = "0.14.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" -dependencies = [ - "ahash", -] [[package]] name = "hashbrown" @@ -1861,11 +1858,11 @@ dependencies = [ [[package]] name = "hashlink" -version = "0.9.1" +version = "0.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af" +checksum = "32069d97bb81e38fa67eab65e3393bf804bb85969f2bc06bf13f64aef5aba248" dependencies = [ - "hashbrown 0.14.5", + "hashbrown 0.17.1", ] [[package]] @@ -2610,9 +2607,9 @@ dependencies = [ [[package]] name = "libsqlite3-sys" -version = "0.30.1" +version = "0.38.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149" +checksum = "f6c19a05435c21ac299d71b6a9c13db3e3f47c520517d58990a462a1397a61db" dependencies = [ "cc", "pkg-config", @@ -3724,10 +3721,20 @@ dependencies = [ ] [[package]] -name = "rusqlite" -version = "0.32.1" +name = "rsqlite-vfs" +version = "0.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e" +checksum = "c51c9ae4df8a7fba42103df5c621fa3c37eccf3a3c650879e90fc48b11cc192c" +dependencies = [ + "hashbrown 0.16.1", + "thiserror 2.0.18", +] + +[[package]] +name = "rusqlite" +version = "0.40.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "11438310b19e3109b6446c33d1ed5e889428cf2e278407bc7896bc4aaea43323" dependencies = [ "bitflags", "fallible-iterator", @@ -3735,6 +3742,7 @@ dependencies = [ "hashlink", "libsqlite3-sys", "smallvec", + "sqlite-wasm-rs", ] [[package]] @@ -4105,6 +4113,18 @@ dependencies = [ "unicode-segmentation", ] +[[package]] +name = "sqlite-wasm-rs" +version = "0.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc3efc0da82635d7e1ced0053bbbfa8c7ab9645d0bf36ceb4f7127bb85315d75" +dependencies = [ + "cc", + "js-sys", + "rsqlite-vfs", + "wasm-bindgen", +] + [[package]] name = "stable_deref_trait" version = "1.2.1" diff --git a/crates/headroom-core/Cargo.toml b/crates/headroom-core/Cargo.toml index c47d2a88b..534a41b78 100644 --- a/crates/headroom-core/Cargo.toml +++ b/crates/headroom-core/Cargo.toml @@ -125,7 +125,7 @@ blake3 = "1" # image may lag behind. Sub-1 MB binary cost. WAL is enabled at # connection-open time (see `ccr/backends/sqlite.rs`); no extra feature # flags required. -rusqlite = { version = "0.32", features = ["bundled"] } +rusqlite = { version = "0.40", features = ["bundled"] } # `redis` for the optional multi-worker CCR backend. Cfg-gated behind # the `redis` feature so deploys that don't need it pay no compile # cost. Default features include the sync `Connection` API used in From 6448545a7f5a1dee88bce6f0830bdbfd1c99c617 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:32:34 -0500 Subject: [PATCH 027/138] deps: bump bytesize from 1.3.3 to 2.4.2 (#2286) Bumps [bytesize](https://github.com/bytesize-rs/bytesize) from 1.3.3 to 2.4.2.
Release notes

Sourced from bytesize's releases.

bytesize: v2.4.2

  • Improve accuracy of parsing large non-decimal byte count strings.

bytesize: v2.4.1

  • Fix rounding error near power-of-unit boundaries.

bytesize: v2.4.0

  • Implement Sum for ByteSize.
  • Minimum supported Rust version (MSRV) is now 1.85.

bytesize: v2.3.1

  • Fix unit truncation in error strings.

bytesize: v2.3.0

  • Add Unit enum.
  • Add UnitParseError type.

bytesize: v2.2.0

  • Add ByteSize::as_*() methods to return equivalent sizes in KB, GiB, etc.

bytesize: v2.1.0

  • Support parsing and formatting exabytes (EB) & exbibytes (EiB).
  • Migrate serde dependency to serde_core.

bytesize: v2.0.1

  • Add support for precision in Display implementations.

bytesize: v2.0.0

  • Add support for no_std targets.
  • Use IEC (binary) format by default with Display.
  • Use "kB" for SI unit.
  • Add Display type for customizing printed format.
  • Add ByteSize::display() method.
  • Implement Sub<ByteSize> for ByteSize.
  • Implement Sub<impl Into<u64>> for ByteSize.
  • Implement SubAssign<ByteSize> for ByteSize.
  • Implement SubAssign<impl Into<u64>> for ByteSize.
  • Reject parsing non-unit characters after whitespace.
  • Remove ByteSize::to_string_as() method.
  • Remove top-level to_string() method.
  • Remove top-level B constant.
Changelog

Sourced from bytesize's changelog.

2.4.2

  • Improve accuracy of parsing large non-decimal byte count strings.

2.4.1

  • Fix rounding error near power-of-unit boundaries.

2.4.0

  • Implement Sum for ByteSize.
  • Minimum supported Rust version (MSRV) is now 1.85.

2.3.1

  • Fix unit truncation in error strings.

2.3.0

  • Add Unit enum.
  • Add UnitParseError type.

2.2.0

  • Add ByteSize::as_*() methods to return equivalent sizes in KB, GiB, etc.

2.1.0

  • Support parsing and formatting exabytes (EB) & exbibytes (EiB).
  • Migrate serde dependency to serde_core.

2.0.1

  • Add support for precision in Display implementations.

v2.0.0

  • Add support for no_std targets.
  • Use IEC (binary) format by default with Display.
  • Use "kB" for SI unit.
  • Add Display type for customizing printed format.
  • Add ByteSize::display() method.
  • Implement Sub<ByteSize> for ByteSize.
  • Implement Sub<impl Into<u64>> for ByteSize.
  • Implement SubAssign<ByteSize> for ByteSize.
  • Implement SubAssign<impl Into<u64>> for ByteSize.
  • Reject parsing non-unit characters after whitespace.
  • Remove ByteSize::to_string_as() method.
  • Remove top-level to_string() method.
  • Remove top-level B constant.
Commits
  • 2f8d196 chore: release v2.4.2 (#177)
  • 13f4aee Avoid f64 precision loss when parsing integer byte counts (#171)
  • 37cf3fc chore: release v2.4.1 (#176)
  • c84e293 chore(deps): bump actions-rust-lang/setup-rust-toolchain from 1.16.1 to 1.17....
  • fdba7f0 chore(deps): bump taiki-e/install-action from 2.81.10 to 2.82.7 (#173)
  • 1bad401 chore(deps): bump actions/checkout from 6.0.3 to 7.0.0 (#174)
  • 520a557 fix: ideal_unit_std picks the wrong unit near power-of-unit boundaries (#175)
  • a50ff2f chore(deps): bump taiki-e/install-action from 2.75.27 to 2.81.10 (#163)
  • ce689d7 chore(deps): bump codecov/codecov-action from 6.0.0 to 7.0.0 (#164)
  • 284b09d chore(deps): bump serde_json from 1.0.149 to 1.0.150 (#165)
  • Additional commits viewable in compare view

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=bytesize&package-manager=cargo&previous-version=1.3.3&new-version=2.4.2)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- Cargo.lock | 4 ++-- crates/headroom-proxy/Cargo.toml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 7be07cbd2..6dd065fb6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -861,9 +861,9 @@ dependencies = [ [[package]] name = "bytesize" -version = "1.3.3" +version = "2.4.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2e93abca9e28e0a1b9877922aacb20576e05d4679ffa78c3d6dc22a26a216659" +checksum = "3d7c8918969267b2932ffd5655509bbbea0833823058c378876953217f5fc50e" [[package]] name = "cast" diff --git a/crates/headroom-proxy/Cargo.toml b/crates/headroom-proxy/Cargo.toml index 898645e9d..813b826a7 100644 --- a/crates/headroom-proxy/Cargo.toml +++ b/crates/headroom-proxy/Cargo.toml @@ -38,7 +38,7 @@ http-body-util = "0.1" hyper = "1" url = "2" humantime = "2" -bytesize = "1" +bytesize = "2" tokio-util = { version = "0.7" } headroom-core = { path = "../headroom-core" } # Phase D PR-D1: native Bedrock InvokeModel route. SigV4 + AWS From 4925bf6a829735977bab5000b469c3edb19c75b1 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:32:59 -0500 Subject: [PATCH 028/138] deps: bump hf-hub from 0.4.3 to 0.5.0 (#2285) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [hf-hub](https://github.com/huggingface/hf-hub) from 0.4.3 to 0.5.0.
Release notes

Sourced from hf-hub's releases.

v0.5.0

What's Changed

New Contributors

Full Changelog: https://github.com/huggingface/hf-hub/compare/v0.4.3...v0.5.0

Changelog

Sourced from hf-hub's changelog.

Releasing hf-hub

This document covers the full release process for the hf-hub crate. If anything here is unclear or out of date, please open a PR.

What gets released

A single tag push releases one artifact:

  • hf-hub Rust crate on crates.io, via .github/workflows/rust-release.yml.

The workflow triggers on tags matching v* (e.g., v1.0.0, v1.0.0-rc.0).

There are no Python components in this repo. The other workspace members are not published:

  • hfrs/ — CLI binary, distributed via cargo install --git.
  • examples/, benches/, integration-tests/ — internal-only, version 0.0.0, never published.

Pre-release checklist

  1. CI is green on main. The Rust workflow must be passing on every platform in the matrix (Ubuntu, Windows, macOS) with both feature configurations ("" and --all-features).
  2. Review the diff since the last release. 
    git log --oneline v0.5.0..main
git diff v0.5.0..main --stat -- hf-hub/
    Pay particular attention to changes under hf-hub/src/ — those are the only changes that actually ship to crates.io.
  3. Identify breaking changes. Anything that changes the public Rust API (types, function signatures, removed re-exports, builder fields) needs to be reflected in the version bump per semver and called out in the release notes.
  4. Run the full pre-release test sweep (see next section).

Pre-release test sweep

Run all of these from the repo root before tagging. They mirror what CI runs, plus a publish dry-run that CI does not currently do.

Format and lint

cargo +nightly fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo clippy --workspace --all-targets --all-features -- -D warnings

Unit tests (hf-hub)

cargo test -p hf-hub
cargo test -p hf-hub --features blocking

Integration tests (integration-tests)

... (truncated)

Commits

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=hf-hub&package-manager=cargo&previous-version=0.4.3&new-version=0.5.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- Cargo.lock | 92 +++------------------------------ crates/headroom-core/Cargo.toml | 2 +- 2 files changed, 7 insertions(+), 87 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 6dd065fb6..88a1eccd1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1037,19 +1037,6 @@ dependencies = [ "static_assertions", ] -[[package]] -name = "console" -version = "0.15.11" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "054ccb5b10f9f2cbf51eb355ca1d05c2d279ce1804688d0db74b4733a5aeafd8" -dependencies = [ - "encode_unicode", - "libc", - "once_cell", - "unicode-width", - "windows-sys 0.59.0", -] - [[package]] name = "console" version = "0.16.3" @@ -1549,7 +1536,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f3c8600c9ec79b51d60c19911fe14eac04fe9c2895e87d2a3e80e2213d645a32" dependencies = [ "anyhow", - "hf-hub 0.5.0", + "hf-hub", "image", "ndarray", "ort", @@ -1876,7 +1863,7 @@ dependencies = [ "dashmap", "fastembed", "flate2", - "hf-hub 0.4.3", + "hf-hub", "http 1.4.2", "icu_segmenter", "magika", @@ -2016,26 +2003,6 @@ version = "0.4.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" -[[package]] -name = "hf-hub" -version = "0.4.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "629d8f3bbeda9d148036d6b0de0a3ab947abd08ce90626327fc3547a49d59d97" -dependencies = [ - "dirs", - "http 1.4.2", - "indicatif 0.17.11", - "libc", - "log", - "rand 0.9.4", - "reqwest", - "serde", - "serde_json", - "thiserror 2.0.18", - "ureq 2.12.1", - "windows-sys 0.60.2", -] - [[package]] name = "hf-hub" version = "0.5.0" @@ -2044,7 +2011,7 @@ checksum = "aef3982638978efa195ff11b305f51f1f22f4f0a6cabee7af79b383ebee6a213" dependencies = [ "dirs", "http 1.4.2", - "indicatif 0.18.4", + "indicatif", "libc", "log", "rand 0.9.4", @@ -2052,7 +2019,7 @@ dependencies = [ "serde", "serde_json", "thiserror 2.0.18", - "ureq 3.3.0", + "ureq", "windows-sys 0.61.2", ] @@ -2438,26 +2405,13 @@ dependencies = [ "hashbrown 0.17.1", ] -[[package]] -name = "indicatif" -version = "0.17.11" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "183b3088984b400f4cfac3620d5e076c84da5364016b4f49473de574b2586235" -dependencies = [ - "console 0.15.11", - "number_prefix", - "portable-atomic", - "unicode-width", - "web-time", -] - [[package]] name = "indicatif" version = "0.18.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "25470f23803092da7d239834776d653104d551bc4d7eacaf31e6837854b8e9eb" dependencies = [ - "console 0.16.3", + "console", "portable-atomic", "unicode-width", "unit-prefix", @@ -2956,12 +2910,6 @@ dependencies = [ "libc", ] -[[package]] -name = "number_prefix" -version = "0.4.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "830b246a0e5f20af87141b25c173cd1b609bd7779a4617d6ec582abaf90870f3" - [[package]] name = "once_cell" version = "1.21.4" @@ -4362,7 +4310,7 @@ dependencies = [ "derive_builder", "esaxx-rs", "getrandom 0.3.4", - "indicatif 0.18.4", + "indicatif", "itertools 0.14.0", "log", "macro_rules_attribute", @@ -4842,25 +4790,6 @@ version = "0.9.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" -[[package]] -name = "ureq" -version = "2.12.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d" -dependencies = [ - "base64 0.22.1", - "flate2", - "log", - "once_cell", - "rustls", - "rustls-pki-types", - "serde", - "serde_json", - "socks", - "url", - "webpki-roots 0.26.11", -] - [[package]] name = "ureq" version = "3.3.0" @@ -5236,15 +5165,6 @@ dependencies = [ "windows-targets 0.52.6", ] -[[package]] -name = "windows-sys" -version = "0.59.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" -dependencies = [ - "windows-targets 0.52.6", -] - [[package]] name = "windows-sys" version = "0.60.2" diff --git a/crates/headroom-core/Cargo.toml b/crates/headroom-core/Cargo.toml index 534a41b78..5fd25553c 100644 --- a/crates/headroom-core/Cargo.toml +++ b/crates/headroom-core/Cargo.toml @@ -22,7 +22,7 @@ tokenizers = "0.22" # with `rustls` (no system OpenSSL dep — keeps the binary static-linkable for # AWS deploys). `from_pretrained` is called once at startup, so blocking is # fine; if a tokio caller needs it later we can wrap in `spawn_blocking`. -hf-hub = { version = "0.4", default-features = false, features = ["ureq", "rustls-tls"] } +hf-hub = { version = "0.5", default-features = false, features = ["ureq", "rustls-tls"] } # `md5` for the CCR cache_key. Python's compression_store hashes the original # diff with MD5 truncated to 24 hex chars; we must match byte-for-byte. md-5 = "0.10" From 1a04c957f53ef25ab1209166f425a7876913c4d3 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Mon, 10 Aug 2026 22:38:51 -0700 Subject: [PATCH 029/138] fix(cache): stabilize Anthropic block-growing lineages (#2917) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Fixes the remaining Anthropic prompt-cache failure in #2671 and the newly reported parallel-tool-profile variant. The production failure has three connected parts: 1. `SessionTrackerStore.resolve_tracker` only recognized whole-message prefixes. A caller that grows or regenerates blocks inside one message therefore received a fresh tracker every turn, so previous forwarded state was always empty and breakpoint relocation could never run. 2. `normalize_message_cache_control` always moved the message breakpoint to the newest block. That is correct for a pure block append, but a message that rewrites its tail can never match the prior newest-block write and repeatedly rewrites the full message prefix. 3. Parallel Anthropic sub-calls can carry identical messages but different tools. Because tools precede messages in the provider cache key, sharing one frozen-prefix tracker across those calls cross-contaminates cache state even when message lineage is identical. This PR deliberately combines the valid parts of #2699 and #2702, fixes the discriminator between their two shapes, and adds cache-key affinity for the second pattern reported on #2671. In particular, a pure append is identified by `stable_prefix_blocks == previous_block_count`; rewritten-tail relocation is only possible when `stable_prefix_blocks < previous_block_count`. This prevents a pure append from being pinned to an old boundary. Closes #2671. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [x] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Added one canonical history classifier with distinct exact, whole-message append, pure block append, rewritten-tail, and diverged outcomes. - Kept pure block appends on newest-block breakpoint placement so each request reads the old prefix and writes only its appended blocks. - Added block-level replay of the prior forwarded bytes for pure appends; the whole-message delta path explicitly refuses this shape so it cannot silently discard appended blocks. - Kept a rewritten-tail request on its existing tracker and anchored its breakpoint to the end of the byte-stable leading run. - Made rewritten-tail matching conservative: one changed message, unchanged message count, no shrink, at least 8 stable leading blocks covering at least half of old and new content, and a fixed suffix of at least 2 blocks. - Required a unique best rewritten-tail lineage match. Ambiguity creates a fresh lineage instead of making sibling sub-calls ping-pong one tracker. - Added a stable affinity fingerprint over model, deterministically forwarded tools, tool choice, thinking, and output configuration. Different provider cache-key profiles cannot share frozen-prefix state. - Snapshotted previous original/forwarded messages once in the Anthropic handler and reused that exact state for delta extraction, replay, and breakpoint placement. - Added `HEADROOM_STABLE_BOUNDARY_BREAKPOINT=0` as a rollback switch for rewritten-tail relocation. The canonical projection is used only for comparison. Replayed content always comes from the exact previously forwarded bytes or the current raw/optimized tail; canonicalized data is never reconstructed into an upstream request. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check` on changed files) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ python -m pytest tests/test_issue_2671_block_growth_cache.py -q 12 passed in 0.10s $ python -m pytest tests/test_cache -q 253 passed, 3 skipped in 1.94s $ python -m pytest -q 134 passed, 1 warning in 9.42s $ ruff format --check 4 files already formatted $ ruff check All checks passed! $ git diff --check # clean ``` The Anthropic regression set covers beta stickiness, CCR injection, compaction transforms, pre-upstream backpressure, streaming reconstruction, upstream headers, model sanitization, diagnostics, and cache stability. ## Real Behavior Proof - Environment: macOS, Python 3.12.13, real FastAPI Anthropic handler with a local upstream stub plus a deterministic provider-cache oracle. - Exact steps: send a cold 35-block aggregate message, then three requests that preserve a 30-block prefix and fixed two-block suffix while regenerating a growing middle tail. Resolve the real session tracker, normalize the real handler body, record the response, and repeat. - Observed result: handler breakpoint indices are `34 -> 29 -> 29`; the cache oracle transitions from a cold 35-block write to establishing the 30-block stable boundary, then produces `(read=30, write=0)` on subsequent rewritten-tail turns. A separate pure-append sequence produces `(0,30) -> (30,4) -> (34,4) -> (38,5)`, proving its breakpoint continues to advance. - Also observed: identical message histories with different tool schemas resolve to distinct trackers in the real handler path. - Not tested: a live Anthropic billing soak, the complete repository test suite, or mypy. #2702 contains earlier live production measurements for the rewritten-tail mechanism; this PR adds the pure-append correction, affinity isolation, and broader regression model. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding documentation updates where applicable (internal behavior is documented in code; no user-facing surface changed) - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing relevant unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from the Conventional Commit PR title ## Additional Notes - Consolidates the complementary approaches in #2699 and #2702. Credit to @axisrow and @nangsontay for the traces, root-cause work, and live validation that made the two production shapes distinguishable. - The 20-block minimum for relocation mirrors the provider lookup-window risk boundary and keeps short ordinary messages on the established newest-block behavior. - Disabling stable-boundary relocation does not disable improved lineage resolution or tool-profile isolation; it restores only the previous breakpoint placement. Co-authored-by: Tejas Chopra --- headroom/cache/prefix_tracker.py | 386 ++++++++++++++++-- headroom/proxy/handlers/anthropic.py | 43 +- tests/test_issue_2671_block_growth_cache.py | 288 +++++++++++++ tests/test_proxy_anthropic_cache_stability.py | 151 +++++++ 4 files changed, 833 insertions(+), 35 deletions(-) create mode 100644 tests/test_issue_2671_block_growth_cache.py diff --git a/headroom/cache/prefix_tracker.py b/headroom/cache/prefix_tracker.py index d54950191..178300295 100644 --- a/headroom/cache/prefix_tracker.py +++ b/headroom/cache/prefix_tracker.py @@ -21,6 +21,7 @@ import hashlib import itertools import json import logging +import os import time from collections import OrderedDict from dataclasses import dataclass @@ -229,6 +230,184 @@ def _canonicalize_for_prefix_compare(obj: Any) -> Any: return obj +# Canonical relationships between consecutive histories. These constants are +# strings (rather than an Enum) so they remain cheap to log on the request hot +# path and easy to assert in tests. +RELATION_EXACT = "exact" +RELATION_MESSAGE_APPEND = "message_append" +RELATION_BLOCK_APPEND = "block_append" +RELATION_BLOCK_REWRITE_TAIL = "block_rewrite_tail" +RELATION_DIVERGED = "diverged" + + +@dataclass(frozen=True) +class HistoryRelation: + """How a current message history relates to one recorded last turn. + + ``block_append`` and ``block_rewrite_tail`` are deliberately distinct: + Anthropic should keep the breakpoint on the newest block for a pure append, + but anchor it to ``stable_prefix_blocks - 1`` when the previous tail was + rewritten and therefore can never match a prior cache write (#2671). + """ + + kind: str + message_index: int | None = None + stable_prefix_blocks: int = 0 + stable_suffix_blocks: int = 0 + previous_block_count: int = 0 + current_block_count: int = 0 + + +# A rewritten-tail match is intentionally conservative. The production shape +# behind #2671 has a hundred-plus-block stable prefix and a fixed two-block +# suffix. Requiring both avoids merging sibling sub-calls which merely share a +# short injected preamble or a single generic reminder at the end. +_MIN_REWRITE_PREFIX_BLOCKS = 8 +_MIN_REWRITE_SUFFIX_BLOCKS = 2 + + +def _message_fields_outside_content(message: dict[str, Any]) -> dict[str, Any]: + """Return message identity fields, excluding the block list itself.""" + return {key: value for key, value in message.items() if key != "content"} + + +def _stable_leading_block_run(current: list[Any], previous: list[Any]) -> int: + """Number of canonical-equal blocks at the start of both lists.""" + limit = min(len(current), len(previous)) + run = 0 + while run < limit and current[run] == previous[run]: + run += 1 + return run + + +def _stable_trailing_block_run(current: list[Any], previous: list[Any], *, leading_run: int) -> int: + """Non-overlapping canonical-equal suffix length.""" + limit = min(len(current), len(previous)) - leading_run + run = 0 + while run < limit and current[-(run + 1)] == previous[-(run + 1)]: + run += 1 + return run + + +def _classify_history_canonical( + current_messages: list[Any], previous_messages: list[Any] +) -> HistoryRelation: + """Classify two already-canonical, structurally snapshotted histories.""" + if not previous_messages or len(current_messages) < len(previous_messages): + return HistoryRelation(RELATION_DIVERGED) + + changed: HistoryRelation | None = None + for index, previous_message in enumerate(previous_messages): + current_message = current_messages[index] + if current_message == previous_message: + continue + if changed is not None: + return HistoryRelation(RELATION_DIVERGED) + if not isinstance(previous_message, dict) or not isinstance(current_message, dict): + return HistoryRelation(RELATION_DIVERGED) + if _message_fields_outside_content(previous_message) != _message_fields_outside_content( + current_message + ): + return HistoryRelation(RELATION_DIVERGED) + + previous_blocks = previous_message.get("content") + current_blocks = current_message.get("content") + if not isinstance(previous_blocks, list) or not isinstance(current_blocks, list): + return HistoryRelation(RELATION_DIVERGED) + + previous_count = len(previous_blocks) + current_count = len(current_blocks) + leading = _stable_leading_block_run(current_blocks, previous_blocks) + + # Pure block append. The previous write remains intact and Anthropic's + # lookback can find it, so the breakpoint must advance to the newest + # block and cover the newly appended tail. + if current_count > previous_count and leading == previous_count: + changed = HistoryRelation( + RELATION_BLOCK_APPEND, + message_index=index, + stable_prefix_blocks=leading, + previous_block_count=previous_count, + current_block_count=current_count, + ) + continue + + # Rewritten-tail growth. This is narrower than a fuzzy prefix match: + # message count may not change, content may not shrink, most of the old + # prefix must survive, and a substantial fixed suffix must identify the + # sub-call. Crucially ``leading < previous_count`` proves this is NOT a + # pure append (the bug in the original #2702 discriminator). + trailing = _stable_trailing_block_run(current_blocks, previous_blocks, leading_run=leading) + if ( + len(current_messages) == len(previous_messages) + and current_count >= previous_count + and _MIN_REWRITE_PREFIX_BLOCKS <= leading < previous_count + and leading * 2 >= previous_count + and leading * 2 >= current_count + and trailing >= _MIN_REWRITE_SUFFIX_BLOCKS + ): + changed = HistoryRelation( + RELATION_BLOCK_REWRITE_TAIL, + message_index=index, + stable_prefix_blocks=leading, + stable_suffix_blocks=trailing, + previous_block_count=previous_count, + current_block_count=current_count, + ) + continue + + return HistoryRelation(RELATION_DIVERGED) + + if changed is not None: + return changed + return HistoryRelation( + RELATION_EXACT + if len(current_messages) == len(previous_messages) + else RELATION_MESSAGE_APPEND + ) + + +def classify_history_relation( + current_messages: list[dict[str, Any]], + previous_messages: list[dict[str, Any]], +) -> HistoryRelation: + """Return the canonical cross-turn relationship for two raw histories. + + The canonical projection may drop a whole directive-only message. Refuse + classification when that would shift raw message indices: block replay + always slices the raw lists and must never consume a canonical index as a + raw one. + """ + if not current_messages or not previous_messages: + return HistoryRelation(RELATION_DIVERGED) + current = _lineage_snapshot(_canonicalize_for_prefix_compare(current_messages)) + previous = _lineage_snapshot(_canonicalize_for_prefix_compare(previous_messages)) + prefix_len = len(previous_messages) + if len(previous) != prefix_len: + return HistoryRelation(RELATION_DIVERGED) + if len(_canonicalize_for_prefix_compare(current_messages[:prefix_len])) != prefix_len: + return HistoryRelation(RELATION_DIVERGED) + return _classify_history_canonical(current, previous) + + +def segment_fingerprint(value: Any) -> str: + """Stable hash for non-message provider cache-key segments. + + Cache-control placement and transport annotations are deliberately ignored; + semantic tool/model/thinking changes remain visible. The hash is affinity + metadata only and is never used to reconstruct or forward request content. + """ + canonical = _lineage_snapshot(_canonicalize_for_prefix_compare(value)) + encoded = json.dumps( + canonical, + sort_keys=True, + ensure_ascii=False, + separators=(",", ":"), + default=str, + ) + return hashlib.sha256(encoded.encode()).hexdigest()[:24] + + def extract_cache_stable_delta( current_messages: list[dict[str, Any]], previous_original_messages: list[dict[str, Any]] | None, @@ -251,13 +430,13 @@ def extract_cache_stable_delta( """ if not previous_original_messages or previous_forwarded_messages is None: return None + relation = classify_history_relation(current_messages, previous_original_messages) + if relation.kind not in (RELATION_EXACT, RELATION_MESSAGE_APPEND): + # A same-message block append needs a block-level splice in + # ``overlay_cached_prefix``; slicing only whole messages would silently + # discard its new blocks. Rewritten tails are not append-only deltas. + return None prefix_len = len(previous_original_messages) - if len(current_messages) < prefix_len: - return None - if _canonicalize_for_prefix_compare( - current_messages[:prefix_len] - ) != _canonicalize_for_prefix_compare(previous_original_messages): - return None return ( copy.deepcopy(previous_forwarded_messages), copy.deepcopy(current_messages[prefix_len:]), @@ -281,12 +460,12 @@ def overlay_cached_prefix( the corresponding leading messages so the forwarded prefix stays byte-for-byte what the provider hashed for its cache key. - Safe only when this turn append-only-extends the previous turn (the standard - growing-conversation shape): the previous ORIGINAL messages must be an exact - prefix of the current ORIGINAL messages, and there is exactly one forwarded - message per original. Otherwise the previous forwarded bytes may not - correspond to the same positions, so we return ``optimized_messages`` - unchanged (accept a possible bust rather than forward wrong content). + Safe only when this turn extends the previous turn in a proven positional + shape: either whole-message append or pure block append inside one message. + There must be exactly one previous forwarded message per original. Otherwise + the previous bytes may not correspond to the same positions, so we return + ``optimized_messages`` unchanged (accept a possible bust rather than forward + wrong content). This makes freezing byte-identical in BOTH proxy modes, so the only remaining difference between them is how large a mutable (still-compressible) tail each @@ -311,6 +490,55 @@ def overlay_cached_prefix( n, ) return optimized_messages + + relation = classify_history_relation(current_original_messages, prev_orig) + if relation.kind == RELATION_BLOCK_APPEND and relation.message_index is not None: + message_index = relation.message_index + if message_index < len(optimized_messages): + previous_message = prev_fwd[message_index] + previous_original_message = prev_orig[message_index] + current_message = optimized_messages[message_index] + previous_content = ( + previous_message.get("content") if isinstance(previous_message, dict) else None + ) + previous_original_content = ( + previous_original_message.get("content") + if isinstance(previous_original_message, dict) + else None + ) + current_content = ( + current_message.get("content") if isinstance(current_message, dict) else None + ) + split = ( + len(previous_original_content) + if isinstance(previous_original_content, list) + else -1 + ) + if ( + isinstance(previous_content, list) + and isinstance(previous_original_content, list) + and isinstance(current_content, list) + and len(previous_content) == split + and len(current_content) >= split + and _canonicalize_for_prefix_compare(current_content[:split]) + == _canonicalize_for_prefix_compare(previous_original_content) + ): + merged = copy.deepcopy(previous_message) + merged["content"] = copy.deepcopy(previous_content) + copy.deepcopy( + current_content[split:] + ) + logger.debug( + "overlay: replayed %d forwarded blocks and appended %d new blocks " + "inside message %d", + split, + len(current_content) - split, + message_index, + ) + return ( + list(prev_fwd[:message_index]) + + [merged] + + list(optimized_messages[message_index + 1 :]) + ) # Append-only guard on CONTENT ONLY, message-by-message. Replay the # previously-forwarded (cached, compressed) bytes for the longest LEADING # run of messages that is byte-for-byte (content-canonical) identical to @@ -359,8 +587,55 @@ def overlay_cached_prefix( return list(prev_fwd[:k]) + list(optimized_messages[k:]) +_STABLE_BOUNDARY_ENV = "HEADROOM_STABLE_BOUNDARY_BREAKPOINT" +_MIN_BLOCKS_FOR_RELOCATION = 20 + + +def _stable_boundary_enabled() -> bool: + return os.environ.get(_STABLE_BOUNDARY_ENV, "").strip().lower() not in ( + "0", + "false", + "no", + "off", + ) + + +def _breakpoint_index( + content: list[Any], + message: dict[str, Any], + message_index: int, + previous_forwarded_messages: list[dict[str, Any]] | None, +) -> int: + """Choose newest for appends, stable-prefix end for rewritten tails.""" + newest = len(content) - 1 + if ( + not previous_forwarded_messages + or not _stable_boundary_enabled() + or len(content) < _MIN_BLOCKS_FOR_RELOCATION + or message_index >= len(previous_forwarded_messages) + ): + return newest + previous = previous_forwarded_messages[message_index] + if not isinstance(previous, dict): + return newest + relation = classify_history_relation([message], [previous]) + if relation.kind != RELATION_BLOCK_REWRITE_TAIL: + return newest + logger.debug( + "cache breakpoint anchored to stable run %d/%d blocks in message %d " + "(previous=%d, stable_suffix=%d)", + relation.stable_prefix_blocks, + relation.current_block_count, + message_index, + relation.previous_block_count, + relation.stable_suffix_blocks, + ) + return relation.stable_prefix_blocks - 1 + + def normalize_message_cache_control( messages: list[dict[str, Any]], + previous_forwarded_messages: list[dict[str, Any]] | None = None, ) -> list[dict[str, Any]]: """Own message-level cache_control placement so breakpoints stay bounded. @@ -371,9 +646,12 @@ def normalize_message_cache_control( so on a long conversation the accumulation eventually 400s. Fix: strip EVERY message-level cache_control and re-place a **single** - ephemeral breakpoint on the last block of the last block-style message. One - breakpoint caches the whole message prefix up to it, and — because the - provider's cache key is message CONTENT, not marker presence (moving the + ephemeral breakpoint. Pure append-only growth keeps it on the newest block, + which both reads the prior write and writes the appended tail. If last turn's + counterpart proves that the tail was rewritten, it is placed at the end of + the byte-stable leading run instead. One breakpoint caches the prefix up to + it, and — because the provider's cache key is message CONTENT, not marker + presence (moving the breakpoint forward is the documented client pattern and it hits) — stripping and re-placing markers never busts. system/tools breakpoints live outside ``messages`` and are left untouched (they still count toward the 4 limit, so @@ -417,7 +695,16 @@ def normalize_message_cache_control( msg = out[last_block_idx] content = list(msg["content"]) marker = dict(last_marker) if last_marker else {"type": "ephemeral"} - content[-1] = {**content[-1], "cache_control": marker} + breakpoint_index = _breakpoint_index( + content, msg, last_block_idx, previous_forwarded_messages + ) + # Anthropic content blocks are dictionaries, but callers can still + # supply mixed list content. The newest block is known to be a dict + # from the scan above; fall back to it rather than attempting ``**`` + # on a scalar stable-boundary element. + if not isinstance(content[breakpoint_index], dict): + breakpoint_index = len(content) - 1 + content[breakpoint_index] = {**content[breakpoint_index], "cache_control": marker} out[last_block_idx] = {**msg, "content": content} changed = True return out if changed else messages @@ -829,6 +1116,10 @@ class SessionTrackerStore: # value, so a synthetic key can never collide with a client-supplied # x-headroom-session-id. self._lineages: dict[str, OrderedDict[str, list[Any]]] = {} + # Exact non-message cache-key affinity per tracker. Anthropic renders + # tools before system/messages, so two sub-calls with identical history + # but different tool profiles must never share frozen-prefix state. + self._lineage_affinities: dict[str, str | None] = {} self._lineage_counter = itertools.count(1) def get_or_create(self, session_id: str, provider: str) -> PrefixCacheTracker: @@ -854,6 +1145,7 @@ class SessionTrackerStore: session_id: str, provider: str, messages: list[dict[str, Any]] | None = None, + cache_affinity: str | None = None, ) -> PrefixCacheTracker: """Resolve the tracker for THIS conversation within a session id (#2085). @@ -866,10 +1158,11 @@ class SessionTrackerStore: Lineage resolution keys trackers by conversation content instead: reuse the tracker whose previous request messages are a prefix of the - incoming history (client histories are append-only, so a - conversation's next request always extends its previous one); start a - fresh lineage when the history diverges or was rewritten (client-side - compaction — the provider cache line is gone then anyway). + incoming history. It also recognizes a conservative block-level shape + where a large leading run and two-block identity suffix survive while + the middle tail is regenerated; all other rewrites start a fresh + lineage. This keeps #2671's stable cache boundary attached without + merging unrelated parallel sub-calls. Byte-identical histories (templated fan-outs before they diverge) intentionally share a tracker: their provider cache line is identical too, so sharing is harmless. @@ -888,6 +1181,9 @@ class SessionTrackerStore: compares like against like across turns. ``None``/empty (legacy callers, stub stores in tests) falls back to plain :meth:`get_or_create`. + cache_affinity: Stable fingerprint of the provider's non-message + cache-key segments (model/tools/tool choice/thinking). Lineages + with different affinity never share a tracker. Returns: The ``PrefixCacheTracker`` for this conversation's lineage. @@ -918,14 +1214,48 @@ class SessionTrackerStore: family = self._lineages.setdefault(session_id, OrderedDict()) - # Longest recorded chain that prefixes the incoming history wins. + # Strict whole-message continuations win first, then pure block appends. + # Rewritten-tail matches are deliberately last and require a unique best + # structural score; ambiguity starts a fresh lineage instead of making + # sibling sub-calls ping-pong one tracker. + by_length = sorted(family.items(), key=lambda item: len(item[1]), reverse=True) best_key: str | None = None - best_len = -1 - for key, chain in family.items(): - if len(chain) > len(snap) or len(chain) <= best_len: - continue - if snap[: len(chain)] == chain: - best_key, best_len = key, len(chain) + for accepted in ( + (RELATION_EXACT, RELATION_MESSAGE_APPEND), + (RELATION_BLOCK_APPEND,), + ): + for key, chain in by_length: + if self._lineage_affinities.get(key) != cache_affinity: + continue + relation = _classify_history_canonical(snap, chain) + if relation.kind in accepted: + best_key = key + break + if best_key is not None: + break + + if best_key is None: + rewrite_candidates: list[tuple[tuple[int, int, int], str]] = [] + for key, chain in by_length: + if self._lineage_affinities.get(key) != cache_affinity: + continue + relation = _classify_history_canonical(snap, chain) + if relation.kind == RELATION_BLOCK_REWRITE_TAIL: + rewrite_candidates.append( + ( + ( + relation.stable_prefix_blocks, + relation.stable_suffix_blocks, + relation.previous_block_count, + ), + key, + ) + ) + rewrite_candidates.sort(reverse=True) + if rewrite_candidates and ( + len(rewrite_candidates) == 1 or rewrite_candidates[0][0] != rewrite_candidates[1][0] + ): + best_key = rewrite_candidates[0][1] if best_key is None: cap = self._default_config.max_lineages_per_session @@ -963,6 +1293,7 @@ class SessionTrackerStore: # the family before the stamp below. tracker = self.get_or_create(best_key, provider) family[best_key] = snap + self._lineage_affinities[best_key] = cache_affinity return tracker def compute_session_id( @@ -1031,6 +1362,7 @@ class SessionTrackerStore: family = self._lineages[base] for key in [k for k in family if k not in self._trackers]: del family[key] + self._lineage_affinities.pop(key, None) if not family: del self._lineages[base] logger.debug("SessionTrackerStore: cleaned up %d expired sessions", len(expired)) diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index 8251b3590..c379df778 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -1091,6 +1091,25 @@ class AnthropicHandlerMixin: session_id = self.session_tracker_store.compute_session_id( request, model, session_messages ) + # Prefix trackers must follow the provider's cache key, not just + # message history. Anthropic renders tools before system/messages; + # parallel sub-calls commonly share model+system+history while + # carrying different tool sets. Sharing one tracker across those + # requests pins cache reads at the early tools segment (#2671). + from headroom.cache.prefix_tracker import segment_fingerprint + + affinity_tools = self._tools_for_forwarding( + body.get("tools"), preserve_order=preserve_tool_order + ) + cache_affinity = segment_fingerprint( + { + "model": model, + "tools": affinity_tools, + "tool_choice": body.get("tool_choice"), + "thinking": body.get("thinking"), + "output_config": body.get("output_config"), + } + ) # Resolve the tracker by conversation lineage within the session id # (#2085): one model + system prompt spans a Claude Code session and # all its parallel subagents, so concurrent conversations share this @@ -1098,8 +1117,17 @@ class AnthropicHandlerMixin: # thrash the frozen-prefix state and the provider prompt cache is # re-written on nearly every call. prefix_tracker = self.session_tracker_store.resolve_tracker( - session_id, "anthropic", messages=session_messages + session_id, + "anthropic", + messages=session_messages, + cache_affinity=cache_affinity, ) + # Snapshot lineage state once. Reusing the same pair for delta + # extraction, byte-stable replay, and breakpoint placement keeps + # all three decisions tied to one previous request (and avoids + # repeatedly deep-copying a multi-megabyte agent transcript). + previous_original_messages = prefix_tracker.get_last_original_messages() + previous_forwarded_messages = prefix_tracker.get_last_forwarded_messages() frozen_message_count = prefix_tracker.get_frozen_message_count() # Idle gap since the previous turn's response, snapshotted at fetch # (before get_or_create bumped the access clock). Forwarded to the @@ -1505,8 +1533,6 @@ class AnthropicHandlerMixin: optimized_tokens = tokenizer.count_messages(optimized_messages) transforms_applied = _cold_transforms else: - previous_original_messages = prefix_tracker.get_last_original_messages() - previous_forwarded_messages = prefix_tracker.get_last_forwarded_messages() delta = self._extract_cache_stable_delta( original_client_messages, previous_original_messages, @@ -1625,8 +1651,8 @@ class AnthropicHandlerMixin: _ov = overlay_cached_prefix( optimized_messages, original_client_messages, - prefix_tracker.get_last_original_messages(), - prefix_tracker.get_last_forwarded_messages(), + previous_original_messages, + previous_forwarded_messages, ) _overlay_replayed = _ov != optimized_messages if _overlay_replayed: @@ -1636,10 +1662,11 @@ class AnthropicHandlerMixin: # Own cache_control placement: the client moves the breakpoint each # turn and the overlay replays past markers, so they accumulate ~1/turn # and Anthropic hard-errors at >4. Strip message-level markers and keep - # a single breakpoint on the last block (caches the whole prefix; - # content-keyed cache so re-placing never busts). Applied last so the + # one breakpoint. Pure appends advance it to the newest block; a + # proven rewritten tail anchors it at the byte-stable boundary so + # that the same prefix is readable next turn. Applied last so the # forwarded AND recorded (next_forwarded) messages stay bounded. - _norm = normalize_message_cache_control(optimized_messages) + _norm = normalize_message_cache_control(optimized_messages, previous_forwarded_messages) if _norm is not optimized_messages: optimized_messages = _norm diff --git a/tests/test_issue_2671_block_growth_cache.py b/tests/test_issue_2671_block_growth_cache.py new file mode 100644 index 000000000..160d4c22a --- /dev/null +++ b/tests/test_issue_2671_block_growth_cache.py @@ -0,0 +1,288 @@ +"""Comprehensive regression for #2671's block-growing Anthropic histories. + +The provider writes cache entries only at explicit breakpoints and searches at +most 20 block boundaries backwards on the next request. Consequently: + +* a pure append must advance the breakpoint to the newest block; +* a rewritten tail must anchor at the last byte-stable leading block; +* both shapes must retain one conversation lineage across turns; +* different tools/thinking profiles must never share that lineage, because + Anthropic renders those segments before messages in its cache key. + +The small cache oracle below models those write/lookback rules. It catches a +green-but-inert implementation: merely moving a marker in a unit-built message +is insufficient unless the real resolve -> normalize -> record sequence carries +the previous turn's state forward. +""" + +from __future__ import annotations + +import json +from dataclasses import dataclass, field +from typing import Any + +from headroom.cache.prefix_tracker import ( + RELATION_BLOCK_APPEND, + RELATION_BLOCK_REWRITE_TAIL, + RELATION_DIVERGED, + PrefixFreezeConfig, + SessionTrackerStore, + _strip_cache_control, + classify_history_relation, + extract_cache_stable_delta, + normalize_message_cache_control, + overlay_cached_prefix, + segment_fingerprint, +) + + +def _text(text: str, *, cache: bool = False) -> dict[str, Any]: + block: dict[str, Any] = {"type": "text", "text": text} + if cache: + block["cache_control"] = {"type": "ephemeral"} + return block + + +def _message(blocks: list[dict[str, Any]]) -> list[dict[str, Any]]: + return [{"role": "user", "content": blocks}] + + +def _pure_append(total: int) -> list[dict[str, Any]]: + return _message([_text(f"block-{index}") for index in range(total)]) + + +def _rewritten_tail( + turn: int, + churn_blocks: int, + *, + stable_blocks: int = 30, + instruction: str = "instruction: summarize", +) -> list[dict[str, Any]]: + blocks = [_text(f"stable-{index}") for index in range(stable_blocks)] + blocks += [_text(f"turn-{turn}-changing-{index}") for index in range(churn_blocks)] + # The captured production shape keeps a two-block identity suffix pinned at + # the end while the blocks immediately before it are rewritten. + blocks += [_text(instruction), _text("fixed end-of-transcript reminder")] + return _message(blocks) + + +def _breakpoint(messages: list[dict[str, Any]]) -> tuple[int, int]: + found = [ + (message_index, block_index) + for message_index, message in enumerate(messages) + if isinstance(message.get("content"), list) + for block_index, block in enumerate(message["content"]) + if isinstance(block, dict) and "cache_control" in block + ] + assert len(found) == 1 + return found[0] + + +@dataclass +class _AnthropicBreakpointCache: + """Deterministic model of Anthropic's explicit-breakpoint cache lookup.""" + + entries: dict[str, int] = field(default_factory=dict) + lookback_blocks: int = 20 + + @staticmethod + def _blocks(messages: list[dict[str, Any]]) -> list[Any]: + blocks: list[Any] = [] + for message in messages: + content = message.get("content") + if isinstance(content, list): + blocks.extend(_strip_cache_control(content)) + return blocks + + @staticmethod + def _key(blocks: list[Any], end: int) -> str: + return json.dumps(blocks[: end + 1], sort_keys=True, separators=(",", ":")) + + def request(self, messages: list[dict[str, Any]]) -> tuple[int, int]: + """Return simulated ``(cache_read_blocks, cache_write_blocks)``.""" + _, breakpoint = _breakpoint(messages) + blocks = self._blocks(messages) + read = 0 + first = max(0, breakpoint - self.lookback_blocks + 1) + for candidate in range(breakpoint, first - 1, -1): + key = self._key(blocks, candidate) + if key in self.entries: + read = self.entries[key] + break + written_prefix = breakpoint + 1 + write = max(0, written_prefix - read) + self.entries[self._key(blocks, breakpoint)] = written_prefix + return read, write + + +def _record(tracker, original, forwarded, *, read=0, write=10_000): # noqa: ANN001 + tracker.update_from_response( + cache_read_tokens=read, + cache_write_tokens=write, + messages=forwarded, + original_messages=original, + ) + + +def test_classifier_separates_pure_append_from_rewritten_tail() -> None: + append = classify_history_relation(_pure_append(35), _pure_append(30)) + rewrite = classify_history_relation(_rewritten_tail(2, 5), _rewritten_tail(1, 3)) + + assert append.kind == RELATION_BLOCK_APPEND + assert append.stable_prefix_blocks == 30 + assert rewrite.kind == RELATION_BLOCK_REWRITE_TAIL + assert rewrite.stable_prefix_blocks == 30 + assert rewrite.stable_suffix_blocks == 2 + + +def test_rewritten_tail_requires_a_real_previous_divergence() -> None: + """The #2702 bug classified a pure append as a rewritten tail.""" + previous = _pure_append(30) + current = _pure_append(31) + relation = classify_history_relation(current, previous) + + assert relation.kind == RELATION_BLOCK_APPEND + assert relation.stable_prefix_blocks == relation.previous_block_count + + +def test_rewritten_tail_requires_a_two_block_identity_suffix() -> None: + """Sibling sub-calls sharing a transcript and generic reminder must split.""" + previous = _rewritten_tail(1, 3, instruction="instruction: summarize") + sibling = _rewritten_tail(2, 5, instruction="instruction: title") + + assert classify_history_relation(sibling, previous).kind == RELATION_DIVERGED + + +def test_lineage_survives_rewritten_tail_growth_and_delivers_previous_state() -> None: + store = SessionTrackerStore(PrefixFreezeConfig(min_cached_tokens=0)) + first_tracker = None + + for turn, churn in enumerate((3, 5, 8, 11), start=1): + original = _rewritten_tail(turn, churn) + tracker = store.resolve_tracker("shared", "anthropic", messages=original) + first_tracker = first_tracker or tracker + assert tracker is first_tracker + previous = tracker.get_last_forwarded_messages() + if turn > 1: + assert previous, "lineage match must deliver the previous forwarded request" + forwarded = normalize_message_cache_control(original, previous) + _record(tracker, original, forwarded) + + assert store.active_sessions == 1 + assert first_tracker._turn_number == 4 + + +def test_sibling_rewritten_tail_streams_do_not_ping_pong() -> None: + store = SessionTrackerStore() + seen = {} + for turn, churn in enumerate((3, 5, 8), start=1): + for instruction in ("instruction: summarize", "instruction: title"): + original = _rewritten_tail(turn, churn, instruction=instruction) + tracker = store.resolve_tracker("shared", "anthropic", messages=original) + seen.setdefault(instruction, tracker) + assert tracker is seen[instruction] + forwarded = normalize_message_cache_control( + original, tracker.get_last_forwarded_messages() + ) + _record(tracker, original, forwarded) + + assert seen["instruction: summarize"] is not seen["instruction: title"] + + +def test_cache_affinity_splits_identical_histories_with_different_tools() -> None: + store = SessionTrackerStore() + history = _pure_append(30) + shell = segment_fingerprint({"model": "claude", "tools": [{"name": "shell"}]}) + search = segment_fingerprint({"model": "claude", "tools": [{"name": "search"}]}) + + shell_tracker = store.resolve_tracker( + "shared", "anthropic", messages=history, cache_affinity=shell + ) + search_tracker = store.resolve_tracker( + "shared", "anthropic", messages=history, cache_affinity=search + ) + + assert search_tracker is not shell_tracker + assert ( + store.resolve_tracker("shared", "anthropic", messages=history, cache_affinity=shell) + is shell_tracker + ) + + +def test_cache_affinity_ignores_only_cache_directive_movement() -> None: + base = { + "model": "claude", + "tools": [{"name": "shell", "cache_control": {"type": "ephemeral"}}], + } + moved = {"model": "claude", "tools": [{"name": "shell"}]} + changed = {"model": "claude", "tools": [{"name": "search"}]} + + assert segment_fingerprint(base) == segment_fingerprint(moved) + assert segment_fingerprint(base) != segment_fingerprint(changed) + + +def test_pure_append_replays_forwarded_blocks_and_advances_breakpoint() -> None: + previous_original = _pure_append(30) + previous_forwarded = _message([_text(f"COMPRESSED-{index}") for index in range(30)]) + current = _pure_append(34) + + overlaid = overlay_cached_prefix(current, current, previous_original, previous_forwarded) + normalized = normalize_message_cache_control(overlaid, previous_forwarded) + + assert [block["text"] for block in normalized[0]["content"][:30]] == [ + f"COMPRESSED-{index}" for index in range(30) + ] + assert [block["text"] for block in normalized[0]["content"][30:]] == [ + f"block-{index}" for index in range(30, 34) + ] + assert _breakpoint(normalized) == (0, 33) + + +def test_whole_message_delta_path_cannot_discard_appended_blocks() -> None: + """Block appends require a splice, never an empty whole-message delta.""" + previous = _pure_append(30) + + assert extract_cache_stable_delta(_pure_append(34), previous, previous) is None + + +def test_cache_oracle_proves_pure_append_chains_without_rewrites() -> None: + oracle = _AnthropicBreakpointCache() + previous = None + outcomes = [] + for total in (30, 34, 38, 43): + current = _pure_append(total) + forwarded = normalize_message_cache_control(current, previous) + outcomes.append(oracle.request(forwarded)) + previous = forwarded + + assert outcomes == [(0, 30), (30, 4), (34, 4), (38, 5)] + + +def test_cache_oracle_proves_rewritten_tail_stops_perpetual_full_writes() -> None: + oracle = _AnthropicBreakpointCache() + previous = None + outcomes = [] + breakpoints = [] + for turn, churn in enumerate((3, 5, 8, 11), start=1): + current = _rewritten_tail(turn, churn) + forwarded = normalize_message_cache_control(current, previous) + breakpoints.append(_breakpoint(forwarded)[1]) + outcomes.append(oracle.request(forwarded)) + previous = forwarded + + # Cold turn writes its varying tail. Turn two establishes the new stable + # boundary; subsequent turns read it and perform no repeated full write. + assert breakpoints == [34, 29, 29, 29] + assert outcomes[0] == (0, 35) + assert outcomes[1] == (0, 30) + assert outcomes[2:] == [(30, 0), (30, 0)] + + +def test_relocation_kill_switch_restores_newest_block(monkeypatch) -> None: # noqa: ANN001 + previous = normalize_message_cache_control(_rewritten_tail(1, 3)) + monkeypatch.setenv("HEADROOM_STABLE_BOUNDARY_BREAKPOINT", "0") + current = _rewritten_tail(2, 5) + + forwarded = normalize_message_cache_control(current, previous) + + assert _breakpoint(forwarded) == (0, len(current[0]["content"]) - 1) diff --git a/tests/test_proxy_anthropic_cache_stability.py b/tests/test_proxy_anthropic_cache_stability.py index 326b9a193..756a6ba4a 100644 --- a/tests/test_proxy_anthropic_cache_stability.py +++ b/tests/test_proxy_anthropic_cache_stability.py @@ -2,6 +2,7 @@ from __future__ import annotations +import copy from types import SimpleNamespace from unittest.mock import AsyncMock @@ -1243,6 +1244,156 @@ def test_cache_mode_reuses_prior_forwarded_prefix_and_compresses_only_new_suffix ] +def test_anthropic_handler_splits_prefix_trackers_when_tool_profiles_differ() -> None: + """The handler must pass its non-message cache affinity into resolution. + + Anthropic's cache key begins with tools. Identical messages on two parallel + sub-calls therefore cannot safely share frozen-prefix state when their tool + arrays differ (#2671 Pattern B). + """ + resolved = [] + with _make_proxy_client() as client: + proxy = client.app.state.proxy + proxy.config.optimize = True + proxy.config.mode = "cache" + proxy.config.image_optimize = False + + real_resolve = proxy.session_tracker_store.resolve_tracker + + def _spy_resolve(session_id, provider, messages=None, cache_affinity=None): # noqa: ANN001 + tracker = real_resolve( + session_id, + provider, + messages=messages, + cache_affinity=cache_affinity, + ) + resolved.append((cache_affinity, tracker)) + return tracker + + proxy.session_tracker_store.resolve_tracker = _spy_resolve + + async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001 + return httpx.Response( + 200, + json={ + "id": "msg_affinity", + "type": "message", + "role": "assistant", + "content": [{"type": "text", "text": "ok"}], + "usage": { + "input_tokens": 10, + "output_tokens": 1, + "cache_read_input_tokens": 0, + "cache_creation_input_tokens": 0, + }, + }, + ) + + proxy._retry_request = _fake_retry + headers = {"x-api-key": "test-key", "anthropic-version": "2023-06-01"} + messages = [{"role": "user", "content": "same parent transcript"}] + + for tool_name in ("shell", "search"): + response = client.post( + "/v1/messages", + headers=headers, + json={ + "model": "claude-sonnet-4-6", + "max_tokens": 32, + "messages": messages, + "tools": [ + { + "name": tool_name, + "description": tool_name, + "input_schema": {"type": "object", "properties": {}}, + } + ], + }, + ) + assert response.status_code == 200 + + assert len(resolved) == 2 + assert resolved[0][0] != resolved[1][0] + assert resolved[0][1] is not resolved[1][1] + + +def test_anthropic_handler_anchors_a_proven_rewritten_tail_to_stable_blocks() -> None: + """The real handler must feed last turn's bytes into normalization.""" + bodies = [] + + def _history(turn: int, churn: int) -> list[dict]: + content = [{"type": "text", "text": f"stable-{index}"} for index in range(30)] + content.extend( + {"type": "text", "text": f"turn-{turn}-changing-{index}"} for index in range(churn) + ) + content.extend( + [ + {"type": "text", "text": "instruction: summarize"}, + {"type": "text", "text": "fixed end-of-transcript reminder"}, + ] + ) + return [{"role": "user", "content": content}] + + with _make_proxy_client() as client: + proxy = client.app.state.proxy + # Breakpoint ownership and lineage tracking apply even in passthrough + # mode. Keeping optimization off isolates that real handler wiring from + # the compression pipeline. + proxy.config.optimize = False + proxy.config.image_optimize = False + # This regression models a client whose next request replaces the same + # aggregate message. Do not synthesize an assistant history entry in + # the tracker, because that is a separate response-reconstruction path. + proxy._assistant_message_from_response_json = lambda _body: None + + async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001 + bodies.append(copy.deepcopy(body)) + return httpx.Response( + 200, + json={ + "id": "msg_rewrite", + "type": "message", + "role": "assistant", + "content": [], + "usage": { + "input_tokens": 10_000, + "output_tokens": 1, + "cache_read_input_tokens": 0, + "cache_creation_input_tokens": 10_000, + }, + }, + ) + + proxy._retry_request = _fake_retry + headers = {"x-api-key": "test-key", "anthropic-version": "2023-06-01"} + for turn, churn in enumerate((3, 5, 8), start=1): + response = client.post( + "/v1/messages", + headers=headers, + json={ + "model": "claude-sonnet-4-6", + "max_tokens": 32, + "messages": _history(turn, churn), + }, + ) + assert response.status_code == 200 + + breakpoint_indices = [] + for body in bodies: + marked = [ + index + for index, block in enumerate(body["messages"][0]["content"]) + if "cache_control" in block + ] + assert len(marked) == 1 + breakpoint_indices.append(marked[0]) + + # Cold request caches through its newest block. Once rewrite is proven, + # all subsequent calls pin the same 30-block boundary instead of creating + # an ever-growing full write on each turn. + assert breakpoint_indices == [34, 29, 29] + + def test_cache_mode_skips_same_message_append_rewrite_to_preserve_stability() -> None: captured = {"calls": []} with _make_proxy_client() as client: From c6f99482e1bea024db6014a70c8e6da419543957 Mon Sep 17 00:00:00 2001 From: gglucass Date: Tue, 11 Aug 2026 18:10:27 +0200 Subject: [PATCH 030/138] fix(proxy/anthropic): run tool-search history repair after turn hooks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `strip_unsupported_tool_search_blocks` (#2807) validates every replayed `tool_reference` in the transcript against the request's `tools` array. It ran *before* the turn-hooks block in `handlers/anthropic.py`, and a registered turn hook may rewrite that array — the hook surface is documented as "a registered hook may inspect or rewrite the outbound tools/messages before we send upstream". So a hook that drops a tool named by a replayed reference leaves the repair having validated against a stale view, and upstream rejects the request: ```text 400 Tool reference 'X' not found in available tools ``` The repair's correctness argument is that it validates against exactly the `tools` array upstream will see. That was true at the old call site and stopped being true one block later. ### Fix Move the repair to after the turn-hooks block, so it is the last stage that can invalidate a reference: - It still runs **after** the deferral injection, so the tool just injected counts as present — the main loop strips nothing and the frozen prefix stays byte-identical. - Nothing past the new call site mutates `body["tools"]` on the outbound path. (The two later `continuation_body["tools"]` assignments build a *derived* body from the already-repaired `body`, so they inherit the repair.) - It still runs before the consistency token re-count, so `tok_after` continues to reflect the repaired messages. - It remains unconditional (not gated on `HEADROOM_TOOL_SEARCH`, not gated on `_bypass`), so transcripts poisoned before the flag was turned off still recover. `strip_unsupported_tool_search_blocks` is copy-on-write and returns the original `messages` object by identity when nothing is removed, so relocating the call does not change the no-op path. ### Severity Latent. No turn hook ships in-tree, so this cannot fire on a default install — it is reachable only through a third-party registered hook that shrinks the tools array. Filing the fix now so the ordering constraint is enforced by a test rather than rediscovered. Closes #2888 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/proxy/handlers/anthropic.py`: the tool-search history repair block moves from just after the deferral injection to just after the turn-hooks block. The comment now states the ordering constraint in both directions (after injection, after hooks) so the next person to add a stage knows where the boundary is. No logic change. - `tests/test_proxy/test_tool_search_repair_after_turn_hooks.py` (new): two handler-level regressions. Ordering is the whole property under test, so a unit test of the helper cannot see it — these drive the real handler through `TestClient` and assert on the forwarded body. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed — no in-tree turn hook exists to exercise this against a live API key; the handler-level test below is the substitute, see Not tested. ### Test Output ```text $ uv run --extra dev pytest tests/test_proxy/ -q ======================= 241 passed, 1 warning in 35.82s ======================== $ uvx ruff check headroom tests All checks passed! $ uv run --extra dev mypy headroom Success: no issues found in 515 source files ``` ## Real Behavior Proof - Environment: macOS 15 (darwin 24.6.0), Python 3.10.18, pytest 9.0.3, in a worktree off `upstream/main` at 2f2950a6. No live Anthropic key: the proxy handler is driven end to end through `fastapi.testclient.TestClient` with `_retry_request` stubbed, so the assertion is on the exact body that would have been sent upstream. - Exact command / steps: (1) on the branch as submitted, `uv run --extra dev pytest tests/test_proxy/test_tool_search_repair_after_turn_hooks.py -q` -> 2 passed; (2) revert ONLY the handler ordering change while keeping the new tests, `git checkout HEAD~1 -- headroom/proxy/handlers/anthropic.py`, and re-run the same command. The request under test carries a `tool_search_tool_result` referencing `Grep`, a `tools` array containing `Grep`, and a registered turn hook that removes `Grep`. - Observed result: with the fix reverted the primary test fails on exactly the shape upstream 400s on, because the forwarded body still carries a `tool_reference` naming a tool the turn hook had already removed from `tools`. Restoring the handler change turns it green. The second test passes in both states by design: it pins the converse (a hook that leaves `tools` alone must not cause over-stripping), so the fix cannot regress into "strip always". Verbatim output of the reverted run: ```text $ git checkout HEAD~1 -- headroom/proxy/handlers/anthropic.py # revert ONLY the ordering fix $ uv run --extra dev pytest tests/test_proxy/test_tool_search_repair_after_turn_hooks.py -q collected 2 items tests/test_proxy/test_tool_search_repair_after_turn_hooks.py F. [100%] =================================== FAILURES =================================== ____________ test_repair_sees_the_tools_array_the_hook_left_behind _____________ tests/test_proxy/test_tool_search_repair_after_turn_hooks.py:166: in test_repair_sees_the_tools_array_the_hook_left_behind assert _referenced_tool_names(forwarded) == [] E AssertionError: assert ['Grep'] == [] E E Left contains one more item: 'Grep' FAILED tests/test_proxy/test_tool_search_repair_after_turn_hooks.py::test_repair_sees_the_tools_array_the_hook_left_behind ``` - Not tested: no live-API reproduction of the 400 itself, since triggering it needs a third-party turn hook that removes a tool and none ships in-tree (the assertion above is on the forwarded body, which is the input that produces the 400); no streaming-path variant, since the repair mutates `body` upstream of the stream/buffered split so both inherit it but only the buffered path is asserted; no performance measurement, since the change moves an existing call ~60 lines later in the same function and adds no work. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation — N/A, no user-facing or configuration surface changes - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes - **CI:** `test (4)` failed on `tests/test_tokenizer_count_offload.py::test_count_tokens_offloaded_keeps_loop_responsive` with `assert 0 >= 5`. That is an event-loop-responsiveness timing assertion under a shared runner, and it is unrelated to this diff — nothing here touches the tokenizer or the offload path. It passes locally (`10 passed in 1.43s`). I do not have rerun permission on this fork PR (`gh run rerun` → `cannot be rerun`), so a maintainer rerun is needed to clear it. - **Codecov:** reports "All modified and coverable lines are covered by tests". The accompanying warning is the repo-level "install the Codecov app" notice, not a finding against this PR. - Surfaced while confirming that #2807 and #2848 supersede #2507, which is now closed as such. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- headroom/proxy/handlers/anthropic.py | 63 ++++--- ...est_tool_search_repair_after_turn_hooks.py | 176 ++++++++++++++++++ 2 files changed, 210 insertions(+), 29 deletions(-) create mode 100644 tests/test_proxy/test_tool_search_repair_after_turn_hooks.py diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index c379df778..8e12401b7 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -2504,35 +2504,6 @@ class AnthropicHandlerMixin: f"{_ts_saved_tokens}tok" ) - # Tool-search history repair (#2805). Once deferral is on, the client - # stores Anthropic's server_tool_use / tool_search_tool_result blocks in - # its transcript forever, and upstream validates every tool_reference in - # that history against THIS request's tools array. Claude Code replays - # the same transcript on side-requests carrying a different, smaller - # tools array (the prompt-type Stop hook evaluator, /compact), which the - # proxy cannot predict — so upstream 400s with "Tool reference 'X' not - # found in available tools". Drop the blocks such a request cannot - # support. Runs AFTER the injection above so the tool we just added - # counts as present: on the main loop nothing is stripped and the prefix - # is untouched. Unconditional (not gated on the flag) so transcripts - # poisoned before the flag was turned off still recover. - from headroom.proxy.helpers import strip_unsupported_tool_search_blocks - - _ts_repaired, _ts_stripped = strip_unsupported_tool_search_blocks( - body.get("messages"), body.get("tools") - ) - if _ts_stripped: - body["messages"] = _ts_repaired - optimized_messages = _ts_repaired - body_mutation_tracker.mark_mutated("tool_search_history_repair") - transforms_applied.append(f"router:tool_search_repair:{_ts_stripped}blocks") - logger.info( - "[%s] Tool search: dropped %d unsupportable history block(s) " - "(tools array cannot resolve their tool_reference entries)", - request_id, - _ts_stripped, - ) - # Turn hooks (opt-in extensions): a registered hook may inspect or # rewrite the outbound tools/messages before we send upstream — the # extensible counterpart to the built-in deferral above. A single @@ -2579,6 +2550,40 @@ class AnthropicHandlerMixin: int(tags.get("turn_hook_tools_saved_tokens", 0) or 0) + _th_saved ) + # Tool-search history repair (#2805). Once deferral is on, the client + # stores Anthropic's server_tool_use / tool_search_tool_result blocks in + # its transcript forever, and upstream validates every tool_reference in + # that history against THIS request's tools array. Claude Code replays + # the same transcript on side-requests carrying a different, smaller + # tools array (the prompt-type Stop hook evaluator, /compact), which the + # proxy cannot predict — so upstream 400s with "Tool reference 'X' not + # found in available tools". Drop the blocks such a request cannot + # support. Unconditional (not gated on the flag) so transcripts poisoned + # before the flag was turned off still recover. + # + # ORDERING (#2888): this must be the LAST stage that can invalidate a + # tool_reference, so it runs after BOTH the deferral injection above (the + # tool we just added counts as present, so the main loop strips nothing + # and the prefix is untouched) AND the turn hooks (a hook may rewrite the + # tools array, and repairing before it validated against a stale view). + # Nothing past this point mutates `body["tools"]` on the outbound path. + from headroom.proxy.helpers import strip_unsupported_tool_search_blocks + + _ts_repaired, _ts_stripped = strip_unsupported_tool_search_blocks( + body.get("messages"), body.get("tools") + ) + if _ts_stripped: + body["messages"] = _ts_repaired + optimized_messages = _ts_repaired + body_mutation_tracker.mark_mutated("tool_search_history_repair") + transforms_applied.append(f"router:tool_search_repair:{_ts_stripped}blocks") + logger.info( + "[%s] Tool search: dropped %d unsupportable history block(s) " + "(tools array cannot resolve their tool_reference entries)", + request_id, + _ts_stripped, + ) + # Consistency: report tok_before/tok_after with ONE tokenizer. The pipeline # and the handler use different token estimators, and cache-mode branches # can leave original_tokens (handler, line ~1049) and optimized_tokens diff --git a/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py b/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py new file mode 100644 index 000000000..30d495760 --- /dev/null +++ b/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py @@ -0,0 +1,176 @@ +"""Tool-search history repair must run AFTER the turn hooks (#2888). + +``strip_unsupported_tool_search_blocks`` (#2807) validates every replayed +``tool_reference`` against the request's ``tools`` array. A registered turn hook +may rewrite that array, so repairing before the hook validates against a stale +view: the reference looks resolvable, the hook then drops the tool it named, and +upstream 400s with ``Tool reference 'X' not found in available tools``. + +These drive the real handler and assert on the forwarded body, because ordering +is the whole property under test -- a unit test of the helper cannot see it. +""" + +from __future__ import annotations + +from types import SimpleNamespace + +import httpx +import pytest + +pytest.importorskip("fastapi") + +from fastapi.testclient import TestClient + +from headroom.proxy.server import ProxyConfig, create_app +from headroom.proxy.turn_hooks import clear_turn_hooks, register_turn_hook + +_SEARCH_TOOL = {"type": "tool_search_tool_20250917", "name": "tool_search"} +_GREP = {"name": "Grep", "description": "search files", "input_schema": {"type": "object"}} +_READ = {"name": "Read", "description": "read a file", "input_schema": {"type": "object"}} + +# A transcript that already carries a resolved tool-search round trip for `Grep`. +_POISONED_MESSAGES = [ + {"role": "user", "content": "find the thing"}, + { + "role": "assistant", + "content": [ + { + "type": "server_tool_use", + "id": "srvtoolu_1", + "name": "tool_search_tool_20250917", + "input": {"query": "grep"}, + }, + { + "type": "tool_search_tool_result", + "tool_use_id": "srvtoolu_1", + "content": { + "type": "tool_search_tool_result_content", + "tool_references": [{"type": "tool_reference", "tool_name": "Grep"}], + }, + }, + ], + }, + {"role": "user", "content": "now use it"}, +] + + +@pytest.fixture(autouse=True) +def _clean_registry(): + clear_turn_hooks() + yield + clear_turn_hooks() + + +class _DropToolHook: + """Turn hook that removes one tool from the outbound array.""" + + def __init__(self, name: str): + self._name = name + + def on_request(self, ctx) -> None: # noqa: ANN001 + if ctx.tools: + ctx.tools = [t for t in ctx.tools if t.get("name") != self._name] + + +class _InertHook: + def on_request(self, ctx) -> None: # noqa: ANN001, ARG002 + return None + + +def _run(hook) -> dict: # noqa: ANN001 + """POST a poisoned transcript through the handler, return the forwarded body.""" + captured: dict[str, object] = {} + register_turn_hook(hook) + + config = 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, + image_optimize=False, + ) + with TestClient(create_app(config)) as client: + proxy = client.app.state.proxy + proxy.pipeline_extensions.emit = lambda *args, **kwargs: SimpleNamespace( + messages=kwargs.get("messages"), + tools=kwargs.get("tools"), + headers=kwargs.get("headers"), + metadata=kwargs.get("metadata"), + ) + + async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001 + captured["body"] = body + return httpx.Response( + 200, + json={ + "id": "msg_repair_order", + "type": "message", + "role": "assistant", + "content": [{"type": "text", "text": "ok"}], + "usage": {"input_tokens": 20, "output_tokens": 3}, + }, + ) + + proxy._retry_request = _fake_retry + + response = client.post( + "/v1/messages", + headers={"x-api-key": "test-key", "anthropic-version": "2023-06-01"}, + json={ + "model": "claude-sonnet-4-6", + "max_tokens": 64, + "messages": _POISONED_MESSAGES, + "tools": [_SEARCH_TOOL, _GREP, _READ], + }, + ) + assert response.status_code == 200 + + return captured["body"] # type: ignore[return-value] + + +def _referenced_tool_names(body: dict) -> list[str]: + names = [] + for message in body.get("messages", []): + content = message.get("content") + if not isinstance(content, list): + continue + for block in content: + if not isinstance(block, dict) or block.get("type") != "tool_search_tool_result": + continue + inner = block.get("content") + entries = inner.get("tool_references") if isinstance(inner, dict) else inner + for entry in entries or []: + names.append(str(entry.get("tool_name") or entry.get("name"))) + return names + + +def _block_types(body: dict) -> list[str]: + types = [] + for message in body.get("messages", []): + content = message.get("content") + if isinstance(content, list): + types.extend(str(b.get("type")) for b in content if isinstance(b, dict)) + return types + + +def test_repair_sees_the_tools_array_the_hook_left_behind() -> None: + """A hook that drops `Grep` must leave no dangling reference to it.""" + forwarded = _run(_DropToolHook("Grep")) + + assert "Grep" not in [t.get("name") for t in forwarded["tools"]] + # The whole pair goes: an orphaned server_tool_use 400s on its own. + assert _referenced_tool_names(forwarded) == [] + assert "tool_search_tool_result" not in _block_types(forwarded) + assert "server_tool_use" not in _block_types(forwarded) + + +def test_repair_leaves_resolvable_history_alone_when_the_hook_keeps_the_tool() -> None: + """The converse: no over-stripping when the hook does not touch `tools`.""" + forwarded = _run(_InertHook()) + + assert _referenced_tool_names(forwarded) == ["Grep"] + assert "tool_search_tool_result" in _block_types(forwarded) From d7b25ae3bb3364cde4931509ecb65e32085e5b09 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Tue, 11 Aug 2026 21:40:32 +0530 Subject: [PATCH 031/138] fix(wrap/serena): install Serena from the serena-agent PyPI wheel, not the git source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `headroom/mcp_registry/install.py` (`build_serena_spec`) and the wrap-time Serena pre-index in `headroom/cli/wrap.py` both ran: ``` uvx --from git+https://github.com/oraios/serena serena ... ``` The git source forces a from-source build. On proot-based filesystems (Termux + proot-distro on Android, some restricted Linux) `uv` cannot hardlink build dependencies into a fresh build venv, so the build fails immediately and Serena's MCP server fails to start on every `headroom wrap codex` launch: ``` × Failed to download and build `serena-agent @ git+https://github.com/oraios/serena@` ╰─▶ failed to hardlink file ... Operation not permitted (os error 1) ``` Setting `UV_LINK_MODE=copy` fixes it in an interactive shell, but Codex strips most env vars from the MCP subprocesses it spawns, so that workaround does not reliably reach Serena's launch. Serena publishes the official `serena-agent` package to PyPI with prebuilt wheels, and it exposes the same `serena` console script (`serena = "serena.cli:top_level"` in the project's `pyproject.toml`), so `uvx --from serena-agent serena ...` runs the identical command without a build step. On platforms where the git build already worked there is no functional difference. Fixes #2871 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/mcp_registry/install.py` (`build_serena_spec`): `--from git+https://github.com/oraios/serena` -> `--from serena-agent`. - `headroom/cli/wrap.py` (Serena `project index` pre-warm): same swap. - `tests/test_mcp_registry/test_install.py`: updated the spec assertion and added `test_build_serena_spec_uses_pypi_not_git_source` (asserts `serena-agent` is used and no `git+` source remains). - `tests/test_cli/test_wrap_serena_boost.py`: the pre-index test now asserts `serena-agent` is in the command and the git source is not. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Fail-before (source swap stashed, updated tests kept): tests/test_mcp_registry/test_install.py::test_build_serena_spec_uses_agent_context FAILED tests/test_mcp_registry/test_install.py::test_build_serena_spec_uses_pypi_not_git_source FAILED tests/test_cli/test_wrap_serena_boost.py::test_preindex_runs_serena_in_cwd FAILED # Pass-after: tests/test_mcp_registry/ tests/test_cli/test_wrap_serena_boost.py tests/test_cli/test_serena_migrate.py tests/test_cli/test_serena_disable.py 135 passed # uvx ruff@0.15.17 check -> All checks passed! # uvx mypy@1.20.2 headroom/mcp_registry/install.py -> Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1, ruff 0.15.17 and mypy 1.20.2 via uvx. - Exact command / steps: confirmed `serena-agent` exists on PyPI (v1.6.1, homepage github.com/oraios/serena) and that its `pyproject.toml` declares `[project.scripts] serena = "serena.cli:top_level"`, so the `serena start-mcp-server ...` invocation is unchanged. Swapped both `--from` sources, then fail-before with `git stash push headroom/mcp_registry/install.py headroom/cli/wrap.py` (the two production-asserting tests fail on the old git source) and pass-after with `git stash pop` (135 serena-suite tests pass). Verified no `git+https://github.com/oraios/serena` references remain in `headroom/`. - Observed result: `build_serena_spec` and the pre-index command now install Serena from the `serena-agent` PyPI wheel, so a proot environment gets the prebuilt wheel instead of a from-source build that cannot hardlink. The migration/ledger tests, which use the old git spec as a deliberately-stale fixture, are unaffected. - Not tested: a live `headroom wrap codex` on a real proot/Termux device (not available here). The change is a package-source swap verified against Serena's own published package metadata and the existing spec/command tests. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`: it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes The git source was unpinned (tracked the repo default branch), so switching to `serena-agent` from PyPI does not lose a version pin; if anything it is more reproducible. The issue reporter also noted that `headroom wrap codex` force-rewrites the Serena block in `~/.codex/config.toml` from this template on every launch, which is why the fix has to live in the package source rather than a user config edit -- this PR puts it there. --- headroom/cli/wrap.py | 4 +++- headroom/mcp_registry/install.py | 5 ++++- tests/test_cli/test_wrap_serena_boost.py | 4 +++- tests/test_mcp_registry/test_install.py | 12 +++++++++++- 4 files changed, 21 insertions(+), 4 deletions(-) diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py index 8911c883f..094454206 100644 --- a/headroom/cli/wrap.py +++ b/headroom/cli/wrap.py @@ -1710,8 +1710,10 @@ def _index_serena_project(*, verbose: bool = False) -> None: result = run( [ "uvx", + # PyPI (prebuilt wheels), not the git source that fails to build + # under proot-based filesystems (#2871). "--from", - "git+https://github.com/oraios/serena", + "serena-agent", "serena", "project", "index", diff --git a/headroom/mcp_registry/install.py b/headroom/mcp_registry/install.py index d8a9f7f09..e550f6ded 100644 --- a/headroom/mcp_registry/install.py +++ b/headroom/mcp_registry/install.py @@ -59,8 +59,11 @@ def build_serena_spec(context: str) -> ServerSpec: name="serena", command="uvx", args=( + # The PyPI package (serena-agent) ships prebuilt wheels; the git + # source forced a from-source build that fails under proot-based + # filesystems where uv cannot hardlink into a build venv (#2871). "--from", - "git+https://github.com/oraios/serena", + "serena-agent", "serena", "start-mcp-server", "--project-from-cwd", diff --git a/tests/test_cli/test_wrap_serena_boost.py b/tests/test_cli/test_wrap_serena_boost.py index 8a29086b3..bb08cd628 100644 --- a/tests/test_cli/test_wrap_serena_boost.py +++ b/tests/test_cli/test_wrap_serena_boost.py @@ -122,7 +122,9 @@ def test_preindex_runs_serena_in_cwd(tmp_path: Path, monkeypatch: pytest.MonkeyP cmd = args[0] assert cmd[0] == "uvx" assert cmd[-3:] == ["serena", "project", "index"] - assert "git+https://github.com/oraios/serena" in cmd + # PyPI package with prebuilt wheels, not the git source (#2871). + assert "serena-agent" in cmd + assert "git+https://github.com/oraios/serena" not in cmd assert kwargs["cwd"] == str(tmp_path) # invoked in the project cwd assert "timeout" in kwargs # timeout-guarded diff --git a/tests/test_mcp_registry/test_install.py b/tests/test_mcp_registry/test_install.py index 674199992..3e22e5b1e 100644 --- a/tests/test_mcp_registry/test_install.py +++ b/tests/test_mcp_registry/test_install.py @@ -89,8 +89,9 @@ def test_build_serena_spec_uses_agent_context() -> None: assert spec.name == "serena" assert spec.command == "uvx" assert spec.args == ( + # PyPI package with prebuilt wheels, not the git source (#2871). "--from", - "git+https://github.com/oraios/serena", + "serena-agent", "serena", "start-mcp-server", "--project-from-cwd", @@ -102,6 +103,15 @@ def test_build_serena_spec_uses_agent_context() -> None: assert spec.env == {} +def test_build_serena_spec_uses_pypi_not_git_source() -> None: + """Serena is installed from the PyPI package (prebuilt wheels), not the git + source, which forces a from-source build that fails under proot-based + filesystems where uv cannot hardlink into a build venv (#2871).""" + spec = build_serena_spec("codex") + assert "serena-agent" in spec.args + assert not any("git+" in arg for arg in spec.args) + + def test_build_serena_spec_disables_dashboard_popup_by_default() -> None: # Headroom installs Serena by default; the dashboard browser tab must not # auto-open. The flag overrides the user's serena_config.yml at startup, From 702dbc5902ff184a7c20178958a811beb9c78fa3 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Tue, 11 Aug 2026 21:40:38 +0530 Subject: [PATCH 032/138] fix(opencode): ship the transport hook-shim so wheel installs route Node child traffic ## Description The OpenCode transport plugin injects `NODE_OPTIONS=--import=<...>/hook-shim/handler.js` into every spawned Node child so its `fetch`/`http` traffic routes through the proxy (`transport.ts` wraps those globals only in the plugin's own process; a spawned `npx` MCP server or `tokensave serve` is a fresh process). That shim was never shipped in the wheel: - Only `headroom/providers/opencode/_dist/entry.opencode.js` is committed and packaged. - The shim source at `plugins/opencode/hook-shim/handler.js` imports the non-bundled `../dist/index.js`, which a pip install (no `node_modules`) cannot resolve. Before #2806, the missing file crashed every Node MCP under `headroom wrap opencode` with `ERR_MODULE_NOT_FOUND` at the ESM loader, before the stdio handshake. #2806 added an `existsSync` guard so the loader is not injected when the shim is absent, which stopped the crash but left child-process routing silently disabled for all wheel installs (#2850). This ships the shim. It builds a self-contained variant in the standalone tsup config (`src/hook-shim.ts`, with the transport bundled inline like the entry, since site-packages has no `node_modules`), and commits it to `headroom/providers/opencode/hook-shim/handler.js` -- the sibling of `_dist/` that `transport.ts`'s `shimImportSpecifier()` resolves via `../hook-shim/handler.js`. maturin packages every file under `headroom/`, so the wheel now carries it, and `existsSync` finds it, so the loader routes spawned Node children again. Fixes #2850 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `plugins/opencode/src/hook-shim.ts` (new): self-contained Node `--import` loader that installs the transport from the inlined `./transport.js`. - `plugins/opencode/tsup.standalone.config.ts`: add `hook-shim/handler` as a second standalone entry. - `headroom/providers/opencode/hook-shim/handler.js` (new): the committed self-contained shim (output of `npm run build:standalone`), shipped by maturin. - `.github/workflows/opencode-plugin.yml`: byte-compare the committed shim against a fresh build (mirrors the existing `entry.opencode.js` guard), and add the shim path to the workflow triggers. - `tests/test_providers_opencode_plugin_path.py`: added `test_hook_shim_is_committed_next_to_the_entry_bundle` asserting the shim ships as a sibling of `_dist/` and is the self-contained build. ## Testing - [x] Unit tests pass (`pytest` + `vitest`) - [x] Type checking passes (`tsc --noEmit`) - [x] New tests added for new functionality - [x] Committed shim rebuilt and byte-matches the standalone build - [ ] Manual testing performed ### Test Output ```text # Fail-before (shim removed from the package): tests/test_providers_opencode_plugin_path.py::test_hook_shim_is_committed_next_to_the_entry_bundle FAILED # Pass-after: tests/test_providers_opencode_plugin_path.py tests/test_providers_opencode_install.py tests/test_providers_opencode_config.py 49 passed, 1 pre-existing failure # the 1 failure (test_build_launch_env_with_project) fails identically on pristine main: # a Windows path-escaping quirk in OPENCODE_CONFIG_CONTENT, unrelated to this diff. # TypeScript: npm run typecheck (clean), npm test -> 14 passed # Standalone build: entry.opencode.js byte-unchanged vs the committed blob; # dist-standalone/hook-shim/handler.js cmp-matches the committed shim. # Shim runtime sanity (node): # with HEADROOM_OPENCODE_TRANSPORT_PROXY_URL set -> loads, exit 0, wraps globalThis.fetch # without it -> throws "loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL", exit 1 ``` ## Real Behavior Proof - Environment: Windows 11, Node v24.11.0, npm 11.5.2, tsup 8.5.1 / esbuild 0.28.1 (pinned via `npm ci`), Python 3.12.11, pytest 9.1.1, ruff 0.15.17. - Exact command / steps: confirmed `transport.ts` resolves `../hook-shim/handler.js` next to the loaded entry (so the wheel needs it at `providers/opencode/hook-shim/handler.js`), that the current wheel ships only `_dist/entry.opencode.js`, and that maturin packages every file under `headroom/`. Added the standalone shim entry, ran `npm run typecheck` and `npm test` (clean), `npm run build:standalone`, verified `entry.opencode.js` is byte-identical to the committed git blob (the standalone build is reproducible; my working copy was only autocrlf-inflated), copied the built shim to the wheel path, and exercised it in Node: it installs the transport (wraps `fetch`) with the proxy env set and throws without it. Fail-before by removing the shim (the new Python test fails); pass-after restored. - Observed result: `headroom/providers/opencode/hook-shim/handler.js` now ships in the package as a self-contained module, so a pip-installed `headroom wrap opencode` routes spawned Node children (npx MCPs, `tokensave serve`) through the proxy instead of leaving them unrouted, and never crashes them. - Not tested: a full pip-install-and-spawn on Linux with a live OpenCode session (no OpenCode client here). The shim is verified to load and wrap `fetch` under Node, the bundle is reproducible and byte-checked by CI, and the packaging path is maturin's standard file inclusion under `headroom/`. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`: it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes The checkout keeps using `plugins/opencode/hook-shim/handler.js` (which imports `../dist/index.js` from the regular build), so dev behavior is unchanged; only the wheel gains the self-contained sibling. `entry.opencode.js` is byte-unchanged, so its existing CI guard still passes. The committed shim is stored with LF endings so the Linux CI byte-compare matches. --- .github/workflows/opencode-plugin.yml | 5 + .../providers/opencode/hook-shim/handler.js | 390 ++++++++++++++++++ plugins/opencode/src/hook-shim.ts | 26 ++ plugins/opencode/tsup.standalone.config.ts | 7 +- tests/test_providers_opencode_plugin_path.py | 17 + 5 files changed, 444 insertions(+), 1 deletion(-) create mode 100644 headroom/providers/opencode/hook-shim/handler.js create mode 100644 plugins/opencode/src/hook-shim.ts diff --git a/.github/workflows/opencode-plugin.yml b/.github/workflows/opencode-plugin.yml index 4fd8103ab..4e81e6597 100644 --- a/.github/workflows/opencode-plugin.yml +++ b/.github/workflows/opencode-plugin.yml @@ -11,12 +11,14 @@ on: paths: - "plugins/opencode/**" - "headroom/providers/opencode/_dist/**" + - "headroom/providers/opencode/hook-shim/**" - ".github/workflows/opencode-plugin.yml" push: branches: [main] paths: - "plugins/opencode/**" - "headroom/providers/opencode/_dist/**" + - "headroom/providers/opencode/hook-shim/**" - ".github/workflows/opencode-plugin.yml" permissions: @@ -51,3 +53,6 @@ jobs: cmp dist-standalone/entry.opencode.js \ ../../headroom/providers/opencode/_dist/entry.opencode.js \ || { echo "::error::headroom/providers/opencode/_dist/entry.opencode.js is stale - run 'npm run build:standalone' in plugins/opencode and commit the result"; exit 1; } + cmp dist-standalone/hook-shim/handler.js \ + ../../headroom/providers/opencode/hook-shim/handler.js \ + || { echo "::error::headroom/providers/opencode/hook-shim/handler.js is stale - run 'npm run build:standalone' in plugins/opencode and commit the result"; exit 1; } diff --git a/headroom/providers/opencode/hook-shim/handler.js b/headroom/providers/opencode/hook-shim/handler.js new file mode 100644 index 000000000..1dbfba992 --- /dev/null +++ b/headroom/providers/opencode/hook-shim/handler.js @@ -0,0 +1,390 @@ +// src/transport.ts +import { createRequire, syncBuiltinESMExports } from "module"; +var nodeRequire = createRequire(import.meta.url); +var http = nodeRequire("node:http"); +var https = nodeRequire("node:https"); +var http2 = nodeRequire("node:http2"); +var childProcess = nodeRequire("node:child_process"); +var fs = nodeRequire("node:fs"); +var BASE_URL_HEADER = "x-headroom-base-url"; +var ORIGINAL_PATH_HEADER = "x-headroom-original-path"; +var PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL"; +var STATE_KEY = /* @__PURE__ */ Symbol.for("headroom.opencode.transport"); +function getState() { + return globalThis[STATE_KEY]; +} +function setState(state) { + globalThis[STATE_KEY] = state; +} +function shimImportSpecifier() { + const shim = new URL("../hook-shim/handler.js", import.meta.url); + return fs.existsSync(shim) ? shim.href : void 0; +} +function withNodeImportOption(existing, shim) { + const parts = existing?.trim() ? existing.trim().split(/\s+/) : []; + const alreadyPresent = parts.some((part, index) => { + return part === `--import=${shim}` || part === "--import" && parts[index + 1] === shim; + }); + if (!alreadyPresent) { + parts.push(`--import=${shim}`); + } + return parts.join(" "); +} +function withShimEnv(env, proxyUrl2) { + const nextEnv = { ...env ?? process.env }; + nextEnv[PROXY_ENV] = proxyUrl2; + const shim = shimImportSpecifier(); + if (shim) { + nextEnv.NODE_OPTIONS = withNodeImportOption(nextEnv.NODE_OPTIONS, shim); + } + return nextEnv; +} +function installProcessEnv(proxyUrl2) { + process.env[PROXY_ENV] = proxyUrl2; + const shim = shimImportSpecifier(); + if (shim) { + process.env.NODE_OPTIONS = withNodeImportOption(process.env.NODE_OPTIONS, shim); + } +} +function isOptions(value) { + return Boolean(value) && typeof value === "object" && !Array.isArray(value) && !(value instanceof URL); +} +function injectOptionsEnv(args, optionIndex, proxyUrl2) { + const nextArgs = [...args]; + const callback = typeof nextArgs.at(-1) === "function" ? nextArgs.pop() : void 0; + const existing = isOptions(nextArgs[optionIndex]) ? { ...nextArgs[optionIndex] } : {}; + existing.env = withShimEnv(existing.env, proxyUrl2); + if (isOptions(nextArgs[optionIndex])) { + nextArgs[optionIndex] = existing; + } else { + nextArgs.splice(optionIndex, 0, existing); + } + if (callback) { + nextArgs.push(callback); + } + return nextArgs; +} +function wrapSpawn(originalSpawn) { + return function headroomSpawn(...args) { + const state = getState(); + if (!state) { + return Reflect.apply(originalSpawn, this, args); + } + const optionIndex = Array.isArray(args[1]) ? 2 : 1; + return Reflect.apply(originalSpawn, this, injectOptionsEnv(args, optionIndex, state.proxyUrl)); + }; +} +function wrapExec(originalExec) { + return function headroomExec(...args) { + const state = getState(); + if (!state) { + return Reflect.apply(originalExec, this, args); + } + return Reflect.apply(originalExec, this, injectOptionsEnv(args, 1, state.proxyUrl)); + }; +} +function wrapExecFile(originalExecFile) { + return function headroomExecFile(...args) { + const state = getState(); + if (!state) { + return Reflect.apply(originalExecFile, this, args); + } + const optionIndex = Array.isArray(args[1]) ? 2 : 1; + return Reflect.apply(originalExecFile, this, injectOptionsEnv(args, optionIndex, state.proxyUrl)); + }; +} +function wrapFork(originalFork) { + return function headroomFork(...args) { + const state = getState(); + if (!state) { + return Reflect.apply(originalFork, this, args); + } + const optionIndex = Array.isArray(args[1]) ? 2 : 1; + return Reflect.apply(originalFork, this, injectOptionsEnv(args, optionIndex, state.proxyUrl)); + }; +} +function normalizeProxyUrl(proxyUrl2) { + return new URL(proxyUrl2); +} +function isLoopback(hostname) { + const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, ""); + return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1"; +} +function shouldRoute(url, proxy) { + if (url.protocol !== "http:" && url.protocol !== "https:") { + return false; + } + if (isLoopback(url.hostname)) { + return false; + } + if (url.origin === proxy.origin) { + return false; + } + return true; +} +function routedUrl(upstream, proxy) { + return new URL(`${upstream.pathname}${upstream.search}`, proxy.origin); +} +function normalizedOpenAiProxyPath(pathname) { + if (pathname.endsWith("/chat/completions")) { + return "/v1/chat/completions"; + } + if (pathname.endsWith("/responses")) { + return "/v1/responses"; + } + return void 0; +} +function routedUrlForOpenCode(upstream, proxy) { + const normalizedPath = normalizedOpenAiProxyPath(upstream.pathname); + if (!normalizedPath) { + return { + url: routedUrl(upstream, proxy), + originalPath: void 0 + }; + } + return { + url: new URL(`${normalizedPath}${upstream.search}`, proxy.origin), + originalPath: upstream.pathname + }; +} +function requestUrl(input) { + if (input instanceof Request) { + return new URL(input.url); + } + if (input instanceof URL) { + return input; + } + return new URL(String(input)); +} +function mergeFetchHeaders(input, init, upstream, originalPath = void 0) { + const headers = new Headers(input instanceof Request ? input.headers : void 0); + if (init?.headers) { + new Headers(init.headers).forEach((value, key) => headers.set(key, value)); + } + if (upstream) { + headers.set(BASE_URL_HEADER, upstream.origin); + headers.delete("host"); + } + if (originalPath) { + headers.set(ORIGINAL_PATH_HEADER, originalPath); + } + return headers; +} +function withRoutedFetchInput(input, init, proxy) { + const upstream = requestUrl(input); + if (!shouldRoute(upstream, proxy)) { + return [input, init]; + } + const { url: nextUrl, originalPath } = routedUrlForOpenCode(upstream, proxy); + const nextInit = { + ...init, + headers: mergeFetchHeaders(input, init, upstream, originalPath) + }; + if (input instanceof Request) { + return [new Request(nextUrl, input), nextInit]; + } + return [nextUrl, nextInit]; +} +function splitNodeArgs(args) { + const callback = typeof args.at(-1) === "function" ? args.at(-1) : void 0; + const withoutCallback = callback ? args.slice(0, -1) : args; + const [first, second] = withoutCallback; + const options = typeof second === "object" && second !== null ? { ...second } : {}; + if (first instanceof URL) { + return { url: first, options, callback }; + } + if (typeof first === "string") { + try { + return { url: new URL(first), options, callback }; + } catch { + return { options, callback }; + } + } + if (typeof first === "object" && first !== null) { + const requestOptions = { ...first, ...options }; + return { url: urlFromRequestOptions(requestOptions), options: requestOptions, callback }; + } + return { options, callback }; +} +function urlFromRequestOptions(options) { + const protocol = String(options.protocol ?? "http:"); + if (protocol !== "http:" && protocol !== "https:") { + return void 0; + } + const hostValue = options.hostname ?? options.host; + if (!hostValue) { + return void 0; + } + const hostname = String(hostValue).replace(/:\d+$/, ""); + const port = options.port ? `:${String(options.port)}` : ""; + const path = String(options.path ?? "/"); + try { + return new URL(`${protocol}//${hostname}${port}${path}`); + } catch { + return void 0; + } +} +function headersForNodeRequest(options, upstream, originalPath) { + const headers = new Headers(options.headers); + headers.set(BASE_URL_HEADER, upstream.origin); + if (originalPath) { + headers.set(ORIGINAL_PATH_HEADER, originalPath); + } + headers.delete("host"); + const result = {}; + headers.forEach((value, key) => { + result[key] = value; + }); + return result; +} +function routedNodeOptions(parts, proxy) { + if (!parts.url || !shouldRoute(parts.url, proxy)) { + return void 0; + } + const { url: nextUrl, originalPath } = routedUrlForOpenCode(parts.url, proxy); + const { + agent: _agent, + auth: _auth, + createConnection: _createConnection, + defaultPort: _defaultPort, + family: _family, + headers: _headers, + host: _host, + hostname: _hostname, + href: _href, + lookup: _lookup, + path: _path, + pathname: _pathname, + port: _port, + protocol: _protocol, + search: _search, + servername: _servername, + setHost: _setHost, + ...rest + } = parts.options; + return { + ...rest, + protocol: nextUrl.protocol, + hostname: nextUrl.hostname, + port: nextUrl.port || void 0, + path: `${nextUrl.pathname}${nextUrl.search}`, + headers: headersForNodeRequest(parts.options, parts.url, originalPath) + }; +} +function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest) { + return function headroomRequest(...args) { + const state = getState(); + if (!state) { + return Reflect.apply(originalRequest, this, args); + } + const proxy = normalizeProxyUrl(state.proxyUrl); + const parts = splitNodeArgs(args); + const nextOptions = routedNodeOptions(parts, proxy); + if (!nextOptions) { + return Reflect.apply(originalRequest, this, args); + } + const targetRequest = proxy.protocol === "https:" ? originalHttpsRequest : originalHttpRequest; + const nextArgs = parts.callback ? [nextOptions, parts.callback] : [nextOptions]; + return Reflect.apply(targetRequest, this, nextArgs); + }; +} +function wrapGet(request) { + return function headroomGet(...args) { + const req = Reflect.apply(request, this, args); + req.end(); + return req; + }; +} +function wrapHttp2Connect(originalConnect) { + return function headroomHttp2Connect(authority, ...args) { + const state = getState(); + if (state) { + const proxy = normalizeProxyUrl(state.proxyUrl); + const upstream = authority instanceof URL ? authority : new URL(String(authority)); + if (shouldRoute(upstream, proxy)) { + throw new Error( + `Headroom OpenCode wrap blocked direct HTTP/2 connection to ${upstream.origin}. Use fetch, http, or https so traffic can be routed through Headroom.` + ); + } + } + return Reflect.apply(originalConnect, this, [authority, ...args]); + }; +} +function installHeadroomTransport(options) { + const existing = getState(); + if (existing) { + existing.refs += 1; + existing.proxyUrl = options.proxyUrl; + existing.debug = Boolean(options.debug); + installProcessEnv(options.proxyUrl); + return () => uninstallHeadroomTransport(); + } + const state = { + refs: 1, + proxyUrl: options.proxyUrl, + debug: Boolean(options.debug), + originalFetch: globalThis.fetch, + originalHttpRequest: http.request, + originalHttpGet: http.get, + originalHttpsRequest: https.request, + originalHttpsGet: https.get, + originalHttp2Connect: http2.connect, + originalChildSpawn: childProcess.spawn, + originalChildExec: childProcess.exec, + originalChildExecFile: childProcess.execFile, + originalChildFork: childProcess.fork + }; + setState(state); + installProcessEnv(options.proxyUrl); + globalThis.fetch = async (...args) => { + const current = getState(); + if (!current) { + return state.originalFetch(...args); + } + const proxy = normalizeProxyUrl(current.proxyUrl); + const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy); + return state.originalFetch(nextInput, nextInit); + }; + http.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpRequest); + https.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpsRequest); + http.get = wrapGet(http.request); + https.get = wrapGet(https.request); + http2.connect = wrapHttp2Connect(state.originalHttp2Connect); + childProcess.spawn = wrapSpawn(state.originalChildSpawn); + childProcess.exec = wrapExec(state.originalChildExec); + childProcess.execFile = wrapExecFile(state.originalChildExecFile); + childProcess.fork = wrapFork(state.originalChildFork); + syncBuiltinESMExports(); + return () => uninstallHeadroomTransport(); +} +function uninstallHeadroomTransport() { + const state = getState(); + if (!state) { + return; + } + state.refs -= 1; + if (state.refs > 0) { + return; + } + globalThis.fetch = state.originalFetch; + http.request = state.originalHttpRequest; + http.get = state.originalHttpGet; + https.request = state.originalHttpsRequest; + https.get = state.originalHttpsGet; + http2.connect = state.originalHttp2Connect; + childProcess.spawn = state.originalChildSpawn; + childProcess.exec = state.originalChildExec; + childProcess.execFile = state.originalChildExecFile; + childProcess.fork = state.originalChildFork; + syncBuiltinESMExports(); + setState(void 0); +} + +// src/hook-shim.ts +var proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL; +if (!proxyUrl) { + throw new Error( + "Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL" + ); +} +installHeadroomTransport({ proxyUrl }); diff --git a/plugins/opencode/src/hook-shim.ts b/plugins/opencode/src/hook-shim.ts new file mode 100644 index 000000000..de15cd01d --- /dev/null +++ b/plugins/opencode/src/hook-shim.ts @@ -0,0 +1,26 @@ +// Self-contained Node `--import` loader for the OpenCode transport, built +// standalone (see tsup.standalone.config.ts) and shipped inside the Python wheel +// at headroom/providers/opencode/hook-shim/handler.js. +// +// transport.ts wraps `fetch`/`http`/`https` in the plugin's own process, but a +// spawned Node child (an `npx` MCP server, `tokensave serve`, ...) is a fresh +// process, so its traffic is only routed if this loader runs at that child's +// startup via NODE_OPTIONS=--import. `shimImportSpecifier()` in transport.ts +// resolves `../hook-shim/handler.js` next to the loaded entry, which is this +// file in a wheel install. +// +// The checkout uses plugins/opencode/hook-shim/handler.js instead, which imports +// the non-bundled `../dist/index.js`; pip installs have no node_modules, so this +// variant inlines the transport. Without it shipped, the loader path did not +// exist, so child-process routing was silently disabled for wheel installs +// (before #2806 it crashed every Node child with ERR_MODULE_NOT_FOUND) (#2850). +import { installHeadroomTransport } from "./transport.js"; + +const proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL; +if (!proxyUrl) { + throw new Error( + "Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL", + ); +} + +installHeadroomTransport({ proxyUrl }); diff --git a/plugins/opencode/tsup.standalone.config.ts b/plugins/opencode/tsup.standalone.config.ts index 3045a98c3..1391e4024 100644 --- a/plugins/opencode/tsup.standalone.config.ts +++ b/plugins/opencode/tsup.standalone.config.ts @@ -6,7 +6,12 @@ import { defineConfig } from "tsup"; // with node_modules present; pip installs have no node_modules, so this // variant bundles every dependency into a single loadable file. export default defineConfig({ - entry: { "entry.opencode": "src/entry.opencode.ts" }, + // `hook-shim/handler` is the self-contained Node `--import` loader shipped + // alongside the entry so spawned Node children route their traffic too (#2850). + entry: { + "entry.opencode": "src/entry.opencode.ts", + "hook-shim/handler": "src/hook-shim.ts", + }, outDir: "dist-standalone", format: ["esm"], splitting: false, diff --git a/tests/test_providers_opencode_plugin_path.py b/tests/test_providers_opencode_plugin_path.py index 98e8dd7eb..c6739bbe1 100644 --- a/tests/test_providers_opencode_plugin_path.py +++ b/tests/test_providers_opencode_plugin_path.py @@ -31,6 +31,23 @@ def test_packaged_bundle_is_committed_and_self_contained() -> None: assert 'from "@opencode-ai/plugin"' not in text +def test_hook_shim_is_committed_next_to_the_entry_bundle() -> None: + # transport.ts resolves `../hook-shim/handler.js` next to the loaded entry, + # so the shim must ship as a sibling of _dist/. Without it, Node children + # spawned under `headroom wrap opencode` lose fetch/http routing (the + # existsSync guard skips injection), and before that guard they crashed with + # ERR_MODULE_NOT_FOUND on every Node MCP (#2850, #2806). + shim = _PACKAGED.resolve().parent.parent / "hook-shim" / "handler.js" + assert shim.is_file(), "committed wheel hook-shim missing - run npm run build:standalone" + text = shim.read_text(encoding="utf-8") + assert len(text) > 5_000, "hook-shim suspiciously small - not the standalone build?" + # Self-contained standalone build, not the checkout dev shim (which imports + # the non-bundled ../dist/index.js that site-packages has no node_modules for). + assert 'from "../dist/index.js"' not in text + assert "installHeadroomTransport" in text + assert "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL" in text + + def test_plugin_path_env_override_wins(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: override = tmp_path / "custom.js" override.write_text("// plugin") From 5e53b8aa0a720b5e6c4974b4b77b734da90ecde7 Mon Sep 17 00:00:00 2001 From: Suliman Abdulrazzaq <144490671+SulimanAbdulrazzaq@users.noreply.github.com> Date: Tue, 11 Aug 2026 19:46:03 +0300 Subject: [PATCH 033/138] fix(opencode): keep Claude models off OpenAI provider ## Description The injected `headroom` OpenCode provider uses `@ai-sdk/openai-compatible` and the proxy's `/v1/chat/completions` route. It currently advertises Claude model IDs in that provider, so OpenCode sends Claude requests to the OpenAI upstream and receives `invalid_api_key` errors. Keep Claude on OpenCode's native `anthropic` provider, which Headroom already redirects to the proxy. Closes #2911 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (bug fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Remove Claude IDs from the injected OpenAI-compatible provider model map. - Keep GPT models available through the `headroom/` namespace. - Add regression assertions that generated config never advertises Claude models on this endpoint. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text python -m pytest tests/test_providers_opencode_config.py -q -k "not build_launch_env_with_project" 40 passed, 1 deselected python -m ruff check headroom/providers/opencode/config.py tests/test_providers_opencode_config.py All checks passed! python -m compileall -q headroom/providers/opencode/config.py tests/test_providers_opencode_config.py (pass) ``` The full config test module also exposes an unrelated pre-existing Windows path assertion failure in `test_build_launch_env_with_project`; the failure is caused by comparing a native `Path` string with JSON-escaped backslashes and is outside this change. ## Real Behavior Proof - Environment: Windows 11, Python 3.11; no external API credentials used. - Exact command / steps: `python -c "from headroom.providers.opencode.config import headroom_provider_entry; print(sorted(headroom_provider_entry(8787)['models']))"` - Observed result: `['gpt-4.1', 'gpt-4o']`; the generated OpenAI-compatible provider no longer advertises any `claude-*` IDs. - Not tested: live OpenCode request routing or a vendor API call, because they require external credentials. The regression suite verifies the generated configuration consumed by OpenCode. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas (not needed; the provider routing rationale is documented inline) - [ ] I have made corresponding changes to the documentation (the generated provider behavior is documented in code; existing docs describe the separate npm provider) - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective - [x] New and existing relevant unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes The native `anthropic` and `openai` provider entries both continue to point at the Headroom proxy, so this change only removes an invalid duplicate Claude route and does not affect native Claude traffic. --- headroom/providers/opencode/config.py | 28 ++++++++++--------------- tests/test_providers_opencode_config.py | 11 +++++++--- 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/headroom/providers/opencode/config.py b/headroom/providers/opencode/config.py index 6c64544fe..08a6f5748 100644 --- a/headroom/providers/opencode/config.py +++ b/headroom/providers/opencode/config.py @@ -31,24 +31,18 @@ _MCP_BLOCK_RE = re.compile( ) HEADROOM_OPENCODE_PLUGIN = "headroom-opencode" -# Models exposed by the injected `headroom` provider. OpenCode only resolves -# `headroom/` for ids listed in the provider's `models` map, so an empty -# map means every documented `headroom/*` model fails with "Model not found". -# Keep in sync with DEFAULT_MODELS in plugins/opencode/src/provider.ts and the -# table in plugins/opencode/README.md. +# Models exposed by the injected `headroom` provider. This provider uses +# ``@ai-sdk/openai-compatible`` and the proxy's ``/v1/chat/completions`` path, +# which is routed to the configured OpenAI upstream. Do not advertise Claude +# models here: OpenCode would send them through the OpenAI endpoint and report +# an ``invalid_api_key`` error instead of reaching Anthropic. Claude models are +# available through OpenCode's native ``anthropic`` provider, whose base URL is +# also redirected to Headroom by ``build_opencode_config_content``. +# +# OpenCode only resolves ``headroom/`` for ids listed in this map, so an +# empty map means every documented ``headroom/*`` model fails with "Model not +# found". HEADROOM_OPENCODE_MODELS: dict[str, Any] = { - "claude-sonnet-4-6": { - "name": "Claude Sonnet 4.6", - "limit": {"context": 200000, "output": 16384}, - }, - "claude-opus-4-6": { - "name": "Claude Opus 4.6", - "limit": {"context": 200000, "output": 16384}, - }, - "claude-haiku-4-5-20251001": { - "name": "Claude Haiku 4.5", - "limit": {"context": 200000, "output": 8192}, - }, "gpt-4o": { "name": "GPT-4o", "limit": {"context": 128000, "output": 16384}, diff --git a/tests/test_providers_opencode_config.py b/tests/test_providers_opencode_config.py index 658ba1ea4..aec387013 100644 --- a/tests/test_providers_opencode_config.py +++ b/tests/test_providers_opencode_config.py @@ -199,7 +199,10 @@ def test_inject_provider_config_creates_file( assert config["provider"]["headroom"]["npm"] == "@ai-sdk/openai-compatible" # Bare model ids: OpenCode resolves them as "headroom/" (#1657). models = config["provider"]["headroom"]["models"] - assert "claude-sonnet-4-6" in models + assert set(models) == {"gpt-4o", "gpt-4.1"} + # The injected provider is OpenAI-compatible. Claude models must remain on + # OpenCode's native Anthropic provider so they are not sent to OpenAI. + assert not any(model_id.startswith("claude-") for model_id in models) assert all(not model_id.startswith("headroom/") for model_id in models) assert "mcp" not in config assert "model" not in config # headroom provider is a transparent pass-through @@ -456,10 +459,12 @@ def test_build_opencode_config_content_without_mcp( providers = config["provider"] assert providers["anthropic"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1" assert providers["openai"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1" - # The headroom provider exposes explicit models so "headroom/" resolves (#1657). + # The headroom provider exposes only models supported by its + # OpenAI-compatible endpoint so "headroom/" resolves safely (#1657). assert providers["headroom"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1" models = providers["headroom"]["models"] - assert "claude-sonnet-4-6" in models + assert set(models) == {"gpt-4o", "gpt-4.1"} + assert not any(model_id.startswith("claude-") for model_id in models) assert all(not model_id.startswith("headroom/") for model_id in models) # The transport plugin is injected by absolute path (opencode loads it directly). assert config["plugin"] == [str(plugin)] From 739fdef423fa8cbc82537481c875d4570b0ecad4 Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Singh <152812718+abhinavkr26104@users.noreply.github.com> Date: Tue, 11 Aug 2026 22:19:07 +0530 Subject: [PATCH 034/138] fix(proxy): cancel periodic TOIN task on shutdown MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Retains the periodic TOIN statistics task on application state and reaps it during proxy lifespan shutdown. Fixes #2896 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Store the periodic TOIN task as `app.state.periodic_toin_stats_task` when enabled. - Cancel and await the task with the existing bounded shutdown helper before stopping proxy resources. - Clear the application state reference after shutdown. - Add regression coverage proving the task is canceled and reaped when the FastAPI lifespan exits. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text python -m pytest -q tests/test_proxy_telemetry_env.py 0 items / 1 error ModuleNotFoundError: No module named 'headroom._core' Temporary in-process native-core stub + real FastAPI TestClient: python -m pytest -q tests/test_proxy_telemetry_env.py 8 passed ruff check . All checks passed! ruff format --check . 1382 files already formatted python -m mypy headroom Success: no issues found in 515 source files python -m pytest -q Collected 8878 items / 174 errors / 18 skipped. Interrupted during collection because this Windows environment lacks the compiled headroom._core extension. ``` ## Real Behavior Proof - Environment: Windows, Python 3.12, real FastAPI `TestClient` lifespan; only the unavailable native `headroom._core` import was replaced with an in-process test stub. - Exact command / steps: Ran the telemetry test module with the temporary core stub. The new test enabled periodic TOIN stats, held the real lifespan open, observed the stored task, exited the `TestClient` context, and checked that the task was canceled and the state reference cleared. - Observed result: 8 telemetry tests passed, including the new shutdown regression test; the periodic task reported canceled after lifespan exit and no task reference remained on application state. - Who maintains it: Headroom Labs maintains this active upstream repository and proxy lifecycle. - Install surface: No dependencies or install behavior changed. The fix uses existing asyncio and FastAPI lifecycle APIs; no native code or runtime network access is introduced. - Not tested: The complete suite and the unmodified proxy test command cannot run in this Windows environment without the compiled `headroom._core` extension. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes (full suite blocked by missing native extension; stubbed focused tests pass) - [x] I did not edit `CHANGELOG.md` - it is generated by release-please from my Conventional Commit PR title. ## Screenshots (if applicable) Not applicable. ## Additional Notes The shutdown uses the existing three-second `_timed()` bound and handles the disabled configuration without creating a task. --- headroom/proxy/server.py | 15 ++++++++++++++- tests/test_proxy_telemetry_env.py | 30 ++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py index 1b58db04e..c26160a4a 100644 --- a/headroom/proxy/server.py +++ b/headroom/proxy/server.py @@ -2553,6 +2553,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: app.state.started_at = time.time() app.state.ready = False app.state.startup_error = None + app.state.periodic_toin_stats_task = None try: try: @@ -2560,7 +2561,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: # Startup await proxy.startup() if config.periodic_toin_stats_enabled: - asyncio.create_task(_log_toin_stats_periodically()) + app.state.periodic_toin_stats_task = asyncio.create_task( + _log_toin_stats_periodically() + ) if proxy.usage_reporter: await proxy.usage_reporter.start(proxy) if proxy.traffic_learner: @@ -2610,6 +2613,16 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: exc, ) + periodic_toin_stats_task = app.state.periodic_toin_stats_task + if periodic_toin_stats_task is not None: + periodic_toin_stats_task.cancel() + await _timed( + asyncio.gather(periodic_toin_stats_task, return_exceptions=True), + label="periodic_toin_stats.stop", + timeout=3.0, + ) + app.state.periodic_toin_stats_task = None + if _cc_reconciler is not None: await _timed(_cc_reconciler.stop(), label="cc_reconciler.stop", timeout=3.0) if _beacon_is_owner[0]: diff --git a/tests/test_proxy_telemetry_env.py b/tests/test_proxy_telemetry_env.py index e3ffd65a6..0dc51c117 100644 --- a/tests/test_proxy_telemetry_env.py +++ b/tests/test_proxy_telemetry_env.py @@ -98,3 +98,33 @@ class TestProxyPeriodicTOINStatsEnv: pass assert requested is True + + def test_lifespan_cancels_periodic_toin_stats_on_shutdown(self, monkeypatch): + """Shutdown cancels and awaits the periodic TOIN stats task.""" + monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1") + + async def hold_periodic_stats_task(): + await asyncio.Event().wait() + + monkeypatch.setattr( + "headroom.proxy.server._log_toin_stats_periodically", + hold_periodic_stats_task, + ) + + app = create_app( + ProxyConfig( + optimize=False, + cache_enabled=False, + rate_limit_enabled=False, + cost_tracking_enabled=False, + periodic_toin_stats_enabled=True, + ) + ) + + with TestClient(app): + task = app.state.periodic_toin_stats_task + assert task is not None + assert not task.done() + + assert task.cancelled() + assert app.state.periodic_toin_stats_task is None From 0ae948c1510735df39317bf0861f8a8750cdbf9d Mon Sep 17 00:00:00 2001 From: Joseph Benno <91036825+Robert2547@users.noreply.github.com> Date: Tue, 11 Aug 2026 12:52:27 -0400 Subject: [PATCH 035/138] fix(cache): bound compression cache bookkeeping MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `CompressionCache.max_entries` bounded the main compression cache, but not `_stable_hashes` or `_first_seen`. A long-lived session could therefore retain every unique tool-result hash even while `_cache` stayed empty. This change applies the same bounded retention to both side tables. It also cleans up expired first-seen entries and resets the timing window when compression occurs near the TTL boundary. Fixes #2874 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Store stable hashes and first-seen timestamps in ordered mappings. - Evict oldest entries when either side table exceeds `max_entries`. - Keep all bookkeeping under the existing reentrant lock. - Reset first-seen timing after compression near the TTL boundary. - Add tests covering size limits, TTL behavior, frozen-prefix safety, and concurrency. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text uv run ruff format --check . Passed uv run ruff check . All checks passed! uv run mypy headroom Success: no issues found in 515 source files uv run pytest Passed ``` Focused cache tests on macOS 26.5.2 arm64 with Python 3.11.14: ```text uv run pytest tests/test_compression_cache.py::TestCompressionCacheRetention -v 5 passed in 0.30s uv run pytest tests/test_compression_cache.py -q 38 passed in 5.76s ``` After the final formatting-only commit, the cache test file was also run on Linux with Python 3.12.13: ```text 37 passed, 1 skipped in 32.70s ``` ## Real Behavior Proof - Environment: Linux 6.18 x86_64, Python 3.12.13, `CompressionCache(max_entries=100)`. - Exact command / steps: Created a `CompressionCache(max_entries=100)`, generated 20,000 unique content hashes, and passed each hash through `mark_stable()` and `should_defer_compression()`. Store sizes were sampled after 100, 1,000, 5,000, and 20,000 results. - Observed result: `_cache=0`, `_stable_hashes=100`, and `_first_seen=100` at every sample after reaching the configured limit. At 20,000 results, traced memory was approximately 0.03 MB current and 0.04 MB peak. Before the fix, the same workload retained all 20,000 hashes and timestamps. - Not tested: A live multi-hour proxy/provider session. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented the code where retention behavior is not obvious - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove the fix is effective - [x] New and existing unit tests pass locally - [x] I did **not** edit `CHANGELOG.md` ## Screenshots N/A — internal cache bookkeeping change. ## Additional Notes No changes to dependencies, public APIs, or configuration. No user-facing behavior changes. --- headroom/cache/compression_cache.py | 47 ++++++++++-- tests/test_compression_cache.py | 110 ++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+), 6 deletions(-) diff --git a/headroom/cache/compression_cache.py b/headroom/cache/compression_cache.py index 71beb4091..00abf07b0 100644 --- a/headroom/cache/compression_cache.py +++ b/headroom/cache/compression_cache.py @@ -135,8 +135,10 @@ class CompressionCache: # `compute_frozen_count` (bounded above by the `min` clamp at # `proxy/handlers/anthropic.py`) and `update_from_result`'s # "unchanged content" tracking. - self._stable_hashes: set[str] = set() - self._first_seen: dict[str, float] = {} + # Ordered mappings preserve set/dict-style membership while allowing + # deterministic oldest-first eviction. + self._stable_hashes: OrderedDict[str, None] = OrderedDict() + self._first_seen: OrderedDict[str, float] = OrderedDict() self._hits: int = 0 self._misses: int = 0 self._total_tokens_saved: int = 0 @@ -172,6 +174,34 @@ class CompressionCache: _, evicted = self._cache.popitem(last=False) self._total_tokens_saved -= evicted.tokens_saved + def _mark_stable_locked(self, content_hash: str) -> None: + """Record a stable hash while bounding retained bookkeeping.""" + self._stable_hashes[content_hash] = None + self._stable_hashes.move_to_end(content_hash) + + while len(self._stable_hashes) > self.max_entries: + self._stable_hashes.popitem(last=False) + + def _record_first_seen_locked(self, content_hash: str, seen_at: float) -> None: + """Record a first-seen timestamp while bounding retained bookkeeping.""" + self._first_seen[content_hash] = seen_at + self._first_seen.move_to_end(content_hash) + + while len(self._first_seen) > self.max_entries: + self._first_seen.popitem(last=False) + + def _prune_expired_first_seen_locked( + self, + now: float, + ttl_seconds: float, + ) -> None: + """Remove first-seen entries whose cache timing window has expired.""" + while self._first_seen: + _, oldest_seen_at = next(iter(self._first_seen.items())) + if now - oldest_seen_at < ttl_seconds: + break + self._first_seen.popitem(last=False) + def mark_stable(self, content_hash: str) -> None: """Mark a content hash as stable (unchanged, not compressed). @@ -180,7 +210,7 @@ class CompressionCache: even though no compressed version exists in the cache. """ with self._lock: - self._stable_hashes.add(content_hash) + self._mark_stable_locked(content_hash) def mark_stable_from_messages(self, messages: list[dict], up_to: int) -> None: """Mark all tool_result hashes in messages[:up_to] as stable.""" @@ -189,7 +219,7 @@ class CompressionCache: if _is_tool_result_message(msg): content = _extract_tool_result_content(msg) if content is not None: - self._stable_hashes.add(self.content_hash(content)) + self._mark_stable_locked(self.content_hash(content)) def should_defer_compression( self, @@ -216,13 +246,18 @@ class CompressionCache: """ with self._lock: now = time.time() + self._prune_expired_first_seen_locked(now, ttl_seconds) + first_seen = self._first_seen.get(content_hash) if first_seen is None: - self._first_seen[content_hash] = now + self._record_first_seen_locked(content_hash, now) return False # First time — compress now (no cache entry to preserve) + age = now - first_seen if age >= ttl_seconds - batch_window: + self._record_first_seen_locked(content_hash, now) return False # Near TTL boundary — compress now (batch window) + return True # Seen recently within TTL — defer to preserve cache def get_stats(self) -> dict: @@ -335,7 +370,7 @@ class CompressionCache: continue if orig_content == comp_content: # Content unchanged — mark as stable for frozen count walk - self._stable_hashes.add(self.content_hash(orig_content)) + self._mark_stable_locked(self.content_hash(orig_content)) continue h = self.content_hash(orig_content) tokens_saved = len(orig_content) // 4 - len(comp_content) // 4 diff --git a/tests/test_compression_cache.py b/tests/test_compression_cache.py index 20cfc82cc..3a8f04efe 100644 --- a/tests/test_compression_cache.py +++ b/tests/test_compression_cache.py @@ -17,6 +17,116 @@ def small_cache() -> CompressionCache: return CompressionCache(max_entries=3) +class TestCompressionCacheRetention: + def test_stable_hashes_are_bounded(self) -> None: + cache = CompressionCache(max_entries=3) + hashes = [CompressionCache.content_hash(f"stable-{index}") for index in range(4)] + + for content_hash in hashes: + cache.mark_stable(content_hash) + + assert len(cache._stable_hashes) == 3 + assert hashes[0] not in cache._stable_hashes + assert hashes[-1] in cache._stable_hashes + + def test_first_seen_is_bounded(self) -> None: + cache = CompressionCache(max_entries=3) + hashes = [CompressionCache.content_hash(f"first-seen-{index}") for index in range(4)] + + for content_hash in hashes: + cache.should_defer_compression(content_hash) + + assert len(cache._first_seen) == 3 + assert hashes[0] not in cache._first_seen + assert hashes[-1] in cache._first_seen + + def test_expired_first_seen_starts_new_window(self, monkeypatch: pytest.MonkeyPatch) -> None: + cache = CompressionCache(max_entries=3) + content_hash = CompressionCache.content_hash("repeated content") + timestamps = iter([1_000.0, 1_271.0, 1_272.0]) + + monkeypatch.setattr( + "headroom.cache.compression_cache.time.time", + lambda: next(timestamps), + ) + + assert ( + cache.should_defer_compression( + content_hash, + ttl_seconds=300, + batch_window=30, + ) + is False + ) + assert ( + cache.should_defer_compression( + content_hash, + ttl_seconds=300, + batch_window=30, + ) + is False + ) + assert cache._first_seen[content_hash] == 1_271.0 + assert ( + cache.should_defer_compression( + content_hash, + ttl_seconds=300, + batch_window=30, + ) + is True + ) + + def test_evicted_stable_hash_does_not_extend_frozen_prefix(self) -> None: + cache = CompressionCache(max_entries=1) + old_content = "old stable tool output" + new_content = "new stable tool output" + + cache.mark_stable(CompressionCache.content_hash(old_content)) + cache.mark_stable(CompressionCache.content_hash(new_content)) + + messages = [ + {"role": "user", "content": "start"}, + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": "tool-1", + "content": old_content, + } + ], + }, + {"role": "user", "content": "follow up"}, + ] + + assert cache.compute_frozen_count(messages) == 1 + + def test_concurrent_bookkeeping_stays_bounded(self) -> None: + import threading + + cache = CompressionCache(max_entries=50) + errors: list[Exception] = [] + + def worker(thread_id: int) -> None: + try: + for index in range(100): + content_hash = CompressionCache.content_hash(f"thread-{thread_id}-{index}") + cache.mark_stable(content_hash) + cache.should_defer_compression(content_hash) + except Exception as exc: # pragma: no cover + errors.append(exc) + + threads = [threading.Thread(target=worker, args=(index,)) for index in range(8)] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + + assert errors == [] + assert len(cache._stable_hashes) <= cache.max_entries + assert len(cache._first_seen) <= cache.max_entries + + class TestCompressionCache: def test_cache_miss_returns_none(self, cache: CompressionCache) -> None: h = CompressionCache.content_hash("some content") From 620028fa18843622d3e454bd40fb91a93e607dbf Mon Sep 17 00:00:00 2001 From: Suliman Abdulrazzaq <144490671+SulimanAbdulrazzaq@users.noreply.github.com> Date: Tue, 11 Aug 2026 19:53:53 +0300 Subject: [PATCH 036/138] fix(proxy): emit request log timestamps in UTC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `RequestLog.timestamp` was serialized with `datetime.now().isoformat()`, which omits timezone information. Browsers then interpret the value as local time, so requests from a UTC container can display negative ages in non-UTC dashboards. Closes #2910 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - Emit request-log timestamps from `datetime.now(timezone.utc)` so the ISO-8601 value includes `+00:00`. - Add a regression test that parses the emitted timestamp and requires a UTC offset. ## Testing - [x] New tests added for the regression - [x] `python -m compileall -q headroom/proxy/outcome.py tests/test_request_outcome.py` - [x] `git diff --check` - [ ] Unit tests pass (`pytest`) — the repository's Rust extension cannot build in this Windows environment because `link.exe` (MSVC) is unavailable; the focused test is included for CI. ### Test Output ```text python -m compileall -q headroom/proxy/outcome.py tests/test_request_outcome.py (pass) git diff --check (pass) uv run pytest tests/test_request_outcome.py -q blocked while building headroom-py: linker `link.exe` not found ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.11; proxy timestamps are generated in `headroom/proxy/outcome.py`. - Exact command / steps: traced the Recent Requests write path and added a timestamp assertion in `tests/test_request_outcome.py` (CI will run with the project's Rust toolchain). - Observed result: the production call now emits an ISO-8601 timestamp with `+00:00`; the regression assertion requires an offset-aware UTC value, preventing browser timezone skew. - Not tested: full pytest suite locally because the MSVC linker is unavailable. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review - [x] I have added tests that prove my fix is effective - [x] I did not edit `CHANGELOG.md` Signed-off-by: Suliman Abdulrazzaq --- headroom/proxy/outcome.py | 7 +++++-- tests/test_request_outcome.py | 17 +++++++++++++++++ 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/headroom/proxy/outcome.py b/headroom/proxy/outcome.py index e0b304d4c..5a23acc04 100644 --- a/headroom/proxy/outcome.py +++ b/headroom/proxy/outcome.py @@ -27,7 +27,7 @@ from __future__ import annotations import logging from dataclasses import dataclass, field -from datetime import datetime +from datetime import datetime, timezone from typing import Any from headroom.proxy.tool_schema_savings_policy import ( @@ -526,7 +526,10 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None: request_logger.log( RequestLog( request_id=outcome.request_id, - timestamp=datetime.now().isoformat(), + # Request logs are consumed by browsers in arbitrary time zones. + # Include the UTC offset so relative-age calculations represent + # the same instant regardless of where the proxy runs. + timestamp=datetime.now(timezone.utc).isoformat(), provider=outcome.provider, model=outcome.model, input_tokens_original=outcome.original_tokens, diff --git a/tests/test_request_outcome.py b/tests/test_request_outcome.py index 09936a094..d2295a5ea 100644 --- a/tests/test_request_outcome.py +++ b/tests/test_request_outcome.py @@ -15,6 +15,7 @@ import asyncio import contextlib import logging from dataclasses import FrozenInstanceError +from datetime import datetime, timezone from typing import Any from unittest.mock import AsyncMock, MagicMock @@ -325,6 +326,22 @@ async def test_funnel_logs_request_with_derived_cache_hit() -> None: assert log_entry.cache_hit is True +@pytest.mark.asyncio +async def test_funnel_logs_request_timestamp_with_utc_offset() -> None: + """Recent-request timestamps must identify an absolute instant. + + A naive ISO timestamp is interpreted in the browser's local timezone, + which makes the dashboard show negative ages when the proxy and browser + use different timezone settings. + """ + h = _FunnelHarness() + await h._record_request_outcome(_outcome()) + + timestamp = datetime.fromisoformat(h.logger.logs[0].timestamp) + assert timestamp.tzinfo is not None + assert timestamp.utcoffset() == timezone.utc.utcoffset(timestamp) + + @pytest.mark.asyncio async def test_funnel_skips_request_log_when_logger_absent() -> None: """Same pattern as cost_tracker — optional surface.""" From 4bd8ecd1e31475365801791d35630f66f7393553 Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Singh <152812718+abhinavkr26104@users.noreply.github.com> Date: Tue, 11 Aug 2026 22:25:20 +0530 Subject: [PATCH 037/138] fix(memory): close MCP backend on shutdown MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Closes the initialized LocalBackend and cancels in-flight initialization whenever the memory MCP stdio transport exits. Fixes #2898 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Added an explicit server cleanup callback that cancels and awaits pending backend initialization. - Closes an initialized backend exactly once and clears the backend/task references. - Runs cleanup in `_run()` through a `finally` block after the stdio transport exits, including transport errors. - Added regression coverage for initialized cleanup, pending initialization cancellation, idempotence, and `_run()` shutdown behavior. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text python -m pytest -q tests/test_memory/test_mcp_server.py 15 passed, 20 warnings ruff check . All checks passed! ruff format --check . 1382 files already formatted python -m mypy headroom Success: no issues found in 515 source files python -m pytest -q Collected 8881 items / 174 errors / 18 skipped. Interrupted during collection because this Windows environment lacks the compiled headroom._core extension. ``` ## Real Behavior Proof - Environment: Windows, Python 3.12, async MCP server lifecycle test with the real `create_memory_server()` closure and an embedded server transport stub. - Exact command / steps: Ran `python -m pytest -q tests/test_memory/test_mcp_server.py`; the regression tests initialized a backend through the server's registered tool lifecycle, returned the stdio transport, and invoked the cleanup callback from `_run()`'s `finally` path. - Observed result: 15 tests passed. Initialized backends were closed once, pending initialization was cancelled and awaited, and transport exit invoked cleanup even when the server run returned. - Who maintains it: Headroom Labs maintains this active upstream repository and memory MCP server. - Install surface: No dependencies or install behavior changed. The fix uses existing asyncio lifecycle handling and `LocalBackend.close()`; no native code or runtime network access is introduced. - Not tested: The complete repository suite could not run past collection because this Windows environment lacks the compiled `headroom._core` extension. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes (full suite blocked by missing native extension; targeted tests pass) - [x] I did not edit `CHANGELOG.md` - it is generated by release-please from my Conventional Commit PR title. ## Screenshots (if applicable) Not applicable. ## Additional Notes Cleanup is attached to each created memory MCP server and is idempotent, so embedded callers can invoke the same lifecycle callback safely if needed. --- headroom/memory/mcp_server.py | 31 +++++++++++- tests/test_memory/test_mcp_server.py | 71 ++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 2 deletions(-) diff --git a/headroom/memory/mcp_server.py b/headroom/memory/mcp_server.py index 2a42dc7ab..3720b3e4f 100644 --- a/headroom/memory/mcp_server.py +++ b/headroom/memory/mcp_server.py @@ -162,6 +162,7 @@ def create_memory_server(db_path: str, user_id: str = "default") -> Server: server = Server("headroom-memory") _backend: LocalBackend | None = None _init_task: asyncio.Task[LocalBackend] | None = None + _close_lock = asyncio.Lock() async def _init_backend() -> LocalBackend: """Initialize backend with ONNX embedder (fast, no PyTorch).""" @@ -225,6 +226,26 @@ def create_memory_server(db_path: str, user_id: str = "default") -> Server: _init_task = None raise + async def _close_backend() -> None: + """Cancel backend initialization and close any initialized backend.""" + nonlocal _backend, _init_task + async with _close_lock: + init_task = _init_task + if init_task is not None: + if not init_task.done(): + init_task.cancel() + await asyncio.gather(init_task, return_exceptions=True) + if _init_task is init_task: + _init_task = None + + backend = _backend + _backend = None + if backend is not None: + try: + await backend.close() + except Exception as cleanup_error: + logger.warning("Memory MCP: failed backend cleanup: %s", cleanup_error) + @server.list_tools() async def list_tools() -> list[Tool]: # Kick off background init on first list_tools (called at MCP handshake) @@ -243,6 +264,7 @@ def create_memory_server(db_path: str, user_id: str = "default") -> Server: return [TextContent(type="text", text=f"Unknown tool: {name}")] + server._headroom_close = _close_backend # type: ignore[attr-defined] return server @@ -357,8 +379,13 @@ async def _handle_save( async def _run(db_path: str, user_id: str) -> None: server = create_memory_server(db_path, user_id) - async with stdio_server() as (read_stream, write_stream): - await server.run(read_stream, write_stream, server.create_initialization_options()) + try: + async with stdio_server() as (read_stream, write_stream): + await server.run(read_stream, write_stream, server.create_initialization_options()) + finally: + close_backend = getattr(server, "_headroom_close", None) + if close_backend is not None: + await close_backend() def _memory_mcp_startup_context( diff --git a/tests/test_memory/test_mcp_server.py b/tests/test_memory/test_mcp_server.py index cd2779627..b55f28218 100644 --- a/tests/test_memory/test_mcp_server.py +++ b/tests/test_memory/test_mcp_server.py @@ -219,6 +219,77 @@ def test_concurrent_tool_calls_share_backend_initialization(monkeypatch) -> None asyncio.run(scenario()) +def test_server_cleanup_closes_initialized_backend_once(monkeypatch) -> None: + async def scenario() -> None: + backend = SimpleNamespace(close=AsyncMock()) + monkeypatch.setattr(mcp_server_mod, "Server", _CapturingServer) + monkeypatch.setattr(mcp_server_mod, "LocalBackend", lambda config: backend) + monkeypatch.setattr(mcp_server_mod, "_warm_up_backend", AsyncMock()) + + server = mcp_server_mod.create_memory_server("memory.db", user_id="alice") + await server.list_tools_handler() + await asyncio.sleep(0) + + close_backend = server._headroom_close + await close_backend() + await close_backend() + + backend.close.assert_awaited_once() + + asyncio.run(scenario()) + + +def test_server_cleanup_cancels_pending_backend_initialization(monkeypatch) -> None: + async def scenario() -> None: + init_started = asyncio.Event() + backend = SimpleNamespace(close=AsyncMock()) + + async def warm_up(_backend, _user_id: str) -> None: + init_started.set() + await asyncio.Event().wait() + + monkeypatch.setattr(mcp_server_mod, "Server", _CapturingServer) + monkeypatch.setattr(mcp_server_mod, "LocalBackend", lambda config: backend) + monkeypatch.setattr(mcp_server_mod, "_warm_up_backend", warm_up) + + server = mcp_server_mod.create_memory_server("memory.db", user_id="alice") + await server.list_tools_handler() + await init_started.wait() + + await server._headroom_close() + + backend.close.assert_awaited_once() + + asyncio.run(scenario()) + + +def test_run_closes_backend_when_stdio_exits(monkeypatch) -> None: + async def scenario() -> None: + close_backend = AsyncMock() + server = SimpleNamespace( + create_initialization_options=lambda: {}, + run=AsyncMock(), + _headroom_close=close_backend, + ) + + class _StdioContext: + async def __aenter__(self): + return object(), object() + + async def __aexit__(self, exc_type, exc_value, traceback): + return False + + monkeypatch.setattr(mcp_server_mod, "create_memory_server", lambda *args: server) + monkeypatch.setattr(mcp_server_mod, "stdio_server", lambda: _StdioContext()) + + await mcp_server_mod._run("memory.db", "alice") + + server.run.assert_awaited_once() + close_backend.assert_awaited_once() + + asyncio.run(scenario()) + + def test_memory_mcp_startup_context_reports_dynamic_project_db(tmp_path) -> None: project_dir = tmp_path / "project-a" project_dir.mkdir() From 99f07e7bbdded9dadc70e35ee6ab025279d1aa22 Mon Sep 17 00:00:00 2001 From: Sudhindra Desai Date: Tue, 11 Aug 2026 11:55:24 -0500 Subject: [PATCH 038/138] fix(proxy): cache litellm model resolution to stop repeated Provider List spam MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description The proxy repeatedly prints LiteLLM's `Provider List: https://docs.litellm.ai/docs/providers` banner during normal operation, with no explanation or way to suppress it (#2851). Root cause: `_resolve_litellm_model()` in `headroom/proxy/savings_tracker.py` runs on every savings-tracking update (i.e. every request). For any model LiteLLM can't price (a custom/local/gateway model name — e.g. the reporter's local oMLX setup), the uncached fallback path calls `litellm.cost_per_token(...)` purely to probe resolvability. When that probe fails, LiteLLM prints the banner as an internal side effect before raising, and since the probe was never cached, it re-fires on every single request for the same unresolvable model. **Update:** review flagged that the first version of this fix cached into a plain, unbounded `dict` keyed by the (client-controlled) model name — a memory-retention path on a request-facing proxy, since a caller can grow it without limit by sending a new model string on every request. Replaced with a bounded `functools.lru_cache`; see Changes Made below. Closes #2851 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/proxy/savings_tracker.py`: `_resolve_litellm_model()` is now decorated with `@lru_cache(maxsize=256)` instead of backing onto a hand-rolled unbounded `dict`. An evicted model name simply re-probes LiteLLM on next use — never a correctness issue, only whether the noisy failure banner reruns for that specific name. - `tests/conftest.py`: added a global `autouse` fixture, `_reset_litellm_model_resolution_cache`, that clears the cache before and after every test. It's process-lifetime and module-global, and several existing tests monkeypatch `savings_tracker.litellm` with different behavior per test while reusing common model names like `"gpt-4o"` — without a reset, whichever test resolves a name first silently wins that cache slot for the rest of the run and later tests stop exercising their own fake. - `tests/test_savings_tracker_litellm_resolution_cache.py` (new): regression tests for the three properties that actually matter — repeated resolution of one unknown model only probes LiteLLM once, resolving far more distinct names than the bound never grows the cache past it, and an evicted name is transparently re-probed rather than reusing a slot it no longer owns. - No behavior change for models LiteLLM can already price (fast path via `model_cost` lookup) — only the noisy uncached probe path is memoized, same as before. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) — not run; `mypy` isn't installed in this environment - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ python3 -m pytest tests/test_proxy_savings_history.py tests/test_savings_tracker_zero_price.py \ tests/test_savings_tracker_litellm_resolution_cache.py -q tests/test_proxy_savings_history.py .................................... [ 73%] ... [ 79%] tests/test_savings_tracker_zero_price.py ....... [ 93%] tests/test_savings_tracker_litellm_resolution_cache.py ... [100%] 49 passed, 1 warning in 1.26s # Re-run in reversed file order to check for the exact order-dependence the # review flagged — same 49 passed, no failures either direction: $ python3 -m pytest tests/test_savings_tracker_litellm_resolution_cache.py \ tests/test_savings_tracker_zero_price.py tests/test_proxy_savings_history.py -q 49 passed, 1 warning in 1.11s $ python3 -m ruff check headroom/proxy/savings_tracker.py tests/conftest.py \ tests/test_savings_tracker_litellm_resolution_cache.py All checks passed! ``` ## Real Behavior Proof - Environment: macOS, Python 3.12.3, this repo checked out locally. - What changed since the last review pass: I got the compiled `headroom._core` Rust extension in hand (by installing the published `headroom-ai[all]` wheel into a separate venv and copying its `_core.abi3.so` next to this local source tree — same Python ABI, pure-Python edits in `savings_tracker.py` don't touch the compiled boundary). That unblocked the full test files this fix touches, including `tests/test_proxy_savings_history.py`, which was previously reported as untestable here. - Exact command / steps: three properties asserted directly against the real (now-bounded) cache in `tests/test_savings_tracker_litellm_resolution_cache.py`: 1. Resolve the same unresolvable model 5 times → assert the underlying `litellm.cost_per_token` probe fired exactly once. 2. Resolve `_MODEL_RESOLUTION_CACHE_MAXSIZE + 50` distinct model names → assert `_resolve_litellm_model.cache_info().currsize` stays at exactly `_MODEL_RESOLUTION_CACHE_MAXSIZE` (256), never higher — this is the actual memory-retention fix the review asked for. 3. Resolve one model, push exactly `maxsize` other distinct names through to evict it via LRU, then resolve it again → assert it re-probed (call count went 1 → 2), proving eviction is real and not just an untested cache_info number. - Observed result: all three pass; full affected-file suite (49 tests) passes in both forward and reversed run order, confirming the new `conftest.py` fixture actually fixes the cross-test leakage risk (verified by literally reordering the files, not just by inspection). - Not tested: a live HTTP request against a running `headroom proxy` process specifically re-exercising this bounded-cache commit — the earlier "20 simulated requests" proof against the previous (unbounded-dict) version of this fix was via a standalone script, not a real server; I have not repeated that specific live-server pass against this commit. The unit-level proof above exercises the exact same function (`_resolve_litellm_model`) the real proxy calls per-request from `headroom/proxy/server.py`, so I'm confident it generalizes, but flagging the gap rather than implying I re-ran it live. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas — the bound/eviction rationale is commented above `_resolve_litellm_model`, and the cross-test leakage rationale is commented above the new `conftest.py` fixture - [ ] I have made corresponding changes to the documentation — N/A, internal implementation detail with no user-facing API/doc surface - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes - `mypy` still hasn't been run — not installed in this sandbox, and I didn't want to widen the PR further by installing/configuring it just for this. Flagging rather than silently skipping. - The earlier "Additional Notes" gap about `test_proxy_savings_history.py` being untestable in this environment is resolved (see Real Behavior Proof) — it now runs and passes, including the pre-existing `test_litellm_resolution_and_savings_estimation_fallbacks` test that exercises `_resolve_litellm_model` with a mutated `model_cost` dict across several assertions in one test. - Deliberately did not also bound `headroom/pricing/litellm_pricing.py`'s sibling `_resolved_model_cache` — same shape of cache, arguably the same exposure — since it's outside this PR's diff and touching it wasn't asked for. Flagging in case a maintainer wants it as a fast follow-up rather than silently leaving it unmentioned. --------- Co-authored-by: connectsudhindra-gif Co-authored-by: Claude Sonnet 5 --- headroom/proxy/savings_tracker.py | 24 +++++ tests/conftest.py | 23 +++++ ...avings_tracker_litellm_resolution_cache.py | 88 +++++++++++++++++++ 3 files changed, 135 insertions(+) create mode 100644 tests/test_savings_tracker_litellm_resolution_cache.py diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py index 4b7d82c44..ccffb81c1 100644 --- a/headroom/proxy/savings_tracker.py +++ b/headroom/proxy/savings_tracker.py @@ -16,6 +16,7 @@ import tempfile import threading from csv import DictWriter from datetime import datetime, timedelta, timezone +from functools import lru_cache from io import StringIO from pathlib import Path from typing import Any @@ -164,6 +165,23 @@ def _normalize_model(value: Any) -> str: return cleaned or MODEL_UNKNOWN +# `_resolve_litellm_model` is called on every savings-tracking update (i.e. +# every request), and `model` is client-controlled — it comes straight off +# the request body. For a model LiteLLM can't price (a custom / local / +# gateway name), the uncached fallback below calls `litellm.cost_per_token` +# purely to probe resolvability, which prints LiteLLM's noisy "Provider +# List: https://docs.litellm.ai/docs/providers" banner on every failed probe +# (#2851). Cache the resolution per model name so that probe runs at most +# once per distinct model — bounded, not a plain dict: a request-facing +# proxy must not let a caller grow an unbounded cache for free by sending a +# fresh model string on every request. `maxsize` caps memory; LRU eviction +# means a model that stops being sent eventually falls out and simply +# re-probes if it's ever sent again — never a correctness issue, only +# whether the probe (and its noisy failure banner) reruns. +_MODEL_RESOLUTION_CACHE_MAXSIZE = 256 + + +@lru_cache(maxsize=_MODEL_RESOLUTION_CACHE_MAXSIZE) def _resolve_litellm_model(model: str) -> str: """Resolve model name to one LiteLLM recognizes. @@ -173,6 +191,12 @@ def _resolve_litellm_model(model: str) -> str: "claude-opus" identically to the live /stats path. Uses the shared result only when it maps to a priced model_cost key; otherwise falls through to the bare-prefix logic below. Fail-soft: pricing never breaks bookkeeping. + + Bounded LRU cache, keyed by model name — see + ``_MODEL_RESOLUTION_CACHE_MAXSIZE`` above. Tests that mock the LiteLLM + module across calls with the same model name must call + ``_resolve_litellm_model.cache_clear()`` between cases, or results from + an earlier case leak in. """ litellm = _get_litellm_module() if litellm is None: diff --git a/tests/conftest.py b/tests/conftest.py index 2aecdbc4a..2a75bd260 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -91,6 +91,29 @@ def _reset_copilot_routing_flag(): reset_request_routed_to_copilot() +# `savings_tracker._resolve_litellm_model` is an `lru_cache`d, module-global, +# process-lifetime cache keyed by model name (bounded — see #2860). Many test +# files monkeypatch `savings_tracker.litellm` to a fake with different +# `model_cost`/`cost_per_token` behavior per test, but reuse common model +# names like "gpt-4o" across them. Without a reset, whichever test resolves +# "gpt-4o" first "wins" the cache entry for the rest of the run, and later +# tests silently stop exercising their own fake — a real-not-hypothetical +# order-dependence bug once the cache is process-lifetime instead of per-call. +# Clear before AND after so a test's own within-test resolutions never leak +# in from, or leak out to, a neighboring test either. +@pytest.fixture(autouse=True) +def _reset_litellm_model_resolution_cache(): + try: + from headroom.proxy.savings_tracker import _resolve_litellm_model + except ModuleNotFoundError: + yield + return + + _resolve_litellm_model.cache_clear() + yield + _resolve_litellm_model.cache_clear() + + # ============================================================================= # Global test hooks # ============================================================================= diff --git a/tests/test_savings_tracker_litellm_resolution_cache.py b/tests/test_savings_tracker_litellm_resolution_cache.py new file mode 100644 index 000000000..04300bf12 --- /dev/null +++ b/tests/test_savings_tracker_litellm_resolution_cache.py @@ -0,0 +1,88 @@ +"""Regression: `_resolve_litellm_model`'s cache must be bounded (PR #2860 review). + +A plain unbounded dict cache keyed by a client-controlled model string is a +memory-retention path on a request-facing proxy: a caller can grow it without +limit by sending a new model name on every request. The fix uses a bounded +`functools.lru_cache`. These tests pin the three properties that actually +matter, independent of the litellm pricing behavior covered elsewhere: + +- repeated resolution of the same unresolvable model only probes litellm once +- the cache never grows past its bound, no matter how many distinct model + names get resolved +- an evicted name is transparently re-probed (never silently wrong or stuck) + rather than growing the cache further +""" + +from __future__ import annotations + +import types + +from headroom.proxy import savings_tracker as st + + +def _fake_litellm_always_unresolvable(probe_calls: dict[str, int]) -> types.SimpleNamespace: + """A fake litellm where every model is unpriced and unresolvable. + + `cost_per_token` always raises — exactly what a real custom/local model + litellm has never heard of does — which is the call this cache exists to + memoize (see the comment above `_resolve_litellm_model` in + savings_tracker.py: that raise is also where real litellm prints its + noisy "Provider List" banner, #2851). + """ + + def cost_per_token(*, model, prompt_tokens, completion_tokens): + probe_calls[model] = probe_calls.get(model, 0) + 1 + raise RuntimeError("unknown model") + + return types.SimpleNamespace(model_cost={}, cost_per_token=cost_per_token) + + +def test_resolve_litellm_model_probes_unknown_model_once(monkeypatch): + probe_calls: dict[str, int] = {} + monkeypatch.setattr( + st, "_get_litellm_module", lambda: _fake_litellm_always_unresolvable(probe_calls) + ) + + for _ in range(5): + resolved = st._resolve_litellm_model("widget-local-model") + assert resolved == "widget-local-model" + + assert probe_calls == {"widget-local-model": 1} + + +def test_resolve_litellm_model_cache_is_bounded(monkeypatch): + probe_calls: dict[str, int] = {} + monkeypatch.setattr( + st, "_get_litellm_module", lambda: _fake_litellm_always_unresolvable(probe_calls) + ) + + extra_beyond_bound = 50 + for i in range(st._MODEL_RESOLUTION_CACHE_MAXSIZE + extra_beyond_bound): + st._resolve_litellm_model(f"widget-local-model-{i}") + + info = st._resolve_litellm_model.cache_info() + assert info.maxsize == st._MODEL_RESOLUTION_CACHE_MAXSIZE + # However many distinct names were resolved, the cache itself never + # grows past its bound -- this is the actual memory-retention fix. + assert info.currsize == st._MODEL_RESOLUTION_CACHE_MAXSIZE + + +def test_resolve_litellm_model_evicted_name_reprobes(monkeypatch): + probe_calls: dict[str, int] = {} + monkeypatch.setattr( + st, "_get_litellm_module", lambda: _fake_litellm_always_unresolvable(probe_calls) + ) + + st._resolve_litellm_model("seed-model") + assert probe_calls["seed-model"] == 1 + + # Push exactly `maxsize` new distinct names through without ever touching + # "seed-model" again -- LRU eviction must push it out to make room. + for i in range(st._MODEL_RESOLUTION_CACHE_MAXSIZE): + st._resolve_litellm_model(f"filler-model-{i}") + + # A resolvable name being evicted is not a correctness bug (it just + # re-probes) -- the assertion that matters is that it *does* re-probe + # rather than silently reusing a slot it no longer legitimately owns. + st._resolve_litellm_model("seed-model") + assert probe_calls["seed-model"] == 2 From 07d89a751d603f5cf73b8fd7af0c766a08e65da8 Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Singh <152812718+abhinavkr26104@users.noreply.github.com> Date: Tue, 11 Aug 2026 22:43:10 +0530 Subject: [PATCH 039/138] fix(litellm): close shared cloud client MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Adds an explicit, idempotent async cleanup lifecycle for the LiteLLM callback's shared cloud HTTP client. Fixes #2894 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Added `HeadroomCallback.aclose()` to close the lazily-created `httpx.AsyncClient` and clear its reference. - Made cleanup safe when cloud mode was never used and when shutdown cleanup is invoked more than once. - Added regression coverage for initialized-client cleanup, reference clearing, and repeated/no-op cleanup. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text python -m pytest -q tests/test_integrations/test_litellm_callback.py 5 passed ruff check . All checks passed! ruff format --check . 1382 files already formatted python -m mypy headroom Success: no issues found in 515 source files python -m pytest -q Collection blocked in this Windows environment by 174 errors, primarily missing compiled headroom._core; one unrelated test also lacks respx. ``` ## Real Behavior Proof - Environment: Windows, Python 3.12, loopback HTTP server, real `httpx.AsyncClient`. - Exact command / steps: Started a local HTTP server, configured `HeadroomCallback(api_key="hdr_test", api_url="http://127.0.0.1:")`, ran `_cloud_compress()` against it, saved the created client, awaited `callback.aclose()`, then awaited `callback.aclose()` again. - Observed result: The real cloud request succeeded; the client was open during the request, reported closed after `aclose()`, the callback reference became `None`, and repeated cleanup was harmless. - Who maintains it: Headroom Labs maintains this active upstream repository and its LiteLLM integration. - Install surface: No dependencies or install behavior changed. Cloud mode continues to use the existing optional `httpx` dependency; no native code or runtime network access is introduced by this fix. - Not tested: The complete test suite could not run past collection because the local Windows environment lacks the compiled `headroom._core` extension. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] Documentation changes are not required; `aclose()` is documented in its public docstring and the host owns shutdown sequencing - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes (full suite blocked by missing native extension; targeted tests pass) - [x] I did not edit `CHANGELOG.md` - it is generated by release-please from my Conventional Commit PR title. ## Screenshots (if applicable) Not applicable. ## Additional Notes The callback exposes `aclose()` for the host application's async shutdown lifecycle, matching the existing ASGI integration pattern. --- headroom/integrations/litellm_callback.py | 12 ++++++++ .../test_litellm_callback.py | 28 +++++++++++++++++++ 2 files changed, 40 insertions(+) diff --git a/headroom/integrations/litellm_callback.py b/headroom/integrations/litellm_callback.py index d5d54cacb..c88078069 100644 --- a/headroom/integrations/litellm_callback.py +++ b/headroom/integrations/litellm_callback.py @@ -94,6 +94,18 @@ class HeadroomCallback(_CustomLogger): """Whether cloud compression is enabled.""" return self._api_key is not None + async def aclose(self) -> None: + """Close the shared cloud HTTP client, if it was initialized. + + Applications using LiteLLM should await this method during their async + shutdown lifecycle. It is safe to call when cloud mode was not used or + after the client has already been closed. + """ + client = self._client + self._client = None + if client is not None: + await client.aclose() + async def async_pre_call_hook( self, user_api_key_dict: Any = None, diff --git a/tests/test_integrations/test_litellm_callback.py b/tests/test_integrations/test_litellm_callback.py index 50f698316..ddf71d4da 100644 --- a/tests/test_integrations/test_litellm_callback.py +++ b/tests/test_integrations/test_litellm_callback.py @@ -5,6 +5,7 @@ from __future__ import annotations import importlib import inspect from pathlib import Path +from unittest.mock import AsyncMock, MagicMock import pytest @@ -52,3 +53,30 @@ class TestHeadroomCallbackPostCallSuccessHook: response=sentinel, ) assert result is sentinel + + +class TestHeadroomCallbackClientLifecycle: + """Cloud client cleanup must be explicit and safe to repeat.""" + + @pytest.mark.asyncio + async def test_aclose_closes_and_clears_initialized_client(self) -> None: + cb = HeadroomCallback(api_key="hdr_test") + client = MagicMock() + client.aclose = AsyncMock() + cb._client = client + + await cb.aclose() + + client.aclose.assert_awaited_once_with() + assert cb._client is None + + await cb.aclose() + client.aclose.assert_awaited_once_with() + + @pytest.mark.asyncio + async def test_aclose_without_initialized_client_is_a_noop(self) -> None: + cb = HeadroomCallback(api_key="hdr_test") + + await cb.aclose() + + assert cb._client is None From c85abf7a87920012e01f0a677f6fbd98c4b08de0 Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Singh <152812718+abhinavkr26104@users.noreply.github.com> Date: Wed, 12 Aug 2026 02:55:25 +0530 Subject: [PATCH 040/138] fix(oauth2): make repository lint checks pass ## Description Fixes #2895 The repository-wide Ruff command failed on the bundled OAuth2 plugin. This change sorts the public export list, narrows the optional LiteLLM setup exception handling to expected failures, and replaces the silent HTTP error-body drain with explicit handling and debug logging. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Sorted headroom_oauth2.__all__ according to Ruff RUF022. - Replaced the blind install-time Exception catch with explicit ImportError, AttributeError, OSError, TypeError, and ValueError handling. - Replaced the silent HTTPError body-drain pass with explicit HTTPException, OSError, and ValueError handling plus debug logging. - Added regression coverage for body-drain failures and invalid LiteLLM header state. ## Testing - [x] Unit tests pass - [x] Linting passes (ruff check .) - [x] Type checking passes (mypy headroom) - [x] New tests added - [x] Manual testing performed ### Test Output ruff 0.15.17 ruff check . All checks passed! ruff format --check . 1382 files already formatted python -m mypy headroom Success: no issues found in 515 source files PYTHONPATH=plugins/headroom-oauth2/src python -m pytest -q plugins/headroom-oauth2/tests 39 passed in 11.12s Full Python pytest was attempted: 8,878 tests were collected, but collection stopped with 174 environment errors because the required compiled headroom._core extension is unavailable in this Windows checkout. 18 tests were skipped. ## Real Behavior Proof - Environment: Windows PowerShell, Python 3.12, Ruff 0.15.17. - Exact command / steps: Ran the OAuth2 test suite with PYTHONPATH pointing to plugins/headroom-oauth2/src. Its local HTTPServer fixture exercised real urllib token minting, cached refresh, HTTP error handling, and middleware injection. - Observed result: 39 tests passed, including real loopback token minting and the new failure-path tests; repository-wide Ruff completed with no diagnostics. - Not tested: External identity-provider traffic and the full Python suite after native extension build, because the local Windows toolchain cannot build headroom._core. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of the code - [x] I have commented my code where needed - [ ] I have made corresponding changes to the documentation (not needed; behavior and lint handling are covered by existing comments/tests) - [x] My changes generate no new warnings - [x] I have added tests that prove the fix is effective - [ ] New and existing full-repository unit tests pass locally (blocked by missing native headroom._core) - [x] I did not edit CHANGELOG.md ## Additional Notes No dependencies or public API behavior changed. Expected environment and transport failures remain handled; unexpected programmer errors now propagate instead of being silently swallowed. The OAuth2 plugin remains standard-library-only. --------- Co-authored-by: Tejas Chopra --- .../src/headroom_oauth2/__init__.py | 10 ++++- .../src/headroom_oauth2/provider.py | 5 +-- plugins/headroom-oauth2/tests/test_oauth2.py | 43 +++++++++++++++++++ 3 files changed, 53 insertions(+), 5 deletions(-) diff --git a/plugins/headroom-oauth2/src/headroom_oauth2/__init__.py b/plugins/headroom-oauth2/src/headroom_oauth2/__init__.py index e4ffe31d3..b202caf39 100644 --- a/plugins/headroom-oauth2/src/headroom_oauth2/__init__.py +++ b/plugins/headroom-oauth2/src/headroom_oauth2/__init__.py @@ -13,7 +13,7 @@ from typing import Any from .middleware import OAuth2Middleware from .provider import OAuth2ClientCredentials, OAuth2Error -__all__ = ["install", "OAuth2ClientCredentials", "OAuth2Error", "OAuth2Middleware", "parse_headers"] +__all__ = ["OAuth2ClientCredentials", "OAuth2Error", "OAuth2Middleware", "install", "parse_headers"] __version__ = "0.1.0" log = logging.getLogger("headroom_oauth2") @@ -116,7 +116,13 @@ def install(app: Any, config: Any) -> None: os.environ.update(_before) litellm.headers = {**(getattr(litellm, "headers", None) or {}), **static} log.info("headroom-oauth2: static upstream headers: %s", list(static)) - except Exception as e: # pragma: no cover + except ( + ImportError, + AttributeError, + OSError, + TypeError, + ValueError, + ) as e: # pragma: no cover log.warning("headroom-oauth2: could not set litellm.headers: %s", e) # The litellm backend auths bedrock/vertex/sagemaker from env and ignores a forwarded # bearer, so this extension is a no-op there -- warn loudly rather than silently do nothing. diff --git a/plugins/headroom-oauth2/src/headroom_oauth2/provider.py b/plugins/headroom-oauth2/src/headroom_oauth2/provider.py index dbcf92df6..49f00d996 100644 --- a/plugins/headroom-oauth2/src/headroom_oauth2/provider.py +++ b/plugins/headroom-oauth2/src/headroom_oauth2/provider.py @@ -14,6 +14,7 @@ import threading import time import urllib.parse import urllib.request +from contextlib import suppress from urllib.error import HTTPError, URLError log = logging.getLogger("headroom_oauth2") @@ -128,10 +129,8 @@ class OAuth2ClientCredentials: with urllib.request.urlopen(req, timeout=self.timeout) as resp: payload = json.load(resp) except HTTPError as e: - try: + with suppress(Exception): e.read() # drain; do NOT surface the IdP body (may echo sensitive context) - except Exception: - pass raise OAuth2Error(f"token endpoint returned HTTP {e.code}") from None except (URLError, OSError) as e: raise OAuth2Error(f"token endpoint unreachable: {e}") from None diff --git a/plugins/headroom-oauth2/tests/test_oauth2.py b/plugins/headroom-oauth2/tests/test_oauth2.py index 5372cb599..4a8b03d35 100644 --- a/plugins/headroom-oauth2/tests/test_oauth2.py +++ b/plugins/headroom-oauth2/tests/test_oauth2.py @@ -1,9 +1,11 @@ import asyncio import base64 import json +import logging import threading import time from http.server import BaseHTTPRequestHandler, HTTPServer +from urllib.error import HTTPError import pytest @@ -161,6 +163,26 @@ def test_error_on_bad_status_hides_body(idp): assert "SENSITIVE" not in str(ei.value) # IdP error body must not leak into the exception +def test_error_body_drain_failure_is_sanitized(monkeypatch, caplog): + class _UnreadableHTTPError(HTTPError): + def read(self): + raise RuntimeError("SENSITIVE") + + def fail(*_args, **_kwargs): + raise _UnreadableHTTPError("https://idp.example/token", 503, "unavailable", {}, None) + + monkeypatch.setattr("urllib.request.urlopen", fail) + caplog.set_level(logging.DEBUG, logger="headroom_oauth2") + p = OAuth2ClientCredentials( + token_url="https://idp.example/token", client_id="c", client_secret="s" + ) + + with pytest.raises(OAuth2Error, match="HTTP 503") as exc_info: + p.token() + assert "SENSITIVE" not in str(exc_info.value) + assert "SENSITIVE" not in caplog.text + + def test_malformed_200_no_token(idp): _IdP.tok = None # HTTP 200 but no access_token field p = OAuth2ClientCredentials(token_url=idp, client_id="c", client_secret="s") @@ -492,3 +514,24 @@ def test_install_sets_static_headers(monkeypatch): install(App(), _cfg("litellm-openai")) assert fake.headers == {"X-App": "demo"} # valid header set on litellm; malformed key dropped + + +def test_install_handles_invalid_litellm_headers(monkeypatch, caplog): + import sys + import types + + fake = types.ModuleType("litellm") + fake.headers = object() + monkeypatch.setitem(sys.modules, "litellm", fake) + monkeypatch.setenv("HEADROOM_OAUTH2_TOKEN_URL", "https://idp.example.com/token") + monkeypatch.setenv("HEADROOM_OAUTH2_CLIENT_ID", "c") + monkeypatch.setenv("HEADROOM_OAUTH2_CLIENT_SECRET", "s") + monkeypatch.setenv("HEADROOM_OAUTH2_HEADERS", "X-App=demo") + caplog.set_level(logging.WARNING, logger="headroom_oauth2") + + class App: + def add_middleware(self, *a, **k): + pass + + install(App(), _cfg("litellm-openai")) + assert "could not set litellm.headers" in caplog.text From e044139001680fd5198147bf373df6f00db32cc7 Mon Sep 17 00:00:00 2001 From: Suliman Abdulrazzaq <144490671+SulimanAbdulrazzaq@users.noreply.github.com> Date: Wed, 12 Aug 2026 00:25:29 +0300 Subject: [PATCH 041/138] fix(install): trust Docker bridge for dashboard metadata ## Summary Closes #2909. The `persistent-docker` installer now discovers Docker's default bridge gateway and passes the exact `/32` gateway CIDR to the proxy's dashboard metadata allowlist when no explicit `HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` value is configured. This keeps the existing metadata gate intact while allowing the first-party loopback-published container to see its own Recent Requests and Per-Project Savings data. Explicit user configuration continues to take precedence. Both native wrappers (POSIX and PowerShell) use the same behavior, and installer integration coverage verifies the generated Docker command. ## Validation - `python -m pytest tests/test_install/test_native_installers.py -q -k bash` (1 skipped on Windows because Bash is unavailable) - PowerShell wrapper smoke test with the repository fake Docker shim: verified `docker network inspect bridge` is called and `HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32` is passed to `docker run` - Explicit allowlist smoke test: verified an existing `HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` is preserved without adding a discovered default - `git diff --check` ## Real behavior proof Setup tested: Windows 11 host, PowerShell wrapper, repository fake Docker shim (Docker CLI is not installed in this environment). Exact command: `headroom.ps1 install apply --profile smoke --port 18999 --image fake/headroom:test`. Observed result: the generated Docker invocation included `docker network inspect bridge --format ...` and `--env HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32`, and the installer completed successfully. Not tested: a live Docker daemon/dashboard request on this host. --------- Co-authored-by: Tejas Chopra --- scripts/install.ps1 | 26 +++- scripts/install.sh | 26 +++- tests/test_install/test_native_installers.py | 121 ++++++++++++++++++- 3 files changed, 170 insertions(+), 3 deletions(-) diff --git a/scripts/install.ps1 b/scripts/install.ps1 index e8abb7378..e95ddfa14 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -346,6 +346,29 @@ function Get-PersistentDockerArgs { return ,$args.ToArray() } +function Add-DashboardGatewayEnv { + param([System.Collections.Generic.List[string]]$ArgsList) + + # This default is safe only because the published dashboard port is bound + # to the host loopback interface below. A host request published through + # Docker's default bridge reaches the + # container from the bridge gateway (for example, 172.17.0.1), not from + # 127.0.0.1. Trust only that exact gateway by default so the dashboard's + # metadata gate works for the first-party persistent Docker preset while + # preserving an explicitly configured allowlist. + if (Test-Path Env:HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS) { + return + } + + $gateway = (& docker network inspect bridge --format '{{(index .IPAM.Config 0).Gateway}}' 2>$null | Out-String).Trim() + if ($LASTEXITCODE -eq 0 -and $gateway) { + $ArgsList.Add('--env') + $ArgsList.Add("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=$gateway/32") + } else { + Write-Warning 'Could not determine Docker bridge gateway; dashboard metadata remains restricted' + } +} + function Get-ManifestProxyArgs { param( [int]$Port, @@ -492,8 +515,9 @@ function Start-PersistentDockerInstall { docker rm -f $containerName | Out-Null 2>$null $dockerArgs = New-Object System.Collections.Generic.List[string] - $dockerArgs.AddRange([string[]]@('run','-d','--restart','unless-stopped','--name',$containerName,'-p',"$Port`:$Port")) + $dockerArgs.AddRange([string[]]@('run','-d','--restart','unless-stopped','--name',$containerName,'-p',"127.0.0.1`:$Port`:$Port")) $dockerArgs.AddRange((Get-PersistentDockerArgs)) + Add-DashboardGatewayEnv -ArgsList $dockerArgs $dockerArgs.AddRange([string[]]@( '--env',"HEADROOM_DEPLOYMENT_PROFILE=$Profile", '--env','HEADROOM_DEPLOYMENT_PRESET=persistent-docker', diff --git a/scripts/install.sh b/scripts/install.sh index cfd2259df..d65a6db59 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -292,6 +292,29 @@ append_persistent_container_args() { append_passthrough_envs "$1" } +append_dashboard_gateway_env() { + local -n ref=$1 + + # This default is safe only because the published dashboard port is bound + # to the host loopback interface below. A host request published through + # Docker's default bridge reaches the + # container from the bridge gateway (for example, 172.17.0.1), not from + # 127.0.0.1. Trust only that exact gateway by default so the dashboard's + # metadata gate works for the first-party persistent Docker preset while + # preserving an explicitly configured allowlist. + if [[ -n "${HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS+x}" ]]; then + return + fi + + local gateway + gateway="$(docker network inspect bridge --format '{{(index .IPAM.Config 0).Gateway}}' 2>/dev/null || true)" + if [[ -n "${gateway}" ]]; then + ref+=(--env "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=${gateway}/32") + else + warn "Could not determine Docker bridge gateway; dashboard metadata remains restricted" + fi +} + build_manifest_proxy_args() { local -n out_args=$1 local port="$2" @@ -466,8 +489,9 @@ start_persistent_docker_install() { docker rm -f "${container_name}" >/dev/null 2>&1 || true - args=(docker run -d --restart unless-stopped --name "${container_name}" -p "${port}:${port}") + args=(docker run -d --restart unless-stopped --name "${container_name}" -p "127.0.0.1:${port}:${port}") append_persistent_container_args args + append_dashboard_gateway_env args args+=( --env "HEADROOM_DEPLOYMENT_PROFILE=${profile}" --env "HEADROOM_DEPLOYMENT_PRESET=persistent-docker" diff --git a/tests/test_install/test_native_installers.py b/tests/test_install/test_native_installers.py index bbad56621..94fee0ba9 100644 --- a/tests/test_install/test_native_installers.py +++ b/tests/test_install/test_native_installers.py @@ -105,6 +105,16 @@ def main() -> int: if command == "pull": return 0 + if command == "network" and len(args) > 1 and args[1] == "inspect": + # Match the default bridge gateway used by the native installer when + # it configures the dashboard metadata allowlist. + gateway = os.environ.get("FAKE_DOCKER_GATEWAY", "172.17.0.1") + if gateway == "FAIL": + return 1 + if "--format" in args and gateway: + print(gateway) + return 0 + if command == "run": detached = "-d" in args if not detached: @@ -112,17 +122,29 @@ def main() -> int: name = None publish = None + container_env = {} for index, arg in enumerate(args): if arg == "--name": name = args[index + 1] elif arg == "-p": publish = args[index + 1] + elif arg == "--env": + spec = args[index + 1] + if "=" in spec: + env_name, value = spec.split("=", 1) + container_env[env_name] = value + elif spec in os.environ: + container_env[spec] = os.environ[spec] if name is None or publish is None: raise SystemExit("missing --name or -p in fake docker run") port = host_port_from_publish(publish) - state["containers"][name] = {"pid": start_server(port), "port": port} + state["containers"][name] = { + "pid": start_server(port), + "port": port, + "env": container_env, + } save_state(state) print(name) return 0 @@ -225,6 +247,84 @@ def _read_fake_docker_log(env: dict[str, str]) -> list[list[str]]: return [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines() if line] +def _persistent_run_call(env: dict[str, str], profile: str) -> list[str]: + container_name = f"headroom-{profile}" + return next( + call + for call in _read_fake_docker_log(env) + if call[:2] == ["run", "-d"] + and "--name" in call + and call[call.index("--name") + 1] == container_name + ) + + +def _persistent_container_env(env: dict[str, str], profile: str) -> dict[str, str]: + state = json.loads(Path(env["FAKE_DOCKER_STATE"]).read_text(encoding="utf-8")) + return state["containers"][f"headroom-{profile}"]["env"] + + +def _exercise_dashboard_gateway_overrides(wrapper_command: list[str], env: dict[str, str]) -> None: + trusted_cidrs = "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS" + + try: + for profile, configured_value in (("configured", "10.20.0.0/16"), ("empty", "")): + env[trusted_cidrs] = configured_value + port = _free_port() + _run( + [ + *wrapper_command, + "install", + "apply", + "--profile", + profile, + "--port", + str(port), + "--image", + "fake/headroom:test", + ], + env=env, + ) + + install_call = _persistent_run_call(env, profile) + assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}" + # Docker's name-only --env form preserves the caller's value, + # including an explicitly empty value, instead of installing the + # discovered bridge gateway default. + assert trusted_cidrs in install_call + assert not any(arg.startswith(f"{trusted_cidrs}=") for arg in install_call) + assert _persistent_container_env(env, profile)[trusted_cidrs] == configured_value + _run([*wrapper_command, "install", "remove", "--profile", profile], env=env) + + env.pop(trusted_cidrs, None) + env["FAKE_DOCKER_GATEWAY"] = "FAIL" + port = _free_port() + result = _run( + [ + *wrapper_command, + "install", + "apply", + "--profile", + "no-gateway", + "--port", + str(port), + "--image", + "fake/headroom:test", + ], + env=env, + ) + install_call = _persistent_run_call(env, "no-gateway") + assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}" + assert not any( + arg == trusted_cidrs or arg.startswith(f"{trusted_cidrs}=") for arg in install_call + ) + assert trusted_cidrs not in _persistent_container_env(env, "no-gateway") + assert "dashboard metadata remains restricted" in (result.stdout + result.stderr) + _run([*wrapper_command, "install", "remove", "--profile", "no-gateway"], env=env) + finally: + env.pop(trusted_cidrs, None) + env.pop("FAKE_DOCKER_GATEWAY", None) + + def _run( command: list[str], *, @@ -402,11 +502,19 @@ def test_bash_native_installer_supports_persistent_docker_lifecycle(tmp_path: Pa install_call = next( call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call ) + assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}" assert "/tmp/headroom-home/.headroom/memory.db" in install_call # Canonical filesystem contract env vars (issue #175) forwarded into # the container so the proxy resolves state/config to the bind mount. assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in install_call assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in install_call + assert "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32" in install_call + assert ( + _persistent_container_env(env, "smoke")["HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS"] + == "172.17.0.1/32" + ) + + _exercise_dashboard_gateway_overrides([str(wrapper)], env) status_result = _run( [str(wrapper), "install", "status", "--profile", "smoke"], @@ -654,10 +762,21 @@ def test_powershell_native_installer_supports_persistent_docker_lifecycle(tmp_pa install_call = next( call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call ) + assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}" assert "/tmp/headroom-home/.headroom/memory.db" in install_call # Canonical filesystem contract env vars (issue #175). assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in install_call assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in install_call + assert "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32" in install_call + assert ( + _persistent_container_env(env, "smoke")["HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS"] + == "172.17.0.1/32" + ) + + _exercise_dashboard_gateway_overrides( + [powershell, "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(wrapper)], + env, + ) status_result = _run( [ From 65961827cf5e90d7b4e7026feb89aac000a73ea3 Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Singh <152812718+abhinavkr26104@users.noreply.github.com> Date: Wed, 12 Aug 2026 02:55:32 +0530 Subject: [PATCH 042/138] fix(memory): close DirectMem0 resources MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `DirectMem0Adapter.close()` now deterministically drains or cancels background writes and releases every initialized client/driver. Fixes #2897 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Initialize the OpenAI client field to `None` so cleanup is safe before or after initialization. - Drain background tasks within a configurable 60-second default, cancel tasks that exceed the timeout, await cancellation, and retain completed/cancelled task status. - Close Mem0, OpenAI, Qdrant, Neo4j, embedder, and graph resources independently, including async close methods, while continuing cleanup if one resource fails. - Clear task and client references and keep `close()` idempotent. - Add regression tests for task draining, timeout cancellation, all resource cleanup, and repeated close calls. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text python -m pytest -q tests/test_memory/test_direct_mem0.py tests/test_memory/test_qdrant_env.py 52 passed ruff check . All checks passed! ruff format --check . 1383 files already formatted python -m mypy headroom Success: no issues found in 515 source files python -m pytest -q Collection blocked in this Windows environment by 174 errors, primarily missing compiled headroom._core; 18 tests skipped. ``` ## Real Behavior Proof - Environment: Windows, Python 3.12, local DirectMem0Adapter instance using real `httpx.Client` resources. - Exact command / steps: Assigned real `httpx.Client()` instances to the adapter's OpenAI and Qdrant resource slots, registered an asynchronous background task, awaited `adapter.close(timeout=1.0)`, then checked both clients' `is_closed` state and the task status. - Observed result: `real httpx clients closed and background task drained`; both clients reported closed, no pending task IDs remained, and the task status was `completed`. - Who maintains it: Headroom Labs maintains this active upstream repository and memory backend. - Install surface: No dependencies or install behavior changed. The fix uses the standard-library asyncio/inspect modules and existing resource close methods; no native code or runtime network access is introduced. - Not tested: The complete test suite could not run past collection because this Windows environment lacks the compiled `headroom._core` extension. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes (full suite blocked by missing native extension; targeted tests pass) - [x] I did not edit `CHANGELOG.md` - it is generated by release-please from my Conventional Commit PR title. ## Screenshots (if applicable) Not applicable. ## Additional Notes The default close timeout is 60 seconds and can be overridden by callers that need a shorter shutdown budget. --------- Co-authored-by: Tejas Chopra --- headroom/memory/backends/direct_mem0.py | 82 ++++++++++- tests/test_memory/test_direct_mem0.py | 184 ++++++++++++++++++++++++ 2 files changed, 259 insertions(+), 7 deletions(-) create mode 100644 tests/test_memory/test_direct_mem0.py diff --git a/headroom/memory/backends/direct_mem0.py b/headroom/memory/backends/direct_mem0.py index c086ef012..20c454620 100644 --- a/headroom/memory/backends/direct_mem0.py +++ b/headroom/memory/backends/direct_mem0.py @@ -49,6 +49,7 @@ from __future__ import annotations import asyncio import hashlib +import inspect import logging import uuid from dataclasses import dataclass, field @@ -150,6 +151,7 @@ class DirectMem0Adapter: """ self._config = config or Mem0Config() self._mem0_client: Any = None + self._openai_client: Any = None self._embedder: Any = None self._neo4j_graph: Any = None self._neo4j_driver: Any = None @@ -159,6 +161,7 @@ class DirectMem0Adapter: # Background task tracking self._background_tasks: dict[str, asyncio.Task] = {} self._task_results: dict[str, dict[str, Any]] = {} + self._close_lock = asyncio.Lock() async def _ensure_initialized(self) -> None: """Ensure all clients are initialized.""" @@ -389,7 +392,10 @@ class DirectMem0Adapter: task = self._background_tasks[task_id] try: - await asyncio.wait_for(task, timeout=timeout) + # A timeout must not cancel a save that may be awaiting + # ``asyncio.to_thread``. Cancelling the asyncio task does not stop + # the underlying worker, and would hide that worker from close(). + await asyncio.wait_for(asyncio.shield(task), timeout=timeout) return self.get_task_status(task_id) except asyncio.TimeoutError: return {"status": "timeout", "task_id": task_id} @@ -949,9 +955,71 @@ class DirectMem0Adapter: """Whether this backend supports vector search.""" return True - async def close(self) -> None: - """Close connections and release resources.""" - if self._neo4j_driver: - self._neo4j_driver.close() - self._mem0_client = None - self._initialized = False + async def close(self, timeout: float = 60.0) -> None: + """Drain background writes and close all initialized resources. + + Args: + timeout: Maximum seconds to wait for background writes to finish. + + Raises: + TimeoutError: If background writes have not quiesced within + ``timeout``. Tasks remain tracked and resources remain open so + callers can retry after the writes finish. + """ + # Concurrent shutdown callers must observe one lifecycle transition. + # In particular, a second caller must not detach resources while the + # first is still waiting for executor-backed writes to quiesce. + async with self._close_lock: + if self._background_tasks: + task_items = list(self._background_tasks.items()) + tasks = [task for _, task in task_items] + _, pending = await asyncio.wait(tasks, timeout=timeout) + + if pending: + pending_ids = [task_id for task_id, task in task_items if task in pending] + raise TimeoutError( + "Timed out waiting for DirectMem0 background writes: " + + ", ".join(pending_ids) + ) + + for task_id, task in task_items: + try: + self._task_results[task_id] = { + "status": "completed", + "result": task.result(), + } + except Exception as e: + self._task_results[task_id] = { + "status": "failed", + "error": str(e), + } + self._background_tasks.clear() + + resources = [ + ("Mem0 client", self._mem0_client), + ("OpenAI client", self._openai_client), + ("Qdrant client", self._qdrant_client), + ("Neo4j driver", self._neo4j_driver), + ("embedder", self._embedder), + ("Neo4j graph", self._neo4j_graph), + ] + self._mem0_client = None + self._openai_client = None + self._qdrant_client = None + self._neo4j_driver = None + self._embedder = None + self._neo4j_graph = None + self._initialized = False + + for name, resource in resources: + if resource is None: + continue + close = getattr(resource, "close", None) or getattr(resource, "aclose", None) + if close is None: + continue + try: + result = close() + if inspect.isawaitable(result): + await result + except Exception as e: + logger.warning("Failed to close %s: %s", name, e) diff --git a/tests/test_memory/test_direct_mem0.py b/tests/test_memory/test_direct_mem0.py new file mode 100644 index 000000000..2a00e229a --- /dev/null +++ b/tests/test_memory/test_direct_mem0.py @@ -0,0 +1,184 @@ +"""Tests for the Direct Mem0 adapter lifecycle.""" + +from __future__ import annotations + +import asyncio +import threading +from unittest.mock import AsyncMock, MagicMock + +import pytest + +from headroom.memory.backends.direct_mem0 import DirectMem0Adapter, Mem0Config + + +def _adapter() -> DirectMem0Adapter: + return DirectMem0Adapter(Mem0Config(enable_graph=True)) + + +@pytest.mark.asyncio +async def test_close_drains_tasks_and_closes_initialized_resources() -> None: + adapter = _adapter() + resources = { + "_mem0_client": MagicMock(), + "_openai_client": MagicMock(), + "_qdrant_client": MagicMock(), + "_neo4j_driver": MagicMock(), + } + resources["_mem0_client"].close = AsyncMock() + for name, resource in resources.items(): + setattr(adapter, name, resource) + + task = asyncio.create_task(asyncio.sleep(0, result="saved")) + adapter._background_tasks["task_1"] = task + + await adapter.close(timeout=1.0) + + assert adapter.get_pending_tasks() == [] + assert adapter.get_task_status("task_1") == { + "status": "completed", + "result": "saved", + } + resources["_mem0_client"].close.assert_awaited_once_with() + for resource in resources.values(): + resource.close.assert_called_once_with() + assert adapter._initialized is False + assert adapter._mem0_client is None + assert adapter._openai_client is None + assert adapter._qdrant_client is None + assert adapter._neo4j_driver is None + + await adapter.close(timeout=0.01) + resources["_mem0_client"].close.assert_awaited_once_with() + for resource in resources.values(): + resource.close.assert_called_once_with() + + +@pytest.mark.asyncio +async def test_close_timeout_keeps_tasks_and_resources_attached() -> None: + adapter = _adapter() + release = asyncio.Event() + resource = MagicMock() + adapter._mem0_client = resource + task = asyncio.create_task(release.wait()) + adapter._background_tasks["task_1"] = task + await asyncio.sleep(0) + + with pytest.raises(TimeoutError, match="task_1"): + await adapter.close(timeout=0.01) + + assert not task.done() + assert adapter.get_pending_tasks() == ["task_1"] + assert adapter._mem0_client is resource + resource.close.assert_not_called() + + release.set() + await adapter.close(timeout=1.0) + + assert adapter.get_pending_tasks() == [] + assert adapter.get_task_status("task_1") == { + "status": "completed", + "result": True, + } + resource.close.assert_called_once_with() + + +@pytest.mark.asyncio +async def test_close_does_not_close_resources_while_sync_worker_is_running() -> None: + adapter = _adapter() + worker_started = threading.Event() + release_worker = threading.Event() + + class BlockingMem0Client: + def __init__(self) -> None: + self.close_calls = 0 + + def add(self, *_args: object, **_kwargs: object) -> dict[str, list[dict[str, str]]]: + worker_started.set() + assert release_worker.wait(timeout=5.0), "test did not release worker" + return {"results": [{"id": "memory-1", "memory": "saved"}]} + + def close(self) -> None: + self.close_calls += 1 + + client = BlockingMem0Client() + adapter._mem0_client = client + adapter._initialized = True + + memory = await adapter.save_memory( + content="saved", + user_id="user-1", + importance=0.5, + background=True, + ) + task_id = memory.metadata["_task_id"] + + for _ in range(100): + if worker_started.is_set(): + break + await asyncio.sleep(0.01) + assert worker_started.is_set() + + with pytest.raises(TimeoutError, match=task_id): + await adapter.close(timeout=0.01) + + assert client.close_calls == 0 + assert adapter._mem0_client is client + assert adapter.get_pending_tasks() == [task_id] + + release_worker.set() + await adapter.close(timeout=1.0) + + assert client.close_calls == 1 + assert adapter._mem0_client is None + assert adapter.get_pending_tasks() == [] + assert adapter.get_task_status(task_id)["status"] == "completed" + + +@pytest.mark.asyncio +async def test_concurrent_close_calls_serialize_resource_cleanup() -> None: + adapter = _adapter() + close_started = asyncio.Event() + release_close = asyncio.Event() + resource = MagicMock() + + async def slow_close() -> None: + close_started.set() + await release_close.wait() + + resource.close = AsyncMock(side_effect=slow_close) + adapter._mem0_client = resource + + first = asyncio.create_task(adapter.close()) + await close_started.wait() + second = asyncio.create_task(adapter.close()) + await asyncio.sleep(0) + + resource.close.assert_awaited_once_with() + assert not first.done() + assert not second.done() + + release_close.set() + await asyncio.gather(first, second) + + resource.close.assert_awaited_once_with() + + +@pytest.mark.asyncio +async def test_wait_for_task_timeout_does_not_cancel_background_write() -> None: + adapter = _adapter() + release = asyncio.Event() + task = asyncio.create_task(release.wait()) + adapter._background_tasks["task_1"] = task + + assert await adapter.wait_for_task("task_1", timeout=0.01) == { + "status": "timeout", + "task_id": "task_1", + } + assert not task.done() + assert adapter.get_pending_tasks() == ["task_1"] + + release.set() + assert await adapter.wait_for_task("task_1", timeout=1.0) == { + "status": "completed", + "result": True, + } From fd4628d82156c65d4fa22df9513315790a6cd2fb Mon Sep 17 00:00:00 2001 From: Radhakrishnan Pachyappan Date: Wed, 12 Aug 2026 02:55:36 +0530 Subject: [PATCH 043/138] fix(memory): sync FTS5 and vector indexes on CLI delete/edit/prune/purge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problem `headroom memory delete`, `prune`, `edit`, and `purge` all operate on the bare `SQLiteMemoryStore` — they update the primary `memories` table but never touch the FTS5 full-text index (`memory_fts` in `memory.db`) or the vector index (`vec_metadata` / `vec_embeddings` in `memory_vectors.db`). The index maintenance path lives in `HierarchicalMemory.delete()` / `.update()`, which the CLI never instantiates. **Symptoms (from #2856):** ```sql -- After deleting 16 of 46 memories via CLI: SELECT COUNT(*) FROM memories; -- 30 SELECT COUNT(*) FROM memory_fts; -- 46 ← orphans -- memory_vectors.db SELECT COUNT(*) FROM vec_metadata; -- 46 ← orphans ``` Deleted memories keep surfacing in `memory_search` results even after a full server restart, because server startup only re-embeds memories whose `embedding IS NULL` — it never removes orphaned index entries. Fixes #2856. ## Solution Add two best-effort helpers to `headroom/cli/memory.py` that use **direct SQLite** (no `sqlite-vec` extension, no embedder): - **`_remove_from_search_indexes(db_path, memory_ids)`**: removes specific IDs from `memory_fts` and from `vec_metadata` / `vec_embeddings`. Skips silently if an index doesn't exist. - **`_clear_all_search_indexes(db_path)`**: truncates both indexes completely (for purge). Wire these up in four commands: | Command | Change | |---|---| | `delete` | `_remove_from_search_indexes` after `store.delete_batch()` | | `prune` | `_remove_from_search_indexes` after `store.delete_batch()` | | `purge` | `_clear_all_search_indexes` after `store.clear_all()` | | `edit` | If content changed: remove stale entries, clear `embedding` (server re-embeds on next startup), re-add FTS5 entry with new content immediately | The edit path re-adds the FTS5 entry right away so keyword search reflects the new content without requiring a server restart. Vector search is deferred to the next startup re-embed cycle (same as what the server already does for missing embeddings). ## Changes - `headroom/cli/memory.py` — two new helpers; four command call sites - `tests/test_cli_memory_index_sync.py` (new) — 9 unit tests covering both helpers with FTS5 and a stub vector DB. No `sqlite-vec` or embedder required; tests run locally. ## Testing ``` $ python -m pytest tests/test_cli_memory_index_sync.py -v ... 9 passed in 2.38s ``` --------- Signed-off-by: Radhakrishnan Pachyappan Signed-off-by: Radhakrishnan Pachyappan Co-authored-by: Tejas Chopra --- headroom/cli/memory.py | 332 +++++++++++++++++- tests/test_cli_memory_index_sync.py | 508 ++++++++++++++++++++++++++++ 2 files changed, 837 insertions(+), 3 deletions(-) create mode 100644 tests/test_cli_memory_index_sync.py diff --git a/headroom/cli/memory.py b/headroom/cli/memory.py index 51a1fd1f9..9a930233a 100644 --- a/headroom/cli/memory.py +++ b/headroom/cli/memory.py @@ -30,6 +30,8 @@ from ._utils.formatting import ( from ._utils.parsers import parse_duration from .main import main +_REINDEX_PAGE_SIZE = 1_000 + def _default_db_path() -> str: """Resolve the memory DB the proxy/install actually use. @@ -66,6 +68,148 @@ def get_store(db_path: str) -> SQLiteMemoryStore: return SQLiteMemoryStore(db_path) +def _sqlite_table_exists(conn: Any, table_name: str) -> bool: + """Return whether a SQLite table or virtual table has been initialized.""" + row = conn.execute( + "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", + (table_name,), + ).fetchone() + return row is not None + + +def _remove_from_search_indexes(db_path: str, memory_ids: list[str]) -> bool: + """Remove specific memories from FTS5 and vector search indexes. + + FTS5 cleanup uses a bare sqlite3 connection (FTS5 is built-in). + Vector cleanup requires sqlite-vec to load the vec0 virtual-table + module; when not installed a warning is printed. + + Returns True when both indexes were fully synced, False when any part + of the sync failed. Callers must treat False as a partial failure and + surface it — typically by exiting with a non-zero code so the primary + store mutation is not silently reported as fully successful. + """ + if not memory_ids: + return True + + import sqlite3 + + db = Path(db_path) + ok = True + + # FTS5 table lives in the same memory.db file (built-in, no extension needed). + try: + with sqlite3.connect(str(db)) as conn: + if _sqlite_table_exists(conn, "memory_fts"): + for i in range(0, len(memory_ids), 500): + chunk = memory_ids[i : i + 500] + placeholders = ",".join("?" * len(chunk)) + conn.execute( + f"DELETE FROM memory_fts WHERE memory_id IN ({placeholders})", + chunk, + ) + conn.commit() + except Exception as exc: + print_warning(f"FTS5 index cleanup incomplete: {exc}") + ok = False + + # Vector DB is a sibling file: memory.db -> memory_vectors.db. + # vec_embeddings is a vec0 virtual table — the sqlite-vec extension must be + # loaded on every connection before touching it. + vector_db = db.parent / f"{db.stem}_vectors.db" + if not vector_db.exists(): + return ok + + try: + with sqlite3.connect(str(vector_db)) as conn: + # A sibling database may exist before the optional vector index has + # ever been initialized. That is a valid no-op, not a sync failure. + if not _sqlite_table_exists(conn, "vec_metadata"): + return ok + + try: + import sqlite_vec + except ImportError: + print_warning( + "sqlite-vec is not installed; stale vector index entries may remain. " + "Run 'headroom memory reindex' after installing sqlite-vec to repair." + ) + return False + + conn.enable_load_extension(True) + sqlite_vec.load(conn) + conn.enable_load_extension(False) + for i in range(0, len(memory_ids), 500): + chunk = memory_ids[i : i + 500] + placeholders = ",".join("?" * len(chunk)) + rows = conn.execute( + f"SELECT rowid FROM vec_metadata WHERE memory_id IN ({placeholders})", + chunk, + ).fetchall() + rowids = [r[0] for r in rows] + if rowids: + rph = ",".join("?" * len(rowids)) + conn.execute(f"DELETE FROM vec_embeddings WHERE rowid IN ({rph})", rowids) + conn.execute(f"DELETE FROM vec_metadata WHERE rowid IN ({rph})", rowids) + conn.commit() + except Exception as exc: + print_warning(f"Vector index cleanup incomplete: {exc}") + ok = False + + return ok + + +def _clear_all_search_indexes(db_path: str) -> bool: + """Truncate both search indexes after a full purge. + + Same extension-loading requirement as :func:`_remove_from_search_indexes`. + Returns True on full success, False on any partial failure. + """ + import sqlite3 + + db = Path(db_path) + ok = True + + try: + with sqlite3.connect(str(db)) as conn: + if _sqlite_table_exists(conn, "memory_fts"): + conn.execute("DELETE FROM memory_fts") + conn.commit() + except Exception as exc: + print_warning(f"FTS5 index cleanup incomplete: {exc}") + ok = False + + vector_db = db.parent / f"{db.stem}_vectors.db" + if not vector_db.exists(): + return ok + + try: + with sqlite3.connect(str(vector_db)) as conn: + if not _sqlite_table_exists(conn, "vec_metadata"): + return ok + + try: + import sqlite_vec + except ImportError: + print_warning( + "sqlite-vec is not installed; stale vector index entries may remain. " + "Run 'headroom memory reindex' after installing sqlite-vec to repair." + ) + return False + + conn.enable_load_extension(True) + sqlite_vec.load(conn) + conn.enable_load_extension(False) + conn.execute("DELETE FROM vec_embeddings") + conn.execute("DELETE FROM vec_metadata") + conn.commit() + except Exception as exc: + print_warning(f"Vector index cleanup incomplete: {exc}") + ok = False + + return ok + + def _resolve_memory(store: SQLiteMemoryStore, memory_id: str) -> Memory: """Resolve an exact or unambiguous partial memory ID.""" memory = asyncio.run(store.get(memory_id)) @@ -620,13 +764,37 @@ def edit_memory( mem = matches[0] # Update fields + content_changed = content is not None and content != mem.content if content is not None: mem.content = content if importance is not None: mem.importance = importance + index_ok = True + if content_changed: + # Clear the stale embedding so the memory MCP server re-embeds on + # next startup. Also remove the old FTS5 and vector index entries + # now to avoid serving stale search results until then. + mem.embedding = None + index_ok = _remove_from_search_indexes(db_path, [mem.id]) + # Re-index FTS5 immediately with new content (no embedder needed). + try: + from ..memory.adapters.fts5 import FTS5TextIndex + + fts = FTS5TextIndex(db_path=db_path) + asyncio.run(fts.index_memory(mem)) + except Exception as exc: + print_warning(f"FTS5 re-index incomplete: {exc}") + index_ok = False + # Save asyncio.run(store.save(mem)) + if not index_ok: + print_warning( + f"Updated memory {mem.id[:8]}, but search index sync incomplete. " + "Run 'headroom memory reindex' to repair." + ) + sys.exit(1) print_success(f"Updated memory {mem.id[:8]}") except Exception as e: @@ -775,7 +943,14 @@ def delete_memories( # Delete deleted = asyncio.run(store.delete_batch(resolved_ids)) - print_success(f"Deleted {deleted} memory(ies).") + if _remove_from_search_indexes(db_path, resolved_ids): + print_success(f"Deleted {deleted} memory(ies).") + else: + print_warning( + f"Deleted {deleted} memory(ies) from store, but search index sync " + "incomplete. Run 'headroom memory reindex' to repair." + ) + sys.exit(1) except click.Abort: click.echo("Aborted.") @@ -897,7 +1072,14 @@ def prune_memories( # Delete ids_to_delete = [m.id for m in memories] deleted = asyncio.run(store.delete_batch(ids_to_delete)) - print_success(f"Deleted {deleted} memory(ies).") + if _remove_from_search_indexes(db_path, ids_to_delete): + print_success(f"Deleted {deleted} memory(ies).") + else: + print_warning( + f"Deleted {deleted} memory(ies) from store, but search index sync " + "incomplete. Run 'headroom memory reindex' to repair." + ) + sys.exit(1) except click.BadParameter as e: print_error(str(e)) @@ -952,7 +1134,14 @@ def purge_memories(ctx: click.Context, db_path: str, confirm_flag: bool) -> None # Purge deleted = asyncio.run(store.clear_all()) - print_success(f"Purged {deleted} memory(ies).") + if _clear_all_search_indexes(db_path): + print_success(f"Purged {deleted} memory(ies).") + else: + print_warning( + f"Purged {deleted} memory(ies) from store, but search index sync " + "incomplete. Run 'headroom memory reindex' to repair." + ) + sys.exit(1) except click.Abort: click.echo("Aborted.") @@ -962,6 +1151,143 @@ def purge_memories(ctx: click.Context, db_path: str, confirm_flag: bool) -> None sys.exit(1) +@memory.command("reindex") +@db_path_option +@click.pass_context +def reindex_memories(ctx: click.Context, db_path: str) -> None: + """Rebuild FTS5 search index and remove orphaned vector entries. + + Use this to repair an inconsistent index after a failed delete, prune, + or purge. Run it after installing sqlite-vec to clean up any vector + entries that could not be removed earlier. + + Vector embeddings are not regenerated by this command — they are rebuilt + automatically when the Headroom server next starts. + + \b + Example: + headroom memory reindex + """ + import sqlite3 + + store = get_store(db_path) + + try: + # Page through the complete active store. A fixed cap is destructive: + # clearing FTS and rebuilding only the first N rows drops valid search + # coverage, while using the same truncated ID set for vector cleanup + # misclassifies later primary rows as orphans. + memories: list[Memory] = [] + offset = 0 + while True: + page = asyncio.run( + store.query( + MemoryFilter( + limit=_REINDEX_PAGE_SIZE, + offset=offset, + order_by="created_at", + order_desc=False, + ) + ) + ) + if not page: + break + memories.extend(page) + offset += len(page) + + db = Path(db_path) + ok = True + + # --- FTS5: wipe and rebuild from primary store --- + from ..memory.adapters.fts5 import FTS5TextIndex + + # Construction initializes an absent optional FTS table. Cleanup + # helpers, by contrast, intentionally treat an absent table as a no-op. + fts = FTS5TextIndex(db_path=db_path) + try: + with sqlite3.connect(str(db)) as conn: + conn.execute("DELETE FROM memory_fts") + conn.commit() + except Exception as exc: + print_error(f"Failed to clear FTS5 index: {exc}") + sys.exit(1) + + fts_indexed = 0 + for mem in memories: + try: + asyncio.run(fts.index_memory(mem)) + fts_indexed += 1 + except Exception as exc: + print_warning(f"FTS5: failed to index {mem.id[:8]}: {exc}") + ok = False + + # --- Vector: remove orphaned entries (requires sqlite-vec) --- + vector_db = db.parent / f"{db.stem}_vectors.db" + vector_msg = "" + if vector_db.exists(): + # Orphan detection is based on every primary row, including + # superseded memories that are intentionally omitted from FTS. + with store._get_conn() as conn: + primary_ids = {row[0] for row in conn.execute("SELECT id FROM memories")} + try: + with sqlite3.connect(str(vector_db)) as conn: + if not _sqlite_table_exists(conn, "vec_metadata"): + vector_msg = ", vector index not initialized" + else: + import sqlite_vec + + conn.enable_load_extension(True) + sqlite_vec.load(conn) + conn.enable_load_extension(False) + rows = conn.execute("SELECT memory_id FROM vec_metadata").fetchall() + orphan_ids = [r[0] for r in rows if r[0] not in primary_ids] + if orphan_ids: + for i in range(0, len(orphan_ids), 500): + chunk = orphan_ids[i : i + 500] + ph = ",".join("?" * len(chunk)) + vec_rows = conn.execute( + f"SELECT rowid FROM vec_metadata WHERE memory_id IN ({ph})", + chunk, + ).fetchall() + rowids = [r[0] for r in vec_rows] + if rowids: + rph = ",".join("?" * len(rowids)) + conn.execute( + f"DELETE FROM vec_embeddings WHERE rowid IN ({rph})", + rowids, + ) + conn.execute( + f"DELETE FROM vec_metadata WHERE rowid IN ({rph})", + rowids, + ) + conn.commit() + vector_msg = ( + f", removed {len(orphan_ids)} orphaned vector entry(ies)" + if orphan_ids + else ", vector index clean" + ) + except ImportError: + vector_msg = ( + " (vector index skipped: sqlite-vec not installed — " + "install with: pip install sqlite-vec)" + ) + ok = False + except Exception as exc: + vector_msg = f" (vector index cleanup failed: {exc})" + ok = False + + msg = f"Re-indexed {fts_indexed}/{len(memories)} memories{vector_msg}." + if ok: + print_success(msg) + else: + print_warning(msg) + sys.exit(1) + + except Exception as e: + print_error(f"Failed to reindex: {e}") + sys.exit(1) + + @memory.command("export") @db_path_option @click.option( diff --git a/tests/test_cli_memory_index_sync.py b/tests/test_cli_memory_index_sync.py new file mode 100644 index 000000000..b4578d05f --- /dev/null +++ b/tests/test_cli_memory_index_sync.py @@ -0,0 +1,508 @@ +"""Tests for memory CLI index synchronization (issue #2856). + +Verifies that headroom memory delete/prune/purge/edit remove stale entries +from the FTS5 and vector search indexes, not just from the primary store. + +Vector index tests require sqlite-vec and are skipped when it is not installed. +They exercise the real SQLiteVectorIndex schema (vec0 virtual table) so that +the extension-aware connection path in _remove_from_search_indexes and +_clear_all_search_indexes is exercised rather than a plain-table stand-in. +""" + +from __future__ import annotations + +import asyncio +import sqlite3 +import sys +from pathlib import Path +from unittest.mock import patch + +import numpy as np +import pytest +from click.testing import CliRunner + +import headroom.cli.memory as memory_cli +from headroom.cli.main import main +from headroom.cli.memory import ( + _clear_all_search_indexes, + _remove_from_search_indexes, +) +from headroom.memory.adapters.fts5 import FTS5TextIndex +from headroom.memory.adapters.sqlite import SQLiteMemoryStore +from headroom.memory.models import Memory + +# --------------------------------------------------------------------------- +# sqlite-vec availability guard +# --------------------------------------------------------------------------- + +try: + from headroom.memory.adapters.sqlite_vector import ( + SQLiteVectorIndex, + is_sqlite_vec_available, + ) + + SQLITE_VEC_AVAILABLE = is_sqlite_vec_available() +except ImportError: + SQLITE_VEC_AVAILABLE = False + SQLiteVectorIndex = None # type: ignore[assignment,misc] + +requires_sqlite_vec = pytest.mark.skipif( + not SQLITE_VEC_AVAILABLE, reason="sqlite-vec not available" +) + +_VEC_DIM = 4 # small dimension keeps test seeding fast + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _make_memory(memory_id: str, content: str = "test content") -> Memory: + return Memory( + id=memory_id, + content=content, + user_id="test-user", + ) + + +def _seed_fts(db_path: Path, memories: list[Memory]) -> None: + """Index memories into the FTS5 table.""" + fts = FTS5TextIndex(db_path=str(db_path)) + for mem in memories: + asyncio.run(fts.index_memory(mem)) + + +def _seed_vector(db_path: Path, memory_ids: list[str]) -> None: + """Seed the vector DB using the real SQLiteVectorIndex (requires sqlite-vec). + + Creates the true vec0 virtual-table schema so the helpers under test + exercise the extension-aware connection path. + """ + vector_db = db_path.parent / f"{db_path.stem}_vectors.db" + index = SQLiteVectorIndex(dimension=_VEC_DIM, db_path=str(vector_db)) + for mid in memory_ids: + embedding = list( + np.random.default_rng(abs(hash(mid))).standard_normal(_VEC_DIM).astype(float) + ) + mem = Memory(id=mid, content="test", user_id="u", embedding=embedding) + asyncio.run(index.index(mem)) + + +def _fts_count(db_path: Path) -> int: + with sqlite3.connect(str(db_path)) as conn: + return conn.execute("SELECT COUNT(*) FROM memory_fts").fetchone()[0] + + +def _fts_ids(db_path: Path) -> set[str]: + with sqlite3.connect(str(db_path)) as conn: + rows = conn.execute("SELECT memory_id FROM memory_fts").fetchall() + return {r[0] for r in rows} + + +def _vector_ids(db_path: Path) -> set[str]: + """Read surviving memory_ids from the metadata table (regular, no extension needed).""" + vector_db = db_path.parent / f"{db_path.stem}_vectors.db" + if not vector_db.exists(): + return set() + with sqlite3.connect(str(vector_db)) as conn: + rows = conn.execute("SELECT memory_id FROM vec_metadata").fetchall() + return {r[0] for r in rows} + + +# --------------------------------------------------------------------------- +# _remove_from_search_indexes — FTS5 (no sqlite-vec required) +# --------------------------------------------------------------------------- + + +def test_remove_from_search_indexes_clears_fts_entries(tmp_path): + db_path = tmp_path / "memory.db" + mems = [_make_memory(f"id-{i}") for i in range(3)] + _seed_fts(db_path, mems) + assert _fts_count(db_path) == 3 + + _remove_from_search_indexes(str(db_path), ["id-0", "id-2"]) + + assert _fts_ids(db_path) == {"id-1"} + + +def test_remove_from_search_indexes_no_vector_db_is_noop(tmp_path): + db_path = tmp_path / "memory.db" + mems = [_make_memory("id-0")] + _seed_fts(db_path, mems) + + # No vector DB → should not raise + _remove_from_search_indexes(str(db_path), ["id-0"]) + + assert _fts_count(db_path) == 0 + + +def test_remove_from_search_indexes_empty_list_is_noop(tmp_path): + db_path = tmp_path / "memory.db" + _seed_fts(db_path, [_make_memory("id-0")]) + assert _fts_count(db_path) == 1 + + _remove_from_search_indexes(str(db_path), []) + + assert _fts_count(db_path) == 1 + + +def test_remove_from_search_indexes_absent_optional_indexes_is_noop(tmp_path): + """A primary-only store must not fail after its mutation already succeeded.""" + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + asyncio.run(store.save(_make_memory("id-0"))) + + assert _remove_from_search_indexes(str(db_path), ["id-0"]) is True + assert _clear_all_search_indexes(str(db_path)) is True + + +def test_empty_uninitialized_vector_database_is_noop_without_sqlite_vec(tmp_path, monkeypatch): + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + asyncio.run(store.save(_make_memory("id-0"))) + (tmp_path / "memory_vectors.db").touch() + monkeypatch.setitem(sys.modules, "sqlite_vec", None) + + assert _remove_from_search_indexes(str(db_path), ["id-0"]) is True + assert _clear_all_search_indexes(str(db_path)) is True + + +# --------------------------------------------------------------------------- +# _remove_from_search_indexes — vector index (real vec0 schema, requires sqlite-vec) +# --------------------------------------------------------------------------- + + +@requires_sqlite_vec +def test_remove_from_search_indexes_clears_vector_entries(tmp_path): + """Exercise the real vec0 virtual-table schema so the extension-aware + connection path in _remove_from_search_indexes is covered.""" + db_path = tmp_path / "memory.db" + _seed_fts(db_path, []) # ensure memory.db exists + _seed_vector(db_path, ["id-0", "id-1", "id-2"]) + assert _vector_ids(db_path) == {"id-0", "id-1", "id-2"} + + _remove_from_search_indexes(str(db_path), ["id-0", "id-2"]) + + assert _vector_ids(db_path) == {"id-1"} + + +@requires_sqlite_vec +def test_remove_from_search_indexes_no_vector_rows_to_delete_is_noop(tmp_path): + """IDs not present in the vector index must be silently skipped.""" + db_path = tmp_path / "memory.db" + _seed_fts(db_path, []) + _seed_vector(db_path, ["id-0"]) + assert _vector_ids(db_path) == {"id-0"} + + _remove_from_search_indexes(str(db_path), ["id-99"]) # not in index + + assert _vector_ids(db_path) == {"id-0"} + + +# --------------------------------------------------------------------------- +# _clear_all_search_indexes — FTS5 (no sqlite-vec required) +# --------------------------------------------------------------------------- + + +def test_clear_all_search_indexes_removes_all_fts_entries(tmp_path): + db_path = tmp_path / "memory.db" + _seed_fts(db_path, [_make_memory(f"id-{i}") for i in range(5)]) + assert _fts_count(db_path) == 5 + + _clear_all_search_indexes(str(db_path)) + + assert _fts_count(db_path) == 0 + + +def test_clear_all_search_indexes_no_vector_db_is_noop(tmp_path): + db_path = tmp_path / "memory.db" + _seed_fts(db_path, [_make_memory("id-0")]) + + _clear_all_search_indexes(str(db_path)) + + assert _fts_count(db_path) == 0 # FTS cleared; no vector DB is fine + + +# --------------------------------------------------------------------------- +# _clear_all_search_indexes — vector index (real vec0 schema, requires sqlite-vec) +# --------------------------------------------------------------------------- + + +@requires_sqlite_vec +def test_clear_all_search_indexes_removes_all_vector_entries(tmp_path): + """Exercise the real vec0 virtual-table schema so the extension-aware + connection path in _clear_all_search_indexes is covered.""" + db_path = tmp_path / "memory.db" + _seed_fts(db_path, []) + _seed_vector(db_path, ["id-0", "id-1"]) + assert _vector_ids(db_path) == {"id-0", "id-1"} + + _clear_all_search_indexes(str(db_path)) + + assert _vector_ids(db_path) == set() + + +# --------------------------------------------------------------------------- +# Integration: CLI commands wire up index sync correctly +# --------------------------------------------------------------------------- + + +def test_delete_command_removes_from_fts(tmp_path): + """Simulate delete command: delete_batch then _remove_from_search_indexes.""" + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + mem = _make_memory("abc123") + asyncio.run(store.save(mem)) + _seed_fts(db_path, [mem]) + assert _fts_count(db_path) == 1 + + asyncio.run(store.delete_batch(["abc123"])) + _remove_from_search_indexes(str(db_path), ["abc123"]) + + assert _fts_count(db_path) == 0 + + +@requires_sqlite_vec +def test_delete_command_removes_from_vector_index(tmp_path): + """Simulate delete command end-to-end with the real vec0 schema.""" + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + mem = _make_memory("abc123") + asyncio.run(store.save(mem)) + _seed_fts(db_path, [mem]) + _seed_vector(db_path, ["abc123"]) + assert _vector_ids(db_path) == {"abc123"} + + asyncio.run(store.delete_batch(["abc123"])) + _remove_from_search_indexes(str(db_path), ["abc123"]) + + assert _fts_count(db_path) == 0 + assert _vector_ids(db_path) == set() + + +def test_purge_command_clears_fts(tmp_path): + """Simulate purge command: clear_all then _clear_all_search_indexes.""" + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + for i in range(3): + asyncio.run(store.save(_make_memory(f"id-{i}"))) + _seed_fts(db_path, [_make_memory(f"id-{i}") for i in range(3)]) + assert _fts_count(db_path) == 3 + + asyncio.run(store.clear_all()) + _clear_all_search_indexes(str(db_path)) + + assert _fts_count(db_path) == 0 + + +@requires_sqlite_vec +def test_purge_command_clears_vector_index(tmp_path): + """Simulate purge command end-to-end with the real vec0 schema.""" + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + for i in range(3): + asyncio.run(store.save(_make_memory(f"id-{i}"))) + _seed_fts(db_path, [_make_memory(f"id-{i}") for i in range(3)]) + _seed_vector(db_path, [f"id-{i}" for i in range(3)]) + assert _vector_ids(db_path) == {"id-0", "id-1", "id-2"} + + asyncio.run(store.clear_all()) + _clear_all_search_indexes(str(db_path)) + + assert _fts_count(db_path) == 0 + assert _vector_ids(db_path) == set() + + +# --------------------------------------------------------------------------- +# Failure-path: return value and exit-code impact +# --------------------------------------------------------------------------- + + +def test_remove_from_search_indexes_fts_failure_returns_false(tmp_path): + """When FTS5 delete raises, the function returns False (not True).""" + db_path = tmp_path / "memory.db" + _seed_fts(db_path, [_make_memory("id-0")]) + + # sqlite3 is imported locally inside the helper so we patch the global module. + original_connect = sqlite3.connect + call_count = [0] + + def failing_connect(path, **kwargs): + call_count[0] += 1 + if call_count[0] == 1: # first call is the FTS5 db open + raise sqlite3.OperationalError("simulated FTS5 failure") + return original_connect(path, **kwargs) + + with patch("sqlite3.connect", side_effect=failing_connect): + result = _remove_from_search_indexes(str(db_path), ["id-0"]) + + assert result is False + + +def test_remove_from_search_indexes_sqlite_vec_missing_returns_false(tmp_path): + """When sqlite_vec is absent and a vector DB exists, returns False.""" + db_path = tmp_path / "memory.db" + _seed_fts(db_path, []) + # Create a non-empty vector DB file so the code doesn't short-circuit. + vector_db = tmp_path / "memory_vectors.db" + vector_db.write_bytes(b"placeholder") + + # Remove sqlite_vec from sys.modules so `import sqlite_vec` raises ImportError. + with patch.dict(sys.modules, {"sqlite_vec": None}): + result = _remove_from_search_indexes(str(db_path), ["id-0"]) + + assert result is False + + +def test_clear_all_search_indexes_fts_failure_returns_false(tmp_path): + """When FTS5 DELETE raises, _clear_all_search_indexes returns False.""" + db_path = tmp_path / "memory.db" + _seed_fts(db_path, [_make_memory("id-0")]) + + original_connect = sqlite3.connect + call_count = [0] + + def failing_connect(path, **kwargs): + call_count[0] += 1 + if call_count[0] == 1: + raise sqlite3.OperationalError("simulated FTS5 failure") + return original_connect(path, **kwargs) + + with patch("sqlite3.connect", side_effect=failing_connect): + result = _clear_all_search_indexes(str(db_path)) + + assert result is False + + +def test_clear_all_search_indexes_sqlite_vec_missing_returns_false(tmp_path): + """When sqlite_vec is absent and a vector DB exists, returns False.""" + db_path = tmp_path / "memory.db" + _seed_fts(db_path, []) + vector_db = tmp_path / "memory_vectors.db" + vector_db.write_bytes(b"placeholder") + + with patch.dict(sys.modules, {"sqlite_vec": None}): + result = _clear_all_search_indexes(str(db_path)) + + assert result is False + + +def test_reindex_pages_through_complete_store(tmp_path, monkeypatch): + """Records beyond the first page remain represented in rebuilt FTS.""" + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + memories = [_make_memory(f"id-{i}", f"content {i}") for i in range(5)] + for memory in memories: + asyncio.run(store.save(memory)) + _seed_fts(db_path, memories[:2]) + monkeypatch.setattr(memory_cli, "_REINDEX_PAGE_SIZE", 2) + + result = CliRunner().invoke(main, ["memory", "reindex", "--db-path", str(db_path)]) + + assert result.exit_code == 0, result.output + assert _fts_ids(db_path) == {memory.id for memory in memories} + assert "Re-indexed 5/5 memories" in result.output + + +@requires_sqlite_vec +def test_reindex_keeps_valid_vectors_beyond_first_page(tmp_path, monkeypatch): + """Complete primary IDs, not one page, determine vector orphans.""" + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + memories = [_make_memory(f"id-{i}", f"content {i}") for i in range(5)] + for memory in memories: + asyncio.run(store.save(memory)) + _seed_vector(db_path, [memory.id for memory in memories] + ["orphan"]) + monkeypatch.setattr(memory_cli, "_REINDEX_PAGE_SIZE", 2) + + result = CliRunner().invoke(main, ["memory", "reindex", "--db-path", str(db_path)]) + + assert result.exit_code == 0, result.output + assert _vector_ids(db_path) == {memory.id for memory in memories} + + +def test_delete_command_exits_nonzero_when_index_sync_fails(tmp_path, monkeypatch): + """The real Click command must not report a partially synced delete as success.""" + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + memory = _make_memory("abc123") + asyncio.run(store.save(memory)) + monkeypatch.setattr(memory_cli, "_remove_from_search_indexes", lambda *_args: False) + + result = CliRunner().invoke( + main, + ["memory", "delete", memory.id, "--force", "--db-path", str(db_path)], + ) + + assert result.exit_code == 1 + assert asyncio.run(store.get(memory.id)) is None + assert "index sync incomplete" in result.output + + +def test_edit_command_exits_nonzero_when_index_sync_fails(tmp_path, monkeypatch): + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + memory = _make_memory("abc123", "before") + asyncio.run(store.save(memory)) + monkeypatch.setattr(memory_cli, "_remove_from_search_indexes", lambda *_args: False) + + result = CliRunner().invoke( + main, + [ + "memory", + "edit", + memory.id, + "--content", + "after", + "--db-path", + str(db_path), + ], + ) + + assert result.exit_code == 1 + assert asyncio.run(store.get(memory.id)).content == "after" + assert "index sync incomplete" in result.output + + +def test_prune_command_exits_nonzero_when_index_sync_fails(tmp_path, monkeypatch): + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + memory = _make_memory("abc123") + asyncio.run(store.save(memory)) + monkeypatch.setattr(memory_cli, "_remove_from_search_indexes", lambda *_args: False) + + result = CliRunner().invoke( + main, + [ + "memory", + "prune", + "--low-importance", + "1.0", + "--force", + "--db-path", + str(db_path), + ], + ) + + assert result.exit_code == 1 + assert asyncio.run(store.get(memory.id)) is None + assert "index sync incomplete" in result.output + + +def test_purge_command_exits_nonzero_when_index_sync_fails(tmp_path, monkeypatch): + db_path = tmp_path / "memory.db" + store = SQLiteMemoryStore(str(db_path)) + memory = _make_memory("abc123") + asyncio.run(store.save(memory)) + monkeypatch.setattr(memory_cli, "_clear_all_search_indexes", lambda *_args: False) + + result = CliRunner().invoke( + main, + ["memory", "purge", "--confirm", "--db-path", str(db_path)], + input="y\n", + ) + + assert result.exit_code == 1 + assert asyncio.run(store.get(memory.id)) is None + assert "index sync incomplete" in result.output From de9e0523dad47b700062464adecd60f82547f332 Mon Sep 17 00:00:00 2001 From: AxelRay Date: Wed, 12 Aug 2026 05:22:27 +0700 Subject: [PATCH 044/138] fix(settings): accept documented HEADROOM_* env names as settings keys (#2833) ## Description Settings validation only accepted short JSON/API keys, so documented HEADROOM_* env names were rejected as unknown. Users following the docs (for example HEADROOM_LOSSLESS) hit SettingsValidationError / PUT /settings 400 even though those names are already on each registry field. This normalizes known env aliases to their short keys before validate/save, keeps existing short-key behavior, and rejects conflicting env+key pairs for the same field. Closes #2812 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Added _BY_ENV and _normalize_values() in settings_store to map documented env names to short keys - Call normalization at the start of validate() and save() so clear/retain paths also accept env aliases - Reject payloads that supply both an env alias and its short key with different values - Add unit coverage for accept/clear/conflict/same-value paths and update registry monkeypatches to rebuild _BY_ENV ## Testing - [x] Unit tests pass (pytest) - [x] Linting passes (ruff check .) - [ ] Type checking passes (mypy headroom) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text python -m pytest tests/test_proxy/test_settings_store.py -q -k "env_alias or validate_accepts or save_rejects or same_env or conflicting or save_accepts or env_alias_clear or anthropic_extra_headers_retain or TestValidation" 23 passed, 11 deselected ruff check headroom/settings_store.py tests/test_proxy/test_settings_store.py tests/test_proxy_settings_endpoints.py All checks passed! ruff format --check headroom/settings_store.py tests/test_proxy/test_settings_store.py tests/test_proxy_settings_endpoints.py 3 files already formatted ``` ## Real Behavior Proof - Environment: Linux x86_64, Python 3.14.5 via contributor venv, worktree of headroom main at 7940c05e plus commit e4c87edf - Exact command / steps: pytest tests/test_proxy/test_settings_store.py focused selection; ruff check and ruff format --check on the three touched files; settings_store.validate({"HEADROOM_LOSSLESS": True}) returns {"lossless": True} - Observed result: Env aliases coerce and persist under short keys; unknown short keys still error; conflicting env+key pairs raise SettingsValidationError; ruff clean on touched files - Not tested: Live dashboard PUT /settings through a running proxy (HTTP suite needs native headroom._core); mypy; full monorepo CI ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project style guidelines - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did not edit CHANGELOG.md - it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A ## Additional Notes - Scoped to settings key normalization only - Registry drift Click test was not exercised here because this environment lacks tomlkit for an unrelated import path --- headroom/settings_store.py | 24 +++++++++++++++ tests/test_proxy/test_settings_store.py | 41 +++++++++++++++++++++++++ tests/test_proxy_settings_endpoints.py | 1 + 3 files changed, 66 insertions(+) diff --git a/headroom/settings_store.py b/headroom/settings_store.py index c085c181f..b686d3b86 100644 --- a/headroom/settings_store.py +++ b/headroom/settings_store.py @@ -697,6 +697,7 @@ SETTINGS: tuple[SettingField, ...] = ( ) _BY_KEY: dict[str, SettingField] = {f.key: f for f in SETTINGS} +_BY_ENV: dict[str, SettingField] = {f.env: f for f in SETTINGS} class SettingsValidationError(Exception): @@ -714,6 +715,27 @@ class SettingsValidationError(Exception): ) +def _normalize_values(values: dict[str, Any]) -> dict[str, Any]: + """Rewrite known env aliases to their JSON/API keys.""" + normalized: dict[str, Any] = {} + source_keys: dict[str, str] = {} + conflicts: dict[str, str] = {} + for incoming_key, value in values.items(): + field = _BY_ENV.get(incoming_key) + key = field.key if field is not None else incoming_key + if key in normalized: + if normalized[key] != value: + conflicts[key] = ( + f"conflicting values supplied for {source_keys[key]!r} and {incoming_key!r}" + ) + continue + normalized[key] = value + source_keys[key] = incoming_key + if conflicts: + raise SettingsValidationError([], conflicts) + return normalized + + def _coerce(field: SettingField, value: Any) -> Any: """Coerce a raw JSON/env value to the field's Python type. @@ -792,6 +814,7 @@ def validate(values: dict[str, Any]) -> dict[str, Any]: Raises :class:`SettingsValidationError` when any key is unknown or any value fails coercion. Returns the coerced dict (``None`` values dropped) on success. """ + values = _normalize_values(values) unknown = [key for key in values if key not in _BY_KEY] field_errors: dict[str, str] = {} coerced: dict[str, Any] = {} @@ -879,6 +902,7 @@ def save(values: dict[str, Any]) -> None: secret's display value verbatim when the user hasn't touched it; anything else is validated/coerced and stored. """ + values = _normalize_values(values) clear_keys = {key for key, value in values.items() if value is None and key in _BY_KEY} retained_keys = { key diff --git a/tests/test_proxy/test_settings_store.py b/tests/test_proxy/test_settings_store.py index c6c1876cc..58f6bce66 100644 --- a/tests/test_proxy/test_settings_store.py +++ b/tests/test_proxy/test_settings_store.py @@ -63,6 +63,37 @@ class TestRoundTrip: class TestValidation: + def test_validate_accepts_env_aliases(self, workspace): + assert settings_store.validate({"HEADROOM_LOSSLESS": True, "HEADROOM_RPM": "30"}) == { + "lossless": True, + "rpm": 30, + } + + def test_save_accepts_env_alias_and_persists_short_key(self, workspace): + settings_store.save({"HEADROOM_LOSSLESS": True}) + + assert settings_store.load() == {"lossless": True} + + def test_env_alias_clear_removes_short_key(self, workspace): + settings_store.save({"lossless": True}) + + settings_store.save({"HEADROOM_LOSSLESS": None}) + + assert settings_store.load() == {} + + def test_conflicting_env_alias_and_short_key_rejected(self, workspace): + with pytest.raises(settings_store.SettingsValidationError) as exc: + settings_store.validate({"HEADROOM_LOSSLESS": True, "lossless": False}) + + assert exc.value.unknown_keys == [] + assert "lossless" in exc.value.field_errors + assert "HEADROOM_LOSSLESS" in exc.value.field_errors["lossless"] + + def test_same_env_alias_and_short_key_value_is_accepted(self, workspace): + assert settings_store.validate({"HEADROOM_LOSSLESS": True, "lossless": True}) == { + "lossless": True + } + def test_save_rejects_unknown_key(self, workspace): with pytest.raises(settings_store.SettingsValidationError) as exc: settings_store.save({"nope": 1}) @@ -156,6 +187,7 @@ class TestSecretMasking: ) monkeypatch.setattr(settings_store, "SETTINGS", registry) monkeypatch.setattr(settings_store, "_BY_KEY", {f.key: f for f in registry}) + monkeypatch.setattr(settings_store, "_BY_ENV", {f.env: f for f in registry}) settings_store.save({"log_file": "/tmp/secret.log"}) stored = settings_store.stored_values() @@ -187,6 +219,15 @@ class TestSecretMasking: "Saving _MASK should retain the stored value, not overwrite it" ) + def test_anthropic_extra_headers_retain_on_env_alias_mask(self, workspace, monkeypatch): + """Saving _MASK through the env alias retains the stored value.""" + _clear_env(monkeypatch) + settings_store.save({"anthropic_extra_headers": '{"Api-Key": "secret123"}'}) + + settings_store.save({"ANTHROPIC_TARGET_API_HEADERS": settings_store._MASK}) + + assert settings_store.load().get("anthropic_extra_headers") == '{"Api-Key": "secret123"}' + def test_anthropic_extra_headers_clear_on_none(self, workspace, monkeypatch): """Saving None for anthropic_extra_headers removes it.""" _clear_env(monkeypatch) diff --git a/tests/test_proxy_settings_endpoints.py b/tests/test_proxy_settings_endpoints.py index 31880c5ab..1e51f1001 100644 --- a/tests/test_proxy_settings_endpoints.py +++ b/tests/test_proxy_settings_endpoints.py @@ -207,6 +207,7 @@ class TestSecretMasking: ) monkeypatch.setattr(settings_store, "SETTINGS", registry) monkeypatch.setattr(settings_store, "_BY_KEY", {f.key: f for f in registry}) + monkeypatch.setattr(settings_store, "_BY_ENV", {f.env: f for f in registry}) settings_store.save({"log_file": "/tmp/secret.log"}) assert client.get("/settings").json()["log_file"] == settings_store._MASK From 7092b53c466bf5dbda8a1cda88403d1a4b16deb1 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Wed, 12 Aug 2026 03:53:29 +0530 Subject: [PATCH 045/138] fix(cli/update): let install ownership win over bare /.dockerenv so venv installs self-update (#2830) ## Description `headroom update` refuses to self-update for any install that happens to run inside a container, including a plain `pip install` into a venv, because `detect_install_method` checks `_in_docker()` before the pipx / uv-tool / venv / user-site branches. The guidance it prints does not apply: there is no Headroom image in the picture, the container is the environment and Headroom was pip-installed into a venv inside it. ```console $ headroom update --check Update available: 0.32.0 -> 0.34.0 Running inside a container - pull a newer Headroom image instead of self-updating. ``` `_in_docker()` is purely environmental (`/.dockerenv` exists, or `HEADROOM_IN_DOCKER` is set), with no reference to how the package was installed, so `/.dockerenv` alone shadows a venv that clearly owns the install. This hits devcontainers, GitHub Codespaces, docker/LXC self-hosting, and dev images. The fix splits the check by intent. An EXPLICIT `HEADROOM_IN_DOCKER` (which the official image can set) is a deliberate opt-out and still refuses up front, even over a venv, so the real-image behavior is preserved. The bare `/.dockerenv` heuristic now runs after ownership detection, so a venv / pipx / uv / user-site install self-updates and only a container whose own system interpreter owns the install still gets the pull-a-new-image guidance. Fixes #2816 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/cli/update.py` (`detect_install_method`): replaced the up-front `_in_docker()` refusal with an explicit `os.environ.get("HEADROOM_IN_DOCKER")` refusal (the official image opt-out), and added the bare `_in_docker()` refusal after the pipx / uv-tool / venv / user-site branches so ownership wins over environment. Updated the resolution-order docstring. - `tests/test_update_helpers.py`: added `test_venv_inside_bare_dockerenv_still_self_updates` (the fix), `test_explicit_headroom_in_docker_still_refuses_over_venv` (image opt-out preserved), and `test_bare_dockerenv_without_owner_refuses` (system-interpreter container still refuses). - `tests/test_cli_update.py` (`test_detect_docker`): updated to drive the bare-`/.dockerenv`-no-owner path deterministically (mock ownership to absent), since a real venv underneath now correctly wins. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Fail-before (source fix stashed, new test kept): tests/test_update_helpers.py::test_venv_inside_bare_dockerenv_still_self_updates FAILED assert method.kind == "pip" AssertionError: assert 'docker' == 'pip' # Pass-after (fix applied), all update suites: tests/test_update_helpers.py tests/test_cli_update.py tests/test_update_check.py 95 passed # uvx ruff@0.15.17 check -> All checks passed! # uvx mypy@1.20.2 headroom/cli/update.py -> Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1, ruff 0.15.17 and mypy 1.20.2 via uvx. - Exact command / steps: read `detect_install_method` to confirm `_in_docker()` (line 354) preceded the pipx (377) / uv-tool (385) / venv (392) branches, reproduced the issue's environment in a test (bare `/.dockerenv` via `_in_docker` monkeypatched True, `HEADROOM_IN_DOCKER` unset, a venv layout under `sys.prefix`), fail-before with `git stash push headroom/cli/update.py` and `python -m pytest tests/test_update_helpers.py -k venv_inside_bare_dockerenv` (the venv is refused with `kind == "docker"`), then pass-after with `git stash pop` and rerunning the full update suites (95 passed). - Observed result: a venv/pip install inside a bare `/.dockerenv` container now resolves to `kind="pip"`, `can_self_update=True`, `argv=[sys.executable, "-m", "pip", "install", "-U", ...]`, matching the manual command the issue reporter confirmed works. An explicit `HEADROOM_IN_DOCKER=1` still resolves to `kind="docker"` even over a venv, and a container whose system interpreter owns the install still resolves to `kind="docker"`. - Not tested: an end-to-end `headroom update` run inside a real devcontainer against live PyPI (no container in this environment). The resolution is a pure classification function verified directly, and the actual upgrade command it builds is the existing, already-tested venv path. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`: it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes The official image opt-out is preserved by design: the issue notes `_in_docker()` already honors `HEADROOM_IN_DOCKER`, so the image can keep refusing self-update by setting it, which this PR routes to the explicit up-front check that wins even over a venv. Only the bare `/.dockerenv` auto-detection was demoted below ownership. --- headroom/cli/update.py | 27 ++++++++++++++--- tests/test_cli_update.py | 9 ++++++ tests/test_update_helpers.py | 58 ++++++++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+), 4 deletions(-) diff --git a/headroom/cli/update.py b/headroom/cli/update.py index 9b907f126..93796d246 100644 --- a/headroom/cli/update.py +++ b/headroom/cli/update.py @@ -328,13 +328,14 @@ def detect_install_method(extras: str | None = None) -> InstallMethod: 1. git checkout → refuse (`git pull`) 2. editable install → refuse (reinstall from source) - 3. Docker → refuse (pull a new image) + 3. explicit HEADROOM_IN_DOCKER → refuse (official image opt-out) 4. pipx → `pipx upgrade` 5. uv tool → `uv tool upgrade` 6. venv / virtualenv / conda → `sys.executable -m pip install -U` 7. user-site (`pip --user`) → `sys.executable -m pip install -U --user` - 8. externally-managed system Python (PEP 668) → refuse with guidance - 9. writable global Python → `sys.executable -m pip install -U` (last resort) + 8. bare /.dockerenv (system interpreter) → refuse (pull a new image) + 9. externally-managed system Python (PEP 668) → refuse with guidance + 10. writable global Python → `sys.executable -m pip install -U` (last resort) """ if _is_source_checkout(): return InstallMethod( @@ -351,7 +352,13 @@ def detect_install_method(extras: str | None = None) -> InstallMethod: "reinstall with `pip install -U --force-reinstall .`." ), ) - if _in_docker(): + # An EXPLICIT HEADROOM_IN_DOCKER (set by the official image) is a deliberate + # "pull a newer image" opt-out and wins up front, even over a venv. The bare + # /.dockerenv heuristic is handled far lower, after ownership detection, so a + # pip / pipx / uv install inside a devcontainer, Codespace, or docker dev + # image is not shadowed by the mere fact that the environment is a container + # (#2816). + if os.environ.get("HEADROOM_IN_DOCKER", "").strip(): return InstallMethod( kind="docker", can_self_update=False, @@ -404,6 +411,18 @@ def detect_install_method(extras: str | None = None) -> InstallMethod: argv=[sys.executable, "-m", "pip", "install", "-U", "--user", _spec(extras)], ) + # Bare /.dockerenv with no venv / pipx / uv / user-site owner: the install + # belongs to the container's own interpreter, where "pull a newer image" is + # the only real route. An explicit HEADROOM_IN_DOCKER already returned above. + if _in_docker(): + return InstallMethod( + kind="docker", + can_self_update=False, + guidance=( + "Running inside a container — pull a newer Headroom image instead of self-updating." + ), + ) + if _is_externally_managed(): return InstallMethod( kind="system", diff --git a/tests/test_cli_update.py b/tests/test_cli_update.py index 372649461..8f3ea107f 100644 --- a/tests/test_cli_update.py +++ b/tests/test_cli_update.py @@ -40,7 +40,16 @@ def test_detect_editable(monkeypatch): def test_detect_docker(monkeypatch): + # A bare /.dockerenv container whose system interpreter owns the install + # (no venv / pipx / uv / user-site) still refuses. When an install method + # owns it, ownership wins over the container environment (#2816) -- see + # test_update_helpers.test_venv_inside_bare_dockerenv_still_self_updates. + monkeypatch.delenv("HEADROOM_IN_DOCKER", raising=False) monkeypatch.setattr(up, "_in_docker", lambda: True) + monkeypatch.setattr(up, "_in_virtualenv", lambda: False) + monkeypatch.setattr(up, "_is_user_site_install", lambda loc: False) + monkeypatch.setattr(up.sys, "prefix", "/usr") + monkeypatch.setattr(up.sys, "executable", "/usr/bin/python3") m = up.detect_install_method() assert m.kind == "docker" and m.can_self_update is False diff --git a/tests/test_update_helpers.py b/tests/test_update_helpers.py index bb313b2d1..b037bb99c 100644 --- a/tests/test_update_helpers.py +++ b/tests/test_update_helpers.py @@ -267,6 +267,64 @@ def test_update_externally_managed_refuses_via_command(monkeypatch): assert "PEP 668" in res.output +def test_venv_inside_bare_dockerenv_still_self_updates(monkeypatch): + """A venv/pip install inside a container (bare /.dockerenv, no explicit + HEADROOM_IN_DOCKER) must self-update, not be refused with image guidance (#2816). + """ + monkeypatch.setattr(up, "_is_source_checkout", lambda: False) + monkeypatch.setattr(up, "_is_editable_install", lambda: False) + monkeypatch.delenv("HEADROOM_IN_DOCKER", raising=False) + # Deterministic, pipx/uv-free venv layout (mirrors the issue's environment). + monkeypatch.setenv("PIPX_HOME", "") + monkeypatch.setenv("UV_TOOL_DIR", "") + monkeypatch.setattr(up.sys, "executable", "/config/.headroom-venv/bin/python") + monkeypatch.setattr(up.sys, "prefix", "/config/.headroom-venv") + monkeypatch.setattr( + up, "_package_location", lambda: "/config/.headroom-venv/lib/python3.12/headroom" + ) + # The container is real (/.dockerenv), but a venv owns the install. + monkeypatch.setattr(up, "_in_docker", lambda: True) + monkeypatch.setattr(up, "_in_virtualenv", lambda: True) + + method = up.detect_install_method() + assert method.kind == "pip" + assert method.can_self_update is True + assert method.argv[:4] == [up.sys.executable, "-m", "pip", "install"] + + +def test_explicit_headroom_in_docker_still_refuses_over_venv(monkeypatch): + """The official image's explicit HEADROOM_IN_DOCKER opt-out wins up front, + even when a venv owns the install.""" + monkeypatch.setattr(up, "_is_source_checkout", lambda: False) + monkeypatch.setattr(up, "_is_editable_install", lambda: False) + monkeypatch.setenv("HEADROOM_IN_DOCKER", "1") + monkeypatch.setattr(up, "_in_virtualenv", lambda: True) + + method = up.detect_install_method() + assert method.kind == "docker" + assert method.can_self_update is False + + +def test_bare_dockerenv_without_owner_refuses(monkeypatch): + """A container whose system interpreter owns the install (bare /.dockerenv, no + venv/pipx/uv/user-site) still refuses with the pull-a-new-image guidance.""" + monkeypatch.setattr(up, "_is_source_checkout", lambda: False) + monkeypatch.setattr(up, "_is_editable_install", lambda: False) + monkeypatch.delenv("HEADROOM_IN_DOCKER", raising=False) + monkeypatch.setenv("PIPX_HOME", "") + monkeypatch.setenv("UV_TOOL_DIR", "") + monkeypatch.setattr(up.sys, "executable", "/usr/bin/python3") + monkeypatch.setattr(up.sys, "prefix", "/usr") + monkeypatch.setattr(up, "_package_location", lambda: "/usr/lib/python3.12/headroom") + monkeypatch.setattr(up, "_in_docker", lambda: True) + monkeypatch.setattr(up, "_in_virtualenv", lambda: False) + monkeypatch.setattr(up, "_is_user_site_install", lambda loc: False) + + method = up.detect_install_method() + assert method.kind == "docker" + assert method.can_self_update is False + + # --------------------------------------------------------------------------- # # update_check helpers / branches # --------------------------------------------------------------------------- # From 8cd138039edbfc295080ec474325d527fb3aedf3 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Tue, 11 Aug 2026 16:10:39 -0700 Subject: [PATCH 046/138] fix(toin): bound private query and pattern retention Fix TOIN privacy leakage and unbounded retention (#2926, #2886). --- headroom/telemetry/backends/filesystem.py | 21 ++++- headroom/telemetry/toin.py | 95 ++++++++++++++++++-- tests/test_toin_retention.py | 100 ++++++++++++++++++++++ 3 files changed, 207 insertions(+), 9 deletions(-) create mode 100644 tests/test_toin_retention.py diff --git a/headroom/telemetry/backends/filesystem.py b/headroom/telemetry/backends/filesystem.py index cd192bf1d..8c5d52691 100644 --- a/headroom/telemetry/backends/filesystem.py +++ b/headroom/telemetry/backends/filesystem.py @@ -28,8 +28,9 @@ class FileSystemTOINBackend: path: Path to the JSON storage file. """ - def __init__(self, path: str) -> None: + def __init__(self, path: str, *, max_load_bytes: int | None = None) -> None: self._path = Path(path) + self._max_load_bytes = max_load_bytes def load(self) -> dict[str, Any]: """Load TOIN data from the JSON file. @@ -41,6 +42,17 @@ class FileSystemTOINBackend: return {} try: + if ( + self._max_load_bytes is not None + and self._path.stat().st_size > self._max_load_bytes + ): + logger.warning( + "TOIN data file %s exceeds the configured load limit (%d bytes); " + "ignoring it until the store is rebuilt", + self._path, + self._max_load_bytes, + ) + return {} with open(self._path) as f: data: dict[str, Any] = json.load(f) return data @@ -60,12 +72,13 @@ class FileSystemTOINBackend: try: self._path.parent.mkdir(parents=True, exist_ok=True) - json_data = json.dumps(data, indent=2) - fd, tmp_path = tempfile.mkstemp(dir=self._path.parent, prefix=".toin_", suffix=".tmp") try: + # Stream compact JSON directly to the temp file. Building a + # second multi-gigabyte string was the primary autosave RSS + # spike reported in #2886. with open(fd, "w") as f: - f.write(json_data) + json.dump(data, f, separators=(",", ":")) Path(tmp_path).replace(self._path) except Exception: try: diff --git a/headroom/telemetry/toin.py b/headroom/telemetry/toin.py index 792cc9fd6..34fb3579d 100644 --- a/headroom/telemetry/toin.py +++ b/headroom/telemetry/toin.py @@ -97,6 +97,13 @@ DEFAULT_MODEL_FAMILY: Final[str] = "unknown" # environment; this is the production default the Rust proxy expects. DEFAULT_MIN_OBSERVATIONS_TO_PUBLISH: Final[int] = 50 +# TOIN is a diagnostic learning store, not an archive. Keep its default +# footprint bounded so a long-lived proxy cannot turn observations into an +# unbounded memory/disk liability. +DEFAULT_MAX_PATTERNS: Final[int] = 10_000 +DEFAULT_MAX_STORAGE_BYTES: Final[int] = 128 * 1024 * 1024 +MAX_QUERY_PATTERN_LENGTH: Final[int] = 512 + # Aggregation-key serialization separator. Used to encode the # `(auth_mode, model_family, sig_hash)` tuple as a string for JSON # storage (JSON object keys must be strings) and for cross-instance @@ -391,6 +398,8 @@ class TOINConfig: # Default path is ~/.headroom/toin.json (or HEADROOM_TOIN_PATH env var) storage_path: str = field(default_factory=get_default_toin_storage_path) auto_save_interval: int = 600 # Auto-save every 10 minutes + max_patterns: int = DEFAULT_MAX_PATTERNS + max_storage_bytes: int = DEFAULT_MAX_STORAGE_BYTES # Network learning thresholds min_samples_for_recommendation: int = 10 @@ -452,7 +461,10 @@ class ToolIntelligenceNetwork: if backend is not None: self._backend = backend elif self._config.storage_path: - self._backend = FileSystemTOINBackend(self._config.storage_path) + self._backend = FileSystemTOINBackend( + self._config.storage_path, + max_load_bytes=self._config.max_storage_bytes, + ) else: self._backend = None @@ -696,6 +708,7 @@ class ToolIntelligenceNetwork: pattern.last_updated = time.time() pattern.confidence = self._calculate_confidence(pattern) self._dirty = True + self._prune_patterns_locked() # Auto-save if needed (outside lock) self._maybe_auto_save() @@ -775,6 +788,59 @@ class ToolIntelligenceNetwork: )[:100] pattern.field_semantics = dict(sorted_fields) + def _prune_patterns_locked(self) -> None: + """Bound the pattern table, evicting least-useful observations first. + + The lock must be held by the caller. Patterns below the publish + threshold are disposable learning noise; within each class, oldest + observations are evicted first. If every pattern is mature, oldest + wins, keeping the table bounded without silently preferring a tenant. + """ + limit = max(1, self._config.max_patterns) + if len(self._patterns) <= limit: + return + + excess = len(self._patterns) - limit + evict = sorted( + self._patterns, + key=lambda key: ( + self._patterns[key].sample_size >= DEFAULT_MIN_OBSERVATIONS_TO_PUBLISH, + self._patterns[key].last_updated, + ), + )[:excess] + for key in evict: + del self._patterns[key] + + logger.info( + "TOIN pattern table pruned", + extra={ + "event": "toin_patterns_pruned", + "evicted": excess, + "remaining": len(self._patterns), + }, + ) + + def _sanitize_loaded_pattern(self, pattern: ToolPattern) -> bool: + """Remove legacy raw query keys from a loaded pattern.""" + import re + + safe_pattern = re.compile(r"(?:\w+:\*)(?:\s+\w+:\*)*") + changed = False + frequencies: dict[str, int] = {} + for raw_key, count in pattern.query_pattern_frequency.items(): + if safe_pattern.fullmatch(raw_key) and len(raw_key) <= MAX_QUERY_PATTERN_LENGTH: + frequencies[raw_key] = max(0, int(count)) + else: + changed = True + if frequencies != pattern.query_pattern_frequency: + changed = True + pattern.query_pattern_frequency = frequencies + safe_common = [key for key in pattern.common_query_patterns if key in frequencies] + if safe_common != pattern.common_query_patterns: + changed = True + pattern.common_query_patterns = safe_common[: self._config.max_query_patterns] + return changed + def record_retrieval( self, tool_signature_hash: str, @@ -949,6 +1015,7 @@ class ToolIntelligenceNetwork: pattern.last_updated = time.time() self._dirty = True + self._prune_patterns_locked() self._maybe_auto_save() @@ -1050,14 +1117,22 @@ class ToolIntelligenceNetwork: if not query: return None - # Simple pattern extraction: replace values after : or = + # Only retain structured field/value predicates. Returning an + # unchanged free-form prompt here would persist the prompt verbatim, + # violating TOIN's privacy contract (and can produce multi-MB keys). import re # Match field:value or field="value" patterns, but don't include spaces in unquoted values - pattern = re.sub(r'(\w+)[=:](?:"[^"]*"|\'[^\']*\'|\w+)', r"\1:*", query) + matches = re.findall(r'(\w+)[=:](?:"[^"]*"|\'[^\']*\'|\w+)', query) + if not matches: + return None + + # Preserve useful field shape while dropping operators, values, and + # all unrelated text (which may contain arbitrary prompt data). + pattern = " ".join(f"{field}:*" for field in matches) # Remove if it's just generic - if pattern in ("*", ""): + if not pattern or len(pattern) > MAX_QUERY_PATTERN_LENGTH: return None return pattern @@ -1217,6 +1292,7 @@ class ToolIntelligenceNetwork: for serialized_key, pattern_dict in patterns_data.items(): key = _deserialize_pattern_key(serialized_key) imported = ToolPattern.from_dict(pattern_dict) + self._sanitize_loaded_pattern(imported) # Make sure dataclass fields agree with the dict key — pre-B5 # dumps don't carry auth_mode/model_family on the pattern; # promote from the (possibly default) key. @@ -1241,6 +1317,7 @@ class ToolIntelligenceNetwork: # CRITICAL: Always increment user_count (even after cap) pattern.user_count += 1 + self._prune_patterns_locked() self._dirty = True def _merge_patterns(self, existing: ToolPattern, imported: ToolPattern) -> None: @@ -1472,7 +1549,15 @@ class ToolIntelligenceNetwork: data = self._backend.load() if data: self.import_patterns(data) - self._dirty = False + with self._lock: + changed = any( + self._sanitize_loaded_pattern(pattern) + for pattern in self._patterns.values() + ) + before = len(self._patterns) + self._prune_patterns_locked() + changed = changed or len(self._patterns) != before + self._dirty = changed except Exception as e: logger.warning( "TOIN storage load failed", diff --git a/tests/test_toin_retention.py b/tests/test_toin_retention.py new file mode 100644 index 000000000..c43f95c05 --- /dev/null +++ b/tests/test_toin_retention.py @@ -0,0 +1,100 @@ +"""Regression tests for TOIN privacy and bounded retention.""" + +from __future__ import annotations + +import json + +from headroom.telemetry.backends.filesystem import FileSystemTOINBackend +from headroom.telemetry.models import ToolSignature +from headroom.telemetry.toin import TOINConfig, ToolIntelligenceNetwork + + +def _signature(index: int) -> ToolSignature: + return ToolSignature.from_items([{f"field_{index}": "x"}]) + + +def test_free_form_queries_are_not_persisted() -> None: + toin = ToolIntelligenceNetwork(TOINConfig(storage_path="")) + + assert toin._anonymize_query_pattern("show me the contents of /private/secret.txt") is None + assert toin._anonymize_query_pattern("status:error AND user:john") == "status:* user:*" + + toin.record_retrieval( + "signature", + retrieval_type="search", + query="show me the contents of /private/secret.txt", + ) + pattern = toin.get_pattern("signature") + assert pattern is not None + assert pattern.query_pattern_frequency == {} + + +def test_query_pattern_length_is_bounded() -> None: + toin = ToolIntelligenceNetwork(TOINConfig(storage_path="")) + + assert toin._anonymize_query_pattern("field:" + "x" * 1000) == "field:*" + assert toin._anonymize_query_pattern(" ".join(f"field{i}:x" for i in range(200))) is None + + +def test_pattern_table_evicts_old_low_sample_patterns() -> None: + config = TOINConfig(storage_path="", max_patterns=2) + toin = ToolIntelligenceNetwork(config) + + for index in range(3): + toin.record_compression( + tool_signature=_signature(index), + original_count=10, + compressed_count=5, + original_tokens=100, + compressed_tokens=50, + strategy="test", + ) + + assert len(toin._patterns) == 2 + assert _signature(0).structure_hash not in { + pattern.tool_signature_hash for pattern in toin._patterns.values() + } + + +def test_legacy_raw_query_keys_are_removed_on_load(tmp_path) -> None: + path = tmp_path / "toin.json" + payload = { + "version": "2.0", + "patterns": { + "unknown|unknown|abc": { + "tool_signature_hash": "abc", + "query_pattern_frequency": { + "raw prompt containing secret source code": 4, + "status:* user:*": 2, + }, + "common_query_patterns": [ + "raw prompt containing secret source code", + "status:* user:*", + ], + } + }, + } + path.write_text(json.dumps(payload), encoding="utf-8") + + toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path))) + pattern = next(iter(toin._patterns.values())) + + assert pattern.query_pattern_frequency == {"status:* user:*": 2} + assert pattern.common_query_patterns == ["status:* user:*"] + + +def test_filesystem_backend_writes_compact_json(tmp_path) -> None: + path = tmp_path / "toin.json" + FileSystemTOINBackend(str(path)).save({"patterns": {"a": {"value": 1}}}) + + assert "\n" not in path.read_text(encoding="utf-8") + assert " " not in path.read_text(encoding="utf-8") + + +def test_filesystem_backend_skips_oversized_store(tmp_path) -> None: + path = tmp_path / "toin.json" + path.write_text("x" * 100, encoding="utf-8") + + backend = FileSystemTOINBackend(str(path), max_load_bytes=10) + assert backend.load() == {} + assert path.exists() From cde1513c91b6c6c240869bc5660f4b8966197bbc Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Tue, 11 Aug 2026 16:18:53 -0700 Subject: [PATCH 047/138] fix(proxy): guard telemetry and TOIN endpoints Harden telemetry and TOIN routes and detail payloads (#2927). --- headroom/proxy/server.py | 28 +++++++++++------ tests/test_proxy_loopback_gating.py | 48 +++++++++++++++++++++++++++-- 2 files changed, 65 insertions(+), 11 deletions(-) diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py index c26160a4a..21d9fe26c 100644 --- a/headroom/proxy/server.py +++ b/headroom/proxy/server.py @@ -4578,7 +4578,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: } # Telemetry endpoints (Data Flywheel) - @app.get("/v1/telemetry") + @app.get("/v1/telemetry", dependencies=[Depends(_require_loopback)]) async def telemetry_stats(): """Get telemetry statistics for the data flywheel. @@ -4601,7 +4601,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: telemetry = get_telemetry_collector() return telemetry.get_stats() - @app.get("/v1/telemetry/export") + @app.get("/v1/telemetry/export", dependencies=[Depends(_require_loopback)]) async def telemetry_export(): """Export full telemetry data for aggregation. @@ -4617,7 +4617,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: telemetry = get_telemetry_collector() return telemetry.export_stats() - @app.post("/v1/telemetry/import") + @app.post("/v1/telemetry/import", dependencies=[Depends(_require_loopback)]) async def telemetry_import(request: Request): """Import telemetry data from another source. @@ -4631,7 +4631,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: telemetry.import_stats(data) return {"status": "imported", "current_stats": telemetry.get_stats()} - @app.get("/v1/telemetry/tools") + @app.get("/v1/telemetry/tools", dependencies=[Depends(_require_loopback)]) async def telemetry_tools(): """Get telemetry statistics for all tracked tool signatures. @@ -4647,7 +4647,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: "tools": {sig_hash: stats.to_dict() for sig_hash, stats in all_stats.items()}, } - @app.get("/v1/telemetry/tools/{signature_hash}") + @app.get("/v1/telemetry/tools/{signature_hash}", dependencies=[Depends(_require_loopback)]) async def telemetry_tool_detail(signature_hash: str): """Get detailed telemetry for a specific tool signature. @@ -4669,7 +4669,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: } # TOIN (Tool Output Intelligence Network) endpoints - @app.get("/v1/toin/stats") + @app.get("/v1/toin/stats", dependencies=[Depends(_require_loopback)]) async def toin_stats(): """Get overall TOIN statistics. @@ -4687,7 +4687,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: toin = get_toin() return toin.get_stats() - @app.get("/v1/toin/patterns") + @app.get("/v1/toin/patterns", dependencies=[Depends(_require_loopback)]) async def toin_patterns(limit: int = 20): """List TOIN patterns with most samples. @@ -4742,7 +4742,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: return patterns_list[:limit] - @app.get("/v1/toin/pattern/{hash_prefix}") + @app.get("/v1/toin/pattern/{hash_prefix}", dependencies=[Depends(_require_loopback)]) async def toin_pattern_detail(hash_prefix: str): """Get detailed TOIN pattern info by hash prefix. @@ -4761,7 +4761,17 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: # Search for pattern with matching hash prefix for sig_hash, pattern_dict in patterns_data.items(): if sig_hash.startswith(hash_prefix): - return pattern_dict + # Keep this response aligned with /v1/toin/patterns while + # excluding query text, field semantics, and other internal + # learning state from the detail endpoint. + return { + "compressions": pattern_dict.get("total_compressions", 0), + "retrievals": pattern_dict.get("total_retrievals", 0), + "retrieval_rate": pattern_dict.get("retrieval_rate", 0.0), + "confidence": pattern_dict.get("confidence", 0.0), + "skip_recommended": pattern_dict.get("skip_compression_recommended", False), + "optimal_max_items": pattern_dict.get("optimal_max_items", 20), + } raise HTTPException( status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}" diff --git a/tests/test_proxy_loopback_gating.py b/tests/test_proxy_loopback_gating.py index 62713af86..7e48dabf6 100644 --- a/tests/test_proxy_loopback_gating.py +++ b/tests/test_proxy_loopback_gating.py @@ -22,6 +22,14 @@ from headroom.proxy.server import ProxyConfig, create_app GATED = [ ("get", "/transformations/feed"), ("post", "/cache/clear"), + ("get", "/v1/telemetry"), + ("get", "/v1/telemetry/export"), + ("post", "/v1/telemetry/import"), + ("get", "/v1/telemetry/tools"), + ("get", "/v1/telemetry/tools/example"), + ("get", "/v1/toin/stats"), + ("get", "/v1/toin/patterns"), + ("get", "/v1/toin/pattern/example"), ] @@ -71,8 +79,44 @@ def test_non_loopback_caller_gets_404(method: str, path: str) -> None: @pytest.mark.parametrize("method,path", GATED) def test_loopback_caller_allowed(method: str, path: str) -> None: client = _loopback_client() - resp = client.request(method, path) - assert resp.status_code == 200, resp.text + resp = client.request(method, path, json={} if method == "post" else None) + # Detail routes legitimately return 404 when their test key is absent; + # the companion non-loopback test proves the guard itself. + assert resp.status_code in {200, 404, 422}, resp.text + + +def test_toin_pattern_detail_whitelists_learned_payload(monkeypatch: pytest.MonkeyPatch) -> None: + class FakeTOIN: + def export_patterns(self): + return { + "patterns": { + "unknown|unknown|abc123": { + "sample_size": 10, + "total_compressions": 8, + "total_retrievals": 2, + "retrieval_rate": 0.25, + "confidence": 0.4, + "skip_compression_recommended": False, + "optimal_max_items": 20, + "query_pattern_frequency": {"secret prompt": 1}, + "common_query_patterns": ["secret prompt"], + "field_semantics": {"secret": "value"}, + } + } + } + + monkeypatch.setattr("headroom.proxy.server.get_toin", lambda: FakeTOIN()) + response = _loopback_client().get("/v1/toin/pattern/unknown") + + assert response.status_code == 200 + assert response.json() == { + "compressions": 8, + "retrievals": 2, + "retrieval_rate": 0.25, + "confidence": 0.4, + "skip_recommended": False, + "optimal_max_items": 20, + } # CCR data endpoints — cached session content, gated to 404 off-loopback (#1227). From d0c1f5b8ad68c7a44ed3aaa0fe40e3a656950123 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Tue, 11 Aug 2026 16:18:57 -0700 Subject: [PATCH 048/138] fix(ccr): avoid injecting tool on chat streaming Avoid unsupported CCR tool injection on OpenAI chat streaming (#2924). --- headroom/proxy/handlers/openai.py | 33 +++++++++++++++++-- .../test_openai_chat_ccr_injection.py | 16 +++++++++ 2 files changed, 46 insertions(+), 3 deletions(-) create mode 100644 tests/test_proxy/test_openai_chat_ccr_injection.py diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py index 23751c65e..7eb55fa9b 100644 --- a/headroom/proxy/handlers/openai.py +++ b/headroom/proxy/handlers/openai.py @@ -979,6 +979,18 @@ def _should_buffer_openai_responses_stream_ccr( ) +def _should_inject_openai_chat_ccr_tool(*, ccr_inject_tool: bool, stream: bool) -> bool: + """Return whether chat-completions can redeem an injected CCR tool. + + The chat streaming path forwards SSE events immediately and deliberately + does not run the response continuation loop. Injecting ``headroom_retrieve`` + there makes OpenAI-compatible clients attempt an unknown tool call. The + non-streaming path can intercept and resolve it; Responses streaming has a + separate buffered-CCR path and is unaffected by this predicate. + """ + return bool(ccr_inject_tool and not stream) + + def _responses_input_to_items(input_data: Any) -> list[dict[str, Any]]: """Normalize a Responses ``input`` field into an item list for CCR continuation. @@ -3410,19 +3422,34 @@ class OpenAIHandlerMixin: # anchored on the previous turn's tool list never busts. tools = body.get("tools") _original_tools = tools # Preserve for diagnostic / future retry + can_inject_ccr_tool = _should_inject_openai_chat_ccr_tool( + ccr_inject_tool=self.config.ccr_inject_tool, + stream=stream, + ) if ( self.config.ccr_inject_tool or self.config.ccr_inject_system_instructions ) and not _bypass: + if self.config.ccr_inject_tool and stream: + logger.info( + f"[{request_id}] CCR: skipping retrieval-tool injection for " + "OpenAI chat streaming; this path cannot intercept tool calls" + ) injector = CCRToolInjector( provider="openai", inject_tool=False, # routed through sticky helper below - inject_system_instructions=self.config.ccr_inject_system_instructions, + inject_system_instructions=( + self.config.ccr_inject_system_instructions and not stream + ), ) injector.scan_for_markers(optimized_messages) - if self.config.ccr_inject_system_instructions and injector.has_compressed_content: + if ( + self.config.ccr_inject_system_instructions + and not stream + and injector.has_compressed_content + ): optimized_messages = injector.inject_into_system_message(optimized_messages) - if self.config.ccr_inject_tool: + if can_inject_ccr_tool: from headroom.proxy.helpers import ( apply_session_sticky_ccr_tool, has_new_ccr_markers, diff --git a/tests/test_proxy/test_openai_chat_ccr_injection.py b/tests/test_proxy/test_openai_chat_ccr_injection.py new file mode 100644 index 000000000..030228685 --- /dev/null +++ b/tests/test_proxy/test_openai_chat_ccr_injection.py @@ -0,0 +1,16 @@ +"""Streaming chat CCR injection must not advertise an unredeemable tool.""" + +from headroom.proxy.handlers.openai import _should_inject_openai_chat_ccr_tool + + +def test_streaming_chat_does_not_inject_ccr_tool() -> None: + assert _should_inject_openai_chat_ccr_tool(ccr_inject_tool=True, stream=True) is False + + +def test_non_streaming_chat_still_injects_ccr_tool() -> None: + assert _should_inject_openai_chat_ccr_tool(ccr_inject_tool=True, stream=False) is True + + +def test_disabled_ccr_never_injects_tool() -> None: + assert _should_inject_openai_chat_ccr_tool(ccr_inject_tool=False, stream=False) is False + assert _should_inject_openai_chat_ccr_tool(ccr_inject_tool=False, stream=True) is False From ae384862a4950cec057103e9daf75e74107640df Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Wed, 12 Aug 2026 06:45:37 +0530 Subject: [PATCH 049/138] fix(wrap/opencode): verify the opencode binary before mutating config Verify the OpenCode executable before changing configuration. --- headroom/cli/wrap.py | 22 ++++++++++++++++----- tests/test_cli/test_wrap_opencode.py | 29 ++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 5 deletions(-) diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py index 094454206..212b52261 100644 --- a/headroom/cli/wrap.py +++ b/headroom/cli/wrap.py @@ -6947,6 +6947,20 @@ def opencode( ) subscription_resolution = _require_copilot_subscription_resolution() + # Verify the opencode binary exists BEFORE mutating any config. Otherwise a + # missing binary leaves headroom MCP/Serena/memory entries in the user's + # opencode config and an injected AGENTS.md, then errors with no cleanup -- + # the config-before-verify anti-pattern (#1614). Siblings (claude, codex, + # goose, omp) already check first. `--prepare-only` intentionally writes + # config without launching, so it is exempt. + opencode_bin: str | None = None + if not prepare_only: + opencode_bin = shutil.which("opencode") + if not opencode_bin: + click.echo("Error: 'opencode' not found in PATH.") + click.echo("Install OpenCode: https://opencode.ai") + raise SystemExit(1) + # Snapshot OpenCode config.json BEFORE any wrap-time mutation so # `headroom unwrap opencode` can restore the user's pre-wrap state. _opencode_config_file, _opencode_backup_file = opencode_config_paths() @@ -6987,11 +7001,9 @@ def opencode( inject_opencode_provider_config(port) return - opencode_bin = shutil.which("opencode") - if not opencode_bin: - click.echo("Error: 'opencode' not found in PATH.") - click.echo("Install OpenCode: https://opencode.ai") - raise SystemExit(1) + # Past the prepare-only return the launch path always ran the binary check + # above, so opencode_bin is resolved. + assert opencode_bin is not None # Register our proxy client marker BEFORE _ensure_proxy so that another # wrapper's cleanup sees us as an active client and doesn't terminate a diff --git a/tests/test_cli/test_wrap_opencode.py b/tests/test_cli/test_wrap_opencode.py index f7cdaf1e5..55914fcef 100644 --- a/tests/test_cli/test_wrap_opencode.py +++ b/tests/test_cli/test_wrap_opencode.py @@ -364,6 +364,35 @@ def test_wrap_opencode_missing_binary_errors_clearly( assert "'opencode' not found in PATH" in result.output +def test_wrap_opencode_missing_binary_does_not_mutate_config( + runner: CliRunner, + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + """A missing opencode binary must not leave memory side-effects behind (#1614 class). + + The MCP/Serena registrations are already gated on ``registrar.detect()``, but + the ``--memory`` injections (AGENTS.md, the .headroom dir, the memory MCP + config) are not -- they ran unconditionally before the binary check. Verify + the binary first, like claude/codex/goose/omp, so an absent tool cannot write + those and then error with nothing launched. + """ + monkeypatch.chdir(tmp_path) + monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False) + _set_test_home(monkeypatch, tmp_path) + + agents_md = tmp_path / "AGENTS.md" + headroom_dir = tmp_path / ".headroom" + + with patch.object(wrap_mod.shutil, "which", return_value=None): + result = runner.invoke(main, ["wrap", "opencode", "--memory"]) + + assert result.exit_code == 1 + assert "'opencode' not found in PATH" in result.output + assert not agents_md.exists(), "AGENTS.md was created before the missing-binary check" + assert not headroom_dir.exists(), ".headroom dir was created before the missing-binary check" + + def test_wrap_opencode_prepare_only_injects_config( runner: CliRunner, tmp_path: Path, From c093bf11eb5f356f71367ebb7b56ae3c2b434a12 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Wed, 12 Aug 2026 06:45:40 +0530 Subject: [PATCH 050/138] fix(wrap/claude): keep --1m effective when an explicit --model is passed through Ensure explicit Claude model arguments retain the 1M context suffix (#2915). --- headroom/cli/wrap.py | 43 +++++++++++++++++-- .../test_wrap_claude_vertex_proxy_env.py | 40 +++++++++++++++++ tests/test_cli/test_wrap_helpers.py | 29 +++++++++++++ 3 files changed, 108 insertions(+), 4 deletions(-) diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py index 212b52261..3db3151e3 100644 --- a/headroom/cli/wrap.py +++ b/headroom/cli/wrap.py @@ -303,6 +303,33 @@ def _resolve_1m_model(current: str | None) -> str: return base if base.endswith(_CONTEXT_1M_SUFFIX) else f"{base}{_CONTEXT_1M_SUFFIX}" +def _apply_1m_to_claude_args(args: tuple[str, ...]) -> tuple[tuple[str, ...], str | None]: + """Add the ``[1m]`` suffix to an explicit ``--model`` in pass-through args. + + Claude Code gives the ``--model`` CLI flag precedence over the + ``ANTHROPIC_MODEL`` env var, so when a user passes both ``--1m`` and + ``--model X`` the env-var suffix is silently shadowed and the session caps at + 200k (#2915). Rewriting the flag's value the same way ``_resolve_1m_model`` + rewrites the env var keeps ``--1m`` effective on the higher-precedence flag. + + Handles ``--model VALUE`` and ``--model=VALUE`` (the first occurrence only, as + Claude Code honours the first). Idempotent via ``_resolve_1m_model``. Returns + ``(new_args, rewritten_value)``; ``rewritten_value`` is ``None`` when no + ``--model`` was present (the env-var path already covers that case). + """ + out = list(args) + for i, arg in enumerate(out): + if arg == "--model" and i + 1 < len(out): + rewritten = _resolve_1m_model(out[i + 1]) + out[i + 1] = rewritten + return tuple(out), rewritten + if arg.startswith("--model="): + rewritten = _resolve_1m_model(arg.split("=", 1)[1]) + out[i] = f"--model={rewritten}" + return tuple(out), rewritten + return tuple(out), None + + def _normalize_tool_search_mode(value: str) -> str: """Validate an ``ENABLE_TOOL_SEARCH`` value and return it normalized. @@ -4728,10 +4755,18 @@ def claude( # force it via ANTHROPIC_MODEL on the launched process. if context_1m: env[_ANTHROPIC_MODEL_ENV] = _resolve_1m_model(env.get(_ANTHROPIC_MODEL_ENV)) - click.echo( - f" {_ANTHROPIC_MODEL_ENV}={env[_ANTHROPIC_MODEL_ENV]} " - "(1M context window; issue #1158)" - ) + # An explicit pass-through --model outranks ANTHROPIC_MODEL in Claude + # Code, so add the suffix there too or the env var is silently + # shadowed and the window stays 200k (#2915). Report what will + # actually take effect rather than the shadowed env value. + claude_args, _model_flag_1m = _apply_1m_to_claude_args(claude_args) + if _model_flag_1m is not None: + click.echo(f" --model {_model_flag_1m} (1M context window; issue #1158)") + else: + click.echo( + f" {_ANTHROPIC_MODEL_ENV}={env[_ANTHROPIC_MODEL_ENV]} " + "(1M context window; issue #1158)" + ) result = subprocess.run([claude_bin, *claude_args], env=env) raise SystemExit(result.returncode) diff --git a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py index 546b31cd8..69c8a03f9 100644 --- a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py +++ b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py @@ -160,6 +160,46 @@ def test_wrap_claude_sibling_note_accurate_under_1m_and_tool_search_optouts( assert "kept on" not in output +def test_wrap_claude_1m_adds_suffix_to_passthrough_model_flag( + runner: CliRunner, monkeypatch: pytest.MonkeyPatch +) -> None: + # #2915: Claude Code's --model CLI flag outranks ANTHROPIC_MODEL, so with + # both --1m and an explicit --model the env-var [1m] suffix is shadowed and + # the window silently caps at 200k. The wrapper must add the suffix to the + # pass-through flag so the 1M window actually activates. + captured, output = _invoke_wrap_claude( + runner, + monkeypatch, + env={}, + extra_args=("--1m", "--model", "opusplan"), + ) + assert captured["child_cmd"] == ["/usr/bin/claude", "--model", "opusplan[1m]"] + # The banner reports what actually takes effect, not the shadowed env value. + assert "--model opusplan[1m]" in output + + +def test_wrap_claude_1m_adds_suffix_to_equals_model_flag( + runner: CliRunner, monkeypatch: pytest.MonkeyPatch +) -> None: + captured, _output = _invoke_wrap_claude( + runner, + monkeypatch, + env={}, + extra_args=("--1m", "--model=opusplan"), + ) + assert captured["child_cmd"] == ["/usr/bin/claude", "--model=opusplan[1m]"] + + +def test_wrap_claude_1m_without_model_flag_still_uses_env( + runner: CliRunner, monkeypatch: pytest.MonkeyPatch +) -> None: + # No pass-through --model: ANTHROPIC_MODEL carries the suffix as before, and + # the launched command is untouched. + captured, _output = _invoke_wrap_claude(runner, monkeypatch, env={}, extra_args=("--1m",)) + assert captured["child_cmd"] == ["/usr/bin/claude"] + assert captured["child_env"]["ANTHROPIC_MODEL"].endswith("[1m]") + + def test_wrap_claude_tool_search_banner_line_still_accurate_when_active( runner: CliRunner, monkeypatch: pytest.MonkeyPatch ) -> None: diff --git a/tests/test_cli/test_wrap_helpers.py b/tests/test_cli/test_wrap_helpers.py index a1366b47e..e0bc16928 100644 --- a/tests/test_cli/test_wrap_helpers.py +++ b/tests/test_cli/test_wrap_helpers.py @@ -109,6 +109,35 @@ def test_wrap_claude_allows_claude_print_short_flag_in_passthrough_args() -> Non assert result.exit_code == 0, result.output +# --------------------------------------------------------------------------- +# _apply_1m_to_claude_args — add the [1m] suffix to an explicit pass-through +# --model so it survives Claude Code's CLI-over-env precedence (#2915). +# --------------------------------------------------------------------------- +def test_apply_1m_rewrites_model_flag_value() -> None: + args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model", "opusplan")) + assert args == ("--model", "opusplan[1m]") + assert rewritten == "opusplan[1m]" + + +def test_apply_1m_rewrites_equals_model_flag() -> None: + args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model=opusplan",)) + assert args == ("--model=opusplan[1m]",) + assert rewritten == "opusplan[1m]" + + +def test_apply_1m_is_idempotent_on_already_suffixed_model() -> None: + args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model", "opusplan[1m]")) + assert args == ("--model", "opusplan[1m]") + assert rewritten == "opusplan[1m]" + + +def test_apply_1m_noop_without_model_flag() -> None: + original = ("--permission-mode", "auto", "--resume") + args, rewritten = wrap_mod._apply_1m_to_claude_args(original) + assert args == original + assert rewritten is None + + # --------------------------------------------------------------------------- # _run_proxy_only_watcher — must print banner, call setup callback, install # signal handlers, and clean up. Heavily mocked since the real watcher From def3d76e5ab4665e609b51bfba54dd6d25116925 Mon Sep 17 00:00:00 2001 From: gglucass Date: Wed, 12 Aug 2026 03:15:44 +0200 Subject: [PATCH 051/138] fix(cache): mirror client cache_control positions instead of single-marker consolidation Preserve client cache-control breakpoint positions. --- headroom/cache/compression_store.py | 18 +++ headroom/cache/prefix_tracker.py | 145 +++++++++++++---- headroom/proxy/handlers/anthropic.py | 48 +++++- headroom/proxy/helpers.py | 106 ++++++++++++ tests/test_cache_breakpoint_diagnostics.py | 180 +++++++++++++++++++++ tests/test_cache_control_move_bust.py | 174 ++++++++++++++++++++ 6 files changed, 635 insertions(+), 36 deletions(-) create mode 100644 tests/test_cache_breakpoint_diagnostics.py diff --git a/headroom/cache/compression_store.py b/headroom/cache/compression_store.py index 72e6ca34f..bbda697cd 100644 --- a/headroom/cache/compression_store.py +++ b/headroom/cache/compression_store.py @@ -52,6 +52,10 @@ DEFAULT_CCR_TTL_SECONDS = 1800 # session-scale; override via HEADROOM_CCR_TTL_S CCR_TTL_SECONDS_ENV = "HEADROOM_CCR_TTL_SECONDS" _RETRIEVAL_LOG_PREVIEW_CHARS = 4096 +# Previews carry verbatim tool-result content (post-redaction), which makes +# proxy.log too sensitive for users to share in bug reports. Set to +# 0/false/no/off to log byte counts only. +PAYLOAD_PREVIEW_ENV = "HEADROOM_LOG_PAYLOAD_PREVIEW" _SECRET_KEY_VALUE_RE = re.compile( r"(?i)\b([A-Z0-9_-]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|AUTH)[A-Z0-9_-]*)" r"(\s*[:=]\s*)([\"']?)([^\"'\s,}]+)" @@ -108,7 +112,21 @@ def _redact_retrieval_log_payload(payload: str) -> str: return _API_KEY_VALUE_RE.sub("sk-[REDACTED]", redacted) +def _payload_preview_enabled() -> bool: + raw = os.environ.get(PAYLOAD_PREVIEW_ENV) + if raw is None: + return True + return raw.strip().lower() not in ("0", "false", "no", "off") + + def _payload_for_retrieval_log(payload: str) -> dict[str, Any]: + if not _payload_preview_enabled(): + return { + "payload_chars": len(payload), + "payload_preview_chars": 0, + "payload_truncated": len(payload) > 0, + "payload_preview": "", + } redacted = _redact_retrieval_log_payload(payload) preview = redacted[:_RETRIEVAL_LOG_PREVIEW_CHARS] truncated = len(redacted) > len(preview) diff --git a/headroom/cache/prefix_tracker.py b/headroom/cache/prefix_tracker.py index 178300295..8157e9e9a 100644 --- a/headroom/cache/prefix_tracker.py +++ b/headroom/cache/prefix_tracker.py @@ -633,9 +633,31 @@ def _breakpoint_index( return relation.stable_prefix_blocks - 1 +def _client_marker_positions( + client_messages: list[dict[str, Any]], +) -> list[tuple[int, int, dict[str, Any]]]: + """(message index, block index, marker) for every CLIENT cache_control. + + Block-level, not one-per-message: clients mark multiple blocks within a + single long message (Claude Code does this on 1-2-message requests with a + large first message), and the ~20-block lookback applies within a message + just as it does across messages. Only block-style content carries markers. + """ + positions: list[tuple[int, int, dict[str, Any]]] = [] + for i, msg in enumerate(client_messages): + content = msg.get("content") if isinstance(msg, dict) else None + if not isinstance(content, list): + continue + for bi, b in enumerate(content): + if isinstance(b, dict) and isinstance(b.get("cache_control"), dict): + positions.append((i, bi, b["cache_control"])) + return positions + + def normalize_message_cache_control( messages: list[dict[str, Any]], previous_forwarded_messages: list[dict[str, Any]] | None = None, + client_messages: list[dict[str, Any]] | None = None, ) -> list[dict[str, Any]]: """Own message-level cache_control placement so breakpoints stay bounded. @@ -645,25 +667,35 @@ def normalize_message_cache_control( hard-errors at **>4 cache_control blocks total** (system + tools + messages), so on a long conversation the accumulation eventually 400s. - Fix: strip EVERY message-level cache_control and re-place a **single** - ephemeral breakpoint. Pure append-only growth keeps it on the newest block, - which both reads the prior write and writes the appended tail. If last turn's - counterpart proves that the tail was rewritten, it is placed at the end of - the byte-stable leading run instead. One breakpoint caches the prefix up to - it, and — because the provider's cache key is message CONTENT, not marker - presence (moving the - breakpoint forward is the documented client pattern and it hits) — stripping - and re-placing markers never busts. system/tools breakpoints live outside - ``messages`` and are left untouched (they still count toward the 4 limit, so - holding messages to one breakpoint leaves room for them). + Fix: strip EVERY message-level cache_control, then re-place markers at the + positions the CLIENT's current request marks (``client_messages``). The + client's positions are load-bearing, not redundant: Anthropic resolves each + breakpoint by walking back **at most ~20 content blocks** for a prior cache + entry, and agentic clients (Claude Code) keep a marker on the previous + turn's newest message precisely so the new turn's write can chain to the + old entry. Collapsing to a single newest-block marker breaks that chain + whenever one turn adds >20 blocks (typical for tool-heavy turns): the + lookback misses, the entire message history silently re-bills as cache + creation, and a marker anchored short of the final block leaves the tail + billing as fully uncached input. Mirroring the client's positions bounds + accumulation identically (the client manages its own 4-marker budget) while + preserving its read/write chaining. - Headroom owns WHERE the breakpoint goes; the client still owns WHAT it says: - the re-placed marker reuses the newest client marker verbatim, so an explicit - ``ttl`` (e.g. ``"1h"``) survives consolidation instead of silently - downgrading to the 5-minute default (#2375). + The provider's cache key is message CONTENT, not marker presence (moving + the breakpoint forward is the documented client pattern and it hits), so + stripping replay leftovers and re-placing markers never busts. system/tools + breakpoints live outside ``messages`` and are left untouched. - Only block-style (list) content can carry cache_control; string content is - left as-is. Returns the input unchanged when there is nothing to normalize. + Headroom owns WHICH BLOCK carries each marker; the client owns the message + positions and the marker values, so an explicit ``ttl`` (e.g. ``"1h"``) + survives per position instead of silently downgrading (#2375). The newest + position uses stable-run anchoring for proven rewritten tails; earlier + positions go on their message's last block. + + Without ``client_messages`` (or when the transformed list no longer aligns + with it), falls back to the legacy single-marker consolidation. Only + block-style (list) content can carry cache_control; string content is left + as-is. Returns the input unchanged when there is nothing to normalize. """ changed = False out: list[dict[str, Any]] = [] @@ -690,22 +722,75 @@ def normalize_message_cache_control( last_block_idx = i else: out.append(msg) - # Re-place exactly one breakpoint on the last block-style message. - if last_block_idx >= 0: - msg = out[last_block_idx] - content = list(msg["content"]) - marker = dict(last_marker) if last_marker else {"type": "ephemeral"} - breakpoint_index = _breakpoint_index( - content, msg, last_block_idx, previous_forwarded_messages - ) + + def _place( + target_idx: int, + marker: dict[str, Any], + *, + anchor: bool, + block_idx: int | None = None, + ) -> bool: + msg = out[target_idx] + content = msg.get("content") + if not isinstance(content, list) or not content: + return False + content = list(content) + if block_idx is not None and 0 <= block_idx < len(content): + # Transforms can shift block indices (e.g. a dropped thinking + # block); a slightly-off placement still lands on a stable block + # in the same message, which is harmless — markers are not part + # of the provider's cache key. + breakpoint_index = block_idx + elif anchor: + breakpoint_index = _breakpoint_index( + content, msg, target_idx, previous_forwarded_messages + ) + else: + breakpoint_index = len(content) - 1 # Anthropic content blocks are dictionaries, but callers can still - # supply mixed list content. The newest block is known to be a dict - # from the scan above; fall back to it rather than attempting ``**`` - # on a scalar stable-boundary element. + # supply mixed list content. Fall back to the newest block rather than + # attempting ``**`` on a scalar stable-boundary element, and skip the + # message entirely when even that is not a dict. if not isinstance(content[breakpoint_index], dict): breakpoint_index = len(content) - 1 - content[breakpoint_index] = {**content[breakpoint_index], "cache_control": marker} - out[last_block_idx] = {**msg, "content": content} + if not isinstance(content[breakpoint_index], dict): + return False + content[breakpoint_index] = {**content[breakpoint_index], "cache_control": dict(marker)} + out[target_idx] = {**msg, "content": content} + return True + + # Preferred: mirror the client's marker positions 1:1, block-level. The + # transform pipeline preserves message count, so index alignment is the + # invariant; fall back to legacy consolidation if it ever does not hold, + # or when the client marked nothing (legacy still places one so the + # prefix caches). The newest client marker keeps stable-run anchoring + # when the client placed it on its message's final block (intent: "cache + # through the end"); an explicit mid-message marker is honored verbatim. + if client_messages is not None and len(client_messages) == len(messages): + positions = _client_marker_positions(client_messages) + if positions: + placed_any = False + newest_mi, newest_bi, _ = positions[-1] + newest_client_content = client_messages[newest_mi].get("content") + newest_on_final_block = ( + isinstance(newest_client_content, list) + and newest_bi == len(newest_client_content) - 1 + ) + for mi, bi, marker in positions: + is_newest = (mi, bi) == (newest_mi, newest_bi) + if is_newest and newest_on_final_block: + placed = _place(mi, marker, anchor=True) + else: + placed = _place(mi, marker, anchor=False, block_idx=bi) + placed_any = placed or placed_any + if placed_any or changed: + return out + return messages + + # Legacy: re-place exactly one breakpoint on the last block-style message. + if last_block_idx >= 0: + marker = dict(last_marker) if last_marker else {"type": "ephemeral"} + _place(last_block_idx, marker, anchor=True) changed = True return out if changed else messages diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index 8e12401b7..059fdb8f0 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -290,7 +290,16 @@ class AnthropicHandlerMixin: new_content: list[dict[str, Any]] = [] appended = False for block in content: - if not appended and isinstance(block, dict) and block.get("type") == "text": + if ( + not appended + and isinstance(block, dict) + and block.get("type") == "text" + # Never mutate a block carrying the client's cache + # breakpoint: the client re-sends the original bytes + # next turn, so any injection here busts the prefix + # cache at this message from then on. + and "cache_control" not in block + ): existing = block.get("text", "") new_content.append({**block, "text": existing + "\n\n" + context_text}) appended = True @@ -736,6 +745,16 @@ class AnthropicHandlerMixin: if input_event.tools is not None: body["tools"] = input_event.tools + # Snapshot the client's cache_control breakpoints before any + # transform runs; paired with the outbound count right before + # forwarding (event=cache_breakpoints) so a dropped or moved + # final breakpoint is self-diagnosing from proxy.log alone. + from headroom.proxy.helpers import count_cache_breakpoints + + inbound_breakpoints = count_cache_breakpoints( + body.get("system"), messages, body.get("tools") + ) + # Validate message array size if len(messages) > MAX_MESSAGE_ARRAY_LENGTH: await _finalize_pre_upstream() @@ -1661,12 +1680,19 @@ class AnthropicHandlerMixin: # Own cache_control placement: the client moves the breakpoint each # turn and the overlay replays past markers, so they accumulate ~1/turn - # and Anthropic hard-errors at >4. Strip message-level markers and keep - # one breakpoint. Pure appends advance it to the newest block; a - # proven rewritten tail anchors it at the byte-stable boundary so - # that the same prefix is readable next turn. Applied last so the + # and Anthropic hard-errors at >4. Strip message-level markers and + # re-place them at the CLIENT's current positions: Anthropic resolves + # each breakpoint with a ~20-content-block lookback, and the client's + # previous-message marker is the read anchor that lets a big turn's + # write chain to the prior entry. Collapsing to one newest-block + # marker breaks that chain on tool-heavy turns (silent full re-write) + # and can leave the tail billing uncached. Applied last so the # forwarded AND recorded (next_forwarded) messages stay bounded. - _norm = normalize_message_cache_control(optimized_messages, previous_forwarded_messages) + _norm = normalize_message_cache_control( + optimized_messages, + previous_forwarded_messages, + client_messages=original_client_messages, + ) if _norm is not optimized_messages: optimized_messages = _norm @@ -2971,6 +2997,16 @@ class AnthropicHandlerMixin: "upstream request for server-side retrieval handling" ) + from headroom.proxy.helpers import log_cache_breakpoints + + log_cache_breakpoints( + request_id=request_id, + inbound=inbound_breakpoints, + outbound=count_cache_breakpoints( + body.get("system"), body.get("messages"), body.get("tools") + ), + ) + if stream and not buffered_stream_ccr: self.pipeline_extensions.emit( PipelineStage.POST_SEND, diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py index 26e360552..31cbe4635 100644 --- a/headroom/proxy/helpers.py +++ b/headroom/proxy/helpers.py @@ -347,6 +347,112 @@ def log_outbound_request( ) +def count_cache_breakpoints( + system: Any, + messages: Any, + tools: Any, +) -> dict[str, int]: + """Count client ``cache_control`` breakpoints per request section. + + Besides raw counts, records how far from the END of the message list the + last marker sits (``last_marker_tail`` = messages after the last marked + one). A dropped or backward-moved final breakpoint — the signature of a + "large uncached tail next to a healthy cache read" billing regression — + shows up as ``last_marker_tail`` growing between inbound and outbound. + Nested markers inside ``tool_result`` list content are counted too, so a + transform that rewrites sub-blocks can't lose one invisibly. + """ + system_count = 0 + if isinstance(system, list): + system_count = sum(1 for b in system if isinstance(b, dict) and "cache_control" in b) + + tools_count = 0 + if isinstance(tools, list): + tools_count = sum(1 for t in tools if isinstance(t, dict) and "cache_control" in t) + + message_count = 0 + messages_total = 0 + last_marker_index = -1 + if isinstance(messages, list): + message_count = len(messages) + for i, msg in enumerate(messages): + if not isinstance(msg, dict): + continue + found = 1 if "cache_control" in msg else 0 + content = msg.get("content") + if isinstance(content, list): + for block in content: + if not isinstance(block, dict): + continue + if "cache_control" in block: + found += 1 + inner = block.get("content") + if isinstance(inner, list): + found += sum( + 1 for sub in inner if isinstance(sub, dict) and "cache_control" in sub + ) + if found: + messages_total += found + last_marker_index = i + + last_marker_tail = message_count - 1 - last_marker_index if last_marker_index >= 0 else -1 + return { + "system": system_count, + "tools": tools_count, + "messages": messages_total, + "total": system_count + tools_count + messages_total, + "message_count": message_count, + "last_marker_tail": last_marker_tail, + } + + +def log_cache_breakpoints( + *, + request_id: str | None, + inbound: dict[str, int], + outbound: dict[str, int], +) -> None: + """One structured line per request: client breakpoints in vs forwarded out. + + Per realignment build constraints: every cache-affecting decision is + logged. Escalates to WARNING when the forwarded request has fewer + breakpoints than the client sent, or the last marker moved further from + the end of the message list — either one silently un-caches the tail. + """ + dropped = outbound["total"] < inbound["total"] + tail_grew = ( + inbound["last_marker_tail"] >= 0 + and outbound["last_marker_tail"] != inbound["last_marker_tail"] + and ( + outbound["last_marker_tail"] < 0 + or outbound["last_marker_tail"] > inbound["last_marker_tail"] + ) + ) + log = logger.warning if (dropped or tail_grew) else logger.info + log( + "event=cache_breakpoints request_id=%s " + "in_total=%d out_total=%d in_system=%d out_system=%d " + "in_tools=%d out_tools=%d in_messages=%d out_messages=%d " + "in_msg_count=%d out_msg_count=%d in_last_tail=%d out_last_tail=%d " + "dropped=%s tail_grew=%s", + request_id or "", + inbound["total"], + outbound["total"], + inbound["system"], + outbound["system"], + inbound["tools"], + outbound["tools"], + inbound["messages"], + outbound["messages"], + inbound["message_count"], + outbound["message_count"], + inbound["last_marker_tail"], + outbound["last_marker_tail"], + "true" if dropped else "false", + "true" if tail_grew else "false", + ) + + def log_memory_injection( *, request_id: str, diff --git a/tests/test_cache_breakpoint_diagnostics.py b/tests/test_cache_breakpoint_diagnostics.py new file mode 100644 index 000000000..03786dc31 --- /dev/null +++ b/tests/test_cache_breakpoint_diagnostics.py @@ -0,0 +1,180 @@ +"""Tests for cache_control breakpoint diagnostics and log-privacy switches. + +Covers the three pieces added for the uncached-tail investigation: +- ``count_cache_breakpoints`` / ``log_cache_breakpoints`` (proxy helpers) +- the ``HEADROOM_LOG_PAYLOAD_PREVIEW`` kill switch (compression store) +- the injection guard that keeps proactive expansion out of breakpointed blocks +""" + +from __future__ import annotations + +import logging + +from headroom.cache.compression_store import _payload_for_retrieval_log +from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin +from headroom.proxy.helpers import count_cache_breakpoints, log_cache_breakpoints + +_CC = {"cache_control": {"type": "ephemeral"}} + + +def _claude_code_style_request() -> tuple[list[dict], list[dict], list[dict]]: + """System/messages/tools shaped like a real Claude Code request.""" + system = [ + {"type": "text", "text": "You are Claude Code."}, + {"type": "text", "text": "project instructions", **_CC}, + ] + tools = [ + {"name": "Bash", "input_schema": {}}, + {"name": "Read", "input_schema": {}, **_CC}, + ] + messages = [ + {"role": "user", "content": [{"type": "text", "text": "hi", **_CC}]}, + {"role": "assistant", "content": [{"type": "text", "text": "ack"}]}, + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": "t1", + "content": [{"type": "text", "text": "big output"}], + **_CC, + } + ], + }, + ] + return system, messages, tools + + +def test_count_cache_breakpoints_counts_all_sections() -> None: + system, messages, tools = _claude_code_style_request() + stats = count_cache_breakpoints(system, messages, tools) + assert stats["system"] == 1 + assert stats["tools"] == 1 + assert stats["messages"] == 2 + assert stats["total"] == 4 + assert stats["message_count"] == 3 + assert stats["last_marker_tail"] == 0 # last message carries a marker + + +def test_count_cache_breakpoints_counts_nested_tool_result_markers() -> None: + messages = [ + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": "t1", + "content": [{"type": "text", "text": "out", **_CC}], + } + ], + } + ] + stats = count_cache_breakpoints("plain system string", messages, None) + assert stats["system"] == 0 + assert stats["tools"] == 0 + assert stats["messages"] == 1 + assert stats["last_marker_tail"] == 0 + + +def test_count_cache_breakpoints_tail_tracks_last_marker() -> None: + messages = [ + {"role": "user", "content": [{"type": "text", "text": "a", **_CC}]}, + {"role": "assistant", "content": [{"type": "text", "text": "b"}]}, + {"role": "user", "content": [{"type": "text", "text": "c"}]}, + ] + stats = count_cache_breakpoints(None, messages, None) + assert stats["last_marker_tail"] == 2 + assert count_cache_breakpoints(None, [], None)["last_marker_tail"] == -1 + + +def test_log_cache_breakpoints_warns_on_dropped_marker(caplog) -> None: + system, messages, tools = _claude_code_style_request() + inbound = count_cache_breakpoints(system, messages, tools) + # Transform "lost" the final breakpoint: strip it from the last message. + stripped = [dict(m) for m in messages] + stripped[2] = { + "role": "user", + "content": [{"type": "tool_result", "tool_use_id": "t1", "content": "compressed"}], + } + outbound = count_cache_breakpoints(system, stripped, tools) + with caplog.at_level(logging.INFO, logger="headroom.proxy"): + log_cache_breakpoints(request_id="r1", inbound=inbound, outbound=outbound) + [record] = caplog.records + assert record.levelno == logging.WARNING + assert "dropped=true" in record.getMessage() + assert "tail_grew=true" in record.getMessage() + + +def test_log_cache_breakpoints_info_when_preserved(caplog) -> None: + system, messages, tools = _claude_code_style_request() + stats = count_cache_breakpoints(system, messages, tools) + with caplog.at_level(logging.INFO, logger="headroom.proxy"): + log_cache_breakpoints(request_id="r1", inbound=stats, outbound=stats) + [record] = caplog.records + assert record.levelno == logging.INFO + assert "dropped=false" in record.getMessage() + + +def test_payload_preview_disabled_omits_content(monkeypatch) -> None: + monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", "0") + payload = "secret file contents: api_key=sk-abcdefghijklmnop" + event = _payload_for_retrieval_log(payload) + assert event["payload_preview"] == "" + assert event["payload_preview_chars"] == 0 + assert event["payload_chars"] == len(payload) + assert event["payload_truncated"] is True + + +def test_payload_preview_enabled_by_default(monkeypatch) -> None: + monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False) + event = _payload_for_retrieval_log("hello world") + assert event["payload_preview"] == "hello world" + + +def test_append_context_skips_breakpointed_text_block() -> None: + messages = [ + { + "role": "user", + "content": [ + {"type": "text", "text": "breakpointed", **_CC}, + {"type": "text", "text": "free"}, + ], + } + ] + result = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn( + messages, "CTX", frozen_message_count=0 + ) + blocks = result[0]["content"] + assert blocks[0]["text"] == "breakpointed" # untouched + assert blocks[1]["text"].endswith("CTX") + + +def test_append_context_no_eligible_block_returns_unchanged() -> None: + messages = [ + { + "role": "user", + "content": [{"type": "text", "text": "breakpointed", **_CC}], + } + ] + result = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn( + messages, "CTX", frozen_message_count=0 + ) + assert result == messages + + +def test_count_cache_breakpoints_tolerates_malformed_shapes() -> None: + messages = [ + "not-a-dict", + {"role": "user", "content": ["scalar-block", {"type": "text", "text": "x", **_CC}]}, + {"role": "user", "content": "plain string"}, + ] + stats = count_cache_breakpoints("system-as-string", messages, "tools-as-string") + assert stats["system"] == 0 + assert stats["tools"] == 0 + assert stats["messages"] == 1 + assert stats["message_count"] == 3 + assert stats["last_marker_tail"] == 1 + + empty = count_cache_breakpoints(None, None, None) + assert empty["total"] == 0 + assert empty["message_count"] == 0 diff --git a/tests/test_cache_control_move_bust.py b/tests/test_cache_control_move_bust.py index 0b74ff92d..3816c7b38 100644 --- a/tests/test_cache_control_move_bust.py +++ b/tests/test_cache_control_move_bust.py @@ -224,3 +224,177 @@ def test_normalize_ttl_survives_many_turns(): conv = normalize_message_cache_control(conv) assert _markers(conv) == 1 assert conv[-1]["content"][-1]["cache_control"] == {"type": "ephemeral", "ttl": "1h"} + + +# ── fix-4: mirror the CLIENT's marker positions (20-block lookback chain) ──── +# Anthropic resolves each breakpoint by walking back at most ~20 content +# blocks. Agentic clients keep a marker on the previous turn's newest message +# as the read anchor; collapsing to a single newest-block marker breaks the +# chain on tool-heavy turns. With client_messages provided, normalize must +# keep exactly the client's positions. + + +def test_normalize_mirrors_client_marker_positions(): + client = [ + B("user", "a", cc=True), + B("assistant", "b"), + B("user", "c", cc=True), # read anchor (previous newest) + B("assistant", "d"), + B("user", "e", cc=True), # newest + ] + # Forwarded form: replay leftovers piled markers onto other messages too. + merged = [ + B("user", "a", cc=True), + B("assistant", "b", cc=True), + B("user", "c", cc=True), + B("assistant", "d", cc=True), + B("user", "e", cc=True), + ] + out = normalize_message_cache_control(merged, client_messages=client) + assert _markers(out) == 3 # exactly the client's three, not one + for idx in (0, 2, 4): + assert "cache_control" in out[idx]["content"][-1], idx + for idx in (1, 3): + assert _markers([out[idx]]) == 0, idx + assert _strip_cache_control(out) == _strip_cache_control(merged) + + +def test_normalize_mirror_preserves_per_position_ttl(): + client = [B_ttl("user", "a", "1h"), B("user", "b", cc=True)] + merged = [B("user", "a", cc=True), B("user", "b", cc=True)] + out = normalize_message_cache_control(merged, client_messages=client) + assert out[0]["content"][-1]["cache_control"] == {"type": "ephemeral", "ttl": "1h"} + assert out[1]["content"][-1]["cache_control"] == {"type": "ephemeral"} + + +def test_normalize_mirror_bounded_across_many_turns(): + """Client moves its pair of markers forward; forwarded stays at client count.""" + conv = [] + for t in range(1, 12): + conv = conv + [B("user", f"turn-{t}")] + # Client marks the newest and second-newest marked position (CC pattern). + client = [dict(m) for m in conv] + client[-1] = B("user", f"turn-{t}", cc=True) + if len(client) >= 2: + client[-2] = B(client[-2]["role"], client[-2]["content"][0]["text"], cc=True) + # Forwarded side accumulated replay leftovers everywhere. + merged = [B(m["role"], m["content"][0]["text"], cc=True) for m in client] + out = normalize_message_cache_control(merged, client_messages=client) + assert _markers(out) == min(2, len(client)) + assert "cache_control" in out[-1]["content"][-1] + + +def test_normalize_falls_back_when_counts_mismatch(): + client = [B("user", "a", cc=True)] # transform changed message count + merged = [B("user", "a", cc=True), B("user", "b", cc=True)] + out = normalize_message_cache_control(merged, client_messages=client) + assert _markers(out) == 1 # legacy consolidation + assert "cache_control" in out[-1]["content"][-1] + + +def test_normalize_falls_back_when_client_has_no_markers(): + client = [B("user", "a"), B("user", "b")] + merged = [B("user", "a", cc=True), B("user", "b")] + out = normalize_message_cache_control(merged, client_messages=client) + assert _markers(out) == 1 # legacy: still place one so the prefix caches + assert "cache_control" in out[-1]["content"][-1] + + +def test_normalize_mirror_skips_string_content_positions(): + # Client marked message 0; forwarded counterpart is string-content (cannot + # carry a marker) — the position is skipped, the rest still mirror. + client = [B("user", "a", cc=True), B("user", "b", cc=True)] + merged = [{"role": "user", "content": "a"}, B("user", "b", cc=True)] + out = normalize_message_cache_control(merged, client_messages=client) + assert _markers(out) == 1 + assert "cache_control" in out[1]["content"][-1] + + +# ── fix-5: block-level mirroring (multiple client markers in one message) ──── + + +def test_normalize_mirrors_multiple_markers_within_one_message(): + """A 2-message request where the client marks TWO blocks of message 0 + (Claude Code's pattern on large first messages) keeps all three markers.""" + big = { + "role": "user", + "content": [ + {"type": "text", "text": "part-1", "cache_control": {"type": "ephemeral"}}, + {"type": "text", "text": "part-2"}, + {"type": "text", "text": "part-3", "cache_control": {"type": "ephemeral"}}, + ], + } + client = [big, B("user", "follow-up", cc=True)] + # Forwarded form: an extra replay leftover on message 1's sibling... use + # identical structure with markers everywhere to prove selective stripping. + merged = [ + { + "role": "user", + "content": [ + {"type": "text", "text": "part-1", "cache_control": {"type": "ephemeral"}}, + {"type": "text", "text": "part-2", "cache_control": {"type": "ephemeral"}}, + {"type": "text", "text": "part-3", "cache_control": {"type": "ephemeral"}}, + ], + }, + B("user", "follow-up", cc=True), + ] + out = normalize_message_cache_control(merged, client_messages=client) + assert _markers(out) == 3 + assert "cache_control" in out[0]["content"][0] + assert "cache_control" not in out[0]["content"][1] + assert "cache_control" in out[0]["content"][2] + assert "cache_control" in out[1]["content"][-1] + assert _strip_cache_control(out) == _strip_cache_control(merged) + + +def test_normalize_mirror_clamps_out_of_range_block_index(): + # Client marked block 2; forwarded message only has 1 block (transform + # merged content) — marker falls back to the last block, not dropped. + client = [ + { + "role": "user", + "content": [ + {"type": "text", "text": "a"}, + {"type": "text", "text": "b"}, + {"type": "text", "text": "c", "cache_control": {"type": "ephemeral"}}, + ], + }, + B("user", "tail", cc=True), + ] + merged = [B("user", "abc-merged"), B("user", "tail", cc=True)] + out = normalize_message_cache_control(merged, client_messages=client) + assert _markers(out) == 2 + assert "cache_control" in out[0]["content"][-1] + assert "cache_control" in out[1]["content"][-1] + + +def test_normalize_mirror_scalar_only_content_is_left_unchanged(): + """Client marks a message whose forwarded counterpart carries only scalar + blocks: nothing can hold a marker and nothing was stripped, so the input + comes back unchanged (identity, not a copy).""" + client = [B("user", "a", cc=True)] + merged = [{"role": "user", "content": ["scalar-only"]}] + out = normalize_message_cache_control(merged, client_messages=client) + assert out is merged + assert _markers(out) == 0 + + +def test_normalize_mirror_scalar_target_still_strips_leftovers(): + # Message 0's forwarded content is scalar-only (marker unplaceable) but a + # replay leftover on message 1 still gets stripped, and message 1 keeps + # its client marker. + client = [B("user", "a", cc=True), B("user", "b", cc=True)] + merged = [ + {"role": "user", "content": ["scalar-only"]}, + { + "role": "user", + "content": [ + {"type": "text", "text": "left-over", "cache_control": {"type": "ephemeral"}}, + {"type": "text", "text": "b"}, + ], + }, + ] + out = normalize_message_cache_control(merged, client_messages=client) + assert _markers(out) == 1 + assert "cache_control" not in out[1]["content"][0] + assert "cache_control" in out[1]["content"][-1] From 0d6866b91a3777475abd58cd8b63a10cd0621e7f Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Wed, 12 Aug 2026 06:45:47 +0530 Subject: [PATCH 052/138] fix(backends/anyllm): convert Anthropic tools and tool_choice to OpenAI shape Convert Anthropic tool requests for AnyLLM OpenAI-compatible backends. --- headroom/backends/anyllm.py | 46 ++++++++++++++++++++-- tests/test_backend_anyllm.py | 75 ++++++++++++++++++++++++++++++++++++ 2 files changed, 117 insertions(+), 4 deletions(-) diff --git a/headroom/backends/anyllm.py b/headroom/backends/anyllm.py index 468d20450..1af994e47 100644 --- a/headroom/backends/anyllm.py +++ b/headroom/backends/anyllm.py @@ -25,6 +25,44 @@ except ImportError: AnyLLM = None # type: ignore +def _convert_anthropic_tool(tool: dict[str, Any]) -> dict[str, Any]: + """Convert an Anthropic tool definition to the OpenAI function shape. + + any-llm speaks OpenAI, so an Anthropic ``{name, description, input_schema}`` + tool must become ``{type: function, function: {name, description, + parameters}}`` before it is forwarded, or the provider ignores/rejects the + tools array and the model never calls a tool. Mirrors the LiteLLM backend's + converter so both OpenAI-compatible backends send the same shape. + """ + func: dict[str, Any] = {"name": tool.get("name", "")} + if "description" in tool: + func["description"] = tool["description"] + if "input_schema" in tool: + func["parameters"] = tool["input_schema"] + return {"type": "function", "function": func} + + +def _convert_tool_choice(choice: Any) -> Any: + """Convert an Anthropic ``tool_choice`` to the OpenAI shape (mirrors LiteLLM). + + Anthropic: ``{"type": "auto"}``, ``{"type": "any"}``, ``{"type": "tool", + "name": ...}``. OpenAI: ``"auto"``, ``"required"``, ``{"type": "function", + "function": {"name": ...}}``. Passing the raw Anthropic dict through makes + the provider reject or ignore it. + """ + if isinstance(choice, str): + return choice + if isinstance(choice, dict): + choice_type = choice.get("type", "auto") + if choice_type == "auto": + return "auto" + if choice_type == "any": + return "required" + if choice_type == "tool": + return {"type": "function", "function": {"name": choice.get("name", "")}} + return "auto" + + class AnyLLMBackend(Backend): """Backend using any-llm for multi-provider support.""" @@ -251,9 +289,9 @@ class AnyLLMBackend(Backend): if "stop_sequences" in body: kwargs["stop"] = body["stop_sequences"] if "tools" in body: - kwargs["tools"] = body["tools"] + kwargs["tools"] = [_convert_anthropic_tool(t) for t in body["tools"]] if "tool_choice" in body: - kwargs["tool_choice"] = body["tool_choice"] + kwargs["tool_choice"] = _convert_tool_choice(body["tool_choice"]) logger.debug(f"any-llm request: provider={self.provider}, model={original_model}") @@ -301,9 +339,9 @@ class AnyLLMBackend(Backend): if "stop_sequences" in body: kwargs["stop"] = body["stop_sequences"] if "tools" in body: - kwargs["tools"] = body["tools"] + kwargs["tools"] = [_convert_anthropic_tool(t) for t in body["tools"]] if "tool_choice" in body: - kwargs["tool_choice"] = body["tool_choice"] + kwargs["tool_choice"] = _convert_tool_choice(body["tool_choice"]) msg_id = f"msg_{uuid.uuid4().hex[:24]}" diff --git a/tests/test_backend_anyllm.py b/tests/test_backend_anyllm.py index 3d56fcb0a..3e1e1a8e1 100644 --- a/tests/test_backend_anyllm.py +++ b/tests/test_backend_anyllm.py @@ -293,6 +293,81 @@ async def test_send_message_builds_anthropic_response(monkeypatch: pytest.Monkey assert instance.calls[0]["stop"] == ["END"] +@pytest.mark.asyncio +async def test_send_message_converts_anthropic_tools_and_tool_choice( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Anthropic tools/tool_choice must reach any-llm in the OpenAI shape. + + any-llm speaks OpenAI; forwarding the raw Anthropic ``input_schema`` tool and + the ``{"type": ...}`` tool_choice makes the provider ignore or reject them, + so the model never calls a tool. Regression for tool use silently not + working on the any-llm backend. + """ + backend, instance = make_backend(monkeypatch) + instance.response = make_response(make_choice("ok", "stop")) + + await backend.send_message( + { + "model": "claude", + "messages": [{"role": "user", "content": "hi"}], + "tools": [ + { + "name": "get_weather", + "description": "look up weather", + "input_schema": { + "type": "object", + "properties": {"city": {"type": "string"}}, + }, + } + ], + "tool_choice": {"type": "any"}, + }, + {}, + ) + + sent = instance.calls[0] + assert sent["tools"] == [ + { + "type": "function", + "function": { + "name": "get_weather", + "description": "look up weather", + "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}, + }, + } + ] + assert sent["tool_choice"] == "required" + + +@pytest.mark.asyncio +async def test_stream_message_converts_anthropic_tools_and_tool_choice( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """The streaming request path converts tools/tool_choice the same way.""" + backend, instance = make_backend(monkeypatch) + instance.response = FakeAsyncStream([]) + + _events = [ + event + async for event in backend.stream_message( + { + "model": "claude", + "messages": [], + "tools": [{"name": "t", "input_schema": {"type": "object"}}], + "tool_choice": {"type": "tool", "name": "t"}, + }, + {}, + ) + ] + + sent = instance.calls[0] + assert sent["tools"] == [ + {"type": "function", "function": {"name": "t", "parameters": {"type": "object"}}} + ] + assert sent["tool_choice"] == {"type": "function", "function": {"name": "t"}} + + @pytest.mark.asyncio async def test_send_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None: backend, instance = make_backend(monkeypatch) From e4904e23a6ba6f5cff2488332946481172446922 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Wed, 12 Aug 2026 06:45:57 +0530 Subject: [PATCH 053/138] fix(backends/anyllm): stream tool_use blocks and map finish_reason on the streaming path Preserve AnyLLM streaming tool calls and finish reasons. --- headroom/backends/anyllm.py | 133 +++++++++++++++++++++++----- tests/test_backend_anyllm.py | 167 +++++++++++++++++++++++++++++++++++ 2 files changed, 278 insertions(+), 22 deletions(-) diff --git a/headroom/backends/anyllm.py b/headroom/backends/anyllm.py index 1af994e47..c1e02b35f 100644 --- a/headroom/backends/anyllm.py +++ b/headroom/backends/anyllm.py @@ -362,42 +362,131 @@ class AnyLLMBackend(Backend): }, ) - yield StreamEvent( - event_type="content_block_start", - data={ - "type": "content_block_start", - "index": 0, - "content_block": {"type": "text", "text": ""}, - }, - ) - stream_response = await self.llm.acompletion(**kwargs) output_tokens = 0 + # Stream text immediately in a single text block, but BUFFER tool + # calls and emit them as complete blocks at the end. OpenAI streams + # parallel tool calls interleaved by index (index 0 and 1 introduced + # together, then a fragment for 0, then for 1), while Anthropic + # requires each content block to be fully emitted — start, deltas, + # stop — before the next opens. Reassembling per index and flushing + # complete blocks keeps every delta inside its own block's start/stop + # for any interleaving. (The previous version pre-opened one text + # block and dropped tool calls entirely; a naive open-on-new-index + # instead mis-sequenced parallel calls, emitting a fragment for an + # already-stopped block.) + current_block_index = -1 + text_block_open = False + # provider tool index -> {"id", "name", "arguments"}, first-seen order + tool_calls: dict[int, dict[str, Any]] = {} + tool_order: list[int] = [] + stop_reason = "end_turn" async for chunk in cast(AsyncIterator[Any], stream_response): - if hasattr(chunk, "choices") and chunk.choices: - delta = chunk.choices[0].delta - if hasattr(delta, "content") and delta.content: + if not (hasattr(chunk, "choices") and chunk.choices): + continue + choice = chunk.choices[0] + delta = choice.delta + + # Map OpenAI finish_reason to the Anthropic stop_reason so a tool + # call or a length truncation is not reported as end_turn. + finish_reason = getattr(choice, "finish_reason", None) + if finish_reason == "tool_calls": + stop_reason = "tool_use" + elif finish_reason == "length": + stop_reason = "max_tokens" + elif finish_reason == "stop": + stop_reason = "end_turn" + + if getattr(delta, "tool_calls", None): + for tc in delta.tool_calls: + idx = tc.index if getattr(tc, "index", None) is not None else 0 + buf = tool_calls.get(idx) + if buf is None: + buf = {"id": None, "name": "", "arguments": ""} + tool_calls[idx] = buf + tool_order.append(idx) + if getattr(tc, "id", None): + buf["id"] = tc.id + func = getattr(tc, "function", None) + if func is not None: + if getattr(func, "name", None): + buf["name"] = func.name + if getattr(func, "arguments", None): + buf["arguments"] += func.arguments + + elif getattr(delta, "content", None): + if not text_block_open: + current_block_index += 1 + text_block_open = True yield StreamEvent( - event_type="content_block_delta", + event_type="content_block_start", data={ - "type": "content_block_delta", - "index": 0, - "delta": {"type": "text_delta", "text": delta.content}, + "type": "content_block_start", + "index": current_block_index, + "content_block": {"type": "text", "text": ""}, }, ) - output_tokens += 1 + yield StreamEvent( + event_type="content_block_delta", + data={ + "type": "content_block_delta", + "index": current_block_index, + "delta": {"type": "text_delta", "text": delta.content}, + }, + ) + output_tokens += 1 - yield StreamEvent( - event_type="content_block_stop", - data={"type": "content_block_stop", "index": 0}, - ) + # Close the text block before any tool blocks (Anthropic orders + # content blocks sequentially, text then tool_use). + if text_block_open: + yield StreamEvent( + event_type="content_block_stop", + data={"type": "content_block_stop", "index": current_block_index}, + ) + + # Flush each buffered tool call as a complete, self-contained block: + # start, one input_json_delta with the reassembled arguments, stop. + for idx in tool_order: + buf = tool_calls[idx] + current_block_index += 1 + tool_id = buf["id"] or f"toolu_{uuid.uuid4().hex[:24]}" + yield StreamEvent( + event_type="content_block_start", + data={ + "type": "content_block_start", + "index": current_block_index, + "content_block": { + "type": "tool_use", + "id": tool_id, + "name": buf["name"], + "input": {}, + }, + }, + ) + if buf["arguments"]: + yield StreamEvent( + event_type="content_block_delta", + data={ + "type": "content_block_delta", + "index": current_block_index, + "delta": { + "type": "input_json_delta", + "partial_json": buf["arguments"], + }, + }, + ) + output_tokens += 1 + yield StreamEvent( + event_type="content_block_stop", + data={"type": "content_block_stop", "index": current_block_index}, + ) yield StreamEvent( event_type="message_delta", data={ "type": "message_delta", - "delta": {"stop_reason": "end_turn", "stop_sequence": None}, + "delta": {"stop_reason": stop_reason, "stop_sequence": None}, "usage": {"output_tokens": output_tokens}, }, ) diff --git a/tests/test_backend_anyllm.py b/tests/test_backend_anyllm.py index 3e1e1a8e1..7ecc933cd 100644 --- a/tests/test_backend_anyllm.py +++ b/tests/test_backend_anyllm.py @@ -419,6 +419,173 @@ async def test_stream_message_yields_events_and_error(monkeypatch: pytest.Monkey assert error_events[-1].data["error"]["message"] == "stream broke" +def _tool_call_delta(*, index, tc_id=None, name=None, arguments=None): # noqa: ANN001, ANN202 + """Build an OpenAI-style streaming tool_call delta chunk.""" + func = SimpleNamespace(name=name, arguments=arguments) + tc = SimpleNamespace(index=index, id=tc_id, function=func) + return SimpleNamespace( + choices=[SimpleNamespace(delta=SimpleNamespace(tool_calls=[tc]), finish_reason=None)] + ) + + +@pytest.mark.asyncio +async def test_stream_message_emits_tool_use_blocks(monkeypatch: pytest.MonkeyPatch) -> None: + """A tool call streamed over any-llm must surface as an Anthropic tool_use block. + + Regression: the streamer only handled text deltas, so ``tools`` were + forwarded upstream but any tool call the model streamed back was dropped and + the client saw an empty turn with stop_reason=end_turn. The block must open, + stream its arguments as input_json_delta, and the turn must end tool_use. + """ + backend, instance = make_backend(monkeypatch) + instance.response = FakeAsyncStream( + [ + _tool_call_delta(index=0, tc_id="call_abc", name="get_weather"), + _tool_call_delta(index=0, arguments='{"city":'), + _tool_call_delta(index=0, arguments='"paris"}'), + SimpleNamespace( + choices=[SimpleNamespace(delta=SimpleNamespace(), finish_reason="tool_calls")] + ), + ] + ) + + events = [ + event async for event in backend.stream_message({"model": "claude", "messages": []}, {}) + ] + types = [e.event_type for e in events] + + # The tool call is buffered and flushed as one complete block: start, a + # single input_json_delta with the reassembled arguments, then stop. + assert types == [ + "message_start", + "content_block_start", + "content_block_delta", + "content_block_stop", + "message_delta", + "message_stop", + ] + + start = next(e for e in events if e.event_type == "content_block_start") + assert start.data["content_block"]["type"] == "tool_use" + assert start.data["content_block"]["id"] == "call_abc" + assert start.data["content_block"]["name"] == "get_weather" + + arg_deltas = [e for e in events if e.event_type == "content_block_delta"] + assert [d.data["delta"]["type"] for d in arg_deltas] == ["input_json_delta"] + joined = "".join(d.data["delta"]["partial_json"] for d in arg_deltas) + assert joined == '{"city":"paris"}' + + message_delta = next(e for e in events if e.event_type == "message_delta") + assert message_delta.data["delta"]["stop_reason"] == "tool_use" + + +@pytest.mark.asyncio +async def test_stream_message_handles_parallel_tool_calls( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Interleaved parallel tool calls must produce valid, disjoint Anthropic blocks. + + OpenAI can introduce two tool indices in one chunk and then stream argument + fragments for each across later chunks. Each Anthropic tool_use block must be + fully framed (exactly one start and stop, arguments reassembled) with no + delta emitted after that block's stop. + """ + backend, instance = make_backend(monkeypatch) + instance.response = FakeAsyncStream( + [ + # One chunk introduces BOTH tool indices at once. + SimpleNamespace( + choices=[ + SimpleNamespace( + delta=SimpleNamespace( + tool_calls=[ + SimpleNamespace( + index=0, + id="call_0", + function=SimpleNamespace(name="alpha", arguments='{"a":'), + ), + SimpleNamespace( + index=1, + id="call_1", + function=SimpleNamespace(name="beta", arguments='{"b":'), + ), + ] + ), + finish_reason=None, + ) + ] + ), + # Interleaved argument fragments: index 0, then index 1. + _tool_call_delta(index=0, arguments="1}"), + _tool_call_delta(index=1, arguments="2}"), + SimpleNamespace( + choices=[SimpleNamespace(delta=SimpleNamespace(), finish_reason="tool_calls")] + ), + ] + ) + + events = [ + event async for event in backend.stream_message({"model": "claude", "messages": []}, {}) + ] + + # Each tool block index must have exactly one start and one stop, and no + # delta may appear after that index's stop. + stopped: set[int] = set() + starts: dict[int, int] = {} + stops: dict[int, int] = {} + args: dict[int, str] = {} + for e in events: + if e.event_type == "content_block_start": + idx = e.data["index"] + starts[idx] = starts.get(idx, 0) + 1 + assert e.data["content_block"]["type"] == "tool_use" + elif e.event_type == "content_block_delta": + idx = e.data["index"] + assert idx not in stopped, f"delta for block {idx} after its stop" + args[idx] = args.get(idx, "") + e.data["delta"]["partial_json"] + elif e.event_type == "content_block_stop": + idx = e.data["index"] + stops[idx] = stops.get(idx, 0) + 1 + stopped.add(idx) + + assert starts == {0: 1, 1: 1} + assert stops == {0: 1, 1: 1} + assert args == {0: '{"a":1}', 1: '{"b":2}'} + + block0 = next( + e for e in events if e.event_type == "content_block_start" and e.data["index"] == 0 + ) + block1 = next( + e for e in events if e.event_type == "content_block_start" and e.data["index"] == 1 + ) + assert block0.data["content_block"]["name"] == "alpha" + assert block0.data["content_block"]["id"] == "call_0" + assert block1.data["content_block"]["name"] == "beta" + assert block1.data["content_block"]["id"] == "call_1" + + +@pytest.mark.asyncio +async def test_stream_message_maps_length_finish_reason(monkeypatch: pytest.MonkeyPatch) -> None: + """A truncated (length) text stream must report stop_reason=max_tokens.""" + backend, instance = make_backend(monkeypatch) + instance.response = FakeAsyncStream( + [ + SimpleNamespace( + choices=[SimpleNamespace(delta=SimpleNamespace(content="hi"), finish_reason=None)] + ), + SimpleNamespace( + choices=[SimpleNamespace(delta=SimpleNamespace(), finish_reason="length")] + ), + ] + ) + + events = [ + event async for event in backend.stream_message({"model": "claude", "messages": []}, {}) + ] + message_delta = next(e for e in events if e.event_type == "message_delta") + assert message_delta.data["delta"]["stop_reason"] == "max_tokens" + + @pytest.mark.asyncio async def test_send_openai_message_maps_choices_and_tool_calls( monkeypatch: pytest.MonkeyPatch, From d7bc1e275f411788abffa2d007db14aa17fd31c5 Mon Sep 17 00:00:00 2001 From: gglucass Date: Wed, 12 Aug 2026 03:16:00 +0200 Subject: [PATCH 054/138] fix(content-router): protect custom-tag blocks before mixed-content section split Protect custom-tag blocks during mixed-content routing. --- headroom/transforms/content_router.py | 47 +++++++++++++- tests/test_transforms/test_content_router.py | 67 ++++++++++++++++++++ 2 files changed, 112 insertions(+), 2 deletions(-) diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py index 657638e40..4a862f7c1 100644 --- a/headroom/transforms/content_router.py +++ b/headroom/transforms/content_router.py @@ -2406,7 +2406,24 @@ class ContentRouter(Transform): Returns: RouterCompressionResult with reassembled content. """ - sections = split_into_sections(content) + from .tag_protector import protect_tags, restore_tags + + # Protect custom-tag blocks BEFORE splitting into sections. Section + # boundaries (code fences, blank lines) split a + # ``...`` pair across sections, so + # the per-section tag protection inside ``_try_ml_compressor`` never + # sees a matched pair (an unmatched tag protects nothing) and + # instruction blocks — Claude Code ships CLAUDE.md inside + # — leak into lossy ML compression and arrive + # word-dropped. Protecting here keeps the whole block as one + # placeholder that spans sections intact. + cleaned, protected = protect_tags( + content, + compress_tagged_content=self.config.compress_tagged_content, + ) + sections_source = cleaned if protected else content + + sections = split_into_sections(sections_source) if logger.isEnabledFor(logging.DEBUG): _log_router_debug( "content_router_mixed_sections", @@ -2422,10 +2439,32 @@ class ContentRouter(Transform): strategy_used=CompressionStrategy.PASSTHROUGH, ) + # Placeholders must survive byte-exact: ``restore_tags`` DISCARDS a + # protected block whose placeholder was stripped or rewritten + # (Hotfix-A9), so a compressor eating a placeholder would silently + # drop the whole tag block — worse than the mangling this fixes. + # Any section carrying a placeholder is passed through verbatim + # instead of ever entering a compressor. + placeholders = [placeholder for placeholder, _ in protected] + compressed_sections: list[str] = [] routing_log: list[RoutingDecision] = [] for i, section in enumerate(sections): + if placeholders and any(ph in section.content for ph in placeholders): + section_tokens = _estimate_tokens(section.content) + compressed_sections.append(section.content) + routing_log.append( + RoutingDecision( + content_type=section.content_type, + strategy=CompressionStrategy.PASSTHROUGH, + original_tokens=section_tokens, + compressed_tokens=section_tokens, + section_index=i, + ) + ) + continue + # Get strategy for this section strategy = self._strategy_from_detection_type(section.content_type) @@ -2455,8 +2494,12 @@ class ContentRouter(Transform): ) ) + compressed = "\n\n".join(compressed_sections) + if protected: + compressed = restore_tags(compressed, protected) + return RouterCompressionResult( - compressed="\n\n".join(compressed_sections), + compressed=compressed, original=content, strategy_used=CompressionStrategy.MIXED, routing_log=routing_log, diff --git a/tests/test_transforms/test_content_router.py b/tests/test_transforms/test_content_router.py index 52f9bfa5b..916bd62ab 100644 --- a/tests/test_transforms/test_content_router.py +++ b/tests/test_transforms/test_content_router.py @@ -1699,3 +1699,70 @@ class TestCompressBlockContent: assert any("router:tool_result" in t for t in transforms_applied), ( f"Expected router:tool_result:* in transforms, got: {transforms_applied}" ) + + +# ============================================================================= +# Mixed content: custom-tag protection (system-reminder mangling regression) +# ============================================================================= + + +class TestMixedContentTagProtection: + """_compress_mixed must protect custom-tag blocks BEFORE section split. + + Splitting first lands the open/close tags of a + ``...`` pair in different sections; + per-section protection then sees only unmatched tags (which protect + nothing) and the block's content — Claude Code ships CLAUDE.md this way — + is lossy-compressed and arrives word-dropped. + """ + + REMINDER = ( + "\n" + "Instruction prose that must survive byte-exact.\n\n" + "```bash\nrtk gain\n```\n\n" + "More instructions after the fence, also byte-exact.\n" + "" + ) + + @staticmethod + def _mangling_router() -> ContentRouter: + """Router whose per-section compressor visibly mangles everything.""" + router = ContentRouter(ContentRouterConfig(min_section_tokens=1)) + + def mangle(content, strategy, context, language=None, question=None, bias=1.0): + return "MANGLED", 1, None + + router._apply_strategy_to_content = mangle # type: ignore[method-assign] + return router + + def test_reminder_block_survives_mixed_compression_verbatim(self): + router = self._mangling_router() + content = ( + "Prose before the reminder that may compress.\n\n" + + self.REMINDER + + "\n\nProse after the reminder that may compress." + ) + + result = router._compress_mixed(content, context="") + + # The tag block (fence and all) is byte-exact in the output... + assert self.REMINDER in result.compressed + # ...while content outside it still went through the compressor. + assert "MANGLED" in result.compressed + + def test_reminder_only_content_passes_through(self): + router = self._mangling_router() + + result = router._compress_mixed(self.REMINDER, context="") + + assert self.REMINDER in result.compressed + assert "MANGLED" not in result.compressed + + def test_untagged_mixed_content_still_compresses(self): + router = self._mangling_router() + content = "Plain prose section.\n\n```python\nprint('hi')\n```\n\nMore prose." + + result = router._compress_mixed(content, context="") + + assert "MANGLED" in result.compressed + assert result.strategy_used == CompressionStrategy.MIXED From 09516635621caccf7e3db4f537eb49ea49b8a453 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Wed, 12 Aug 2026 06:46:04 +0530 Subject: [PATCH 055/138] fix(proxy): close the upstream stream when a streaming body is never consumed Close unconsumed upstream streaming bodies. --- headroom/proxy/handlers/streaming.py | 20 ++++ tests/test_proxy_copilot_auth_hooks.py | 16 ++- .../test_proxy_streaming_ratelimit_headers.py | 99 +++++++++++++++++++ 3 files changed, 134 insertions(+), 1 deletion(-) diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py index e265ba80c..ef9600381 100644 --- a/headroom/proxy/handlers/streaming.py +++ b/headroom/proxy/handlers/streaming.py @@ -1098,6 +1098,7 @@ class StreamingMixin: ) -> Response | StreamingResponse: """Actual streaming implementation, guarded by _stream_response's cleanup wrapper.""" from fastapi.responses import Response, StreamingResponse + from starlette.background import BackgroundTask from headroom.proxy.helpers import MAX_SSE_BUFFER_SIZE @@ -1656,10 +1657,29 @@ class StreamingMixin: ) yield f"event: headroom_pending_messages\ndata: {pending_event}\n\n".encode() + async def _release_upstream_stream() -> None: + # Guarantee the upstream HTTP/2 stream is released even when the + # body generator above is never iterated — the client disconnected + # before Starlette started sending the response body (routine when a + # harness like Claude Code cancels or supersedes an in-flight turn), + # so ``generate()`` never entered its own ``aclosing`` and nothing + # else closes ``upstream_response``. Each such request otherwise + # leaks one open h2 stream; they accumulate on the pooled upstream + # connection until it reaches SETTINGS_MAX_CONCURRENT_STREAMS (100) + # and no new stream can open ("Max outbound streams is 100, 100 + # open"), and the proxy goes unhealthy until restart (#2797). + # Starlette runs a response's ``background`` task after the body + # finishes *and* after an early client disconnect, so this fires in + # both cases. ``aclose()`` is idempotent, so on the normal path — + # where the generator already closed the stream — this is a no-op. + with contextlib.suppress(Exception): + await upstream_response.aclose() + return StreamingResponse( generate(), media_type="text/event-stream", headers=forwarded_headers, + background=BackgroundTask(_release_upstream_stream), ) async def _stream_response_bedrock( diff --git a/tests/test_proxy_copilot_auth_hooks.py b/tests/test_proxy_copilot_auth_hooks.py index eb0eecd4a..7a37a82c7 100644 --- a/tests/test_proxy_copilot_auth_hooks.py +++ b/tests/test_proxy_copilot_auth_hooks.py @@ -52,11 +52,22 @@ def _load_handler_module(monkeypatch: pytest.MonkeyPatch, module_name: str, rela responses_mod = types.ModuleType("fastapi.responses") class Response: - def __init__(self, content=None, status_code: int = 200, headers=None, media_type=None): + def __init__( + self, + content=None, + status_code: int = 200, + headers=None, + media_type=None, + background=None, + ): self.content = content self.status_code = status_code self.headers = headers or {} self.media_type = media_type + # The streaming forwarder attaches a background task that releases the + # upstream stream when the body is never consumed (#2882); the double + # must accept and store it so the real StreamingResponse call works. + self.background = background class StreamingResponse(Response): pass @@ -228,6 +239,9 @@ def test_streaming_response_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch assert sent_headers["Authorization"] == "Bearer upstream-token" assert sent_headers["content-type"] == "application/json" assert response.status_code == 200 + # The Copilot auth hook and the #2882 upstream-stream cleanup coexist: the + # streaming response still carries its background release task. + assert response.background is not None def test_openai_chat_routes_copilot_requests_per_model(monkeypatch: pytest.MonkeyPatch) -> None: diff --git a/tests/test_proxy_streaming_ratelimit_headers.py b/tests/test_proxy_streaming_ratelimit_headers.py index dfedc4915..5983dea54 100644 --- a/tests/test_proxy_streaming_ratelimit_headers.py +++ b/tests/test_proxy_streaming_ratelimit_headers.py @@ -463,6 +463,105 @@ class TestStreamingRatelimitHeaderForwarding: assert attempts["count"] == 2 assert chunks + @pytest.mark.asyncio + async def test_upstream_stream_closed_when_body_never_consumed(self): + """A never-iterated streaming body must still release the upstream stream (#2797). + + The upstream stream is opened before the body generator, and the + generator's own ``aclosing`` only runs if the body is iterated. When a + client disconnects before Starlette starts sending the body the + generator never runs, so the close must come from the response's + ``background`` task instead — otherwise every such request leaks an open + HTTP/2 stream and the pooled upstream connection eventually exhausts its + 100 concurrent streams ("Max outbound streams is 100, 100 open"). + """ + proxy = self._create_mock_proxy() + mock_response = self._create_mock_upstream_response() + + mock_request = MagicMock() + proxy.http_client.build_request = MagicMock(return_value=mock_request) + proxy.http_client.send = AsyncMock(return_value=mock_response) + + result = await proxy._stream_response( + url="https://api.anthropic.com/v1/messages", + headers={"x-api-key": "sk-test"}, + body={ + "model": "claude-sonnet-4-20250514", + "max_tokens": 100, + "stream": True, + "messages": [{"role": "user", "content": "hi"}], + }, + provider="anthropic", + model="claude-sonnet-4-20250514", + request_id="test-abandoned-stream", + original_tokens=10, + optimized_tokens=10, + tokens_saved=0, + transforms_applied=[], + tags={}, + optimization_latency=0.0, + ) + + # Simulate the client disconnecting before the body is consumed: the + # generator is never iterated, so its aclosing never runs. + mock_response.aclose.assert_not_awaited() + + # Starlette runs the response's background task in exactly this case. + assert result.background is not None, "streaming response must carry a cleanup task" + await result.background() + + mock_response.aclose.assert_awaited() + + @pytest.mark.asyncio + async def test_upstream_stream_released_over_asgi_lifecycle_on_disconnect(self): + """Driving the real ASGI response through an early disconnect releases the stream. + + Rather than calling ``result.background()`` directly, this exercises the + Starlette response lifecycle with a client that disconnects immediately, + and asserts the upstream stream is closed by the end of it -- proving the + cleanup this PR attaches is actually invoked by Starlette, not merely + present on the response object. + """ + import asyncio + + proxy = self._create_mock_proxy() + mock_response = self._create_mock_upstream_response() + proxy.http_client.build_request = MagicMock(return_value=MagicMock()) + proxy.http_client.send = AsyncMock(return_value=mock_response) + + result = await proxy._stream_response( + url="https://api.anthropic.com/v1/messages", + headers={"x-api-key": "sk-test"}, + body={ + "model": "claude-sonnet-4-20250514", + "max_tokens": 100, + "stream": True, + "messages": [{"role": "user", "content": "hi"}], + }, + provider="anthropic", + model="claude-sonnet-4-20250514", + request_id="test-asgi-lifecycle", + original_tokens=10, + optimized_tokens=10, + tokens_saved=0, + transforms_applied=[], + tags={}, + optimization_latency=0.0, + ) + + async def receive(): + # The client is already gone before the body is streamed. + return {"type": "http.disconnect"} + + async def send(_message): + return None + + scope = {"type": "http", "method": "POST", "headers": []} + await asyncio.wait_for(result(scope, receive, send), timeout=5.0) + + # By the end of the response lifecycle the upstream stream is released. + mock_response.aclose.assert_awaited() + @pytest.mark.asyncio async def test_codex_rate_limit_headers_captured_and_forwarded_in_streaming(self): """Codex x-codex-* headers must refresh /stats state AND reach the client. From 12149f74466c08b69be8d5fe751425be63c2fda4 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Wed, 12 Aug 2026 06:46:08 +0530 Subject: [PATCH 056/138] fix(proxy): include tool_search_deferral savings in the savings ledger Include tool-search deferral in savings accounting (#2795). --- headroom/proxy/prometheus_metrics.py | 15 ++++- tests/test_savings_ledger_before_forwarded.py | 66 +++++++++++++++++++ 2 files changed, 78 insertions(+), 3 deletions(-) diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.py index 889ed60be..8cd83846b 100644 --- a/headroom/proxy/prometheus_metrics.py +++ b/headroom/proxy/prometheus_metrics.py @@ -869,14 +869,23 @@ class PrometheusMetrics: # would hold the lock for the whole write instead of just the syscall. # ponytail: default thread pool, not a dedicated executor -- give it one # if a profile ever shows writers parked on flock saturating the pool. - if tokens_saved > 0 and not self._stateless: + # tool_search_deferral saves tool-SCHEMA tokens that never move the + # message-level tok_before/after, so a tool-heavy turn can have + # tokens_saved=0 while genuinely deferring thousands of tokens. Fold that + # component into the ledger delta the same way the PERF headline and + # perf/analyzer do (`headline_before = before + tool_saved`); otherwise + # `headroom savings` understates real compression 7-10x on tool-search + # sessions and drops deferral-only turns from the ledger entirely (#2795). + deferral_saved = max(0, int(tool_search_saved)) + ledger_saved = tokens_saved + deferral_saved + if ledger_saved > 0 and not self._stateless: # `input_tokens` here is the optimized (post-compression) count # that was actually forwarded — see emit_request_outcome, which # passes `input_tokens=outcome.optimized_tokens`. The ledger's # `before` is the pre-compression original and `after` is what we # forwarded, and `headroom savings` derives the reduction percent # as saved / before. Passing the forwarded count as `before` - # understated the original by `tokens_saved`, inflating that + # understated the original by `ledger_saved`, inflating that # percentage (e.g. a real 40% reduction was reported as ~67%). # Reconstruct the original as forwarded + saved. await asyncio.to_thread( @@ -887,7 +896,7 @@ class PrometheusMetrics: # `tokens_saved` yields a mixed-ruler before/after (local 10->6 # with the provider reporting 8 would record 12->8). Use the # caller's local count when supplied. - tokens_before=ledger_input_tokens + tokens_saved, + tokens_before=ledger_input_tokens + ledger_saved, tokens_after=ledger_input_tokens, model=model, client=client or "proxy", diff --git a/tests/test_savings_ledger_before_forwarded.py b/tests/test_savings_ledger_before_forwarded.py index 52a10a133..72d158377 100644 --- a/tests/test_savings_ledger_before_forwarded.py +++ b/tests/test_savings_ledger_before_forwarded.py @@ -63,3 +63,69 @@ async def test_record_savings_event_uses_original_input_as_before( "source": "proxy", } ] + + +def _capture_ledger(monkeypatch: pytest.MonkeyPatch) -> list[dict[str, Any]]: + calls: list[dict[str, Any]] = [] + monkeypatch.setattr( + prometheus_metrics.savings_ledger, + "record_savings_event", + lambda **kwargs: calls.append(kwargs), + ) + return calls + + +@pytest.mark.asyncio +async def test_record_savings_event_includes_tool_search_deferral( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """tool_search_deferral savings must ride into the ledger delta so + `headroom savings` does not undercount tool-search sessions ~7-10x (#2795).""" + calls = _capture_ledger(monkeypatch) + metrics = prometheus_metrics.PrometheusMetrics( + savings_tracker=_FakeSavingsTracker(), + otel_metrics=_FakeOtelMetrics(), + ) + await metrics.record_request( + provider="anthropic", + model="claude-opus-4-6", + input_tokens=109844, # forwarded (post-compression) message count + output_tokens=25, + tokens_saved=1896, + tool_search_saved=13182, # deferred tool schemas never sent + latency_ms=10.0, + client="claude-code", + ) + + assert len(calls) == 1 + # saved = tokens_saved + tool_search_saved; before = forwarded + saved. + assert calls[0]["tokens_after"] == 109844 + assert calls[0]["tokens_before"] == 109844 + 1896 + 13182 # == 124922 + + +@pytest.mark.asyncio +async def test_record_savings_event_written_for_deferral_only_turn( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """A tool-heavy turn can defer thousands of tool-schema tokens while + tokens_saved is 0 (deferral does not move the message-level count). It must + still be recorded, not dropped from the ledger (#2795).""" + calls = _capture_ledger(monkeypatch) + metrics = prometheus_metrics.PrometheusMetrics( + savings_tracker=_FakeSavingsTracker(), + otel_metrics=_FakeOtelMetrics(), + ) + await metrics.record_request( + provider="anthropic", + model="claude-opus-4-6", + input_tokens=50000, + output_tokens=25, + tokens_saved=0, + tool_search_saved=13182, + latency_ms=10.0, + client="claude-code", + ) + + assert len(calls) == 1 + assert calls[0]["tokens_before"] == 50000 + 13182 + assert calls[0]["tokens_after"] == 50000 From eb5b5e41988f5c27d29ae8ae3e5fe74e56493b8c Mon Sep 17 00:00:00 2001 From: Yossi Ovadia Date: Tue, 11 Aug 2026 21:03:09 -0700 Subject: [PATCH 057/138] fix: Vertex model pricing shows $0.00 for versioned model names and vertex:anthropic provider (#2517) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Two bugs cause `$0.00` cost display for Vertex AI users in headroom's dashboard: 1. **Model name resolution** — Vertex appends `@YYYYMMDD` version tags at runtime (e.g. `claude-haiku-4-5@20251001`). LiteLLM's database stores bare names without version suffixes, so every versioned model missed the lookup. 2. **Prefix cache savings** — the provider match checks `provider == "anthropic"` but Vertex traffic is tagged `provider == "vertex:anthropic"`, so cache read savings computed as $0.00. This bug is **not** addressed by #2516. Fixes #2515 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/pricing/litellm_model_resolution.py`: strip `@YYYYMMDD` suffix before lookup; add `vertex_ai/` to `MODEL_PREFIX_RULES` for Claude models; apply prefix rules to both original and bare names - `headroom/proxy/cost.py`: extend provider match to include `vertex:anthropic` alongside `anthropic` for prefix cache savings - `tests/test_pricing_litellm_model_resolution.py`: 4 new tests covering suffix stripping, versioned model resolution, pricing lookup, and end-to-end resolve ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ python -m pytest tests/test_pricing_litellm_model_resolution.py -v collected 10 items tests/test_pricing_litellm_model_resolution.py::test_prefix_rule_matches_case_insensitively PASSED tests/test_pricing_litellm_model_resolution.py::test_resolution_candidates_try_bare_then_matching_prefix_then_alias PASSED tests/test_pricing_litellm_model_resolution.py::test_pricing_lookup_candidates_include_provider_prefixes_and_aliases PASSED tests/test_pricing_litellm_model_resolution.py::test_retired_claude_3_sonnet_aliases_to_sonnet_tier_not_haiku PASSED tests/test_pricing_litellm_model_resolution.py::test_resolve_litellm_model_name_returns_first_known_candidate PASSED tests/test_pricing_litellm_model_resolution.py::test_resolve_litellm_model_name_returns_original_when_unknown PASSED tests/test_pricing_litellm_model_resolution.py::test_strip_vertex_version_suffix PASSED tests/test_pricing_litellm_model_resolution.py::test_resolution_candidates_vertex_versioned_models PASSED tests/test_pricing_litellm_model_resolution.py::test_pricing_lookup_candidates_vertex_versioned_models PASSED tests/test_pricing_litellm_model_resolution.py::test_vertex_versioned_model_resolves_to_known_key PASSED 10 passed in 1.23s ``` ## Real Behavior Proof - Environment: macOS arm64, Python 3.11.13, headroom 0.32.1, Claude Code 2.1.211, `CLAUDE_CODE_USE_VERTEX=1`, persistent local proxy - Exact command / steps: `python3 -c "from headroom.pricing.litellm_model_resolution import resolution_candidates; import litellm; m='claude-haiku-4-5@20251001'; [print(c, litellm.model_cost.get(c,{}).get('input_cost_per_token',0)*1e6) for c in resolution_candidates(m)]"` - Observed result: before fix all versioned Vertex models returned $0.00; after fix `claude-haiku-4-5@20251001`→$1.00/MTok, `claude-opus-4@20250514`→$15.00/MTok, dashboard "Prefix Cache Impact" shows Net savings $6.31 (was $0.00). Screenshots in issue #2515. - Not tested: non-Vertex paths (direct Anthropic, Bedrock, OpenAI) — changes are additive and guarded by `vertex:anthropic` provider check ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes --------- Co-authored-by: JD Davis --- headroom/pricing/litellm_model_resolution.py | 64 ++++++++++++++--- headroom/proxy/cost.py | 2 +- .../test_pricing_litellm_model_resolution.py | 72 +++++++++++++++++-- 3 files changed, 123 insertions(+), 15 deletions(-) diff --git a/headroom/pricing/litellm_model_resolution.py b/headroom/pricing/litellm_model_resolution.py index c006f64d9..0a9242001 100644 --- a/headroom/pricing/litellm_model_resolution.py +++ b/headroom/pricing/litellm_model_resolution.py @@ -2,9 +2,15 @@ from __future__ import annotations +import re from collections.abc import Callable from dataclasses import dataclass +# Vertex AI appends @YYYYMMDD version tags to model names at runtime +# (e.g. "claude-haiku-4-5@20251001"). LiteLLM's database stores bare +# names without version suffixes, so we strip the suffix before lookup. +_VERTEX_VERSION_SUFFIX_RE = re.compile(r"@\d{8}$") + @dataclass(frozen=True, slots=True) class LiteLLMModelPrefixRule: @@ -55,16 +61,40 @@ PRICE_LOOKUP_PROVIDER_PREFIXES: tuple[str, ...] = ( ) +def _strip_vertex_version_suffix(model: str) -> str: + """Strip Vertex @YYYYMMDD version suffix if present.""" + return _VERTEX_VERSION_SUFFIX_RE.sub("", model) + + def resolution_candidates(model: str) -> tuple[str, ...]: """Return ordered LiteLLM keys to try for cost-per-token resolution.""" candidates = [model] - candidates.extend( - candidate - for rule in MODEL_PREFIX_RULES - for candidate in (rule.candidate_for(model),) - if candidate is not None - ) - alias = MODEL_ALIASES.get(model) + + # If the model has a Vertex @YYYYMMDD version suffix, also try the bare + # name. Vertex appends these at runtime; LiteLLM stores bare names only. + bare = _strip_vertex_version_suffix(model) + is_vertex_versioned = bare != model + if is_vertex_versioned: + candidates.append(bare) + + # Apply prefix rules to both the original and bare name so that e.g. + # "anthropic/claude-haiku-4-5" is tried after "claude-haiku-4-5". + for m in dict.fromkeys([model, bare]): + candidates.extend( + candidate + for rule in MODEL_PREFIX_RULES + for candidate in (rule.candidate_for(m),) + if candidate is not None + ) + + # Only add vertex_ai/ candidates for models with @YYYYMMDD suffix — + # these are known Vertex-routed models. Non-versioned models should not + # get vertex_ai/ candidates to avoid matching wrong pricing tier. + if is_vertex_versioned: + for m in dict.fromkeys([model, bare]): + candidates.append(f"vertex_ai/{m}") + + alias = MODEL_ALIASES.get(model) or MODEL_ALIASES.get(bare) if alias: candidates.append(alias) return tuple(dict.fromkeys(candidates)) @@ -86,11 +116,27 @@ def unwrapped_model_forms(model: str) -> tuple[str, ...]: def pricing_lookup_candidates(model: str) -> tuple[str, ...]: """Return ordered LiteLLM model_cost keys to try for pricing lookup.""" + bare = _strip_vertex_version_suffix(model) + is_vertex_versioned = bare != model + candidates = [model] - candidates.extend(f"{prefix}{model}" for prefix in PRICE_LOOKUP_PROVIDER_PREFIXES) + if is_vertex_versioned: + candidates.append(bare) + + # Try all provider prefixes for both the original and bare name. + for m in dict.fromkeys([model, bare]): + candidates.extend(f"{prefix}{m}" for prefix in PRICE_LOOKUP_PROVIDER_PREFIXES) + # Unwrapped forms come after the prefixed ones so existing precedence is # unchanged for names that already resolved. - candidates.extend(unwrapped_model_forms(model)) + for m in dict.fromkeys([model, bare]): + candidates.extend(unwrapped_model_forms(m)) + + # Only add vertex_ai/ candidates for models with @YYYYMMDD suffix. + if is_vertex_versioned: + for m in dict.fromkeys([model, bare]): + candidates.append(f"vertex_ai/{m}") + candidates.extend( alias for candidate in tuple(candidates) if (alias := MODEL_ALIASES.get(candidate)) ) diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.py index cff6be4b2..b42ac18b0 100644 --- a/headroom/proxy/cost.py +++ b/headroom/proxy/cost.py @@ -213,7 +213,7 @@ def build_prefix_cache_stats( # Match model to provider _openai_prefixes = ("gpt", "o1", "o3", "o4") is_match = ( - (provider == "anthropic" and "claude" in model_name) + (provider in ("anthropic", "vertex:anthropic") and "claude" in model_name) or (provider == "openai" and any(p in model_name for p in _openai_prefixes)) or (provider == "gemini" and "gemini" in model_name) or (provider == "bedrock" and "claude" in model_name) diff --git a/tests/test_pricing_litellm_model_resolution.py b/tests/test_pricing_litellm_model_resolution.py index c2098a89b..dcfb21485 100644 --- a/tests/test_pricing_litellm_model_resolution.py +++ b/tests/test_pricing_litellm_model_resolution.py @@ -3,6 +3,7 @@ from __future__ import annotations from headroom.pricing.litellm_model_resolution import ( MODEL_ALIASES, LiteLLMModelPrefixRule, + _strip_vertex_version_suffix, pricing_lookup_candidates, resolution_candidates, resolve_litellm_model_name, @@ -21,11 +22,11 @@ def test_resolution_candidates_try_bare_then_matching_prefix_then_alias() -> Non assert resolution_candidates("MiniMax-M3") == ("MiniMax-M3", "minimax/MiniMax-M3") retired = "claude-3-5-sonnet-20241022" - assert resolution_candidates(retired) == ( - retired, - f"anthropic/{retired}", - MODEL_ALIASES[retired], - ) + candidates = resolution_candidates(retired) + assert candidates[0] == retired + assert f"anthropic/{retired}" in candidates + assert f"vertex_ai/{retired}" not in candidates # no @YYYYMMDD suffix = not Vertex + assert MODEL_ALIASES[retired] in candidates def test_pricing_lookup_candidates_include_provider_prefixes_and_aliases() -> None: @@ -59,3 +60,64 @@ def test_resolve_litellm_model_name_returns_first_known_candidate() -> None: def test_resolve_litellm_model_name_returns_original_when_unknown() -> None: assert resolve_litellm_model_name("mystery-model", lambda _: False) == "mystery-model" + + +def test_strip_vertex_version_suffix() -> None: + assert _strip_vertex_version_suffix("claude-haiku-4-5@20251001") == "claude-haiku-4-5" + assert _strip_vertex_version_suffix("claude-opus-4@20250514") == "claude-opus-4" + assert _strip_vertex_version_suffix("claude-sonnet-4-6") == "claude-sonnet-4-6" + assert _strip_vertex_version_suffix("claude-sonnet-4-20250514") == "claude-sonnet-4-20250514" + + +def test_resolution_candidates_vertex_versioned_models() -> None: + # Vertex appends @YYYYMMDD — bare name and vertex_ai/ must be candidates + candidates = resolution_candidates("claude-haiku-4-5@20251001") + assert "claude-haiku-4-5" in candidates + assert "anthropic/claude-haiku-4-5" in candidates + assert "vertex_ai/claude-haiku-4-5" in candidates # vertex_ai/ only for versioned + + candidates = resolution_candidates("claude-opus-4@20250514") + assert "claude-opus-4" in candidates + assert "anthropic/claude-opus-4" in candidates + assert "vertex_ai/claude-opus-4" in candidates + + # Non-versioned names should NOT get vertex_ai/ candidates + candidates = resolution_candidates("claude-sonnet-4-6") + assert candidates[0] == "claude-sonnet-4-6" + assert "vertex_ai/claude-sonnet-4-6" not in candidates + assert "anthropic/claude-sonnet-4-6" in candidates + + +def test_pricing_lookup_candidates_vertex_versioned_models() -> None: + candidates = pricing_lookup_candidates("claude-haiku-4-5@20251001") + # Bare name and vertex_ai/ prefix must both be candidates + assert "claude-haiku-4-5" in candidates + assert "vertex_ai/claude-haiku-4-5" in candidates + assert "anthropic/claude-haiku-4-5" in candidates + + candidates = pricing_lookup_candidates("claude-opus-4@20250514") + assert "claude-opus-4" in candidates + assert "vertex_ai/claude-opus-4" in candidates + + # Non-versioned names should NOT get vertex_ai/ pricing candidates + candidates = pricing_lookup_candidates("claude-sonnet-4-6") + assert "vertex_ai/claude-sonnet-4-6" not in candidates + assert "anthropic/claude-sonnet-4-6" in candidates + + +def test_vertex_versioned_model_resolves_to_known_key() -> None: + # Simulate LiteLLM knowing the bare model name (not the versioned one) + known = {"claude-haiku-4-5", "anthropic/claude-sonnet-4-6"} + assert ( + resolve_litellm_model_name("claude-haiku-4-5@20251001", known.__contains__) + == "claude-haiku-4-5" + ) + assert ( + resolve_litellm_model_name("claude-sonnet-4-6", known.__contains__) + == "anthropic/claude-sonnet-4-6" + ) + # Unknown versioned model falls back to original + assert ( + resolve_litellm_model_name("claude-unknown@20251001", lambda _: False) + == "claude-unknown@20251001" + ) From a5b0a8f4cc54d68afcf371a422b3a4a9635b7e7f Mon Sep 17 00:00:00 2001 From: Parideboy Date: Wed, 12 Aug 2026 06:05:22 +0200 Subject: [PATCH 058/138] fix(proxy): allow settings routes for trusted gateway/dashboard clients (#2491) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `/settings`, `/settings/schema`, `/settings/apply`, and `/dashboard/settings` were gated by `_require_loopback`, which checks `request.client.host` directly and 404s for any non-loopback caller. When headroom-proxy runs behind a reverse-proxy/gateway (e.g. in a container), `request.client.host` is the gateway's IP, so these routes 404 unconditionally — even with `HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS`/`HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` configured, a trust chain `/stats` and `/stats-lifetime` already use. Fixes #2466. ## Type of Change - [x] Bug fix ## Changes Made - Added `_require_loopback_or_trusted_dashboard_client` dependency in `headroom/proxy/server.py`, reusing the existing `_request_can_view_dashboard_metadata` trust chain (loopback check, IP-literal Host header check, same-origin check, trusted-gateway CIDR check). - Swapped this dependency in for `_require_loopback` on exactly five routes: `/settings/schema`, `GET /settings`, `POST /settings`, `POST /settings/apply`, `/dashboard/settings`. All other loopback-only admin/debug routes (`/admin/*`, `/debug/*`, `/cache/clear`, `/v1/retrieve*`) are untouched. - Added test coverage in `tests/test_proxy_loopback_gating.py`: non-loopback without trusted CIDR still 404s, loopback still allowed, trusted-gateway dashboard client is now allowed, and CIDR mismatch still 404s. ## Testing - [x] Added/updated tests - [x] Ran full test suite locally ``` $ python -m pytest tests/test_proxy_loopback_gating.py tests/test_proxy_settings_endpoints.py -q 73 passed, 1 warning in 28.80s $ ruff check headroom/proxy/server.py tests/test_proxy_loopback_gating.py All checks passed! $ ruff format --check headroom/proxy/server.py tests/test_proxy_loopback_gating.py 1 file already formatted, 1 file already formatted $ mypy headroom --ignore-missing-imports Success: no issues found in 506 source files ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.13.11, pytest 9.1.1, headroom repo local checkout - Exact command / steps: `python -m pytest tests/test_proxy_loopback_gating.py -q` after adding parametrized tests that set `HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` and hit `/settings`, `/settings/schema`, `/dashboard/settings` from a simulated gateway-forwarded peer IP - Observed result: all 51 tests in the file pass, including new cases confirming trusted-gateway clients get 200 (previously 404) while unlisted/mismatched clients still get 404 - Not tested: did not manually deploy a real Docker container behind an actual reverse-proxy (e.g. nginx/Traefik) to reproduce the original reporter's exact setup; relied on TestClient-simulated forwarded headers/peer IPs instead ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review --------- Co-authored-by: Claude Sonnet 5 --- headroom/proxy/server.py | 56 +++++++++++++++-- tests/test_proxy_loopback_gating.py | 98 +++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 5 deletions(-) diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py index 21d9fe26c..ea9615fcc 100644 --- a/headroom/proxy/server.py +++ b/headroom/proxy/server.py @@ -3342,6 +3342,40 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: from headroom.proxy.loopback_guard import require_loopback as _require_loopback from headroom.proxy.loopback_guard import require_same_origin as _require_same_origin + def _require_loopback_or_trusted_dashboard_client(request: Request) -> None: + """Allow loopback callers, or gateway-forwarded dashboard clients. + + Mirrors the trust chain already used by /stats and /stats-lifetime + (see _request_can_view_dashboard_metadata) so the settings UI works + the same way behind a reverse-proxy/gateway (issue #2466). + """ + if not _request_can_view_dashboard_metadata(request, trusted_dashboard_client_cidrs): + raise HTTPException(status_code=404) + + def _require_same_origin_or_trusted_dashboard_client(request: Request) -> None: + """Same-origin CSRF guard for settings writes, trusted-dashboard aware. + + ``require_same_origin`` only accepts an ``Origin`` that itself names a + loopback host, so a browser POST from a trusted-gateway dashboard + client was rejected even though the paired GET routes allow that same + caller (issue #2466). For non-loopback callers, accept an ``Origin`` + that matches this request's own Host header, provided the caller is + already an IP-literal-Host, CIDR-trusted dashboard client. Loopback + callers keep the stricter loopback-only origin check unchanged. + """ + if not _request_is_loopback(request): + origin = request.headers.get("origin") + host_header = request.headers.get("host") + if ( + origin + and origin != "null" + and host_header + and _request_has_same_origin_or_no_provenance(request, host_header) + and _request_can_view_dashboard_metadata(request, trusted_dashboard_client_cidrs) + ): + return + _require_same_origin(request) + @app.get("/admin/upstream", dependencies=[Depends(_require_loopback)]) async def get_upstream(): """Current Anthropic upstream + cc-switch reconciler state (loopback-only). @@ -3462,7 +3496,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: # (Phase 3's /settings/apply drives that). from headroom import settings_store - @app.get("/settings/schema", dependencies=[Depends(_require_loopback)]) + @app.get( + "/settings/schema", dependencies=[Depends(_require_loopback_or_trusted_dashboard_client)] + ) async def settings_schema(_request: Request): """Registry + grouped fields + effective values for the settings form.""" schema = settings_store.to_schema() @@ -3479,12 +3515,18 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: schema["supervised"] = False return JSONResponse(status_code=200, content=schema) - @app.get("/settings", dependencies=[Depends(_require_loopback)]) + @app.get("/settings", dependencies=[Depends(_require_loopback_or_trusted_dashboard_client)]) async def settings_get(_request: Request): """Return stored (file) values only; secret fields masked.""" return JSONResponse(status_code=200, content=settings_store.stored_values()) - @app.post("/settings", dependencies=[Depends(_require_loopback), Depends(_require_same_origin)]) + @app.post( + "/settings", + dependencies=[ + Depends(_require_loopback_or_trusted_dashboard_client), + Depends(_require_same_origin_or_trusted_dashboard_client), + ], + ) async def settings_post(request: Request): """Persist settings. Unknown key -> 400; bad type/enum/range -> 422. @@ -3529,7 +3571,11 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: ) @app.post( - "/settings/apply", dependencies=[Depends(_require_loopback), Depends(_require_same_origin)] + "/settings/apply", + dependencies=[ + Depends(_require_loopback_or_trusted_dashboard_client), + Depends(_require_same_origin_or_trusted_dashboard_client), + ], ) async def settings_apply(request: Request): """Persist settings (optional body) then restart the proxy to apply them. @@ -3592,7 +3638,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: @app.get( "/dashboard/settings", response_class=HTMLResponse, - dependencies=[Depends(_require_loopback)], + dependencies=[Depends(_require_loopback_or_trusted_dashboard_client)], ) async def dashboard_settings(): """Serve the Headroom settings GUI.""" diff --git a/tests/test_proxy_loopback_gating.py b/tests/test_proxy_loopback_gating.py index 7e48dabf6..5e9a1c9cb 100644 --- a/tests/test_proxy_loopback_gating.py +++ b/tests/test_proxy_loopback_gating.py @@ -200,6 +200,104 @@ def test_ccr_retrieve_hash_route_blocks_valid_hash_for_non_loopback() -> None: reset_compression_store() +SETTINGS_GATED = [ + ("get", "/settings/schema"), + ("get", "/settings"), + ("get", "/dashboard/settings"), +] + + +@pytest.mark.parametrize("method,path", SETTINGS_GATED) +def test_settings_non_loopback_gets_404_without_trusted_cidr(method: str, path: str) -> None: + resp = TestClient(_make_app()).request(method, path) + assert resp.status_code == 404, resp.text + + +@pytest.mark.parametrize("method,path", SETTINGS_GATED) +def test_settings_loopback_caller_allowed(method: str, path: str) -> None: + resp = _loopback_client().request(method, path) + assert resp.status_code == 200, resp.text + + +@pytest.mark.parametrize("method,path", SETTINGS_GATED) +def test_settings_trusted_gateway_dashboard_client_allowed( + monkeypatch: pytest.MonkeyPatch, method: str, path: str +) -> None: + """Settings routes must follow the same trust chain as /stats so the + dashboard works behind a reverse-proxy/gateway (#2466).""" + monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32") + client = TestClient( + _make_app(), + base_url="http://100.82.0.2:8787", + client=("100.90.0.5", 12345), + ) + resp = client.request(method, path) + assert resp.status_code == 200, resp.text + + +def test_settings_trusted_gateway_cidr_mismatch_still_404s( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32") + client = TestClient( + _make_app(), + base_url="http://100.82.0.2:8787", + client=("100.90.0.9", 12345), + ) + assert client.get("/settings").status_code == 404 + + +@pytest.mark.parametrize( + "path,body", + [("/settings", {"values": {}}), ("/settings/apply", None)], +) +def test_settings_post_trusted_gateway_client_same_origin_allowed( + monkeypatch: pytest.MonkeyPatch, path: str, body: dict | None +) -> None: + """Regression for #2491 review: a trusted-gateway dashboard client's real + same-origin browser POST (Origin matching this Host) must not be rejected + by the loopback-only same-origin guard.""" + monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32") + client = TestClient( + _make_app(), + base_url="http://100.82.0.2:8787", + client=("100.90.0.5", 12345), + ) + resp = client.post(path, json=body, headers={"origin": "http://100.82.0.2:8787"}) + assert resp.status_code != 403, resp.text + + +@pytest.mark.parametrize( + "path,body", + [("/settings", {"values": {}}), ("/settings/apply", None)], +) +def test_settings_post_trusted_gateway_client_mismatched_origin_rejected( + monkeypatch: pytest.MonkeyPatch, path: str, body: dict | None +) -> None: + """A trusted-gateway peer with a foreign Origin is still CSRF-rejected. + + The mismatched Origin also fails the first (loopback-or-trusted-client) + gate's own same-origin check, so this surfaces as 404, not 403 -- either + way the write must not go through.""" + monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32") + client = TestClient( + _make_app(), + base_url="http://100.82.0.2:8787", + client=("100.90.0.5", 12345), + ) + resp = client.post(path, json=body, headers={"origin": "http://attacker.example"}) + assert resp.status_code in (403, 404), resp.text + + +def test_settings_post_loopback_null_origin_still_rejected() -> None: + """Loopback callers keep the stricter loopback-only origin check: a + sandboxed-iframe/file:// "null" Origin must still 403, unaffected by the + trusted-dashboard-client carve-out.""" + client = _loopback_client() + resp = client.post("/settings", json={"values": {}}, headers={"origin": "null"}) + assert resp.status_code == 403, resp.text + + def test_dns_rebinding_host_header_rejected() -> None: # Loopback peer IP but an attacker-controlled Host header (the DNS-rebinding # shape) must still be rejected by the second gate. From 685ebe457d727922ba4057515556a2d2aac0f616 Mon Sep 17 00:00:00 2001 From: Alex Sun Date: Tue, 11 Aug 2026 21:27:49 -0700 Subject: [PATCH 059/138] fix(ccr): report embedded hashes from compress endpoint (#717) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Fixes `/v1/compress` so its `ccr_hashes` response includes retrievable CCR hashes embedded in compressed message content, including row-drop and recursive JSON markers that may not be present in `TransformResult.markers_inserted`. The original PR also changed query-based JSON row search. Current `main` intentionally made CCR retrieval a hash-only, full-content lookup in #1532, so that obsolete half is not restored. This reconciliation preserves the reporting bug fix without reversing the current retrieval contract. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that causes existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - extract 12–24 character CCR hashes from `Retrieve more`, `Retrieve original`, and `<>` markers - scan both transform marker metadata and nested rendered message values - preserve stable encounter order and deduplicate case-insensitively - exclude non-retrieval transform metadata such as tool digests and stable-prefix hashes - return the normalized hashes from `/v1/compress` - add helper-level and endpoint-level regression coverage ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual behavior inspection performed ### Test Output ```text $ uv run --extra dev pytest tests/test_proxy_compress_endpoint.py -q 50 passed, 1 warning in 6.54s $ uv run --extra dev ruff check headroom/proxy/handlers/openai.py tests/test_proxy_compress_endpoint.py All checks passed! $ uv run --extra dev ruff format --check headroom/proxy/handlers/openai.py tests/test_proxy_compress_endpoint.py 2 files already formatted $ git diff --check # no output ``` ## Real Behavior Proof - Environment: macOS, Python 3.12.13, current `main` at `7940c05e`, project native extension built by `uv` - Exact command / steps: ran the complete `/v1/compress` endpoint test module, including a mocked pipeline response containing an embedded row-drop marker but only unrelated tool-digest marker metadata - Observed result: endpoint returned exactly the embedded retrievable hash; helper coverage also proved nested markers, case normalization, deduplication, stable ordering, and exclusion of unrelated metadata - Not tested: full repository test and CI matrix; GitHub CI covers the broader matrix ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented the non-obvious marker filtering behavior - [x] Documentation is unchanged because the public response contract is corrected, not expanded - [x] My changes generate no new warnings - [x] I have added tests that prove the fix is effective - [x] New and existing endpoint tests pass locally - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from the Conventional Commit PR title ## Screenshots (if applicable) Not applicable. This changes a JSON API response and tests, with no graphical UI changes. ## Additional Notes The query-based JSON row-search changes from the original branch were made obsolete by #1532 and are deliberately excluded rather than reviving a retired API behavior. The original contributor remains the commit author for the reconciled fix. --------- Co-authored-by: JD Davis --- headroom/proxy/handlers/openai.py | 43 ++++++++++- .../test_platform_stabilization_functional.py | 5 +- tests/test_proxy_compress_endpoint.py | 71 +++++++++++++++++++ 3 files changed, 116 insertions(+), 3 deletions(-) diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py index 7eb55fa9b..4b096e070 100644 --- a/headroom/proxy/handlers/openai.py +++ b/headroom/proxy/handlers/openai.py @@ -12,6 +12,7 @@ import hashlib import json import logging import os +import re import threading import time import uuid @@ -94,6 +95,45 @@ _OPENAI_RESPONSES_UNIT_CACHE_INIT_LOCK = threading.RLock() _OPENAI_RESPONSES_UNIT_EXECUTOR_LOCK = threading.RLock() _OPENAI_RESPONSES_UNIT_EXECUTOR: ThreadPoolExecutor | None = None _CODEX_WS_COMPRESSION_TIMEOUT_SECONDS = 5.0 +_CCR_HASH_RE = re.compile( + r"(?:Retrieve (?:more|original): hash=|< list[str]: + """Return the distinct retrievable CCR hashes exposed by a response. + + ``TransformResult.markers_inserted`` is not a hash-only collection: it can + also contain tool-digest and stable-prefix metadata. Extract only supported + CCR retrieval markers, then scan the rendered messages because row-drop and + recursive JSON paths can embed a marker without registering it separately. + """ + hashes: list[str] = [] + seen: set[str] = set() + + def collect(value: Any, *, allow_bare_hash: bool = False) -> None: + if isinstance(value, str): + candidates = [value] if allow_bare_hash and _BARE_CCR_HASH_RE.fullmatch(value) else [] + candidates.extend(match.group(1) for match in _CCR_HASH_RE.finditer(value)) + for candidate in candidates: + normalized = candidate.lower() + if normalized not in seen: + seen.add(normalized) + hashes.append(normalized) + return + if isinstance(value, dict): + for child in value.values(): + collect(child) + return + if isinstance(value, list): + for child in value: + collect(child) + + for marker in markers: + collect(marker, allow_bare_hash=True) + collect(messages) + return hashes def _codex_ws_compression_timeout_seconds() -> float: @@ -8978,6 +9018,7 @@ class OpenAIHandlerMixin: ), timeout=COMPRESSION_TIMEOUT_SECONDS, ) + ccr_hashes = _response_ccr_hashes(result.messages, result.markers_inserted) tokens_before = result.tokens_before tokens_after = result.tokens_after @@ -9025,7 +9066,7 @@ class OpenAIHandlerMixin: ), "transforms_applied": result.transforms_applied, "transforms_summary": result.transforms_summary, - "ccr_hashes": result.markers_inserted, + "ccr_hashes": ccr_hashes, } ) except TimeoutError: diff --git a/tests/test_platform_stabilization_functional.py b/tests/test_platform_stabilization_functional.py index 92ab78d7c..7be75b7c2 100644 --- a/tests/test_platform_stabilization_functional.py +++ b/tests/test_platform_stabilization_functional.py @@ -56,6 +56,7 @@ def test_v1_compress_success_reports_actual_metrics(monkeypatch) -> None: proxy = app.state.proxy request_messages = [{"role": "user", "content": "summarize this repeated payload"}] compressed_messages = [{"role": "user", "content": "summary payload"}] + ccr_hash = "abc123def4567890abc123de" def fake_apply(**kwargs): assert kwargs["messages"] == request_messages @@ -65,7 +66,7 @@ def test_v1_compress_success_reports_actual_metrics(monkeypatch) -> None: tokens_before=100, tokens_after=40, transforms_applied=["test:compress"], - markers_inserted=["marker-1"], + markers_inserted=[ccr_hash], ) # The default /v1/compress mode runs a marker-free pipeline derived from @@ -88,7 +89,7 @@ def test_v1_compress_success_reports_actual_metrics(monkeypatch) -> None: assert body["compression_ratio"] == 0.4 assert body["transforms_applied"] == ["test:compress"] assert body["transforms_summary"] == {"test:compress": 1} - assert body["ccr_hashes"] == ["marker-1"] + assert body["ccr_hashes"] == [ccr_hash] def test_v1_compress_timeout_fails_open_quickly(monkeypatch) -> None: diff --git a/tests/test_proxy_compress_endpoint.py b/tests/test_proxy_compress_endpoint.py index 53aa74141..c6434e4ed 100644 --- a/tests/test_proxy_compress_endpoint.py +++ b/tests/test_proxy_compress_endpoint.py @@ -134,6 +134,45 @@ class TestCompressEndpointBasic: assert data["tokens_saved"] >= 0 assert data["compression_ratio"] > 0 + def test_response_ccr_hashes_extracts_only_retrievable_hashes(self): + """Embedded CCR markers are reported without unrelated transform metadata.""" + from headroom.proxy.handlers.openai import _response_ccr_hashes + + messages = [ + { + "role": "tool", + "content": ("[100 rows compressed. Retrieve more: hash=abc123def4567890abc123de]"), + }, + { + "role": "assistant", + "content": [ + { + "type": "text", + "text": "<>", + }, + { + "type": "text", + "text": "Retrieve original: hash=ABC123DEF4567890ABC123DE", + }, + ], + }, + ] + + hashes = _response_ccr_hashes( + messages, + [ + "deadbeef0000000000000000", + "", + "stable_prefix_hash:feedface00112233", + ], + ) + + assert hashes == [ + "deadbeef0000000000000000", + "abc123def4567890abc123de", + "feedface00112233", + ] + def test_bypass_header_returns_uncompressed(self, client): """X-Headroom-Bypass header should skip compression.""" messages = [ @@ -290,6 +329,38 @@ class TestCompressEndpointCompression: assert outcome.transforms_applied == ("test_transform",) assert outcome.total_latency_ms >= 0 + def test_response_reports_embedded_ccr_hashes(self, client, monkeypatch): + """The endpoint reports a CCR marker even when the transform omitted its registry.""" + proxy = client.app.state.proxy + ccr_hash = "abc123def4567890abc123de" + result = SimpleNamespace( + messages=[ + { + "role": "tool", + "content": f"<>", + } + ], + tokens_before=12, + tokens_after=7, + transforms_applied=["test_transform"], + transforms_summary={"test_transform": 1}, + markers_inserted=[""], + ) + monkeypatch.setattr( + proxy, + "_run_compression_in_executor", + AsyncMock(return_value=result), + ) + monkeypatch.setattr(proxy, "_record_request_outcome", AsyncMock()) + + response = client.post( + "/v1/compress", + json={"messages": [{"role": "user", "content": "compress me"}], "model": "gpt-4"}, + ) + + assert response.status_code == 200 + assert response.json()["ccr_hashes"] == [ccr_hash] + def test_compression_error_records_failed_request(self, client, monkeypatch): """A hard compression failure should increment failed metrics.""" proxy = client.app.state.proxy From 89493714d2cffdc1f81a8f417ea09891453d7009 Mon Sep 17 00:00:00 2001 From: Radhakrishnan Pachyappan Date: Wed, 12 Aug 2026 10:05:28 +0530 Subject: [PATCH 060/138] fix(health): label kompress as degraded/optional when not yet loaded (#2865) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `/readyz` reports kompress as `"status": "unhealthy"` while the top-level payload simultaneously reports `"status": "healthy"` and `"ready": true`. This is a visible contradiction — kompress is intentionally excluded from the aggregate readiness gate, but it still receives the harshest label when it hasn't finished loading. This PR is a superset of #2829: it makes the same `degraded` status change **and** adds an `"optional": true` field to the component dict so API consumers can distinguish optional components from gating ones without parsing the `status` string. Fixes #2813. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/proxy/server.py` — `_component_health()` accepts `optional: bool = False`; when `optional=True` and not-ready, status is `"degraded"` instead of `"unhealthy"`; `"optional": True` is added to the returned dict so callers can identify optional components without parsing the status string. Kompress call passes `optional=True`. - `tests/test_proxy_health.py` — All 11 kompress assertion dicts updated: `"status": "degraded"` for not-ready cases and `"optional": True` for all kompress cases (covering disabled/healthy/degraded states in the full parametrized matrix). ## Schema diff **Before** (kompress not yet loaded): ```json { "enabled": true, "ready": false, "status": "unhealthy", "backend": null } ``` **After**: ```json { "enabled": true, "ready": false, "status": "degraded", "optional": true, "backend": null } ``` The `"optional": true` field is additive — existing consumers that only check `status` are unaffected. The field gives consumers a stable machine-readable signal without requiring them to enumerate which component names are optional. ## Testing - [x] Unit tests pass (`pytest`) — CI only; `headroom._core` (compiled Rust extension) is not available locally, blocking direct `pytest tests/test_proxy_health.py` locally. All tests that don't import through `headroom.proxy.server → headroom.transforms → headroom._core` run locally. - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality (existing tests updated to cover the new status value and the new `"optional"` field) - [ ] Manual testing performed ### Test Output ``` $ uv run ruff check headroom/proxy/server.py tests/test_proxy_health.py All checks passed! $ uv run mypy headroom/proxy/server.py Success: no issues found in 1 source file ``` Full test suite (`tests/test_proxy_health.py`) is verified by CI; local run blocked by missing `headroom._core` native extension. ## Real Behavior Proof - Environment: local dev checkout, Windows 11, Python 3.14.3 - Ruff + mypy pass locally on both changed files (see Test Output above) - `tests/test_proxy_health.py` test suite requires `headroom._core` (compiled Rust extension not available locally) — CI run covers this - Diff is a mechanical expansion of the same `optional` flag already approved in #2829's head, plus the additive `"optional": true` response field ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title --------- Signed-off-by: Radhakrishnan Pachyappan Co-authored-by: JD Davis --- headroom/proxy/server.py | 21 +++++++++++-- tests/test_proxy_health.py | 61 ++++++++++++++++++++++++++++++++------ 2 files changed, 70 insertions(+), 12 deletions(-) diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py index ea9615fcc..10e5260c7 100644 --- a/headroom/proxy/server.py +++ b/headroom/proxy/server.py @@ -2685,15 +2685,29 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: *, enabled: bool, ready: bool, + optional: bool = False, **details: Any, ) -> dict[str, Any]: - status = "disabled" if not enabled else ("healthy" if ready else "unhealthy") - return { + if not enabled: + status = "disabled" + elif ready: + status = "healthy" + elif optional: + # Optional/non-gating components report "degraded" rather than + # "unhealthy" so the top-level status: "healthy" / ready: true + # payload is not contradicted by a component-level failure label. + status = "degraded" + else: + status = "unhealthy" + result: dict[str, Any] = { "enabled": enabled, "ready": (ready if enabled else True), "status": status, - **details, } + if optional: + result["optional"] = True + result.update(details) + return result def _kompress_health_routers() -> list[ContentRouter]: routers: list[ContentRouter] = [] @@ -2803,6 +2817,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI: "kompress": _component_health( enabled=kompress_enabled, ready=proxy.warmup.kompress.status == "loaded", + optional=True, backend=proxy.warmup.kompress.info.get("backend", None), ), } diff --git a/tests/test_proxy_health.py b/tests/test_proxy_health.py index efdad4cc1..b45cb42ad 100644 --- a/tests/test_proxy_health.py +++ b/tests/test_proxy_health.py @@ -69,7 +69,8 @@ def test_readyz_excludes_kompress_from_aggregate_readiness(monkeypatch): assert payload["checks"]["kompress"] == { "enabled": True, "ready": False, - "status": "unhealthy", + "status": "degraded", + "optional": True, "backend": None, } @@ -85,6 +86,7 @@ def test_readyz_promotes_deferred_kompress_after_runtime_load(monkeypatch): "enabled": True, "ready": True, "status": "healthy", + "optional": True, "backend": "onnx", } # The promotion must also clear the startup marker, otherwise the slot @@ -110,6 +112,7 @@ def test_readyz_promotes_kompress_from_module_cache(monkeypatch, attached): "enabled": True, "ready": True, "status": "healthy", + "optional": True, "backend": "onnx", } assert proxy.warmup.kompress.handle is model @@ -141,7 +144,8 @@ def test_readyz_keeps_pending_kompress_unloaded(monkeypatch): assert payload["checks"]["kompress"] == { "enabled": True, "ready": False, - "status": "unhealthy", + "status": "degraded", + "optional": True, "backend": None, } assert compressor.calls == ["is_ready"] @@ -181,6 +185,7 @@ def test_readyz_disabled_kompress_skips_inspection(monkeypatch): "enabled": False, "ready": True, "status": "disabled", + "optional": True, "backend": None, } assert compressor.calls == [] @@ -202,6 +207,7 @@ def test_readyz_per_provider_kompress_override_reenables_health(monkeypatch): "enabled": True, "ready": True, "status": "healthy", + "optional": True, "backend": "onnx", } assert compressor.calls == ["is_ready", "ready_backend"] @@ -222,7 +228,8 @@ def test_readyz_never_calls_lazy_kompress_getters(monkeypatch): assert payload["checks"]["kompress"] == { "enabled": True, "ready": False, - "status": "unhealthy", + "status": "degraded", + "optional": True, "backend": None, } @@ -234,37 +241,73 @@ def test_readyz_never_calls_lazy_kompress_getters(monkeypatch): "null", None, False, - {"enabled": True, "ready": False, "status": "unhealthy", "backend": None}, + { + "enabled": True, + "ready": False, + "status": "degraded", + "optional": True, + "backend": None, + }, ), ( "null", _ReadyCompressor(), False, - {"enabled": True, "ready": True, "status": "healthy", "backend": "onnx"}, + { + "enabled": True, + "ready": True, + "status": "healthy", + "optional": True, + "backend": "onnx", + }, ), ( "null", _ReadyCompressor(backend="remote"), False, - {"enabled": True, "ready": True, "status": "healthy", "backend": "remote"}, + { + "enabled": True, + "ready": True, + "status": "healthy", + "optional": True, + "backend": "remote", + }, ), ( "error", _ReadyCompressor(), False, - {"enabled": True, "ready": True, "status": "healthy", "backend": "onnx"}, + { + "enabled": True, + "ready": True, + "status": "healthy", + "optional": True, + "backend": "onnx", + }, ), ( "loaded", _ReadyCompressor(), False, - {"enabled": True, "ready": True, "status": "healthy", "backend": "existing"}, + { + "enabled": True, + "ready": True, + "status": "healthy", + "optional": True, + "backend": "existing", + }, ), ( "null", _ReadyCompressor(), True, - {"enabled": False, "ready": True, "status": "disabled", "backend": None}, + { + "enabled": False, + "ready": True, + "status": "disabled", + "optional": True, + "backend": None, + }, ), ], ) From a4bd2e62a5bb73f15b3b12e979c69e2b555bee10 Mon Sep 17 00:00:00 2001 From: TenderDeve Date: Wed, 12 Aug 2026 10:06:39 +0530 Subject: [PATCH 061/138] fix(proxy): gate mid-turn message coalescing to Claude Code clients (#1643) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `headroom wrap opencode` (and any other `@ai-sdk/anthropic` client) can't use subagents. The subagent is spawned, receives the prompt, and never responds; OpenCode throws `invalid_union / "No matching discriminator" / discriminator: "type"`. Root cause is headroom's mid-turn message coalescing. It keys concurrent streaming requests by `md5(model:system[:500])` (`_get_session_key`, `handlers/streaming.py`). An OpenCode subagent runs concurrently with the main agent on the same model and same first-500-char system prefix, so it produces the **same** session key and collides with the still-active main stream. Two things then break it: 1. `handlers/anthropic.py` sees the key in `_active_streams` and answers the subagent's request with a bare `202 headroom_queued` instead of forwarding it — so the subagent never gets a response. 2. When the main stream ends, `handlers/streaming.py` emits a non-standard `event: headroom_pending_messages` SSE event. `@ai-sdk/anthropic`'s SSE parser keys its Zod union on `type`, and `headroom_pending_messages` isn't a valid Anthropic event type — hence the error. The 202 reply and the `headroom_pending_messages` event are a Claude Code-only protocol (nothing else consumes them). This gates coalescing to Claude Code clients; every other harness streams normally. Closes #1608 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `handlers/streaming.py`: only register a stream in `_active_streams` when `classify_client(headers) == "claude-code"`, and only emit the `headroom_pending_messages` SSE event for Claude Code. - `handlers/anthropic.py`: only take the queue-and-`202` branch when the client is Claude Code (in addition to the existing `session_key in _active_streams` check). - Regression tests in `tests/test_mid_turn_steering.py` for all four cases (active-stream registration and pending-event emission, each for a Claude Code vs. a non-Claude-Code client). ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest tests/test_mid_turn_steering.py -q 9 passed in 0.46s $ ruff check headroom/proxy/handlers/streaming.py headroom/proxy/handlers/anthropic.py tests/test_mid_turn_steering.py All checks passed! $ ruff format --check 3 files already formatted $ mypy headroom/proxy/handlers/streaming.py headroom/proxy/handlers/anthropic.py --ignore-missing-imports Success: no issues found in 2 source files ``` ## Real Behavior Proof - Environment: macOS (arm64), Python 3.14 venv, editable install of this branch. - Exact command / steps: ran `pytest tests/test_mid_turn_steering.py` — the new tests drive `_stream_response` with a queued mid-turn message under an `opencode/1.0` User-Agent vs. a `claude-code/1.2.3` User-Agent and assert the streamed bytes. Also ran the streaming + anthropic handler suites (`pytest tests/test_mid_turn_steering.py tests/test_proxy_streaming_* tests/test_anthropic_* tests/test_streaming_usage_parser.py`). - Observed result: with the `opencode/1.0` client the session is never added to `_active_streams` and the response contains no `headroom_pending_messages` event; with `claude-code/1.2.3` both still happen (protocol preserved). Handler suites: 155 passed, 3 skipped. Before this change the non-Claude client received the `headroom_pending_messages` event (the exact byte string the OpenCode parser rejects). - Not tested: end-to-end against a live OpenCode + real subagent run — reproduced deterministically at the proxy layer instead (the emitted SSE bytes are the direct source of the reported `invalid_union` error). ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Additional Notes Gating on `classify_client == "claude-code"` (User-Agent `claude-code/` / `claude-cli/`) is the same client identification used elsewhere in the proxy. Unidentified clients (no recognized User-Agent) are treated as non-Claude-Code and stream normally, which is the safe default for this feature. ## Maintainer Update (2026-07-21) - Removed the manual `CHANGELOG.md` entry so release-please remains the source of changelog updates; pushed `d8e36540`. - Validation: `tests/test_mid_turn_steering.py` passed (12 tests), the related streaming/Anthropic suite passed (72 tests), Ruff check passed for touched files, Ruff format check passed, and `git diff --check upstream/main...HEAD` passed. --------- Co-authored-by: JerrettDavis --- headroom/proxy/auth_mode.py | 23 ++++++ headroom/proxy/handlers/anthropic.py | 23 ++++-- headroom/proxy/handlers/streaming.py | 14 +++- tests/test_mid_turn_steering.py | 112 +++++++++++++++++++++++++++ 4 files changed, 163 insertions(+), 9 deletions(-) diff --git a/headroom/proxy/auth_mode.py b/headroom/proxy/auth_mode.py index 2c7e97021..97a76259a 100644 --- a/headroom/proxy/auth_mode.py +++ b/headroom/proxy/auth_mode.py @@ -162,6 +162,28 @@ def should_stamp_codex_client(path: str, headers: Mapping[str, Any] | Any) -> bo return should_stamp_codex_client_signals(path, _auth_signals(headers)) +# Client harnesses that can consume Headroom's mid-turn message-coalescing +# protocol: the 202 ``headroom_queued`` reply and the synthetic +# ``headroom_pending_messages`` SSE event. This is a custom protocol only Claude +# Code parses today; other harnesses would receive events they can't decode, so +# a concurrent same-session request from them must stream normally instead of +# being queued and replayed. Keeping the capability in one named place — rather +# than scattering ``client == "claude-code"`` string checks across the request +# handlers — makes it a single, documented decision to revisit as more clients +# learn the protocol (#1608). +_COALESCING_CAPABLE_CLIENTS = frozenset({"claude-code"}) + + +def supports_mid_turn_coalescing(client: str | None) -> bool: + """Whether ``client`` can consume the mid-turn coalescing protocol. + + ``client`` is a value returned by :func:`classify_client`. See + :data:`_COALESCING_CAPABLE_CLIENTS` for why the set is currently limited to + Claude Code. + """ + return client in _COALESCING_CAPABLE_CLIENTS + + __all__ = [ "AuthMode", "CLIENT_UA_MAP", @@ -170,4 +192,5 @@ __all__ = [ "classify_auth_mode", "classify_client", "should_stamp_codex_client", + "supports_mid_turn_coalescing", ] diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index 059fdb8f0..9e79e3a27 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -27,7 +27,11 @@ from headroom.agent_savings import proxy_pipeline_kwargs from headroom.ccr.context_tracker import looks_like_claude_code_compact_summary from headroom.copilot_auth import build_copilot_upstream_url from headroom.pipeline import PipelineStage, summarize_routing_markers -from headroom.proxy.auth_mode import classify_auth_mode, classify_client +from headroom.proxy.auth_mode import ( + classify_auth_mode, + classify_client, + supports_mid_turn_coalescing, +) from headroom.proxy.compression_decision import CompressionDecision from headroom.proxy.forwarded_headers import resolve_client_ip from headroom.proxy.handlers._debug_dump import _debug_dump_mode, _redact_debug_value @@ -3024,11 +3028,18 @@ class AnthropicHandlerMixin: body, session_header=explicit_session_header, ) - # Only opt-in (header-bearing) callers participate in - # mid-turn steering; see StreamingMixin._should_queue_mid_turn - # for why the coarse md5 fallback must not queue concurrent - # independent streams (it wrongly 202s a streaming caller). - if self._should_queue_mid_turn(session_key, explicit_session_header): + # Coalesce mid-turn messages only for Claude Code, the sole + # client that understands the 202 `headroom_queued` reply and + # the `headroom_pending_messages` SSE event. Other harnesses + # (e.g. OpenCode subagents sharing a body-derived session key) + # would otherwise have their request swallowed and never + # answered. (#1608) `_should_queue_mid_turn` further restricts + # this to opt-in (header-bearing) callers with an active + # stream, so the coarse md5 fallback can't 202 a streaming + # caller. + if supports_mid_turn_coalescing( + classify_client(request.headers) + ) and self._should_queue_mid_turn(session_key, explicit_session_header): from fastapi.responses import JSONResponse queued = self._queue_mid_turn_message(session_key, body) diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py index ef9600381..07d4f70be 100644 --- a/headroom/proxy/handlers/streaming.py +++ b/headroom/proxy/handlers/streaming.py @@ -12,7 +12,7 @@ import logging import time from typing import TYPE_CHECKING, Any -from headroom.proxy.auth_mode import classify_client +from headroom.proxy.auth_mode import classify_client, supports_mid_turn_coalescing from headroom.proxy.helpers import ( RETRYABLE_OVERLOAD_STATUSES, jitter_delay_ms, @@ -1033,7 +1033,6 @@ class StreamingMixin: 4. Streams the final response to the client """ session_key = session_key or self._get_session_key(body) - self._active_streams.add(session_key) # Guard everything up to the generator's own try/finally (which owns # cleanup once streaming starts): any exception here — including @@ -1106,6 +1105,15 @@ class StreamingMixin: # ...) from the *client's* User-Agent before copilot-auth # potentially rewrites headers for upstream. client = classify_client(headers) + # Mid-turn message coalescing (queueing a concurrent same-session + # request and later replaying it via a `headroom_pending_messages` + # SSE event) is a Claude Code-only protocol. Only register the stream + # as active for coalescing when the client can consume that protocol, + # so concurrent requests from other harnesses (e.g. OpenCode subagents + # that share a body-derived session key) are streamed normally instead + # of being swallowed. (#1608) + if supports_mid_turn_coalescing(client): + self._active_streams.add(session_key) headers = await apply_copilot_api_auth(headers, url=url) start_time = time.time() @@ -1651,7 +1659,7 @@ class StreamingMixin: client=client, waste_signals=waste_signals, ) - if pending_messages: + if supports_mid_turn_coalescing(client) and pending_messages: pending_event = json.dumps( {"type": "headroom_pending_messages", "messages": pending_messages} ) diff --git a/tests/test_mid_turn_steering.py b/tests/test_mid_turn_steering.py index 1776190a6..81534ae0d 100644 --- a/tests/test_mid_turn_steering.py +++ b/tests/test_mid_turn_steering.py @@ -201,3 +201,115 @@ class TestMidTurnSteering: finally: proxy._active_streams.discard(session_key) proxy._mid_turn_queues.pop(session_key, None) + + # --- #1608: mid-turn coalescing must be gated to Claude Code clients --- + + def _normal_stream(self): + return self._create_mock_upstream_response( + [ + b'event: message_start\ndata: {"type":"message_start"}\n\n', + b'event: message_stop\ndata: {"type":"message_stop"}\n\n', + ] + ) + + async def _run_stream(self, proxy, session_key, user_agent): + mock_response = self._normal_stream() + proxy.http_client.build_request = MagicMock(return_value=MagicMock()) + proxy.http_client.send = AsyncMock(return_value=mock_response) + return await proxy._stream_response( + url="https://api.anthropic.com/v1/messages", + headers={"x-api-key": "sk-test", "user-agent": user_agent}, + body={ + "model": "claude-sonnet-4-20250514", + "max_tokens": 100, + "stream": True, + "messages": [{"role": "user", "content": "hi"}], + }, + provider="anthropic", + model="claude-sonnet-4-20250514", + request_id="test-1608", + original_tokens=10, + optimized_tokens=10, + tokens_saved=0, + transforms_applied=[], + tags={}, + optimization_latency=0.0, + session_key=session_key, + ) + + @pytest.mark.asyncio + async def test_non_claude_client_not_registered_active(self): + # An OpenCode subagent shares the main agent's body-derived session + # key; if it registered as active, the concurrent request would be + # swallowed. Non-Claude-Code clients must never be registered. + proxy = self._create_mock_proxy() + session_key = "opencode-session" + result = await self._run_stream(proxy, session_key, "opencode/1.0") + try: + assert session_key not in proxy._active_streams + finally: + async for _chunk in result.body_iterator: + pass + proxy._active_streams.discard(session_key) + proxy._mid_turn_queues.pop(session_key, None) + + @pytest.mark.asyncio + async def test_claude_code_client_registered_active(self): + proxy = self._create_mock_proxy() + session_key = "claude-session" + result = await self._run_stream(proxy, session_key, "claude-code/1.2.3") + try: + assert session_key in proxy._active_streams + finally: + async for _chunk in result.body_iterator: + pass + proxy._active_streams.discard(session_key) + proxy._mid_turn_queues.pop(session_key, None) + + @pytest.mark.asyncio + async def test_pending_event_not_emitted_for_non_claude(self): + # Even with a queued message, a non-Claude-Code stream must not emit the + # custom `headroom_pending_messages` SSE event — @ai-sdk/anthropic can't + # parse it and throws "invalid_union / No matching discriminator". + proxy = self._create_mock_proxy() + session_key = "opencode-pending" + proxy._queue_mid_turn_message( + session_key, {"messages": [{"role": "user", "content": "queued"}]} + ) + result = await self._run_stream(proxy, session_key, "opencode/1.0") + try: + body = b"".join([chunk async for chunk in result.body_iterator]) + assert b"headroom_pending_messages" not in body + finally: + proxy._active_streams.discard(session_key) + proxy._mid_turn_queues.pop(session_key, None) + + @pytest.mark.asyncio + async def test_pending_event_emitted_for_claude_code(self): + proxy = self._create_mock_proxy() + session_key = "claude-pending" + proxy._queue_mid_turn_message( + session_key, {"messages": [{"role": "user", "content": "queued"}]} + ) + result = await self._run_stream(proxy, session_key, "claude-code/1.2.3") + try: + body = b"".join([chunk async for chunk in result.body_iterator]) + assert b"headroom_pending_messages" in body + finally: + proxy._active_streams.discard(session_key) + proxy._mid_turn_queues.pop(session_key, None) + + +class TestCoalescingCapability: + """The capability predicate that gates the mid-turn coalescing protocol.""" + + def test_claude_code_supports_coalescing(self): + from headroom.proxy.auth_mode import supports_mid_turn_coalescing + + assert supports_mid_turn_coalescing("claude-code") is True + + def test_other_clients_do_not_support_coalescing(self): + from headroom.proxy.auth_mode import supports_mid_turn_coalescing + + for client in ("opencode", "codex", "cursor", "aider", "", None): + assert supports_mid_turn_coalescing(client) is False From d02df1075894b414d60626aca2bbcadd7a3577a0 Mon Sep 17 00:00:00 2001 From: Rod Boev Date: Wed, 12 Aug 2026 00:37:08 -0400 Subject: [PATCH 062/138] fix(proxy): give each Codex /v1/responses WS turn a unique request_id (#2164) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description After any Codex traffic, the dashboard "Recent Requests" table goes blank — including the unrelated Anthropic/Claude rows — even though the proxy is actively handling and compressing Codex `/v1/responses` WebSocket turns and aggregate counters keep moving. The feed isn't stale; it is being wiped client-side. Root cause: the Codex WebSocket handler `OpenAIHandlerMixin.handle_openai_responses_ws` (`headroom/proxy/handlers/openai.py`) mints a single `request_id` per WebSocket **session** (`_next_request_id()` near the top of the handler) and reuses it for every per-turn `RequestOutcome` in `_record_ws_response_metrics`, the session-residual outcome, and the session-summary `RequestLog`. Those all flow through `emit_request_outcome` (`headroom/proxy/outcome.py`), which writes a `RequestLog` per outcome into the request logger that backs `/stats.recent_requests` and `/transformations/feed` — so one session with N turns produces N+ feed rows sharing one `request_id`. The dashboard renders that feed with `