dsh-llm-grok

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

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.x, 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.

Plugin configuration

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.x, 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.