dsh-plugin-subscription-oauth 0.16.3 → 0.17.0

package/README.dev.md

@@ -70,7 +70,7 @@ quota, which is read per subscription period and per model's free allowance.
 | --- | --- |
 | `ctx.llm` | the `kimi`, `grok`, `antigravity`, `glm` and `auto` provider routes (models, reasoning efforts, streaming) |
 | Settings | a **Subscriptions** section: one card per provider — sign in, sign out, default account, token refresh, plan quota, model catalog, manage dialog |
-| Model picker | each provider's own models, plus **`auto` as its own route** spanning them — Kimi ships `kimi-for-coding`, `k3`, `k3[1m]`, `k3-256k`; Grok seeds `grok-4.6`, `grok-4.5` and adds whatever its live catalog reports; Antigravity lists the agent-callable subset of what its endpoint reports (`fetchAvailableModels`), filtering out tabs, commit-message and transcription surfaces; GLM ships the `glm-5.3` family (`glm-5.3`, `glm-5.3-flash`, `glm-5.2`, `glm-5.1`, `glm-5`) and adds whatever its coding host lists |
+| Model picker | each provider's own models, plus **`auto` as its own route** spanning them. Membership comes from the provider's own model list, read once and cached as that route's table (`~/.dsh/plugins/kimi-oauth/model-catalog.json`), so the picker never spends a request and a release or retirement server-side needs no plugin update. Kimi serves `kimi-for-coding`, `k3` (1M) and `k3-256k`; Grok adds whatever its live catalog reports on top of `grok-4.6`/`grok-4.5`; Antigravity lists the agent-callable subset of what its endpoint reports (`fetchAvailableModels`), filtering out tabs, commit-message and transcription surfaces; GLM adds whatever its coding host lists on top of the `glm-5.3` family |
 
 Credentials live at `~/.dsh/plugins/kimi-oauth/auth.json` (mode `0600`,
 written atomically, one section per provider). The directory keeps the name this

package/README.md

@@ -13,12 +13,12 @@ Sign in once per provider from **Settings → Subscriptions** and that provider'
 
 | Provider | What you get | Sign-in |
 | --- | --- | --- |
-| **Kimi Code** | `kimi-for-coding`, `k3`, `k3[1m]`, `k3-256k` + live catalog | OAuth device flow (show code, confirm in browser) |
-| **Grok (X Premium)** | `grok-4.7`, `grok-4.6`, … + live catalog, **⚡ lightspeed** fast variant | Browser OAuth (auto-redirect) |
-| **Google Antigravity** | Claude Sonnet/Opus, Gemini Flash, GPT-OSS, with reasoning tiers | Google account OAuth |
-| **GLM (BigModel)** | `glm-5.3`, `glm-5.3-flash`, `glm-5.2`, `glm-5.1`, `glm-5` | ZCode browser sign-in (polled) |
-| **Volcengine Ark** | Ark coding models + live catalog | Volcengine SSO |
-| **Xiaomi MiMo** | MiMo Pro, MiMo Flash | Xiaomi account (QR / password) |
+| **Kimi Code** | `kimi-for-coding`, `k3` (1M), `k3-256k` — read from the endpoint's own model list | OAuth device flow (show code, confirm in browser) |
+| **Grok (X Premium)** | whatever the account's own model list reports (e.g. `grok-4.7`), **⚡ lightspeed** fast variant | Browser OAuth (auto-redirect) |
+| **Google Antigravity** | Claude Sonnet/Opus, Gemini Flash, GPT-OSS, with reasoning tiers — read from the account's own list | Google account OAuth |
+| **GLM (BigModel)** | whatever the coding host lists (e.g. `glm-5.3`, `glm-5.3-flash`) | ZCode browser sign-in (polled) |
+| **Volcengine Ark** | the plan's own coding models | Volcengine SSO |
+| **Xiaomi MiMo** | MiMo's own model list, with the app's two-model set as the fallback | Xiaomi account (QR / password) |
 | **WorkBuddy (国内版)** | Hy, GLM, Kimi, DeepSeek, MiniMax models | Browser OAuth (Tencent) |
 
 Every provider also feeds the **`auto`** route, which spans them all: pick `auto` and the harness walks your enabled models in order until one answers.
