dsh-plugin-subscription-oauth 0.16.3 → 0.17.1

package/lib/providers/grok.js

@@ -16,7 +16,7 @@ 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 { composeCatalog, fallbackEntry, findEntry, liveEntry, liveModelFacts, resolveCatalog } from './catalog.js';
 import { isMissingOrInvalidCredential } from './common.js';
 import { streamProviderResponses, accountPoolHooks } from './responses-stream.js';
 import { readGrokUsage } from './usage.js';
@@ -66,11 +66,14 @@ const EFFORT_LABELS = {
     [FAST_RUNG]: { name: 'Fast', description: 'xAI fast variant of this model' },
 };
 /**
- * Curated catalog entries.
+ * The cold-start seed: what this build knows about xAI's models before either of the
+ * account's own listings has been read.
  *
- * 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.
+ * A seed, never a roster. It decides which ids exist only until a listing has been read
+ * — the cached one at startup, or a fresh one on "refresh models" — and afterwards it
+ * describes only the fields those listings left silent. A fact the endpoint states,
+ * a context window included, always wins over anything here, so a model released,
+ * renamed or retired server-side reaches the picker without a plugin release.
  */
 export const GROK_MODELS = [
     {
@@ -276,6 +279,75 @@ export async function refreshGrokToken(input) {
     }
     return parseGrokTokenPayload(payload, input.refreshToken);
 }
+/** Description the picker shows for a model only the endpoint's listing describes. */
+const GROK_LIVE_DESCRIPTION = 'Reported by the xAI model list';
+/**
+ * Split one cached or fresh payload into the two listings it holds.
+ *
+ * The payload is this route's own object, so its shape is validated rather than trusted:
+ * a document written by an older build, or corrupted on disk, is a cache miss and never
+ * a crash on the way to the picker.
+ *
+ * @param payload - the cached or freshly assembled `{ public, cli }` payload.
+ * @returns the two row lists, or undefined when the payload is not this route's.
+ */
+function listingOf(payload) {
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+        return undefined;
+    const record = payload;
+    const publicRows = record['public'];
+    if (!Array.isArray(publicRows))
+        return undefined;
+    const cliRows = record['cli'];
+    return { public: publicRows, cli: Array.isArray(cliRows) ? cliRows : [] };
+}
+/**
+ * Read the capability metadata and the ids one CLI catalog answer named.
+ *
+ * The shape is xAI's own rather than the OpenAI-compatible one the shared row reader
+ * handles: a context window under `context_window`, and a ladder under
+ * `reasoning_efforts[].value` gated by `supports_reasoning_effort`. A row that states
+ * nothing usable contributes only its id, because the id list is what folds a fast
+ * variant onto its base row.
+ *
+ * @param rows - decoded rows of the CLI catalog answer.
+ * @returns the metadata by model id, and every id the catalog named.
+ */
+function cliListingOf(rows) {
+    const metadata = new Map();
+    const ids = [];
+    for (const row of rows) {
+        if (typeof row !== 'object' || row === null || Array.isArray(row))
+            continue;
+        const entry = row;
+        const rawId = entry['id'];
+        const id = typeof rawId === 'string' && rawId.length > 0 ? rawId : undefined;
+        if (id === undefined)
+            continue;
+        ids.push(id);
+        const rawContext = entry['context_window'];
+        const contextWindow = typeof rawContext === 'number' && Number.isFinite(rawContext) ? rawContext : undefined;
+        const supportsEffort = entry['supports_reasoning_effort'] === true;
+        const rawEfforts = entry['reasoning_efforts'];
+        const efforts = supportsEffort && Array.isArray(rawEfforts)
+            ? rawEfforts
+                .map((effort) => (typeof effort === 'object' && effort !== null
+                ? effort['value']
+                : undefined))
+                .filter((value) => typeof value === 'string' && value.length > 0)
+            : [];
+        const requested = entry['reasoning_effort'];
+        const defaultEffort = supportsEffort && typeof requested === 'string' && efforts.includes(requested)
+            ? requested
+            : undefined;
+        metadata.set(id, {
+            ...contextWindow === undefined ? {} : { contextWindow },
+            ...efforts.length === 0 ? {} : { reasoningEfforts: efforts },
+            ...defaultEffort === undefined ? {} : { defaultEffort },
+        });
+    }
+    return { metadata, ids };
+}
 /** Model ids that are clearly not chat models. */
 const NON_CHAT_ID = /(?:^|[-_/])(?:image|video|imagine|embed|embedding|whisper|tts|vision-only)/i;
 /** Model ids that are image-generation models, matched per provider's naming. */
@@ -438,13 +510,23 @@ export function stripContext(id) {
 /** Grok wire adapter: one instance serves the `grok` provider route. */
 export class GrokAdapter extends LlmAdapter {
     options;
-    /** Live model ids seen this session. */
-    discovered;
+    /**
+     * The catalog this route serves: entries derived from the endpoint's own two
+     * listings, either the pair just read or the pair the cache kept from the last read.
+     *
+     * Undefined means neither source has produced a listing yet, so the cold-start seed
+     * is all this build can honestly offer.
+     */
+    live;
+    /** Whether the cached listing has been read; it is read at most once per session. */
+    hydrated = false;
     /** Capability metadata from the CLI catalog, keyed by model id. */
     metadata = new Map();
     /** Fast-variant wire id per base model, for the picker's quick-mode button. */
     fastVariants = new FastVariantIndex();
-    /** Image-generation model id, when discovery reported one. */
+    /** The context variant one base row dispatches to, so `@500k` is never typed by hand. */
+    defaultContext = new Map();
+    /** Image-generation model id, when the listing reported one. */
     imageModel;
     /** Ids the user added by hand, cached so the sync catalog can name them. */
     userAddedIds = [];
@@ -452,6 +534,146 @@ export class GrokAdapter extends LlmAdapter {
         super();
         this.options = options;
     }
+    /**
+     * Adopt the two listings of one live read as this route's catalog.
+     *
+     * Everything the picker shows is derived here from the endpoint's own answers: the
+     * public `/models` rows decide membership and state each model's display name, window
+     * and modalities, and the account's CLI catalog states the reasoning ladder and names
+     * the fast variants — the one thing the public list omits.
+     *
+     * A fast variant or an `@Nk` context variant rides with its base row instead of becoming
+     * a row of its own: the variant is a wire id the composer dispatches, never a picker
+     * row, so the user always has a way back to the standard model.
+     *
+     * @param payload - the cached or freshly assembled `{ public, cli }` payload.
+     * @returns the entries to publish, in the endpoint's own order; undefined when the
+     *   payload names no model at all, so the caller keeps whatever it already had.
+     */
+    adoptListing(payload) {
+        const listing = listingOf(payload);
+        if (listing === undefined)
+            return undefined;
+        const facts = listing.public
+            .map((row) => liveModelFacts(row))
+            .filter((fact) => fact !== undefined);
+        const cli = cliListingOf(listing.cli);
+        const chat = facts.filter((fact) => !NON_CHAT_ID.test(fact.id) && !isImageModel(fact.id));
+        // Membership comes from the public list, so a payload that named none of it is a miss
+        // rather than an empty picker.
+        if (chat.length === 0)
+            return undefined;
+        // One payload is the whole truth, so every table derived from an earlier read is
+        // replaced rather than merged: a model the endpoint has retired cannot survive in
+        // state left behind by a read that no longer names it.
+        this.metadata.clear();
+        this.fastVariants.clear();
+        this.defaultContext.clear();
+        for (const [id, meta] of cli.metadata)
+            this.metadata.set(id, meta);
+        // Image models are never picker rows: an agent calls them, always on.
+        this.imageModel = [...facts.map((fact) => fact.id), ...cli.ids].find((id) => isImageModel(id));
+        // Every id either listing named is what a variant may pair with; the pairing itself is
+        // the longest listed prefix of the variant's own name.
+        const wireIds = [
+            ...chat.map((fact) => fact.id),
+            ...cli.ids.filter((id) => !NON_CHAT_ID.test(id) && !isImageModel(id)),
+        ];
+        for (const id of wireIds)
+            this.fastVariants.noteListed(id);
+        this.noteWireVariants(chat.map((fact) => fact.id));
+        this.noteWireVariants(cli.ids);
+        // Fold each variant onto its row, keeping the endpoint's order. A row's own facts are
+        // its identity and win outright; a variant only fills what they omit, except a context
+        // variant, whose window is the one the row actually dispatches to.
+        const own = new Map();
+        const folds = new Map();
+        const windows = new Map();
+        const order = [];
+        for (const fact of chat) {
+            const contextVariant = contextOf(fact.id) !== undefined;
+            const rowId = isFastVariant(fact.id)
+                ? this.fastVariants.pair(fact.id) ?? baseModelOf(fact.id)
+                : contextVariant ? stripContext(fact.id) : fact.id;
+            if (rowId === '')
+                continue;
+            if (!own.has(rowId) && !folds.has(rowId))
+                order.push(rowId);
+            if (contextVariant)
+                windows.set(rowId, Math.max(windows.get(rowId) ?? 0, fact.contextWindow ?? 0));
+            if (rowId === fact.id) {
+                if (!own.has(rowId))
+                    own.set(rowId, fact);
+            }
+            else {
+                folds.set(rowId, [...folds.get(rowId) ?? [], fact]);
+            }
+        }
+        return order.map((rowId) => {
+            const stated = own.get(rowId);
+            const variants = folds.get(rowId) ?? [];
+            const fill = (pick) => {
+                const ownValue = stated === undefined ? undefined : pick(stated);
+                if (ownValue !== undefined)
+                    return ownValue;
+                for (const variant of variants) {
+                    const value = pick(variant);
+                    if (value !== undefined)
+                        return value;
+                }
+                return undefined;
+            };
+            const widest = windows.get(rowId);
+            const statedWindow = stated?.contextWindow;
+            const contextWindow = widest === undefined || (statedWindow ?? 0) >= widest ? statedWindow : widest;
+            const inputModalities = fill((fact) => fact.inputModalities);
+            const reasoningEfforts = fill((fact) => fact.reasoningEfforts);
+            const defaultEffort = fill((fact) => fact.defaultEffort);
+            // The CLI catalog is a listing too, so its figures only fill what the public row
+            // left silent: a window or a ladder the endpoint already stated is never overridden,
+            // and the shipped seed never overrides either of them.
+            const meta = [rowId, ...variants.map((variant) => variant.id)]
+                .map((id) => this.metadata.get(id))
+                .find((entry) => entry !== undefined);
+            const context = contextWindow ?? meta?.contextWindow;
+            const efforts = reasoningEfforts ?? meta?.reasoningEfforts;
+            const metaDefault = meta?.defaultEffort;
+            // A default the ladder does not offer would leave the picker with a rung it cannot
+            // select, so it is stated only when the ladder that won actually contains it.
+            const fallback = defaultEffort
+                ?? (metaDefault === undefined || efforts !== undefined && !efforts.includes(metaDefault) ? undefined : metaDefault);
+            const described = {
+                ...stated ?? { id: rowId },
+                ...context === undefined ? {} : { contextWindow: context },
+                ...efforts === undefined ? {} : { reasoningEfforts: efforts },
+                ...fallback === undefined ? {} : { defaultEffort: fallback },
+                ...inputModalities === undefined ? {} : { inputModalities },
+            };
+            return liveEntry(described, GROK_MODELS, GROK_CONTEXT_WINDOW, GROK_LIVE_DESCRIPTION);
+        });
+    }
+    /**
+     * Read the cached listing, once, so the picker works without asking the endpoint.
+     *
+     * Called before the first catalog query, and fired at construction by the route's
+     * factory because the Settings page reads the catalog synchronously. A read failure is
+     * a cache miss, never a failure: the route simply has no listing until one is fetched.
+     */
+    async hydrate() {
+        if (this.hydrated)
+            return;
+        this.hydrated = true;
+        if (this.live !== undefined || this.options.cachedListing === undefined)
+            return;
+        try {
+            const entries = this.adoptListing(await this.options.cachedListing());
+            if (entries !== undefined)
+                this.live = entries;
+        }
+        catch (error) {
+            this.options.onWarn?.(`cached model catalog unavailable (${errorChain(error)})`);
+        }
+    }
     providerInfo(provider) {
         return { id: provider, name: GROK_PROVIDER_NAME };
     }
@@ -464,6 +686,7 @@ export class GrokAdapter extends LlmAdapter {
         // must not appear in the picker, and Auto must not try it.
         if (await this.options.tokens.session() === undefined)
             return [];
+        await this.hydrate();
         await this.syncUserModels();
         const hidden = await this.hidden();
         // One row per model, always under the model's own id: the host validates every GUI
@@ -491,14 +714,18 @@ export class GrokAdapter extends LlmAdapter {
         }
     }
     async resolveModel(_provider, model) {
+        await this.hydrate();
         await this.syncUserModels();
         // A fast variant is not a catalog row of its own: it answers with its base model's
-        // metadata — the same 500k window, name and ladder the picker shows — while the id
+        // metadata — the same window, name and ladder the picker shows — while the id
         // stays the fast wire id the request must send.
         const pair = this.fastPairOf(model);
         const entry = findEntry(this.catalog(), model)
             ?? (pair === undefined ? undefined : findEntry(this.catalog(), pair.baseId));
         if (entry === undefined) {
+            // An unknown id is still dispatchable: the endpoint accepts the id it reports, and a
+            // model added after this build should not be refused. It gets the conservative
+            // defaults, described by the cold-start seed rather than by a guess.
             const template = findEntry(GROK_MODELS, 'grok-4.6');
             const reasoning = template === undefined ? undefined : reasoningInfo(template);
             return {
@@ -567,45 +794,25 @@ export class GrokAdapter extends LlmAdapter {
         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.
+     * The catalog to present: the models both of the endpoint's listings named, in the
+     * public list's own order, each with the metadata the listings stated.
+     *
+     * There is no shipped roster to fall back to. The listings are read once and cached
+     * (see {@link hydrate} and {@link fetchCatalog}), and that cached table is what the
+     * picker shows until the next read, so a model released, renamed or retired
+     * server-side is reflected without a plugin update or a request per refresh.
+     *
+     * {@link GROK_MODELS} is only the cold-start seed: it decides membership while neither
+     * listing has been read, and afterwards describes the fields the listings left silent.
+     * A live fact, a context window included, always wins over it.
      */
     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 (reasoning ladder, default effort). The
-        // curated context window is never narrowed by a live figure: the CLI catalog states
-        // 256k for `grok-4.7`, which serves 500k, and a live read may only widen what this
-        // build ships.
-        const seeded = GROK_MODELS.map((entry) => {
-            const meta = this.metadata.get(entry.id);
-            if (meta === undefined)
-                return entry;
-            return {
-                ...entry,
-                contextWindow: Math.max(entry.contextWindow, meta.contextWindow ?? 0),
-                ...meta.reasoningEfforts === undefined ? {} : { reasoningEfforts: meta.reasoningEfforts },
-                ...meta.defaultEffort === undefined ? {} : { defaultEffort: meta.defaultEffort },
-            };
+        return composeCatalog({
+            curated: GROK_MODELS,
+            ...this.live === undefined ? {} : { live: this.live },
+            fallbackContextWindow: GROK_CONTEXT_WINDOW,
+            liveDescription: GROK_LIVE_DESCRIPTION,
         });
-        return [...seeded, ...extra];
     }
     /** Re-read the ids the user added by hand. */
     async syncUserModels() {
@@ -633,13 +840,21 @@ export class GrokAdapter extends LlmAdapter {
             .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);
+    /**
+     * Adopt the ids a caller reports as the served set, without a listing.
+     *
+     * {@link fetchCatalog} already derived the entries from the rows it read, and the
+     * controller reports the union of every account's ids back here; the entries it
+     * recorded are kept, and an id no entry describes gets a conservative row described by
+     * the cold-start seed. An id the caller does not report is dropped: the reported set is
+     * the endpoint's whole answer.
+     *
+     * @param ids - model ids the caller reports.
+     */
+    discover(ids) {
+        const known = new Map((this.live ?? []).map((entry) => [entry.id, entry]));
+        this.live = ids.map((id) => known.get(id)
+            ?? liveEntry({ id }, GROK_MODELS, GROK_CONTEXT_WINDOW, GROK_LIVE_DESCRIPTION));
     }
     /** The fast/lightspeed variant wire id for a base model, when discovery reported one. */
     fastVariant(baseId) {
@@ -653,6 +868,16 @@ export class GrokAdapter extends LlmAdapter {
     imageModelId() {
         return this.imageModel;
     }
+    /**
+     * Whether this route has read a model listing yet.
+     *
+     * A variant is derived from the listing, so until one has been read "this model has no
+     * variant" and "the listing has not arrived" look identical from outside; a caller that
+     * asks once (the composer's quick-mode button) needs to tell them apart.
+     */
+    hasListing() {
+        return this.live !== undefined;
+    }
     /** The curated catalog, for the Settings page's model list. */
     catalogEntries() {
         return this.catalog();
@@ -662,8 +887,6 @@ export class GrokAdapter extends LlmAdapter {
         return this.shippedCatalog();
     }
     /** Build and send one request for one model. */
-    /** The default context variant per base model, set during discovery. */
-    defaultContext = new Map();
     /** Resolve a model id to the wire id the endpoint accepts (largest context). */
     resolveModelId(model) {
         return this.defaultContext.get(model) ?? model;
@@ -726,9 +949,18 @@ export class GrokAdapter extends LlmAdapter {
         };
     }
     /**
-     * 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.
+     * Read both of the endpoint's listings and adopt them as this route's catalog.
+     *
+     * This is the one place a model table is produced, and it is the endpoint's own answer:
+     * what the public list names is what the picker offers, and the account's CLI catalog
+     * states the capabilities and names the fast variants that list omits. The rows are also
+     * handed to {@link GrokAdapterOptions.saveListing}, so the next session starts from this
+     * table instead of asking again — the Settings "refresh models" action is what re-reads
+     * it, and a picker query never does.
+     *
+     * @param accessToken - bearer for the account.
+     * @param signal - optional cancellation.
+     * @returns the model ids now served, or undefined when the listing is unavailable.
      */
     async fetchCatalog(accessToken, signal) {
         if (!this.options.discovery)
@@ -743,56 +975,36 @@ export class GrokAdapter extends LlmAdapter {
                 // 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`);
+                    this.options.onWarn?.(`xAI model discovery failed (HTTP ${response.status}); keeping the last catalog`);
                 }
                 return undefined;
             }
             const payload = await response.json();
-            const allIds = (payload.data ?? [])
-                .map((entry) => entry.id)
-                .filter((id) => typeof id === 'string' && id.length > 0);
-            // Image models are not chat models; they are picked by an agent, not the picker.
-            this.imageModel = allIds.find((id) => isImageModel(id));
-            const rawIds = allIds.filter((id) => !NON_CHAT_ID.test(id));
-            // Fast/lightspeed variants ride with their base model: they share the base's
-            // visibility switch and are reached by a picker button, not a separate row.
-            // Context variants (@500k) also fold into the base; the largest context wins.
-            this.fastVariants.clear();
-            this.defaultContext.clear();
-            for (const id of rawIds) {
-                this.fastVariants.noteListed(id);
-            }
-            this.noteWireVariants(rawIds);
-            const ids = rawIds
-                .map((id) => {
-                if (isFastVariant(id))
-                    return this.fastVariants.pair(id) ?? baseModelOf(id);
-                const ctx = contextOf(id);
-                if (ctx !== undefined)
-                    return stripContext(id);
-                return id;
-            })
-                .filter((id, index, list) => list.indexOf(id) === index);
-            if (ids.length === 0) {
-                this.options.onWarn?.('xAI model discovery returned an empty catalog; using the built-in catalog');
+            const publicRows = Array.isArray(payload.data) ? payload.data : [];
+            const cliRows = await this.readCliCatalog(fetchFn, signal, accessToken);
+            const listing = { public: publicRows, cli: cliRows };
+            const entries = this.adoptListing(listing);
+            if (entries === undefined) {
+                this.options.onWarn?.('xAI model discovery returned no usable catalog; keeping the last catalog');
                 return undefined;
             }
-            const cli = await this.readCliCatalog(fetchFn, signal, accessToken);
-            for (const [id, meta] of cli.metadata)
-                this.metadata.set(id, meta);
-            // The account's own CLI catalog is the only surface that names a fast variant:
-            // the public `/models` list omits `grok-4.7-build-fast` entirely. Its ids fold
-            // into the same base rows, and are never added as picker rows of their own.
-            for (const id of cli.ids) {
-                this.fastVariants.noteListed(id);
+            this.live = entries;
+            // The cached table is the endpoint's answer, kept so the next session does not ask
+            // again. A cache failure never fails the read that produced it.
+            if (this.options.saveListing !== undefined) {
+                try {
+                    await this.options.saveListing(listing);
+                }
+                catch (error) {
+                    this.options.onWarn?.(`model catalog cache write failed (${errorChain(error)})`);
+                }
             }
-            this.noteWireVariants(cli.ids);
-            return ids;
+            return entries.map((entry) => entry.id);
         }
         catch (error) {
             if (signal?.aborted === true)
                 return undefined;
-            this.options.onWarn?.(`xAI model discovery failed; using the built-in catalog (${errorChain(error)})`);
+            this.options.onWarn?.(`xAI model discovery failed; keeping the last catalog (${errorChain(error)})`);
             return undefined;
         }
     }
@@ -818,57 +1030,34 @@ export class GrokAdapter extends LlmAdapter {
         }
     }
     /**
-     * Read per-model capabilities from the CLI catalog; failures are silent.
+     * Read the account's CLI catalog; a failure is an empty listing, not an error.
      *
      * The catalog answers only for the signed-in account's own bearer — an anonymous
-     * request is refused — and it, unlike the public `/models` list, names the account's
-     * fast variant.
+     * request is refused — and it, unlike the public `/models` list, states per-model
+     * context windows and reasoning ladders and names the account's fast variant. The rows
+     * are returned verbatim so both the fresh catalog and the cached payload are derived
+     * from the same parse.
      *
      * @param fetchFn - fetch implementation.
      * @param signal - caller cancellation.
      * @param accessToken - the account's bearer.
-     * @returns the capability metadata and every id the catalog named.
+     * @returns the decoded rows, or an empty list when the catalog is unavailable.
      */
     async readCliCatalog(fetchFn, signal, accessToken) {
-        const result = new Map();
-        const ids = [];
         try {
             const response = await fetchFn(GROK_CLI_MODELS_URL, {
                 headers: attributedHeaders({ 'authorization': `Bearer ${accessToken}` }),
                 ...signal === undefined ? {} : { signal },
             });
             if (!response.ok)
-                return { metadata: result, ids };
+                return [];
             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;
-                ids.push(id);
-                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 },
-                });
-            }
+            return Array.isArray(payload.data) ? payload.data : [];
         }
         catch {
             // Capability metadata is a bonus; the id list is what matters.
+            return [];
         }
-        return { metadata: result, ids };
     }
 }
 /**
@@ -960,8 +1149,13 @@ export function createGrokProvider(options) {
             const read = await readGrokUsage({ accessToken: token.accessToken, fetchFn: options.discoveryFetchFn ?? proxiedFetch });
             return read === undefined ? [] : read.windows;
         },
+        ...options.cachedListing === undefined ? {} : { cachedListing: options.cachedListing },
+        ...options.saveListing === undefined ? {} : { saveListing: options.saveListing },
         ...options.discoveryFetchFn === undefined ? {} : { fetchFn: options.discoveryFetchFn },
     });
+    // Read the cached table now rather than at the first picker query: the Settings page
+    // reads the catalog synchronously, so a request-free start must already have it.
+    void adapter.hydrate().catch(() => undefined);
     const spec = {
         id: GROK_PROVIDER_ID,
         displayName: GROK_PROVIDER_NAME,
@@ -1009,12 +1203,19 @@ export function createGrokProvider(options) {
         removeModel: (id) => controller.removeModel(id),
         usage: (force) => controller.usage(force),
         reload: () => controller.reload(),
-        modelVariants: (id) => {
+        modelVariants: async (id) => {
+            // A variant is known only once the route has read its listing, whose rows name it.
+            // The composer asks exactly once, so the read is awaited here: "no fast variant"
+            // must mean the route really has none, not that its table was still loading.
+            await adapter.hydrate();
             const pair = adapter.fastPairOf(id);
             const image = adapter.imageModelId();
             return {
                 ...pair === undefined ? {} : { fast: pair.wireId, fastBase: pair.baseId, fastRung: fastWordOf(pair.wireId) },
                 ...image === undefined ? {} : { image },
+                // Nothing read yet: the answer above is provisional, and the caller is told so
+                // rather than being left to read silence as "this model has no variant".
+                ...adapter.hasListing() ? {} : { pending: true },
             };
         },
     };

package/lib/providers/kimi-provider.d.ts

@@ -26,6 +26,16 @@ export interface KimiProviderOptions {
     defaultModel?: string;
     /** Extra model ids published without shipped metadata. */
     extraModels?: readonly string[];
+    /**
+     * The endpoint's last live payload, from this plugin's cache.
+     *
+     * The cached table is what the picker shows before any request: the endpoint's own
+     * answer from the last read, so a release does not need a plugin update and a refresh
+     * does not need a request.
+     */
+    cachedListing?: () => Promise<unknown>;
+    /** Record what a live listing just produced, replacing the cached table. */
+    saveListing?: (payload: unknown) => Promise<void>;
     /** Shared model-visibility preferences. */
     preferences: ModelPreferences;
     /** Resolve the attachment service per request. */