dsh-plugin-subscriptions 0.3.0 → 0.4.0

package/lib/providers/catalog-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * On-disk discovered-model-catalog cache at
+ * `~/.dsh/plugins/subscriptions/models.json` — the durable half of each
+ * provider's {@link ModelCatalogCache}. One entry per provider: the last
+ * successfully discovered catalog with its fetch time, so capability metadata
+ * (reasoning efforts) survives restarts and network failures.
+ *
+ * Unlike the auth store, this file is a cache: a missing, corrupt, or
+ * malformed file silently reads as absent, because the next successful
+ * discovery rewrites it. Loads are strictly validated — a malformed entry
+ * passed through `resolveModel` would make the harness's metadata validation
+ * throw on every call, which is worse than having no fallback at all.
+ */
+import type { ProviderId } from '../auth/store.js';
+import type { CatalogPersistence, CatalogSnapshot } from './common.js';
+/**
+ * Absolute path of the catalog store file.
+ * @returns `dshHomePath('plugins', 'subscriptions', 'models.json')`.
+ */
+export declare function modelsFilePath(): string;
+/**
+ * Validate one persisted snapshot. Strict: any malformed field drops the
+ * whole snapshot rather than repairing it — the next successful discovery
+ * rewrites the entry anyway.
+ * @param value - the raw per-provider file entry.
+ * @returns the validated snapshot, or undefined when unusable.
+ */
+export declare function sanitizeSnapshot(value: unknown): CatalogSnapshot | undefined;
+/**
+ * Build the durable half of one provider's catalog cache over the shared
+ * models.json file (concurrent writers are last-writer-wins, acceptable for
+ * a cache).
+ * @param provider - the provider route keying the file entry.
+ * @param path - store file path; defaults to {@link modelsFilePath}.
+ * @returns the persistence hooks for {@link ModelCatalogCache}.
+ */
+export declare function catalogStore(provider: ProviderId, path?: string): CatalogPersistence;

package/lib/providers/catalog-store.js

