dsh-plugin-subscription-oauth 0.16.2 → 0.17.0

package/lib/providers/kimi.d.ts

@@ -32,14 +32,6 @@ export interface KimiSession extends SessionBase {
  * @returns the session, or undefined when required fields are missing.
  */
 export declare function parseKimiSession(value: unknown): KimiSession | undefined;
-/**
- * Kimi Code's live coding catalog.
- *
- * `kimi-for-coding` is the stable subscription alias Moonshot re-points at each
- * coding release; `k3` is the current flagship, with the `[1m]` suffix selecting
- * its 1M-token window.
- */
-export declare const KIMI_MODELS: readonly KimiModelEntry[];
 /** Constructor dependencies for {@link KimiAdapter}. */
 export interface KimiAdapterOptions {
     /** Resolved Kimi Code API base (`<base>/responses`). */
@@ -73,6 +65,14 @@ export interface KimiAdapterOptions {
     readUsage?: (account: string) => Promise<readonly UsageWindow[]>;
     /** Extra model ids from the plugin configuration, appended to the catalog. */
     extraModels?: readonly string[];
+    /**
+     * Model this route preselects, and therefore always offers.
+     *
+     * Configuration rather than a shipped fact: a subscription that re-points its
+     * alias at a new release follows the config instead of this build's release
+     * cadence. Defaults to {@link KIMI_DEFAULT_MODEL}.
+     */
+    defaultModel?: string;
     /**
      * The user's model rank for this route, most preferred first.
      *
@@ -96,36 +96,78 @@ export interface KimiAdapterOptions {
      * endpoint is the authority on what it serves, not this build.
      */
     userModels?: () => Promise<readonly string[]>;
+    /**
+     * The payload of the endpoint's last live listing, as the cache kept it.
+     *
+     * Read once per session, before the first catalog query, so the picker offers real
+     * models without asking the endpoint anything. A route that fetched once and cached
+     * the answer has no reason to fetch again on every refresh; the Settings "refresh
+     * models" action is what re-reads it.
+     */
+    cachedListing?: () => Promise<unknown>;
+    /** Record what a live listing just produced, replacing the cached table. */
+    saveListing?: (payload: unknown) => Promise<void>;
 }
 /** Kimi Code adapter serving the `kimi` provider route. */
 export declare class KimiAdapter extends LlmAdapter {
     private readonly options;
-    /** Live catalog ids seen this session, used to accept renamed models. */
-    private discovered;
-    /** Image-generation model id, when discovery reported one. */
+    /**
+     * 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.
+     */
+    private live;
+    /** Whether the cached listing has been read; it is read at most once per session. */
+    private hydrated;
+    /** Image-generation model id, when the listing reported one. */
     private imageModel;
     /**
      * Fast-variant wire id per picker row, for the composer's quick-mode button.
      *
-     * Seeded from the curated aliases — `kimi-for-coding-highspeed` is one — so the button
-     * exists before any discovery run, and then updated from the live catalog, which is
-     * the authority on what this account actually serves.
+     * Derived from the listing: `kimi-for-coding-highspeed` is a row of its own there,
+     * and pairs with `kimi-for-coding` because its name is that of a listed model plus
+     * the provider's own fast word.
      */
     private readonly fastVariants;
     /** Ids the user added by hand, cached so the sync catalog can name them. */
     private userAddedIds;
+    /**
+     * Model ids the endpoint renamed during this session, and what each became.
+     *
+     * Learned from the endpoint's own refusal (`Please set model id as \`k3\``), so a
+     * spelling retired after this build shipped is repaired without a plugin update. The
+     * first turn pays one refused request; every later turn goes straight to the current id.
+     */
+    private readonly renamed;
     /** Tools already reported as flattened, so each is stated once. */
     private readonly flattenedTools;
     constructor(options: KimiAdapterOptions);
     /**
-     * Record the fast variants the curated catalog already names as aliases.
+     * 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, the fast variant that pairs with each row, and
+     * the image model that is called by an agent rather than chosen. Nothing about
+     * which models exist, or what each one is, is decided by this build.
+     *
+     * Fast variants ride with their base row instead of becoming rows of their own: they
+     * share the row's visibility switch and are reached by the composer's quick-mode
+     * button. A variant is recognized by its own name — the provider's fast word appended
+     * to a listed model's id — so no curated alias map is needed to pair them.
+     *
+     * @param rows - decoded rows of the endpoint's listing, in the endpoint's order.
+     * @returns the entries to publish, in picker order.
+     */
+    private adoptListing;
+    /**
+     * Read the cached listing, once, so the picker works without asking the endpoint.
      *
-     * The alias is the recognition: `kimi-for-coding-highspeed` is stated as an accepted
-     * id of `kimi-for-coding`, so the route can offer the quick-mode button without
-     * waiting for a live list that may never name it. A row a live catalog already paired
-     * keeps that pairing, so this only fills the gaps.
+     * 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.
      */
-    private seedCuratedFastVariants;
+    hydrate(): Promise<void>;
     /** The fast pair one picker id belongs to, from either side. */
     fastPairOf(id: string): {
         baseId: string;
@@ -157,19 +199,27 @@ export declare class KimiAdapter extends LlmAdapter {
      */
     private catalog;
     /**
-     * The catalog to present: the shipped entries in their curated order and with
-     * their curated metadata, then any configured extra id, then any live id this
-     * build does not know.
+     * 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.
      *
-     * The live list never removes a shipped entry: the endpoint serves variants
-     * such as `k3[1m]` that its own `/models` listing omits, so absence there is
-     * not evidence of retirement.
+     * There is no shipped roster to fall back to. 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 or a request per refresh.
      */
     private shippedCatalog;
-    /** Whether one shipped entry covers a live model id. */
-    private entryMatches;
-    /** Resolve a requested model id onto its catalog entry. */
+    /** Resolve a requested model id onto the entry the endpoint's listing described. */
     private entryFor;
+    /**
+     * The model one wire id names, when the endpoint has retired the spelling.
+     *
+     * Consulted only for an id the current listing does not serve, so an id the endpoint
+     * itself reports is always dispatched exactly as reported.
+     *
+     * @param model - the requested model id.
+     * @returns the current spelling, or undefined when the id is not a known retirement.
+     */
+    private repairModelId;
     /** Re-read the ids the user added by hand. */
     private syncUserModels;
     /**
@@ -179,9 +229,18 @@ export declare class KimiAdapter extends LlmAdapter {
      * the endpoint's own defaults are the honest description.
      */
     private addedEntries;
-    /** Record the live catalog for the picker; failures keep the shipped list. */
+    /**
+     * 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: readonly string[]): void;
-    /** The curated catalog, for the Settings page's model list. */
+    /** The catalog, for the Settings page's model list. */
     catalogEntries(): readonly KimiModelEntry[];
     /** What this route itself serves, without the ids added by hand. */
     ownCatalogEntries(): readonly KimiModelEntry[];
@@ -191,6 +250,19 @@ export declare class KimiAdapter extends LlmAdapter {
     private identity;
     /** Resolve image blocks through the attachment service, when it is present. */
     private imageResolver;
-    /** Read the live `/models` catalog, or undefined when unavailable. */
+    /**
+     * Read the endpoint's model listing and adopt it 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 listing names is what the picker offers, with the display name,
+     * context window, modalities and reasoning ladder the listing states. The rows are
+     * also handed to {@link KimiAdapterOptions.saveListing}, so the next session starts
+     * from this table instead of asking again — the Settings "refresh models" action is
+     * what re-reads it.
+     *
+     * @param accessToken - bearer for the account.
+     * @param signal - optional cancellation.
+     * @returns the model ids now served, or undefined when the listing is unavailable.
+     */
     fetchCatalog(accessToken: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
 }