dsh-llm-grok
English | 中文
xAI Grok integration for DeepSeek Harness. This plugin is a separate provider route (grok) and settings namespace (llm-grok). It does not replace the built-in xai console API-key route, and it does not declare apiKeyEnv.
The package root exposes the Cordis plugin contract. The same artifact exports ./client, which contributes the Grok card under Settings → LLM Providers.
Compatibility
DSH peer and compile-time dependency ranges accept 0.1.7-alpha.2 and later releases; Cordis peers accept >=4.0.4 <5.0.0.
Verified Hosts in package.json#dsh.compatibility.dshReleases are evidence, not an allowlist. Unknown newer Hosts warn once and keep the normal mount path. Only a reproduced failure is blocklisted.
catalogId and the unresolved unknown account state are attached at runtime. The older dsh-llm-providers-ui 0.2.8 omits those fields and treats unknown as unconnected; install Owner 0.2.12 or newer.
LLM Providers UI ownership
The LLM Providers Settings page (settings.section id: providers with child settings.provider.item) and the shared llm-providers order store are owned solely by dsh-llm-providers-ui.
- This plugin contributes only its keyed card (
key: llm-grok) and its Host llm route; it does not install the page or the shared llm-providers namespace. Load order with the owner does not matter.
- Without the owner (Headless or Web without
dsh-llm-providers-ui): the Host model route grok still works; in Web the Providers page and this card are omitted. pack:check verifies the owner artifact identity, ./sortable export, and packed client closure.
- The nav globe glyph is a temporary Alpha.4 DOM adapter owned only by
dsh-llm-providers-ui (src/client/nav-icon.ts); this plugin does not ship that adapter.
- Type resolution:
tsconfig.json maps @deepseek-ai/dsh-client-ui-slots and @deepseek-ai/cordis to their installed type declarations so the client typecheck resolves a single copy of each instead of duplicate type closures.
Install dsh-llm-providers-ui explicitly in the profile alongside provider plugins (see that package's cordis.patch.yml).
Installation
Verified on official DeepSeek Harness 0.1.7-alpha.2 and 0.1.7-rc.1. Install directly from GitHub:
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.13/dsh-llm-providers-ui-0.2.13.tgz
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-grok/releases/download/v0.3.21/dsh-llm-grok-0.3.21.tgz
dsh web
The repository tracks release-ready lib artifacts, so GitHub installation needs no build-script allowlist.
Web configuration
Open Settings → LLM Providers → Grok. Sign in with xAI starts a Host-owned PKCE flow against auth.x.ai (the Grok CLI public client), opens the system browser, and stores the session only on the Host at $DSH_HOME/grok-oauth.json (mode 0600). The card then shows the account email. Sign out deletes that file. The browser never receives tokens. This plugin does not read or write ~/.grok/auth.json.
Plugin configuration
Grok Plugin card: subscription login, usage, and model catalog
The Plugin card keeps two catalogs: the signed-in account list from GET /v1/models-v2, and the displayed subset stored as settings.models. The conversation picker uses only the displayed subset. Each row can set Default thinking and a Context window used as the DSH compaction budget. Official grok-4.6 / grok-4.5 default to 500,000 tokens. The card catalog starts collapsed; it can be reordered, edited, deleted, or replaced from the account list. When the subset has never been saved, the frozen default is grok-4.6 and grok-4.5. Chat goes to POST https://cli-chat-proxy.grok.com/v1/responses. Every request includes DSH function tools plus always-on server-side { type: "web_search" } and { type: "x_search" }. Search is not a ctx.web provider. Server search returns encrypted tco_* reasoning items with empty summaries; those stay in replay and no longer each paint an empty Think row. If Grok also echoes the same search as a client custom_tool_call (xs_call-* / ws_call-*, often named x_keyword_search), the plugin drops it so DSH does not report unknown tool. Reasoning is sent as official Responses reasoning: { effort }, with values low / medium / high (default) / xhigh (4.6 only). When signed in, the card also shows subscription usage from a Host billing read (GET /v1/billing?format=credits). The signed-in card starts its cached billing read while collapsed; expansion does not refetch. Logged-out cards do not request billing. For a valid active credits period with no paid or legacy budget, omitted proto3 zero usage is decoded as zero; malformed or ambiguous paid data is not defaulted. Only a missing billing endpoint (404) is unsupported; malformed or unrecognized successful responses are query errors, without invented quota values.
The collapsed header first-paints the last successful quota from the shared browser cache when no live reading is available (never on error or unsupported); signing in, signing out, or an authoritative signed-out status purges the cached quota in every bundle copy, even without providerDirectory; so does a usage read that cannot resolve a usable credential, which the Host answers as INVALID_CREDENTIAL instead of a generic failure.
With dsh-model-switch v0.4.5+, Grok also registers an optional Image-only adapter for the stable generate_image router. It reuses the same authenticated implementation and registers no Search or Vision adapter. Standalone behavior is unchanged.
Optional grok_image_gen (default off) registers a model-facing tool that generates an image with Grok Imagine. It reuses the same Host OAuth session and posts https://api.x.ai/v1/images/generations — the same rail Grok Build's local image_gen uses, not a console API key and not the chat proxy. The name is distinct from Codex codex_generate_image. Generated bytes are saved to the workspace and committed through the attachment store.
Chat without a session fails MISSING_CREDENTIAL. A stored session whose refresh fails is cleared and fails AUTH. ensureFreshSession runs before each chat request. A later content-less AUTH (HTTP 401) force-refreshes the session and retries the request once; remaining AUTH failures are eligible for the bundle's eight normal retries.
Every proxy request sends this plugin's X-Dsh-Plugin identity plus the CLI version headers the proxy requires (x-grok-client-version / x-grok-client-identifier). A missing version is answered 426. Those headers are required by the proxy and do not attempt to impersonate the official CLI product.
The Models page, if it lists Grok at all, is hint-only. Because this package does not declare apiKeyEnv, that row must not show a missing-API-key badge.
Config
- id: llm-grok
name: 'dsh-llm-grok'
config:
streamIdleTimeoutMs: 300000
retryPolicy:
mode: normal
maxRetries: 8
backoff:
initialDelayMs: 500
maxDelayMs: 10000
jitterRatio: 0.1
The bundle retries eligible model-request failures up to eight times by default, including AUTH. xAI capacity/high-demand failures are classified as RATE_LIMIT; temporary availability degradation is classified as SERVER.
There is no apiKeyEnv and no user-editable base URL. models is the displayed conversation catalog, a subset of the account list.
The composer picker groups sibling catalog rows that share a base id after peeling a Fast suffix (-fast) and a generic context suffix (-<n>k / -<n>m). Product names such as kimi-k3-max are not treated as a context tier. This package's catalog comes from discovery; add extra suffix rows yourself if you want DSH to compact against a smaller budget. This plugin does not peel those suffixes on the wire.
Release installation (Latest)
xAI Grok subscription login, Responses chat, usage, search, and Imagine. The release artifact targets official DeepSeek Harness 0.1.7-rc.1 and contains built Host/Client files only; it has no sibling-repository source, workstation path, link:, or workspace: dependency.
The dsh-llm-providers-ui package owns the LLM Providers page, navigation, and shared order store. This package owns only its provider card, models, credentials, and Host route. Install the Owner first for Web; headless Host routing works without the Owner.
Latest (Owner + this plugin; required together on Web):
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.13.tgz
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-grok/releases/latest/download/dsh-llm-grok-0.3.21.tgz
Fixed versions (reproducible):
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.13/dsh-llm-providers-ui-0.2.13.tgz
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-grok/releases/download/v0.3.21/dsh-llm-grok-0.3.21.tgz
Update, uninstall, and verify:
# Update Owner + this plugin to Latest
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.13.tgz
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-grok/releases/latest/download/dsh-llm-grok-0.3.21.tgz
# Verify the loaded version
dsh plugin --profile web list
dsh plugin --profile web doctor
# Uninstall only this plugin
dsh plugin --profile web remove dsh-llm-grok
Configuration: use the plugin section in Settings for Web UI plugins, or the profile dsh.profile.bundles entry for Host-only plugins. Start with this README's minimal YAML/JSON example and provide credentials/backend addresses explicitly.
Rollback: reinstall the prior stable v0.3.18, verify the profile list, then restart the Web service once. Inspect journalctl --user -u dsh-web.service and dsh plugin --profile web doctor; never put a source checkout in the production profile.
Release and integrity: v0.3.21 · SHA256SUMS.
Independent Model Switch search
The Host registers Search and Image adapters together through the existing Model Switch registry, with lifecycle disposal. Independent search declares the supported Grok chat models and calls the existing subscription Responses endpoint with required server-side search tools. It reuses the provider token resolver and identity headers. Only native URL citations/search-call results become sources; missing credentials, unsupported models and responses without search evidence fail explicitly. Upstream error bodies are not exposed. This is distinct from a conversational model merely having native networking enabled.
This requires the coordinated Model Switch dynamic-search implementation (dsh-model-switch 0.4.7; the adapter itself builds against the 0.4.6 registry contract). Registering an adapter does not select global Web routing: explicitly configure web.searchProvider: model-switch, retaining every other Web config field, then choose the provider/model in Model Switch. No replacement web tool is registered; web_fetch is unchanged. ProviderDirectory deferred role/usage integration is preserved.
Validation: pnpm test (198 passed), pnpm run build; 3082 official Web selection returned real sources with both grok-4.6 and grok-4.5 in sequence. See the Model Switch integration audit for exact lab composition and evidence.