@@ -0,0 +1,167 @@
+/**
+ * On-disk discovered-model-catalog cache at
+ * `~/.dsh/plugins/subscriptions/models.json` — the durable half of each
+ * provider's {@link ModelCatalogCache}. One entry per provider: the last
+ * successfully discovered catalog with its fetch time, so capability metadata
+ * (reasoning efforts) survives restarts and network failures.
+ *
+ * Unlike the auth store, this file is a cache: a missing, corrupt, or
+ * malformed file silently reads as absent, because the next successful
+ * discovery rewrites it. Loads are strictly validated — a malformed entry
+ * passed through `resolveModel` would make the harness's metadata validation
+ * throw on every call, which is worse than having no fallback at all.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+/**
+ * Absolute path of the catalog store file.
+ * @returns `dshHomePath('plugins', 'subscriptions', 'models.json')`.
+ */
+export function modelsFilePath() {
+    return dshHomePath('plugins', 'subscriptions', 'models.json');
+}
+/** Validate one persisted reasoning block, or undefined when malformed. */
+function sanitizeReasoning(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const raw = value;
+    if (!Array.isArray(raw.efforts) || raw.efforts.length === 0)
+        return undefined;
+    const seen = new Set();
+    const efforts = [];
+    for (const entry of raw.efforts) {
+        if (typeof entry !== 'object' || entry === null)
+            return undefined;
+        const effort = entry;
+        if (typeof effort.id !== 'string' || effort.id.length === 0
+            || typeof effort.name !== 'string' || effort.name.length === 0
+            || (effort.description !== undefined && typeof effort.description !== 'string')
+            || seen.has(effort.id))
+            return undefined;
+        seen.add(effort.id);
+        efforts.push({
+            id: ReasoningEffortId(effort.id),
+            name: effort.name,
+            ...effort.description === undefined ? {} : { description: effort.description },
+        });
+    }
+    if (raw.defaultEffort !== undefined
+        && (typeof raw.defaultEffort !== 'string' || !seen.has(raw.defaultEffort)))
+        return undefined;
+    return {
+        efforts,
+        ...raw.defaultEffort === undefined ? {} : { defaultEffort: ReasoningEffortId(raw.defaultEffort) },
+    };
+}
+/** Validate one persisted model, or undefined when malformed. */
+function sanitizeModel(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const raw = value;
+    if (typeof raw.id !== 'string' || raw.id.length === 0
+        || typeof raw.name !== 'string' || raw.name.length === 0
+        || (raw.description !== undefined && typeof raw.description !== 'string')
+        || (raw.contextWindow !== undefined
+            && (typeof raw.contextWindow !== 'number' || !Number.isInteger(raw.contextWindow) || raw.contextWindow <= 0))
+        || (raw.priority !== undefined
+            && (typeof raw.priority !== 'number' || !Number.isFinite(raw.priority))))
+        return undefined;
+    const reasoning = raw.reasoning === undefined ? undefined : sanitizeReasoning(raw.reasoning);
+    if (raw.reasoning !== undefined && reasoning === undefined)
+        return undefined;
+    return {
+        id: raw.id,
+        name: raw.name,
+        ...raw.description === undefined ? {} : { description: raw.description },
+        ...raw.contextWindow === undefined ? {} : { contextWindow: raw.contextWindow },
+        ...raw.priority === undefined ? {} : { priority: raw.priority },
+        ...reasoning === undefined ? {} : { reasoning },
+    };
+}
+/**
+ * Validate one persisted snapshot. Strict: any malformed field drops the
+ * whole snapshot rather than repairing it — the next successful discovery
+ * rewrites the entry anyway.
+ * @param value - the raw per-provider file entry.
+ * @returns the validated snapshot, or undefined when unusable.
+ */
+export function sanitizeSnapshot(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const raw = value;
+    if (typeof raw.at !== 'number' || !Number.isFinite(raw.at))
+        return undefined;
+    if (!Array.isArray(raw.models) || raw.models.length === 0)
+        return undefined;
+    const seen = new Set();
+    const models = [];
+    for (const entry of raw.models) {
+        const model = sanitizeModel(entry);
+        if (model === undefined || seen.has(model.id))
+            return undefined;
+        seen.add(model.id);
+        models.push(model);
+    }
+    return { at: raw.at, models };
+}
+/** Read the whole file; missing or unparsable reads as an empty cache. */
+async function readCatalogFile(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+/** Persist the whole file atomically (tmp file + rename). */
+async function writeCatalogFile(store, path) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await writeFile(tmp, JSON.stringify(store, null, 2));
+        await rename(tmp, path);
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        throw error;
+    }
+}
+/**
+ * Build the durable half of one provider's catalog cache over the shared
+ * models.json file (concurrent writers are last-writer-wins, acceptable for
+ * a cache).
+ * @param provider - the provider route keying the file entry.
+ * @param path - store file path; defaults to {@link modelsFilePath}.
+ * @returns the persistence hooks for {@link ModelCatalogCache}.
+ */
+export function catalogStore(provider, path = modelsFilePath()) {
+    return {
+        async load() {
+            return sanitizeSnapshot((await readCatalogFile(path))[provider]);
+        },
+        async save(snapshot) {
+            const store = await readCatalogFile(path);
+            store[provider] = snapshot;
+            await writeCatalogFile(store, path);
+        },
+        async clear() {
+            const store = await readCatalogFile(path);
+            if (store[provider] === undefined)
+                return;
+            delete store[provider];
+            await writeCatalogFile(store, path);
+        },
+    };
+}

package/lib/providers/codex.d.ts

