dsh-plugin-subscription-oauth 0.16.2 → 0.17.0

package/lib/providers/grok.d.ts

@@ -48,11 +48,14 @@ export declare const GROK_DEFAULT_MAX_TOKENS = 32000;
 /** Refresh when the access token has less than this much life left. */
 export declare const GROK_PREEMPT_MS: number;
 /**
- * Curated catalog entries.
+ * 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 declare const GROK_MODELS: readonly CatalogEntry[];
 /** A stored Grok (X Premium) login. */
@@ -106,12 +109,6 @@ export declare function refreshGrokToken(input: {
     tokenEndpoint: string;
     refreshToken: string;
 }): Promise<GrokTokens>;
-/** One CLI-catalog entry's capability metadata. */
-interface GrokCliMetadata {
-    contextWindow?: number;
-    reasoningEfforts?: readonly string[];
-    defaultEffort?: string;
-}
 /** True when a model id names an image-generation model. */
 export declare function isImageModel(id: string): boolean;
 /** True when a model id names a fast/lightspeed variant of a base model. */
@@ -224,21 +221,66 @@ export interface GrokAdapterOptions {
     onCredentialRejected?: (account: string) => void;
     /** Read one account's metered windows, so the streamer can steer away from a spent one. */
     readUsage?: ((account: string) => Promise<readonly UsageWindow[]>) | undefined;
+    /**
+     * The endpoint's last live payload, from this plugin's cache.
+     *
+     * Read once per session, before the first catalog query, so the picker offers real
+     * models without asking the endpoint anything. The Settings "refresh models" action is
+     * what re-reads it; a picker query never does.
+     */
+    cachedListing?: () => Promise<unknown>;
+    /** Record what a live listing just produced, replacing the cached table. */
+    saveListing?: (payload: unknown) => Promise<void>;
 }
 /** Grok wire adapter: one instance serves the `grok` provider route. */
 export declare class GrokAdapter extends LlmAdapter {
     private readonly options;
-    /** Live model ids seen this session. */
-    private discovered;
+    /**
+     * 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.
+     */
+    private live;
+    /** Whether the cached listing has been read; it is read at most once per session. */
+    private hydrated;
     /** Capability metadata from the CLI catalog, keyed by model id. */
     private readonly metadata;
     /** Fast-variant wire id per base model, for the picker's quick-mode button. */
     private readonly fastVariants;
-    /** Image-generation model id, when discovery reported one. */
+    /** The context variant one base row dispatches to, so `@500k` is never typed by hand. */
+    private readonly defaultContext;
+    /** Image-generation model id, when the listing reported one. */
     private imageModel;
     /** Ids the user added by hand, cached so the sync catalog can name them. */
     private userAddedIds;
     constructor(options: GrokAdapterOptions);
+    /**
+     * 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.
+     */
+    private adoptListing;
+    /**
+     * 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.
+     */
+    hydrate(): Promise<void>;
     providerInfo(provider: string): LlmProviderInfo;
     providerRetryPolicy(): undefined;
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
@@ -252,9 +294,17 @@ export declare class GrokAdapter extends LlmAdapter {
      */
     private catalog;
     /**
-     * The catalog to present: curated seeds with their shipped metadata, then any
-     * live id this build does not know, enriched from the CLI catalog when it
-     * disclosed that model's context window or reasoning ladder.
+     * 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.
      */
     private shippedCatalog;
     /** Re-read the ids the user added by hand. */
@@ -266,8 +316,18 @@ export declare class GrokAdapter extends LlmAdapter {
      * the endpoint's own defaults are the honest description.
      */
     private addedEntries;
-    /** Record the live catalog for the picker. */
-    discover(ids: readonly string[], metadata?: ReadonlyMap<string, GrokCliMetadata>): void;
+    /**
+     * 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: readonly string[]): void;
     /** The fast/lightspeed variant wire id for a base model, when discovery reported one. */
     fastVariant(baseId: string): string | undefined;
     /** The fast pair one picker id belongs to, from either side. */
@@ -282,8 +342,6 @@ export declare class GrokAdapter extends LlmAdapter {
     /** What this route itself serves, without the ids added by hand. */
     ownCatalogEntries(): readonly CatalogEntry[];
     /** Build and send one request for one model. */
-    /** The default context variant per base model, set during discovery. */
-    private defaultContext;
     /** Resolve a model id to the wire id the endpoint accepts (largest context). */
     resolveModelId(model: string): string;
     /** Record one default-context mapping. */
@@ -292,9 +350,18 @@ export declare class GrokAdapter extends LlmAdapter {
     /** Resolve image blocks through the attachment service, when it is present. */
     private imageResolver;
     /**
-     * Read the live model list, and the CLI catalog's capability metadata.
-     * @param accessToken - bearer for the account's models.
-     * @returns the model ids, or undefined when discovery is off or unavailable.
+     * 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.
      */
     fetchCatalog(accessToken: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
     /**
@@ -304,16 +371,18 @@ export declare class GrokAdapter extends LlmAdapter {
      */
     private noteWireVariants;
     /**
-     * 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.
      */
     private readCliCatalog;
 }
@@ -338,6 +407,16 @@ export interface GrokProviderOptions {
     fetchFn?: FetchFn;
     /** Discovery fetch override, for tests. */
     discoveryFetchFn?: FetchFn;
+    /**
+     * 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>;
 }
 /**
  * Build the `grok` route: its adapter and its login/lifecycle controller.