dsh-plugin-subscription-oauth 0.16.3 → 0.17.1

package/lib/providers/ark.js

@@ -11,7 +11,10 @@
  *   malformed one is told so (`401 The API key format is incorrect`). So the
  *   credential is a UUID key, sent as a plain bearer — no request signing.
  * - `/api/coding/v3` is documented by the official CLI as "OpenTOP + CodingPlan
- *   API", and the catalogue below is the plan's roster.
+ *   API", and its `/models` listing — read once and kept in this plugin's cache, see
+ *   `hydrate` and `fetchCatalog` — is the roster this route publishes. Nothing in this
+ *   module decides which models the plan serves, so one released, renamed or retired
+ *   server-side reaches the picker without a plugin update.
  *
  * @module dsh-plugin-subscription-oauth/providers/ark
  */
@@ -20,10 +23,10 @@ import { REAUTH_REQUIRED, ProviderError } from '../errors.js';
 import { finiteInstant, nonEmpty } from '../auth/store.js';
 import { callArkControl, parseArkFreeUsage, parseArkPlanUsage } from '../auth/ark-control.js';
 import { proxiedFetch } from '../http.js';
-import { findEntry, resolveCatalog } from './catalog.js';
+import { composeCatalog, fallbackEntry, findEntry, liveEntry, liveModelFacts, resolveCatalog } from './catalog.js';
 import { streamProviderResponses, accountPoolHooks } from './responses-stream.js';
 import { toResponsesInput, toResponsesTools } from '../translate/responses.js';
-import { isImageModel } from './grok.js';
+import { baseModelOf, FastVariantIndex, isFastVariant, isImageModel } from './grok.js';
 /** Model ids that are clearly not chat models. */
 const NON_CHAT_ID = /(?:^|[-_/])(?:image|video|imagine|embed|embedding|whisper|tts|vision-only)/i;
 /** Provider route this module serves. */
@@ -43,23 +46,12 @@ export const ARK_DEFAULT_MODEL = 'ark-code-latest';
 /**
  * Context capacity advertised for the plan's models.
  *
- * The Coding Plan is a curated, text-first roster and states no window per model;
- * discovery refines this where the endpoint reports one.
+ * The plan states no window in this build; the endpoint's own listing supplies one
+ * where it names a model, and discovery refines this where it does not.
  */
 export const ARK_CONTEXT_WINDOW = 262_144;
 /** Output budget used when the caller sets no cap. */
 export const ARK_DEFAULT_MAX_TOKENS = 32_000;