@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { CodexSession } from '../auth/store.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { TokenManager } from './common.js';
-import type { DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
+import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
 export declare const CODEX_AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
 export declare const CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token";
@@ -57,8 +57,11 @@ export declare const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usa
 /**
  * Fetch the codex subscription usage from the ChatGPT backend wham/usage
  * endpoint (the source of the codex CLI `/status` rate-limit lines). The
- * primary window is the rolling session (5-hour) lane, the secondary window
- * the weekly lane; the lookup itself consumes no rate-limit budget.
+ * windows are classified by their reported duration (`limit_window_seconds`)
+ * rather than by slot, since the backend has been observed to report the
+ * weekly lane as `primary_window` without a secondary window; slot order is
+ * kept only as a fallback when the duration is absent. The lookup itself
+ * consumes no rate-limit budget.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param signal - caller cancellation from the RPC transport.
@@ -93,15 +96,27 @@ export interface CodexAdapterOptions {
     fetchFn?: FetchFn;
     /** Resolve the attachment service per request; absent means image requests fail loudly. */
     resolveAttachments?: () => AttachmentStore | undefined;
+    /** Durable catalog store seeding capability metadata across restarts. */
+    catalogStore?: CatalogPersistence;
 }
 /** Codex wire adapter: one instance serves the `codex` provider route. */
 export declare class CodexAdapter extends LlmAdapter {
     private readonly options;
     private readonly catalog;
     constructor(options: CodexAdapterOptions);
+    /** Discovery fetcher: resolves the session through the refresh-aware path. */
+    private fetchCatalog;
     providerInfo(provider: string): LlmProviderInfo;
     private staticModels;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * The discovered entry for one model. Resolved through the cache's
+     * stale-while-revalidate path so capability metadata stays stable across a
+     * long conversation: a discovered-only effort (one missing from the static
+     * CODEX_EFFORTS list) selected by the user must not vanish — and fail the
+     * call — just because the TTL lapsed mid-turn.
+     */
+    private discovered;
     resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
     private request;

package/lib/providers/codex.js

@@ -189,8 +189,31 @@ export function isCodexPermanentRefreshError(error) {
         && PERMANENT_REFRESH_CODES.has(error.oauthCode);
 }
 export const CODEX_USAGE_URL = 'https://chatgpt.com/backend-api/wham/usage';
+/** Seconds of the canonical 5-hour session and 7-day weekly windows. */
+const SESSION_WINDOW_SECONDS = 5 * 60 * 60;
+const WEEKLY_WINDOW_SECONDS = 7 * 24 * 60 * 60;
+/** Whether a reported duration approximately matches the expected window length. */
+function matchesWindow(seconds, expected) {
+    return seconds >= expected * 0.95 && seconds <= expected * 1.05;
+}
+/**
+ * Classify a wham/usage window by its reported duration. The backend has been
+ * observed to place the weekly lane in `primary_window` with no secondary
+ * window, so slot position alone is unreliable; the caller's positional
+ * fallback applies only when the duration is absent.
+ */
+function codexWindowKind(window, fallback) {
+    const seconds = window.limit_window_seconds;
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0)
+        return fallback;
+    if (matchesWindow(seconds, SESSION_WINDOW_SECONDS))
+        return 'session';
+    if (matchesWindow(seconds, WEEKLY_WINDOW_SECONDS))
+        return 'weekly';
+    return 'other';
+}
 /** Map one wham/usage window into a {@link UsageWindow}; undefined when unusable. */
