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.
Files changed (50) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +162 -2
  3. package/README.zh-CN.md +170 -0
  4. package/bundle/cordis.patch.yml +19 -0
  5. package/dist/authorized-route.d.ts +68 -0
  6. package/dist/automatch.d.ts +98 -0
  7. package/dist/chains.d.ts +186 -0
  8. package/dist/client/ConversationFallbackSwitch.d.ts +91 -0
  9. package/dist/client/FallbacksCard.d.ts +36 -0
  10. package/dist/client/GeneralFallbacksRow.d.ts +19 -0
  11. package/dist/client/ModelsPanel.d.ts +64 -0
  12. package/dist/client/SubagentRoleBadge.d.ts +53 -0
  13. package/dist/client/fallbacks-store.d.ts +631 -0
  14. package/dist/client/index.d.ts +64 -0
  15. package/dist/client/index.js +3420 -0
  16. package/dist/client/locales.d.ts +454 -0
  17. package/dist/client/switch-guard.d.ts +17 -0
  18. package/dist/client/use-snapshot.d.ts +11 -0
  19. package/dist/commands.d.ts +380 -0
  20. package/dist/config.d.ts +239 -0
  21. package/dist/cooldown.d.ts +57 -0
  22. package/dist/events.d.ts +52 -0
  23. package/dist/gateway.d.ts +359 -0
  24. package/dist/index.d.ts +195 -0
  25. package/dist/index.js +4587 -0
  26. package/dist/models.d.ts +306 -0
  27. package/dist/override.d.ts +39 -0
  28. package/dist/presets.d.ts +20 -0
  29. package/dist/recovery.d.ts +92 -0
  30. package/dist/role-notice.d.ts +184 -0
  31. package/dist/role-persona.d.ts +71 -0
  32. package/dist/role-projection-key.d.ts +41 -0
  33. package/dist/role-projection.d.ts +152 -0
  34. package/dist/role-resolution.d.ts +105 -0
  35. package/dist/roles.d.ts +90 -0
  36. package/dist/route-allowlist.d.ts +43 -0
  37. package/dist/schema.d.ts +46 -0
  38. package/dist/seeds.d.ts +237 -0
  39. package/dist/selectors.d.ts +38 -0
  40. package/dist/state.d.ts +205 -0
  41. package/dist/subagent-policy.d.ts +123 -0
  42. package/dist/subagents-seam.d.ts +305 -0
  43. package/dist/time-slots.d.ts +147 -0
  44. package/dist/tui-settings.d.ts +145 -0
  45. package/dist/tui.d.ts +63 -0
  46. package/dist/virtual-adapter.d.ts +259 -0
  47. package/icon.svg +16 -0
  48. package/locale/en.json +6 -0
  49. package/locale/zh.json +6 -0
  50. 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;