dsh-plugin-subscription-oauth 0.0.0-stage → 0.2.0

package/lib/providers/grok.js

@@ -0,0 +1,700 @@
+/**
+ * The `grok` provider route: xAI / X Premium (SuperGrok) subscription access.
+ *
+ * Login is an OIDC authorization-code flow with PKCE against `auth.x.ai`,
+ * discovered from the issuer's well-known document and completed on a loopback
+ * callback the CLI's registered client allows. Requests then go over xAI's
+ * Responses endpoint, which the shared Responses translator already speaks.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/grok
+ */
+import { errorChain, LlmAdapter, LlmError, ReasoningEffortId, } from '@deepseek-ai/dsh-llm';
+import { REAUTH_REQUIRED, ProviderError } from '../errors.js';
+import { attributedHeaders } from '../auth/headers.js';
+import { LoopbackFlow } from '../auth/pkce-flow.js';
+import { TokenStore, finiteInstant, nonEmpty } from '../auth/store.js';
+import { TokenManager } from '../auth/tokens.js';
+import { ProviderController } from '../auth/provider-controller.js';
+import { proxiedFetch } from '../http.js';
+import { fallbackEntry, findEntry, resolveCatalog } from './catalog.js';
+import { isMissingOrInvalidCredential } from './common.js';
+import { streamProviderResponses } from './responses-stream.js';
+import { readGrokUsage } from './usage.js';
+import { toResponsesInput, toResponsesTools } from '../translate/responses.js';
+/** Route key this module registers. */
+export const GROK_PROVIDER_ID = 'grok';
+/** Display name for selectors and diagnostics. */
+export const GROK_PROVIDER_NAME = 'Grok (X Premium)';
+/** Where a user manages the underlying subscription. */
+export const GROK_CODE_URL = 'https://x.ai/grok';
+/** OIDC issuer whose well-known document names the endpoints. */
+export const GROK_ISSUER = 'https://auth.x.ai';
+/** Discovery document URL. */
+export const GROK_DISCOVERY_URL = `${GROK_ISSUER}/.well-known/openid-configuration`;
+/** The Grok CLI's registered client id. */
+export const GROK_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828';
+/** Scopes the CLI requests; `grok-cli:access` is what admits subscription traffic. */
+export const GROK_SCOPE = 'openid profile email offline_access grok-cli:access api:access';
+/** The one loopback port the registered client redirects to. */
+export const GROK_CALLBACK_PORT = 56121;
+/** Path the client redirects to. */
+export const GROK_CALLBACK_PATH = '/callback';
+/** API base; `<base>/responses` streams and `<base>/models` lists. */
+export const GROK_API_BASE = 'https://api.x.ai/v1';
+/** Optional CLI catalog that discloses per-model context and reasoning levels. */
+export const GROK_CLI_MODELS_URL = 'https://cli-chat-proxy.grok.com/v1/models';
+/** Context window assumed when neither the CLI catalog nor a seed states one. */
+export const GROK_CONTEXT_WINDOW = 256_000;
+/** Default per-request output cap. */
+export const GROK_DEFAULT_MAX_TOKENS = 32_000;
+/** Refresh when the access token has less than this much life left. */
+export const GROK_PREEMPT_MS = 2 * 60 * 1000;
+/** Hosts an authorization server endpoint may live on. */
+const TRUSTED_AUTH_HOSTS = new Set(['auth.x.ai', 'accounts.x.ai']);
+/** Display metadata for the reasoning ladder xAI documents. */
+const EFFORT_LABELS = {
+    none: { name: 'Off', description: 'Answer without spending thinking tokens' },
+    low: { name: 'Low', description: 'Short chain of thought' },
+    medium: { name: 'Medium', description: 'Balanced thinking budget' },
+    high: { name: 'High', description: 'Deep chain of thought' },
+};
+/**
+ * Curated catalog entries.
+ *
+ * Seeds only what the provider's own documentation names; everything else the
+ * account is entitled to arrives through live discovery, so a new model does not
+ * need a plugin release.
+ */
+export const GROK_MODELS = [
+    {
+        id: 'grok-4.6',
+        name: 'Grok 4.6',
+        description: 'Current flagship, reasoning levels from the live catalog',
+        contextWindow: GROK_CONTEXT_WINDOW,
+        inputModalities: ['text', 'image'],
+    },
+    {
+        id: 'grok-4.5',
+        name: 'Grok 4.5',
+        description: 'Previous flagship',
+        contextWindow: GROK_CONTEXT_WINDOW,
+        inputModalities: ['text', 'image'],
+    },
+];
+/**
+ * Coerce one decoded credential entry into a Grok session.
+ * @param value - decoded JSON value for one account.
+ * @returns the session, or undefined when required fields are missing.
+ */
+export function parseGrokSession(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const accessToken = nonEmpty(record.accessToken);
+    const tokenEndpoint = nonEmpty(record.tokenEndpoint);
+    const expiresAt = finiteInstant(record.expiresAt);
+    if (accessToken === undefined || tokenEndpoint === undefined || expiresAt === undefined)
+        return undefined;
+    const refreshToken = nonEmpty(record.refreshToken);
+    const issuer = nonEmpty(record.issuer);
+    const scopes = nonEmpty(record.scopes);
+    const accountId = nonEmpty(record.accountId);
+    const email = nonEmpty(record.email);
+    return {
+        accessToken,
+        expiresAt,
+        tokenEndpoint,
+        issuer: issuer ?? GROK_ISSUER,
+        ...refreshToken === undefined ? {} : { refreshToken },
+        ...scopes === undefined ? {} : { scopes },
+        ...accountId === undefined ? {} : { accountId },
+        ...email === undefined ? {} : { email },
+    };
+}
+/** One `reasoning.efforts` entry. */
+function effortInfo(effort) {
+    const label = EFFORT_LABELS[effort] ?? { name: effort, description: '' };
+    return { id: ReasoningEffortId(effort), name: label.name, description: label.description };
+}
+/** The reasoning block for a catalog entry, or undefined when it supports none. */
+function reasoningInfo(entry) {
+    const efforts = entry.reasoningEfforts;
+    if (efforts === undefined || efforts.length === 0)
+        return undefined;
+    return {
+        efforts: efforts.map(effortInfo),
+        ...entry.defaultEffort === undefined ? {} : { defaultEffort: ReasoningEffortId(entry.defaultEffort) },
+    };
+}
+/** Reject an endpoint that is not an xAI HTTPS URL. */
+function assertTrustedEndpoint(raw, field) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`xAI discovery returned an unparseable ${field}`);
+    }
+    if (url.protocol !== 'https:' || url.username !== '' || url.password !== '' || url.port !== ''
+        || !TRUSTED_AUTH_HOSTS.has(url.hostname.toLowerCase())) {
+        throw new Error(`xAI discovery returned an untrusted ${field} (${url.hostname})`);
+    }
+    return url.toString();
+}
+/** Read one JWT payload, or undefined for an opaque token. */
+function decodeJwt(token) {
+    if (token === undefined)
+        return undefined;
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Account identity from the id token, falling back to the access token. */
+export function identityFromGrokTokens(accessToken, idToken) {
+    const payload = decodeJwt(idToken) ?? decodeJwt(accessToken);
+    const accountId = nonEmpty(payload?.sub);
+    const email = nonEmpty(payload?.email)?.toLowerCase();
+    return {
+        ...accountId === undefined ? {} : { accountId },
+        ...email === undefined ? {} : { email },
+    };
+}
+/** Turn a token-endpoint payload into tokens with an absolute expiry. */
+export function parseGrokTokenPayload(payload, previousRefreshToken) {
+    const record = (payload ?? {});
+    const accessToken = nonEmpty(record.access_token);
+    const lifetime = record.expires_in;
+    const lifetimeOk = typeof lifetime === 'number' && Number.isFinite(lifetime) && lifetime >= 0;
+    if (accessToken === undefined || !lifetimeOk) {
+        throw new Error('xAI token response missing required fields');
+    }
+    const expiresAt = Date.now() + lifetime * 1000;
+    if (!Number.isFinite(expiresAt))
+        throw new Error('xAI token response missing required fields');
+    const refreshToken = nonEmpty(record.refresh_token) ?? previousRefreshToken;
+    const idToken = nonEmpty(record.id_token);
+    return {
+        accessToken,
+        expiresAt,
+        ...refreshToken === undefined ? {} : { refreshToken },
+        ...idToken === undefined ? {} : { idToken },
+    };
+}
+/** OIDC discovery, cached for the process. */
+export function createGrokDiscovery(fetchFn, onWarn) {
+    let cached;
+    return async function discover() {
+        if (cached !== undefined)
+            return cached;
+        const response = await fetchFn(GROK_DISCOVERY_URL, { headers: { accept: 'application/json' } });
+        if (!response.ok) {
+            throw new Error(`xAI OIDC discovery failed (HTTP ${response.status})`);
+        }
+        const payload = await response.json();
+        if (typeof payload.authorization_endpoint !== 'string' || typeof payload.token_endpoint !== 'string') {
+            throw new Error('xAI OIDC discovery response is missing authorization/token endpoints');
+        }
+        const endpoints = {
+            authorizationEndpoint: assertTrustedEndpoint(payload.authorization_endpoint, 'authorization_endpoint'),
+            tokenEndpoint: assertTrustedEndpoint(payload.token_endpoint, 'token_endpoint'),
+        };
+        onWarn?.(`xAI endpoints discovered (${new URL(endpoints.tokenEndpoint).host})`);
+        cached = endpoints;
+        return endpoints;
+    };
+}
+/** Exchange an authorization code for tokens. */
+export async function exchangeGrokCode(input) {
+    const response = await input.fetchFn(input.tokenEndpoint, {
+        method: 'POST',
+        headers: { ...attributedHeaders(), 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: GROK_CLIENT_ID,
+            code: input.code,
+            redirect_uri: input.redirectUri,
+            code_verifier: input.pkce.verifier,
+            code_challenge: input.pkce.challenge,
+            code_challenge_method: 'S256',
+        }).toString(),
+        signal: input.signal,
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok) {
+        const detail = (payload ?? {});
+        const described = nonEmpty(detail.error_description) ?? nonEmpty(detail.error);
+        throw new Error(`xAI token exchange failed (HTTP ${response.status})${described === undefined ? '' : `: ${described}`}`);
+    }
+    return parseGrokTokenPayload(payload);
+}
+/** Redeem a refresh token. */
+export async function refreshGrokToken(input) {
+    const response = await input.fetchFn(input.tokenEndpoint, {
+        method: 'POST',
+        headers: { ...attributedHeaders(), 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams({
+            grant_type: 'refresh_token',
+            client_id: GROK_CLIENT_ID,
+            refresh_token: input.refreshToken,
+        }).toString(),
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok) {
+        const detail = (payload ?? {});
+        const described = nonEmpty(detail.error_description) ?? nonEmpty(detail.error);
+        throw new ProviderError(`xAI token refresh failed (HTTP ${response.status})${described === undefined ? '' : `: ${described}`}`, REAUTH_REQUIRED);
+    }
+    return parseGrokTokenPayload(payload, input.refreshToken);
+}
+/** Model ids that are clearly not chat models. */
+const NON_CHAT_ID = /(?:^|[-_/])(?:image|video|imagine|embed|embedding|whisper|tts|vision-only)/i;
+/** Grok wire adapter: one instance serves the `grok` provider route. */
+export class GrokAdapter extends LlmAdapter {
+    options;
+    /** Live model ids seen this session. */
+    discovered;
+    /** Capability metadata from the CLI catalog, keyed by model id. */
+    metadata = new Map();
+    /** Ids the user added by hand, cached so the sync catalog can name them. */
+    userAddedIds = [];
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    providerInfo(provider) {
+        return { id: provider, name: GROK_PROVIDER_NAME };
+    }
+    providerRetryPolicy() {
+        // xAI reports its own pacing through 429 `retry-after`.
+        return undefined;
+    }
+    async listModels(_provider) {
+        // Nothing to offer without a signed-in account: a model that cannot be called
+        // must not appear in the picker, and Auto must not try it.
+        if (await this.options.tokens.session() === undefined)
+            return [];
+        await this.syncUserModels();
+        const hidden = await this.hidden();
+        return resolveCatalog(this.catalog(), [], hidden).entries.map((entry) => ({
+            provider: GROK_PROVIDER_ID,
+            id: entry.id,
+            name: entry.name,
+            ...entry.description === undefined ? {} : { description: entry.description },
+            ...entry.inputModalities === undefined ? {} : { inputModalities: entry.inputModalities },
+        }));
+    }
+    async hidden() {
+        if (this.options.hiddenModels === undefined)
+            return new Set();
+        try {
+            return await this.options.hiddenModels();
+        }
+        catch (error) {
+            this.options.onWarn?.(`model preferences unavailable (${errorChain(error)})`);
+            return new Set();
+        }
+    }
+    async resolveModel(_provider, model) {
+        await this.syncUserModels();
+        const entry = findEntry(this.catalog(), model);
+        if (entry === undefined) {
+            const template = findEntry(GROK_MODELS, 'grok-4.6');
+            const reasoning = template === undefined ? undefined : reasoningInfo(template);
+            return {
+                provider: GROK_PROVIDER_ID,
+                id: model,
+                name: model,
+                context: { contextWindow: GROK_CONTEXT_WINDOW },
+                defaultMaxTokens: GROK_DEFAULT_MAX_TOKENS,
+                ...reasoning === undefined ? {} : { reasoning },
+            };
+        }
+        const reasoning = reasoningInfo(entry);
+        return {
+            provider: GROK_PROVIDER_ID,
+            id: entry.id,
+            name: entry.name,
+            ...entry.description === undefined ? {} : { description: entry.description },
+            ...entry.inputModalities === undefined ? {} : { inputModalities: entry.inputModalities },
+            context: { contextWindow: entry.contextWindow },
+            defaultMaxTokens: GROK_DEFAULT_MAX_TOKENS,
+            ...reasoning === undefined ? {} : { reasoning },
+        };
+    }
+    stream(options) {
+        return streamProviderResponses(options, {
+            label: 'xAI API',
+            tokens: this.options.tokens,
+            request: (call, model, accessToken, signal) => this.request(call, model, accessToken, signal),
+            streamIdleTimeoutMs: this.options.streamIdleTimeoutMs,
+            ...this.options.onCredentialRejected === undefined
+                ? {}
+                : { onCredentialRejected: this.options.onCredentialRejected },
+            onFallback: (from, to, reason) => {
+                this.options.onWarn?.(`grok: model ${from} unavailable (${reason}); falling back to ${to}`);
+            },
+            describeFailure: (error) => (error instanceof ProviderError && error.code === REAUTH_REQUIRED
+                ? new LlmError(`Grok (X Premium) login expired; sign in again from Settings → Subscriptions (${GROK_CODE_URL})`, 'INVALID_CREDENTIAL', { status: 401 })
+                : error),
+        });
+    }
+    /**
+     * The catalog the route serves: its own entries, then the ids the user added
+     * by hand. The two are built separately so the hand-added check can look at
+     * the shipped list without recursing.
+     */
+    catalog() {
+        return [...this.shippedCatalog(), ...this.addedEntries()];
+    }
+    /**
+     * The catalog to present: curated seeds with their shipped metadata, then any
+     * live id this build does not know, enriched from the CLI catalog when it
+     * disclosed that model's context window or reasoning ladder.
+     */
+    shippedCatalog() {
+        const extra = [];
+        const seen = new Set();
+        for (const id of this.discovered ?? []) {
+            if (findEntry(GROK_MODELS, id) !== undefined || seen.has(id))
+                continue;
+            seen.add(id);
+            const meta = this.metadata.get(id);
+            extra.push({
+                id,
+                name: id,
+                description: 'Reported by the xAI model list',
+                contextWindow: meta?.contextWindow ?? GROK_CONTEXT_WINDOW,
+                inputModalities: ['text', 'image'],
+                // A ladder is advertised only when the provider's own catalog gave one.
+                ...meta?.reasoningEfforts === undefined ? {} : { reasoningEfforts: meta.reasoningEfforts },
+                ...meta?.defaultEffort === undefined ? {} : { defaultEffort: meta.defaultEffort },
+            });
+        }
+        // The seeds also pick up live metadata (context window, reasoning ladder).
+        const seeded = GROK_MODELS.map((entry) => {
+            const meta = this.metadata.get(entry.id);
+            if (meta === undefined)
+                return entry;
+            return {
+                ...entry,
+                contextWindow: meta.contextWindow ?? entry.contextWindow,
+                ...meta.reasoningEfforts === undefined ? {} : { reasoningEfforts: meta.reasoningEfforts },
+                ...meta.defaultEffort === undefined ? {} : { defaultEffort: meta.defaultEffort },
+            };
+        });
+        return [...seeded, ...extra];
+    }
+    /** Re-read the ids the user added by hand. */
+    async syncUserModels() {
+        if (this.options.userModels === undefined)
+            return;
+        try {
+            this.userAddedIds = await this.options.userModels();
+        }
+        catch (error) {
+            this.options.onWarn?.(`user-added models unavailable (${errorChain(error)})`);
+            this.userAddedIds = [];
+        }
+    }
+    /**
+     * The entries for ids the user added by hand.
+     *
+     * Published without shipped metadata: this build has never seen the model, so
+     * the endpoint's own defaults are the honest description.
+     */
+    addedEntries() {
+        if (this.userAddedIds.length === 0)
+            return [];
+        const known = new Set(this.shippedCatalog().map((entry) => entry.id));
+        return this.userAddedIds
+            .filter((id) => !known.has(id))
+            .map((id) => fallbackEntry(id, 'Added by hand in Settings', GROK_CONTEXT_WINDOW));
+    }
+    /** Record the live catalog for the picker. */
+    discover(ids, metadata) {
+        this.discovered = ids;
+        if (metadata === undefined)
+            return;
+        for (const [id, meta] of metadata)
+            this.metadata.set(id, meta);
+    }
+    /** The curated catalog, for the Settings page's model list. */
+    catalogEntries() {
+        return this.catalog();
+    }
+    /** What this route itself serves, without the ids added by hand. */
+    ownCatalogEntries() {
+        return this.shippedCatalog();
+    }
+    /** Build and send one request for one model. */
+    async request(options, model, accessToken, signal) {
+        const resolved = await toResponsesInput(options.messages, options.system, this.imageResolver(signal));
+        const body = {
+            model,
+            ...resolved.instructions === undefined ? {} : { instructions: resolved.instructions },
+            input: resolved.input,
+            ...options.tools === undefined || options.tools.length === 0
+                ? {}
+                : { tools: toResponsesTools(options.tools), tool_choice: 'auto', parallel_tool_calls: true },
+            ...options.maxTokens === undefined ? {} : { max_output_tokens: options.maxTokens },
+            ...options.reasoningEffort === undefined
+                ? {}
+                : { reasoning: { effort: String(options.reasoningEffort) } },
+            // Cache-affinity hint: xAI routes a repeated request back to the shard
+            // holding its prompt cache only when the same key returns.
+            ...options.sessionId === undefined ? {} : { prompt_cache_key: String(options.sessionId) },
+            store: false,
+            stream: true,
+        };
+        const fetchFn = this.options.fetchFn ?? proxiedFetch;
+        return fetchFn(`${this.options.apiBase}/responses`, {
+            method: 'POST',
+            headers: attributedHeaders({
+                'authorization': `Bearer ${accessToken}`,
+                'accept': 'text/event-stream',
+                'content-type': 'application/json',
+            }),
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+    /** Resolve image blocks through the attachment service, when it is present. */
+    imageResolver(signal) {
+        const store = this.options.resolveAttachments?.();
+        if (store === undefined || store === null)
+            return undefined;
+        return async (ref) => {
+            try {
+                const stored = await store.readImage(ref, signal);
+                return { mediaType: ref.mediaType, base64: Buffer.from(stored.data).toString('base64') };
+            }
+            catch (error) {
+                this.options.onWarn?.(`image attachment unavailable (${errorChain(error)})`);
+                return undefined;
+            }
+        };
+    }
+    /**
+     * Read the live model list, and the CLI catalog's capability metadata.
+     * @param accessToken - bearer for the account's models.
+     * @returns the model ids, or undefined when discovery is off or unavailable.
+     */
+    async fetchCatalog(accessToken, signal) {
+        if (!this.options.discovery)
+            return undefined;
+        const fetchFn = this.options.fetchFn ?? proxiedFetch;
+        try {
+            const response = await fetchFn(`${this.options.apiBase}/models`, {
+                headers: attributedHeaders({ 'authorization': `Bearer ${accessToken}` }),
+                ...signal === undefined ? {} : { signal },
+            });
+            if (!response.ok) {
+                // A refused credential is reported by the card's account list; only a
+                // genuine discovery failure is worth a warning.
+                if (response.status !== 401 && response.status !== 403) {
+                    this.options.onWarn?.(`xAI model discovery failed (HTTP ${response.status}); using the built-in catalog`);
+                }
+                return undefined;
+            }
+            const payload = await response.json();
+            const ids = (payload.data ?? [])
+                .map((entry) => entry.id)
+                .filter((id) => typeof id === 'string' && id.length > 0 && !NON_CHAT_ID.test(id));
+            if (ids.length === 0) {
+                this.options.onWarn?.('xAI model discovery returned an empty catalog; using the built-in catalog');
+                return undefined;
+            }
+            const metadata = await this.fetchCliMetadata(fetchFn, signal);
+            for (const [id, meta] of metadata)
+                this.metadata.set(id, meta);
+            return ids;
+        }
+        catch (error) {
+            if (signal?.aborted === true)
+                return undefined;
+            this.options.onWarn?.(`xAI model discovery failed; using the built-in catalog (${errorChain(error)})`);
+            return undefined;
+        }
+    }
+    /** Read per-model capabilities from the CLI catalog; failures are silent. */
+    async fetchCliMetadata(fetchFn, signal) {
+        const result = new Map();
+        try {
+            const response = await fetchFn(GROK_CLI_MODELS_URL, {
+                headers: attributedHeaders({ 'authorization': 'Bearer anonymous' }),
+                ...signal === undefined ? {} : { signal },
+            });
+            if (!response.ok)
+                return result;
+            const payload = await response.json();
+            for (const entry of payload.data ?? []) {
+                const id = typeof entry.id === 'string' && entry.id.length > 0 ? entry.id : undefined;
+                if (id === undefined)
+                    continue;
+                const contextWindow = typeof entry.context_window === 'number' && Number.isFinite(entry.context_window)
+                    ? entry.context_window
+                    : undefined;
+                const supportsEffort = entry.supports_reasoning_effort === true;
+                const efforts = supportsEffort
+                    ? (entry.reasoning_efforts ?? [])
+                        .map((effort) => effort.value)
+                        .filter((value) => typeof value === 'string' && value.length > 0)
+                    : [];
+                const defaultEffort = supportsEffort && typeof entry.reasoning_effort === 'string'
+                    && efforts.includes(entry.reasoning_effort)
+                    ? entry.reasoning_effort
+                    : undefined;
+                result.set(id, {
+                    ...contextWindow === undefined ? {} : { contextWindow },
+                    ...efforts.length === 0 ? {} : { reasoningEfforts: efforts },
+                    ...defaultEffort === undefined ? {} : { defaultEffort },
+                });
+            }
+        }
+        catch {
+            // Capability metadata is a bonus; the id list is what matters.
+        }
+        return result;
+    }
+}
+/**
+ * Build the `grok` route: its adapter and its login/lifecycle controller.
+ *
+ * @param options - resolved paths and shared services.
+ * @returns the route, ready to register and to serve over RPC.
+ */
+export function createGrokProvider(options) {
+    const fetchFn = options.fetchFn ?? proxiedFetch;
+    const apiBase = options.apiBase ?? GROK_API_BASE;
+    const store = new TokenStore(options.credentialFile, GROK_PROVIDER_ID, parseGrokSession);
+    const discoverEndpoints = createGrokDiscovery(fetchFn, options.onWarn);
+    /** Endpoints resolved by `prepare`, read synchronously while building URLs. */
+    let endpointsSnapshot;
+    const flow = new LoopbackFlow(GROK_PROVIDER_ID, {
+        ports: [GROK_CALLBACK_PORT],
+        callbackPath: GROK_CALLBACK_PATH,
+        prepare: async () => { endpointsSnapshot = await discoverEndpoints(); },
+        buildAuthorizeUrl: ({ redirectUri, state, pkce }) => {
+            // `prepare` has already resolved and cached the endpoints.
+            const endpoints = endpointsSnapshot;
+            if (endpoints === undefined)
+                throw new Error('xAI endpoints were not discovered');
+            const url = new URL(endpoints.authorizationEndpoint);
+            url.searchParams.set('response_type', 'code');
+            url.searchParams.set('client_id', GROK_CLIENT_ID);
+            url.searchParams.set('redirect_uri', redirectUri);
+            url.searchParams.set('scope', GROK_SCOPE);
+            url.searchParams.set('state', state);
+            url.searchParams.set('code_challenge', pkce.challenge);
+            url.searchParams.set('code_challenge_method', 'S256');
+            return url.toString();
+        },
+        exchange: async ({ code, redirectUri, pkce, signal }) => {
+            const endpoints = endpointsSnapshot ?? await discoverEndpoints();
+            const tokens = await exchangeGrokCode({
+                fetchFn,
+                tokenEndpoint: endpoints.tokenEndpoint,
+                code,
+                redirectUri,
+                pkce,
+                signal,
+            });
+            return {
+                accessToken: tokens.accessToken,
+                ...tokens.refreshToken === undefined ? {} : { refreshToken: tokens.refreshToken },
+                expiresAt: tokens.expiresAt,
+                tokenEndpoint: endpoints.tokenEndpoint,
+                issuer: GROK_ISSUER,
+                scopes: GROK_SCOPE,
+                ...identityFromGrokTokens(tokens.accessToken, tokens.idToken),
+            };
+        },
+    });
+    const tokens = new TokenManager({
+        store,
+        displayName: GROK_PROVIDER_NAME,
+        preemptMs: GROK_PREEMPT_MS,
+        refresh: async (session) => {
+            const refreshToken = session.refreshToken;
+            if (refreshToken === undefined) {
+                throw new ProviderError(`${GROK_PROVIDER_NAME} account has no refresh token; sign in again`, REAUTH_REQUIRED);
+            }
+            const refreshed = await refreshGrokToken({
+                fetchFn,
+                tokenEndpoint: session.tokenEndpoint,
+                refreshToken,
+            });
+            return {
+                accessToken: refreshed.accessToken,
+                expiresAt: refreshed.expiresAt,
+                ...refreshed.refreshToken === undefined ? {} : { refreshToken: refreshed.refreshToken },
+            };
+        },
+    });
+    const adapter = new GrokAdapter({
+        apiBase,
+        discovery: options.discovery,
+        streamIdleTimeoutMs: options.streamIdleTimeoutMs,
+        tokens,
+        ...options.onWarn === undefined ? {} : { onWarn: options.onWarn },
+        ...options.resolveAttachments === undefined ? {} : { resolveAttachments: options.resolveAttachments },
+        hiddenModels: () => options.preferences.hiddenIds(GROK_PROVIDER_ID),
+        userModels: () => options.preferences.extraIds(GROK_PROVIDER_ID),
+        modelOrder: () => options.preferences.orderOf(GROK_PROVIDER_ID),
+        ...options.discoveryFetchFn === undefined ? {} : { fetchFn: options.discoveryFetchFn },
+    });
+    const spec = {
+        id: GROK_PROVIDER_ID,
+        displayName: GROK_PROVIDER_NAME,
+        codeUrl: GROK_CODE_URL,
+        credentialFile: options.credentialFile,
+        discovery: options.discovery,
+        defaultModel: 'grok-4.6',
+        catalog: () => adapter.catalogEntries(),
+        catalogOwn: () => adapter.ownCatalogEntries(),
+        fallbackContextWindow: GROK_CONTEXT_WINDOW,
+        discover: (accessToken) => adapter.fetchCatalog(accessToken),
+        usage: (accessToken) => readGrokUsage({ accessToken, fetchFn: options.discoveryFetchFn ?? fetchFn }),
+        details: () => [
+            { key: 'oauthHost', value: GROK_ISSUER },
+            { key: 'apiBase', value: apiBase },
+            { key: 'credentialFile', value: options.credentialFile },
+        ],
+        applyDiscovery: (ids) => { adapter.discover(ids); },
+    };
+    const controller = new ProviderController({
+        spec,
+        store,
+        tokens,
+        flow,
+        preferences: options.preferences,
+        ...options.onCatalogChanged === undefined ? {} : { onCatalogChanged: options.onCatalogChanged },
+        ...options.onWarn === undefined ? {} : { onWarn: options.onWarn },
+    });
+    return {
+        id: controller.id,
+        displayName: controller.displayName,
+        credentialFile: controller.credentialFile,
+        adapter,
+        status: () => controller.status(),
+        login: (account) => controller.login(account),
+        cancel: () => controller.cancel(),
+        logout: (account) => controller.logout(account),
+        setDefault: (account) => controller.setDefault(account),
+        refresh: (account) => controller.refresh(account),
+        discover: (force) => controller.discover(force),
+        setModelVisible: (id, visible) => controller.setModelVisible(id, visible),
+        setModelOrder: (ids) => controller.setModelOrder(ids),
+        addModel: (id) => controller.addModel(id),
+        removeModel: (id) => controller.removeModel(id),
+        usage: (force) => controller.usage(force),
+        reload: () => controller.reload(),
+    };
+}