dsh-model-think-level 2.0.3 → 2.1.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 (55) hide show
  1. package/README.md +38 -22
  2. package/lib/balance.d.ts +44 -0
  3. package/lib/client/ComposerSlider.d.ts +19 -0
  4. package/lib/client/ConfigPane.d.ts +47 -0
  5. package/lib/client/EffortEditor.d.ts +1 -8
  6. package/lib/client/KeyManager.d.ts +2 -2
  7. package/lib/client/balance-client.d.ts +34 -0
  8. package/lib/client/events.d.ts +31 -2
  9. package/lib/client/image-config-client.d.ts +75 -0
  10. package/lib/client/injection/autofill-run.d.ts +2 -2
  11. package/lib/client/injection/config-button-seat.d.ts +96 -0
  12. package/lib/client/injection/create-key-seat.d.ts +3 -3
  13. package/lib/client/injection/create-keys-pane.d.ts +4 -2
  14. package/lib/client/injection/editor-tab-bar.d.ts +1 -1
  15. package/lib/client/injection/editor-tabs.d.ts +1 -1
  16. package/lib/client/injection/image-card.d.ts +85 -0
  17. package/lib/client/injection/imagegen-completion.d.ts +43 -0
  18. package/lib/client/injection/imagegen-entry.d.ts +22 -0
  19. package/lib/client/injection/key-prefetch.d.ts +44 -0
  20. package/lib/client/injection/key-reveal.d.ts +2 -3
  21. package/lib/client/injection/models-page-editor.d.ts +24 -27
  22. package/lib/client/injection/models-page.d.ts +15 -3
  23. package/lib/client/injection/provider-balance.d.ts +83 -0
  24. package/lib/client/injection/provider-endpoints.d.ts +2 -2
  25. package/lib/client/injection/row-drag.d.ts +7 -0
  26. package/lib/client/injection/staged-keys.d.ts +24 -12
  27. package/lib/client/key-manager-client.d.ts +68 -17
  28. package/lib/client/locales.d.ts +60 -6
  29. package/lib/client/ops.d.ts +1 -0
  30. package/lib/client/styles.d.ts +1 -1
  31. package/lib/client/types.d.ts +4 -1
  32. package/lib/client.js +672 -13
  33. package/lib/client.js.map +4 -4
  34. package/lib/constants.d.ts +45 -0
  35. package/lib/fingerprint/estimate.d.ts +16 -0
  36. package/lib/fingerprint/run.d.ts +6 -0
  37. package/lib/fingerprint/store.d.ts +2 -2
  38. package/lib/fingerprint/verdict.d.ts +24 -0
  39. package/lib/headers-core.d.ts +3 -1
  40. package/lib/headers-fetch.d.ts +25 -0
  41. package/lib/image/command.d.ts +84 -0
  42. package/lib/image/config.d.ts +150 -0
  43. package/lib/image/generate.d.ts +135 -0
  44. package/lib/image/legacy-cleanup.d.ts +29 -0
  45. package/lib/image/sizes.d.ts +28 -0
  46. package/lib/image/tool.d.ts +107 -0
  47. package/lib/index.js +3666 -1534
  48. package/lib/index.js.map +4 -4
  49. package/lib/key-index.d.ts +37 -7
  50. package/lib/key-probe.d.ts +42 -17
  51. package/lib/key-refs.d.ts +43 -19
  52. package/lib/key-route-core.d.ts +100 -32
  53. package/lib/key-serves.d.ts +81 -0
  54. package/lib/listing.d.ts +18 -20
  55. package/package.json +1 -8