@@ -28,6 +28,7 @@ Every provider also feeds the **`auto`** route, which spans them all: pick `auto
 - **One sign-in per provider** — no API keys to find, paste, or rotate. The plugin runs the provider's own OAuth/device flow and keeps the token on disk (`~/.dsh/plugins/kimi-oauth/auth.json`, mode `0600`).
 - **Live plan usage** — the Settings card and the composer chip show each account's remaining quota (Kimi's 5-hour / weekly windows + credit, Grok's weekly credit, Antigravity's Gemini + Claude buckets, GLM/Ark/MiMo/WorkBuddy credits), with a meter and reset time.
 - **Model picker integration** — each provider's models appear in the session picker with context windows and reasoning tiers; hide or re-order them per provider.
+- **Catalogs come from the provider, not from this build** — every route reads its own model list once and caches it as the provider's table, so a model released, renamed or retired server-side shows up (or disappears) without a plugin update. Signing in and the Settings **refresh models** action are what re-read it; browsing the picker never spends a request.
 - **⚡ Fast / lightspeed variants** — for models that have one (e.g. Grok 4.7 → `grok-4.7-build-fast`), a bolt button beside the model selector switches to the fast variant; it reads as a reasoning rung so the base model always stays selectable.
 - **Cross-account pool** — sign in to several accounts on one provider; the plugin draws on the next account when one's allowance runs out.
 - **Auto fallback** — `auto` moves to the next enabled model when a provider refuses the preferred one (renamed, rate-limited, out of quota), and stops falling back once a stream has started.

package/README.zh.dev.md

@@ -56,7 +56,7 @@ Antigravity 的流程是 Google 的桌面 OAuth 客户端（`accounts.google.com
 | --- | --- |
 | `ctx.llm` | `kimi`、`grok`、`antigravity`、`glm` 和 `auto` 提供方路由（模型、推理强度、流式输出） |
 | Settings | 一个 **Subscriptions** 区域：每个提供方一张卡片——登录、退出登录、默认账户、令牌刷新、套餐配额、模型目录、管理对话框 |
-| 模型选择器 | 每个提供方自己的模型，外加**作为独立路由的 `auto`**，横跨它们——Kimi 提供 `kimi-for-coding`、`k3`、`k3[1m]`、`k3-256k`；Grok 内置 `grok-4.6`、`grok-4.5`，并加入其实时目录所报告的任何模型；Antigravity 列出其端点所报告内容（`fetchAvailableModels`）中可供 agent 调用的子集，过滤掉 tabs、commit-message 和 transcription 相关层面；GLM 提供 `glm-5.3` 系列（`glm-5.3`、`glm-5.3-flash`、`glm-5.2`、`glm-5.1`、`glm-5`），并加入其编码主机所列出的一切 |
+| 模型选择器 | 每个提供方自己的模型，外加**作为独立路由的 `auto`**，横跨它们。成员资格来自提供方自己的模型列表：每个路由只读取一次并缓存为该路由的目录（`~/.dsh/plugins/kimi-oauth/model-catalog.json`），因此选择器不会发出请求，服务端新增或下线模型也无需插件更新。Kimi 提供 `kimi-for-coding`、`k3`（1M）与 `k3-256k`；Grok 在 `grok-4.6`、`grok-4.5` 之上加入其实时目录所报告的任何模型；Antigravity 列出其端点所报告内容（`fetchAvailableModels`）中可供 agent 调用的子集，过滤掉 tabs、commit-message 和 transcription 相关层面；GLM 在 `glm-5.3` 系列之上加入其编码主机所列出的一切 |
 
 凭证存放在 `~/.dsh/plugins/kimi-oauth/auth.json`（模式 `0600`，原子写入，每个提供方
 一个区段）。该目录保留了本插件在只服务 Kimi Code 时所用的名称：它保存着**活跃的

