feat(desktop): make xAI Grok a first-class OAuth provider in the launcher by OutThisLife · Pull Request #37697 · NousResearch/hermes-agent

OutThisLife · 2026-06-02T22:34:54Z

Summary

xAI Grok was only reachable through the desktop's "I have an API key" form, even though a full xAI OAuth (SuperGrok / Premium+) flow already exists in the backend (hermes auth add xai-oauth). This promotes it to a first-class one-click provider card in the onboarding launcher, alongside Nous / Anthropic / OpenAI Codex / MiniMax.

It introduces a loopback PKCE flow: the desktop's local Python backend binds the 127.0.0.1 callback listener, the client opens the browser, and the redirect lands back automatically — nothing to copy or paste. The implementation reuses the existing xAI OAuth helpers (discovery, callback server, token exchange, persist) rather than duplicating them.

Backend (`hermes_cli/web_server.py`)

xai-oauth added to _OAUTH_PROVIDER_CATALOG with flow: "loopback" (now listed by /api/providers/oauth)
status dispatch → auth.get_xai_oauth_auth_status() so the card shows Connected
_start_xai_loopback_flow() + _xai_loopback_worker() (waits for callback, validates state, exchanges code, persists to auth store + credential pool — mirrors hermes auth add xai-oauth)
loopback branch wired into the start_oauth_login route; disconnect works via the generic clear_provider_auth

Desktop (`apps/desktop`)

types/hermes.ts: 'loopback' flow + LoopbackStart response shape
store/onboarding.ts: new awaiting_browser status; startProviderOAuth opens the auth URL and polls (generalized pollDevice → pollSession)
desktop-onboarding-overlay.tsx: "xAI Grok" card title, loopback subtitle, and a waiting panel

Notes

The first-class card is the OAuth (SuperGrok / Premium+) path; the plain XAI_API_KEY path still lives in the API-key form (same split as Anthropic / OpenAI Codex).
This _OAUTH_PROVIDER_CATALOG + hardcoded API_KEY_OPTIONS split is the thing to collapse in the follow-up that feeds the selector dynamically from /providers.

Test plan

Desktop tsc -b typecheck clean; ESLint clean on edited files (repo-wide lint errors are pre-existing)
tests/hermes_cli/test_web_oauth_dispatch.py (12), test_web_server.py (211), test_auth_xai_oauth_provider.py (82), test_xai_oauth_pkce_token_exchange.py (14) all pass
New tests: catalog listing, start authorize-url, worker token persist, state-mismatch rejection
Live end-to-end OAuth from the desktop app against real xAI (not yet run — unit coverage is mocked)

…cher xAI Grok was only reachable via the "I have an API key" form. xAI's OAuth (SuperGrok / Premium+) flow already exists in the backend (`hermes auth add xai-oauth`) but was never surfaced in the desktop onboarding launcher. Add a loopback PKCE flow: the local backend binds the 127.0.0.1 callback listener, the client opens the browser, and the redirect lands back automatically — no code to copy/paste. Reuses the existing xAI OAuth helpers (discovery, callback server, token exchange, persist) rather than duplicating them. - web_server: catalog entry (flow: loopback) + status dispatch + _start_xai_loopback_flow + background worker + route branch - desktop: 'loopback' flow type, awaiting_browser status, xAI Grok card (PROVIDER_DISPLAY / FLOW_SUBTITLES / FlowPanel waiting render) - tests: catalog listing, start authorize-url, worker persist, state mismatch rejection

github-actions · 2026-06-02T22:35:45Z

🔎 Lint report: `bb/grok-provider-desktop` 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: 9683 on HEAD, 9682 on base (🆕 +1)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 5016 pre-existing issues carried over.

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

Copilot

Pull request overview

Promotes xAI Grok OAuth to a first-class onboarding provider in the desktop launcher by adding a new loopback PKCE flow to the local FastAPI backend and wiring the desktop UI/store to open the browser and poll session status until completion.

Changes:

Backend: add xai-oauth to the OAuth provider catalog and implement loopback PKCE start + background worker to complete token exchange and persistence.
Desktop: extend OAuth flow typing/state machine with loopback + awaiting_browser, open the authorize URL, and poll the session until approved/error.
Tests: add coverage for provider catalog listing, loopback start response, successful persistence, and state-mismatch rejection.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`tests/hermes_cli/test_web_oauth_dispatch.py`	Adds unit tests for xAI loopback flow listing/start/worker success + state mismatch.
`hermes_cli/web_server.py`	Adds `xai-oauth` provider entry, status dispatch, loopback flow implementation, and start route wiring.
`apps/desktop/src/types/hermes.ts`	Adds `loopback` flow and start-response typing.
`apps/desktop/src/store/onboarding.ts`	Adds `awaiting_browser` state and generalizes polling to support loopback sessions.
`apps/desktop/src/components/desktop-onboarding-overlay.tsx`	Adds xAI provider card ordering/title and a waiting panel for loopback flow.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- web_server: join the callback-server thread in the start error path so a failed discovery/URL build doesn't leave a daemon thread running - web_server: loopback worker now bails if the session was cancelled while waiting for the callback or exchanging the code, instead of persisting tokens the user no longer wants (+ regression test) - onboarding: fall back to window.open when the desktop bridge's openExternal is unavailable, so the flow never silently stalls

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

- onboarding: openSignInUrl now falls back to window.open when the desktop bridge's openExternal throws/rejects (OS handler missing, user denied), not just when the bridge is absent - web_server: cancelling a loopback session shuts down the 127.0.0.1 callback server + joins its thread immediately, freeing the port instead of holding it until the wait times out (+ regression test) - web_server: document the new "loopback" flow in the /api/providers/oauth enum, the poll-endpoint docstring, and the Phase 2 flow comment block

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

source_label is meant to be a human-readable origin (file path / source), not the internal auth_mode string ("oauth_pkce"). Surface the auth-store path, then the source slug, then a generic label.

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Shutting down the callback server stopped the serve thread but left the worker spinning in _xai_wait_for_callback (which polls callback_result) until the timeout. Flag callback_result as cancelled on DELETE so the wait returns promptly and the daemon thread exits — avoids thread buildup on repeated cancel/retry.

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

…der-desktop feat(desktop): make xAI Grok a first-class OAuth provider in the launcher

feat(desktop): make xAI Grok a first-class OAuth provider in the launcher

…der-desktop feat(desktop): make xAI Grok a first-class OAuth provider in the launcher

fix(desktop): order xAI Grok after MiniMax in the OAuth catalog

63e8248

OutThisLife requested a review from Copilot June 2, 2026 22:42

alt-glitch added type/feature New feature or request provider/xai xAI (Grok) comp/cli CLI entry point, hermes_cli/, setup wizard P3 Low — cosmetic, nice to have labels Jun 2, 2026

Copilot started reviewing on behalf of OutThisLife June 2, 2026 22:42 View session