@@ -40,6 +40,15 @@ export interface KeyIndexDocument {
40
40
  * "no extra endpoints" (every key falls back to the route's own `baseURL`).
41
41
  */
42
42
  readonly endpoints?: Record<string, RouteEndpoints>;
43
+ /**
44
+ * Route → the URL that answers that provider's remaining balance.
45
+ *
46
+ * A balance endpoint is display-only: requests never use it, so it lives
47
+ * beside the key metadata rather than in the pi-ai profile. Absent (or a
48
+ * route without an entry) means "not configured", which is what the Models
49
+ * page reads to decide whether to show a balance at all.
50
+ */
51
+ readonly balances?: Record<string, string>;
43
52
  }
44
53
  /** A fresh, empty index. */
45
54
  export declare function emptyKeyIndex(): KeyIndexDocument;
@@ -90,19 +99,29 @@ export declare function withKeyEntry(document: KeyIndexDocument, route: string,
90
99
  */
91
100
  export declare function withKeyAlias(document: KeyIndexDocument, route: string, ref: string, alias: string | undefined): KeyIndexDocument;
92
101
  /**
93
- * Set (or clear) one key's discovered model scope.
94
- *
95
- * This is the automatic-binding side of Scheme A: the host probes each key's
96
- * model listing and records what it reached here, so a later request for model
97
- * M can be routed to the first key that lists M. Passing `undefined` clears the
98
- * scope back to "unscoped catch-all"; an empty array records "probed, reached
99
- * no models". A no-op when the reference is not listed.
102
+ * Set (or clear) the user's model assignment. `undefined` means catch-all, and
103
+ * an empty array remains a concrete empty assignment.
100
104
  * @param document - the current document.
101
105
  * @param route - the provider route key.
102
106
  * @param ref - the credential reference.
103
107
  * @param models - the ids this key serves, or undefined to unscope it.
104
108
  */
105
109
  export declare function withKeyModels(document: KeyIndexDocument, route: string, ref: string, models: readonly string[] | undefined): KeyIndexDocument;
110
+ /**
111
+ * Write the probe's model assignment, marking it as maintained.
112
+ *
113
+ * This is the host's post-save probe speaking, not the user: the scope is
114
+ * rewritten on every probe pass until a manual edit (via {@link withKeyModels})
115
+ * claims it. `undefined` stores a marked catch-all — the probe found the key
116
+ * serving every declared model, and the catch-all is both the honest reading
117
+ * and the one that keeps serving models added later.
118
+ * @param document - the current document.
119
+ * @param route - the provider route key.
120
+ * @param ref - the credential reference.
121
+ * @param models - the ids the probe observed within the route's declared set,
122
+ * or undefined for a maintained catch-all.
123
+ */
124
+ export declare function withKeyAutoScope(document: KeyIndexDocument, route: string, ref: string, models: readonly string[] | undefined): KeyIndexDocument;
106
125
  /**
107
126
  * Set (or clear) one key's pinned wire protocol.
108
127
  *
@@ -139,6 +158,17 @@ export declare function withKeyDisabled(document: KeyIndexDocument, route: strin
139
158
  * @param endpoints - the OpenAI/Anthropic base URLs, or undefined to clear both.
140
159
  */
141
160
  export declare function withRouteEndpoints(document: KeyIndexDocument, route: string, endpoints: RouteEndpoints | undefined): KeyIndexDocument;
161
+ /**
162
+ * Set (or clear) one route's balance endpoint.
163
+ *
164
+ * The URL is display-only and independent of the protocol-family addresses, so
165
+ * it is stored in its own map: writing endpoints never clears a balance URL and
166
+ * writing a balance URL never disturbs the routing addresses.
167
+ * @param document - the current document.
168
+ * @param route - the provider route key.
169
+ * @param endpoint - the URL to store, or undefined/blank to clear it.
170
+ */
171
+ export declare function withRouteBalance(document: KeyIndexDocument, route: string, endpoint: string | undefined): KeyIndexDocument;
142
172
  /**
143
173
  * Drop one key. The route key itself is removed once its list empties, so a
144
174
  * provider the user cleaned up leaves no residue in the file.
@@ -1,35 +1,34 @@
1
1
  /**
2
- * Shared facts of per-key model probing.
2
+ * Shared facts and target derivation of per-key model probing.
3
3
  *
4
4
  * A key is not tied to one protocol: a route can answer on an OpenAI-family
5
- * address, an Anthropic-family one and a Gemini-family one, and each key may
5
+ * address and an Anthropic-family one, and each key may
6
6
  * pin a protocol of its own. Asking every key against the route's default wire
7
7
  * would therefore ask half of them a question their credential cannot answer —
8
8
  * an Anthropic-pinned key returns `401` from an OpenAI gateway. The probe
9
9
  * targets a key may be asked of are derived from the same facts routing uses
10
10
  * (the pin, the route's api, and the stored endpoints), so a probe is only
11
- * sent where a request would go; the fetch overlay that assembles a provider's
12
- * catalogue (`modelListing` in the entry module) derives them inline.
11
+ * sent where a request would go — wherever a per-key listing is wanted, from
12
+ * the fetch overlay that assembles a provider's catalogue to the post-save
13
+ * probe that auto-checks each key's scope.
13
14
  *
14
- * The rules mirror routing ({@link module:key-route-core}):
15
- * - a pin is honoured only when its family has an address; a cross-family pin
16
- * with no address for that family is NOT probed, because no request could be
17
- * served that way either — the key keeps its previous scope;
18
- * - a same-family pin (Responses vs Chat Completions) rides the route's own
19
- * address: only the wire changes, so the listing is asked there;
20
- * - a key with no pin is AUTOMATIC (the request speaks the model family's own
21
- * wire where the provider addressed it), so it is probed on the route's wire
22
- * and additionally on every other family's address the route configured —
23
- * that is the only way to learn that the key also reaches the models of
24
- * those families.
15
+ * The exact rules live on {@link listingTargetsOf}, the one derivation every
16
+ * caller shares.
25
17
  *
26
18
  * @module dsh-model-think-level/key-probe
27
19
  */
28
- import type { EndpointFamily, RouteProtocol } from './key-refs.js';
20
+ import type { EndpointFamily, RouteEndpoints, RouteProtocol } from './key-refs.js';
29
21
  export type { EndpointFamily };
30
22
  /** The protocol a probe speaks on a family when it has no more specific pin. */
31
23
  export declare const FAMILY_PROTOCOL: Readonly<Record<EndpointFamily, RouteProtocol>>;
32
- /** What one key's probe learned, as the catalogue merge reads it. */
24
+ /** One address a key's listing may be asked on. */
25
+ export interface ProbeTarget {
26
+ readonly api: RouteProtocol;
27
+ readonly baseURL: string;
28
+ }
29
+ /**
30
+ * What one key's probe learned, as the catalogue merge reads it.
31
+ */
33
32
  export interface KeyProbeResult {
34
33
  readonly ref: string;
35
34
  /**
@@ -39,3 +38,29 @@ export interface KeyProbeResult {
39
38
  */
40
39
  readonly models: string[] | undefined;
41
40
  }
41
+ /** The per-key probe facts a target derivation reads (the routing scope's shape). */
42
+ export interface ProbeKeyShape {
43
+ /** The wire this key pins, when it pins one. */
44
+ readonly protocol?: RouteProtocol;
45
+ /** The base URL a pinned key signs against (its family's address). */
46
+ readonly endpoint?: string;
47
+ /** The family addresses an UNPINNED key may dispatch on. */
48
+ readonly endpoints?: RouteEndpoints;
49
+ }
50
+ /**
51
+ * The addresses one key's listing may be asked on, deduplicated by listing URL.
52
+ *
53
+ * The rules mirror routing (key-route-core):
54
+ * - a pin is honoured only through its own wire; its address is the family's
55
+ * stored endpoint when the route configured one, the route's own URL
56
+ * otherwise (a same-family pin rides the route's address — only the wire
57
+ * changes, and the route's URL serves that family);
58
+ * - an unpinned key is AUTOMATIC (the request speaks the model family's own
59
+ * wire where the provider addressed it), so it is asked on the route's wire
60
+ * plus every cross-family address the route configured — the only way to
61
+ * learn that the key also reaches those families' models;
62
+ * - targets whose listing this plugin cannot read, and addresses that are
63
+ * empty, are dropped; a gateway that spells one listing under two protocols
64
+ * is asked once.
65
+ */
66
+ export declare function listingTargetsOf(key: ProbeKeyShape, routeAPI: RouteProtocol, routeBaseURL: string): ProbeTarget[];
package/lib/key-refs.d.ts CHANGED
@@ -23,21 +23,26 @@ export interface KeyEntry {
23
23
  /** User-facing label; absent means "show the reference itself". */
24
24
  readonly alias?: string;
25
25
  /**
26
- * The model ids this key is known to serve, discovered from the provider's
27
- * model listing. Absent means "unscoped": the key has not been probed yet, so
28
- * it acts as a catch-all and serves any model no other key claims. An empty
29
- * array means the key was probed and reached no models at all.
30
- *
31
- * Presence, not order, is what matters here: a model reachable through
32
- * several keys is served by the first key (in list order) that lists it, so
33
- * list order doubles as the preference order the user asked for.
26
+ * The user's model assignment. Absent means a catch-all; an empty array is a
27
+ * concrete empty assignment. Nothing but the user's explicit choice may
28
+ * change this field — except a scope the host's own post-save probe wrote
29
+ * (marked by {@link KeyEntry.auto}, and re-written by that probe on every
30
+ * later pass until the user claims the scope with a manual edit).
34
31
  */
35
32
  readonly models?: readonly string[];
33
+ /**
34
+ * Whether the model scope is the probe's assignment rather than the user's.
35
+ * The host rewrites an auto scope whenever it re-probes the route; a manual
36
+ * scope edit clears the mark, and a manually claimed scope is never touched
37
+ * by the probe again. Absent means the scope (or the catch-all) is the
38
+ * user's, or has never been assigned at all.
39
+ */
40
+ readonly auto?: boolean;
36
41
  /**
37
42
  * The wire protocol this key must speak, when it is pinned to one.
38
43
  * Absent means AUTOMATIC: each request speaks the wire the model's own family
39
- * names — an Anthropic-family endpoint for claude models, the Gemini one for
40
- * gemini models, the route's default for everything else — as far as the
44
+ * names — an Anthropic-family endpoint for claude models, the route's default
45
+ * for everything else — as far as the
41
46
  * provider configured that family's endpoint. A concrete value re-dispatches
42
47
  * every request through that protocol's API implementation AND that key's
43
48
  * endpoint, so one provider route can hold a Chat-Completions key and an
@@ -56,16 +61,14 @@ export interface KeyEntry {
56
61
  /**
57
62
  * The pi-ai API ids the manager can pin a key to. These are the exact ids
58
63
  * `providers.<route>.api` carries, so a key pinned to one speaks the same wire
59
- * format the official card would have produced for that protocol — with one
60
- * addition: `google-generative-ai` names a protocol the harness's own adapter
61
- * registry does not offer at route level, so it can only ever appear as a
62
- * per-key pin riding the gemini family's endpoint.
64
+ * format the official card would have produced for that protocol. Only the
65
+ * host-supported OpenAI and Anthropic protocols are offered.
63
66
  */
64
- export type RouteProtocol = 'openai-completions' | 'anthropic-messages' | 'openai-responses' | 'google-generative-ai';
67
+ export type RouteProtocol = 'openai-completions' | 'anthropic-messages' | 'openai-responses';
65
68
  /** Every protocol a key can be pinned to, in the order the picker shows them. */
66
69
  export declare const ROUTE_PROTOCOLS: readonly RouteProtocol[];
67
70
  /** The endpoint families a protocol can draw its base URL from. */
68
- export type EndpointFamily = 'openai' | 'anthropic' | 'gemini';
71
+ export type EndpointFamily = 'openai' | 'anthropic';
69
72
  /** Every endpoint family, in the order address rows and pickers show them. */
70
73
  export declare const ENDPOINT_FAMILIES: readonly EndpointFamily[];
71
74
  /** Which endpoint family a protocol draws its base URL from. */
@@ -94,9 +97,18 @@ export declare function normalizeKeyProtocol(value: unknown): RouteProtocol | un
94
97
  * @returns `true` when the key is switched off, else undefined.
95
98
  */
96
99
  export declare function normalizeKeyDisabled(value: unknown): boolean | undefined;
100
+ /**
101
+ * A stored probe-maintained mark, or undefined when the scope is not the
102
+ * probe's. Only a literal `true` counts — the same rule as
103
+ * {@link normalizeKeyDisabled} — so a hand-edited index file cannot half-claim
104
+ * the mark, and an entry never carries a redundant `auto: false`.
105
+ * @param value - whatever arrived (the probe's write, or a hand-edited file).
106
+ * @returns `true` when the scope is the probe's assignment, else undefined.
107
+ */
108
+ export declare function normalizeKeyAuto(value: unknown): boolean | undefined;
97
109
  /**
98
110
  * The base URLs one provider route can hold, one per endpoint family: an
99
- * OpenAI-family endpoint, an Anthropic-family endpoint and a Gemini-family one.
111
+ * OpenAI-family endpoint and an Anthropic-family endpoint.
100
112
  * A key pinned to a protocol uses the matching one; an automatic key (no pin)
101
113
  * dispatches a model to the entry of the family the model's id names, and to
102
114
  * the route's own `providers.<route>.baseURL` otherwise.
@@ -106,8 +118,6 @@ export interface RouteEndpoints {
106
118
  readonly openai?: string;
107
119
  /** Base URL for anthropic-messages keys. */
108
120
  readonly anthropic?: string;
109
- /** Base URL for google-generative-ai keys (version path included, `…/v1beta`). */
110
- readonly gemini?: string;
111
121
  }
112
122
  /**
113
123
  * A stored set of endpoints, or undefined when none carries a usable URL.
@@ -119,6 +129,20 @@ export interface RouteEndpoints {
119
129
  * @returns the cleaned set, or undefined when it holds no endpoint.
120
130
  */
121
131
  export declare function normalizeRouteEndpoints(value: unknown): RouteEndpoints | undefined;
132
+ /**
133
+ * A stored balance endpoint, or undefined when the value carries nothing usable.
134
+ *
135
+ * This is the one URL a provider may add beside its base addresses: the host
136
+ * queries it (with that route's enabled key) and the Models page shows the
137
+ * amount in front of the provider's enable switch. It is not a request endpoint
138
+ * and never takes part in routing, so it is kept outside {@link RouteEndpoints}
139
+ * — a route may configure a balance URL without configuring either family
140
+ * address, and vice versa. Blank and non-http(s) values are dropped rather than
141
+ * stored, so "no balance endpoint" stays distinguishable from an empty string.
142
+ * @param value - whatever arrived (the card's balance field, or a hand-edited file).
143
+ * @returns the trimmed URL, or undefined when there is none.
144
+ */
145
+ export declare function normalizeBalanceEndpoint(value: unknown): string | undefined;
122
146
  /**
123
147
  * A stored model-scope list, or undefined when the value carries nothing usable.
124
148
  *
@@ -10,12 +10,20 @@
10
10
  * - A model only one key can serve sticks to that key.
11
11
  * - When a request errors, the next capable key is tried.
12
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).
13
+ * "Can serve" is read from TWO different kinds of knowledge, which are never
14
+ * mixed up:
15
+ * - an ASSIGNMENT ({@link KeyCandidate.models}): the user's own scope. A scope
16
+ * that lists the model can serve it; a scope that does not is an exact
17
+ * denial; an UNSCOPED key is a catch-all that serves whatever is left
18
+ * (the state before a key has been scoped, and the way a user says "this
19
+ * key takes whatever is left");
20
+ * - an OBSERVATION ({@link ServingKnowledge}): what each key's `/models`
21
+ * listing advertised the last time it answered. Keys on one route can sit
22
+ * in different upstream groups, so "key B lists this model, key A does not"
23
+ * is a real fact about the pair — but only when a sibling DOES list it: a
24
+ * failed listing is not an empty one, and a key nobody probed stays a
25
+ * candidate. This is the case a per-key scope cannot express, because the
26
+ * user never assigned anything and the first key is a catch-all.
19
27
  *
20
28
  * Eligible keys keep their list order, so the "both can serve -> first key"
21
29
  * and "only one can -> that key" rules both fall out of a single filter. If NO
@@ -41,7 +49,10 @@
41
49
  * cannot re-dispatch, so it trails the keys that can (it is never dropped: a
42
50
  * lone key must still sign the request);
43
51
  * - 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.
52
+ * instead of being charged the same failure again on the next request. A
53
+ * failure that names THIS model ({@link classifyFailure}'s `unserved`) rests
54
+ * only the (key, model) pair, so a key that carries one group's models and
55
+ * not another's keeps serving the ones it does carry.
45
56
  *
46
57
  * The wire seam alone ranks by wire, because only it can act on a pin; the fetch
47
58
  * seam only consults the cooldown memory, since it can neither switch a protocol
@@ -57,16 +68,16 @@ export interface KeyCandidate {
57
68
  /** The secret to put on the wire. */
58
69
  readonly value: string;
59
70
  /**
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.
71
+ * Model ids this key is known to serve. `undefined` means "unscoped":
72
+ * deliberately left as a catch-all. An array (possibly empty) is a concrete
73
+ * scope.
63
74
  */
64
75
  readonly models?: readonly string[];
65
76
  /**
66
77
  * The wire protocol this key must speak, when it is pinned to one.
67
78
  * `undefined` means AUTOMATIC: the request speaks whichever wire the model's
68
79
  * own family names — an Anthropic-family endpoint for claude models, the
69
- * Gemini one for gemini models, the route's default for everything else —
80
+ * route's default for everything else —
70
81
  * as far as the key carries that family's address in {@link endpoints}.
71
82
  * A concrete value makes the wire seam re-dispatch the request through that
72
83
  * protocol's API implementation (a true protocol switch), using {@link endpoint}.
@@ -86,22 +97,49 @@ export interface KeyCandidate {
86
97
  */
87
98
  readonly endpoints?: Readonly<Partial<Record<EndpointFamily, string>>>;
88
99
  }
89
- /** Whether `key` can serve `model`, per the scope rules above. */
90
- export declare function canServe(key: KeyCandidate, model: string | undefined): boolean;
100
+ /**
101
+ * What the plugin has OBSERVED about one route's keys, as opposed to what the
102
+ * user ASSIGNED in each key's `models`.
103
+ *
104
+ * A listing says what an account's upstream group actually carries; an
105
+ * assignment says what the user ordered. They answer different questions, so
106
+ * they travel separately: an assignment always wins, and an observation only
107
+ * decides between keys the user left unscoped.
108
+ */
109
+ export interface ServingKnowledge {
110
+ /**
111
+ * Each reference's last successful listing: the model ids that key's
112
+ * `/models` answer advertised. A reference with NO entry never answered and
113
+ * is therefore unknown — never "serves nothing", because a failed listing must
114
+ * not be read as an empty one.
115
+ */
116
+ readonly listed: ReadonlyMap<string, readonly string[]>;
117
+ }
118
+ /**
119
+ * Whether `key` can serve `model`, per the assignment and observation rules.
120
+ * @param key - the candidate, with its manual scope (if any).
121
+ * @param model - the model id the request names, or undefined when unknown.
122
+ * @param knowledge - what the route's keys were last observed serving.
123
+ */
124
+ export declare function canServe(key: KeyCandidate, model: string | undefined, knowledge?: ServingKnowledge): boolean;
91
125
  /**
92
126
  * Order the keys that may sign a request for `model`, most-preferred first.
93
127
  *
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
128
+ * The result is the eligible keys in their original list order, grouped into
129
+ * four tiers: a key the user assigned this model to, then a key whose own
130
+ * listing advertises it, then a key nothing is known about, then — last, when no
131
+ * sibling lists it either — a key that was probed and does not carry it. When
132
+ * the filter leaves nothing, all keys are returned unchanged (last resort) — the
96
133
  * caller's failover loop still bounds the attempts, so an over-eager scope is
97
134
  * corrected on the wire rather than failing the request outright.
98
135
  * @param keys - the route's keys in preference order (may be empty).
99
136
  * @param model - the model id the request names, or undefined when unknown.
137
+ * @param knowledge - what the route's keys were last observed serving.
100
138
  * @returns the ordered candidates to try.
101
139
  */
102
- export declare function keysForModel(keys: readonly KeyCandidate[], model: string | undefined): KeyCandidate[];
140
+ export declare function keysForModel(keys: readonly KeyCandidate[], model: string | undefined, knowledge?: ServingKnowledge): KeyCandidate[];
103
141
  /** The wire families: one body format and one endpoint shape each. */
104
- export type WireFamily = 'anthropic' | 'openai' | 'gemini';
142
+ export type WireFamily = 'anthropic' | 'openai';
105
143
  /** The family a protocol draws its body format and endpoint from. */
106
144
  export declare function wireFamilyOf(protocol: RouteProtocol): WireFamily;
107
145
  /** The family a model id announces, or undefined when it announces none. */
@@ -111,8 +149,8 @@ export declare function modelWireFamily(modelId: string | undefined): WireFamily
111
149
  *
112
150
  * The OpenAI family has two wires (Chat Completions and Responses), so no id can
113
151
  * 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
152
+ * The Anthropic family has exactly one wire, so a key pinned to it needs no
153
+ * translation for a model of that family and deserves the
116
154
  * first attempt.
117
155
  * @param modelId - the model id the request names, or undefined.
118
156
  * @returns the concrete protocol, or undefined when the id does not settle one.
@@ -122,8 +160,8 @@ export declare function modelWireHint(modelId: string | undefined): RouteProtoco
122
160
  * The wire an AUTOMATIC key (no pin) dispatches for `model`.
123
161
  *
124
162
  * 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
163
+ * the Anthropic address — but only when the key actually carries that family's
164
+ * address; any
127
165
  * other model (or a family the route itself serves) keeps the route's default
128
166
  * wire, which is the one dispatch that always works. A wire that just failed
129
167
  * this model before any content (`avoid`) is skipped as the automatic choice —
@@ -259,18 +297,25 @@ export declare function planKeys(candidates: readonly KeyCandidate[], options: P
259
297
  /**
260
298
  * Whether an HTTP status is worth retrying on the next key. Authentication and
261
299
  * 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.
300
+ * and server faults are all "this key did not work, try the next"; a bare
301
+ * 400/404/422 is a request-shape problem that every key would answer identically,
302
+ * so it is returned to the caller unchanged rather than multiplied across keys.
303
+ *
304
+ * The one exception is a 400/404/422 whose BODY names the model as unsupported:
305
+ * that is not a request-shape problem at all but a fact about this key's upstream
306
+ * group (a multi-account relay answers exactly this way for a model another
307
+ * account carries), so it fails over like any other key-level refusal.
265
308
  * @param status - the response status code.
309
+ * @param bodyText - the (bounded) response body, when the caller has read it.
266
310
  */
267
- export declare function shouldFailover(status: number): boolean;
311
+ export declare function shouldFailover(status: number, bodyText?: string): boolean;
268
312
  /**
269
313
  * Why a key failed, as far as the next request is concerned. The distinction is
270
314
  * only between "this key is the problem" and "every key would repeat it", which
271
- * is why a 400 has no kind at all.
315
+ * is why a bare 400 has no kind at all — and between "this key" and "this key
316
+ * for THIS model", which is why `unserved` exists.
272
317
  */
273
- export type FailureKind = 'auth' | 'rate' | 'quota' | 'server' | 'timeout' | 'refused';
318
+ export type FailureKind = 'auth' | 'rate' | 'quota' | 'server' | 'timeout' | 'refused' | 'unserved';
274
319
  /**
275
320
  * What a failed attempt says about the key, or undefined when it says nothing —
276
321
  * a request-shape failure (400/404/422) that every key would answer identically.
@@ -343,15 +388,38 @@ export declare const REST_STORE_LIMIT = 256;
343
388
  */
344
389
  export declare function createRestStore(limit?: number): RestStore;
345
390
  /**
346
- * The key a cooldown belongs to: the route and the credential reference.
391
+ * The key a cooldown belongs to: the route and the credential reference, plus
392
+ * the model when the failure was about ONE model rather than the credential.
347
393
  *
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.
394
+ * A 401 or a 429 describes the credential and its account, so charging the same
395
+ * key a known failure on every model of the route is exactly what a cooldown
396
+ * exists to prevent. An `unserved` refusal is narrower: the account's group
397
+ * carries some models and not others, so benching the whole key would throw away
398
+ * the models it does carry. Those pass a `model` and get a pair-scoped entry.
399
+ * @param route - the provider route key.
400
+ * @param ref - the credential reference.
401
+ * @param model - the model the refusal named, when the cooldown is pair-scoped.
402
+ */
403
+ export declare function restKeyOf(route: string, ref: string, model?: string | undefined): string;
404
+ /**
405
+ * Whether a key should be deferred for this request: it may be benched as a
406
+ * whole, or benched for this model alone.
407
+ * @param store - the cooldown memory.
408
+ * @param route - the provider route key.
409
+ * @param ref - the credential reference.
410
+ * @param model - the model this request names.
411
+ * @param now - the clock.
412
+ */
413
+ export declare function isRestingFor(store: RestStore, route: string, ref: string, model: string | undefined, now: number): boolean;
414
+ /**
415
+ * Retire every cooldown a successful attempt disproves: the key works, and for
416
+ * this model it works too.
417
+ * @param store - the cooldown memory.
351
418
  * @param route - the provider route key.
352
419
  * @param ref - the credential reference.
420
+ * @param model - the model that just answered.
353
421
  */
354
- export declare function restKeyOf(route: string, ref: string): string;
422
+ export declare function clearRest(store: RestStore, route: string, ref: string, model?: string | undefined): void;
355
423
  /** The cooldown memory both seams share for this process. */
356
424
  export declare const keyRest: RestStore;
357
425
  /** One key as it took part in a plan, without its secret. */
@@ -0,0 +1,81 @@
1
+ /**
2
+ * What each key's own listing said it serves — the observed half of routing.
3
+ *
4
+ * A provider route fans one request shape out over several credentials, and a
5
+ * relay may resolve each of them to a different upstream ACCOUNT with its own
6
+ * catalogue: one key's group carries `gpt-6.1-sol`, another key's group does not
7
+ * and answers "Model ... is not supported by any configured account in this
8
+ * group". The plugin cannot derive that split from configuration — keys are
9
+ * opaque references and the upstream group an account belongs to is declared
10
+ * nowhere — so it records what it observed: every successful model listing per
11
+ * key, with the moment it was taken.
12
+ *
13
+ * `canServe` and `keysForModel` read these observations as a preference and a
14
+ * guardrail (see key-route-core.ts), never as an assertion: a list that could not
15
+ * be read is UNKNOWN, not empty, and a model no key lists is still tried on
16
+ * every key — the provider, not the plugin, has the last word.
17
+ *
18
+ * The document is derived, not authored: losing it costs a round of failed
19
+ * requests until the next listing, never correctness. It is therefore parsed
20
+ * leniently — a malformed entry is dropped instead of thrown over — unlike the
21
+ * key index, which holds what the user wrote.
22
+ *
23
+ * @module dsh-model-think-level/key-serves
24
+ */
25
+ /** What one key's last successful listing advertised. */
26
+ export interface KeyServesEntry {
27
+ /** Model ids, as the listing sent them, de-duplicated and in listing order. */
28
+ readonly models: readonly string[];
29
+ /** When that listing was read (epoch ms), so a client merge can tell ages apart. */
30
+ readonly at: number;
31
+ }
32
+ /** Every route's per-key observations. */
33
+ export interface KeyServesDocument {
34
+ readonly version: 1;
35
+ readonly providers: Readonly<Record<string, Readonly<Record<string, KeyServesEntry>>>>;
36
+ }
37
+ /** A fresh, empty document. */
38
+ export declare function emptyKeyServes(): KeyServesDocument;
39
+ /** Absolute path of the observation document beside the key index. */
40
+ export declare function keyServesFilePath(home?: string): string;
41
+ /**
42
+ * Parse an already-decoded document, dropping whatever does not fit. Never
43
+ * throws: this file is a cache of observations, so a corrupt one is an empty one.
44
+ * @param raw - the decoded JSON value (or anything else).
45
+ * @returns a well-formed document.
46
+ */
47
+ export declare function parseKeyServes(raw: unknown): KeyServesDocument;
48
+ /**
49
+ * Read the document. Never throws: an absent file and an unreadable one both
50
+ * mean "nothing observed yet".
51
+ * @param file - document path (tests pass a temp file).
52
+ */
53
+ export declare function readKeyServes(file?: string): KeyServesDocument;
54
+ /** Write the document at one path, atomically. */
55
+ export declare function writeKeyServes(document: KeyServesDocument, file?: string): void;
56
+ /** What one key last advertised, or undefined when it was never listed. */
57
+ export declare function servesOf(document: KeyServesDocument, route: string, ref: string): readonly string[] | undefined;
58
+ /**
59
+ * One route's observations, keyed by reference — the shape `canServe` reads.
60
+ * @param document - the observation document.
61
+ * @param route - the provider route.
62
+ */
63
+ export declare function servesOfRoute(document: KeyServesDocument, route: string): ReadonlyMap<string, readonly string[]>;
64
+ /**
65
+ * Record one key's listing, replacing whatever it said before. A key with an
66
+ * empty catalogue is dropped from the document: an empty list would assert
67
+ * "serves nothing", which is the reading this module exists to avoid.
68
+ * @param document - the current document.
69
+ * @param route - the provider route.
70
+ * @param ref - the credential reference.
71
+ * @param models - the listing's model ids.
72
+ * @param at - when the listing was read (epoch ms).
73
+ */
74
+ export declare function withServes(document: KeyServesDocument, route: string, ref: string, models: readonly string[], at: number): KeyServesDocument;
75
+ /**
76
+ * Forget one key's observations, for a key that was removed or re-pointed.
77
+ * @param document - the current document.
78
+ * @param route - the provider route.
79
+ * @param ref - the credential reference.
80
+ */
81
+ export declare function withoutServes(document: KeyServesDocument, route: string, ref: string): KeyServesDocument;
package/lib/listing.d.ts CHANGED
@@ -15,25 +15,35 @@
15
15
  export declare const ANTHROPIC_VERSION = "2023-06-01";
16
16
  /** Largest model-list page accepted by Anthropic's public endpoint. */
17
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
18
  /** Largest listing reply a probe accepts (the official discovery's bound). */
21
19
  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). */
20
+ /** Protocols whose model listing this module can read (the harness discovery set). */
23
21
  export declare const LISTABLE_PROTOCOLS: ReadonlySet<string>;
24
22
  /**
25
23
  * A URL safe to echo in responses: a baseURL may carry userinfo
26
- * (https://user:pass@host), and failure messages must never repeat it.
24
+ * (https://user:pass@host) or a key in its query (?api_key=… — a common relay
25
+ * spelling), and failure messages must never repeat either. The path is what
26
+ * identifies the probe; credentials live in the userinfo and the query, both
27
+ * of which are dropped, along with the fragment. A string that is not a
28
+ * parseable URL is replaced with a placeholder — echoing the raw input back
29
+ * would defeat the whole point (the opaque `user:pass@host` spelling parses
30
+ * as a non-special scheme whose userinfo setters are no-ops).
27
31
  */
28
32
  export declare function displayUrl(raw: string): string;
33
+ /**
34
+ * Redact credential-bearing URL shapes from free-form error text: any
35
+ * `user:password@` authority (with or without a scheme — the opaque spelling
36
+ * parses as scheme+path and survives URL-level stripping) loses its secret.
37
+ * Applied to upstream error messages before they reach a response body, since
38
+ * undici's own texts quote the original URL verbatim.
39
+ */
40
+ export declare function redactUrlSecrets(text: string): string;
29
41
  /**
30
42
  * Probe-listing URL, mirroring the harness's own model discovery:
31
43
  * OpenAI-compatible protocols list at `{baseURL}/models`; Anthropic Messages
32
44
  * uses its native route at `{root}/v1/models?limit=1000`, where the root is the
33
45
  * 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}).
46
+ * (gateway documentation publishes both spellings of the same root).
37
47
  */
38
48
  export declare function probeListingUrl(baseURL: string, api: string): string;
39
49
  /**
@@ -42,14 +52,6 @@ export declare function probeListingUrl(baseURL: string, api: string): string;
42
52
  * the request endpoint at exactly `/v1/messages`.
43
53
  */
44
54
  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
55
  /**
54
56
  * Compose the raw-models probe request's headers, mirroring the discipline of
55
57
  * the harness's own model discovery: the provider
@@ -81,11 +83,7 @@ export declare function readBounded(response: Response, url: string): Promise<st
81
83
  * official parser: the standard `data` array takes precedence; the
82
84
  * enriched `models` map uses each property key as the endpoint-facing id
83
85
  * (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
86
+ * canonical identity there instead of the alias they accept on requests). Only
89
87
  * object-valued entries are models, and entries without a usable id are
90
88
  * dropped. Returns undefined when the listing names none of these shapes.
91
89
  */