package/README.zh.md

@@ -13,12 +13,12 @@
 
 | 服务 | 可用模型 | 登录方式 |
 | --- | --- | --- |
-| **Kimi Code** | `kimi-for-coding`、`k3`、`k3[1m]`、`k3-256k` + 实时目录 | OAuth 设备流（显示代码，浏览器确认） |
-| **Grok (X Premium)** | `grok-4.7`、`grok-4.6`… + 实时目录，**⚡ lightspeed** 快速变体 | 浏览器 OAuth（自动回调） |
-| **Google Antigravity** | Claude Sonnet/Opus、Gemini Flash、GPT-OSS，带推理档 | Google 账号 OAuth |
-| **GLM (BigModel)** | `glm-5.3`、`glm-5.3-flash`、`glm-5.2`、`glm-5.1`、`glm-5` | ZCode 浏览器登录（轮询） |
-| **Volcengine Ark** | Ark 编程模型 + 实时目录 | 火山引擎 SSO |
-| **Xiaomi MiMo** | MiMo Pro、MiMo Flash | 小米账号（扫码 / 密码） |
+| **Kimi Code** | `kimi-for-coding`、`k3`（1M）、`k3-256k` —— 直接来自端点自己的模型列表 | OAuth 设备流（显示代码，浏览器确认） |
+| **Grok (X Premium)** | 账号自己的模型列表所报告的一切（如 `grok-4.7`），**⚡ lightspeed** 快速变体 | 浏览器 OAuth（自动回调） |
+| **Google Antigravity** | Claude Sonnet/Opus、Gemini Flash、GPT-OSS，带推理档 —— 来自账号自己的列表 | Google 账号 OAuth |
+| **GLM (BigModel)** | 编码主机列出的一切（如 `glm-5.3`、`glm-5.3-flash`） | ZCode 浏览器登录（轮询） |
+| **Volcengine Ark** | 套餐自己的编程模型 | 火山引擎 SSO |
+| **Xiaomi MiMo** | MiMo 自己的模型列表，读取失败时回退到应用内置的两个模型 | 小米账号（扫码 / 密码） |
 | **WorkBuddy (国内版)** | Hy、GLM、Kimi、DeepSeek、MiniMax 模型 | 浏览器 OAuth（腾讯） |
 
 每个服务也会汇入 **`auto`** 路由，它横跨全部：选 `auto`，harness 会按顺序尝试你已启用的模型，直到有响应。
@@ -28,6 +28,7 @@
 - **每个服务登录一次** —— 无需找、贴、轮换 API Key。插件运行服务自己的 OAuth/设备流，令牌保存在磁盘（`~/.dsh/plugins/kimi-oauth/auth.json`，权限 `0600`）。
 - **实时套餐额度** —— 设置卡片和输入框 chip 显示每个账号的剩余额度（Kimi 的 5 小时 / 每周窗口 + 额度，Grok 每周额度，Antigravity 的 Gemini + Claude 分组，GLM/Ark/MiMo/WorkBuddy 的额度），带进度条和重置时间。
 - **模型选择器集成** —— 每个服务的模型带上下文窗口和推理档出现在选择器里；可按服务隐藏或排序。
+- **模型目录来自服务本身，而不是本插件** —— 每个路由只读取一次服务自己的模型列表，并把它缓存为该路由的目录，因此服务端新增、改名或下线的模型无需插件更新即可出现（或消失）。重新读取的时机是登录成功和设置页的**刷新模型**；浏览选择器不会发出任何请求。
 - **⚡ 快速 / lightspeed 变体** —— 对有快速变体的模型（如 Grok 4.7 → `grok-4.7-build-fast`），模型选择器旁的闪电按钮一键切换；它作为推理档实现，基础模型始终可选。
 - **多账号池** —— 一个服务可登录多个账号；某账号额度用尽时自动切到下一个。
 - **Auto 回退** —— `auto` 在首选模型被拒（改名、限流、额度尽）时改用下一个已启用模型，且流开始后不再回退。

