dsh-plugin-subscriptions 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +17 -1
- package/README.zh.md +17 -1
- package/lib/index.js +319 -35
- package/lib/providers/catalog-store.d.ts +37 -0
- package/lib/providers/catalog-store.js +167 -0
- package/lib/providers/codex.d.ts +13 -1
- package/lib/providers/codex.js +26 -10
- package/lib/providers/common.d.ts +47 -5
- package/lib/providers/common.js +74 -11
- package/lib/providers/grok.d.ts +40 -4
- package/lib/providers/grok.js +131 -22
- package/package.json +6 -8
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* On-disk discovered-model-catalog cache at
|
|
3
|
+
* `~/.dsh/plugins/subscriptions/models.json` — the durable half of each
|
|
4
|
+
* provider's {@link ModelCatalogCache}. One entry per provider: the last
|
|
5
|
+
* successfully discovered catalog with its fetch time, so capability metadata
|
|
6
|
+
* (reasoning efforts) survives restarts and network failures.
|
|
7
|
+
*
|
|
8
|
+
* Unlike the auth store, this file is a cache: a missing, corrupt, or
|
|
9
|
+
* malformed file silently reads as absent, because the next successful
|
|
10
|
+
* discovery rewrites it. Loads are strictly validated — a malformed entry
|
|
11
|
+
* passed through `resolveModel` would make the harness's metadata validation
|
|
12
|
+
* throw on every call, which is worse than having no fallback at all.
|
|
13
|
+
*/
|
|
14
|
+
import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
|
|
15
|
+
import { dirname } from 'node:path';
|
|
16
|
+
import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
|
|
17
|
+
import { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
|
|
18
|
+
/**
|
|
19
|
+
* Absolute path of the catalog store file.
|
|
20
|
+
* @returns `dshHomePath('plugins', 'subscriptions', 'models.json')`.
|
|
21
|
+
*/
|
|
22
|
+
export function modelsFilePath() {
|
|
23
|
+
return dshHomePath('plugins', 'subscriptions', 'models.json');
|
|
24
|
+
}
|
|
25
|
+
/** Validate one persisted reasoning block, or undefined when malformed. */
|
|
26
|
+
function sanitizeReasoning(value) {
|
|
27
|
+
if (typeof value !== 'object' || value === null)
|
|
28
|
+
return undefined;
|
|
29
|
+
const raw = value;
|
|
30
|
+
if (!Array.isArray(raw.efforts) || raw.efforts.length === 0)
|
|
31
|
+
return undefined;
|
|
32
|
+
const seen = new Set();
|
|
33
|
+
const efforts = [];
|
|
34
|
+
for (const entry of raw.efforts) {
|
|
35
|
+
if (typeof entry !== 'object' || entry === null)
|
|
36
|
+
return undefined;
|
|
37
|
+
const effort = entry;
|
|
38
|
+
if (typeof effort.id !== 'string' || effort.id.length === 0
|
|
39
|
+
|| typeof effort.name !== 'string' || effort.name.length === 0
|
|
40
|
+
|| (effort.description !== undefined && typeof effort.description !== 'string')
|
|
41
|
+
|| seen.has(effort.id))
|
|
42
|
+
return undefined;
|
|
43
|
+
seen.add(effort.id);
|
|
44
|
+
efforts.push({
|
|
45
|
+
id: ReasoningEffortId(effort.id),
|
|
46
|
+
name: effort.name,
|
|
47
|
+
...effort.description === undefined ? {} : { description: effort.description },
|
|
48
|
+
});
|
|
49
|
+
}
|
|
50
|
+
if (raw.defaultEffort !== undefined
|
|
51
|
+
&& (typeof raw.defaultEffort !== 'string' || !seen.has(raw.defaultEffort)))
|
|
52
|
+
return undefined;
|
|
53
|
+
return {
|
|
54
|
+
efforts,
|
|
55
|
+
...raw.defaultEffort === undefined ? {} : { defaultEffort: ReasoningEffortId(raw.defaultEffort) },
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
/** Validate one persisted model, or undefined when malformed. */
|
|
59
|
+
function sanitizeModel(value) {
|
|
60
|
+
if (typeof value !== 'object' || value === null)
|
|
61
|
+
return undefined;
|
|
62
|
+
const raw = value;
|
|
63
|
+
if (typeof raw.id !== 'string' || raw.id.length === 0
|
|
64
|
+
|| typeof raw.name !== 'string' || raw.name.length === 0
|
|
65
|
+
|| (raw.description !== undefined && typeof raw.description !== 'string')
|
|
66
|
+
|| (raw.contextWindow !== undefined
|
|
67
|
+
&& (typeof raw.contextWindow !== 'number' || !Number.isInteger(raw.contextWindow) || raw.contextWindow <= 0))
|
|
68
|
+
|| (raw.priority !== undefined
|
|
69
|
+
&& (typeof raw.priority !== 'number' || !Number.isFinite(raw.priority))))
|
|
70
|
+
return undefined;
|
|
71
|
+
const reasoning = raw.reasoning === undefined ? undefined : sanitizeReasoning(raw.reasoning);
|
|
72
|
+
if (raw.reasoning !== undefined && reasoning === undefined)
|
|
73
|
+
return undefined;
|
|
74
|
+
return {
|
|
75
|
+
id: raw.id,
|
|
76
|
+
name: raw.name,
|
|
77
|
+
...raw.description === undefined ? {} : { description: raw.description },
|
|
78
|
+
...raw.contextWindow === undefined ? {} : { contextWindow: raw.contextWindow },
|
|
79
|
+
...raw.priority === undefined ? {} : { priority: raw.priority },
|
|
80
|
+
...reasoning === undefined ? {} : { reasoning },
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Validate one persisted snapshot. Strict: any malformed field drops the
|
|
85
|
+
* whole snapshot rather than repairing it — the next successful discovery
|
|
86
|
+
* rewrites the entry anyway.
|
|
87
|
+
* @param value - the raw per-provider file entry.
|
|
88
|
+
* @returns the validated snapshot, or undefined when unusable.
|
|
89
|
+
*/
|
|
90
|
+
export function sanitizeSnapshot(value) {
|
|
91
|
+
if (typeof value !== 'object' || value === null)
|
|
92
|
+
return undefined;
|
|
93
|
+
const raw = value;
|
|
94
|
+
if (typeof raw.at !== 'number' || !Number.isFinite(raw.at))
|
|
95
|
+
return undefined;
|
|
96
|
+
if (!Array.isArray(raw.models) || raw.models.length === 0)
|
|
97
|
+
return undefined;
|
|
98
|
+
const seen = new Set();
|
|
99
|
+
const models = [];
|
|
100
|
+
for (const entry of raw.models) {
|
|
101
|
+
const model = sanitizeModel(entry);
|
|
102
|
+
if (model === undefined || seen.has(model.id))
|
|
103
|
+
return undefined;
|
|
104
|
+
seen.add(model.id);
|
|
105
|
+
models.push(model);
|
|
106
|
+
}
|
|
107
|
+
return { at: raw.at, models };
|
|
108
|
+
}
|
|
109
|
+
/** Read the whole file; missing or unparsable reads as an empty cache. */
|
|
110
|
+
async function readCatalogFile(path) {
|
|
111
|
+
let text;
|
|
112
|
+
try {
|
|
113
|
+
text = await readFile(path, 'utf8');
|
|
114
|
+
}
|
|
115
|
+
catch {
|
|
116
|
+
return {};
|
|
117
|
+
}
|
|
118
|
+
try {
|
|
119
|
+
const parsed = JSON.parse(text);
|
|
120
|
+
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
|
|
121
|
+
return {};
|
|
122
|
+
return parsed;
|
|
123
|
+
}
|
|
124
|
+
catch {
|
|
125
|
+
return {};
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
/** Persist the whole file atomically (tmp file + rename). */
|
|
129
|
+
async function writeCatalogFile(store, path) {
|
|
130
|
+
await mkdir(dirname(path), { recursive: true });
|
|
131
|
+
const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
|
|
132
|
+
try {
|
|
133
|
+
await writeFile(tmp, JSON.stringify(store, null, 2));
|
|
134
|
+
await rename(tmp, path);
|
|
135
|
+
}
|
|
136
|
+
catch (error) {
|
|
137
|
+
await rm(tmp, { force: true });
|
|
138
|
+
throw error;
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Build the durable half of one provider's catalog cache over the shared
|
|
143
|
+
* models.json file (concurrent writers are last-writer-wins, acceptable for
|
|
144
|
+
* a cache).
|
|
145
|
+
* @param provider - the provider route keying the file entry.
|
|
146
|
+
* @param path - store file path; defaults to {@link modelsFilePath}.
|
|
147
|
+
* @returns the persistence hooks for {@link ModelCatalogCache}.
|
|
148
|
+
*/
|
|
149
|
+
export function catalogStore(provider, path = modelsFilePath()) {
|
|
150
|
+
return {
|
|
151
|
+
async load() {
|
|
152
|
+
return sanitizeSnapshot((await readCatalogFile(path))[provider]);
|
|
153
|
+
},
|
|
154
|
+
async save(snapshot) {
|
|
155
|
+
const store = await readCatalogFile(path);
|
|
156
|
+
store[provider] = snapshot;
|
|
157
|
+
await writeCatalogFile(store, path);
|
|
158
|
+
},
|
|
159
|
+
async clear() {
|
|
160
|
+
const store = await readCatalogFile(path);
|
|
161
|
+
if (store[provider] === undefined)
|
|
162
|
+
return;
|
|
163
|
+
delete store[provider];
|
|
164
|
+
await writeCatalogFile(store, path);
|
|
165
|
+
},
|
|
166
|
+
};
|
|
167
|
+
}
|
package/lib/providers/codex.d.ts
CHANGED
|
@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
|
|
|
9
9
|
import type { CodexSession } from '../auth/store.js';
|
|
10
10
|
import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
|
|
11
11
|
import { TokenManager } from './common.js';
|
|
12
|
-
import type { DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
|
|
12
|
+
import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
|
|
13
13
|
export declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
|
|
14
14
|
export declare const CODEX_AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
|
|
15
15
|
export declare const CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token";
|
|
@@ -93,15 +93,27 @@ export interface CodexAdapterOptions {
|
|
|
93
93
|
fetchFn?: FetchFn;
|
|
94
94
|
/** Resolve the attachment service per request; absent means image requests fail loudly. */
|
|
95
95
|
resolveAttachments?: () => AttachmentStore | undefined;
|
|
96
|
+
/** Durable catalog store seeding capability metadata across restarts. */
|
|
97
|
+
catalogStore?: CatalogPersistence;
|
|
96
98
|
}
|
|
97
99
|
/** Codex wire adapter: one instance serves the `codex` provider route. */
|
|
98
100
|
export declare class CodexAdapter extends LlmAdapter {
|
|
99
101
|
private readonly options;
|
|
100
102
|
private readonly catalog;
|
|
101
103
|
constructor(options: CodexAdapterOptions);
|
|
104
|
+
/** Discovery fetcher: resolves the session through the refresh-aware path. */
|
|
105
|
+
private fetchCatalog;
|
|
102
106
|
providerInfo(provider: string): LlmProviderInfo;
|
|
103
107
|
private staticModels;
|
|
104
108
|
listModels(provider: string): Promise<readonly LlmModelInfo[]>;
|
|
109
|
+
/**
|
|
110
|
+
* The discovered entry for one model. Resolved through the cache's
|
|
111
|
+
* stale-while-revalidate path so capability metadata stays stable across a
|
|
112
|
+
* long conversation: a discovered-only effort (one missing from the static
|
|
113
|
+
* CODEX_EFFORTS list) selected by the user must not vanish — and fail the
|
|
114
|
+
* call — just because the TTL lapsed mid-turn.
|
|
115
|
+
*/
|
|
116
|
+
private discovered;
|
|
105
117
|
resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
|
|
106
118
|
stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
|
|
107
119
|
private request;
|
package/lib/providers/codex.js
CHANGED
|
@@ -327,10 +327,15 @@ export async function fetchCodexModels(session, fetchFn = fetch) {
|
|
|
327
327
|
/** Codex wire adapter: one instance serves the `codex` provider route. */
|
|
328
328
|
export class CodexAdapter extends LlmAdapter {
|
|
329
329
|
options;
|
|
330
|
-
catalog
|
|
330
|
+
catalog;
|
|
331
331
|
constructor(options) {
|
|
332
332
|
super();
|
|
333
333
|
this.options = options;
|
|
334
|
+
this.catalog = new ModelCatalogCache(options.catalogStore);
|
|
335
|
+
}
|
|
336
|
+
/** Discovery fetcher: resolves the session through the refresh-aware path. */
|
|
337
|
+
async fetchCatalog() {
|
|
338
|
+
return fetchCodexModels(await this.options.tokens.session(), this.options.fetchFn);
|
|
334
339
|
}
|
|
335
340
|
providerInfo(provider) {
|
|
336
341
|
return { id: provider, name: 'ChatGPT (Codex)' };
|
|
@@ -354,7 +359,7 @@ export class CodexAdapter extends LlmAdapter {
|
|
|
354
359
|
// The fetcher runs only on a cache miss, and resolves the session
|
|
355
360
|
// through the refresh-aware path so an expired access token renews here
|
|
356
361
|
// instead of failing discovery into the static fallback.
|
|
357
|
-
const discovered = await this.catalog.get(
|
|
362
|
+
const discovered = await this.catalog.get(() => this.fetchCatalog());
|
|
358
363
|
return discovered.map(model => ({
|
|
359
364
|
provider,
|
|
360
365
|
id: model.id,
|
|
@@ -375,14 +380,25 @@ export class CodexAdapter extends LlmAdapter {
|
|
|
375
380
|
return this.staticModels(provider);
|
|
376
381
|
}
|
|
377
382
|
}
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
383
|
+
/**
|
|
384
|
+
* The discovered entry for one model. Resolved through the cache's
|
|
385
|
+
* stale-while-revalidate path so capability metadata stays stable across a
|
|
386
|
+
* long conversation: a discovered-only effort (one missing from the static
|
|
387
|
+
* CODEX_EFFORTS list) selected by the user must not vanish — and fail the
|
|
388
|
+
* call — just because the TTL lapsed mid-turn.
|
|
389
|
+
*/
|
|
390
|
+
async discovered(model) {
|
|
391
|
+
if (!this.options.discovery)
|
|
392
|
+
return undefined;
|
|
393
|
+
const models = await this.catalog.resolve(() => this.fetchCatalog());
|
|
394
|
+
return models?.find(entry => entry.id === model);
|
|
395
|
+
}
|
|
396
|
+
async resolveModel(provider, model) {
|
|
397
|
+
// Discovered metadata (when discovery is on) wins over the static entry;
|
|
398
|
+
// the static entry wins over the built-in defaults.
|
|
399
|
+
const discovered = await this.discovered(model);
|
|
384
400
|
const configured = this.options.models.find(entry => entry.id === model);
|
|
385
|
-
return
|
|
401
|
+
return {
|
|
386
402
|
provider,
|
|
387
403
|
id: model,
|
|
388
404
|
name: discovered?.name ?? configured?.name ?? model,
|
|
@@ -391,7 +407,7 @@ export class CodexAdapter extends LlmAdapter {
|
|
|
391
407
|
context: { contextWindow: discovered?.contextWindow ?? configured?.contextWindow ?? CODEX_CONTEXT_WINDOW },
|
|
392
408
|
defaultMaxTokens: configured?.maxTokens ?? CODEX_DEFAULT_MAX_TOKENS,
|
|
393
409
|
reasoning: discovered?.reasoning ?? { efforts: CODEX_EFFORTS, defaultEffort: CODEX_DEFAULT_EFFORT },
|
|
394
|
-
}
|
|
410
|
+
};
|
|
395
411
|
}
|
|
396
412
|
async *stream(options) {
|
|
397
413
|
const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);
|
|
@@ -178,27 +178,69 @@ export interface DiscoveredModel {
|
|
|
178
178
|
}
|
|
179
179
|
/** How long a discovered catalog is trusted before re-fetching. */
|
|
180
180
|
export declare const DISCOVERY_TTL_MS: number;
|
|
181
|
+
/** A durable snapshot of one provider's discovered catalog. */
|
|
182
|
+
export interface CatalogSnapshot {
|
|
183
|
+
/** Epoch milliseconds of the successful fetch that produced it. */
|
|
184
|
+
at: number;
|
|
185
|
+
models: DiscoveredModel[];
|
|
186
|
+
}
|
|
187
|
+
/** The durable half of a {@link ModelCatalogCache} (the models.json store). */
|
|
188
|
+
export interface CatalogPersistence {
|
|
189
|
+
/** The last persisted snapshot, or undefined when absent or unusable. */
|
|
190
|
+
load(): Promise<CatalogSnapshot | undefined>;
|
|
191
|
+
/** Persist a fresh snapshot (write-through after every successful fetch). */
|
|
192
|
+
save(snapshot: CatalogSnapshot): Promise<void>;
|
|
193
|
+
/** Drop the persisted snapshot (a 401 proved the credential changed). */
|
|
194
|
+
clear(): Promise<void>;
|
|
195
|
+
}
|
|
181
196
|
/**
|
|
182
|
-
*
|
|
183
|
-
*
|
|
184
|
-
*
|
|
185
|
-
*
|
|
197
|
+
* Cache for one provider's discovered model catalog. The TTL only decides
|
|
198
|
+
* when to REFRESH; it never makes the cache forget: capability metadata
|
|
199
|
+
* (reasoning efforts) must stay stable for a session that selected an effort,
|
|
200
|
+
* or mid-conversation calls fail UNSUPPORTED_REASONING_EFFORT the moment the
|
|
201
|
+
* cache goes stale. `listModels` awaits freshness via {@link get};
|
|
202
|
+
* `resolveModel` uses {@link resolve}, which serves the last-known catalog
|
|
203
|
+
* while a stale entry refreshes in the background, and only awaits the fetch
|
|
204
|
+
* when nothing is known yet. An optional {@link CatalogPersistence} seeds the
|
|
205
|
+
* last-known state across restarts and receives every successful fetch. A 401
|
|
206
|
+
* during a fetch must call {@link invalidate}.
|
|
186
207
|
*/
|
|
187
208
|
export declare class ModelCatalogCache {
|
|
209
|
+
private readonly persistence?;
|
|
188
210
|
private readonly ttlMs;
|
|
189
211
|
private entry;
|
|
190
|
-
|
|
212
|
+
private inflight;
|
|
213
|
+
/** Settles once the persisted snapshot (when any) has been considered. */
|
|
214
|
+
private seeded;
|
|
215
|
+
/** Set by {@link invalidate} so an in-flight disk read cannot resurrect dropped state. */
|
|
216
|
+
private seedDisabled;
|
|
217
|
+
constructor(persistence?: CatalogPersistence | undefined, ttlMs?: number);
|
|
191
218
|
/**
|
|
192
219
|
* The cached catalog when fresh, without fetching.
|
|
193
220
|
* @returns the cached models, or `undefined` when absent or stale.
|
|
194
221
|
*/
|
|
195
222
|
cached(): readonly DiscoveredModel[] | undefined;
|
|
223
|
+
/** Load the persisted snapshot once; a fetch or invalidate that landed first wins. */
|
|
224
|
+
private ensureSeeded;
|
|
225
|
+
/** Run (or join) the single in-flight fetch, updating memory and disk on success. */
|
|
226
|
+
private refresh;
|
|
196
227
|
/**
|
|
197
228
|
* Return the cached catalog when fresh, otherwise fetch and cache it.
|
|
198
229
|
* @param fetcher - performs the provider's model-list request.
|
|
199
230
|
* @returns the discovered models.
|
|
231
|
+
* @throws the fetcher's failure (the `listModels` caller warns and falls back).
|
|
200
232
|
*/
|
|
201
233
|
get(fetcher: () => Promise<DiscoveredModel[]>): Promise<readonly DiscoveredModel[]>;
|
|
234
|
+
/**
|
|
235
|
+
* The models for capability resolution. A fresh cache answers directly; a
|
|
236
|
+
* stale one answers immediately from the last-known catalog while a
|
|
237
|
+
* background refresh runs (a mid-conversation `resolveModel` must neither
|
|
238
|
+
* block on nor fail with the network); a cold cache awaits one fetch.
|
|
239
|
+
* @param fetcher - performs the provider's model-list request.
|
|
240
|
+
* @returns the models, or `undefined` when nothing is known (the caller
|
|
241
|
+
* falls back to its static metadata). Never throws.
|
|
242
|
+
*/
|
|
243
|
+
resolve(fetcher: () => Promise<DiscoveredModel[]>): Promise<readonly DiscoveredModel[] | undefined>;
|
|
202
244
|
/** Drop the cached catalog (e.g. after a 401 proved the credential changed). */
|
|
203
245
|
invalidate(): void;
|
|
204
246
|
}
|
package/lib/providers/common.js
CHANGED
|
@@ -262,15 +262,28 @@ export class TokenManager {
|
|
|
262
262
|
/** How long a discovered catalog is trusted before re-fetching. */
|
|
263
263
|
export const DISCOVERY_TTL_MS = 5 * 60_000;
|
|
264
264
|
/**
|
|
265
|
-
*
|
|
266
|
-
*
|
|
267
|
-
*
|
|
268
|
-
*
|
|
265
|
+
* Cache for one provider's discovered model catalog. The TTL only decides
|
|
266
|
+
* when to REFRESH; it never makes the cache forget: capability metadata
|
|
267
|
+
* (reasoning efforts) must stay stable for a session that selected an effort,
|
|
268
|
+
* or mid-conversation calls fail UNSUPPORTED_REASONING_EFFORT the moment the
|
|
269
|
+
* cache goes stale. `listModels` awaits freshness via {@link get};
|
|
270
|
+
* `resolveModel` uses {@link resolve}, which serves the last-known catalog
|
|
271
|
+
* while a stale entry refreshes in the background, and only awaits the fetch
|
|
272
|
+
* when nothing is known yet. An optional {@link CatalogPersistence} seeds the
|
|
273
|
+
* last-known state across restarts and receives every successful fetch. A 401
|
|
274
|
+
* during a fetch must call {@link invalidate}.
|
|
269
275
|
*/
|
|
270
276
|
export class ModelCatalogCache {
|
|
277
|
+
persistence;
|
|
271
278
|
ttlMs;
|
|
272
279
|
entry;
|
|
273
|
-
|
|
280
|
+
inflight;
|
|
281
|
+
/** Settles once the persisted snapshot (when any) has been considered. */
|
|
282
|
+
seeded;
|
|
283
|
+
/** Set by {@link invalidate} so an in-flight disk read cannot resurrect dropped state. */
|
|
284
|
+
seedDisabled = false;
|
|
285
|
+
constructor(persistence, ttlMs = DISCOVERY_TTL_MS) {
|
|
286
|
+
this.persistence = persistence;
|
|
274
287
|
this.ttlMs = ttlMs;
|
|
275
288
|
}
|
|
276
289
|
/**
|
|
@@ -282,21 +295,71 @@ export class ModelCatalogCache {
|
|
|
282
295
|
return undefined;
|
|
283
296
|
return this.entry.models;
|
|
284
297
|
}
|
|
298
|
+
/** Load the persisted snapshot once; a fetch or invalidate that landed first wins. */
|
|
299
|
+
ensureSeeded() {
|
|
300
|
+
if (this.persistence === undefined)
|
|
301
|
+
return Promise.resolve();
|
|
302
|
+
this.seeded ??= this.persistence.load().then((snapshot) => {
|
|
303
|
+
if (snapshot !== undefined && this.entry === undefined && !this.seedDisabled) {
|
|
304
|
+
this.entry = snapshot;
|
|
305
|
+
}
|
|
306
|
+
}, () => undefined);
|
|
307
|
+
return this.seeded;
|
|
308
|
+
}
|
|
309
|
+
/** Run (or join) the single in-flight fetch, updating memory and disk on success. */
|
|
310
|
+
refresh(fetcher) {
|
|
311
|
+
this.inflight ??= fetcher()
|
|
312
|
+
.then((models) => {
|
|
313
|
+
const snapshot = { at: Date.now(), models };
|
|
314
|
+
this.entry = snapshot;
|
|
315
|
+
// Write-through is fire-and-forget: a failed save only costs durability.
|
|
316
|
+
void this.persistence?.save(snapshot).catch(() => undefined);
|
|
317
|
+
return models;
|
|
318
|
+
})
|
|
319
|
+
.finally(() => { this.inflight = undefined; });
|
|
320
|
+
return this.inflight;
|
|
321
|
+
}
|
|
285
322
|
/**
|
|
286
323
|
* Return the cached catalog when fresh, otherwise fetch and cache it.
|
|
287
324
|
* @param fetcher - performs the provider's model-list request.
|
|
288
325
|
* @returns the discovered models.
|
|
326
|
+
* @throws the fetcher's failure (the `listModels` caller warns and falls back).
|
|
289
327
|
*/
|
|
290
328
|
async get(fetcher) {
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
329
|
+
await this.ensureSeeded();
|
|
330
|
+
return this.cached() ?? this.refresh(fetcher);
|
|
331
|
+
}
|
|
332
|
+
/**
|
|
333
|
+
* The models for capability resolution. A fresh cache answers directly; a
|
|
334
|
+
* stale one answers immediately from the last-known catalog while a
|
|
335
|
+
* background refresh runs (a mid-conversation `resolveModel` must neither
|
|
336
|
+
* block on nor fail with the network); a cold cache awaits one fetch.
|
|
337
|
+
* @param fetcher - performs the provider's model-list request.
|
|
338
|
+
* @returns the models, or `undefined` when nothing is known (the caller
|
|
339
|
+
* falls back to its static metadata). Never throws.
|
|
340
|
+
*/
|
|
341
|
+
async resolve(fetcher) {
|
|
342
|
+
await this.ensureSeeded();
|
|
343
|
+
const fresh = this.cached();
|
|
344
|
+
if (fresh !== undefined)
|
|
345
|
+
return fresh;
|
|
346
|
+
const known = this.entry?.models;
|
|
347
|
+
if (known !== undefined) {
|
|
348
|
+
// Stale-while-revalidate: the refresh outcome serves the NEXT resolve.
|
|
349
|
+
this.refresh(fetcher).catch(() => undefined);
|
|
350
|
+
return known;
|
|
351
|
+
}
|
|
352
|
+
try {
|
|
353
|
+
return await this.refresh(fetcher);
|
|
354
|
+
}
|
|
355
|
+
catch {
|
|
356
|
+
return undefined;
|
|
357
|
+
}
|
|
297
358
|
}
|
|
298
359
|
/** Drop the cached catalog (e.g. after a 401 proved the credential changed). */
|
|
299
360
|
invalidate() {
|
|
300
361
|
this.entry = undefined;
|
|
362
|
+
this.seedDisabled = true;
|
|
363
|
+
void this.persistence?.clear().catch(() => undefined);
|
|
301
364
|
}
|
|
302
365
|
}
|
package/lib/providers/grok.d.ts
CHANGED
|
@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
|
|
|
9
9
|
import type { GrokSession } from '../auth/store.js';
|
|
10
10
|
import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
|
|
11
11
|
import { TokenManager } from './common.js';
|
|
12
|
-
import type { DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
|
|
12
|
+
import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
|
|
13
13
|
export declare const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
|
|
14
14
|
export declare const GROK_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
|
|
15
15
|
export declare const GROK_API_URL = "https://api.x.ai/v1/responses";
|
|
@@ -80,12 +80,34 @@ export declare const GROK_BILLING_URL = "https://cli-chat-proxy.grok.com/v1/bill
|
|
|
80
80
|
export declare function fetchGrokUsage(session: GrokSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
|
|
81
81
|
export declare const GROK_MODELS_URL = "https://api.x.ai/v1/models";
|
|
82
82
|
/**
|
|
83
|
-
*
|
|
83
|
+
* The Grok Build CLI chat proxy's model catalog — the only grok endpoint that
|
|
84
|
+
* advertises reasoning capability. The `api.x.ai/v1/models` and
|
|
85
|
+
* `/v1/language-models` payloads carry pricing, context, and aliases only, so
|
|
86
|
+
* effort metadata must come from here (the same source the official CLI's
|
|
87
|
+
* picker uses).
|
|
88
|
+
*/
|
|
89
|
+
export declare const GROK_CLI_MODELS_URL = "https://cli-chat-proxy.grok.com/v1/models";
|
|
90
|
+
/** Per-model metadata the CLI catalog contributes to a discovered model. */
|
|
91
|
+
type GrokCliModelMeta = Partial<Pick<DiscoveredModel, 'name' | 'description' | 'contextWindow' | 'reasoning'>>;
|
|
92
|
+
/**
|
|
93
|
+
* Fetch the CLI catalog and index its per-model metadata by model id.
|
|
94
|
+
* @param session - the stored session (used as-is; never refreshed here).
|
|
95
|
+
* @param fetchFn - fetch implementation (injectable for tests).
|
|
96
|
+
* @returns model id → contributed metadata.
|
|
97
|
+
*/
|
|
98
|
+
export declare function fetchGrokCliCatalog(session: GrokSession, fetchFn?: FetchFn): Promise<Map<string, GrokCliModelMeta>>;
|
|
99
|
+
/**
|
|
100
|
+
* Fetch the live grok model list, enriched with the CLI catalog's per-model
|
|
101
|
+
* metadata (display name, context window, reasoning efforts). The api.x.ai
|
|
102
|
+
* list stays authoritative for which models exist; the CLI catalog is
|
|
103
|
+
* enrichment only, so its failure degrades to a plain list instead of taking
|
|
104
|
+
* discovery down — models it does not cover simply expose no efforts.
|
|
84
105
|
* @param session - the stored session (used as-is; never refreshed here).
|
|
85
106
|
* @param fetchFn - fetch implementation (injectable for tests).
|
|
86
|
-
* @
|
|
107
|
+
* @param onWarn - warning sink for a failed CLI catalog fetch.
|
|
108
|
+
* @returns discovered chat models in endpoint order.
|
|
87
109
|
*/
|
|
88
|
-
export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn): Promise<DiscoveredModel[]>;
|
|
110
|
+
export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn, onWarn?: (message: string) => void): Promise<DiscoveredModel[]>;
|
|
89
111
|
/** Constructor dependencies for {@link GrokAdapter}. */
|
|
90
112
|
export interface GrokAdapterOptions {
|
|
91
113
|
models: readonly ModelEntry[];
|
|
@@ -99,16 +121,30 @@ export interface GrokAdapterOptions {
|
|
|
99
121
|
fetchFn?: FetchFn;
|
|
100
122
|
/** Resolve the attachment service per request; absent means image requests fail loudly. */
|
|
101
123
|
resolveAttachments?: () => AttachmentStore | undefined;
|
|
124
|
+
/** Durable catalog store seeding capability metadata across restarts. */
|
|
125
|
+
catalogStore?: CatalogPersistence;
|
|
102
126
|
}
|
|
103
127
|
/** Grok wire adapter: one instance serves the `grok` provider route. */
|
|
104
128
|
export declare class GrokAdapter extends LlmAdapter {
|
|
105
129
|
private readonly options;
|
|
106
130
|
private readonly catalog;
|
|
107
131
|
constructor(options: GrokAdapterOptions);
|
|
132
|
+
/** Discovery fetcher: resolves the session through the refresh-aware path. */
|
|
133
|
+
private fetchCatalog;
|
|
108
134
|
providerInfo(provider: string): LlmProviderInfo;
|
|
109
135
|
private staticModels;
|
|
110
136
|
listModels(provider: string): Promise<readonly LlmModelInfo[]>;
|
|
137
|
+
/**
|
|
138
|
+
* The discovered entry for one model. Resolved through the cache's
|
|
139
|
+
* stale-while-revalidate path: capability metadata must stay stable across
|
|
140
|
+
* a long conversation — a session that selected a reasoning effort calls
|
|
141
|
+
* this on EVERY step, and forgetting the efforts just because the TTL
|
|
142
|
+
* lapsed mid-turn would fail the call with UNSUPPORTED_REASONING_EFFORT
|
|
143
|
+
* before provider I/O.
|
|
144
|
+
*/
|
|
145
|
+
private discovered;
|
|
111
146
|
resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
|
|
112
147
|
stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
|
|
113
148
|
private request;
|
|
114
149
|
}
|
|
150
|
+
export {};
|