hermes - 💡(How to fix) Fix [Bug]: xAI OAuth loopback on macOS: local callback received, but Hermes times out [4 pull requests]

Bug Description

Trying to set up xAI Grok OAuth on a local macOS Hermes install.

The browser callback succeeds and shows:

xAI authorization received.
You can close this tab.

but Hermes still throws:

hermes_cli.auth.AuthError: xAI authorization timed out waiting for the local callback.

No xAI credentials are stored, and hermes doctor continues to show no xAI auth provider.

This seems different from the documented “remote/SSH” cases where the callback never reaches the loopback listener.

Steps to Reproduce

1. Run Hermes locally on macOS (no Docker, no WSL, no remote host):

   hermes auth add xai-oauth

2. Hermes prints something like:

   Open this URL to authorize Hermes with xAI:
   https://auth.x.ai/oauth2/authorize?response_type=code&client_id=b1a00492-073a-47ea-816f-4c329264a828&redirect_uri=http%3A%2F%2F127.0.0.1%3A56121%2Fcallback&scope=openid+profile+email+offline_access+grok-cli%3Aaccess+api%3Aaccess&code_challenge=...&code_challenge_method=S256&state=...&nonce=...&plan=generic&referrer=hermes-agent
   
   Waiting for callback on http://127.0.0.1:56121/callback
   Browser opened for xAI authorization.

3. The browser opens accounts.x.ai. Log in with a valid SuperGrok subscription and click Authenticate.

4. xAI then shows a page with (German UI):

   Verbindung konnte nicht hergestellt werden
   Wir konnten Ihre App nicht erreichen. Bitte kopieren Sie den unten stehenden Code in Grok Build ein.
   Bitte aktualisieren Sie diese Seite nicht. Sie erkennt eine erfolgreiche Fertigstellung automatisch.

   A code is displayed on that page.

5. While Hermes is still printing Waiting for callback on http://127.0.0.1:56121/callback in the terminal, manually open the callback URL directly in the same browser:

   http://127.0.0.1:56121/callback

6. The browser then shows:

   xAI authorization received.
   You can close this tab.

   So the loopback listener seems to receive and handle the callback.

7. Despite that, Hermes immediately crashes with:

   Traceback (most recent call last):
     File "/Users/nimarfranklinmac/.local/bin/hermes", line 8, in <module>
       sys.exit(main())
                ^^^^^^
     File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/main.py", line 12435, in main
       args.func(args)
     File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/main.py", line 5504, in cmd_auth
       auth_command(args)
     File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/auth_commands.py", line 727, in auth_command
       auth_add_command(args)
     File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/auth_commands.py", line 339, in auth_add_command
       creds = auth_mod._xai_oauth_loopback_login(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/auth.py", line 5356, in _xai_oauth_loopback_login
       callback = _xai_wait_for_callback(
                  ^^^^^^^^^^^^^^^^^^^^^^^
     File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/auth.py", line 2207, in _xai_wait_for_callback
       raise AuthError(
   hermes_cli.auth.AuthError: xAI authorization timed out waiting for the local callback.

8. Running hermes doctor afterwards still does not show any xAI auth provider, and ~/.hermes/auth.json has no xai-oauth entry.

Expected Behavior

After the browser shows “xAI authorization received. You can close this tab.”, Hermes should:

• accept the callback,
• exchange the code for tokens,
• store an xAI OAuth credential (e.g. xai-oauth) in ~/.hermes/auth.json,
• and hermes doctor should list xAI as an authenticated provider.

Actual Behavior

Screenshots / terminal output text Relevant terminal output:

Hermes Agent v0.14.0 (2026.5.16)
Project: /Users/nimarfranklinmac/.hermes/hermes-agent
Python: 3.11.11
OpenAI SDK: 2.24.0
Up to date

nimarfranklinmac@MacBook-Air-von-Nimar-3 ~ % hermes auth add xai-oauth

Open this URL to authorize Hermes with xAI:
https://auth.x.ai/oauth2/authorize?response_type=code&client_id=b1a00492-073a-47ea-816f-4c329264a828&redirect_uri=http%3A%2F%2F127.0.0.1%3A56121%2Fcallback&scope=openid+profile+email+offline_access+grok-cli%3Aaccess+api%3Aaccess&code_challenge=pEr8T8KYeMuiL-SL4z9glsaeLUFSywKWBgtJWOpUZx0&code_challenge_method=S256&state=889152b48aee47d5a5b17c1535e89193&nonce=4777b8a77f4d4a08beed807f3e1b38a9&plan=generic&referrer=hermes-agent

Waiting for callback on http://127.0.0.1:56121/callback
Browser opened for xAI authorization.
Traceback (most recent call last):
  File "/Users/nimarfranklinmac/.local/bin/hermes", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/main.py", line 12435, in main
    args.func(args)
  File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/main.py", line 5504, in cmd_auth
    auth_command(args)
  File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/auth_commands.py", line 727, in auth_command
    auth_add_command(args)
  File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/auth_commands.py", line 339, in auth_add_command
    creds = auth_mod._xai_oauth_loopback_login(
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/auth.py", line 5356, in _xai_oauth_loopback_login
    callback = _xai_wait_for_callback(
               ^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nimarfranklinmac/.hermes/hermes-agent/hermes_cli/auth.py", line 2207, in _xai_wait_for_callback
    raise AuthError(
hermes_cli.auth.AuthError: xAI authorization timed out waiting for the local callback.

Environment text

• OS: macOS <your version here, e.g. 14.4.1>
• Hermes Agent: v0.14.0 (2026.5.16), Up to date
• Python: 3.11.11
• Install type: local macOS (no Docker/WSL/remote host)
• Network: no SSH tunnel, no VPN, browser and Hermes running on the same machine Additional context text
• This is not the remote/SSH case described in the “OAuth over SSH / Remote Hosts” guide. The loopback callback is reachable on 127.0.0.1:56121.
• Browser language is German, which is why the xAI error page text is localized (“Verbindung konnte nicht hergestellt werden …”). Behavior seems independent of language.
• Happy to test a debug build or add extra logging around _xai_wait_for_callback / _xai_oauth_loopback_login if that helps.

Affected Component

Configuration (config.yaml, .env, hermes setup)

Messaging Platform (if gateway-related)

No response

Debug Report

Report       https://paste.rs/lyxnw
  agent.log    https://paste.rs/Xz6S3
  gateway.log  https://paste.rs/3uUPV

Operating System

macOS 26.3.1 (a) (25D771280a)

Python Version

Python 3.14.4

Hermes Version

Hermes Agent v0.14.0 (2026.5.16)

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR