fix(xai): set Grok Build User-Agent on all requests to fix billing classification

xAI classifies usage into "Grok Build" (subscription) vs "API" (pay-per-token)
partly based on the User-Agent header.  The openai-python SDK injects
"OpenAI/Python ..." which gets bucketed as API usage.  Now all xAI requests
send "User-Agent: grok/<version>" via extra_headers, matching the Grok Build
CLI and aligning with how 9router/CLIProxyAPI route OAuth traffic.

Co-authored-by: claw-io <273482092+claw-io@users.noreply.github.com>

Author: b3nw

.fork/features/xai.md

@@ -47,3 +47,36 @@ Notes:
      `.bak` backup), preventing duplicate files for the same identity.
 - `set_app_ref(app)` added to `main.py` lifespan so background OAuth poll tasks
   (which lack a `Request` object) can access the `RotatingClient` for hot-loading.
+
+## 2026-07-09 — Fix xAI usage classification: Grok Build vs API
+
+Branch: `fix/xai-grok-build-useragent`
+Files:
+- `src/rotator_library/providers/x_ai_provider.py`
+
+Problem:
+- xAI usage was reporting as "API" (pay-per-token) instead of "Grok Build"
+  (subscription) on the xAI billing dashboard.
+- Root cause: the `openai` Python SDK (used via LiteLLM) sets
+  `User-Agent: OpenAI/Python ...` on all requests. xAI uses the User-Agent
+  to classify traffic into billing tracks.
+- 9router (decolua/9router PR #1286) and CLIProxyAPI both route OAuth chat
+  completions to `api.x.ai/v1` with `User-Agent: grok/<version>`, which xAI
+  recognizes as Grok Build subscription traffic.
+
+Fix:
+- Added `_get_grok_build_headers()` returning `{"User-Agent": "grok/<version>"}`.
+- `acompletion()` now injects this header via `extra_headers` on **all** xAI
+  requests (not just CLI proxy models). LiteLLM merges `extra_headers` into
+  the outgoing HTTP request, overriding the openai SDK's default User-Agent.
+- `aembedding()` similarly injects the Grok Build User-Agent.
+- CLI proxy models continue to get the additional `x-xai-token-auth` and
+  `x-grok-client-version` headers on top.
+
+Verification:
+- `uv run python3 -m py_compile` and `uv run ruff check` — passed
+- Hot-patched to `llm-proxy-dev` on `docker-test`, restarted, verified healthy
+- Dry-run import: `XAiProvider()._get_grok_build_headers()` returns correct UA
+- Header capture test confirmed `user-agent: grok/0.1.202` reaches upstream
+  (via openai SDK `extra_headers` → httpx request)
+- Test completions to `grok-4.3` and `grok-build-0.1` both succeeded

.fork/stack.yml

@@ -25,6 +25,7 @@ rules:
     xai:
       - "feat(xai): add xAI Grok OAuth provider with PKCE and Device Code flows"
       - "feat(xai): enable xAI Grok device-code OAuth in admin WebUI"
+      - "fix(xai): set Grok Build User-Agent on all requests to fix billing classification"
     umans:
       - "feat(umans): add Umans provider with request-based quota tracking"
       - "fix(umans): normalize API base and show quota without proxy requests"

src/rotator_library/providers/x_ai_provider.py

@@ -250,9 +250,20 @@ def has_custom_logic(self) -> bool:
         """
         return True
 
+    def _get_grok_build_headers(self) -> dict:
+        """Return User-Agent header identifying as a Grok Build client.
+
+        xAI classifies usage as "Grok Build" vs "API" partly based on the
+        User-Agent.  The openai-python SDK sets ``OpenAI/Python ...`` which
+        gets bucketed as plain API usage.  Overriding with the same UA the
+        Grok Build CLI sends ensures OAuth-subscription traffic is attributed
+        to the Grok Build billing track.
+        """
+        return {"User-Agent": f"grok/{self._cli_version}"}
+
     def _get_cli_proxy_headers(self) -> dict:
         """Return extra headers required by the CLI chat proxy."""
-        ver = XAI_CLI_VERSION
+        ver = self._cli_version
         return {
             "User-Agent": f"grok/{ver}",
             "x-xai-token-auth": "xai-grok-cli",
@@ -301,15 +312,20 @@ async def acompletion(
         kwargs["api_base"] = api_base
         kwargs["custom_llm_provider"] = "xai"
 
-        # Inject CLI proxy headers if needed
+        # Always inject Grok Build User-Agent so xAI attributes traffic to
+        # the subscription billing track instead of the pay-per-token API.
+        existing_headers = kwargs.get("extra_headers") or {}
+        extra_headers = {**self._get_grok_build_headers(), **existing_headers}
+
+        # CLI proxy models need additional transport headers
         if use_cli_proxy:
-            extra_headers = self._get_cli_proxy_headers()
-            existing_headers = kwargs.get("extra_headers") or {}
-            kwargs["extra_headers"] = {**existing_headers, **extra_headers}
+            extra_headers.update(self._get_cli_proxy_headers())
             lib_logger.debug(
                 f"xai: routing {model_bare} through CLI proxy with version header"
             )
 
+        kwargs["extra_headers"] = extra_headers
+
         # Set up async OpenAI client for LiteLLM
         kwargs["client"] = openai.AsyncOpenAI(
             api_key=token,
@@ -355,6 +371,10 @@ async def aembedding(
         kwargs["api_key"] = token
         kwargs["api_base"] = self.api_base
         kwargs["custom_llm_provider"] = "xai"
+        kwargs["extra_headers"] = {
+            **self._get_grok_build_headers(),
+            **(kwargs.get("extra_headers") or {}),
+        }
 
         kwargs["client"] = openai.AsyncOpenAI(
             api_key=token,