feat(gatekeeper): refactor to async functions and update dependencies

- Changed dependency from `requests` to `httpx`.
- Updated HTTP client from `requests` to `httpx` for asynchronous capabilities.
- Converted completion functions for OpenAI, Anthropic, Gemini, OpenRouter, and Vertex AI to async.
- Added a new check in documentation to ensure async functions are only decorated when `asyncio_mode` is not set to auto.

Author: subpop

AGENTS.md

@@ -29,6 +29,7 @@ make verify                  # All checks (required before commit)
 - Use pytest-mock (`mocker` fixture) for mocking instead of `unittest.mock` imports
 - Use `autospec=True` when patching; `spec=<object>` with Mock
 - 100% patch coverage for new code
+- Check the project config and test runners and only decorate async functions if the ascyio_mode is not set to auto.
 
 **Security (Critical):**
 - All tools must be read-only with `readOnlyHint=True`

pyproject.toml

@@ -17,7 +17,7 @@ requires-python = ">=3.10"
 dependencies = [
     "asyncssh[bcrypt] >= 2.22.0",
     "fastmcp >= 3.2.4",
-    "requests>=2.32.0",
+    "httpx>=0.28.1",
     "pydantic-settings >= 2.12.0",
     "pydantic >= 2.12.5",
     # pydocket is incompatible with newer versions of fakeredis.

src/linux_mcp_server/gatekeeper/anthropic_client.py

@@ -66,13 +66,15 @@ def extract_messages_text(response: dict[str, Any]) -> str:
     return ""
 
 
-def complete_anthropic(prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIMEOUT_SECONDS) -> GatekeeperCompletion:
+async def complete_anthropic(
+    prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIMEOUT_SECONDS
+) -> GatekeeperCompletion:
     headers = {
         "x-api-key": _get_anthropic_api_key(),
         "anthropic-version": ANTHROPIC_API_VERSION,
         "Content-Type": "application/json",
     }
-    response = post_json(
+    response = await post_json(
         provider="anthropic",
         url=ANTHROPIC_API_URL,
         headers=headers,

src/linux_mcp_server/gatekeeper/check_run_script.py

@@ -222,7 +222,7 @@ async def check_run_script_with_stats(
     time_before = time.perf_counter()
     try:
         completion = await asyncio.wait_for(
-            asyncio.to_thread(complete_gatekeeper, prompt, max_tokens=GATEKEEPER_MAX_TOKENS),
+            complete_gatekeeper(prompt, max_tokens=GATEKEEPER_MAX_TOKENS),
             timeout=GATEKEEPER_TIMEOUT,
         )
     except asyncio.TimeoutError:

src/linux_mcp_server/gatekeeper/gemini_client.py

@@ -64,10 +64,12 @@ def extract_gemini_text(response: dict[str, Any]) -> str:
     return text.strip() if isinstance(text, str) else ""
 
 
-def complete_gemini(prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIMEOUT_SECONDS) -> GatekeeperCompletion:
+async def complete_gemini(
+    prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIMEOUT_SECONDS
+) -> GatekeeperCompletion:
     model = normalize_model_id(CONFIG.gatekeeper.model or "")
     api_key = _get_google_api_key()
-    response = post_json(
+    response = await post_json(
         provider="gemini",
         url=f"{GOOGLE_AI_BASE_URL}/models/{model}:generateContent?key={api_key}",
         headers={"Content-Type": "application/json"},

src/linux_mcp_server/gatekeeper/http_utils.py

@@ -2,11 +2,13 @@
 
 from typing import Any
 
-import requests
+import httpx
 
 
 DEFAULT_TIMEOUT_SECONDS = 120
 
+HTTP_CLIENT = httpx.AsyncClient()
+
 
 class GatekeeperHTTPError(RuntimeError):
     """Raised when an LLM provider returns an error response."""
@@ -19,16 +21,16 @@ def __init__(self, provider: str, status_code: int, body: str):
         self.body = body
 
 
-def post_json(
+async def post_json(
     *,
     provider: str,
     url: str,
     headers: dict[str, str],
     body: dict[str, Any],
     timeout: int = DEFAULT_TIMEOUT_SECONDS,
 ) -> dict[str, Any]:
-    response = requests.post(url, headers=headers, json=body, timeout=timeout)
-    if not response.ok:
+    response = await HTTP_CLIENT.post(url, headers=headers, json=body, timeout=timeout)
+    if not response.is_success:
         raise GatekeeperHTTPError(provider, response.status_code, response.text)
     return response.json()
 

src/linux_mcp_server/gatekeeper/llm.py

@@ -33,19 +33,19 @@ def resolve_provider() -> GatekeeperProvider:
     return _infer_provider_from_model(CONFIG.gatekeeper.model)
 
 
-def complete_gatekeeper(prompt: str, *, max_tokens: int) -> GatekeeperCompletion:
+async def complete_gatekeeper(prompt: str, *, max_tokens: int) -> GatekeeperCompletion:
     provider = resolve_provider()
     match provider:
         case GatekeeperProvider.OPENAI:
-            completion = complete_openai(prompt, max_tokens=max_tokens)
+            completion = await complete_openai(prompt, max_tokens=max_tokens)
         case GatekeeperProvider.ANTHROPIC:
-            completion = complete_anthropic(prompt, max_tokens=max_tokens)
+            completion = await complete_anthropic(prompt, max_tokens=max_tokens)
         case GatekeeperProvider.GEMINI:
-            completion = complete_gemini(prompt, max_tokens=max_tokens)
+            completion = await complete_gemini(prompt, max_tokens=max_tokens)
         case GatekeeperProvider.OPENROUTER:
-            completion = complete_openrouter(prompt, max_tokens=max_tokens)
+            completion = await complete_openrouter(prompt, max_tokens=max_tokens)
         case GatekeeperProvider.VERTEX_AI:
-            completion = complete_vertex_ai(prompt, max_tokens=max_tokens)
+            completion = await complete_vertex_ai(prompt, max_tokens=max_tokens)
         case _:  # pragma: no cover
             raise ValueError(f"Unsupported gatekeeper provider: {provider}")
 

src/linux_mcp_server/gatekeeper/openai_client.py

@@ -123,7 +123,9 @@ def extract_chat_completions_text(response: dict[str, Any]) -> str:
     return (content or "").strip() if isinstance(content, str) else ""
 
 
-def complete_openai(prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIMEOUT_SECONDS) -> GatekeeperCompletion:
+async def complete_openai(
+    prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIMEOUT_SECONDS
+) -> GatekeeperCompletion:
     base_url = _get_openai_base_url()
     headers = {
         **_openai_auth_headers(),
@@ -133,7 +135,7 @@ def complete_openai(prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIME
     # Try the Responses API first, falling back to Chat Completions if it's not available.
     if not _prefers_openai_chat_completions(base_url):
         try:
-            response = post_json(
+            response = await post_json(
                 provider="openai",
                 url=f"{base_url}/responses",
                 headers=headers,
@@ -150,7 +152,7 @@ def complete_openai(prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIME
             if exc.status_code not in {404, 405}:
                 raise
 
-    response = post_json(
+    response = await post_json(
         provider="openai",
         url=f"{base_url}/chat/completions",
         headers=headers,

src/linux_mcp_server/gatekeeper/openrouter_client.py

@@ -87,15 +87,15 @@ def _extract_chat_completions_text(response: dict[str, Any]) -> str:
     return (content or "").strip() if isinstance(content, str) else ""
 
 
-def complete_openrouter(
+async def complete_openrouter(
     prompt: str, *, max_tokens: int, timeout: int = DEFAULT_TIMEOUT_SECONDS
 ) -> GatekeeperCompletion:
     base_url = _get_openrouter_base_url()
     headers = {
         **_openrouter_auth_headers(),
         "Content-Type": "application/json",
     }
-    response = post_json(
+    response = await post_json(
         provider="openrouter",
         url=f"{base_url}/chat/completions",
         headers=headers,

src/linux_mcp_server/gatekeeper/pricing.py

@@ -4,11 +4,12 @@
 import logging
 import os
 
+from functools import cache
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlparse
 
-import requests
+import httpx
 
 from linux_mcp_server.config import CONFIG
 from linux_mcp_server.config import GatekeeperProvider
@@ -84,23 +85,19 @@ def _load_models_dev_fallback() -> dict[str, Any]:
         return json.load(handle)
 
 
+@cache
 def _load_models_dev_pricing() -> dict[str, Any]:
     """Loads the pricing from the models.dev API, falling back to the vendored fallback if the API is not available."""
-    global _models_dev_cache
-    if _models_dev_cache is not None:
-        return _models_dev_cache
-
     try:
-        response = requests.get(MODELS_DEV_API_URL, timeout=10)
-        response.raise_for_status()
-        _models_dev_cache = response.json()
-        logger.debug("Loaded gatekeeper pricing from models.dev API")
+        with httpx.Client(timeout=10) as client:
+            response = client.get(MODELS_DEV_API_URL)
+            response.raise_for_status()
+            pricing = response.json()
+            logger.debug("Loaded gatekeeper pricing from models.dev API", extra={"pricing": pricing})
+            return pricing
     except Exception as exc:
         logger.debug("Failed to fetch models.dev pricing (%s); using vendored fallback", exc)
-        _models_dev_cache = _load_models_dev_fallback()
-
-    assert _models_dev_cache is not None
-    return _models_dev_cache
+        return _load_models_dev_fallback()
 
 
 def _lookup_models_dev_cost(provider_key: str, model: str) -> tuple[float, float] | None: