dsh-plugin-subscriptions 0.3.0 → 0.3.1

package/lib/index.js

@@ -678,14 +678,26 @@ var TokenManager = class {
 /** How long a discovered catalog is trusted before re-fetching. */
 const DISCOVERY_TTL_MS = 5 * 6e4;
 /**
-* 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}.
 */
 var ModelCatalogCache = class {
 	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;
 	}
 	/**
@@ -696,27 +708,200 @@ var ModelCatalogCache = class {
 		if (this.entry === void 0 || Date.now() - this.entry.at >= this.ttlMs) return void 0;
 		return this.entry.models;
 	}
+	/** Load the persisted snapshot once; a fetch or invalidate that landed first wins. */
+	ensureSeeded() {
+		if (this.persistence === void 0) return Promise.resolve();
+		this.seeded ??= this.persistence.load().then((snapshot) => {
+			if (snapshot !== void 0 && this.entry === void 0 && !this.seedDisabled) this.entry = snapshot;
+		}, () => void 0);
+		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;
+			this.persistence?.save(snapshot).catch(() => void 0);
+			return models;
+		}).finally(() => {
+			this.inflight = void 0;
+		});
+		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 !== void 0) 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 !== void 0) return fresh;
+		const known = this.entry?.models;
+		if (known !== void 0) {
+			this.refresh(fetcher).catch(() => void 0);
+			return known;
+		}
+		try {
+			return await this.refresh(fetcher);
+		} catch {
+			return;
+		}
 	}
 	/** Drop the cached catalog (e.g. after a 401 proved the credential changed). */
 	invalidate() {
 		this.entry = void 0;
+		this.seedDisabled = true;
+		this.persistence?.clear().catch(() => void 0);
 	}
 };
 
+//#endregion
+//#region src/providers/catalog-store.ts
+/**
+* Absolute path of the catalog store file.
+* @returns `dshHomePath('plugins', 'subscriptions', 'models.json')`.
+*/
+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 void 0;
+	const raw = value;
+	if (!Array.isArray(raw.efforts) || raw.efforts.length === 0) return void 0;
+	const seen = /* @__PURE__ */ new Set();
+	const efforts = [];
+	for (const entry of raw.efforts) {
+		if (typeof entry !== "object" || entry === null) return void 0;
+		const effort = entry;
+		if (typeof effort.id !== "string" || effort.id.length === 0 || typeof effort.name !== "string" || effort.name.length === 0 || effort.description !== void 0 && typeof effort.description !== "string" || seen.has(effort.id)) return void 0;
+		seen.add(effort.id);
+		efforts.push({
+			id: ReasoningEffortId(effort.id),
+			name: effort.name,
+			...effort.description === void 0 ? {} : { description: effort.description }
+		});
+	}
+	if (raw.defaultEffort !== void 0 && (typeof raw.defaultEffort !== "string" || !seen.has(raw.defaultEffort))) return void 0;
+	return {
+		efforts,
+		...raw.defaultEffort === void 0 ? {} : { defaultEffort: ReasoningEffortId(raw.defaultEffort) }
+	};
+}
+/** Validate one persisted model, or undefined when malformed. */
+function sanitizeModel(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const raw = value;
+	if (typeof raw.id !== "string" || raw.id.length === 0 || typeof raw.name !== "string" || raw.name.length === 0 || raw.description !== void 0 && typeof raw.description !== "string" || raw.contextWindow !== void 0 && (typeof raw.contextWindow !== "number" || !Number.isInteger(raw.contextWindow) || raw.contextWindow <= 0) || raw.priority !== void 0 && (typeof raw.priority !== "number" || !Number.isFinite(raw.priority))) return void 0;
+	const reasoning = raw.reasoning === void 0 ? void 0 : sanitizeReasoning(raw.reasoning);
+	if (raw.reasoning !== void 0 && reasoning === void 0) return void 0;
+	return {
+		id: raw.id,
+		name: raw.name,
+		...raw.description === void 0 ? {} : { description: raw.description },
+		...raw.contextWindow === void 0 ? {} : { contextWindow: raw.contextWindow },
+		...raw.priority === void 0 ? {} : { priority: raw.priority },
+		...reasoning === void 0 ? {} : { 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.
+*/
+function sanitizeSnapshot(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const raw = value;
+	if (typeof raw.at !== "number" || !Number.isFinite(raw.at)) return void 0;
+	if (!Array.isArray(raw.models) || raw.models.length === 0) return void 0;
+	const seen = /* @__PURE__ */ new Set();
+	const models = [];
+	for (const entry of raw.models) {
+		const model = sanitizeModel(entry);
+		if (model === void 0 || seen.has(model.id)) return void 0;
+		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}.
+*/
+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] === void 0) return;
+			delete store[provider];
+			await writeCatalogFile(store, path);
+		}
+	};
+}
+
 //#endregion
 //#region src/auth/jwt.ts
 /** Minimal JWT payload decoding for claims extraction (no signature verification). */
