feat(xai): add first-class xai-oauth provider + correct base grok-4.3 context length (512k)

[am423]

Summary

Adds proper first-class support for using Grok models via the official Grok CLI OAuth login (xai-oauth).

This fixes the "response.created before error" issue for users who use grok login credentials in Hermes.

Key Changes

• New plugin: plugins/model-providers/xai-oauth/
• Runtime resolution forces chat_completions for OAuth tokens
• x-grok-conv-id header support on chat_completions transport
• Correct context length (base grok-4.3 = 512k)
• New dedicated guide: website/docs/guides/grok-oauth.md
• Updated public docs + test + AGENTS.md guidance

Testing

• New test passes
• Manual verification with real Grok CLI credentials successful

Ready for review.

[am423]

PR Overview

This adds proper xai-oauth support so people who use the official Grok CLI can have a first-class experience in Hermes without needing a separate XAI_API_KEY.

Scope

• Runtime safety (prevents Responses API misuse with OAuth tokens)
• Prompt caching support on the chat_completions path
• Correct context length handling for base vs fast Grok-4.3 variants
• Full documentation (new dedicated guide + updates)
• Test coverage + contributor notes in AGENTS.md

Review Focus Areas

• Runtime resolution logic in hermes_cli/runtime_provider.py
• Header injection in agent/transports/chat_completions.py
• Context length fallbacks in agent/model_metadata.py
• New guide quality (website/docs/guides/grok-oauth.md)

Happy to address any feedback quickly. Thanks!

[github-actions]

🔎 Lint report: feat/xai-oauth-grok-support vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 8341 on HEAD, 8340 on base (🆕 +1)

🆕 New issues (4):

Rule	Count
invalid-argument-type	3
unresolved-import	1

First entries

run_agent.py:13711: [invalid-argument-type] invalid-argument-type: Argument to function `_is_oauth_token` is incorrect: Expected `str`, found `str | dict[Unknown | str, Unknown | str | dict[str, str]] | Any | ... omitted 3 union elements`
run_agent.py:7480: [invalid-argument-type] invalid-argument-type: Argument to function `build_anthropic_client` is incorrect: Expected `str`, found `str | dict[Unknown | str, Unknown | str | dict[str, str]] | Any | ... omitted 3 union elements`
run_agent.py:13714: [invalid-argument-type] invalid-argument-type: Argument to function `len` is incorrect: Expected `Sized`, found `(str & ~AlwaysFalsy) | (dict[Unknown | str, Unknown | str | dict[str, str]] & ~AlwaysFalsy) | (Any & ~AlwaysFalsy) | ... omitted 3 union elements`
hermes_cli/runtime_provider.py:288: [unresolved-import] unresolved-import: Module `hermes_cli.auth` has no member `resolve_xai_oauth_runtime_credentials`

✅ Fixed issues (3):

Rule	Count
invalid-argument-type	3

First entries

run_agent.py:7480: [invalid-argument-type] invalid-argument-type: Argument to function `build_anthropic_client` is incorrect: Expected `str`, found `str | dict[Unknown, Unknown] | Any | ... omitted 3 union elements`
run_agent.py:13714: [invalid-argument-type] invalid-argument-type: Argument to function `len` is incorrect: Expected `Sized`, found `(str & ~AlwaysFalsy) | (dict[Unknown, Unknown] & ~AlwaysFalsy) | (Any & ~AlwaysFalsy) | ... omitted 3 union elements`
run_agent.py:13711: [invalid-argument-type] invalid-argument-type: Argument to function `_is_oauth_token` is incorrect: Expected `str`, found `str | dict[Unknown, Unknown] | Any | ... omitted 3 union elements`

Unchanged: 4385 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.