dsh-plugin-subscriptions 0.1.0

package/lib/providers/codex.js

@@ -0,0 +1,391 @@
+/**
+ * ChatGPT/Codex subscription provider: OAuth against auth.openai.com with the
+ * Codex CLI client id, and streaming against the ChatGPT backend Responses
+ * endpoint.
+ */
+import { randomUUID } from 'node:crypto';
+import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import { decodeJwtPayload } from '../auth/jwt.js';
+import { resolveImages } from '../translate/resolved.js';
+import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
+export const CODEX_CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann';
+export const CODEX_AUTHORIZE_URL = 'https://auth.openai.com/oauth/authorize';
+export const CODEX_TOKEN_URL = 'https://auth.openai.com/oauth/token';
+export const CODEX_API_URL = 'https://chatgpt.com/backend-api/codex/responses';
+const CODEX_SCOPE = 'openid profile email offline_access api.connectors.read api.connectors.invoke';
+const CODEX_CALLBACK_PATH = '/auth/callback';
+const CODEX_CONTEXT_WINDOW = 400_000;
+const CODEX_DEFAULT_MAX_TOKENS = 128_000;
+/** Refresh when the access token has less than this much life left. */
+export const CODEX_PREEMPT_MS = 5 * 60_000;
+/** Default instruction when the request carries no system prompt. */
+const DEFAULT_CODEX_INSTRUCTIONS = 'You are Codex, a coding agent based on GPT-5. '
+    + 'Help the user with their software engineering tasks.';
+/** Refresh-grant rejections that mean the login is gone for good. */
+const PERMANENT_REFRESH_CODES = new Set([
+    'refresh_token_expired',
+    'refresh_token_reused',
+    'refresh_token_invalidated',
+    'invalid_grant',
+]);
+const CODEX_EFFORTS = [
+    { id: ReasoningEffortId('minimal'), name: 'Minimal' },
+    { id: ReasoningEffortId('low'), name: 'Low' },
+    { id: ReasoningEffortId('medium'), name: 'Medium' },
+    { id: ReasoningEffortId('high'), name: 'High' },
+    { id: ReasoningEffortId('xhigh'), name: 'Extra High' },
+];
+const CODEX_DEFAULT_EFFORT = ReasoningEffortId('high');
+/** Every gpt-5.x codex model accepts image input. */
+const CODEX_MODALITIES = ['text', 'image'];
+/** Static codex flow facts for the OAuth flow engine. */
+export const codexFlow = {
+    callbackPath: CODEX_CALLBACK_PATH,
+    listen: { host: 'localhost', ports: [1455, 1457] },
+    buildAuthorizeUrl({ redirectUri, state, pkce }) {
+        const params = new URLSearchParams({
+            response_type: 'code',
+            client_id: CODEX_CLIENT_ID,
+            redirect_uri: redirectUri,
+            scope: CODEX_SCOPE,
+            code_challenge: pkce.challenge,
+            code_challenge_method: 'S256',
+            state,
+            id_token_add_organizations: 'true',
+            codex_cli_simplified_flow: 'true',
+            originator: 'codex_cli_rs',
+        });
+        return `${CODEX_AUTHORIZE_URL}?${params.toString()}`;
+    },
+};
+/** Pull `chatgpt_account_id` out of an id token payload. */
+function accountIdOf(idToken) {
+    const payload = idToken === undefined ? undefined : decodeJwtPayload(idToken);
+    const auth = payload?.['https://api.openai.com/auth'];
+    const accountId = typeof auth === 'object' && auth !== null
+        ? auth.chatgpt_account_id
+        : undefined;
+    if (typeof accountId !== 'string' || accountId.length === 0) {
+        throw new Error('codex login did not return a chatgpt account id; cannot use the subscription');
+    }
+    return accountId;
+}
+/**
+ * Decode the user-identity claims of a codex id token (pure, cheap — no
+ * verification, same trust posture as {@link accountIdOf}). Claim paths
+ * mirror codex-rs `login/src/token_data.rs`: the email is the top-level
+ * `email` claim, falling back to `https://api.openai.com/profile`.email; the
+ * plan is `https://api.openai.com/auth`.chatgpt_plan_type.
+ * @param idToken - a stored or freshly issued id token, when present.
+ * @returns whichever claims the token carried; empty when undecodable.
+ */
+export function codexProfileClaims(idToken) {
+    const payload = idToken === undefined ? undefined : decodeJwtPayload(idToken);
+    if (payload === undefined)
+        return {};
+    const profile = payload['https://api.openai.com/profile'];
+    const profileEmail = typeof profile === 'object' && profile !== null
+        ? profile.email
+        : undefined;
+    const email = payload.email ?? profileEmail;
+    const auth = payload['https://api.openai.com/auth'];
+    const plan = typeof auth === 'object' && auth !== null
+        ? auth.chatgpt_plan_type
+        : undefined;
+    return {
+        ...typeof email === 'string' && email.length > 0 ? { emailAddress: email } : {},
+        ...typeof plan === 'string' && plan.length > 0 ? { planType: plan } : {},
+    };
+}
+/** Build a session from a token response; expires_in wins, JWT exp is the fallback. */
+function codexSession(tokens, fallback) {
+    if (typeof tokens.access_token !== 'string' || tokens.access_token.length === 0) {
+        throw new Error('codex token endpoint returned no access token');
+    }
+    const refreshToken = tokens.refresh_token ?? fallback?.refreshToken;
+    if (refreshToken === undefined)
+        throw new Error('codex token endpoint returned no refresh token');
+    let expiresAt;
+    if (typeof tokens.expires_in === 'number' && tokens.expires_in > 0) {
+        expiresAt = Date.now() + tokens.expires_in * 1000;
+    }
+    else {
+        const exp = decodeJwtPayload(tokens.access_token)?.exp;
+        if (typeof exp === 'number' && exp > 0)
+            expiresAt = exp * 1000;
+    }
+    if (expiresAt === undefined)
+        throw new Error('codex token endpoint returned no usable expiry');
+    // Identity claims come from the freshest id token; a refresh that omits
+    // one keeps the claims the stored session already had.
+    const idToken = tokens.id_token ?? fallback?.idToken;
+    const claims = {
+        ...fallback?.emailAddress === undefined ? {} : { emailAddress: fallback.emailAddress },
+        ...fallback?.planType === undefined ? {} : { planType: fallback.planType },
+        ...codexProfileClaims(tokens.id_token),
+    };
+    return {
+        accessToken: tokens.access_token,
+        refreshToken,
+        expiresAt,
+        accountId: tokens.id_token === undefined && fallback !== undefined
+            ? fallback.accountId
+            : accountIdOf(tokens.id_token),
+        ...idToken === undefined ? {} : { idToken },
+        ...claims,
+    };
+}
+/**
+ * Exchange an authorization code for a codex session (form-encoded grant).
+ * @param code - the authorization code from the callback.
+ * @param verifier - the PKCE verifier minted for the attempt.
+ * @param redirectUri - the attempt's redirect URI.
+ * @returns the session to store.
+ */
+export async function exchangeCodexCode(code, verifier, redirectUri) {
+    const response = await fetch(CODEX_TOKEN_URL, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirectUri,
+            client_id: CODEX_CLIENT_ID,
+            code_verifier: verifier,
+        }).toString(),
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'codex');
+    return codexSession(await response.json());
+}
+/**
+ * Refresh a codex session (JSON grant — unlike the code exchange).
+ * @param session - the stored session.
+ * @returns the fresh session to store.
+ */
+export async function refreshCodex(session) {
+    const response = await fetch(CODEX_TOKEN_URL, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            client_id: CODEX_CLIENT_ID,
+            grant_type: 'refresh_token',
+            refresh_token: session.refreshToken,
+        }),
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'codex');
+    return codexSession(await response.json(), session);
+}
+/**
+ * Whether a codex refresh failure means the login is permanently gone.
+ * @param error - the thrown refresh error.
+ * @returns true when re-login is the only fix.
+ */
+export function isCodexPermanentRefreshError(error) {
+    return error instanceof OAuthEndpointError
+        && error.oauthCode !== undefined
+        && PERMANENT_REFRESH_CODES.has(error.oauthCode);
+}
+export const CODEX_MODELS_URL = 'https://chatgpt.com/backend-api/codex/models';
+/**
+ * Client version sent on the /models catalog request. The backend gates the
+ * visible model list by client version: versions below ~0.101 get an empty
+ * list, while current codex CLI releases get the full catalog — keep this in
+ * the range of current codex CLI releases.
+ */
+export const CODEX_CLIENT_VERSION = '0.147.0';
+/** Display name for a wire reasoning-effort value. */
+function effortName(effort) {
+    return effort === 'xhigh' ? 'Extra High' : effort.charAt(0).toUpperCase() + effort.slice(1);
+}
+/**
+ * Fetch the live codex model catalog with the session's auth headers.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @returns discovered models: hidden entries dropped, sorted by priority.
+ */
+export async function fetchCodexModels(session, fetchFn = fetch) {
+    const url = `${CODEX_MODELS_URL}?client_version=${CODEX_CLIENT_VERSION}`;
+    const response = await fetchFn(url, {
+        headers: {
+            'authorization': `Bearer ${session.accessToken}`,
+            'chatgpt-account-id': session.accountId,
+            'originator': 'codex_cli_rs',
+            'accept': 'application/json',
+            ...attributionHeaders(),
+        },
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'codex models');
+    const payload = await response.json();
+    if (!Array.isArray(payload.models))
+        throw new Error('codex models endpoint returned no models array');
+    const discovered = [];
+    for (const entry of payload.models) {
+        if (typeof entry.slug !== 'string' || entry.slug.length === 0)
+            continue;
+        // codex-rs ModelVisibility: only "list" is picker-visible; hide/none are
+        // dropped, and an absent or unknown value is included (in doubt, include).
+        if (entry.visibility === 'hide' || entry.visibility === 'none')
+            continue;
+        const efforts = (entry.supported_reasoning_levels ?? [])
+            .filter(level => typeof level.effort === 'string' && level.effort.length > 0)
+            .map(level => ({
+            id: ReasoningEffortId(level.effort),
+            name: effortName(level.effort),
+            ...level.description === undefined ? {} : { description: level.description },
+        }));
+        const defaultEffort = typeof entry.default_reasoning_level === 'string'
+            && entry.default_reasoning_level.length > 0
+            && efforts.some(effort => effort.id === ReasoningEffortId(entry.default_reasoning_level))
+            ? ReasoningEffortId(entry.default_reasoning_level)
+            : undefined;
+        discovered.push({
+            id: entry.slug,
+            name: typeof entry.display_name === 'string' && entry.display_name.length > 0
+                ? entry.display_name
+                : entry.slug,
+            ...typeof entry.description === 'string' && entry.description.length > 0
+                ? { description: entry.description }
+                : {},
+            ...typeof entry.context_window === 'number' && entry.context_window > 0
+                ? { contextWindow: entry.context_window }
+                : {},
+            ...typeof entry.priority === 'number' ? { priority: entry.priority } : {},
+            ...efforts.length > 0
+                ? { reasoning: { efforts, ...defaultEffort === undefined ? {} : { defaultEffort } } }
+                : {},
+        });
+    }
+    discovered.sort((a, b) => (a.priority ?? Number.MAX_SAFE_INTEGER) - (b.priority ?? Number.MAX_SAFE_INTEGER));
+    // An empty catalog from a 200 response means the backend gated us out (e.g.
+    // client_version too old): surface it as a discovery failure so the adapter
+    // falls back to the static catalog instead of vanishing from the picker.
+    if (discovered.length === 0) {
+        throw new Error(`codex models endpoint returned an empty catalog (client_version ${CODEX_CLIENT_VERSION})`);
+    }
+    return discovered;
+}
+/** Codex wire adapter: one instance serves the `codex` provider route. */
+export class CodexAdapter extends LlmAdapter {
+    options;
+    catalog = new ModelCatalogCache();
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    providerInfo(provider) {
+        return { id: provider, name: 'ChatGPT (Codex)' };
+    }
+    staticModels(provider) {
+        return this.options.models.map(model => ({
+            provider,
+            id: model.id,
+            name: model.name ?? model.id,
+            inputModalities: model.inputModalities ?? CODEX_MODALITIES,
+        }));
+    }
+    async listModels(provider) {
+        // Not logged in → empty catalog, so the web picker drops the provider.
+        const session = await this.options.tokens.peek();
+        if (session === undefined)
+            return [];
+        if (!this.options.discovery)
+            return this.staticModels(provider);
+        try {
+            const discovered = await this.catalog.get(() => fetchCodexModels(session, this.options.fetchFn));
+            return discovered.map(model => ({
+                provider,
+                id: model.id,
+                name: model.name,
+                ...model.description === undefined ? {} : { description: model.description },
+                inputModalities: CODEX_MODALITIES,
+            }));
+        }
+        catch (error) {
+            if (error instanceof OAuthEndpointError && error.status === 401)
+                this.catalog.invalidate();
+            this.options.onWarn?.(`codex model discovery failed; using the built-in catalog (${errorChain(error)})`);
+            return this.staticModels(provider);
+        }
+    }
+    resolveModel(provider, model) {
+        // Discovered metadata (when discovery is on and the cache is warm) wins
+        // over the static entry; the static entry wins over the built-in defaults.
+        const discovered = this.options.discovery
+            ? this.catalog.cached()?.find(entry => entry.id === model)
+            : undefined;
+        const configured = this.options.models.find(entry => entry.id === model);
+        return Promise.resolve({
+            provider,
+            id: model,
+            name: discovered?.name ?? configured?.name ?? model,
+            ...discovered?.description === undefined ? {} : { description: discovered.description },
+            inputModalities: configured?.inputModalities ?? CODEX_MODALITIES,
+            context: { contextWindow: discovered?.contextWindow ?? configured?.contextWindow ?? CODEX_CONTEXT_WINDOW },
+            defaultMaxTokens: configured?.maxTokens ?? CODEX_DEFAULT_MAX_TOKENS,
+            reasoning: discovered?.reasoning ?? { efforts: CODEX_EFFORTS, defaultEffort: CODEX_DEFAULT_EFFORT },
+        });
+    }
+    async *stream(options) {
+        const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);
+        try {
+            let session = await this.options.tokens.session();
+            let response = await this.request(options, session, watchdog.signal);
+            if (response.status === 401) {
+                // One forced refresh + retry on an unexpired-but-rejected token.
+                session = await this.options.tokens.session(true);
+                response = await this.request(options, session, watchdog.signal);
+            }
+            if (!response.ok)
+                throw await httpLlmError(response, 'codex API');
+            if (response.body === null) {
+                throw new LlmError('codex API returned no response body', EMPTY_RESPONSE_CODE);
+            }
+            yield* streamResponses(response.body, () => { watchdog.pulse(); });
+        }
+        catch (error) {
+            throw mapFetchFailure('codex API', error, watchdog, options.signal);
+        }
+        finally {
+            watchdog.stop();
+        }
+    }
+    async request(options, session, signal) {
+        const messages = await resolveImages(options.messages, this.options.resolveAttachments?.(), signal);
+        const { instructions, input } = toResponsesInput(messages, options.system);
+        const body = {
+            model: options.model,
+            instructions: instructions ?? DEFAULT_CODEX_INSTRUCTIONS,
+            input,
+            ...options.tools !== undefined && options.tools.length > 0
+                ? { tools: toResponsesTools(options.tools) }
+                : {},
+            tool_choice: 'auto',
+            parallel_tool_calls: true,
+            ...options.reasoningEffort !== undefined
+                ? { reasoning: { effort: String(options.reasoningEffort), summary: 'auto' } }
+                : {},
+            store: false,
+            stream: true,
+            include: ['reasoning.encrypted_content'],
+            ...options.sessionId !== undefined ? { prompt_cache_key: String(options.sessionId) } : {},
+        };
+        return fetch(CODEX_API_URL, {
+            method: 'POST',
+            headers: {
+                'authorization': `Bearer ${session.accessToken}`,
+                'chatgpt-account-id': session.accountId,
+                'originator': 'codex_cli_rs',
+                'session-id': randomUUID(),
+                'accept': 'text/event-stream',
+                'content-type': 'application/json',
+                ...attributionHeaders(),
+            },
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+}

package/lib/providers/common.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Plumbing shared by the three subscription adapters: HTTP error mapping, a
+ * stream idle watchdog, fetch failure classification, OAuth endpoint errors,
+ * and the per-provider {@link TokenManager} that owns session freshness.
+ * Concurrent refreshes for one provider coalesce behind a single in-flight
+ * promise (`inflight`), so a rotating refresh token is never spent twice.
+ */
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import type { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+/** One configured model catalog entry. */
+export interface ModelEntry {
+    /** Wire model id; must be non-empty. */
+    id: string;
+    /** Selector label; defaults to the id. */
+    name?: string;
+    /** Known combined request/response context capacity. */
+    contextWindow?: number;
+    /** Per-request output cap for this model. */
+    maxTokens?: number;
+    /** Accepted request modalities; when set, wins over the provider default. */
+    inputModalities?: ('text' | 'image')[];
+}
+/**
+ * Validate a configured model catalog (mirrors llm-deepseek's resolveModels).
+ * @param models - raw configured entries.
+ * @param label - diagnostic prefix naming the provider.
+ * @returns the validated entries.
+ */
+export declare function validateModels(models: readonly ModelEntry[], label: string): ModelEntry[];
+/**
+ * Build an LlmError from a non-2xx provider response, reading and truncating
+ * the body for the message and mapping the status to a stable code.
+ * @param response - the failed response.
+ * @param label - diagnostic prefix naming the provider API.
+ * @returns the classified error.
+ */
+export declare function httpLlmError(response: Response, label: string): Promise<LlmError>;
+/** An idle watchdog: aborts its signal when no SSE activity arrives within the timeout. */
+export interface IdleWatchdog {
+    /** Signal to pass to fetch and body reads; aborts on caller cancel or idle expiry. */
+    readonly signal: AbortSignal;
+    /** Reset the idle timer (call on every received SSE event). */
+    pulse(): void;
+    /** Stop the timer and detach from the caller signal. */
+    stop(): void;
+    /** Whether the last abort came from idle expiry rather than caller cancellation. */
+    timedOut(): boolean;
+}
+/**
+ * Create an idle watchdog chained to the caller's signal.
+ * @param caller - the request's own abort signal, when present.
+ * @param timeoutMs - maximum idle interval while a stream read is outstanding.
+ * @returns the watchdog; always {@link IdleWatchdog.stop} it when the stream ends.
+ */
+export declare function idleWatchdog(caller: AbortSignal | undefined, timeoutMs: number): IdleWatchdog;
+/**
+ * Classify a thrown fetch failure. Caller cancellation maps to ABORTED, idle
+ * expiry to TIMEOUT, and everything else (DNS, TLS, refused connection) to
+ * TRANSPORT with the cause chained.
+ * @param label - diagnostic prefix naming the provider API.
+ * @param error - the thrown value.
+ * @param watchdog - the request's idle watchdog.
+ * @param caller - the request's own abort signal, when present.
+ * @returns the classified error.
+ */
+export declare function mapFetchFailure(label: string, error: unknown, watchdog: IdleWatchdog, caller: AbortSignal | undefined): LlmError;
+/** OAuth token-endpoint failure carrying the provider's `error` code when it sent one. */
+export declare class OAuthEndpointError extends Error {
+    /** HTTP status of the token endpoint response. */
+    readonly status: number;
+    /** The provider's OAuth `error` code (e.g. `invalid_grant`), when present. */
+    readonly oauthCode: string | undefined;
+    constructor(message: string, status: number, oauthCode?: string);
+}
+/**
+ * Read an OAuth JSON error body into an {@link OAuthEndpointError}.
+ * @param response - the failed token-endpoint response.
+ * @param label - diagnostic prefix naming the provider.
+ * @returns the error to throw.
+ */
+export declare function oauthEndpointError(response: Response, label: string): Promise<OAuthEndpointError>;
+/** A session fresh enough to serve a request without a refresh. */
+interface TimedSession {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+/** Provider hooks the token manager needs. */
+export interface TokenManagerOptions<S extends TimedSession> {
+    /** Human-readable provider name for error messages. */
+    displayName: string;
+    /** Refresh this long before `expiresAt`. */
+    preemptMs: number;
+    load(): Promise<S | undefined>;
+    save(session: S): Promise<void>;
+    remove(): Promise<void>;
+    /** Perform the provider's refresh-token grant. */
+    refresh(session: S): Promise<S>;
+    /** Whether a refresh failure is permanent (re-login required). */
+    isPermanent(error: unknown): boolean;
+    /** Called after a permanent refresh failure deleted the stored session. */
+    onRemoved?(): void;
+}
+/**
+ * Per-provider session freshness: loads the stored session, refreshes
+ * proactively inside the preempt window or on demand after a 401, and
+ * coalesces concurrent refreshes behind one in-flight promise. Permanent
+ * refresh failures delete the stored session and surface INVALID_CREDENTIAL
+ * with a re-login hint; transient failures fall back to a still-valid token.
+ */
+export declare class TokenManager<S extends TimedSession> {
+    private readonly options;
+    private inflight;
+    constructor(options: TokenManagerOptions<S>);
+    /**
+     * Read the stored session without any refresh side effect. Catalog queries
+     * (`listModels`) use this to decide whether the provider is logged in.
+     * @returns the stored session, or `undefined` when logged out.
+     */
+    peek(): Promise<S | undefined>;
+    /**
+     * Whether a session is currently stored (cheap; never refreshes).
+     * @returns true when logged in.
+     */
+    hasSession(): Promise<boolean>;
+    /**
+     * Resolve a usable session, refreshing proactively or on demand.
+     * @param forceRefresh - refresh regardless of expiry (used after a 401).
+     * @returns the persisted session to send.
+     * @throws LlmError MISSING_CREDENTIAL when logged out, INVALID_CREDENTIAL
+     *   when the refresh grant is permanently rejected.
+     */
+    session(forceRefresh?: boolean): Promise<S>;
+    private doRefresh;
+}
+/** Fetch signature adapters accept for discovery calls (injectable for tests). */
+export type FetchFn = typeof fetch;
+/** One model discovered from a provider's live model-list endpoint. */
+export interface DiscoveredModel {
+    /** Wire model id. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    description?: string;
+    /** Advertised combined context capacity in tokens. */
+    contextWindow?: number;
+    /** Provider sort hint; lower sorts earlier. */
+    priority?: number;
+    /** Advertised reasoning efforts, when the provider discloses them. */
+    reasoning?: {
+        efforts: {
+            id: ReasoningEffortId;
+            name: string;
+            description?: string;
+        }[];
+        defaultEffort?: ReasoningEffortId;
+    };
+}
+/** How long a discovered catalog is trusted before re-fetching. */
+export declare const DISCOVERY_TTL_MS: number;
+/**
+ * TTL cache for one provider's discovered model catalog. Only `listModels`
+ * populates it (via {@link get}); `resolveModel` reads {@link cached} so it
+ * never performs network I/O. A 401 during a fetch must call
+ * {@link invalidate}.
+ */
+export declare class ModelCatalogCache {
+    private readonly ttlMs;
+    private entry;
+    constructor(ttlMs?: number);
+    /**
+     * The cached catalog when fresh, without fetching.
+     * @returns the cached models, or `undefined` when absent or stale.
+     */
+    cached(): readonly DiscoveredModel[] | undefined;
+    /**
+     * Return the cached catalog when fresh, otherwise fetch and cache it.
+     * @param fetcher - performs the provider's model-list request.
+     * @returns the discovered models.
+     */
+    get(fetcher: () => Promise<DiscoveredModel[]>): Promise<readonly DiscoveredModel[]>;
+    /** Drop the cached catalog (e.g. after a 401 proved the credential changed). */
+    invalidate(): void;
+}
+export {};