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.
- package/README.md +38 -22
- package/lib/balance.d.ts +44 -0
- package/lib/client/ComposerSlider.d.ts +19 -0
- package/lib/client/ConfigPane.d.ts +47 -0
- package/lib/client/EffortEditor.d.ts +1 -8
- package/lib/client/KeyManager.d.ts +2 -2
- package/lib/client/balance-client.d.ts +34 -0
- package/lib/client/events.d.ts +31 -2
- package/lib/client/image-config-client.d.ts +75 -0
- package/lib/client/injection/autofill-run.d.ts +2 -2
- package/lib/client/injection/config-button-seat.d.ts +96 -0
- package/lib/client/injection/create-key-seat.d.ts +3 -3
- package/lib/client/injection/create-keys-pane.d.ts +4 -2
- package/lib/client/injection/editor-tab-bar.d.ts +1 -1
- package/lib/client/injection/editor-tabs.d.ts +1 -1
- package/lib/client/injection/image-card.d.ts +85 -0
- package/lib/client/injection/imagegen-completion.d.ts +43 -0
- package/lib/client/injection/imagegen-entry.d.ts +22 -0
- package/lib/client/injection/key-prefetch.d.ts +44 -0
- package/lib/client/injection/key-reveal.d.ts +2 -3
- package/lib/client/injection/models-page-editor.d.ts +24 -27
- package/lib/client/injection/models-page.d.ts +15 -3
- package/lib/client/injection/provider-balance.d.ts +83 -0
- package/lib/client/injection/provider-endpoints.d.ts +2 -2
- package/lib/client/injection/row-drag.d.ts +7 -0
- package/lib/client/injection/staged-keys.d.ts +24 -12
- package/lib/client/key-manager-client.d.ts +68 -17
- package/lib/client/locales.d.ts +60 -6
- package/lib/client/ops.d.ts +1 -0
- package/lib/client/styles.d.ts +1 -1
- package/lib/client/types.d.ts +4 -1
- package/lib/client.js +672 -13
- package/lib/client.js.map +4 -4
- package/lib/constants.d.ts +45 -0
- package/lib/fingerprint/estimate.d.ts +16 -0
- package/lib/fingerprint/run.d.ts +6 -0
- package/lib/fingerprint/store.d.ts +2 -2
- package/lib/fingerprint/verdict.d.ts +24 -0
- package/lib/headers-core.d.ts +3 -1
- package/lib/headers-fetch.d.ts +25 -0
- package/lib/image/command.d.ts +84 -0
- package/lib/image/config.d.ts +150 -0
- package/lib/image/generate.d.ts +135 -0
- package/lib/image/legacy-cleanup.d.ts +29 -0
- package/lib/image/sizes.d.ts +28 -0
- package/lib/image/tool.d.ts +107 -0
- package/lib/index.js +3666 -1534
- package/lib/index.js.map +4 -4
- package/lib/key-index.d.ts +37 -7
- package/lib/key-probe.d.ts +42 -17
- package/lib/key-refs.d.ts +43 -19
- package/lib/key-route-core.d.ts +100 -32
- package/lib/key-serves.d.ts +81 -0
- package/lib/listing.d.ts +18 -20
- package/package.json +1 -8
package/lib/key-index.d.ts
CHANGED
|
@@ -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)
|
|
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.
|
package/lib/key-probe.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
12
|
-
*
|
|
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
|
|
15
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
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
|
|
40
|
-
*
|
|
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
|
|
60
|
-
*
|
|
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'
|
|
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'
|
|
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
|
|
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
|
*
|
package/lib/key-route-core.d.ts
CHANGED
|
@@ -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
|
|
14
|
-
*
|
|
15
|
-
* - an
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
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":
|
|
61
|
-
*
|
|
62
|
-
*
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
90
|
-
|
|
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
|
|
95
|
-
*
|
|
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'
|
|
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
|
|
115
|
-
*
|
|
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
|
|
126
|
-
* address
|
|
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
|
|
263
|
-
* is a request-shape problem that every key would answer identically,
|
|
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
|
-
*
|
|
349
|
-
*
|
|
350
|
-
*
|
|
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
|
|
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
|
|
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)
|
|
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).
|
|
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
|
*/
|