package/lib/index.js

@@ -25,6 +25,7 @@ import { createArkProvider } from './providers/ark-provider.js';
 import { createMimoProvider } from './providers/mimo-provider.js';
 import { createWorkBuddyProvider } from './providers/workbuddy-provider.js';
 import { ModelPreferences } from './settings.js';
+import { ModelCatalogCache } from './providers/model-cache.js';
 /** Plugin id; also the name every effect label and log line is prefixed with. */
 export const name = 'dsh-plugin-subscription-oauth';
 /** The provider routes need the LLM runtime; everything else is optional. */
@@ -68,6 +69,10 @@ export function apply(ctx, config = {}) {
     const dataDir = dshHomePath(...KIMI_DATA_DIR);
     const credentialFile = path.join(dataDir, 'auth.json');
     const preferences = new ModelPreferences(path.join(dataDir, 'preferences.json'));
+    // The endpoint's own last answer per route. It is written whenever a route reads its
+    // live listing — at startup, after a login, and on the page's "refresh models" action
+    // — and read as the route's model table, so a picker query is never a request.
+    const catalogCache = new ModelCatalogCache(path.join(dataDir, 'model-catalog.json'));
     /** Registration handles, so a catalog change can re-announce one route. */
     const handles = new Map();
     const reannounce = (id) => { handles.get(id)?.replace([id]); };
@@ -84,6 +89,8 @@ export function apply(ctx, config = {}) {
                     streamIdleTimeoutMs,
                     ...config.defaultModel === undefined ? {} : { defaultModel: config.defaultModel },
                     ...config.extraModels === undefined ? {} : { extraModels: config.extraModels },
+                    cachedListing: () => catalogCache.read('kimi'),
+                    saveListing: (rows) => catalogCache.write('kimi', rows),
                     preferences,
                     // Resolved per request: the attachment service may start after this plugin.
                     resolveAttachments: () => ctx.get('attachments'),
@@ -98,6 +105,8 @@ export function apply(ctx, config = {}) {
                     discovery: config.discovery ?? true,
                     streamIdleTimeoutMs,
                     preferences,
+                    cachedListing: () => catalogCache.read('grok'),
+                    saveListing: (payload) => catalogCache.write('grok', payload),
                     resolveAttachments: () => ctx.get('attachments'),
                     onCatalogChanged: () => { reannounce('grok'); },
                     onWarn,
@@ -113,6 +122,8 @@ export function apply(ctx, config = {}) {
                     resolveAttachments: () => ctx.get('attachments'),
                     onCatalogChanged: () => { reannounce('antigravity'); },
                     onWarn,
+                    cachedListing: () => catalogCache.read('antigravity'),
+                    saveListing: (payload) => catalogCache.write('antigravity', payload),
                     fetchFn: proxiedFetch,
                 }));
                 break;
@@ -122,6 +133,8 @@ export function apply(ctx, config = {}) {
                     discovery: config.discovery ?? true,
                     streamIdleTimeoutMs,
                     preferences,
+                    cachedListing: () => catalogCache.read('glm'),
+                    saveListing: (payload) => catalogCache.write('glm', payload),
                     resolveAttachments: () => ctx.get('attachments'),
                     onCatalogChanged: () => { reannounce('glm'); },
                     onWarn,
@@ -134,6 +147,8 @@ export function apply(ctx, config = {}) {
                     discovery: config.discovery ?? true,
                     streamIdleTimeoutMs,
                     preferences,
+                    cachedListing: () => catalogCache.read('ark'),
+                    saveListing: (payload) => catalogCache.write('ark', payload),
                     resolveAttachments: () => ctx.get('attachments'),
                     onCatalogChanged: () => { reannounce('ark'); },
                     onWarn,
@@ -143,8 +158,11 @@ export function apply(ctx, config = {}) {
             case 'mimo':
                 routes.push(createMimoProvider({
                     credentialFile,
+                    discovery: config.discovery ?? true,
                     streamIdleTimeoutMs,
                     preferences,
+                    cachedListing: () => catalogCache.read('mimo'),
+                    saveListing: (payload) => catalogCache.write('mimo', payload),
                     resolveAttachments: () => ctx.get('attachments'),
                     onCatalogChanged: () => { reannounce('mimo'); },
                     onWarn,
@@ -154,8 +172,11 @@ export function apply(ctx, config = {}) {
             case 'workbuddy':
                 routes.push(createWorkBuddyProvider({
                     credentialFile,
+                    discovery: config.discovery ?? true,
                     streamIdleTimeoutMs,
                     preferences,
+                    cachedListing: () => catalogCache.read('workbuddy'),
+                    saveListing: (payload) => catalogCache.write('workbuddy', payload),
                     onCatalogChanged: () => { reannounce('workbuddy'); },
                     onWarn,
                     fetchFn: proxiedFetch,

package/lib/providers/antigravity.d.ts

@@ -195,6 +195,17 @@ export interface AntigravityAdapterOptions {
     modelOrder?: () => Promise<readonly string[]>;
     fetchFn?: FetchFn;
     onCredentialRejected?: (account: string) => void;
+    /**
+     * The endpoint's last live listing, 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. 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>;
 }
 /** Antigravity wire adapter serving the `antigravity` route. */
 export declare class AntigravityAdapter extends LlmAdapter {
@@ -203,6 +214,8 @@ export declare class AntigravityAdapter extends LlmAdapter {
     private discovered;
     /** Live catalog entries, so the Settings list matches what the account has. */
     private live;
+    /** Whether the cached listing has been read; it is read at most once per session. */
+    private hydrated;
     /** Per-model quota windows from the last catalog read. */
     private quotas;
     /** Ids the user added by hand, cached so the sync catalog can name them. */
@@ -213,12 +226,20 @@ export declare class AntigravityAdapter extends LlmAdapter {
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
     private hidden;
     /**
-     * The catalog the route serves: its own entries, then the ids the user added
-     * by hand. The two are built separately so the hand-added check can look at
-     * the shipped list without recursing.
+     * Read the cached listing, once, so the picker works without asking the endpoint.
+     *
+     * The cache is this route's last live catalog — the entries the endpoint reported, which
+     * is also what a fresh read produces — so adopting it is indistinguishable from having
+     * just fetched. A read failure is a cache miss, never a failure.
      */
+    hydrate(): Promise<void>;
+    /** Publish one listing as this route's catalog. */
+    private adopt;
+    /** The catalog the route serves: its own entries, then the ids the user added
+     * by hand. The two are built separately so the hand-added check can look at
+     * the shipped list without recursing. */
     private catalog;
-    /** Live entries when discovery has run, otherwise an empty catalog. */
+    /** The live entries: the cached listing until a fresh one replaces it. */
     private shippedCatalog;
     resolveModel(_provider: string, model: string): Promise<LlmResolvedModelInfo>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
@@ -332,6 +353,15 @@ export interface AntigravityProviderOptions {
     fetchFn?: FetchFn;
     /** Activate an eligible account when `loadCodeAssist` reports no project. */
     onboard?: boolean;
+    /**
+     * The endpoint's last live catalog, from this plugin's cache.
+     *
+     * This route has no curated list — what an account may use is plan-dependent — so the
+     * cache is what makes a cold start (or an unreachable endpoint) still show models.
+     */
+    cachedListing?: () => Promise<unknown>;
+    /** Record what a live listing just produced, replacing the cached table. */
+    saveListing?: (payload: unknown) => Promise<void>;
 }
 /**
  * Build the `antigravity` route: its adapter and its login/lifecycle controller.

package/lib/providers/antigravity.js

@@ -329,16 +329,6 @@ export async function fetchAntigravityModels(input) {
     if (typeof models !== 'object' || models === null) {
         throw new LlmError('Antigravity models endpoint returned no models object', 'MALFORMED_RESPONSE');
     }
-    // TEMP diagnostics: write the raw model-id list to a file so an over-eager filter is
-    // inspectable after a discovery run, since the node half's stdout is unreachable in
-    // the desktop shell.
-    try {
-        const { writeFileSync } = require('node:fs');
-        const { homedir } = require('node:os');
-        const { join } = require('node:path');
-        writeFileSync(join(homedir(), '.dsh', 'antigravity-raw-models.json'), JSON.stringify(Object.keys(models), null, 2), 'utf8');
-    }
-    catch { /* diagnostics never break parsing */ }
     // The response names far more than the agent may call; the filter keeps the
     // callable grouping and reports the per-model quota for the fallback path.
     const entries = parseAntigravityModels(payload);
@@ -365,6 +355,33 @@ function quotaWindow(scope, quota) {
         ...Number.isFinite(resetsAt) ? { resetsAt } : {},
     };
 }
+/** Whether one cached value is a usable catalog entry. */
+function isCachedEntry(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record['id'] === 'string' && record['id'] !== ''
+        && typeof record['name'] === 'string'
+        && typeof record['contextWindow'] === 'number' && Number.isFinite(record['contextWindow']);
+}
+/**
+ * Read a cached catalog payload.
+ *
+ * The route writes the entries themselves; a whole `{ entries: [...] }` document is
+ * accepted too, so a payload written in either shape cannot silently empty the picker.
+ * Anything unusable is dropped rather than trusted.
+ *
+ * @param payload - whatever the cache returned.
+ * @returns the usable entries, possibly none.
+ */
+function cachedEntries(payload) {
+    const rows = Array.isArray(payload)
+        ? payload
+        : typeof payload === 'object' && payload !== null && Array.isArray(payload.entries)
+            ? payload.entries
+            : [];
+    return rows.filter(isCachedEntry);
+}
 /** Antigravity wire adapter serving the `antigravity` route. */
 export class AntigravityAdapter extends LlmAdapter {
     options;
@@ -372,6 +389,8 @@ export class AntigravityAdapter extends LlmAdapter {
     discovered;
     /** Live catalog entries, so the Settings list matches what the account has. */
     live;
+    /** Whether the cached listing has been read; it is read at most once per session. */
+    hydrated = false;
     /** Per-model quota windows from the last catalog read. */
     quotas = new Map();
     /** Ids the user added by hand, cached so the sync catalog can name them. */
@@ -392,6 +411,7 @@ export class AntigravityAdapter 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();
         return resolveCatalog(this.catalog(), [], hidden).entries.map((entry) => ({
@@ -414,18 +434,44 @@ export class AntigravityAdapter extends LlmAdapter {
         }
     }
     /**
-     * The catalog the route serves: its own entries, then the ids the user added
-     * by hand. The two are built separately so the hand-added check can look at
-     * the shipped list without recursing.
+     * Read the cached listing, once, so the picker works without asking the endpoint.
+     *
+     * The cache is this route's last live catalog — the entries the endpoint reported, which
+     * is also what a fresh read produces — so adopting it is indistinguishable from having
+     * just fetched. A read failure is a cache miss, never a failure.
      */
+    async hydrate() {
+        if (this.hydrated)
+            return;
+        this.hydrated = true;
+        if (this.live !== undefined || this.options.cachedListing === undefined)
+            return;
+        try {
+            const entries = cachedEntries(await this.options.cachedListing());
+            if (entries.length > 0)
+                this.adopt(entries);
+        }
+        catch (error) {
+            this.options.onWarn?.(`cached model catalog unavailable (${errorChain(error)})`);
+        }
+    }
+    /** Publish one listing as this route's catalog. */
+    adopt(entries) {
+        this.live = entries;
+        this.discovered = entries.map((entry) => entry.id);
+    }
+    /** The catalog the route serves: its own entries, then the ids the user added
+     * by hand. The two are built separately so the hand-added check can look at
+     * the shipped list without recursing. */
     catalog() {
         return [...this.shippedCatalog(), ...this.addedEntries()];
     }
-    /** Live entries when discovery has run, otherwise an empty catalog. */
+    /** The live entries: the cached listing until a fresh one replaces it. */
     shippedCatalog() {
         return this.live ?? [];
     }
     async resolveModel(_provider, model) {
+        await this.hydrate();
         await this.syncUserModels();
         const entries = this.catalog();
         const entry = findEntry(entries, model);
@@ -591,7 +637,13 @@ export class AntigravityAdapter extends LlmAdapter {
         if (Date.now() < session.expiresAt) {
             return { account, accessToken: session.accessToken, expiresAt: session.expiresAt };
         }
-        return await this.options.tokens.resolve(account, true);
+        try {
+            const resolved = await this.options.tokens.resolve(account, true);
+            return resolved;
+        }
+        catch (error) {
+            throw error;
+        }
     }
     /** Translate an auth failure into the message a user can act on. */
     refreshHint(error) {
@@ -611,17 +663,23 @@ export class AntigravityAdapter extends LlmAdapter {
         const envelope = await toAntigravityRequest({ ...options, model }, projectId, options.system, this.imageResolver(signal), true);
         const fetchFn = this.options.fetchFn ?? proxiedFetch;
         const origin = this.options.baseUrl ?? ANTIGRAVITY_BASE_URL;
-        return fetchFn(`${origin}/v1internal:streamGenerateContent?alt=sse`, {
-            method: 'POST',
-            headers: attributedHeaders({
-                'authorization': `Bearer ${accessToken}`,
-                'accept': 'text/event-stream',
-                'content-type': 'application/json',
-                'user-agent': ANTIGRAVITY_USER_AGENT,
-            }),
-            body: JSON.stringify(envelope),
-            signal,
-        });
+        try {
+            const response = await fetchFn(`${origin}/v1internal:streamGenerateContent?alt=sse`, {
+                method: 'POST',
+                headers: attributedHeaders({
+                    'authorization': `Bearer ${accessToken}`,
+                    'accept': 'text/event-stream',
+                    'content-type': 'application/json',
+                    'user-agent': ANTIGRAVITY_USER_AGENT,
+                }),
+                body: JSON.stringify(envelope),
+                signal,
+            });
+            return response;
+        }
+        catch (error) {
+            throw error;
+        }
     }
     /** Resolve image blocks through the attachment service, when it is present. */
     imageResolver(signal) {
@@ -664,8 +722,17 @@ export class AntigravityAdapter extends LlmAdapter {
                 ...signal === undefined ? {} : { signal },
             });
             this.quotas = quotas;
-            this.live = entries;
-            this.discovered = entries.map((entry) => entry.id);
+            this.adopt(entries);
+            // The catalog the endpoint just reported is what the next session starts from, so
+            // the picker does not have to ask again. A cache failure never fails this read.
+            if (this.options.saveListing !== undefined) {
+                try {
+                    await this.options.saveListing(entries);
+                }
+                catch (error) {
+                    this.options.onWarn?.(`model catalog cache write failed (${errorChain(error)})`);
+                }
+            }
             return this.discovered;
         }
         catch (error) {
@@ -911,8 +978,13 @@ export function createAntigravityProvider(options) {
         hiddenModels: () => options.preferences.hiddenIds(ANTIGRAVITY_PROVIDER_ID),
         userModels: () => options.preferences.extraIds(ANTIGRAVITY_PROVIDER_ID),
         modelOrder: () => options.preferences.orderOf(ANTIGRAVITY_PROVIDER_ID),
+        ...options.cachedListing === undefined ? {} : { cachedListing: options.cachedListing },
+        ...options.saveListing === undefined ? {} : { saveListing: options.saveListing },
         fetchFn,
     });
+    // 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: ANTIGRAVITY_PROVIDER_ID,
         displayName: ANTIGRAVITY_PROVIDER_NAME,

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

@@ -27,6 +27,16 @@ export interface ArkProviderOptions {
     streamIdleTimeoutMs: number;
     defaultModel?: string;
     extraModels?: readonly string[];
+    /**
+     * The endpoint's last live listing, 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>;
     preferences: ModelPreferences;
     resolveAttachments?: () => AttachmentStore | undefined;
     onCatalogChanged?: () => void;

package/lib/providers/ark-provider.js

@@ -113,8 +113,14 @@ export function createArkProvider(options) {
         hiddenModels: () => options.preferences.hiddenIds(ARK_PROVIDER_ID),
         userModels: () => options.preferences.extraIds(ARK_PROVIDER_ID),
         ...options.extraModels === undefined ? {} : { extraModels: options.extraModels },
+        ...options.defaultModel === undefined ? {} : { defaultModel: options.defaultModel },
+        ...options.cachedListing === undefined ? {} : { cachedListing: options.cachedListing },
+        ...options.saveListing === undefined ? {} : { saveListing: options.saveListing },
         fetchFn,
     });
+    // 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: ARK_PROVIDER_ID,
         displayName: ARK_PROVIDER_NAME,

package/lib/providers/ark.d.ts

@@ -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
  */
@@ -42,14 +45,12 @@ export declare 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 declare const ARK_CONTEXT_WINDOW = 262144;
 /** Output budget used when the caller sets no cap. */
 export declare const ARK_DEFAULT_MAX_TOKENS = 32000;
-/** The plan's model roster, as the reference registry records it. */
-export declare const ARK_MODELS: readonly CatalogEntry[];
 /** One signed-in Ark account. */
 export interface ArkSession extends SessionBase {
     /**
@@ -89,6 +90,25 @@ export interface ArkAdapterOptions {
     hiddenModels?: () => Promise<ReadonlySet<string>> | ReadonlySet<string>;
     userModels?: () => Promise<readonly string[]> | readonly string[];
     extraModels?: readonly string[];
+    /**
+     * Model this route preselects, and therefore always offers.
+     *
+     * Configuration rather than a shipped fact: the plan re-points its alias at a new
+     * release on its own schedule, and the picker must be able to preselect it. Defaults
+     * to {@link ARK_DEFAULT_MODEL}.
+     */
+    defaultModel?: string;
+    /**
+     * The endpoint's last live listing, 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. 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>;
     resolveAttachments?: () => AttachmentStore | undefined;
     onWarn?: (message: string) => void;
     onCredentialRejected?: (account: string) => void;
@@ -99,10 +119,45 @@ export interface ArkAdapterOptions {
 /** The adapter behind the `ark` route. */
 export declare class ArkAdapter extends LlmAdapter {
     private readonly 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.
+     */
     private live;
-    /** Image-generation model id, when discovery reported one. */
+    /** 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.
+     *
+     * 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.
+     */
+    private readonly fastVariants;
     constructor(options: ArkAdapterOptions);
+    /**
+     * 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.
+     */
+    private adoptListing;
+    /**
+     * 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.
+     */
+    hydrate(): Promise<void>;
     providerInfo(provider: string): LlmProviderInfo;
     providerRetryPolicy(): undefined;
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
@@ -113,18 +168,49 @@ export declare class ArkAdapter extends LlmAdapter {
     /** Translate an auth failure into the message a user can act on. */
     private refreshHint;
     private catalog;
+    /**
+     * 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.
+     */
     private shippedCatalog;
+    /** The model the picker preselects, from configuration. */
+    private defaultModel;
     private addedEntries;
     private hidden;
-    /** 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: readonly string[]): void;
     /**
-     * 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, 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.
      *
-     * 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.
+     * @param apiKey - bearer for the account.
+     * @param signal - optional cancellation.
+     * @returns the model ids now served, or undefined when the listing is unavailable.
      */
     fetchCatalog(apiKey: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
+    /** Persist one live listing, reporting a cache failure without failing the read. */
+    private saveListing;
     /** Send one streaming request over the Responses wire. */
     private request;
     /** Resolve image blocks through the attachment service, when it is present. */