-/** The plan's model roster, as the reference registry records it. */
-export const ARK_MODELS = [
-    { id: 'ark-code-latest', name: 'Ark Code (latest)', description: 'Plan alias for the current coding model', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
-    { id: 'doubao-seed-2.0-code', name: 'Doubao Seed 2.0 Code', description: 'Coding-tuned Doubao', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
-    { id: 'deepseek-v4-flash', name: 'DeepSeek V4 Flash', description: 'Fast DeepSeek', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
-    { id: 'glm-5.3', name: 'GLM-5.3', description: 'Zhipu flagship', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
-    { id: 'glm-5.3-flash', name: 'GLM-5.3 Flash', description: 'Fast GLM, reads images', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text', 'image'] },
-    { id: 'glm-5.2', name: 'GLM-5.2', description: 'Previous Zhipu flagship', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
-    { id: 'kimi-k2.6', name: 'Kimi K2.6', description: 'Moonshot model on Ark', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
-    { id: 'minimax-m3', name: 'MiniMax M3', description: 'MiniMax model on Ark', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text', 'image'] },
-];
 /**
  * Coerce one decoded credential entry into an Ark session.
  *
@@ -108,20 +100,107 @@ function stsFromSession(value) {
     }
     return { accessKeyId, secretAccessKey, sessionToken, expiresAt };
 }
-/** An entry for an id this build ships no metadata for. */
-function extraEntry(id) {
-    return { id, name: id, contextWindow: ARK_CONTEXT_WINDOW };
+/**
+ * The rows of one cached listing.
+ *
+ * The cache holds the rows this plugin stored; a payload written as the endpoint's own
+ * envelope is read too, so a differently shaped cache cannot silently empty the picker.
+ *
+ * @param payload - whatever `cachedListing` returned.
+ * @returns the rows to adopt, or an empty list when the payload names none.
+ */
+function listingRows(payload) {
+    if (Array.isArray(payload))
+        return payload;
+    const data = typeof payload === 'object' && payload !== null
+        ? payload.data
+        : undefined;
+    return Array.isArray(data) ? data : [];
 }
 /** The adapter behind the `ark` route. */
 export class ArkAdapter extends LlmAdapter {
     options;
+    /**
+     * The catalog this route serves: entries derived from the endpoint's own listing,
+     * either the one just read or the one the cache kept from the last read.
+     *
+     * Undefined means neither source has produced a listing yet, so only the configured
+     * default model is offered until one does.
+     */
     live;
-    /** Image-generation model id, when discovery reported one. */
+    /** Whether the cached listing has been read; it is read at most once per session. */
+    hydrated = false;
+    /** Image-generation model id, when the listing reported one. */
     imageModel;
+    /**
+     * Fast-variant wire id per picker row.
+     *
+     * Derived from the listing rather than a curated alias map: a row whose name is a
+     * listed model plus the provider's own fast word rides that row instead of becoming
+     * one of its own.
+     */
+    fastVariants = new FastVariantIndex();
     constructor(options) {
         super();
         this.options = options;
     }
+    /**
+     * Adopt the rows of one live listing as this route's catalog.
+     *
+     * Everything the picker shows is derived here from the endpoint's own answer: the
+     * rows that become picker entries and the fast variant that pairs with each row.
+     * Nothing about which models exist, or what each one is, is decided by this build.
+     *
+     * @param rows - decoded rows of the endpoint's listing, in the endpoint's order.
+     * @returns the entries to publish, in picker order.
+     */
+    adoptListing(rows) {
+        const facts = rows
+            .map((row) => liveModelFacts(row))
+            .filter((fact) => fact !== undefined);
+        // Image models are never picker rows: they are agent-called, always on.
+        this.imageModel = facts.find((fact) => isImageModel(fact.id))?.id;
+        this.fastVariants.clear();
+        for (const fact of facts)
+            this.fastVariants.noteListed(fact.id);
+        for (const fact of facts) {
+            const base = this.fastVariants.pair(fact.id);
+            this.fastVariants.note(fact.id, () => base ?? baseModelOf(fact.id));
+        }
+        // Fold a variant onto its row and drop the ids that are not chat models, keeping the
+        // endpoint's order. A row's own facts describe the row; a variant's describe the
+        // variant, so a row that is also listed is never overwritten by its variant.
+        const byId = new Map();
+        for (const fact of facts) {
+            if (NON_CHAT_ID.test(fact.id))
+                continue;
+            const id = isFastVariant(fact.id) ? this.fastVariants.pair(fact.id) ?? baseModelOf(fact.id) : fact.id;
+            if (id === fact.id || !byId.has(id))
+                byId.set(id, { ...fact, id });
+        }
+        return [...byId.values()].map((fact) => liveEntry(fact, [], ARK_CONTEXT_WINDOW, 'Reported by the Ark model list'));
+    }
+    /**
+     * Read the cached listing, once, so the picker works without asking the endpoint.
+     *
+     * Called before the first catalog query. 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 rows = listingRows(await this.options.cachedListing());
+            if (rows.length > 0)
+                this.live = this.adoptListing(rows);
+        }
+        catch (error) {
+            this.options.onWarn?.(`cached model catalog unavailable (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
     providerInfo(provider) {
         return { id: provider, name: ARK_PROVIDER_NAME };
     }
@@ -133,6 +212,7 @@ export class ArkAdapter 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();
         const hidden = await this.hidden();
         // Image models are never picker rows: they are agent-called, always on.
         const imageless = this.catalog().filter((entry) => !isImageModel(entry.id));
@@ -148,10 +228,21 @@ export class ArkAdapter extends LlmAdapter {
     imageModelId() {
         return this.imageModel;
     }
+    /**
+     * Whether this route has read a model listing yet.
+     *
+     * The image model is a row of the listing, so until one has been read "there is no image
+     * model" and "the listing has not arrived" look identical from outside; a caller that asks
+     * once needs to tell them apart.
+     */
+    hasListing() {
+        return this.live !== undefined;
+    }
     async resolveModel(_provider, model) {
+        await this.hydrate();
         const entry = findEntry(this.catalog(), model);
         if (entry === undefined) {
-            const template = findEntry(this.catalog(), ARK_DEFAULT_MODEL) ?? this.catalog()[0];
+            const template = findEntry(this.catalog(), this.defaultModel()) ?? this.catalog()[0];
             return {
                 provider: ARK_PROVIDER_ID,
                 id: model,
@@ -200,19 +291,30 @@ export class ArkAdapter extends LlmAdapter {
     catalog() {
         return [...this.shippedCatalog(), ...this.addedEntries()];
     }
+    /**
+     * The catalog to present: the models the endpoint's listing named, in its own order,
+     * each with the metadata that listing stated, then the configured extras.
+     *
+     * There is no shipped roster. A listing is 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. Only the configured default is always offered, because the picker
+     * preselects it.
+     */
     shippedCatalog() {
-        const shipped = this.options.extraModels === undefined
-            ? [...ARK_MODELS]
-            : [...ARK_MODELS, ...this.options.extraModels.map(extraEntry)];
-        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;
+        return composeCatalog({
+            curated: [],
+            ...this.live === undefined ? {} : { live: this.live },
+            ...this.options.extraModels === undefined ? {} : { extra: this.options.extraModels },
+            defaultModel: this.defaultModel(),
+            fallbackContextWindow: ARK_CONTEXT_WINDOW,
+            liveDescription: 'Reported by the Ark model list',
+            extraDescription: 'Extra model from the plugin configuration',
+        });
+    }
+    /** The model the picker preselects, from configuration. */
+    defaultModel() {
+        return this.options.defaultModel ?? ARK_DEFAULT_MODEL;
     }
     addedEntries() {
         const own = this.shippedCatalog();
@@ -221,7 +323,7 @@ export class ArkAdapter extends LlmAdapter {
             return [];
         return (Array.isArray(added) ? added : [])
             .filter((id) => findEntry(own, id) === undefined)
-            .map(extraEntry);
+            .map((id) => fallbackEntry(id, 'Added by hand in Settings', ARK_CONTEXT_WINDOW));
     }
     async hidden() {
         if (this.options.hiddenModels === undefined)
@@ -233,15 +335,34 @@ export class ArkAdapter extends LlmAdapter {
             return new Set();
         }
     }
-    /** Adopt the endpoint's live catalog. */
+    /**
+     * 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 those same ids back here; the entries it recorded are kept. A
+     * caller that only has ids (a test, another discovery path) gets conservative entries
+     * for them.
+     *
+     * @param ids - model ids the caller reports.
+     */
     discover(ids) {
-        this.live = [...ids];
+        const known = new Map((this.live ?? []).map((entry) => [entry.id, entry]));
+        this.live = ids.map((id) => known.get(id)
+            ?? liveEntry({ id }, [], ARK_CONTEXT_WINDOW, 'Reported by the Ark model list'));
     }
     /**
-     * Read the plan's live model list.
+     * Read the plan's live model list and adopt it as this route's catalog.
      *
-     * The Coding Plan answers the OpenAI models shape on its own base; an endpoint
-     * that does not serve it leaves the shipped roster in place.
+     * The Coding Plan answers the OpenAI models shape on its own base, so the rows are
+     * parsed exactly as the other routes parse theirs: what the listing names is what the
+     * picker offers, with the display name, window, modalities and ladder it states. The
+     * rows are also handed to {@link ArkAdapterOptions.saveListing}, so the next session
+     * starts from this table instead of asking again — the Settings "refresh models"
+     * action is what re-reads it.
+     *
+     * @param apiKey - bearer for the account.
+     * @param signal - optional cancellation.
+     * @returns the model ids now served, or undefined when the listing is unavailable.
      */
     async fetchCatalog(apiKey, signal) {
         if (!this.options.discovery)
@@ -253,23 +374,40 @@ export class ArkAdapter extends LlmAdapter {
                 ...signal === undefined ? {} : { signal },
             });
             if (!response.ok) {
-                this.options.onWarn?.(`Ark model list unavailable (HTTP ${response.status})`);
+                this.options.onWarn?.(`Ark model list unavailable (HTTP ${response.status}); keeping the last catalog`);
+                return undefined;
+            }
+            const payload = await response.json();
+            const rows = Array.isArray(payload.data) ? payload.data : [];
+            const entries = this.adoptListing(rows);
+            if (entries.length === 0) {
+                this.options.onWarn?.('Ark model discovery returned an empty catalog; keeping the last catalog');
                 return undefined;
             }
-            const body = await response.json();
-            const allIds = (body.data ?? [])
-                .map((entry) => (typeof entry?.id === 'string' ? entry.id.trim() : ''))
-                .filter((id) => id !== '');
-            // Image models are never picker rows: they are agent-called, always on.
-            this.imageModel = allIds.find((id) => isImageModel(id));
-            const ids = allIds.filter((id) => !NON_CHAT_ID.test(id));
-            return ids.length === 0 ? undefined : ids;
+            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.
+            await this.saveListing(rows);
+            return entries.map((entry) => entry.id);
         }
         catch (error) {
+            if (signal?.aborted === true)
+                return undefined;
             this.options.onWarn?.(`Ark model list unavailable (${error instanceof Error ? error.message : String(error)})`);
             return undefined;
         }
     }
+    /** Persist one live listing, reporting a cache failure without failing the read. */
+    async saveListing(rows) {
+        if (this.options.saveListing === undefined)
+            return;
+        try {
+            await this.options.saveListing(rows);
+        }
+        catch (error) {
+            this.options.onWarn?.(`model catalog cache write failed (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
     /** Send one streaming request over the Responses wire. */
     async request(options, model, apiKey, signal) {
         const resolveImage = this.imageResolver(signal);

package/lib/providers/catalog.d.ts

@@ -54,6 +54,98 @@ export interface ResolvedCatalog {
     /** Every entry in catalog order, hidden ids included (the Settings list). */
     ranked: CatalogEntry[];
 }
+/**
+ * One model as a live listing stated it.
+ *
+ * Every field but the id is optional, and an absent field means the listing was
+ * silent rather than that the model lacks the capability: a row states what it
+ * states, and a curated entry fills the gaps.
+ */
+export interface LiveModelFacts {
+    readonly id: string;
+    readonly name?: string | undefined;
+    readonly description?: string | undefined;
+    readonly contextWindow?: number | undefined;
+    readonly inputModalities?: readonly ModelModality[] | undefined;
+    readonly reasoningEfforts?: readonly string[] | undefined;
+    readonly defaultEffort?: string | undefined;
+}
+/**
+ * Read the facts one live listing row states.
+ *
+ * The field names are the ones these providers actually use, including Kimi's
+ * `display_name`/`context_length`/`think_efforts` and the OpenAI-compatible
+ * `context_window`/`name` spellings; anything unrecognized is left absent rather than
+ * guessed, so a curated entry can still describe the model.
+ *
+ * @param row - one decoded row of a `/models` payload.
+ * @returns the facts, or undefined when the row names no model.
+ */
+export declare function liveModelFacts(row: unknown): LiveModelFacts | undefined;
+/**
+ * The entry to publish for one id the endpoint served.
+ *
+ * What the endpoint stated wins; the curated table fills only what the listing was
+ * silent about, so a live figure — the window a model actually serves today — is
+ * never overridden by a shipped guess, and a retired figure never survives a live
+ * read that contradicts it. A route whose ids are stable aliases the service re-points
+ * per release keeps its own labels instead (see the kimi route's alias labels).
+ *
+ * @param facts - what the listing stated for this id.
+ * @param curated - the curated metadata table.
+ * @param fallbackContextWindow - window to state when neither source names one.
+ * @param description - picker description when neither source states one.
+ * @returns the merged entry.
+ */
+export declare function liveEntry(facts: LiveModelFacts, curated: readonly CatalogEntry[], fallbackContextWindow: number, description: string): CatalogEntry;
+/**
+ * How one provider's catalog is composed from its curated table and the entries the
+ * endpoint itself reported.
+ *
+ * The endpoint decides membership. A curated table is metadata, not a roster: the ids
+ * in it describe what the build knows about a model's name, window and ladder, and it
+ * is the membership only while no live list has been read. That is what lets a model
+ * released or retired server-side reach the picker without a plugin update, which a
+ * roster can never do.
+ */
+export interface CatalogPlan {
+    /** Curated entries, in curated order; metadata first, fallback membership second. */
+    readonly curated: readonly CatalogEntry[];
+    /**
+     * Entries the endpoint reported, in its own order.
+     *
+     * Undefined means discovery has not run (or failed), so the curated table decides
+     * membership and the picker is never empty.
+     */
+    readonly live?: readonly CatalogEntry[] | undefined;
+    /** Ids the plugin configuration adds, on top of the membership. */
+    readonly extra?: readonly string[] | undefined;
+    /** The model the picker preselects, and therefore always offers. */
+    readonly defaultModel?: string | undefined;
+    /** Context advertised for an id no curated entry describes. */
+    readonly fallbackContextWindow: number;
+    /** Description shown for a live id no curated entry describes. */
+    readonly liveDescription?: string | undefined;
+    /** Description shown for a configured id no curated entry describes. */
+    readonly extraDescription?: string | undefined;
+    /** Description shown for the default model when no curated entry describes it. */
+    readonly defaultDescription?: string | undefined;
+}
+/**
+ * Compose one provider's published catalog.
+ *
+ * The membership is the live entries in the endpoint's own order when a listing has
+ * been read, and the curated order otherwise. The configured default comes first —
+ * the picker preselects it, so it must be selectable — and configured extras last.
+ * Metadata always comes from the source that described the id: a live row is never
+ * shadowed by the curated table or by the default seed, so what the endpoint states
+ * about a model is what the picker shows.
+ *
+ * @param plan - curated metadata, the live membership, and the fallbacks.
+ * @param refine - widens an entry with provider-side metadata, when the provider has it.
+ * @returns the entries to publish, in picker order.
+ */
+export declare function composeCatalog(plan: CatalogPlan, refine?: (entry: CatalogEntry) => CatalogEntry): CatalogEntry[];
 /**
  * Apply the user's model order and visibility to one provider's catalog.
  *

package/lib/providers/catalog.js

@@ -42,6 +42,197 @@ export function fallbackEntry(id, description, contextWindow) {
         defaultEffort: 'max',
     };
 }
+/** Read a non-empty string field. */
+function stringField(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/** Read a positive integer field. */
+function numberField(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0)
+        return Math.floor(value);
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return Math.floor(parsed);
+    }
+    return undefined;
+}
+/**
+ * The input modalities a listing states, in the harness vocabulary.
+ *
+ * Listings name modalities the harness has no word for (`video`, `audio`); those are
+ * dropped rather than smuggled through the type, so a capability is advertised only
+ * where the harness can act on it.
+ */
+function modalitiesOf(row) {
+    const stated = [];
+    const modalities = row['modalities'];
+    if (typeof modalities === 'object' && modalities !== null) {
+        const input = modalities['input'];
+        if (Array.isArray(input))
+            stated.push(...input);
+    }
+    for (const [field, modality] of [['supports_image_in', 'image'], ['supports_image_input', 'image']]) {
+        if (row[field] === true)
+            stated.push(modality);
+    }
+    if (stated.length === 0)
+        return undefined;
+    const out = [];
+    for (const value of stated) {
+        if (value === 'text' && !out.includes('text'))
+            out.push('text');
+        if (value === 'image' && !out.includes('image'))
+            out.push('image');
+    }
+    return out.length === 0 ? undefined : out;
+}
+/** The reasoning ladder a listing states, from either of the shapes these APIs use. */
+function effortsOf(row) {
+    const think = row['think_efforts'];
+    if (typeof think === 'object' && think !== null) {
+        const record = think;
+        const valid = Array.isArray(record['valid_efforts'])
+            ? record['valid_efforts'].filter((effort) => typeof effort === 'string' && effort !== '')
+            : [];
+        const fallback = stringField(record['default_effort']);
+        return {
+            ...valid.length === 0 ? {} : { efforts: valid },
+            ...fallback === undefined ? {} : { defaultEffort: fallback },
+        };
+    }
+    const reasoning = row['reasoning'];
+    if (typeof reasoning === 'object' && reasoning !== null) {
+        const effort = reasoning['effort'];
+        if (typeof effort === 'object' && effort !== null) {
+            const record = effort;
+            const valid = Array.isArray(record['valid'])
+                ? record['valid'].filter((value) => typeof value === 'string' && value !== '')
+                : [];
+            const fallback = stringField(record['default']);
+            return {
+                ...valid.length === 0 ? {} : { efforts: valid },
+                ...fallback === undefined ? {} : { defaultEffort: fallback },
+            };
+        }
+    }
+    return {};
+}
+/**
+ * Read the facts one live listing row states.
+ *
+ * The field names are the ones these providers actually use, including Kimi's
+ * `display_name`/`context_length`/`think_efforts` and the OpenAI-compatible
+ * `context_window`/`name` spellings; anything unrecognized is left absent rather than
+ * guessed, so a curated entry can still describe the model.
+ *
+ * @param row - one decoded row of a `/models` payload.
+ * @returns the facts, or undefined when the row names no model.
+ */
+export function liveModelFacts(row) {
+    if (typeof row !== 'object' || row === null || Array.isArray(row))
+        return undefined;
+    const record = row;
+    const id = stringField(record['id']) ?? stringField(record['model']);
+    if (id === undefined)
+        return undefined;
+    const name = stringField(record['display_name']) ?? stringField(record['name']);
+    const description = stringField(record['description']);
+    const limit = record['limit'];
+    const contextWindow = numberField(record['context_length'])
+        ?? numberField(record['context_window'])
+        ?? numberField(record['max_context_length'])
+        ?? numberField(typeof limit === 'object' && limit !== null
+            ? limit['context']
+            : undefined);
+    const inputModalities = modalitiesOf(record);
+    const { efforts, defaultEffort } = effortsOf(record);
+    return {
+        id,
+        ...name === undefined ? {} : { name },
+        ...description === undefined ? {} : { description },
+        ...contextWindow === undefined ? {} : { contextWindow },
+        ...inputModalities === undefined ? {} : { inputModalities },
+        ...efforts === undefined ? {} : { reasoningEfforts: efforts },
+        ...defaultEffort === undefined ? {} : { defaultEffort },
+    };
+}
+/**
+ * The entry to publish for one id the endpoint served.
+ *
+ * What the endpoint stated wins; the curated table fills only what the listing was
+ * silent about, so a live figure — the window a model actually serves today — is
+ * never overridden by a shipped guess, and a retired figure never survives a live
+ * read that contradicts it. A route whose ids are stable aliases the service re-points
+ * per release keeps its own labels instead (see the kimi route's alias labels).
+ *
+ * @param facts - what the listing stated for this id.
+ * @param curated - the curated metadata table.
+ * @param fallbackContextWindow - window to state when neither source names one.
+ * @param description - picker description when neither source states one.
+ * @returns the merged entry.
+ */
+export function liveEntry(facts, curated, fallbackContextWindow, description) {
+    const known = findEntry(curated, facts.id);
+    const contextWindow = facts.contextWindow ?? known?.contextWindow ?? fallbackContextWindow;
+    const name = facts.name ?? known?.name ?? facts.id;
+    const summary = facts.description ?? known?.description ?? description;
+    const inputModalities = facts.inputModalities ?? known?.inputModalities;
+    const reasoningEfforts = facts.reasoningEfforts ?? known?.reasoningEfforts;
+    const defaultEffort = facts.defaultEffort ?? known?.defaultEffort;
+    return {
+        id: known?.id ?? facts.id,
+        name,
+        description: summary,
+        contextWindow,
+        ...inputModalities === undefined ? {} : { inputModalities },
+        ...reasoningEfforts === undefined ? {} : { reasoningEfforts },
+        ...defaultEffort === undefined ? {} : { defaultEffort },
+    };
+}
+/**
+ * Compose one provider's published catalog.
+ *
+ * The membership is the live entries in the endpoint's own order when a listing has
+ * been read, and the curated order otherwise. The configured default comes first —
+ * the picker preselects it, so it must be selectable — and configured extras last.
+ * Metadata always comes from the source that described the id: a live row is never
+ * shadowed by the curated table or by the default seed, so what the endpoint states
+ * about a model is what the picker shows.
+ *
+ * @param plan - curated metadata, the live membership, and the fallbacks.
+ * @param refine - widens an entry with provider-side metadata, when the provider has it.
+ * @returns the entries to publish, in picker order.
+ */
+export function composeCatalog(plan, refine = (entry) => entry) {
+    const membership = plan.live ?? plan.curated;
+    const described = new Map(membership.map((entry) => [entry.id, entry]));
+    const source = plan.live === undefined
+        ? 'Built-in catalog'
+        : plan.liveDescription ?? 'Reported by the provider model list';
+    const wanted = [];
+    if (plan.defaultModel !== undefined && plan.defaultModel !== '') {
+        wanted.push({ id: plan.defaultModel, description: plan.defaultDescription ?? 'Default model for this route' });
+    }
+    for (const entry of membership)
+        wanted.push({ id: entry.id, description: source });
+    for (const id of plan.extra ?? []) {
+        wanted.push({ id, description: plan.extraDescription ?? 'Extra model from the plugin configuration' });
+    }
+    const rows = [];
+    const seen = new Set();
+    for (const { id, description } of wanted) {
+        const canonical = findEntry(plan.curated, id)?.id ?? id;
+        if (seen.has(canonical))
+            continue;
+        seen.add(canonical);
+        const entry = described.get(canonical)
+            ?? findEntry(plan.curated, id)
+            ?? fallbackEntry(id, description, plan.fallbackContextWindow);
+        rows.push(refine({ ...entry, id: canonical }));
+    }
+    return rows;
+}
 /**
  * Apply the user's model order and visibility to one provider's catalog.
  *

package/lib/providers/common.d.ts

@@ -38,6 +38,20 @@ export declare function idleWatchdog(signal: AbortSignal | undefined, idleMs: nu
 export declare function httpLlmError(response: Response, label: string): Promise<LlmError>;
 /** Whether a failure means the stored credential no longer works. */
 export declare function isMissingOrInvalidCredential(error: unknown): boolean;
+/**
+ * The model id a provider's failure names as the one to use instead.
+ *
+ * A 401/403 is not always about the credential: a provider also answers it when the
+ * request names a model id the account does not serve — Kimi says `Your model id does
+ * not exist, recognized as other:k3[1m]. Please set model id as \`k3\``. That message
+ * is the endpoint's own answer to "which id should I have used", so it is worth acting
+ * on rather than reporting: refreshing a healthy token, or marking the account as
+ * needing a new login, would both be wrong answers to a model rename.
+ *
+ * @param message - the failure text.
+ * @returns the replacement id, or undefined when the failure is not about the model id.
+ */
+export declare function unknownModelReplacement(message: string): string | undefined;
 /**
  * Map a thrown transport failure onto a harness error, distinguishing caller
  * cancellation from an idle timeout from a genuine network fault.