From d6259b226365abba47048a49a579ead23e55684c Mon Sep 17 00:00:00 2001 From: JD Davis Date: Sun, 12 Jul 2026 16:09:07 +0000 Subject: [PATCH] refactor(proxy): extract tool injection policy (#1995) ## Description Extracts memory tool injection stickiness configuration parsing from `headroom.proxy.helpers` into a focused policy module. The existing helper functions remain in place for the session tool tracker and sticky injection helpers. 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 - [ ] Performance improvement - [x] Code refactoring (no functional changes) ## Changes Made - Added `headroom.proxy.tool_injection_policy` for tool sticky mode and tracker session limit resolution. - Kept `get_tool_injection_sticky_mode()` and `get_tool_tracker_max_sessions()` as compatibility wrappers in `helpers.py`. - Added direct unit tests for defaults, accepted values, and loud rejection of invalid operator configuration. ## 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_tool_injection_policy.py tests/test_memory_tool_session_sticky.py 38 passed in 0.44s python -m ruff check . All checks passed! python -m ruff format --check . 1069 files already formatted python -m mypy headroom --ignore-missing-imports Success: no issues found in 410 source files gitleaks protect --staged --no-banner --redact no leaks found ``` ## Real Behavior Proof - Environment: Windows, Python 3.13.13 - Exact command / steps: Ran focused tool injection policy tests, existing memory tool sticky suite, full ruff, format check, mypy, and staged gitleaks scan. - Observed result: Existing sticky memory-tool behavior remains green while extracted policy parsing is covered directly. - Not tested: Full repository pytest suite locally; 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 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 ## Screenshots (if applicable) N/A ## Additional Notes Documentation and changelog updates are not applicable for this internal refactor. The default-branch Dependabot alerts reported during push are pre-existing and unrelated to this PR. Co-authored-by: Tejas Chopra --- headroom/proxy/handlers/anthropic.py | 5 ++- headroom/proxy/tool_injection_config.py | 46 +++++++++++-------------- headroom/proxy/tool_injection_policy.py | 44 +++++++++++++++++++++++ tests/test_tool_injection_policy.py | 42 ++++++++++++++++++++++ 4 files changed, 110 insertions(+), 27 deletions(-) create mode 100644 headroom/proxy/tool_injection_policy.py create mode 100644 tests/test_tool_injection_policy.py diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index a6b0f5fb4..74ce5bb7d 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -3434,7 +3434,10 @@ class AnthropicHandlerMixin: # blocks every other request for the duration; a timeout # here is caught below and passes the item through. result = await self._run_compression_in_executor( - lambda messages=messages, model=model, context_limit=context_limit, frozen_message_count=frozen_message_count: ( + lambda messages=messages, + model=model, + context_limit=context_limit, + frozen_message_count=frozen_message_count: ( self.anthropic_pipeline.apply( messages=messages, model=model, diff --git a/headroom/proxy/tool_injection_config.py b/headroom/proxy/tool_injection_config.py index 01ebdf0bf..5cb6a8b76 100644 --- a/headroom/proxy/tool_injection_config.py +++ b/headroom/proxy/tool_injection_config.py @@ -3,41 +3,35 @@ from __future__ import annotations import os -from typing import Literal, cast -TOOL_INJECTION_STICKY_ENV = "HEADROOM_TOOL_INJECTION_STICKY" -ToolInjectionStickyMode = Literal["enabled", "disabled"] -TOOL_INJECTION_STICKY_DEFAULT: ToolInjectionStickyMode = "enabled" +from headroom.proxy.tool_injection_policy import ( + TOOL_INJECTION_STICKY_DEFAULT, + TOOL_INJECTION_STICKY_ENV, + TOOL_TRACKER_MAX_SESSIONS_DEFAULT, + TOOL_TRACKER_MAX_SESSIONS_ENV, + ToolInjectionStickyMode, + resolve_tool_injection_sticky_mode, + resolve_tool_tracker_max_sessions, +) -TOOL_TRACKER_MAX_SESSIONS_ENV = "HEADROOM_TOOL_TRACKER_MAX_SESSIONS" -TOOL_TRACKER_MAX_SESSIONS_DEFAULT = 1000 +__all__ = [ + "TOOL_INJECTION_STICKY_DEFAULT", + "TOOL_INJECTION_STICKY_ENV", + "TOOL_TRACKER_MAX_SESSIONS_DEFAULT", + "TOOL_TRACKER_MAX_SESSIONS_ENV", + "ToolInjectionStickyMode", + "get_tool_injection_sticky_mode", + "get_tool_tracker_max_sessions", +] def get_tool_injection_sticky_mode() -> ToolInjectionStickyMode: """Return the active memory-tool stickiness mode.""" - raw = os.environ.get(TOOL_INJECTION_STICKY_ENV, "").strip().lower() - if not raw: - return TOOL_INJECTION_STICKY_DEFAULT - if raw in ("enabled", "disabled"): - return cast(ToolInjectionStickyMode, raw) - raise ValueError( - f"Invalid {TOOL_INJECTION_STICKY_ENV}={raw!r}; expected 'enabled' or 'disabled'" - ) + return resolve_tool_injection_sticky_mode(os.environ.get(TOOL_INJECTION_STICKY_ENV)) def get_tool_tracker_max_sessions() -> int: """Return the LRU bound for memory tool session tracking.""" - raw = os.environ.get(TOOL_TRACKER_MAX_SESSIONS_ENV, "").strip() - if not raw: - return TOOL_TRACKER_MAX_SESSIONS_DEFAULT - try: - value = int(raw) - except ValueError as exc: - raise ValueError( - f"Invalid {TOOL_TRACKER_MAX_SESSIONS_ENV}={raw!r}; expected positive int" - ) from exc - if value <= 0: - raise ValueError(f"Invalid {TOOL_TRACKER_MAX_SESSIONS_ENV}={raw!r}; expected positive int") - return value + return resolve_tool_tracker_max_sessions(os.environ.get(TOOL_TRACKER_MAX_SESSIONS_ENV)) diff --git a/headroom/proxy/tool_injection_policy.py b/headroom/proxy/tool_injection_policy.py new file mode 100644 index 000000000..428fab125 --- /dev/null +++ b/headroom/proxy/tool_injection_policy.py @@ -0,0 +1,44 @@ +"""Policy helpers for memory tool injection stickiness configuration.""" + +from __future__ import annotations + +from typing import Literal, cast + +TOOL_INJECTION_STICKY_ENV = "HEADROOM_TOOL_INJECTION_STICKY" +ToolInjectionStickyMode = Literal["enabled", "disabled"] +TOOL_INJECTION_STICKY_DEFAULT: ToolInjectionStickyMode = "enabled" + +TOOL_TRACKER_MAX_SESSIONS_ENV = "HEADROOM_TOOL_TRACKER_MAX_SESSIONS" +TOOL_TRACKER_MAX_SESSIONS_DEFAULT = 1000 + + +def resolve_tool_injection_sticky_mode(raw: str | None) -> ToolInjectionStickyMode: + """Resolve memory-tool injection stickiness mode from an environment value.""" + + normalized = (raw or "").strip().lower() + if not normalized: + return TOOL_INJECTION_STICKY_DEFAULT + if normalized in ("enabled", "disabled"): + return cast(ToolInjectionStickyMode, normalized) + raise ValueError( + f"Invalid {TOOL_INJECTION_STICKY_ENV}={normalized!r}; expected 'enabled' or 'disabled'" + ) + + +def resolve_tool_tracker_max_sessions(raw: str | None) -> int: + """Resolve the positive LRU session bound for tool injection tracking.""" + + normalized = (raw or "").strip() + if not normalized: + return TOOL_TRACKER_MAX_SESSIONS_DEFAULT + try: + value = int(normalized) + except ValueError as exc: + raise ValueError( + f"Invalid {TOOL_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int" + ) from exc + if value <= 0: + raise ValueError( + f"Invalid {TOOL_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int" + ) + return value diff --git a/tests/test_tool_injection_policy.py b/tests/test_tool_injection_policy.py new file mode 100644 index 000000000..b5962aebe --- /dev/null +++ b/tests/test_tool_injection_policy.py @@ -0,0 +1,42 @@ +from __future__ import annotations + +import pytest + +from headroom.proxy.tool_injection_policy import ( + TOOL_INJECTION_STICKY_ENV, + TOOL_TRACKER_MAX_SESSIONS_DEFAULT, + TOOL_TRACKER_MAX_SESSIONS_ENV, + resolve_tool_injection_sticky_mode, + resolve_tool_tracker_max_sessions, +) + + +def test_resolve_tool_injection_sticky_mode_defaults_to_enabled() -> None: + assert resolve_tool_injection_sticky_mode(None) == "enabled" + assert resolve_tool_injection_sticky_mode(" ") == "enabled" + + +def test_resolve_tool_injection_sticky_mode_accepts_known_values() -> None: + assert resolve_tool_injection_sticky_mode("ENABLED") == "enabled" + assert resolve_tool_injection_sticky_mode(" disabled ") == "disabled" + + +def test_resolve_tool_injection_sticky_mode_rejects_unknown_values() -> None: + with pytest.raises(ValueError, match=TOOL_INJECTION_STICKY_ENV): + resolve_tool_injection_sticky_mode("maybe") + + +def test_resolve_tool_tracker_max_sessions_defaults() -> None: + assert resolve_tool_tracker_max_sessions(None) == TOOL_TRACKER_MAX_SESSIONS_DEFAULT + assert resolve_tool_tracker_max_sessions(" ") == TOOL_TRACKER_MAX_SESSIONS_DEFAULT + + +def test_resolve_tool_tracker_max_sessions_accepts_positive_int() -> None: + assert resolve_tool_tracker_max_sessions("42") == 42 + assert resolve_tool_tracker_max_sessions(" 7 ") == 7 + + +@pytest.mark.parametrize("raw", ["0", "-1", "not-int", "1.5"]) +def test_resolve_tool_tracker_max_sessions_rejects_invalid_values(raw: str) -> None: + with pytest.raises(ValueError, match=TOOL_TRACKER_MAX_SESSIONS_ENV): + resolve_tool_tracker_max_sessions(raw)