dsh-model-think-level 2.0.2 → 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 (61) hide show
  1. package/README.md +49 -23
  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 +34 -16
  6. package/lib/client/KeyManager.d.ts +2 -2
  7. package/lib/client/balance-client.d.ts +34 -0
  8. package/lib/client/capacity.d.ts +20 -4
  9. package/lib/client/configured-inputs.d.ts +11 -2
  10. package/lib/client/events.d.ts +31 -2
  11. package/lib/client/fingerprint-runner.d.ts +13 -1
  12. package/lib/client/image-config-client.d.ts +75 -0
  13. package/lib/client/injection/autofill-run.d.ts +2 -2
  14. package/lib/client/injection/config-button-seat.d.ts +96 -0
  15. package/lib/client/injection/create-key-seat.d.ts +3 -3
  16. package/lib/client/injection/create-keys-pane.d.ts +4 -2
  17. package/lib/client/injection/editor-tab-bar.d.ts +1 -1
  18. package/lib/client/injection/editor-tabs.d.ts +1 -1
  19. package/lib/client/injection/image-card.d.ts +85 -0
  20. package/lib/client/injection/imagegen-completion.d.ts +43 -0
  21. package/lib/client/injection/imagegen-entry.d.ts +22 -0
  22. package/lib/client/injection/key-prefetch.d.ts +44 -0
  23. package/lib/client/injection/key-reveal.d.ts +2 -3
  24. package/lib/client/injection/models-page-editor.d.ts +59 -28
  25. package/lib/client/injection/models-page.d.ts +15 -3
  26. package/lib/client/injection/provider-balance.d.ts +83 -0
  27. package/lib/client/injection/provider-endpoints.d.ts +2 -2
  28. package/lib/client/injection/row-drag.d.ts +7 -0
  29. package/lib/client/injection/staged-keys.d.ts +24 -12
  30. package/lib/client/key-manager-client.d.ts +70 -18
  31. package/lib/client/locales.d.ts +65 -15
  32. package/lib/client/ops.d.ts +12 -2
  33. package/lib/client/styles.d.ts +1 -1
  34. package/lib/client/types.d.ts +21 -3
  35. package/lib/client.js +721 -78
  36. package/lib/client.js.map +4 -4
  37. package/lib/constants.d.ts +58 -0
  38. package/lib/detection.d.ts +7 -0
  39. package/lib/fingerprint/estimate.d.ts +16 -0
  40. package/lib/fingerprint/run.d.ts +24 -0
  41. package/lib/fingerprint/store.d.ts +2 -2
  42. package/lib/fingerprint/verdict.d.ts +53 -3
  43. package/lib/headers-core.d.ts +3 -1
  44. package/lib/headers-fetch.d.ts +25 -0
  45. package/lib/image/command.d.ts +84 -0
  46. package/lib/image/config.d.ts +150 -0
  47. package/lib/image/generate.d.ts +135 -0
  48. package/lib/image/legacy-cleanup.d.ts +29 -0
  49. package/lib/image/sizes.d.ts +28 -0
  50. package/lib/image/tool.d.ts +107 -0
  51. package/lib/index.js +3876 -1745
  52. package/lib/index.js.map +4 -4
  53. package/lib/key-index.d.ts +37 -7
  54. package/lib/key-probe.d.ts +39 -99
  55. package/lib/key-refs.d.ts +43 -19
  56. package/lib/key-route-core.d.ts +100 -32
  57. package/lib/key-serves.d.ts +81 -0
  58. package/lib/knowledge.d.ts +21 -0
  59. package/lib/listing.d.ts +18 -20
  60. package/lib/multi-key-listing.d.ts +3 -3
  61. 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,126 +1,66 @@
1
1
  /**
2
- * Which endpoint a key's model listing is asked of.
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
6
- * pin a protocol of its own. Probing every key against the route's default
7
- * wire would therefore ask half of them a question their credential cannot
8
- * answer — an Anthropic-pinned key returns `401` from an OpenAI gateway, and
9
- * the panel would conclude the key serves nothing. This module derives the
10
- * *protocols a key can actually be used with* from the same facts routing uses
5
+ * address and an Anthropic-family one, and each key may
6
+ * pin a protocol of its own. Asking every key against the route's default wire
7
+ * would therefore ask half of them a question their credential cannot answer —
8
+ * an Anthropic-pinned key returns `401` from an OpenAI gateway. The probe
9
+ * targets a key may be asked of are derived from the same facts routing uses
11
10
  * (the pin, the route's api, and the stored endpoints), so a probe is only
12
- * sent where a request would go.
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 and the plan says
18
- * why;
19
- * - a same-family pin (Responses vs Chat Completions) rides the route's own
20
- * address: only the wire changes, so the listing is asked there;
21
- * - a key with no pin is AUTOMATIC (the request speaks the model family's own
22
- * wire where the provider addressed it), so it is probed on the route's wire
23
- * and additionally on every other family's address the route configured —
24
- * that is the only way to learn that the key also reaches the models of
25
- * those families.
15
+ * The exact rules live on {@link listingTargetsOf}, the one derivation every
16
+ * caller shares.
26
17
  *
27
18
  * @module dsh-model-think-level/key-probe
28
19
  */
29
- import { type EndpointFamily, type RouteEndpoints, type RouteProtocol } from './key-refs.js';
30
- import { listingEntries } from './listing.js';
20
+ import type { EndpointFamily, RouteEndpoints, RouteProtocol } from './key-refs.js';
31
21
  export type { EndpointFamily };
