What does this PR do?

Adds a new bundled web search provider plugin backed by xAI's agentic Web Search tool on the Responses API.

Why this approach:

• Reuses existing credential plumbing. Hermes already has tools/xai_http.py for the xAI image-gen / TTS / STT providers (OAuth-first via hermes auth login xai-oauth, env-var fallback via XAI_API_KEY). No new auth paths, no new env vars, no new setup wizard — the existing xai_grok post_setup hook handles credential prompts.
• Plugin, not core. Lives entirely under plugins/web/xai/ mirroring the plugins/web/brave_free/ layout, registers via the standard register(ctx) plugin hook, and touches only 11 lines of tools/web_tools.py (one set-element + one if-branch in _is_backend_available).
• Cheap is_available(). The ABC contract requires is_available() to be safe to call on every hermes tools repaint and at tool-registration time. The provider uses a new has_xai_credentials() helper that does an env-var check + single auth.json read — never invokes the OAuth resolver (which can trigger a network token refresh).

Related Issue

Fixes #

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

Provider behavior:

• Sends a structured prompt to Grok with tools=[{"type": "web_search"}] enabled and include=["no_inline_citations"] so URLs come back from annotations / citations rather than inline markdown.
• Primary parse path: extract a {"results": [...]} JSON block from output[*].content[*].text. Tolerates leading/trailing prose because reasoning models occasionally narrate.
• Fallback 1: derive results from url_citation annotations + surrounding-text descriptions.
• Fallback 2: derive from top-level citations list (URLs only).
• HTTP 200 + {"error": {...}} envelopes (model-overload, refusal) are surfaced as failures rather than masked as success-with-empty-results.
• allowed_domains / excluded_domains config keys map to xAI's domain filters; capped at 5 each per the API; mutual-exclusion enforced locally to skip a known-bad request.

Config (config.yaml):

web:
  backend: xai
  xai:
    model: grok-4.3              # optional, defaults to grok-4.3
    allowed_domains:             # optional, max 5 — mutually exclusive with excluded_domains
      - arxiv.org
    excluded_domains:            # optional, max 5
      - example-spam.com
    timeout: 90                  # optional, seconds

How to Test

1. Run the new test suite:

   scripts/run_tests.sh tests/tools/test_web_providers_xai.py -v

   Expected: 35 passed.

2. Sibling-provider regression check:

   scripts/run_tests.sh tests/tools/test_web_providers_brave_free.py \
                       tests/tools/test_web_providers_ddgs.py \
                       tests/tools/test_web_providers_searxng.py \
                       tests/tools/test_web_providers.py -q

   Expected: 79 passed, no regressions.

3. Live smoke test (requires xAI credentials):

   # Option A: env-var path
   export XAI_API_KEY="sk-xai-…"
   
   # Option B: OAuth path (SuperGrok subscription)
   hermes auth login xai-oauth
   
   # Configure backend
   echo 'web:\n  backend: xai' >> ~/.hermes/config.yaml
   
   # Exercise via CLI
   hermes --toolsets web -q "Search the web for the latest xAI Grok release notes"

   Expected: agent calls web_search, results come back as {title, url, description, position} rows, no credential prompts, no errors.

4. Verify is_available() is cheap (regression-guard test asserts the resolver is never called):

   scripts/run_tests.sh tests/tools/test_web_providers_xai.py::TestXAIProviderIsAvailable::test_is_available_does_not_call_resolver -v

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(web):, fix(web/xai):)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run scripts/run_tests.sh and all tests pass (35 new + 79 adjacent green)
• I've added tests for my changes (35-test suite)
• I've tested on my platform: macOS 15.2 (darwin 24.6.0)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — provider has extensive docstrings; config keys documented in provider.py module docstring
• I've updated cli-config.yaml.example if I added/changed config keys — N/A (web.xai.* keys are documented in the provider module docstring; no top-level schema change)
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A (uses existing plugin + web-provider patterns)
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — pure-Python, only depends on httpx (already a dep); no POSIX-only primitives
• I've updated tool descriptions/schemas if I changed tool behavior — N/A (no tool schema changes; this is a backend plugin behind the existing web_search tool)

For New Skills

N/A — this PR adds a web search provider plugin, not a skill.

Screenshots / Logs

Test run output:

$ scripts/run_tests.sh tests/tools/test_web_providers_xai.py -q
4 workers [35 items]
....................................                                     [100%]
============================== 35 passed in 1.95s ==============================

Sibling-suite regression check:

$ scripts/run_tests.sh tests/tools/test_web_providers_brave_free.py \
                       tests/tools/test_web_providers_ddgs.py \
                       tests/tools/test_web_providers_searxng.py \
                       tests/tools/test_web_providers.py -q
........................................................................ [ 91%]
.......                                                                  [100%]
79 passed in 3.24s

Trust-model note (also captured in the provider class docstring): unlike index-backed providers (Brave / Tavily / Exa) which return verbatim search-engine results, this backend is an LLM that decides which URLs to surface, generates titles and descriptions itself, and is influenced by the content of the query. A maliciously crafted query (e.g. injected via untrusted upstream input the agent picked up) can in principle steer Grok into emitting attacker-chosen URLs. Callers that pipe untrusted text directly into web_search should treat returned URLs the same way they'd treat any model-generated link, validate before fetching.