@@ -1430,10 +1615,15 @@ async function fetchCodexModels(session, fetchFn = fetch) {
 }
 /** Codex wire adapter: one instance serves the `codex` provider route. */
 var CodexAdapter = class extends LlmAdapter {
-	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 {
@@ -1453,7 +1643,7 @@ var CodexAdapter = class extends LlmAdapter {
 		if (await this.options.tokens.peek() === void 0) return [];
 		if (!this.options.discovery) return this.staticModels(provider);
 		try {
-			return (await this.catalog.get(async () => fetchCodexModels(await this.options.tokens.session(), this.options.fetchFn))).map((model) => ({
+			return (await this.catalog.get(() => this.fetchCatalog())).map((model) => ({
 				provider,
 				id: model.id,
 				name: model.name,
@@ -1467,10 +1657,21 @@ var CodexAdapter = class extends LlmAdapter {
 			return this.staticModels(provider);
 		}
 	}
-	resolveModel(provider, model) {
-		const discovered = this.options.discovery ? this.catalog.cached()?.find((entry) => entry.id === model) : void 0;
+	/**
+	* 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 void 0;
+		return (await this.catalog.resolve(() => this.fetchCatalog()))?.find((entry) => entry.id === model);
+	}
+	async resolveModel(provider, model) {
+		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,
@@ -1482,7 +1683,7 @@ var CodexAdapter = class extends LlmAdapter {
 				efforts: CODEX_EFFORTS,
 				defaultEffort: CODEX_DEFAULT_EFFORT
 			}
-		});
+		};
 	}
 	async *stream(options) {
 		const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);
@@ -2538,10 +2739,15 @@ async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
 }
 /** Grok wire adapter: one instance serves the `grok` provider route. */
 var GrokAdapter = class extends LlmAdapter {
-	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 fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn);
 	}
 	providerInfo(provider) {
 		return {
@@ -2561,7 +2767,7 @@ var GrokAdapter = class extends LlmAdapter {
 		if (await this.options.tokens.peek() === void 0) return [];
 		if (!this.options.discovery) return this.staticModels(provider);
 		try {
-			return (await this.catalog.get(async () => fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn))).map((model) => ({
+			return (await this.catalog.get(() => this.fetchCatalog())).map((model) => ({
 				provider,
 				id: model.id,
 				name: model.name,
@@ -2575,10 +2781,22 @@ var GrokAdapter = class extends LlmAdapter {
 			return this.staticModels(provider);
 		}
 	}
-	resolveModel(provider, model) {
-		const discovered = this.options.discovery ? this.catalog.cached()?.find((entry) => entry.id === model) : void 0;
+	/**
+	* 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.
+	*/
+	async discovered(model) {
+		if (!this.options.discovery) return void 0;
+		return (await this.catalog.resolve(() => this.fetchCatalog()))?.find((entry) => entry.id === model);
+	}
+	async resolveModel(provider, model) {
+		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,
@@ -2587,7 +2805,7 @@ var GrokAdapter = class extends LlmAdapter {
 			context: { contextWindow: discovered?.contextWindow ?? configured?.contextWindow ?? GROK_CONTEXT_WINDOW },
 			defaultMaxTokens: configured?.maxTokens ?? GROK_DEFAULT_MAX_TOKENS,
 			...discovered?.reasoning === void 0 ? {} : { reasoning: discovered.reasoning }
-		});
+		};
 	}
 	async *stream(options) {
 		const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);
@@ -3303,7 +3521,8 @@ function apply(ctx, config) {
 				tokens,
 				discovery: !overridden.has("codex"),
 				onWarn,
-				resolveAttachments
+				resolveAttachments,
+				catalogStore: catalogStore("codex")
 			})));
 			break;
 		}
@@ -3350,7 +3569,8 @@ function apply(ctx, config) {
 				tokens,
 				discovery: !overridden.has("grok"),
 				onWarn,
-				resolveAttachments
+				resolveAttachments,
+				catalogStore: catalogStore("grok")
 			})));
 			break;
 		}

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";
@@ -93,15 +93,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

@@ -327,10 +327,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 +359,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 +380,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 +407,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;

package/lib/providers/grok.js

@@ -405,10 +405,15 @@ export async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
 /** Grok wire adapter: one instance serves the `grok` provider route. */
 export class GrokAdapter 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 fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn);
     }
     providerInfo(provider) {
         return { id: provider, name: 'Grok (Subscription)' };
@@ -432,7 +437,7 @@ export class GrokAdapter 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 () => fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn));
+            const discovered = await this.catalog.get(() => this.fetchCatalog());
             return discovered.map(model => ({
                 provider,
                 id: model.id,
@@ -453,12 +458,24 @@ export class GrokAdapter extends LlmAdapter {
             return this.staticModels(provider);
         }
     }
-    resolveModel(provider, model) {
-        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: 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.
+     */
+    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) {
+        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,
@@ -470,7 +487,7 @@ export class GrokAdapter extends LlmAdapter {
             // cover expose none, so the harness rejects explicit efforts before
             // provider I/O instead of the API 400ing.
             ...discovered?.reasoning === undefined ? {} : { reasoning: discovered.reasoning },
-        });
+        };
     }
     async *stream(options) {
         const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-subscriptions",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Use ChatGPT (Codex), Claude, and Grok (X Premium) subscriptions as DeepSeek Harness LLM providers, with OAuth login from the web Settings page",
   "license": "MIT",
   "repository": {