32
22
  /** The protocol a probe speaks on a family when it has no more specific pin. */
33
23
  export declare const FAMILY_PROTOCOL: Readonly<Record<EndpointFamily, RouteProtocol>>;
34
- /** The listing request one key should be sent. */
24
+ /** One address a key's listing may be asked on. */
35
25
  export interface ProbeTarget {
36
26
  readonly api: RouteProtocol;
37
27
  readonly baseURL: string;
38
- readonly family: EndpointFamily;
39
- }
40
- /** What a key's probe would ask, and why it asks nothing when it asks nothing. */
41
- export interface ProbePlan {
42
- readonly targets: readonly ProbeTarget[];
43
- /** Set when no legal request exists for this key (its pin cannot be honoured). */
44
- readonly skipped?: string;
45
- }
46
- /** The routing facts a probe plan is derived from. */
47
- export interface ProbeIntent {
48
- /** The route's own wire (the provider profile's `api`). */
49
- readonly api: unknown;
50
- /** The route's own address. */
51
- readonly baseURL: string;
52
- /** The protocol this key pinned, when it pinned one. */
53
- readonly pinned?: RouteProtocol | undefined;
54
- /** The route's stored endpoint pair, when the storage has one. */
55
- readonly endpoints?: RouteEndpoints | undefined;
56
28
  }
57
29
  /**
58
- * The listing requests one key should receive.
59
- *
60
- * Every target is a request a real call could also make: the protocol is one
61
- * the key would be dispatched to, and the address is the one that protocol
62
- * would use. Targets are de-duplicated by what they would actually fetch — a
63
- * same-family pin shares its family's address with the route's own wire, and a
64
- * gateway that spells one listing under both protocols must not be asked twice.
65
- * @param intent - the route's wire and address, the key's pin, the endpoint pair.
66
- * @returns the targets in preference order, or a skip reason when none apply.
30
+ * What one key's probe learned, as the catalogue merge reads it.
67
31
  */
68
- export declare function probePlanFor(intent: ProbeIntent): ProbePlan;
69
- /** One target's outcome, in the shape the panel can render. */
70
- export interface ProbeTargetOutcome {
71
- readonly api: RouteProtocol;
72
- readonly family: EndpointFamily;
73
- /** The URL asked, with userinfo stripped so a stored `user:pass@` never leaks. */
74
- readonly url: string;
75
- readonly ok: boolean;
76
- /** HTTP status when the endpoint answered at all. */
77
- readonly status?: number;
78
- /** How many distinct models this target advertised. */
79
- readonly models?: number;
80
- /** Why this target did not answer, when it did not. */
81
- readonly error?: string;
82
- }
83
- /** What one key's probe learned. */
84
32
  export interface KeyProbeResult {
85
33
  readonly ref: string;
86
34
  /**
87
- * The key's new scope: the union of every target that answered. Undefined
88
- * when no target answered — the caller must then keep the previous scope
89
- * rather than recording "serves nothing".
35
+ * The key's scope: the union of every address that answered. Undefined when
36
+ * no address answered — the caller must then keep the previous scope rather
37
+ * than recording "serves nothing".
90
38
  */
91
39
  readonly models: string[] | undefined;
92
- readonly targets: readonly ProbeTargetOutcome[];
93
- /** Set when the plan had no legal target at all (see {@link probePlanFor}). */
94
- readonly skipped?: string;
95
40
  }
96
- /** Transport and credentials one key's probe needs. */
97
- export interface ProbeKeyOptions {
98
- readonly ref: string;
99
- readonly intent: ProbeIntent;
100
- /** The resolved credential; a probe is always signed by the key it asks about. */
101
- readonly apiKey: string;
102
- /** The route profile's configured headers (deployment-owned values ride along). */
103
- readonly profileHeaders: unknown;
104
- readonly timeoutMs: number;
105
- readonly send: (url: string, init: RequestInit) => Promise<Response>;
106
- /** How to sign one listing request for one protocol. */
107
- readonly headersFor: (profileHeaders: unknown, apiKey: string, api: RouteProtocol) => Record<string, string>;
108
- /** Reads a bounded listing body. */
109
- readonly read: (response: Response, url: string) => Promise<string>;
110
- /** Parses a listing body into entries; undefined when it names no listing shape. */
111
- readonly entries: (body: unknown) => Record<string, unknown>[] | undefined;
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;
112
49
  }
113
50
  /**
114
- * Ask one key for its models on every address it can legitimately be used with.
51
+ * The addresses one key's listing may be asked on, deduplicated by listing URL.
115
52
  *
116
- * A target that fails is reported and does not cancel the others: a key that
117
- * serves only the Anthropic family still records those models when its OpenAI
118
- * family probe is refused. When at least one target answers, the key's scope
119
- * becomes the union of the answers; an endpoint answering with an empty listing
120
- * is a real answer ("this key serves none") and yields `[]`.
121
- * @param options - the key, its routing facts, and the transport readers.
122
- * @returns the scope to store and the per-target report.
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.
123
65
  */
124
- export declare function probeKeyModels(options: ProbeKeyOptions): Promise<KeyProbeResult>;
125
- /** Re-exported so the entry module does not import two listing names for one op. */
126
- export { listingEntries as parseListingEntries };
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;