dsh-fallback-router 0.0.0-stage → 0.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/LICENSE +21 -0
- package/README.md +162 -2
- package/README.zh-CN.md +170 -0
- package/bundle/cordis.patch.yml +19 -0
- package/dist/authorized-route.d.ts +68 -0
- package/dist/automatch.d.ts +98 -0
- package/dist/chains.d.ts +186 -0
- package/dist/client/ConversationFallbackSwitch.d.ts +91 -0
- package/dist/client/FallbacksCard.d.ts +36 -0
- package/dist/client/GeneralFallbacksRow.d.ts +19 -0
- package/dist/client/ModelsPanel.d.ts +64 -0
- package/dist/client/SubagentRoleBadge.d.ts +53 -0
- package/dist/client/fallbacks-store.d.ts +631 -0
- package/dist/client/index.d.ts +64 -0
- package/dist/client/index.js +3420 -0
- package/dist/client/locales.d.ts +454 -0
- package/dist/client/switch-guard.d.ts +17 -0
- package/dist/client/use-snapshot.d.ts +11 -0
- package/dist/commands.d.ts +380 -0
- package/dist/config.d.ts +239 -0
- package/dist/cooldown.d.ts +57 -0
- package/dist/events.d.ts +52 -0
- package/dist/gateway.d.ts +359 -0
- package/dist/index.d.ts +195 -0
- package/dist/index.js +4587 -0
- package/dist/models.d.ts +306 -0
- package/dist/override.d.ts +39 -0
- package/dist/presets.d.ts +20 -0
- package/dist/recovery.d.ts +92 -0
- package/dist/role-notice.d.ts +184 -0
- package/dist/role-persona.d.ts +71 -0
- package/dist/role-projection-key.d.ts +41 -0
- package/dist/role-projection.d.ts +152 -0
- package/dist/role-resolution.d.ts +105 -0
- package/dist/roles.d.ts +90 -0
- package/dist/route-allowlist.d.ts +43 -0
- package/dist/schema.d.ts +46 -0
- package/dist/seeds.d.ts +237 -0
- package/dist/selectors.d.ts +38 -0
- package/dist/state.d.ts +205 -0
- package/dist/subagent-policy.d.ts +123 -0
- package/dist/subagents-seam.d.ts +305 -0
- package/dist/time-slots.d.ts +147 -0
- package/dist/tui-settings.d.ts +145 -0
- package/dist/tui.d.ts +63 -0
- package/dist/virtual-adapter.d.ts +259 -0
- package/icon.svg +16 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +138 -6
|
@@ -0,0 +1,631 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fallbacks settings controller — the client half's own store (slot owner
|
|
3
|
+
* props are empty; data rides this store, per the `plugins.bundle.config`
|
|
4
|
+
* card contract).
|
|
5
|
+
*
|
|
6
|
+
* Read path: the fallbacks config rides the plugin's own gateway channel —
|
|
7
|
+
* `connection.rpc.call('/api', 'fallbacks/get', { args: {} })` — NOT the
|
|
8
|
+
* apiproxy wire: after the settings-exposure patches are gone the
|
|
9
|
+
* `fallbacks` namespace is absent from `settings.describe` on every host
|
|
10
|
+
* (like `advisor` is). `settings.describe({})` is still called, but only
|
|
11
|
+
* for the top-level `writable` flag (host read-only mode) and the namespace
|
|
12
|
+
* directory (the configured-provider join reads model-provider namespaces).
|
|
13
|
+
* A `get` that does not resolve (transport down / gateway not ready / no
|
|
14
|
+
* settings service on the host) is NOT a page error — `state.present` goes
|
|
15
|
+
* false and the section keeps the usable defaults skeleton (KD-G5).
|
|
16
|
+
*
|
|
17
|
+
* Write path: `save(next)` → `rpc.call('/api', 'fallbacks/set', { args: {
|
|
18
|
+
* patch: next } })` (the full edited config is the patch — a merge with all
|
|
19
|
+
* keys present is a full overwrite); `resetToDefaults()` →
|
|
20
|
+
* `rpc.call('/api', 'fallbacks/reset', { args: {} })` (the host clears the
|
|
21
|
+
* user layer via `settings.replace(ns, {})` — the removal path a merge
|
|
22
|
+
* cannot express). The gateway channel has NO revision guard: any
|
|
23
|
+
* `set`/`reset` failure (business rejection or transport) surfaces its
|
|
24
|
+
* message in `state.error` for the section's error banner (KD-G3 — the old
|
|
25
|
+
* `settings-conflict` branch is gone).
|
|
26
|
+
*/
|
|
27
|
+
import type { LlmConfigurableProvider, ModelCatalog, ModelProviderGroup, SessionFollowFrame, SessionFollowRequest, SessionId, SettingsDescribeValue, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client';
|
|
28
|
+
import type { SessionEventLikeEntry } from '@deepseek-ai/dsh-api-session-controller/client';
|
|
29
|
+
import type { ClientConnectionRpc } from '@deepseek-ai/dsh-client-connection/client';
|
|
30
|
+
import { type SnapshotStore } from '@deepseek-ai/dsh-client-store';
|
|
31
|
+
import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
|
|
32
|
+
import { type FallbackStrategy, type FallbacksConfig, type FallbacksRole, type FallbacksRoleRule, type FallbacksRoles } from '../config.ts';
|
|
33
|
+
import type { SlotRowConfig } from '../time-slots.ts';
|
|
34
|
+
import type { FallbacksSwitchEventData } from '../events.ts';
|
|
35
|
+
import type { SeedsWireStatus } from '../seeds.ts';
|
|
36
|
+
/** The plugin's settings namespace on the host wire (settings/document-updated ns filter). */
|
|
37
|
+
export declare const FALLBACKS_SETTINGS_NS = "fallbacks";
|
|
38
|
+
/** Single-page history read for the status block (spec §2.5 D-5: `HISTORY_PAGE_MESSAGES`-sized). */
|
|
39
|
+
export declare const SWITCHES_HISTORY_PAGE = 50;
|
|
40
|
+
/** How many recent switches the status block renders (spec §2.5 D-5: N=5). */
|
|
41
|
+
export declare const RECENT_SWITCH_LIMIT = 5;
|
|
42
|
+
/**
|
|
43
|
+
* One recent `fallbacks/switch` event as the status block renders it: the
|
|
44
|
+
* durable payload plus the raw event's ordering key and time (the payload
|
|
45
|
+
* itself carries no seq/time — spec §5 table).
|
|
46
|
+
*/
|
|
47
|
+
export interface FallbacksSwitchSnapshot extends FallbacksSwitchEventData {
|
|
48
|
+
/** Event seq within the session (newest-first ordering key). */
|
|
49
|
+
seq: number;
|
|
50
|
+
/** Event time, Unix epoch milliseconds. */
|
|
51
|
+
time: number;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The status block's derived "current effective model" (spec §2.5 D-6) — a
|
|
55
|
+
* **display value** derived from configuration + recent switches, never a
|
|
56
|
+
* live route probe.
|
|
57
|
+
*/
|
|
58
|
+
export type EffectiveModelView =
|
|
59
|
+
/** ① An inactive config (nothing configured) or an empty rootChain. */
|
|
60
|
+
{
|
|
61
|
+
kind: 'unavailable';
|
|
62
|
+
}
|
|
63
|
+
/** ② The most recent switch's target (`to`). */
|
|
64
|
+
| {
|
|
65
|
+
kind: 'switched';
|
|
66
|
+
provider: string;
|
|
67
|
+
model: string;
|
|
68
|
+
}
|
|
69
|
+
/** ③ No switches yet: the config's primary target (first chain entry). */
|
|
70
|
+
| {
|
|
71
|
+
kind: 'config';
|
|
72
|
+
provider: string;
|
|
73
|
+
model: string;
|
|
74
|
+
};
|
|
75
|
+
/** Fallbacks settings-row snapshot. */
|
|
76
|
+
export interface FallbacksSettingsState {
|
|
77
|
+
status: 'idle' | 'loading' | 'ready' | 'saving' | 'error';
|
|
78
|
+
error: string | null;
|
|
79
|
+
/** Whether the provider allows writes at all (describe top-level flag). */
|
|
80
|
+
writable: boolean;
|
|
81
|
+
/** The resolved configuration (last accepted gateway response, or the defaults skeleton). */
|
|
82
|
+
config: FallbacksConfig;
|
|
83
|
+
/**
|
|
84
|
+
* Whether the `fallbacks/get` gateway channel resolved on the last load.
|
|
85
|
+
* `false` = channel unreachable (transport down / gateway not ready / no
|
|
86
|
+
* settings service) → the section keeps the usable skeleton (KD-G5).
|
|
87
|
+
*/
|
|
88
|
+
present: boolean;
|
|
89
|
+
/**
|
|
90
|
+
* Legacy (two-block-era) config keys the gateway detected on the composed
|
|
91
|
+
* source (`get().legacyKeys` / the post-write `set`/`reset` response,
|
|
92
|
+
* spec §9): non-empty → the migration banner renders. The wire field is
|
|
93
|
+
* authoritative — the client never guesses legacy status on its own
|
|
94
|
+
* (detectLegacyClientKeys is a test-only fallback). A `set`/`reset`
|
|
95
|
+
* response WITHOUT the field (older gateway) keeps the last accepted
|
|
96
|
+
* value — only a `get` may settle legacy truth (W-1/F-1: a save merges
|
|
97
|
+
* over the user layer, so it cannot delete legacy keys).
|
|
98
|
+
*/
|
|
99
|
+
legacyKeys: string[];
|
|
100
|
+
/**
|
|
101
|
+
* Seeded-role badge state (spec §9.4): one entry per live seed, with the
|
|
102
|
+
* gateway's override verdict. The wire field is authoritative — absent on
|
|
103
|
+
* an old response it keeps the last accepted value (the `legacyKeys`
|
|
104
|
+
* honest rule: only a `get` may settle seed truth).
|
|
105
|
+
*/
|
|
106
|
+
seeds: SeedsWireStatus[];
|
|
107
|
+
/** Provider/model directory snapshot (spec §2.5 D-4). */
|
|
108
|
+
catalogStatus: 'idle' | 'loading' | 'ready' | 'error';
|
|
109
|
+
/** Catalog read diagnostic: whole-load failure or per-provider lookups. */
|
|
110
|
+
catalogError: string | null;
|
|
111
|
+
/** Configurable-provider directory (`llm/listConfigurableProviders`). */
|
|
112
|
+
providers: LlmConfigurableProvider[];
|
|
113
|
+
/**
|
|
114
|
+
* The provider dropdown's offer set: catalog providers whose settings
|
|
115
|
+
* profile resolves, with the Models page's `configured` join semantics
|
|
116
|
+
* (spec §2.5 — see {@link configuredProvidersOf}). Unconfigured directory
|
|
117
|
+
* providers never appear as options.
|
|
118
|
+
*/
|
|
119
|
+
configuredProviders: LlmConfigurableProvider[];
|
|
120
|
+
/**
|
|
121
|
+
* The picker catalog actually offered to the panel: one entry per CONFIGURED
|
|
122
|
+
* provider, carrying the models that provider's own settings profile already
|
|
123
|
+
* declares (the Models page's enabled list), falling back to the runtime
|
|
124
|
+
* catalog when the profile names none. Directory-only providers stay out —
|
|
125
|
+
* a dropdown that offers providers the user never set up is noise.
|
|
126
|
+
*/
|
|
127
|
+
catalogProviders: CatalogProvider[];
|
|
128
|
+
/** Model catalog groups (`session/modelCatalog`). */
|
|
129
|
+
groups: readonly ModelProviderGroup[];
|
|
130
|
+
/** Bumped on every accepted catalog read; drives row re-classification. */
|
|
131
|
+
catalogEpoch: number;
|
|
132
|
+
/** Recent-switch summary (spec §2.4 R-4a / §2.5 D-5). */
|
|
133
|
+
switchesStatus: 'idle' | 'loading' | 'ready' | 'error';
|
|
134
|
+
/** Switch-read diagnostic (wire message); null when none. */
|
|
135
|
+
switchesError: string | null;
|
|
136
|
+
/** Most recent `fallbacks/switch` events of the current session, newest first. */
|
|
137
|
+
switches: FallbacksSwitchSnapshot[];
|
|
138
|
+
/**
|
|
139
|
+
* Host subagent-model-selection policy (spec D4 / T5). `undefined` when
|
|
140
|
+
* the gateway omitted the additive field (old payload / policy off) —
|
|
141
|
+
* the card hides the status area and never renders an active allowlist.
|
|
142
|
+
*/
|
|
143
|
+
subagentPolicy: SubagentPolicyView | undefined;
|
|
144
|
+
}
|
|
145
|
+
/** Source label of the effective subagent chain head (spec D4). */
|
|
146
|
+
export type SubagentPolicyHeadSource = 'authorized' | 'injected';
|
|
147
|
+
/** One exact route on the additive `subagentPolicy` wire field. */
|
|
148
|
+
export type SubagentPolicyRoute = {
|
|
149
|
+
provider: string;
|
|
150
|
+
model: string;
|
|
151
|
+
};
|
|
152
|
+
/**
|
|
153
|
+
* Client-side view of the additive host-policy payload. Structural twin of
|
|
154
|
+
* the gateway wire type — parsed from unknown, never imported from host
|
|
155
|
+
* modules (`src/client/**` consumes policy only via the gateway channel).
|
|
156
|
+
*/
|
|
157
|
+
export type SubagentPolicyView = {
|
|
158
|
+
state: 'enabled';
|
|
159
|
+
allowedModels: SubagentPolicyRoute[];
|
|
160
|
+
head?: {
|
|
161
|
+
route: SubagentPolicyRoute;
|
|
162
|
+
source: SubagentPolicyHeadSource;
|
|
163
|
+
};
|
|
164
|
+
blockedAttempt?: {
|
|
165
|
+
at: number;
|
|
166
|
+
route: SubagentPolicyRoute;
|
|
167
|
+
reason: string;
|
|
168
|
+
};
|
|
169
|
+
} | {
|
|
170
|
+
state: 'disabled';
|
|
171
|
+
} | {
|
|
172
|
+
state: 'unprovable';
|
|
173
|
+
};
|
|
174
|
+
/**
|
|
175
|
+
* Shape-guard the additive `subagentPolicy` wire field (T5). Malformed
|
|
176
|
+
* payloads resolve to `undefined` (hide the status area) — the store never
|
|
177
|
+
* throws on an old or misshapen field (old-payload tolerance).
|
|
178
|
+
*/
|
|
179
|
+
export declare function parseSubagentPolicyWire(value: unknown): SubagentPolicyView | undefined;
|
|
180
|
+
/**
|
|
181
|
+
* The provider dropdown's offer set (spec §2.5 D-4): catalog providers whose
|
|
182
|
+
* settings profile resolves in the describe namespaces — the Models page's
|
|
183
|
+
* `configured` predicate (`ui-models` store.ts): a provider is configured
|
|
184
|
+
* when its settings namespace exists AND either it addresses the whole
|
|
185
|
+
* section (`settingsPath` empty) or its profile path resolves in the resolved
|
|
186
|
+
* value. Directory-only (unconfigured) providers never become options; the
|
|
187
|
+
* section still renders existing values for them (read-back + annotation) so
|
|
188
|
+
* nothing is lost on save.
|
|
189
|
+
*/
|
|
190
|
+
export declare function configuredProvidersOf(providers: readonly LlmConfigurableProvider[], namespaces: ReadonlyMap<string, SettingsNamespaceView>): LlmConfigurableProvider[];
|
|
191
|
+
/** One reasoning level a model advertises (推理等级). */
|
|
192
|
+
export interface CatalogEffort {
|
|
193
|
+
id: string;
|
|
194
|
+
name: string;
|
|
195
|
+
}
|
|
196
|
+
/** One model row of the picker catalog, with its advertised reasoning levels. */
|
|
197
|
+
export interface CatalogModel {
|
|
198
|
+
id: string;
|
|
199
|
+
name: string;
|
|
200
|
+
/** Empty when the model exposes no 推理等级 at all. */
|
|
201
|
+
efforts: CatalogEffort[];
|
|
202
|
+
/** The level the model picks when the request names none. */
|
|
203
|
+
defaultEffort?: string;
|
|
204
|
+
}
|
|
205
|
+
/** One provider row of the picker catalog. */
|
|
206
|
+
export interface CatalogProvider {
|
|
207
|
+
id: string;
|
|
208
|
+
models: CatalogModel[];
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* The models a provider's own settings profile declares — the same list the
|
|
212
|
+
* Models page edits, so the picker offers exactly the models the user enabled.
|
|
213
|
+
* `undefined` means "the profile says nothing", which lets the caller fall back
|
|
214
|
+
* to the runtime catalog instead of showing an empty dropdown.
|
|
215
|
+
* @param entry - one configurable-provider directory row.
|
|
216
|
+
* @param namespaces - the settings mirror the row's `settingsNs` addresses.
|
|
217
|
+
* @returns the declared models, or undefined when the profile declares none.
|
|
218
|
+
*/
|
|
219
|
+
export declare function declaredModelsOf(entry: LlmConfigurableProvider, namespaces: ReadonlyMap<string, SettingsNamespaceView>): {
|
|
220
|
+
id: string;
|
|
221
|
+
name: string;
|
|
222
|
+
}[] | undefined;
|
|
223
|
+
/**
|
|
224
|
+
* Build the picker catalog: configured providers only, each carrying the models
|
|
225
|
+
* its settings profile declares, else the runtime catalog's list, else nothing
|
|
226
|
+
* (the picker then degrades to free text for that provider). The signed-in
|
|
227
|
+
* DeepSeek account has no settings namespace of its own, so it is offered when
|
|
228
|
+
* — and only when — the runtime catalog reports models for it, which is exactly
|
|
229
|
+
* the Models page's own `accountAvailable` rule.
|
|
230
|
+
* @param providers - configured-provider rows, in directory order.
|
|
231
|
+
* @param namespaces - the settings mirror backing {@link declaredModelsOf}.
|
|
232
|
+
* @param groups - runtime model catalog groups (`session/modelCatalog`).
|
|
233
|
+
* @returns the catalog offered to the panel.
|
|
234
|
+
*/
|
|
235
|
+
export declare function catalogOf(providers: readonly LlmConfigurableProvider[], namespaces: ReadonlyMap<string, SettingsNamespaceView>, groups: readonly ModelProviderGroup[]): CatalogProvider[];
|
|
236
|
+
/**
|
|
237
|
+
* Fold the redacted descriptor value into a complete {@link FallbacksConfig}:
|
|
238
|
+
* missing optional fields take spec §4 defaults; gross type mismatches throw
|
|
239
|
+
* so the UI can surface a broken descriptor instead of mis-rendering.
|
|
240
|
+
*/
|
|
241
|
+
export interface NamedChainEditorRow {
|
|
242
|
+
id: string;
|
|
243
|
+
name: string;
|
|
244
|
+
chain: ChainSelectorRow[];
|
|
245
|
+
}
|
|
246
|
+
export declare function namedChainsToRows(chains: readonly import('../config.ts').NamedFallbackChain[], catalog?: CatalogLookup): NamedChainEditorRow[];
|
|
247
|
+
export declare function rowsToNamedChains(rows: readonly NamedChainEditorRow[]): import('../config.ts').NamedFallbackChain[];
|
|
248
|
+
export declare function parseFallbacksConfig(value: unknown): FallbacksConfig;
|
|
249
|
+
/**
|
|
250
|
+
* Row-level selection state of one provider/model cell (spec §2.5 D-3):
|
|
251
|
+
* a catalog id, an out-of-catalog raw value read back from the server, or
|
|
252
|
+
* nothing (empty / "any"). Serialization always writes the raw string, so an
|
|
253
|
+
* outside value is preserved verbatim — round-trip lossless.
|
|
254
|
+
*/
|
|
255
|
+
export type CatalogSelection = {
|
|
256
|
+
kind: 'catalog';
|
|
257
|
+
id: string;
|
|
258
|
+
} | {
|
|
259
|
+
kind: 'outside';
|
|
260
|
+
raw: string;
|
|
261
|
+
} | null;
|
|
262
|
+
/** The catalog faces row conversions classify raw values against (D-4). */
|
|
263
|
+
export interface CatalogLookup {
|
|
264
|
+
providers: readonly LlmConfigurableProvider[];
|
|
265
|
+
groups: readonly ModelProviderGroup[];
|
|
266
|
+
}
|
|
267
|
+
/** The raw selector string a selection serializes to ('' when empty). */
|
|
268
|
+
export declare function selectionToRaw(selection: CatalogSelection): string;
|
|
269
|
+
/**
|
|
270
|
+
* Classify a raw provider value against the catalog: a catalog route id is a
|
|
271
|
+
* catalog selection, anything else is an outside value kept verbatim.
|
|
272
|
+
*/
|
|
273
|
+
export declare function classifyProvider(raw: string, catalog: CatalogLookup | undefined): CatalogSelection;
|
|
274
|
+
/**
|
|
275
|
+
* Classify a raw model value under its provider against the catalog: a model
|
|
276
|
+
* id advertised by that provider is a catalog selection, anything else is an
|
|
277
|
+
* outside value kept verbatim.
|
|
278
|
+
*/
|
|
279
|
+
export declare function classifyModel(provider: string, raw: string, catalog: CatalogLookup | undefined): CatalogSelection;
|
|
280
|
+
/**
|
|
281
|
+
* Extract the most recent `fallbacks/switch` events from one history page
|
|
282
|
+
* (spec §2.5 D-5): drop packed chunk runs, filter by event type, order by
|
|
283
|
+
* `seq` descending, take at most `limit`. Single-page read — fewer than
|
|
284
|
+
* `limit` events show as-is; no multi-page backfill (Non-Goal).
|
|
285
|
+
*/
|
|
286
|
+
export declare function extractRecentSwitches(entries: readonly SessionEventLikeEntry[], limit?: number): FallbacksSwitchSnapshot[];
|
|
287
|
+
/**
|
|
288
|
+
* Derive the "current effective model" (spec §2.5 D-6): ① inactive (nothing
|
|
289
|
+
* configured — the removed `enabled` switch re-keyed to `isFallbackActive`)
|
|
290
|
+
* / empty rootChain → unavailable; ② a recent switch exists → the latest
|
|
291
|
+
* one's `to`; ③ otherwise → the config's primary target. A **display
|
|
292
|
+
* value** — never a live route probe.
|
|
293
|
+
*
|
|
294
|
+
* INTENTIONAL D-6 CONTRACT RETENTION: after the AC-2 trim (plan
|
|
295
|
+
* fallbacks-settings-visibility Task 2) the settings card's status block no
|
|
296
|
+
* longer consumes this derivation, and no other production code imports it —
|
|
297
|
+
* it is retained (NOT dead code to delete) as the spec §2.5 D-6 derived-value
|
|
298
|
+
* surface, pinned by `tests/fallbacks-store.spec.ts` (D-6 display-value
|
|
299
|
+
* contract). Keep both exports until the spec derivation is removed or gains
|
|
300
|
+
* a real consumer.
|
|
301
|
+
*/
|
|
302
|
+
export declare function deriveEffectiveModel(config: FallbacksConfig, switches: readonly FallbacksSwitchSnapshot[]): EffectiveModelView;
|
|
303
|
+
/** One chain selector row: provider + model (or wildcard). */
|
|
304
|
+
export interface ChainSelectorRow {
|
|
305
|
+
/** `provider/*` wildcard entry: the model part is absent. */
|
|
306
|
+
wildcard: boolean;
|
|
307
|
+
provider: CatalogSelection;
|
|
308
|
+
/** Null when wildcard (or the entry carries no model part). */
|
|
309
|
+
model: CatalogSelection;
|
|
310
|
+
}
|
|
311
|
+
/** Serialize one selector row to its wire string (`provider/model` | `provider/*`). */
|
|
312
|
+
export declare function selectorRowToRaw(row: ChainSelectorRow): string;
|
|
313
|
+
/**
|
|
314
|
+
* One rootChain row in the editor: the root agent's single fallback chain
|
|
315
|
+
* (block 1 of the two-block model) as an ordered selector list. There is no
|
|
316
|
+
* key input — the row IS the chain.
|
|
317
|
+
*/
|
|
318
|
+
export interface RootChainRow {
|
|
319
|
+
selectors: ChainSelectorRow[];
|
|
320
|
+
}
|
|
321
|
+
/** Project the rootChain entries into editable rows (one flat chain row). */
|
|
322
|
+
export declare function rootChainToRows(rootChain: readonly string[], catalog?: CatalogLookup): RootChainRow[];
|
|
323
|
+
/** Rebuild the rootChain from edited rows; rows with no usable selector drop out. */
|
|
324
|
+
export declare function rowsToRootChain(rows: readonly RootChainRow[]): string[];
|
|
325
|
+
/**
|
|
326
|
+
* One extra time-slot row in the editor (plan fallbacks-timeslots Task 3):
|
|
327
|
+
* preset rows freeze their windows (read-only summary, models-only edits);
|
|
328
|
+
* custom rows edit start/end/days + chain. `kind` rides the wire VERBATIM —
|
|
329
|
+
* a hand-written YAML row with an unknown kind reads back as a custom-shaped
|
|
330
|
+
* row and serializes back unchanged, so the dirty check stays quiet (save
|
|
331
|
+
* validation rejects it).
|
|
332
|
+
*/
|
|
333
|
+
export interface SlotEditorRow {
|
|
334
|
+
kind: string;
|
|
335
|
+
/** Frozen preset id — preset rows only (windows are code constants). */
|
|
336
|
+
preset?: string;
|
|
337
|
+
/** Custom rows: window start `HH:mm` text. */
|
|
338
|
+
start: string;
|
|
339
|
+
/** Custom rows: window end `HH:mm` text. */
|
|
340
|
+
end: string;
|
|
341
|
+
/** Custom rows: day mask 0=Sunday…6=Saturday; [] = every day. */
|
|
342
|
+
days: number[];
|
|
343
|
+
/** Custom rows: display name (PR #62 feedback round — collapsed rows). */
|
|
344
|
+
name: string;
|
|
345
|
+
/** UI-only collapse state — never serialized (dropped by rowsToTimeSlots). */
|
|
346
|
+
collapsed: boolean;
|
|
347
|
+
selectors: ChainSelectorRow[];
|
|
348
|
+
}
|
|
349
|
+
/** Project the time-slot rows into editable rows (chain selectors classified). */
|
|
350
|
+
export declare function timeSlotsToRows(timeSlots: readonly SlotRowConfig[], catalog?: CatalogLookup): SlotEditorRow[];
|
|
351
|
+
/** Rebuild the time-slot rows from edited rows; blank selectors drop out.
|
|
352
|
+
* `kind` rides verbatim (a hand-written unknown kind reads back unchanged;
|
|
353
|
+
* save validation rejects it) — the cast asserts the trusted editor shape.
|
|
354
|
+
* `days` is ALWAYS serialized ([] included): schemastery composes absent
|
|
355
|
+
* array fields as `[]`, so the composed config every card load accepts
|
|
356
|
+
* carries `days` on every row — the draft must too, or a clean card would
|
|
357
|
+
* read back dirty. */
|
|
358
|
+
export declare function rowsToTimeSlots(rows: readonly SlotEditorRow[]): SlotRowConfig[];
|
|
359
|
+
/**
|
|
360
|
+
* One declared-role row in the editor (block 2 `roles.list`): identity
|
|
361
|
+
* fields + the role's own chain selector list + its append strategy.
|
|
362
|
+
* `prompt`/`permissions` are schema-reserved for the next iteration
|
|
363
|
+
* (fallbacks-explicit-role-tool) — they never enter row editing this round.
|
|
364
|
+
*/
|
|
365
|
+
export interface RoleRow {
|
|
366
|
+
id: string;
|
|
367
|
+
persona: string;
|
|
368
|
+
selectors: ChainSelectorRow[];
|
|
369
|
+
fallback: FallbackStrategy;
|
|
370
|
+
/** UI-only collapse state — never serialized (dropped by rowsToRoles). */
|
|
371
|
+
collapsed: boolean;
|
|
372
|
+
/**
|
|
373
|
+
* UI-only seeded-persona brief disclosure (plan role-card-seeded-ux) —
|
|
374
|
+
* never serialized (dropped by rowsToRoles). Only seeded rows render the
|
|
375
|
+
* affordance (a read-only single-line brief + the expandable full text);
|
|
376
|
+
* ordinary rows ignore the flag.
|
|
377
|
+
*/
|
|
378
|
+
personaOpen: boolean;
|
|
379
|
+
}
|
|
380
|
+
/** Project the declared roles into editable rows (chain selectors classified). */
|
|
381
|
+
export declare function rolesToRows(roles: readonly FallbacksRole[], catalog?: CatalogLookup): RoleRow[];
|
|
382
|
+
/** Rebuild the declared roles from edited rows; empty selectors drop out. */
|
|
383
|
+
export declare function rowsToRoles(rows: readonly RoleRow[]): FallbacksRole[];
|
|
384
|
+
/**
|
|
385
|
+
* Rebuild the declared roles from edited rows, re-attaching the
|
|
386
|
+
* schema-reserved `prompt`/`permissions` fields from the last accepted
|
|
387
|
+
* config by role id — they never round-trip through rows this round, so
|
|
388
|
+
* without the merge a save would silently drop them (T2 reviewer minor
|
|
389
|
+
* #2). The id trim matches {@link rowsToRoles}; a row whose id matches no
|
|
390
|
+
* original role (a freshly added one) keeps no extras. Key order mirrors
|
|
391
|
+
* `parseFallbacksConfig` so a clean draft's JSON dirty comparison never
|
|
392
|
+
* flags it.
|
|
393
|
+
*/
|
|
394
|
+
export declare function mergeRoleExtras(rows: readonly RoleRow[], originalRoles: readonly FallbacksRole[]): FallbacksRole[];
|
|
395
|
+
/**
|
|
396
|
+
* The `roles.rules` role dropdown's offer set — the ONLY data source for the
|
|
397
|
+
* rule rows' role selector: the built-in `'inherit'` target plus every
|
|
398
|
+
* declared `roles.list` id, in declaration order (a role added/removed on
|
|
399
|
+
* the same page is reflected immediately).
|
|
400
|
+
*/
|
|
401
|
+
export declare function ruleRoleOptions(roles: Pick<FallbacksRoles, 'list'>): string[];
|
|
402
|
+
/**
|
|
403
|
+
* Client-side legacy fallback detection (spec §9). The gateway's
|
|
404
|
+
* `legacyKeys` wire field is authoritative for the migration banner; this is
|
|
405
|
+
* a defensive fallback for configs that already passed wire normalization
|
|
406
|
+
* yet still carry a `roles.rules` reference to an undeclared role id — the
|
|
407
|
+
* only two-block-era leftover that can survive the wire (the removed
|
|
408
|
+
* `chains`/`roles.default` keys never ride it).
|
|
409
|
+
*/
|
|
410
|
+
export declare function detectLegacyClientKeys(config: FallbacksConfig): string[];
|
|
411
|
+
/**
|
|
412
|
+
* One role-rule row in the editor (PR #62 feedback: no origin control —
|
|
413
|
+
* rules are subagent-only; a persisted wire `origin` is ignored).
|
|
414
|
+
*/
|
|
415
|
+
export interface RoleRuleRow {
|
|
416
|
+
provider: CatalogSelection;
|
|
417
|
+
model: CatalogSelection;
|
|
418
|
+
role: string;
|
|
419
|
+
}
|
|
420
|
+
/** Project the role rules into editable rows (provider/model classified). */
|
|
421
|
+
export declare function rulesToRows(rules: readonly FallbacksRoleRule[], catalog?: CatalogLookup): RoleRuleRow[];
|
|
422
|
+
/** Rebuild the role rules from edited rows; empty provider/model drop out. */
|
|
423
|
+
export declare function rowsToRules(rows: readonly RoleRuleRow[]): FallbacksRoleRule[];
|
|
424
|
+
/**
|
|
425
|
+
* The settings Remote namespace face the fallbacks store reads
|
|
426
|
+
* (`ctx.remote.settings`; api-settings-controller `@Remote` methods).
|
|
427
|
+
*/
|
|
428
|
+
export interface FallbacksSettingsRemote {
|
|
429
|
+
/** Redacted describe: provider writability plus the namespace directory. */
|
|
430
|
+
describe(): Promise<RemoteResult<SettingsDescribeValue>>;
|
|
431
|
+
}
|
|
432
|
+
/**
|
|
433
|
+
* The llm Remote namespace face the fallbacks store reads
|
|
434
|
+
* (`ctx.remote.llm`; dsh-llm `@Remote` methods).
|
|
435
|
+
*/
|
|
436
|
+
export interface FallbacksLlmRemote {
|
|
437
|
+
/** Declared configurable-provider directory, registered or dormant. */
|
|
438
|
+
listConfigurableProviders(): Promise<RemoteResult<LlmConfigurableProvider[]>>;
|
|
439
|
+
}
|
|
440
|
+
/**
|
|
441
|
+
* The session Remote namespace face the fallbacks store reads
|
|
442
|
+
* (`ctx.remote.session`; api-session-controller `@Remote` methods).
|
|
443
|
+
*/
|
|
444
|
+
export interface FallbacksSessionRemote {
|
|
445
|
+
/** Host-generation model catalog: provider groups plus per-provider failures. */
|
|
446
|
+
modelCatalog(): Promise<RemoteResult<ModelCatalog>>;
|
|
447
|
+
/**
|
|
448
|
+
* Live event stream for one durable session address; the opening snapshot
|
|
449
|
+
* frame carries the tail page this store reads, then the stream is
|
|
450
|
+
* cancelled (successor of the apiproxy `sessions.history` unary —
|
|
451
|
+
* `session/page` needs the follow opening frame's cursor, so a cold tail
|
|
452
|
+
* read goes through the follow opening).
|
|
453
|
+
*/
|
|
454
|
+
follow(request: SessionFollowRequest, signal?: AbortSignal): AsyncIterable<SessionFollowFrame>;
|
|
455
|
+
}
|
|
456
|
+
/**
|
|
457
|
+
* The generated Remote namespaces the fallbacks store consumes, as one
|
|
458
|
+
* structural face. The mount boundary casts `ctx.remote` once — the same
|
|
459
|
+
* pattern as the session-controller client's `ctx.remote as unknown as
|
|
460
|
+
* SessionRemotes` — because the generated `TypertRemoteNamespaceMap` merge
|
|
461
|
+
* ships with the host's build, not with the linked package types.
|
|
462
|
+
*/
|
|
463
|
+
export interface FallbacksRemote {
|
|
464
|
+
readonly settings: FallbacksSettingsRemote;
|
|
465
|
+
readonly llm: FallbacksLlmRemote;
|
|
466
|
+
readonly session: FallbacksSessionRemote;
|
|
467
|
+
}
|
|
468
|
+
/** Controller joining Settings reads, writes, and pushed invalidations. */
|
|
469
|
+
export declare class FallbacksSettingsController {
|
|
470
|
+
private readonly api;
|
|
471
|
+
private readonly rpc;
|
|
472
|
+
/** Snapshot consumed by the section through `useSyncExternalStore`. */
|
|
473
|
+
readonly store: SnapshotStore<FallbacksSettingsState>;
|
|
474
|
+
/** Read guard: a newer load() supersedes an older one's publish. */
|
|
475
|
+
private readGeneration;
|
|
476
|
+
/**
|
|
477
|
+
* Write guard: save()/resetToDefaults() completions ALWAYS publish unless
|
|
478
|
+
* dispose() invalidated them — an overlapping read must never discard a
|
|
479
|
+
* successful write's accept() (audit F1).
|
|
480
|
+
*/
|
|
481
|
+
private writeGeneration;
|
|
482
|
+
private catalogGeneration;
|
|
483
|
+
private switchesGeneration;
|
|
484
|
+
/** Every settings namespace from the last describe, keyed by ns — the configured-provider join's other input. */
|
|
485
|
+
private namespaces;
|
|
486
|
+
private currentSession;
|
|
487
|
+
/**
|
|
488
|
+
* The store's dispose signal (qc3 F-003): created alongside the store
|
|
489
|
+
* lifecycle, threaded into every `session.follow` call, aborted once in
|
|
490
|
+
* {@link dispose} — a follow opening still mid-await at plugin unload
|
|
491
|
+
* (HMR / fiber dispose, or a wedged gateway stream) is cancelled promptly
|
|
492
|
+
* instead of staying open until the mount abort or socket failure.
|
|
493
|
+
*/
|
|
494
|
+
private readonly followAbort;
|
|
495
|
+
/**
|
|
496
|
+
* @param api - the Remote namespace faces the store reads (settings
|
|
497
|
+
* describe `writable` + namespace directory, llm provider directory,
|
|
498
|
+
* session model catalog + follow tail page) — `ctx.remote` cast once at
|
|
499
|
+
* the mount boundary.
|
|
500
|
+
* @param rpc - the connection's generic RPC caller for the host gateway
|
|
501
|
+
* channel (`/api`), injected from the connection handle.
|
|
502
|
+
*/
|
|
503
|
+
constructor(api: FallbacksRemote, rpc: ClientConnectionRpc);
|
|
504
|
+
/**
|
|
505
|
+
* Refresh the page snapshot. Latest request wins. `settings.describe`
|
|
506
|
+
* still runs — it supplies the top-level `writable` flag (host read-only
|
|
507
|
+
* mode) and the namespace directory (the configured-provider join's other
|
|
508
|
+
* input) — but the fallbacks config itself rides the gateway channel:
|
|
509
|
+
* `rpc.call('/api', 'fallbacks/get', { args: {} })`. The two reads are
|
|
510
|
+
* independent and run in PARALLEL (Promise.all — one round trip per
|
|
511
|
+
* refresh, not two). The `fallbacks` namespace is NOT expected in describe
|
|
512
|
+
* anymore (it is off the apiproxy boundary post-patch); a describe failure
|
|
513
|
+
* remains a hard `error` (the form cannot render provider/model options
|
|
514
|
+
* without the directory), while a get failure is NOT a page error —
|
|
515
|
+
* `present` goes false and the section keeps the usable skeleton (KD-G5).
|
|
516
|
+
* @returns nothing; {@link store} carries success or failure.
|
|
517
|
+
*/
|
|
518
|
+
load(): Promise<void>;
|
|
519
|
+
/**
|
|
520
|
+
* Refresh the provider/model catalog (`llm/listConfigurableProviders` +
|
|
521
|
+
* `session/modelCatalog`), an
|
|
522
|
+
* independent read path with its own generation guard so it can run
|
|
523
|
+
* parallel to {@link load} without clobbering it (spec §2.5 D-4).
|
|
524
|
+
* Per-provider lookup failures ride `catalogError` as a diagnostic without
|
|
525
|
+
* failing the sound groups; a whole-load failure lands `catalogStatus:
|
|
526
|
+
* 'error'` and never blocks the rest of the form.
|
|
527
|
+
* @returns nothing; {@link store} carries success or failure.
|
|
528
|
+
*/
|
|
529
|
+
loadCatalog(): Promise<void>;
|
|
530
|
+
/**
|
|
531
|
+
* Record the current session the status block reads (spec §2.5 D-5). Once
|
|
532
|
+
* the block has been read once, its summary follows session switches
|
|
533
|
+
* immediately; an idle block only records the id — the section's mount
|
|
534
|
+
* effect performs the first read.
|
|
535
|
+
* @param sessionId - the session whose history is summarized; undefined
|
|
536
|
+
* (no current session) resolves to the empty state.
|
|
537
|
+
*/
|
|
538
|
+
setCurrentSession(sessionId: SessionId | undefined): void;
|
|
539
|
+
/**
|
|
540
|
+
* Read the recent-switch summary for the current session (spec §2.5 D-5):
|
|
541
|
+
* one tail page (`maxMessages` = {@link SWITCHES_HISTORY_PAGE}) read from
|
|
542
|
+
* the `session/follow` opening snapshot — the host has no unary tail-page
|
|
543
|
+
* read (`session/page` needs the follow opening frame's cursor), so the
|
|
544
|
+
* stream is cancelled right after its first frame —
|
|
545
|
+
* `fallbacks/switch` events extracted newest-first capped at
|
|
546
|
+
* {@link RECENT_SWITCH_LIMIT}. No current session → honest empty ready
|
|
547
|
+
* state (no RPC); a read failure lands `switchesStatus: 'error'` and never
|
|
548
|
+
* touches the settings state (the form keeps editing/saving normally).
|
|
549
|
+
* @returns nothing; {@link store} carries success or failure.
|
|
550
|
+
*/
|
|
551
|
+
loadSwitches(): Promise<void>;
|
|
552
|
+
/**
|
|
553
|
+
* Persist the full edited configuration through the gateway channel
|
|
554
|
+
* (`/api/fallbacks/set`). The full config is sent as a MERGE patch (guide
|
|
555
|
+
* §9) — keys the new schema cannot express (legacy `chains` /
|
|
556
|
+
* `roles.default` in the user layer) survive the write, which is why the
|
|
557
|
+
* gateway returns POST-WRITE `legacyKeys` and the banner stays honest
|
|
558
|
+
* (W-1/F-1). The merge has no revision guard: any failure (business
|
|
559
|
+
* rejection or transport) surfaces its message in `state.error` for the
|
|
560
|
+
* section's error banner and the form stays editable for retry (KD-G3).
|
|
561
|
+
* @param next - the complete edited configuration.
|
|
562
|
+
*/
|
|
563
|
+
save(next: FallbacksConfig): Promise<void>;
|
|
564
|
+
/**
|
|
565
|
+
* Explicit "sync to host allowlist" write (plan
|
|
566
|
+
* role-chain-allowlist-visibility T2): the gateway endpoint merges the
|
|
567
|
+
* CURRENT allowlist with this plugin's exact chain routes plus the virtual
|
|
568
|
+
* `FallbacksChain/Auto` route and writes only `allowedModels`. The button
|
|
569
|
+
* click is the ONLY trigger — the store never syncs on its own.
|
|
570
|
+
* @returns true when the write landed (the card then reads the fresh
|
|
571
|
+
* snapshot from the store); false on a refused/failed call, leaving the
|
|
572
|
+
* last accepted state untouched. A response discarded by the write
|
|
573
|
+
* generation guard is still a landed write — dispose() is the only
|
|
574
|
+
* invalidator, so it must not report failure.
|
|
575
|
+
*/
|
|
576
|
+
syncAllowlist(): Promise<boolean>;
|
|
577
|
+
/**
|
|
578
|
+
* Reset to composition defaults through the gateway channel
|
|
579
|
+
* (`/api/fallbacks/reset` — the fallbacks-specific third method; the host
|
|
580
|
+
* clears the user layer via `settings.replace(ns, {})`, the removal path a
|
|
581
|
+
* merge cannot express). Same error handling as {@link save} (KD-G3).
|
|
582
|
+
*/
|
|
583
|
+
resetToDefaults(): Promise<void>;
|
|
584
|
+
/** Stop in-flight responses from publishing after plugin disposal. */
|
|
585
|
+
dispose(): void;
|
|
586
|
+
/**
|
|
587
|
+
* Unpack one write response (set / reset / sync-allowlist) into the store
|
|
588
|
+
* snapshot. The additive fields (legacyKeys §9, seeds §9.4, subagentPolicy
|
|
589
|
+
* D4) follow the W-1/F-1 rule: absent on the wire keeps the last accepted
|
|
590
|
+
* value — only a `get` may settle server truth.
|
|
591
|
+
*/
|
|
592
|
+
private acceptWire;
|
|
593
|
+
/**
|
|
594
|
+
* Publish a settled load: `status` ready, `writable` from describe, and —
|
|
595
|
+
* only when the gateway returned a REAL config — `present` true and
|
|
596
|
+
* `state.config` replaced with the parsed value. A get that did not
|
|
597
|
+
* resolve (`config === undefined`) lands `present` false and keeps the
|
|
598
|
+
* last accepted config (the defaults skeleton on a first load) — the
|
|
599
|
+
* draft seed invariant (I-1): a transient channel-down must never seed
|
|
600
|
+
* the form with defaults over real server truth. `legacyKeys` rides the
|
|
601
|
+
* same publish: the wire field drives the migration banner. save/reset
|
|
602
|
+
* pass the POST-WRITE value (W-1/F-1) — or the previous value when the
|
|
603
|
+
* response omits the field, so a write can never clear the banner
|
|
604
|
+
* against server truth; only a real `get` may. `seeds` (spec §9.4)
|
|
605
|
+
* follows the same honest rule: the wire badge field is authoritative
|
|
606
|
+
* only when a real config resolved — a transient channel-down keeps the
|
|
607
|
+
* last accepted badge state.
|
|
608
|
+
*/
|
|
609
|
+
private accept;
|
|
610
|
+
private fail;
|
|
611
|
+
}
|
|
612
|
+
/**
|
|
613
|
+
* Refetch after reconnect / settings change only when the section has already
|
|
614
|
+
* opened once.
|
|
615
|
+
* @param controller - the fallbacks settings controller.
|
|
616
|
+
*/
|
|
617
|
+
export declare function refreshFallbacksIfLoaded(controller: FallbacksSettingsController): void;
|
|
618
|
+
/**
|
|
619
|
+
* Refetch the catalog after `llm/adapters-updated` only when it has already
|
|
620
|
+
* been opened once (the catalog twin of {@link refreshFallbacksIfLoaded}).
|
|
621
|
+
* @param controller - the fallbacks settings controller.
|
|
622
|
+
*/
|
|
623
|
+
export declare function refreshCatalogIfLoaded(controller: FallbacksSettingsController): void;
|
|
624
|
+
/**
|
|
625
|
+
* Refetch the recent-switch summary after `settings/document-updated`
|
|
626
|
+
* (fallbacks ns) / `connection/reset` only when the status block has already
|
|
627
|
+
* been read once
|
|
628
|
+
* (the switches twin of {@link refreshFallbacksIfLoaded}).
|
|
629
|
+
* @param controller - the fallbacks settings controller.
|
|
630
|
+
*/
|
|
631
|
+
export declare function refreshSwitchesIfLoaded(controller: FallbacksSettingsController): void;
|