dsh-model-think-level 1.1.7 → 2.0.0

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.
Files changed (36) hide show
  1. package/README.md +38 -15
  2. package/lib/client/ComposerSlider.d.ts +9 -9
  3. package/lib/client/EffortEditor.d.ts +9 -6
  4. package/lib/client/KeyManager.d.ts +36 -10
  5. package/lib/client/ProtocolMenu.d.ts +51 -0
  6. package/lib/client/events.d.ts +26 -0
  7. package/lib/client/injection/add-card.d.ts +4 -0
  8. package/lib/client/injection/create-card-pane.d.ts +15 -0
  9. package/lib/client/injection/create-key-seat.d.ts +54 -0
  10. package/lib/client/injection/create-keys-pane.d.ts +46 -0
  11. package/lib/client/injection/key-reveal.d.ts +12 -0
  12. package/lib/client/injection/models-page-editor.d.ts +83 -0
  13. package/lib/client/injection/provider-endpoints.d.ts +70 -0
  14. package/lib/client/injection/staged-keys.d.ts +169 -0
  15. package/lib/client/key-manager-client.d.ts +89 -12
  16. package/lib/client/locales.d.ts +48 -15
  17. package/lib/client/ops.d.ts +0 -71
  18. package/lib/client/styles.d.ts +1 -1
  19. package/lib/client/types.d.ts +35 -2
  20. package/lib/client.js +1781 -313
  21. package/lib/client.js.map +4 -4
  22. package/lib/discovery-merge.d.ts +35 -0
  23. package/lib/headers-fetch.d.ts +53 -3
  24. package/lib/headers-pi-ai.d.ts +31 -1
  25. package/lib/index.d.ts +3 -19
  26. package/lib/index.js +1462 -139
  27. package/lib/index.js.map +4 -4
  28. package/lib/key-index.d.ts +58 -1
  29. package/lib/key-probe.d.ts +126 -0
  30. package/lib/key-refs.d.ts +106 -0
  31. package/lib/key-route-core.d.ts +415 -0
  32. package/lib/knowledge.d.ts +6 -5
  33. package/lib/listing.d.ts +118 -0
  34. package/lib/multi-key-listing.d.ts +101 -0
  35. package/package.json +1 -1
  36. package/lib/client/LongCacheSection.d.ts +0 -36