-function codexUsageWindow(value, kind) {
+function codexUsageWindow(value, fallbackKind) {
     if (typeof value !== 'object' || value === null)
         return undefined;
     const window = value;
@@ -203,13 +226,20 @@ function codexUsageWindow(value, kind) {
     else if (typeof window.reset_after_seconds === 'number' && window.reset_after_seconds > 0) {
         resetsAt = Date.now() + window.reset_after_seconds * 1000;
     }
-    return { kind, usedPercent: window.used_percent, ...resetsAt === undefined ? {} : { resetsAt } };
+    return {
+        kind: codexWindowKind(window, fallbackKind),
+        usedPercent: window.used_percent,
+        ...resetsAt === undefined ? {} : { resetsAt },
+    };
 }
 /**
  * Fetch the codex subscription usage from the ChatGPT backend wham/usage
  * endpoint (the source of the codex CLI `/status` rate-limit lines). The
- * primary window is the rolling session (5-hour) lane, the secondary window
- * the weekly lane; the lookup itself consumes no rate-limit budget.
+ * windows are classified by their reported duration (`limit_window_seconds`)
+ * rather than by slot, since the backend has been observed to report the
+ * weekly lane as `primary_window` without a secondary window; slot order is
+ * kept only as a fallback when the duration is absent. The lookup itself
+ * consumes no rate-limit budget.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param signal - caller cancellation from the RPC transport.
@@ -327,10 +357,15 @@ export async function fetchCodexModels(session, fetchFn = fetch) {
 /** Codex wire adapter: one instance serves the `codex` provider route. */
 export class CodexAdapter extends LlmAdapter {
     options;
-    catalog = new ModelCatalogCache();
+    catalog;
     constructor(options) {
         super();
         this.options = options;
+        this.catalog = new ModelCatalogCache(options.catalogStore);
+    }
+    /** Discovery fetcher: resolves the session through the refresh-aware path. */
+    async fetchCatalog() {
+        return fetchCodexModels(await this.options.tokens.session(), this.options.fetchFn);
     }
     providerInfo(provider) {
         return { id: provider, name: 'ChatGPT (Codex)' };
@@ -354,7 +389,7 @@ export class CodexAdapter extends LlmAdapter {
             // The fetcher runs only on a cache miss, and resolves the session
             // through the refresh-aware path so an expired access token renews here
             // instead of failing discovery into the static fallback.
-            const discovered = await this.catalog.get(async () => fetchCodexModels(await this.options.tokens.session(), this.options.fetchFn));
+            const discovered = await this.catalog.get(() => this.fetchCatalog());
             return discovered.map(model => ({
                 provider,
                 id: model.id,
@@ -375,14 +410,25 @@ export class CodexAdapter extends LlmAdapter {
             return this.staticModels(provider);
         }
     }
-    resolveModel(provider, model) {
-        // Discovered metadata (when discovery is on and the cache is warm) wins
-        // over the static entry; the static entry wins over the built-in defaults.
-        const discovered = this.options.discovery
-            ? this.catalog.cached()?.find(entry => entry.id === model)
-            : undefined;
+    /**
+     * The discovered entry for one model. Resolved through the cache's
+     * stale-while-revalidate path so capability metadata stays stable across a
+     * long conversation: a discovered-only effort (one missing from the static
+     * CODEX_EFFORTS list) selected by the user must not vanish — and fail the
+     * call — just because the TTL lapsed mid-turn.
+     */
+    async discovered(model) {
+        if (!this.options.discovery)
+            return undefined;
+        const models = await this.catalog.resolve(() => this.fetchCatalog());
+        return models?.find(entry => entry.id === model);
+    }
+    async resolveModel(provider, model) {
+        // Discovered metadata (when discovery is on) wins over the static entry;
+        // the static entry wins over the built-in defaults.
+        const discovered = await this.discovered(model);
         const configured = this.options.models.find(entry => entry.id === model);
-        return Promise.resolve({
+        return {
             provider,
             id: model,
             name: discovered?.name ?? configured?.name ?? model,
@@ -391,7 +437,7 @@ export class CodexAdapter extends LlmAdapter {
             context: { contextWindow: discovered?.contextWindow ?? configured?.contextWindow ?? CODEX_CONTEXT_WINDOW },
             defaultMaxTokens: configured?.maxTokens ?? CODEX_DEFAULT_MAX_TOKENS,
             reasoning: discovered?.reasoning ?? { efforts: CODEX_EFFORTS, defaultEffort: CODEX_DEFAULT_EFFORT },
-        });
+        };
     }
     async *stream(options) {
         const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);

package/lib/providers/common.d.ts

@@ -178,27 +178,69 @@ export interface DiscoveredModel {
 }
 /** How long a discovered catalog is trusted before re-fetching. */
 export declare const DISCOVERY_TTL_MS: number;
+/** A durable snapshot of one provider's discovered catalog. */
+export interface CatalogSnapshot {
+    /** Epoch milliseconds of the successful fetch that produced it. */
+    at: number;
+    models: DiscoveredModel[];
+}
+/** The durable half of a {@link ModelCatalogCache} (the models.json store). */
+export interface CatalogPersistence {
+    /** The last persisted snapshot, or undefined when absent or unusable. */
+    load(): Promise<CatalogSnapshot | undefined>;
+    /** Persist a fresh snapshot (write-through after every successful fetch). */
+    save(snapshot: CatalogSnapshot): Promise<void>;
+    /** Drop the persisted snapshot (a 401 proved the credential changed). */
+    clear(): Promise<void>;
+}
 /**
- * TTL cache for one provider's discovered model catalog. Only `listModels`
- * populates it (via {@link get}); `resolveModel` reads {@link cached} so it
- * never performs network I/O. A 401 during a fetch must call
- * {@link invalidate}.
+ * Cache for one provider's discovered model catalog. The TTL only decides
+ * when to REFRESH; it never makes the cache forget: capability metadata
+ * (reasoning efforts) must stay stable for a session that selected an effort,
+ * or mid-conversation calls fail UNSUPPORTED_REASONING_EFFORT the moment the
+ * cache goes stale. `listModels` awaits freshness via {@link get};
+ * `resolveModel` uses {@link resolve}, which serves the last-known catalog
+ * while a stale entry refreshes in the background, and only awaits the fetch
+ * when nothing is known yet. An optional {@link CatalogPersistence} seeds the
+ * last-known state across restarts and receives every successful fetch. A 401
+ * during a fetch must call {@link invalidate}.
  */
 export declare class ModelCatalogCache {
+    private readonly persistence?;
     private readonly ttlMs;
     private entry;
-    constructor(ttlMs?: number);
+    private inflight;
+    /** Settles once the persisted snapshot (when any) has been considered. */
+    private seeded;
+    /** Set by {@link invalidate} so an in-flight disk read cannot resurrect dropped state. */
+    private seedDisabled;
+    constructor(persistence?: CatalogPersistence | undefined, ttlMs?: number);
     /**
      * The cached catalog when fresh, without fetching.
      * @returns the cached models, or `undefined` when absent or stale.
      */
     cached(): readonly DiscoveredModel[] | undefined;
+    /** Load the persisted snapshot once; a fetch or invalidate that landed first wins. */
+    private ensureSeeded;
+    /** Run (or join) the single in-flight fetch, updating memory and disk on success. */
+    private refresh;
     /**
      * Return the cached catalog when fresh, otherwise fetch and cache it.
      * @param fetcher - performs the provider's model-list request.
      * @returns the discovered models.
+     * @throws the fetcher's failure (the `listModels` caller warns and falls back).
      */
     get(fetcher: () => Promise<DiscoveredModel[]>): Promise<readonly DiscoveredModel[]>;
+    /**
+     * The models for capability resolution. A fresh cache answers directly; a
+     * stale one answers immediately from the last-known catalog while a
+     * background refresh runs (a mid-conversation `resolveModel` must neither
+     * block on nor fail with the network); a cold cache awaits one fetch.
+     * @param fetcher - performs the provider's model-list request.
+     * @returns the models, or `undefined` when nothing is known (the caller
+     *   falls back to its static metadata). Never throws.
+     */
+    resolve(fetcher: () => Promise<DiscoveredModel[]>): Promise<readonly DiscoveredModel[] | undefined>;
     /** Drop the cached catalog (e.g. after a 401 proved the credential changed). */
     invalidate(): void;
 }

package/lib/providers/common.js

@@ -262,15 +262,28 @@ export class TokenManager {
 /** How long a discovered catalog is trusted before re-fetching. */
 export const DISCOVERY_TTL_MS = 5 * 60_000;
 /**
- * TTL cache for one provider's discovered model catalog. Only `listModels`
- * populates it (via {@link get}); `resolveModel` reads {@link cached} so it
- * never performs network I/O. A 401 during a fetch must call
- * {@link invalidate}.
+ * Cache for one provider's discovered model catalog. The TTL only decides
+ * when to REFRESH; it never makes the cache forget: capability metadata
+ * (reasoning efforts) must stay stable for a session that selected an effort,
+ * or mid-conversation calls fail UNSUPPORTED_REASONING_EFFORT the moment the
+ * cache goes stale. `listModels` awaits freshness via {@link get};
+ * `resolveModel` uses {@link resolve}, which serves the last-known catalog
+ * while a stale entry refreshes in the background, and only awaits the fetch
+ * when nothing is known yet. An optional {@link CatalogPersistence} seeds the
+ * last-known state across restarts and receives every successful fetch. A 401
+ * during a fetch must call {@link invalidate}.
  */
 export class ModelCatalogCache {
+    persistence;
     ttlMs;
     entry;
-    constructor(ttlMs = DISCOVERY_TTL_MS) {
+    inflight;
+    /** Settles once the persisted snapshot (when any) has been considered. */
+    seeded;
+    /** Set by {@link invalidate} so an in-flight disk read cannot resurrect dropped state. */
+    seedDisabled = false;
+    constructor(persistence, ttlMs = DISCOVERY_TTL_MS) {
+        this.persistence = persistence;
         this.ttlMs = ttlMs;
     }
     /**
@@ -282,21 +295,71 @@ export class ModelCatalogCache {
             return undefined;
         return this.entry.models;
     }
+    /** Load the persisted snapshot once; a fetch or invalidate that landed first wins. */
+    ensureSeeded() {
+        if (this.persistence === undefined)
+            return Promise.resolve();
+        this.seeded ??= this.persistence.load().then((snapshot) => {
+            if (snapshot !== undefined && this.entry === undefined && !this.seedDisabled) {
+                this.entry = snapshot;
+            }
+        }, () => undefined);
+        return this.seeded;
+    }
+    /** Run (or join) the single in-flight fetch, updating memory and disk on success. */
+    refresh(fetcher) {
+        this.inflight ??= fetcher()
+            .then((models) => {
+            const snapshot = { at: Date.now(), models };
+            this.entry = snapshot;
+            // Write-through is fire-and-forget: a failed save only costs durability.
+            void this.persistence?.save(snapshot).catch(() => undefined);
+            return models;
+        })
+            .finally(() => { this.inflight = undefined; });
+        return this.inflight;
+    }
     /**
      * Return the cached catalog when fresh, otherwise fetch and cache it.
      * @param fetcher - performs the provider's model-list request.
      * @returns the discovered models.
+     * @throws the fetcher's failure (the `listModels` caller warns and falls back).
      */
     async get(fetcher) {
-        const cached = this.cached();
-        if (cached !== undefined)
-            return cached;
-        const models = await fetcher();
-        this.entry = { at: Date.now(), models };
-        return models;
+        await this.ensureSeeded();
+        return this.cached() ?? this.refresh(fetcher);
+    }
+    /**
+     * The models for capability resolution. A fresh cache answers directly; a
+     * stale one answers immediately from the last-known catalog while a
+     * background refresh runs (a mid-conversation `resolveModel` must neither
+     * block on nor fail with the network); a cold cache awaits one fetch.
+     * @param fetcher - performs the provider's model-list request.
+     * @returns the models, or `undefined` when nothing is known (the caller
+     *   falls back to its static metadata). Never throws.
+     */
+    async resolve(fetcher) {
+        await this.ensureSeeded();
+        const fresh = this.cached();
+        if (fresh !== undefined)
+            return fresh;
+        const known = this.entry?.models;
+        if (known !== undefined) {
+            // Stale-while-revalidate: the refresh outcome serves the NEXT resolve.
+            this.refresh(fetcher).catch(() => undefined);
+            return known;
+        }
+        try {
+            return await this.refresh(fetcher);
+        }
+        catch {
+            return undefined;
+        }
     }
     /** Drop the cached catalog (e.g. after a 401 proved the credential changed). */
     invalidate() {
         this.entry = undefined;
+        this.seedDisabled = true;
+        void this.persistence?.clear().catch(() => undefined);
     }
 }

package/lib/providers/grok.d.ts

@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { GrokSession } from '../auth/store.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { TokenManager } from './common.js';
-import type { DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
+import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
 export declare const GROK_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
 export declare const GROK_API_URL = "https://api.x.ai/v1/responses";
@@ -121,15 +121,28 @@ export interface GrokAdapterOptions {
     fetchFn?: FetchFn;
     /** Resolve the attachment service per request; absent means image requests fail loudly. */
     resolveAttachments?: () => AttachmentStore | undefined;
+    /** Durable catalog store seeding capability metadata across restarts. */
+    catalogStore?: CatalogPersistence;
 }
 /** Grok wire adapter: one instance serves the `grok` provider route. */
 export declare class GrokAdapter extends LlmAdapter {
     private readonly options;
     private readonly catalog;
     constructor(options: GrokAdapterOptions);
+    /** Discovery fetcher: resolves the session through the refresh-aware path. */
+    private fetchCatalog;
     providerInfo(provider: string): LlmProviderInfo;
     private staticModels;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * The discovered entry for one model. Resolved through the cache's
+     * stale-while-revalidate path: capability metadata must stay stable across
+     * a long conversation — a session that selected a reasoning effort calls
+     * this on EVERY step, and forgetting the efforts just because the TTL
+     * lapsed mid-turn would fail the call with UNSUPPORTED_REASONING_EFFORT
+     * before provider I/O.
+     */
+    private discovered;
     resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
     private request;