dsh-llm-xai-oauth

You already pay for SuperGrok / X Premium. This plugin puts that subscription into DeepSeek Harness as a live xai route: grok-4.6, device-code login, token refresh that does not depend on a TUI being open. No xAI API key.

Works in headless, web, and any terminal profile. The SSH TUI dsh-ssh-tui can sit on top; it is not required.

中文：README.zh.md

Listed on dshfind:

Install from npm (do not use the GitHub source unless you are developing):

dsh plugin --profile headless add dsh-llm-xai-oauth@latest
npx dsh-llm-xai-oauth login
npx dsh-llm-xai-oauth daemon --install
dsh --profile headless --provider xai --model grok-4.6

Swap headless for web or tui. Updates must use @latest. A bare add dsh-llm-xai-oauth keeps whatever version pnpm already pinned.

Three facts that matter

1. This is subscription OAuth, not an API key. After install, dsh talks to https://cli-chat-proxy.grok.com with the access token in ~/.grok-bridge/auth.json.
2. The access token lasts about an hour. While dsh is running, the plugin refreshes five minutes before expiry and again on HTTP 401. If dsh is not running, that refresh does not happen.
3. So you need a refresher that is not the dsh process. Use dsh-llm-xai-oauth daemon. Do not expect the TUI or a headless one-shot to keep the token alive overnight.

/usage returning 401, then chat also 401, almost always means: the token expired and nothing was refreshing it.

Setup in five minutes

You need Node.js ≥ 22.19 and a DeepSeek Harness CLI (npm i -g @deepseek-ai/dsh). Verified on 0.1.2-rc.1 and 0.1.5-rc.1 / 0.1.5-rc.2. 0.1.6-alpha is not supported; stay on 0.1.5-rc.2.

1. Add the plugin to a profile

dsh plugin --profile headless add dsh-llm-xai-oauth@latest
dsh plugin --profile web add dsh-llm-xai-oauth@latest
dsh plugin --profile tui add dsh-llm-xai-oauth@latest

Confirm the bundle landed (id: llm-xai-oauth). Without that line, /model will not have a live SuperGrok route:

dsh --profile headless --dump-config | grep llm-xai-oauth

A local checkout is for development. Prefer npm; a bare github: install is what outdated directories still suggest, and pnpm ≥ 10 will refuse its prepare script until you allow builds.

2. Log in once (from a machine that can open a browser)

If grok-bridge or the official Grok CLI already left ~/.grok-bridge/auth.json or ~/.grok/auth.json on this machine, this step reuses it and does not open a browser.

Otherwise, from a terminal that can open auth.x.ai:

npx dsh-llm-xai-oauth login
# force a new device-code even when a token already exists:
npx dsh-llm-xai-oauth login --force

The CLI prints a URL and a user code. Authorize SuperGrok / X Premium in the browser. On success it writes:

• token: ~/.grok-bridge/auth.json (0600)
• dsh default model: $DSH_HOME/settings.yaml agent-default-model → xai / grok-4.6
  (if that section is already xai, your grok model and effort are left alone)

Headless / CI hosts without a TTY skip the prompt. Set DSH_XAI_OAUTH_NO_LOGIN=1 to skip it even on a TTY.

Check remaining lifetime:

npx dsh-llm-xai-oauth status

3. Keep the token fresh (this is not dsh)

Access tokens are short. A TUI, headless job, or cron that starts after expiry will read a dead token; /usage and chat then 401.

Recommended: a user systemd unit

npx dsh-llm-xai-oauth daemon --install

That writes ~/.config/systemd/user/dsh-llm-xai-oauth.service and enable --now. The process re-reads auth.json about once a minute and refreshes five minutes before expiry. dsh does not need to be running.

No systemd, or you do not want a user unit:

# foreground
npx dsh-llm-xai-oauth daemon

# or cron every 20 minutes (no-op while the token is still valid)
*/20 * * * * npx --yes dsh-llm-xai-oauth refresh >/tmp/dsh-xai-refresh.log 2>&1

Remove the user unit:

npx dsh-llm-xai-oauth daemon --uninstall

Refresh once by hand:

npx dsh-llm-xai-oauth refresh
npx dsh-llm-xai-oauth refresh --force

4. Run one SuperGrok turn

grep -A3 agent-default-model ~/.dsh/settings.yaml

dsh --profile tui --provider xai --model grok-4.6
dsh --profile headless "Reply with exactly: xai-harness-ok. Do not use tools."

In dsh-ssh-tui: /model picks Grok; /usage reads the SuperGrok weekly remaining quota. The TUI now refreshes a due token before /usage, and on 401 it force-refreshes once and retries. That covers “I opened the TUI just as the token expired”. It does not cover “the machine slept overnight with no refresher”. Step 3 is that refresher.

Switching models later

# $DSH_HOME/settings.yaml
agent-default-model:
  provider: xai
  model: grok-4.6
  reasoningEffort: high

Or pass --provider / --model, or use /model in the TUI. At startup the plugin calls GET {baseURL}/models with the current token; /model prefers that live catalog (currently grok-4.6 with xhigh, grok-4.5 up to high). The static fallback still lists grok-4.3.

max in a DeepSeek-style picker maps to xhigh.

Optional plugin settings live under llm-xai-oauth: in $DSH_HOME/settings.yaml (baseURL, reasoningEffort, models, retry / idle timeout). Change them without restarting; the next request re-resolves.

Long SuperGrok chats can fill the 500K window and then 400 with a generic INVALID_REQUEST because max_tokens no longer fits. From 0.1.3 the adapter projects the next prompt from the last usage sample and, when remaining context cannot hold the requested completion, throws CONTEXT_WINDOW_EXCEEDED so harness overflow compaction can retry. Compaction / title calls still go through, with max_tokens clamped to the remainder.

401 / expiry

npx dsh-llm-xai-oauth status
ls -l ~/.grok-bridge/auth.json
systemctl --user status dsh-llm-xai-oauth.service
journalctl --user -u dsh-llm-xai-oauth.service -n 50

HTTPS_PROXY / HTTP_PROXY apply to login, refresh, and chat.

Override client / endpoints only when xAI changes them:

What it is not

• Not an xAI API-key provider. Metered api.x.ai stays on the generic catalog.
• Not a Codex / Claude / Copilot aggregator.
• Not a Web “one-click login” settings card. Device login is CLI / TTY.
• Does not registerConfigurableProviders('xai'); llm-pi-ai already owns that catalog key. This package owns the live adapter route.

Layout

src/index.ts        Cordis plugin: search / login / register the xai route
src/cli.ts          login / status / refresh / daemon
src/bootstrap.ts    local token search, device login, dsh default model
src/oauth.ts        load / refresh / device-code
src/adapter.ts      fetch + SSE chat-completions adapter (retries once on 401)
src/context-budget.ts  project remaining context and trip harness overflow compaction
cordis.patch.yml    profile bundle insert

License

MIT