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

package/lib/providers/glm.js

@@ -0,0 +1,445 @@
+/**
+ * The `glm` route: BigModel's coding plan over the OpenAI Responses wire.
+ *
+ * Sign-in is ZCode's own OAuth flow (see `auth/glm-flow.ts`). What the flow hands
+ * back is a BigModel access token and the ZCode JWT the subscription is bound to;
+ * requests and the model list then go to the coding-plan host, whose
+ * `/responses` route answers the same wire the `kimi` and `grok` routes use.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/glm
+ */
+import { LlmAdapter, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import { REAUTH_REQUIRED, ProviderError } from '../errors.js';
+import { finiteInstant, nonEmpty } from '../auth/store.js';
+import { proxiedFetch } from '../http.js';
+import { findEntry, resolveCatalog } from './catalog.js';
+import { streamProviderResponses } from './responses-stream.js';
+import { toResponsesInput, toResponsesTools } from '../translate/responses.js';
+/** Provider route this module serves. */
+export const GLM_PROVIDER_ID = 'glm';
+/** Display name for the picker group and the Settings card. */
+export const GLM_PROVIDER_NAME = 'GLM (BigModel)';
+/** Page a user opens to manage the coding plan. */
+export const GLM_CODE_URL = 'https://bigmodel.cn/coding-plan/personal/overview';
+/** Coding-plan host; the Responses endpoint is `<base>/responses`. */
+export const GLM_API_BASE = 'https://open.bigmodel.cn/api/coding/paas/v4';
+/** Origin the account-level endpoints hang off, without the coding path. */
+export const GLM_ORIGIN = 'https://open.bigmodel.cn';
+/** Path appended to the API base for a streaming request. */
+export const GLM_RESPONSES_PATH = '/responses';
+/** Path appended to the API base to list the models an account can reach. */
+export const GLM_MODELS_PATH = '/models';
+/**
+ * Account allowance endpoint.
+ *
+ * It sits on the host root rather than under the coding prefix, and BigModel
+ * authenticates it with the bare key — no `Bearer` scheme, which the host refuses.
+ */
+export const GLM_QUOTA_PATH = '/api/monitor/usage/quota/limit';
+/** Model the picker preselects. */
+export const GLM_DEFAULT_MODEL = 'glm-5.3';
+/** Context capacity of the GLM 5.x family. */
+export const GLM_CONTEXT_WINDOW = 1_048_576;
+/** Output budget used when the caller sets no cap. */
+export const GLM_DEFAULT_MAX_TOKENS = 131_072;
+/** Reasoning ladder the GLM 5.3 family accepts. */
+const GLM_53_EFFORTS = ['low', 'high', 'max'];
+/**
+ * The catalog this build ships, so a signed-in route is usable with no discovery.
+ *
+ * Ids are the wire ids, lowercase: the coding plan answers `glm-5.3`, not the
+ * `GLM-5.3` display name its own client shows. `glm-5.3-flash` is the multimodal
+ * member of the family; the rest read text only.
+ */
+export const GLM_MODELS = [
+    {
+        id: 'glm-5.3',
+        name: 'GLM-5.3',
+        description: 'Coding plan flagship, text only',
+        contextWindow: GLM_CONTEXT_WINDOW,
+        inputModalities: ['text'],
+        reasoningEfforts: [...GLM_53_EFFORTS],
+    },
+    {
+        id: 'glm-5.3-flash',
+        name: 'GLM-5.3 Flash',
+        description: 'Fast, reads images',
+        contextWindow: GLM_CONTEXT_WINDOW,
+        inputModalities: ['text', 'image'],
+        reasoningEfforts: [...GLM_53_EFFORTS],
+    },
+    {
+        id: 'glm-5.2',
+        name: 'GLM-5.2',
+        description: 'Previous flagship',
+        contextWindow: GLM_CONTEXT_WINDOW,
+        inputModalities: ['text'],
+    },
+    {
+        id: 'glm-5.1',
+        name: 'GLM-5.1',
+        description: 'Earlier 5.x release',
+        contextWindow: GLM_CONTEXT_WINDOW,
+        inputModalities: ['text'],
+    },
+    {
+        id: 'glm-5',
+        name: 'GLM-5',
+        description: 'First 5.x release',
+        contextWindow: GLM_CONTEXT_WINDOW,
+        inputModalities: ['text'],
+    },
+];
+/**
+ * Coerce one decoded credential entry into a GLM session.
+ *
+ * @param value - decoded JSON value for one account.
+ * @returns the session, or undefined when required fields are missing.
+ */
+export function parseGlmSession(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const accessToken = nonEmpty(record.accessToken);
+    const zcodeJwt = nonEmpty(record.zcodeJwt);
+    const expiresAt = finiteInstant(record.expiresAt);
+    if (accessToken === undefined || zcodeJwt === undefined || expiresAt === undefined)
+        return undefined;
+    const refreshToken = nonEmpty(record.refreshToken);
+    const apiBase = nonEmpty(record.apiBase);
+    const accountId = nonEmpty(record.accountId);
+    const email = nonEmpty(record.email);
+    return {
+        accessToken,
+        zcodeJwt,
+        expiresAt,
+        ...refreshToken === undefined ? {} : { refreshToken },
+        ...apiBase === undefined ? {} : { apiBase },
+        ...accountId === undefined ? {} : { accountId },
+        ...email === undefined ? {} : { email },
+    };
+}
+/** A finite number from a wire field, or undefined. */
+function finiteNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+/** A reset instant from an RFC 3339 string or epoch milliseconds. */
+function resetInstant(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'string' || value.trim() === '')
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Read the two windows a coding-plan allowance reports.
+ *
+ * The host lists one row per metered window and names it by a `unit`/`number`
+ * pair: `(3, 5)` is the rolling five-hour window and `(6, 1)` the weekly one.
+ * Rows of any other type — MCP tool usage, for instance — are not model quota and
+ * are skipped rather than shown as an allowance.
+ *
+ * @param payload - the decoded `quota/limit` body.
+ * @returns one window per metered allowance, rolling first.
+ */
+export function parseGlmQuota(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return [];
+    const body = payload;
+    const data = typeof body.data === 'object' && body.data !== null ? body.data : body;
+    const limits = Array.isArray(data.limits) ? data.limits : [];
+    const found = new Map();
+    for (const row of limits) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const type = typeof row.type === 'string' ? row.type : '';
+        if (type !== 'TOKENS_LIMIT' && type !== 'CREDIT_LIMIT')
+            continue;
+        let usedPercent = finiteNumber(row.percentage);
+        if (usedPercent === undefined) {
+            const used = finiteNumber(row.currentValue);
+            const total = finiteNumber(row.usage);
+            if (used !== undefined && total !== undefined && total > 0)
+                usedPercent = (used / total) * 100;
+        }
+        if (usedPercent === undefined)
+            continue;
+        const unit = finiteNumber(row.unit);
+        const number = finiteNumber(row.number);
+        const label = unit === 3 && number === 5 ? '5h' : unit === 6 && number === 1 ? 'weekly' : undefined;
+        if (label === undefined || found.has(label))
+            continue;
+        const resetsAt = resetInstant(row.nextResetTime);
+        found.set(label, {
+            label,
+            usedPercent: Math.max(0, Math.min(100, usedPercent)),
+            ...resetsAt === undefined ? {} : { resetsAt },
+        });
+    }
+    return ['5h', 'weekly'].flatMap((label) => {
+        const window = found.get(label);
+        return window === undefined ? [] : [window];
+    });
+}
+/**
+ * Read an account's coding-plan allowance.
+ *
+ * @param input - host, bearer, and fetch.
+ * @returns the windows the host reported; an empty list when it stated none.
+ */
+export async function readGlmUsage(input) {
+    const response = await input.fetchFn(`${input.origin}${GLM_QUOTA_PATH}`, {
+        headers: {
+            // BigModel wants the key itself here, not a Bearer scheme.
+            authorization: input.accessToken,
+            accept: 'application/json',
+        },
+        ...input.signal === undefined ? {} : { signal: input.signal },
+    });
+    if (!response.ok)
+        throw await httpFailure(response, 'GLM allowance');
+    return { windows: parseGlmQuota(await response.json()) };
+}
+/** Map a refused allowance request onto a harness error. */
+async function httpFailure(response, label) {
+    const text = await response.text().catch(() => '');
+    const detail = text.trim() === '' ? undefined : text.slice(0, 200);
+    return new LlmError(detail === undefined
+        ? `${label} request failed (HTTP ${response.status})`
+        : `${label} request failed (HTTP ${response.status}): ${detail}`, response.status === 401 || response.status === 403 ? 'INVALID_CREDENTIAL' : 'PROVIDER_ERROR', { status: response.status });
+}
+/** The adapter behind the `glm` route. */
+export class GlmAdapter extends LlmAdapter {
+    options;
+    /** Live catalog ids, once discovery succeeded this session. */
+    live;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    providerInfo(provider) {
+        return { id: provider, name: GLM_PROVIDER_NAME };
+    }
+    providerRetryPolicy() {
+        // The coding host states its own pacing through 429; a local ladder would
+        // fight the account-level limiter.
+        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 [];
+        const hidden = await this.hidden();
+        return resolveCatalog(this.catalog(), [], hidden).entries.map((entry) => ({
+            provider: GLM_PROVIDER_ID,
+            id: entry.id,
+            name: entry.name,
+            ...entry.description === undefined ? {} : { description: entry.description },
+            ...entry.inputModalities === undefined ? {} : { inputModalities: entry.inputModalities },
+        }));
+    }
+    async resolveModel(_provider, model) {
+        const entry = findEntry(this.catalog(), model);
+        if (entry === undefined) {
+            // An id this build has never heard of is still dispatchable: the endpoint is
+            // the authority on what it serves, and a newer model should not be refused.
+            const template = findEntry(this.catalog(), GLM_DEFAULT_MODEL) ?? this.catalog()[0];
+            return {
+                provider: GLM_PROVIDER_ID,
+                id: model,
+                name: model,
+                context: { contextWindow: template?.contextWindow ?? GLM_CONTEXT_WINDOW },
+                defaultMaxTokens: GLM_DEFAULT_MAX_TOKENS,
+            };
+        }
+        const reasoning = reasoningInfo(entry);
+        return {
+            provider: GLM_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: GLM_DEFAULT_MAX_TOKENS,
+            ...reasoning === undefined ? {} : { reasoning },
+        };
+    }
+    stream(options) {
+        return streamProviderResponses(options, {
+            label: 'GLM 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?.(`glm: model ${from} unavailable (${reason}); falling back to ${to}`);
+            },
+            describeFailure: (error) => this.refreshHint(error),
+        });
+    }
+    /** Translate an auth failure into the message a user can act on. */
+    refreshHint(error) {
+        if (error instanceof ProviderError && error.code === REAUTH_REQUIRED) {
+            return new LlmError(`GLM sign-in expired; sign in again from Settings → Subscriptions (${GLM_CODE_URL})`, 'INVALID_CREDENTIAL', { status: 401 });
+        }
+        return error;
+    }
+    /** The catalog served: the shipped list, the live one, then hand-added ids. */
+    catalog() {
+        return [...this.shippedCatalog(), ...this.addedEntries()];
+    }
+    /** The route's own catalog, without ids the user added by hand. */
+    shippedCatalog() {
+        const shipped = this.options.extraModels === undefined
+            ? [...GLM_MODELS]
+            : [...GLM_MODELS, ...this.options.extraModels.map((id) => extraEntry(id))];
+        const live = this.live;
+        if (live === undefined)
+            return shipped;
+        const merged = [...shipped];
+        for (const id of live) {
+            if (findEntry(merged, id) === undefined)
+                merged.push(extraEntry(id));
+        }
+        return merged;
+    }
+    /** Ids the user published by hand that this route does not already serve. */
+    addedEntries() {
+        const own = this.shippedCatalog();
+        const added = this.options.userModels?.();
+        if (added === undefined)
+            return [];
+        return (Array.isArray(added) ? added : [])
+            .filter((id) => findEntry(own, id) === undefined)
+            .map((id) => extraEntry(id));
+    }
+    /** The ids the picker must currently omit. */
+    async hidden() {
+        if (this.options.hiddenModels === undefined)
+            return new Set();
+        try {
+            return await this.options.hiddenModels();
+        }
+        catch {
+            // A preferences read failure must not empty the picker.
+            return new Set();
+        }
+    }
+    /**
+     * Adopt the endpoint's live catalog.
+     *
+     * @param ids - model ids the endpoint reported.
+     */
+    discover(ids) {
+        this.live = [...ids];
+    }
+    /**
+     * Read the live model list.
+     *
+     * @param accessToken - bearer for the account.
+     * @param signal - optional cancellation.
+     * @returns the ids the endpoint serves, or undefined when it cannot be read.
+     */
+    async fetchCatalog(accessToken, signal) {
+        if (!this.options.discovery)
+            return undefined;
+        const fetchFn = this.options.fetchFn ?? proxiedFetch;
+        try {
+            const response = await fetchFn(`${this.options.apiBase}${GLM_MODELS_PATH}`, {
+                headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' },
+                ...signal === undefined ? {} : { signal },
+            });
+            if (!response.ok) {
+                this.options.onWarn?.(`GLM model list unavailable (HTTP ${response.status})`);
+                return undefined;
+            }
+            const body = await response.json();
+            const ids = (body.data ?? [])
+                .map((entry) => (typeof entry?.id === 'string' ? entry.id.trim() : ''))
+                .filter((id) => id !== '');
+            return ids.length === 0 ? undefined : ids;
+        }
+        catch (error) {
+            this.options.onWarn?.(`GLM model list unavailable (${error instanceof Error ? error.message : String(error)})`);
+            return undefined;
+        }
+    }
+    /** Send one streaming request over the Responses wire. */
+    async request(options, model, accessToken, signal) {
+        const resolveImage = this.imageResolver(signal);
+        const resolved = await toResponsesInput(options.messages, options.system, resolveImage);
+        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) } },
+            ...options.sessionId === undefined ? {} : { prompt_cache_key: String(options.sessionId) },
+            include: ['reasoning.encrypted_content'],
+            store: false,
+            stream: true,
+        };
+        const fetchFn = this.options.fetchFn ?? proxiedFetch;
+        return fetchFn(`${this.options.apiBase}${GLM_RESPONSES_PATH}`, {
+            method: 'POST',
+            headers: {
+                '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 (${error instanceof Error ? error.message : String(error)})`);
+                return undefined;
+            }
+        };
+    }
+    /** The catalog the controller publishes without hand-added ids. */
+    ownCatalogEntries() {
+        return this.shippedCatalog();
+    }
+    /** The catalog the controller publishes. */
+    catalogEntries() {
+        return this.catalog();
+    }
+}
+/** An entry for an id this build ships no metadata for. */
+function extraEntry(id) {
+    return { id, name: id, contextWindow: GLM_CONTEXT_WINDOW };
+}
+/** 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((effort) => ({ id: ReasoningEffortId(effort), name: String(effort), description: '' })),
+        ...entry.defaultEffort === undefined ? {} : { defaultEffort: ReasoningEffortId(entry.defaultEffort) },
+    };
+}

package/lib/providers/grok.d.ts

@@ -0,0 +1,224 @@
+/**
+ * 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 { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { PkcePair } from '../auth/pkce-flow.js';
+import type { SessionBase } from '../auth/store.js';
+import { TokenManager } from '../auth/tokens.js';
+import type { ProviderRoute } from '../auth/registry.js';
+import type { ModelPreferences } from '../settings.js';
+import type { FetchFn } from '../http.js';
+import type { CatalogEntry } from './catalog.js';
+/** Route key this module registers. */
+export declare const GROK_PROVIDER_ID = "grok";
+/** Display name for selectors and diagnostics. */
+export declare const GROK_PROVIDER_NAME = "Grok (X Premium)";
+/** Where a user manages the underlying subscription. */
+export declare const GROK_CODE_URL = "https://x.ai/grok";
+/** OIDC issuer whose well-known document names the endpoints. */
+export declare const GROK_ISSUER = "https://auth.x.ai";
+/** Discovery document URL. */
+export declare const GROK_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
+/** The Grok CLI's registered client id. */
+export declare const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+/** Scopes the CLI requests; `grok-cli:access` is what admits subscription traffic. */
+export declare const GROK_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+/** The one loopback port the registered client redirects to. */
+export declare const GROK_CALLBACK_PORT = 56121;
+/** Path the client redirects to. */
+export declare const GROK_CALLBACK_PATH = "/callback";
+/** API base; `<base>/responses` streams and `<base>/models` lists. */
+export declare const GROK_API_BASE = "https://api.x.ai/v1";
+/** Optional CLI catalog that discloses per-model context and reasoning levels. */
+export declare 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 declare const GROK_CONTEXT_WINDOW = 256000;
+/** Default per-request output cap. */
+export declare const GROK_DEFAULT_MAX_TOKENS = 32000;
+/** Refresh when the access token has less than this much life left. */
+export declare const GROK_PREEMPT_MS: number;
+/**
+ * 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 declare const GROK_MODELS: readonly CatalogEntry[];
+/** A stored Grok (X Premium) login. */
+export interface GrokSession extends SessionBase {
+    /** Token endpoint discovered at login time; used for later refresh. */
+    tokenEndpoint: string;
+    /** Issuer the session was created against. */
+    issuer: string;
+    /** Scopes the tokens were issued with, echoed on refresh. */
+    scopes?: string;
+}
+/**
+ * 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 declare function parseGrokSession(value: unknown): GrokSession | undefined;
+/** The discovered authorization-server endpoints. */
+interface GrokEndpoints {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+}
+/** Account identity from the id token, falling back to the access token. */
+export declare function identityFromGrokTokens(accessToken: string, idToken?: string): {
+    accountId?: string;
+    email?: string;
+};
+/** One token-endpoint answer, normalised. */
+interface GrokTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    idToken?: string;
+}
+/** Turn a token-endpoint payload into tokens with an absolute expiry. */
+export declare function parseGrokTokenPayload(payload: unknown, previousRefreshToken?: string): GrokTokens;
+/** OIDC discovery, cached for the process. */
+export declare function createGrokDiscovery(fetchFn: FetchFn, onWarn?: (message: string) => void): () => Promise<GrokEndpoints>;
+/** Exchange an authorization code for tokens. */
+export declare function exchangeGrokCode(input: {
+    fetchFn: FetchFn;
+    tokenEndpoint: string;
+    code: string;
+    redirectUri: string;
+    pkce: PkcePair;
+    signal: AbortSignal;
+}): Promise<GrokTokens>;
+/** Redeem a refresh token. */
+export declare function refreshGrokToken(input: {
+    fetchFn: FetchFn;
+    tokenEndpoint: string;
+    refreshToken: string;
+}): Promise<GrokTokens>;
+/** One CLI-catalog entry's capability metadata. */
+interface GrokCliMetadata {
+    contextWindow?: number;
+    reasoningEfforts?: readonly string[];
+    defaultEffort?: string;
+}
+/** Constructor dependencies for {@link GrokAdapter}. */
+export interface GrokAdapterOptions {
+    /** API base; `<base>/responses` and `<base>/models`. */
+    apiBase: string;
+    /** Whether the live catalog is consulted. */
+    discovery: boolean;
+    /** Inactivity budget before a stalled stream is abandoned. */
+    streamIdleTimeoutMs: number;
+    tokens: TokenManager<GrokSession>;
+    onWarn?: (message: string) => void;
+    resolveAttachments?: () => AttachmentStore | undefined;
+    hiddenModels?: () => Promise<ReadonlySet<string>>;
+    /**
+     * Model ids the user added by hand.
+     *
+     * Read per catalog query, so the add button takes effect at the picker's next
+     * refresh. A hand-added id is published with conservative metadata: the
+     * endpoint is the authority on what it serves, not this build.
+     */
+    userModels?: () => Promise<readonly string[]>;
+    /** The user's model rank for this route, most preferred first. */
+    modelOrder?: () => Promise<readonly string[]>;
+    fetchFn?: FetchFn;
+    onCredentialRejected?: (account: string) => void;
+}
+/** Grok wire adapter: one instance serves the `grok` provider route. */
+export declare class GrokAdapter extends LlmAdapter {
+    private readonly options;
+    /** Live model ids seen this session. */
+    private discovered;
+    /** Capability metadata from the CLI catalog, keyed by model id. */
+    private readonly metadata;
+    /** Ids the user added by hand, cached so the sync catalog can name them. */
+    private userAddedIds;
+    constructor(options: GrokAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(): undefined;
+    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    private hidden;
+    resolveModel(_provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * 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.
+     */
+    private catalog;
+    /**
+     * 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.
+     */
+    private shippedCatalog;
+    /** Re-read the ids the user added by hand. */
+    private syncUserModels;
+    /**
+     * 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.
+     */
+    private addedEntries;
+    /** Record the live catalog for the picker. */
+    discover(ids: readonly string[], metadata?: ReadonlyMap<string, GrokCliMetadata>): void;
+    /** The curated catalog, for the Settings page's model list. */
+    catalogEntries(): readonly CatalogEntry[];
+    /** What this route itself serves, without the ids added by hand. */
+    ownCatalogEntries(): readonly CatalogEntry[];
+    /** Build and send one request for one model. */
+    private request;
+    /** Resolve image blocks through the attachment service, when it is present. */
+    private imageResolver;
+    /**
+     * 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.
+     */
+    fetchCatalog(accessToken: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
+    /** Read per-model capabilities from the CLI catalog; failures are silent. */
+    private fetchCliMetadata;
+}
+/** Everything the `grok` route needs from the plugin configuration. */
+export interface GrokProviderOptions {
+    /** Absolute path of `auth.json`. */
+    credentialFile: string;
+    /** API base; `<base>/responses` and `<base>/models`. */
+    apiBase?: string;
+    /** Consult the endpoint's live model list. */
+    discovery: boolean;
+    /** Abandon a stream after this much silence. */
+    streamIdleTimeoutMs: number;
+    /** Shared model-visibility preferences. */
+    preferences: ModelPreferences;
+    /** Resolve the attachment service per request. */
+    resolveAttachments?: () => AttachmentStore | undefined;
+    /** Invoked when the catalog or its visibility changed. */
+    onCatalogChanged?: () => void;
+    onWarn?: (message: string) => void;
+    /** Fetch implementation; defaults to the proxy-aware fetch. */
+    fetchFn?: FetchFn;
+    /** Discovery fetch override, for tests. */
+    discoveryFetchFn?: FetchFn;
+}
+/**
+ * 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 declare function createGrokProvider(options: GrokProviderOptions): ProviderRoute;
+export {};