@@ -0,0 +1,415 @@
1
+ /**
2
+ * The pure half of multi-key routing: given the ordered keys a provider route
3
+ * may authenticate with and the model a request names, decide WHICH key signs
4
+ * the request first, and — when that request fails — WHICH key to try next.
5
+ *
6
+ * The rule the user asked for (Scheme A):
7
+ * - Keys are listed in preference order; index 0 is the default.
8
+ * - A model reachable through several keys goes to the FIRST key that can
9
+ * serve it.
10
+ * - A model only one key can serve sticks to that key.
11
+ * - When a request errors, the next capable key is tried.
12
+ *
13
+ * "Can serve" is read from each key's discovered `models` scope:
14
+ * - a scope that lists the model -> can serve it (an exact claim);
15
+ * - an UNSCOPED key (no `models`) -> treated as a catch-all, so it can serve
16
+ * anything (this is the state before a key has been probed, and the way a
17
+ * user deliberately says "this key takes whatever is left");
18
+ * - a scope that does NOT list the model -> cannot serve it (an exact denial).
19
+ *
20
+ * Eligible keys keep their list order, so the "both can serve -> first key"
21
+ * and "only one can -> that key" rules both fall out of a single filter. If NO
22
+ * key is eligible (a stale or empty scope across the board), every key is
23
+ * returned as a last resort so a wrong scope can never strand a model the
24
+ * first key could in fact reach.
25
+ *
26
+ * This module performs no I/O and knows nothing about credentials: the host
27
+ * fills in each candidate's `value`, and the wire seam consumes the answer.
28
+ *
29
+ * On top of the model scope, three further signals decide the attempt order —
30
+ * the same three a gateway such as magpie mixes into its dispatch:
31
+ *
32
+ * - WIRE FIT: a key is ranked by how much translation the model needs (its own
33
+ * family first, the route's default second, a different vendor's family
34
+ * last), so a claude model on an OpenAI-speaking route reaches a key that
35
+ * can speak the Anthropic wire before paying for a translated round trip.
36
+ * A key PINNED to a protocol always speaks it; an UNPINNED key is automatic
37
+ * ({@link autoWireOf}) — it speaks the model family's own wire against that
38
+ * family's address when the key carries one, and the route's default
39
+ * otherwise;
40
+ * - HONOUR: a pin that crosses wire families without that family's endpoint
41
+ * cannot re-dispatch, so it trails the keys that can (it is never dropped: a
42
+ * lone key must still sign the request);
43
+ * - COOLDOWN: a key that just failed with a retryable status rests for a while
44
+ * instead of being charged the same failure again on the next request.
45
+ *
46
+ * The wire seam alone ranks by wire, because only it can act on a pin; the fetch
47
+ * seam only consults the cooldown memory, since it can neither switch a protocol
48
+ * nor pick the URL.
49
+ *
50
+ * @module dsh-model-think-level/key-route-core
51
+ */
52
+ import { type EndpointFamily, type RouteProtocol } from './key-refs.js';
53
+ /** One key a route may use, with the secret already resolved. */
54
+ export interface KeyCandidate {
55
+ /** Stable credential reference (for diagnostics and de-duplication). */
56
+ readonly ref: string;
57
+ /** The secret to put on the wire. */
58
+ readonly value: string;
59
+ /**
60
+ * Model ids this key is known to serve. `undefined` means "unscoped": not
61
+ * probed yet, or deliberately left as a catch-all. An array (possibly empty)
62
+ * is a concrete scope.
63
+ */
64
+ readonly models?: readonly string[];
65
+ /**
66
+ * The wire protocol this key must speak, when it is pinned to one.
67
+ * `undefined` means AUTOMATIC: the request speaks whichever wire the model's
68
+ * own family names — an Anthropic-family endpoint for claude models, the
69
+ * Gemini one for gemini models, the route's default for everything else —
70
+ * as far as the key carries that family's address in {@link endpoints}.
71
+ * A concrete value makes the wire seam re-dispatch the request through that
72
+ * protocol's API implementation (a true protocol switch), using {@link endpoint}.
73
+ */
74
+ readonly protocol?: RouteProtocol;
75
+ /**
76
+ * The base URL to send this key's request to, already resolved for the key's
77
+ * protocol family. `undefined` means "use the model's own baseUrl" (the route
78
+ * default). A pinned-protocol key carries its family's endpoint here.
79
+ */
80
+ readonly endpoint?: string;
81
+ /**
82
+ * The addresses an AUTOMATIC key (no {@link protocol}) may dispatch on, one
83
+ * per endpoint family beyond the route's own. `wireOf` picks the model
84
+ * family's entry and the wire seam sends the request there; families absent
85
+ * from the map fall back to the route's default wire.
86
+ */
87
+ readonly endpoints?: Readonly<Partial<Record<EndpointFamily, string>>>;
88
+ }
89
+ /** Whether `key` can serve `model`, per the scope rules above. */
90
+ export declare function canServe(key: KeyCandidate, model: string | undefined): boolean;
91
+ /**
92
+ * Order the keys that may sign a request for `model`, most-preferred first.
93
+ *
94
+ * The result is the eligible keys in their original list order. When the
95
+ * filter leaves nothing, all keys are returned unchanged (last resort) — the
96
+ * caller's failover loop still bounds the attempts, so an over-eager scope is
97
+ * corrected on the wire rather than failing the request outright.
98
+ * @param keys - the route's keys in preference order (may be empty).
99
+ * @param model - the model id the request names, or undefined when unknown.
100
+ * @returns the ordered candidates to try.
101
+ */
102
+ export declare function keysForModel(keys: readonly KeyCandidate[], model: string | undefined): KeyCandidate[];
103
+ /** The wire families: one body format and one endpoint shape each. */
104
+ export type WireFamily = 'anthropic' | 'openai' | 'gemini';
105
+ /** The family a protocol draws its body format and endpoint from. */
106
+ export declare function wireFamilyOf(protocol: RouteProtocol): WireFamily;
107
+ /** The family a model id announces, or undefined when it announces none. */
108
+ export declare function modelWireFamily(modelId: string | undefined): WireFamily | undefined;
109
+ /**
110
+ * The single wire a model id points at, when its family has only one.
111
+ *
112
+ * The OpenAI family has two wires (Chat Completions and Responses), so no id can
113
+ * single one of them out — the route's own protocol stays the tie-breaker there.
114
+ * The Anthropic and Gemini families have exactly one each, so a key pinned to
115
+ * one of them needs no translation for a model of that family and deserves the
116
+ * first attempt.
117
+ * @param modelId - the model id the request names, or undefined.
118
+ * @returns the concrete protocol, or undefined when the id does not settle one.
119
+ */
120
+ export declare function modelWireHint(modelId: string | undefined): RouteProtocol | undefined;
121
+ /**
122
+ * The wire an AUTOMATIC key (no pin) dispatches for `model`.
123
+ *
124
+ * The model's own family decides: a claude id speaks the Anthropic wire against
125
+ * the Anthropic address, a gemini id speaks the Gemini wire against the Gemini
126
+ * address — but only when the key actually carries that family's address; any
127
+ * other model (or a family the route itself serves) keeps the route's default
128
+ * wire, which is the one dispatch that always works. A wire that just failed
129
+ * this model before any content (`avoid`) is skipped as the automatic choice —
130
+ * the route's wire is the fallback that answers when the family's gateway does
131
+ * not — while an explicit pin is never second-guessed this way.
132
+ * @param candidate - the key (only its `endpoints` map is read).
133
+ * @param api - the protocol the route speaks.
134
+ * @param model - the model id the request names, or undefined when unknown.
135
+ * @param avoid - a wire not to pick automatically for this model, when one
136
+ * recently failed.
137
+ * @returns the protocol this attempt speaks.
138
+ */
139
+ export declare function autoWireOf(candidate: Pick<KeyCandidate, 'endpoints'>, api: RouteProtocol, model: string | undefined, avoid?: RouteProtocol | undefined): RouteProtocol;
140
+ /**
141
+ * The protocol a key actually dispatches on a route speaking `api`.
142
+ *
143
+ * An unpinned key resolves automatically per model ({@link autoWireOf}). A pin
144
+ * is honoured when it names the route's own family (a same-family switch needs
145
+ * no other address) or when it carries the endpoint of its family, which is
146
+ * what lets a true protocol switch happen. A cross-family pin with no endpoint
147
+ * cannot be honoured — the route's base URL carries the route family's paths —
148
+ * so the key still signs on the route's own wire rather than being sent to an
149
+ * address it does not own.
150
+ * @param candidate - the key.
151
+ * @param api - the protocol the route speaks.
152
+ * @param model - the model id the request names, or undefined when unknown.
153
+ * @param avoid - a wire the automatic resolution should skip, when one
154
+ * recently failed for this model.
155
+ * @returns the protocol the attempt will speak.
156
+ */
157
+ export declare function wireOf(candidate: KeyCandidate, api: RouteProtocol, model?: string | undefined, avoid?: RouteProtocol | undefined): RouteProtocol;
158
+ /** Whether {@link wireOf} can honour the candidate's pin on this route. */
159
+ export declare function isHonoured(candidate: KeyCandidate, api: RouteProtocol): boolean;
160
+ /**
161
+ * How much translation a key costs for a model: 0 needs none, 1 keeps the wire
162
+ * family but changes the protocol (Chat Completions vs Responses), 2 speaks a
163
+ * different vendor's family and would pay for a translated round trip.
164
+ */
165
+ export type WireFit = 0 | 1 | 2;
166
+ /**
167
+ * Rank one key against one model, following magpie's three-way fit: the model's
168
+ * own family first, the request's own wire next, another family last.
169
+ * @param candidate - the key.
170
+ * @param api - the protocol the route speaks.
171
+ * @param modelId - the model id, or undefined when the body was unreadable.
172
+ * @param avoid - a wire the automatic resolution should skip, when one
173
+ * recently failed for this model.
174
+ * @returns 0 (native), 1 (translated within the family) or 2 (another family).
175
+ */
176
+ export declare function protocolFit(candidate: KeyCandidate, api: RouteProtocol, modelId: string | undefined, avoid?: RouteProtocol | undefined): WireFit;
177
+ /**
178
+ * Order keys by wire fit alone, keeping list order inside each rank.
179
+ *
180
+ * A model whose family no key shares leaves every key at the same rank, so the
181
+ * caller's order survives untouched: ranking can reorder, never drop.
182
+ * @param candidates - the route's keys in preference order.
183
+ * @param api - the protocol the route speaks.
184
+ * @param modelId - the model id the request names, or undefined.
185
+ * @param avoid - a wire the automatic resolution should skip, when one
186
+ * recently failed for this model.
187
+ * @returns a new array, stable within each rank.
188
+ */
189
+ export declare function sortByFit(candidates: readonly KeyCandidate[], api: RouteProtocol, modelId: string | undefined, avoid?: RouteProtocol | undefined): KeyCandidate[];
190
+ /** Move keys the caller reports as resting behind every key that is ready. */
191
+ export declare function restLast<T extends KeyCandidate>(candidates: readonly T[], isResting: (candidate: KeyCandidate) => boolean): T[];
192
+ /** One key as the wire seam will attempt it, with the reasons recorded. */
193
+ export interface PlannedKey {
194
+ readonly candidate: KeyCandidate;
195
+ /** The protocol this attempt will speak ({@link wireOf}). */
196
+ readonly wire: RouteProtocol;
197
+ /** How much translation the model costs on this wire ({@link protocolFit}). */
198
+ readonly fit: WireFit;
199
+ /** Whether a protocol pin can be honoured ({@link isHonoured}). */
200
+ readonly honoured: boolean;
201
+ /** Whether this key is cooling down after a failure. */
202
+ readonly resting: boolean;
203
+ }
204
+ /** What the wire seam should attempt, in order, and why. */
205
+ export interface KeyPlan {
206
+ /** The keys to try, most-preferred first (pool, then aside, then resting). */
207
+ readonly ordered: readonly KeyCandidate[];
208
+ /** The same order, annotated for diagnostics. */
209
+ readonly entries: readonly PlannedKey[];
210
+ /**
211
+ * The keys that speak the starting wire. A failure inside the pool is most
212
+ * likely environmental, so the pool is drained before any other wire is tried —
213
+ * a mixed-protocol route then costs at most one translated attempt.
214
+ */
215
+ readonly pool: readonly KeyCandidate[];
216
+ /** Keys that would change the wire (or that a missing endpoint demotes). */
217
+ readonly aside: readonly KeyCandidate[];
218
+ /** The protocol the first attempt speaks, when there is any key at all. */
219
+ readonly wire: RouteProtocol | undefined;
220
+ }
221
+ /** What the wire seam knows about the request it is about to place. */
222
+ export interface PlanOptions {
223
+ /** The protocol the route speaks. */
224
+ readonly api: RouteProtocol;
225
+ /** The model id the request names, when it could be read. */
226
+ readonly model?: string;
227
+ /** The wire that served this model last time, learned from a committed stream. */
228
+ readonly preferredWire?: RouteProtocol;
229
+ /**
230
+ * The wire that failed this model last time before any content, learned from
231
+ * a pre-content failure. An automatic key does not pick it again for this
232
+ * model ({@link autoWireOf}); explicit pins are never second-guessed.
233
+ */
234
+ readonly avoidWire?: RouteProtocol;
235
+ /** Whether a key is cooling down after a failure. */
236
+ readonly isResting?: (candidate: KeyCandidate) => boolean;
237
+ }
238
+ /**
239
+ * Decide what the wire seam attempts, in which order, and on which wire.
240
+ *
241
+ * The order is the composition of four signals, strongest last, so a learned
242
+ * fact always beats a heuristic and a hard constraint always beats both:
243
+ *
244
+ * 1. wire fit — least translation first ({@link protocolFit}; the automatic
245
+ * resolution inside it also skips {@link PlanOptions.avoidWire});
246
+ * 2. the wire that served this model last time ({@link PlanOptions.preferredWire});
247
+ * 3. honour — keys whose pin can be dispatched before keys that cannot;
248
+ * 4. pooling — the starting wire's keys first, other wires appended after them;
249
+ * 5. cooldown — resting keys last, never dropped.
250
+ *
251
+ * Pooling splits the list without dropping anything: the aside keys are still
252
+ * tried when the pool fails, which is what keeps a single misconfigured key from
253
+ * stranding a model that a different wire could serve.
254
+ * @param candidates - the keys the resolver returned, in preference order.
255
+ * @param options - the route's wire, the model, and the runtime's memories.
256
+ * @returns the plan the caller iterates.
257
+ */
258
+ export declare function planKeys(candidates: readonly KeyCandidate[], options: PlanOptions): KeyPlan;
259
+ /**
260
+ * Whether an HTTP status is worth retrying on the next key. Authentication and
261
+ * authorization failures (the wrong key for this endpoint), rate limits, timeouts
262
+ * and server faults are all "this key did not work, try the next"; a 400/404/422
263
+ * is a request-shape problem that every key would answer identically, so it is
264
+ * returned to the caller unchanged rather than multiplied across keys.
265
+ * @param status - the response status code.
266
+ */
267
+ export declare function shouldFailover(status: number): boolean;
268
+ /**
269
+ * Why a key failed, as far as the next request is concerned. The distinction is
270
+ * only between "this key is the problem" and "every key would repeat it", which
271
+ * is why a 400 has no kind at all.
272
+ */
273
+ export type FailureKind = 'auth' | 'rate' | 'quota' | 'server' | 'timeout' | 'refused';
274
+ /**
275
+ * What a failed attempt says about the key, or undefined when it says nothing —
276
+ * a request-shape failure (400/404/422) that every key would answer identically.
277
+ * @param status - the response status, or undefined when the stream failed without one.
278
+ * @param bodyText - the response body (bounded by the caller) or the stream's error text.
279
+ * @returns the failure kind, or undefined for a failure the key did not cause.
280
+ */
281
+ export declare function classifyFailure(status: number | undefined, bodyText?: string): FailureKind | undefined;
282
+ /** Longest a key is ever benched, whatever keeps failing. */
283
+ export declare const REST_COOLDOWN_CAP_MS: number;
284
+ /**
285
+ * How long a key should rest after its `failures`-th consecutive failure.
286
+ *
287
+ * The provider's own `Retry-After` is the floor when it is longer than the
288
+ * kind's baseline (a server that says "come back in an hour" means it), and
289
+ * repeated failures double the wait up to the cap so a dead key is not retried
290
+ * on every request forever.
291
+ * @param kind - why it failed.
292
+ * @param failures - how many consecutive failures, 1 for the first.
293
+ * @param retryAfterMs - the provider's `Retry-After`, already parsed.
294
+ * @returns the resting period in milliseconds.
295
+ */
296
+ export declare function cooldownFor(kind: FailureKind, failures?: number, retryAfterMs?: number): number;
297
+ /**
298
+ * Parse a `Retry-After` header (delay-seconds or an HTTP date) into milliseconds.
299
+ * @param value - the header value, when the response carried one.
300
+ * @param now - the current time, for the date form.
301
+ * @returns milliseconds to wait, or undefined when the value says nothing usable.
302
+ */
303
+ export declare function parseRetryAfter(value: string | null | undefined, now: number): number | undefined;
304
+ /** One key's cooling state: who benched it, until when, and how often it failed. */
305
+ export interface RestState {
306
+ readonly kind: FailureKind;
307
+ /** Epoch milliseconds after which the key is a normal candidate again. */
308
+ readonly until: number;
309
+ /** Consecutive failures that produced this period. */
310
+ readonly failures: number;
311
+ }
312
+ /** How a failure was observed, so the period can honour the provider's word. */
313
+ export interface RestNote {
314
+ /** The observation time; defaults to now. Injected so tests are deterministic. */
315
+ readonly now?: number;
316
+ /** The provider's `Retry-After`, already parsed. */
317
+ readonly retryAfterMs?: number;
318
+ }
319
+ /** Bounded memory of which keys are benched and for how long. */
320
+ export interface RestStore {
321
+ /** How many keys it remembers (expired entries included until pruned). */
322
+ readonly size: number;
323
+ /** The live state of a key, or undefined when it is a normal candidate again. */
324
+ stateOf(key: string, now: number): RestState | undefined;
325
+ /** Whether the key should be deferred right now. */
326
+ isResting(key: string, now: number): boolean;
327
+ /** Record one failure of a key and return the state it is now in. */
328
+ note(key: string, kind: FailureKind, options?: RestNote): RestState;
329
+ /** The key answered: forget its failures. */
330
+ clear(key: string): void;
331
+ /** Forget every key. */
332
+ reset(): void;
333
+ }
334
+ /** Enough for a host that churns through routes without growing without bound. */
335
+ export declare const REST_STORE_LIMIT = 256;
336
+ /**
337
+ * Create a cooldown store.
338
+ *
339
+ * Holding the clock outside makes the store a pure function of its call history,
340
+ * which is what lets both seams share one memory while the tests drive it.
341
+ * @param limit - how many keys it may remember before pruning expired entries.
342
+ * @returns a store with no keys resting.
343
+ */
344
+ export declare function createRestStore(limit?: number): RestStore;
345
+ /**
346
+ * The key a cooldown belongs to: the route and the credential reference.
347
+ *
348
+ * Deliberately not per model: a 401 or a 429 describes the credential and its
349
+ * account, and charging the same key a known failure on every model of the route
350
+ * is what a cooldown exists to prevent.
351
+ * @param route - the provider route key.
352
+ * @param ref - the credential reference.
353
+ */
354
+ export declare function restKeyOf(route: string, ref: string): string;
355
+ /** The cooldown memory both seams share for this process. */
356
+ export declare const keyRest: RestStore;
357
+ /** One key as it took part in a plan, without its secret. */
358
+ export interface PlannedKeyTrace {
359
+ readonly ref: string;
360
+ readonly wire: RouteProtocol;
361
+ readonly fit: WireFit;
362
+ readonly honoured: boolean;
363
+ readonly resting: boolean;
364
+ }
365
+ /** The last plan the wire seam built for a request, for `?diag=1`. */
366
+ export interface RoutePlanTrace {
367
+ /** When the plan was built. */
368
+ readonly at: number;
369
+ readonly route: string;
370
+ readonly model: string | undefined;
371
+ readonly wire: RouteProtocol | undefined;
372
+ readonly keys: readonly PlannedKeyTrace[];
373
+ }
374
+ /**
375
+ * Remember a plan for diagnostics. Only references and ranks are kept — never a
376
+ * key value — because the probe route prints these entries to the browser.
377
+ * @param route - the provider route the plan was built for.
378
+ * @param plan - the plan.
379
+ * @param options - the model the plan was built for, and the time.
380
+ */
381
+ export declare function recordRoutePlan(route: string, plan: KeyPlan, options?: {
382
+ readonly model?: string;
383
+ readonly now?: number;
384
+ }): void;
385
+ /** The most recent plans, newest last. */
386
+ export declare function readRoutePlans(limit?: number): readonly RoutePlanTrace[];
387
+ /** Forget the recorded plans. */
388
+ export declare function resetRoutePlans(): void;
389
+ /**
390
+ * Re-sign `headers` with `value` in place, preserving whichever credential
391
+ * scheme the request already used.
392
+ *
393
+ * pi-ai's provider has ALREADY set the auth header from the route's configured
394
+ * key by the time a request reaches the fetch seam; this only swaps the value so
395
+ * the chosen key takes effect without re-deriving the scheme. If neither header
396
+ * is present (a transport that auths elsewhere), a Bearer `authorization` is
397
+ * added. The opposite scheme's header is cleared so two credentials can never
398
+ * ride along together.
399
+ * @param headers - the mutable request headers.
400
+ * @param value - the secret to sign with.
401
+ */
402
+ export declare function applyKeyToHeaders(headers: Headers, value: string): void;
403
+ /** The credential header names, exported for the wire seam's diagnostics. */
404
+ export declare const CREDENTIAL_HEADERS: readonly string[];
405
+ /**
406
+ * Marker the wire seam (headers-pi-ai) stamps on requests it dispatched: it
407
+ * chose that request's key, wire protocol and endpoint, so the fetch seam
408
+ * (headers-fetch) must apply only its header patch and leave the signature and
409
+ * the failover alone — the two seams rank keys differently on purpose, and a
410
+ * re-signing fetch layer would put a different key's credential on a body
411
+ * encoded for the wire seam's choice. Carries a constant value only (never a
412
+ * reference or secret) and is stripped before the request leaves the fetch
413
+ * wrapper.
414
+ */
415
+ export declare const WIRE_DISPATCH_HEADER = "x-dsh-model-think-level-wire";
@@ -109,11 +109,12 @@ export interface KnowledgeEntry {
109
109
  */
110
110
  input?: InputModalities;
111
111
  /**
112
- * Reference context window in tokens (display-only advice; the official
113
- * capacity inputs are never auto-filled).
112
+ * Reference context window in tokens. Rendered as footnote advice, and a
113
+ * mounted row's official capacity input echoes it (fill-only) when a
114
+ * suggestion is applied.
114
115
  */
115
116
  contextWindow?: number;
116
- /** Reference max output tokens in tokens (display-only advice). */
117
+ /** Reference max output tokens in tokens (same echo rule as the context window). */
117
118
  maxTokens?: number;
118
119
  /**
119
120
  * The vendor's own default level for the family, when its docs name one
@@ -174,9 +175,9 @@ export interface EffortSuggestion {
174
175
  input?: InputModalities;
175
176
  /** Where the modality part came from -- its confidence rides this. */
176
177
  inputSource?: InputSource;
177
- /** Reference context window (display-only; never auto-filled anywhere). */
178
+ /** Reference context window; echoed into the row's official capacity input when one is mounted. */
178
179
  contextWindow?: number;
179
- /** Reference max output tokens (display-only). */
180
+ /** Reference max output tokens (same echo rule as the context window). */
180
181
  maxTokens?: number;
181
182
  /** Whether a knowledge-base entry matched (vs protocol inference). */
182
183
  matched: boolean;
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Reading one provider's raw model listing.
3
+ *
4
+ * The same rules govern every place this plugin interrogates an endpoint: the
5
+ * probe route (the browser half's auto-adapt), the key panel's discover op, and
6
+ * the merged model discovery the provider card performs. The listing URL,
7
+ * the request headers, the response ceiling, and the one parser for both reply
8
+ * shapes therefore live here once, and mirror the harness's own discovery
9
+ * (`@deepseek-ai/dsh-llm-pi-ai`) exactly — a listing this module reads is a
10
+ * listing the official fetch reads, character for character.
11
+ *
12
+ * @module dsh-model-think-level/listing
13
+ */
14
+ /** Stable API version required by Anthropic's model-listing endpoint. */
15
+ export declare const ANTHROPIC_VERSION = "2023-06-01";
16
+ /** Largest model-list page accepted by Anthropic's public endpoint. */
17
+ export declare const ANTHROPIC_MODEL_LIMIT = 1000;
18
+ /** Largest model-list page requested of Gemini's native endpoint. */
19
+ export declare const GEMINI_MODEL_LIMIT = 1000;
20
+ /** Largest listing reply a probe accepts (the official discovery's bound). */
21
+ export declare const MAX_RESPONSE_BYTES: number;
22
+ /** Protocols whose model listing this module can read (the harness discovery set, plus the plugin's pinned Gemini). */
23
+ export declare const LISTABLE_PROTOCOLS: ReadonlySet<string>;
24
+ /**
25
+ * A URL safe to echo in responses: a baseURL may carry userinfo
26
+ * (https://user:pass@host), and failure messages must never repeat it.
27
+ */
28
+ export declare function displayUrl(raw: string): string;
29
+ /**
30
+ * Probe-listing URL, mirroring the harness's own model discovery:
31
+ * OpenAI-compatible protocols list at `{baseURL}/models`; Anthropic Messages
32
+ * uses its native route at `{root}/v1/models?limit=1000`, where the root is the
33
+ * base without trailing slashes and without one trailing `/v1` segment
34
+ * (gateway documentation publishes both spellings of the same root). Gemini's
35
+ * native protocol lists at `{base}/v1beta/models?pageSize=1000` on the same
36
+ * version-qualified base its requests speak (see {@link geminiRequestBaseUrl}).
37
+ */
38
+ export declare function probeListingUrl(baseURL: string, api: string): string;
39
+ /**
40
+ * pi-ai's Anthropic SDK appends `/v1/messages` to the model base URL. Accept
41
+ * either gateway spelling (`https://host` or `https://host/v1`) while keeping
42
+ * the request endpoint at exactly `/v1/messages`.
43
+ */
44
+ export declare function anthropicRequestBaseUrl(baseURL: string): string;
45
+ /**
46
+ * The base URL a Gemini-native request needs. pi-ai's Google client takes
47
+ * `model.baseUrl` verbatim with `apiVersion: ''`, so the version segment must
48
+ * already sit in the path; a bare origin is completed with `/v1beta` (the
49
+ * official spelling), while a path the user spelled out is kept as the
50
+ * gateway's own.
51
+ */
52
+ export declare function geminiRequestBaseUrl(baseURL: string): string;
53
+ /**
54
+ * Compose the raw-models probe request's headers, mirroring the discipline of
55
+ * the harness's own model discovery: the provider
56
+ * profile's configured request headers form the base (deployment-owned
57
+ * credentials like `x-api-key` ride along), `accept` is always JSON, and a
58
+ * resolved credential's Bearer overwrites a profile `authorization` — which
59
+ * survives only when no credential resolves (a route may authenticate through
60
+ * its configured headers alone). Anthropic Messages answers through
61
+ * `x-api-key` plus a fixed `anthropic-version`, and its Bearer arm is never
62
+ * used (a profile `authorization` survives untouched there, exactly as the
63
+ * official discovery leaves it). Entries Fetch would refuse are dropped
64
+ * rather than failing the probe. Harness attribution headers are deliberately
65
+ * not sent — this is a same-origin diagnostic, not a harness request.
66
+ * @param profileHeaders - the profile's raw `headers` dict (simply absent
67
+ * on older documents).
68
+ * @param apiKey - the resolved credential, when one resolved.
69
+ * @param api - the profile's wire protocol.
70
+ */
71
+ export declare function composeProbeHeaders(profileHeaders: unknown, apiKey: string | undefined, api: string): Record<string, string>;
72
+ /**
73
+ * Read a listing reply body, refusing one that outgrows the ceiling (the same
74
+ * bound the official discovery applies). A declared length is checked first
75
+ * so an honest server is turned away without transferring anything; the
76
+ * accumulated total is what actually enforces the bound.
77
+ */
78
+ export declare function readBounded(response: Response, url: string): Promise<string>;
79
+ /**
80
+ * Normalize a supported listing reply into one entry array, mirroring the
81
+ * official parser: the standard `data` array takes precedence; the
82
+ * enriched `models` map uses each property key as the endpoint-facing id
83
+ * (the nested `id` only falls back for an empty key — gateways may put a
84
+ * canonical identity there instead of the alias they accept on requests);
85
+ * Gemini's native `models` ARRAY unwraps each `models/<id>` resource name into
86
+ * the bare id the request path needs, keeps only entries a chat request can
87
+ * address (`generateContent`), and reads the display label from
88
+ * `displayName` (the raw `name` is the resource path, not a label). Only
89
+ * object-valued entries are models, and entries without a usable id are
90
+ * dropped. Returns undefined when the listing names none of these shapes.
91
+ */
92
+ export declare function listingEntries(body: unknown): Record<string, unknown>[] | undefined;
93
+ /**
94
+ * One model a listing advertises, in the shape the harness's model discovery
95
+ * reports: the endpoint-facing id, and whatever presentation metadata the
96
+ * endpoint offered. A source without the optional fields yields just the id,
97
+ * which every consumer (`adopt()` on the Models card) treats as complete.
98
+ */
99
+ export interface ListedModel {
100
+ id: string;
101
+ name?: string;
102
+ contextWindow?: number;
103
+ maxTokens?: number;
104
+ /** Textual inputs a model advertises, when the endpoint names them. */
105
+ inputModalities?: string[];
106
+ }
107
+ /**
108
+ * Read a listing reply into the models it advertises, in endpoint order.
109
+ *
110
+ * This is the mirror of the official `readListing`, extended with the idle
111
+ * metadata the Models page can adopt: a name/display label, a context window,
112
+ * an output ceiling, and input modalities when the endpoint names them. Ids are
113
+ * trimmed and de-duplicated because the merged discovery appends one endpoint's
114
+ * list to another's, and a duplicate row would render twice in the picker.
115
+ * @param body - the decoded JSON reply.
116
+ * @returns the models, or undefined when the reply names neither listing shape.
117
+ */
118
+ export declare function modelsFromListing(body: unknown): ListedModel[] | undefined;
@@ -0,0 +1,101 @@
1
+ /**
2
+ * One model catalogue from a route's several keys.
3
+ *
4
+ * A provider route may hold more than one key, and the keys need not see the
5
+ * same models: an Anthropic-pinned key answers a different listing than the
6
+ * OpenAI-family one, and a gateway can give two OpenAI keys different quotas
7
+ * while advertising different catalogues. Probing each key separately answers
8
+ * "what does THIS key serve" — the question routing needs — but a picker and a
9
+ * "detect models" button both ask the other question: "what does this provider
10
+ * serve at all?". This module answers that one by keeping, per model, the keys
11
+ * that advertised it.
12
+ *
13
+ * Two rules are inherited from the gateway practice this mirrors (magpie's
14
+ * `fetchPerKey`):
15
+ * - a model advertised by several keys is ONE model, listing every key that
16
+ * serves it;
17
+ * - a key whose listing could not be read this time keeps the models it was
18
+ * last seen serving, instead of making them disappear from the catalogue
19
+ * (those models are reported as `retained`, so a caller can say the scope is
20
+ * stale rather than fresh).
21
+ *
22
+ * The catalogue reads in one natural id order (`numeric` collation, so a model
23
+ * family keeps version order), not in the order the keys were asked: a
24
+ * catalogue assembled key by key would read as one key's list with the next
25
+ * key's extras appended, scattering one letter across both ends.
26
+ *
27
+ * Probing is the caller's job: {@link collectKeyListings} only bounds how many
28
+ * probes run at once and merges what comes back, so the panel, the `discover`
29
+ * operation and the fetch overlay all share one merge.
30
+ *
31
+ * @module dsh-model-think-level/multi-key-listing
32
+ */
33
+ import type { KeyProbeResult } from './key-probe.js';
34
+ /** How many probes run at once unless the caller says otherwise. */
35
+ export declare const DEFAULT_PROBE_CONCURRENCY = 4;
36
+ /** One model in the merged catalogue and the keys that advertised it. */
37
+ export interface MergedModel {
38
+ readonly id: string;
39
+ /** The keys whose listing named this model, in key-list order. */
40
+ readonly keys: readonly string[];
41
+ }
42
+ /** A route's whole catalogue, merged across the keys that were asked. */
43
+ export interface MergedListing {
44
+ /** The models, in natural id order, each naming its keys. */
45
+ readonly models: readonly MergedModel[];
46
+ /** Just the ids, in the same order (what a picker or a patch needs). */
47
+ readonly ids: readonly string[];
48
+ /** Keys that answered this pass. */
49
+ readonly answered: readonly string[];
50
+ /**
51
+ * Keys whose probe produced no scope at all. When a last-known scope exists
52
+ * for one of them, its models are still in the catalogue and the key is
53
+ * reported here — the caller decides whether "stale" is worth saying.
54
+ */
55
+ readonly unreadable: readonly string[];
56
+ /** Keys whose models came from their last-known scope rather than this pass. */
57
+ readonly retained: readonly string[];
58
+ }
59
+ /**
60
+ * Fold per-key probe results into one catalogue.
61
+ *
62
+ * A key with `models === undefined` did not answer; its last-known scope (when
63
+ * one is supplied) keeps its models in the catalogue and marks it `retained`.
64
+ * Without such a scope the key simply contributes nothing to this pass.
65
+ * @param results - one result per key, in key-list order.
66
+ * @param lastKnown - the scopes the keys were seen serving before this pass.
67
+ * @returns the merged catalogue and the per-key bookkeeping.
68
+ */
69
+ export declare function mergeKeyListings(results: readonly KeyProbeResult[], lastKnown?: ReadonlyMap<string, readonly string[]>): MergedListing;
70
+ /** What one collection run needs from its caller. */
71
+ export interface CollectKeyListingsOptions<Key> {
72
+ /** The keys to ask, in the order the catalogue should read. */
73
+ readonly keys: readonly Key[];
74
+ /** Ask one key for its listing (typically `probeKeyModels`). */
75
+ readonly probe: (key: Key) => Promise<KeyProbeResult>;
76
+ /**
77
+ * The ref a key is known by. When given, a probe that THROWS is recorded as
78
+ * that key having no answer (so its last-known scope still survives); without
79
+ * it a throwing probe simply contributes nothing.
80
+ */
81
+ readonly refOf?: (key: Key) => string;
82
+ /** How many probes may be in flight; at least 1. Defaults to 4. */
83
+ readonly concurrency?: number;
84
+ /** The scopes the keys were seen serving before this pass. */
85
+ readonly lastKnown?: ReadonlyMap<string, readonly string[]>;
86
+ }
87
+ /**
88
+ * Probe every key with bounded concurrency, then merge the answers.
89
+ *
90
+ * Kept in key order regardless of which probe finished first: the per-key
91
+ * bookkeeping reads in the keys' preference order, not by network luck. (The
92
+ * catalogue itself reads in id order — see {@link mergeKeyListings}.) A probe
93
+ * that throws contributes nothing for its key (the caller's own probe decides
94
+ * what "no answer" means); the remaining probes still run.
95
+ * @param options - the keys, how to probe one, and the concurrency bound.
96
+ * @returns the results in key order, plus the merged catalogue.
97
+ */
98
+ export declare function collectKeyListings<Key>(options: CollectKeyListingsOptions<Key>): Promise<{
99
+ results: KeyProbeResult[];
100
+ merged: MergedListing;
101
+ }>;