dsh-llm-fallbacks 0.6.13 → 0.8.0

package/dist/gateway.d.ts

@@ -26,9 +26,9 @@
  * Data: `get` reads the `FallbacksSettingsBridge` source — the same live
  * composed config the runtime reads (schema defaults → plugin-row base →
  * profile patch). There is NO hard-gate resolver (unlike advisor's
- * `resolveAdvisorConfig`): the fallbacks decision path runs at
- * `agent/request` time in `src/index.ts`, so the gateway returns the raw
- * composed config. There is NO config-level `enabled` key on the contract
+ * `resolveAdvisorConfig`): the fallbacks decision path runs inside the
+ * virtual route's chain walk (`src/chain-walk.ts`), so the gateway returns
+ * the raw composed config. There is NO config-level `enabled` key on the contract
  * (plan fallbacks-web-ux-alignment T2): the Plugins-page row toggle is the
  * master switch, the runtime gates read content presence
  * (`isFallbackActive` in `src/config.ts`), and a stored `enabled:` line is
@@ -66,7 +66,7 @@
  * @module dsh-llm-fallbacks/gateway
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { type SettingsNamespace } from '@deepseek-ai/dsh-settings';
+import SettingsForms, { type SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry';
 import type { FallbacksConfig } from './config';
@@ -91,61 +91,6 @@ export declare const FALLBACKS_SETTINGS_NAMESPACE: SettingsNamespace;
  * reference `apply()` reads — no separate registration step.
  */
 export declare const FALLBACKS_PROFILE_ENTRY = "llm-fallbacks";
-/** One exact child LLM route on the additive `subagentPolicy` wire field (T5). */
-export type SubagentPolicyRoute = {
-    provider: string;
-    model: string;
-};
-/**
- * Additive `/api/fallbacks/get` host-policy snapshot (spec D4 / T5).
- * Omitted only when the snapshot is unwired (3-arg constructor) so older
- * clients and gateway unit tests keep a byte-identical `{ config,
- * legacyKeys, seeds }` payload. A wired snapshot always emits the field —
- * `{ state: 'disabled' }` included — so a write after an enabled get cannot
- * keep-last an allowlist. Never written through `set`/`reset`.
- */
-export type SubagentPolicyWire = {
-    state: 'enabled';
-    allowedModels: SubagentPolicyRoute[];
-    head?: {
-        route: SubagentPolicyRoute;
-        source: 'authorized' | 'injected';
-    };
-    blockedAttempt?: {
-        at: number;
-        route: SubagentPolicyRoute;
-        reason: string;
-    };
-} | {
-    state: 'disabled';
-} | {
-    state: 'unprovable';
-};
-/**
- * Live host-policy snapshot the gateway projects onto the wire. Built in
- * `apply()` from the SAME T1 reader the override paths use — no second
- * policy source. Optional: the 3-arg constructor (gateway unit tests)
- * omits the field entirely.
- */
-export type SubagentPolicySnapshotFn = () => {
-    policy: {
-        state: 'disabled';
-    } | {
-        state: 'enabled';
-        allowedModels: readonly SubagentPolicyRoute[];
-    } | {
-        state: 'unprovable';
-    };
-    head?: {
-        route: SubagentPolicyRoute;
-        source: 'authorized' | 'injected';
-    };
-    blockedAttempt?: {
-        at: number;
-        route: SubagentPolicyRoute;
-        reason: string;
-    };
-};
 /**
  * The live configuration source for the gateway (guide §7 — the same bridge
  * shape the runtime reads through). `source()` returns the live composed
@@ -155,7 +100,15 @@ export type SubagentPolicySnapshotFn = () => {
  * `onChange` fan-out was removed in the QC fix wave — nothing subscribed).
  */
 export interface FallbacksSettingsBridge {
+    /** The EFFECTIVE config the runtime reads (v1 already upgraded in memory). */
     source(): FallbacksConfig;
+    /**
+     * The STORED view, before the in-memory upgrade. Legacy detection reads it,
+     * so the migration banner keeps reporting keys the effective config no
+     * longer carries (plan fallbacks-v1-auto-migration). Optional: a caller
+     * without one is assumed to hold the raw shape itself.
+     */
+    rawSource?(): FallbacksConfig;
 }
 /** Patch shape accepted by `fallbacks.set` — any subset of the config keys. */
 export type FallbacksConfigPatch = Partial<FallbacksConfig>;
@@ -168,13 +121,6 @@ export interface FallbacksReadResult {
     config: FallbacksConfig;
     legacyKeys: string[];
     seeds: SeedsWireStatus[];
-    /**
-     * Host subagent-model-selection policy (spec D4). Additive — old readers
-     * ignore it; omitted only when no snapshot is wired. A wired snapshot
-     * always carries the field (`disabled` included) so keep-last cannot
-     * retain an allowlist after policy-off.
-     */
-    subagentPolicy?: SubagentPolicyWire;
 }
 /** The `fallbacks/revert-seed` response — a read result plus the revert outcome. */
 export interface FallbacksRevertResult extends FallbacksReadResult {
@@ -198,12 +144,6 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
     private readonly seeds;
     /** The live settings service once the optional inject child activates. */
     private settings;
-    /**
-     * Optional host-policy snapshot (T5). When omitted the additive
-     * `subagentPolicy` field is absent on every read — the 3-arg constructor
-     * used by gateway unit tests stays byte-identical to the pre-T5 payload.
-     */
-    private readonly subagentPolicy;
     /**
      * @param ctx - owning context (the plugin fiber's ctx inside `apply`).
      * @param bridge - the same `FallbacksSettingsBridge` the runtime reads, so
@@ -211,22 +151,21 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      * @param seeds - the per-apply `FallbacksSeedManager` constructed in
      *   `apply()` — the gateway delegates badge state and revert to it (no
      *   copied manager logic), through the io seam built over this bridge.
-     * @param subagentPolicy - live host-policy snapshot from `apply()`; omit
-     *   to leave the additive field off the wire.
      */
-    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager, subagentPolicy?: SubagentPolicySnapshotFn);
+    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager);
     /**
      * Read the current composed config (schema defaults → entry base → profile
      * patch). No hard-gate resolver (ADR-2): the raw composed config is
      * the wire value. The removed `enabled` key never crosses the wire (the
      * read whitelist drops it — the snapshot-strip half of LEGACY_KEYS).
-     * @returns the wire-normalized composed config plus `legacyKeys` — legacy
-     *   two-block-era fields (`chains` / `roles.default` / undeclared rule
-     *   role refs) detected on the composed source (schemastery retains them,
-     *   plan Task 1 Step 1), so the client can show a migration banner (spec
-     *   §9, incremental field — old clients ignore it) — plus the additive
-     *   `seeds` badge state (spec §9.4, legacyKeys precedent — old clients
-     *   ignore it).
+     * @returns the wire-normalized composed config plus `legacyKeys` — every
+     *   v1 field detected on the composed source (`rootChain`, top-level
+     *   `timeSlots`, `roles.rules`, `roles.default`, `roles.list[].fallback`,
+     *   the v1 ARRAY form of `roles.list[].chain`, plus the older
+     *   `alwaysModeRetryCap` / `roleAutoMatch` / renamed role fields —
+     *   schemastery retains them), so the client can show a migration banner
+     *   (incremental field — old clients ignore it) — plus the additive `seeds`
+     *   badge state (legacyKeys precedent — old clients ignore it).
      */
     get(): FallbacksReadResult;
     /**
@@ -275,22 +214,6 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      *   write channel is unavailable (KD-G5).
      */
     revertSeed(id: string): Promise<FallbacksRevertResult>;
-    /**
-     * Merge the CURRENT host allowlist with the exact routes configured in this
-     * plugin's chains (every `roles.list[].chain` entry plus `rootChain`), plus
-     * the virtual `FallbacksChain/Auto` route. De-duplicated by exact
-     * provider+model with first-seen order kept (the current allowlist first).
-     * Wildcard (`provider/*`) and unparseable entries are skipped — never
-     * expanded into routes. This is the only allowlist write face; it runs
-     * exclusively from the explicit card button (never silently) and writes
-     * ONLY `allowedModels` — never `enabled`.
-     * @returns the post-write read result (the fresh `subagentPolicy` snapshot
-     *   reflects the new allowlist).
-     * @throws when no live policy snapshot is wired, the policy is not proven
-     *   enabled (`disabled` / `unprovable`), or no settings service is composed
-     *   (KD-G5: no allowlist write without a proven-enabled policy).
-     */
-    syncAllowlist(): Promise<FallbacksReadResult>;
     /**
      * Read the live composed config and normalize it to the typertGateway JSON
      * wire boundary. Containment (guide §10): a malformed stored patch section
@@ -316,26 +239,59 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      */
     private readResult;
     /**
-     * The io seam the seed manager writes through (spec §9.1): `read` walks
-     * the same live bridge source the gateway reads; `writeRoles` persists a
-     * full `{ list, rules }` to the plugin's profile-entry section — both
-     * arrays always computed from a fresh composed read, so the write stays
-     * correct under the settings merge's array-replace semantics and never
-     * touches operator rules. The write channel fails with the same KD-G5
-     * message as set/reset when no settings service is composed. Built fresh
-     * per call so the mutable settings capture is read at call time (the
-     * inject child swaps it when the settings service appears/disappears).
+     * The io seam the seed manager writes through (spec §9.1): `read` walks the
+     * same live bridge source the gateway reads; `writeRoles` persists the
+     * declared roles as `{ list }` — the v2 shape, whose rows are `{ id,
+     * persona, chain? }` — computed from a fresh composed read, so the write
+     * stays correct under the settings merge's replace-whole-array semantics
+     * and every operator-specified `chain` pointer survives verbatim. It goes
+     * through {@link writeSection}, so a seed write also drops any stored v1
+     * field. The write channel fails with the same KD-G5 message as set/reset
+     * when no settings service is composed. Built fresh per call so the mutable
+     * settings capture is read at call time (the inject child swaps it when the
+     * settings service appears/disappears).
      */
     private seedsIo;
+    /**
+     * Write a CLEANED patch and, in the same save, remove v1 fields the
+     * persisted section may still carry. `settings.update` is merge-only, so a
+     * stored `rootChain` / top-level `timeSlots` / `roles.rules` /
+     * `roles.list[].fallback` would otherwise survive every v2 save; the
+     * removals ride `settings.mutate`'s `unset` path ops, which touch only the
+     * named fields (unrelated configuration, foreign keys and redacted secrets
+     * are preserved — a wholesale `replace` rebuilt from a descriptor would not
+     * be).
+     * @param patch - already stripped of v1 fields and null values.
+     */
+    private writeSection;
 }
+/**
+ * Persist a CLEANED patch and, in the same operation, remove the v1 fields the
+ * ACTIVE PROFILE's persisted section still holds. `settings.update` is
+ * merge-only, so a stored `rootChain` / top-level `timeSlots` / `roles.rules` /
+ * `roles.list[].fallback` would otherwise survive every v2 save; the removals
+ * ride `settings.mutate`'s path ops, which touch only the named fields
+ * (unrelated configuration, foreign keys and redacted secrets are preserved —
+ * a wholesale `replace` rebuilt from a descriptor would delete them).
+ *
+ * Exported because the plugin has TWO write entry points — the gateway
+ * (`set` / `writeRoles`) and the apply-level `SeedsIo` (`declareSeeds`,
+ * `revertSeededPersona`, the bundled preset self-declaration) — and the same
+ * logical operation must clean the same way through both.
+ * @param settings - the live settings service.
+ * @param patch - a patch; v1 fields are stripped here, callers need not.
+ * @param ns - profile entry id (defaults to the plugin's own).
+ */
+export declare function writeFallbacksSection(settings: SettingsForms, patch: Record<string, unknown>, ns?: string): Promise<void>;
 /**
  * Reject a patch the `Config` schema cannot express: non-object input, unknown
  * top-level keys (schemastery merges them silently — the settings service
  * would accept them), and schema type violations — plus the Task 3 semantic
  * guards the permissive schema deliberately does not carry: nested `roles`
- * keys, `timeSlots` row shapes (unknown preset ids, duplicate presets, preset
- * rows carrying windows, non-`HH:mm` custom bounds, out-of-range days, empty
- * chains), and the all-day `rootChain` head conformance.
+ * keys, `chains[]` row shape (id pattern, case-sensitive uniqueness, label),
+ * per-chain `timeSlots` row shapes (unknown preset ids, duplicate presets,
+ * preset rows carrying windows, non-`HH:mm` custom bounds, out-of-range days,
+ * empty chains), and each chain's non-empty `entries` tail conformance.
  *
  * Exported (plan fallbacks-tui-settings Task 1): the TUI settings section's
  * JSON-field `parse` mirrors the gateway save rules through this single

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 /**
- * dsh-llm-fallbacks host half (plan Task 3: settings + waterfall + state
- * machine + events).
+ * dsh-llm-fallbacks host half: settings, the virtual chain row, the dispatch
+ * seam, role seeds and the diagnostics surfaces (direction C, plan
+ * dsh-022-rc1-upgrade).
  *
  * Cordis function plugin mounted by the profile bundle patch row
  * `llm-fallbacks` (see `bundle/cordis.patch.yml`), composed AFTER llm-retry.
@@ -11,38 +12,29 @@
  *   `apply` reads the Loader's live config reference, and the
  *   `settings/document-updated` listener re-derives the runtime caches —
  *   the old `installSection` setSource/onChange contract, spec §4).
- * - `agent/request-error` waterfall: inactive config (`isFallbackActive`) /
- *   code ∉ `triggerCodes`
- *   (**always mode included**) → `next()`; otherwise resolve role + chain,
- *   and when a candidate survives the filter (current / cooldown /
- *   step-failed / `provider/*`-missing-id) write the pending switch +
- *   cooldown + failure bookkeeping, then return
- *   `{ kind: 'retry' }` (own recovery, no `next()`).
- * - `agent/request` waterfall: apply a pending switch after `await next()`
- *   (provider/model override; the inherited `reasoningEffort` follows the
- *   upstream routeChanged rule — dropped on a route change unless explicitly
- *   named, preserved on a same-route override; spec D3); a
- *   root-origin `FallbacksChain/Auto` seed is served UNCHANGED (plan
- *   model-change-notice-loop Task 1 — the route the loop serves and records
- *   must equal the session selection, otherwise the host `model-selection`
- *   notice is re-armed on every step; the virtual adapter's `stream()`
- *   delegate is what reaches the chain head); then the always-mode cap check
- *   (count `llm/retry` events for the current turn/step/provider; ≥
- *   `alwaysModeRetryCap` → same decision path, reason `always-cap` —
- *   ADR-2).
- * - Per-agent state (`FallbackStateStore`): `agent/disposed` removes it,
- *   `agent/status` idle prunes per-step state defensively, plugin dispose
- *   clears everything (spec §6 — no residual state).
+ * - The virtual `FallbacksChain/Auto` adapter is the ONLY fallback path: its
+ *   `stream()` WALKS the session's chain (`src/chain-walk.ts`). No
+ *   `agent/request` / `agent/request-error` listener is registered — rc.1
+ *   rejects a request that changes the captured selection, and a
+ *   request-error retry `continue`s with that captured selection, so the old
+ *   waterfall could not route a retried attempt at all. Real-model sessions
+ *   therefore have no plugin fallback; `llm-retry` owns their recovery.
+ * - Subagents: the dispatch seam (`src/subagents-seam.ts`) mounts an
+ *   inheriting child on the virtual row by stamping its creation options
+ *   (design §1.3) — creation-time only, so a resumed child's own durable
+ *   selection always wins.
+ * - Per-agent state (`FallbackStateStore`): `agent/disposed` removes it, plugin
+ *   dispose clears everything (spec §6 — no residual state). The cooldown /
+ *   recovery circuit is the cross-call memory the walk reads; per-request
+ *   bookkeeping lives inside one walk.
  *
  * @module dsh-llm-fallbacks
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { Session } from '@deepseek-ai/dsh-session';
 import { detectLegacyKeys, validateFallbacksConfig, type FallbacksConfig } from './config.ts';
 import { Config } from './schema.ts';
 import { resolveChain } from './chains.ts';
-import { resolveRole } from './roles.ts';
-import { FallbackStateStore, type BlockedSwitchAttempt, type EffectiveChainHead } from './state.ts';
+import { FallbackStateStore } from './state.ts';
 import { type EffectiveRolesReadback, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertOutcome, type SeedsDeclareOptions } from './seeds.ts';
 /** The plugin row id mounted by the profile bundle patch. */
 export declare const name = "llm-fallbacks";
@@ -69,7 +61,6 @@ export interface FallbacksService {
     name: 'llm-fallbacks';
     /** Package.json version string (module-load snapshot). */
     version: string;
-    resolveRole: typeof resolveRole;
     resolveChain: typeof resolveChain;
     validateFallbacksConfig: typeof validateFallbacksConfig;
     detectLegacyKeys: typeof detectLegacyKeys;
@@ -113,12 +104,9 @@ export { Config };
 /** The plugin's composition config — the `fallbacks` settings schema (spec §4). */
 export type Config = FallbacksConfig;
 export type { FallbackSwitchReason, FallbacksSwitchEventData } from './events.ts';
-export type { AgentFallbackState, BlockedSwitchAttempt, FallbackStateStore, PendingSwitch, StepFailures, SwitchScope } from './state.ts';
-/** @internal T5 test-seam types (mirrors `BlockedSwitchAttempt`; not public API). */
-export type { ChainHeadSource, EffectiveChainHead } from './state.ts';
-export { resolveRole, type AgentLike, type Origin, } from './roles.ts';
+export type { AgentFallbackState, FallbackStateStore } from './state.ts';
 export { annotateCandidates, createCandidateFilter, hasWildcardEntry, resolveCandidate, resolveChain, resolveChainViews, selectCandidates, type AnnotatedCandidate, type CandidateFilterOptions, type CandidateSkipReason, type FailingModel, } from './chains.ts';
-export { defaultFallbacksConfig, detectLegacyKeys, INHERIT_ROLE_ID, ROLE_ID_PATTERN, validateFallbacksConfig, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRole, type FallbacksRoles, type FallbacksRoleRule, type FallbackStrategy, type RevertPolicy, type RecoveryPolicy, } from './config.ts';
+export { CHAIN_ID_PATTERN, defaultFallbacksConfig, detectLegacyKeys, INHERIT_ROLE_ID, ROLE_ID_PATTERN, validateFallbacksConfig, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRole, type FallbacksRoles, type NamedChain, type RevertPolicy, type RecoveryPolicy, } from './config.ts';
 export { parseSelector, SelectorError, type Selector, } from './selectors.ts';
 export { FallbacksSeedManager, type EffectiveRole, type EffectiveRolesReadback, type SeedConflict, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertFailReason, type SeedRevertOutcome, type SeedSkipReason, type SeedSource, type SeedsDeclareOptions, type SeedsIo, type SeedsWireStatus, } from './seeds.ts';
 export { presetRoles } from './presets.ts';
@@ -130,37 +118,6 @@ export { ROLE_PROJECTION_KEY, readRoleProjectionValue } from './role-projection-
  * request must not grow the store) without reaching into the closure.
  */
 export declare function stateStore(ctx: Context): FallbackStateStore | undefined;
-/**
- * @internal Test seam (mirrors `stateStore`): the per-agent blocked-switch
- * attempts recorded by the T3 allowlist gate for the plugin applied to `ctx`
- * (spec D1; in-memory only, issue #52). Not part of the plugin's public
- * surface; lets tests (and the T5 gateway projection) read blocked attempts
- * without reaching into the closure. `undefined` when no plugin is applied.
- */
-export declare function blockedAttempts(ctx: Context): ReadonlyMap<string, BlockedSwitchAttempt> | undefined;
-/**
- * @internal Test seam (mirrors `blockedAttempts`): the per-agent effective
- * chain heads recorded by the T2 inject path (source `authorized` |
- * `injected`) for the plugin applied to `ctx` (spec D4 / T2 M3). Not part
- * of the plugin's public surface; lets tests and the T5 gateway projection
- * read the head without reaching into the closure. `undefined` when no
- * plugin is applied.
- */
-export declare function chainHeads(ctx: Context): ReadonlyMap<string, EffectiveChainHead> | undefined;
-/**
- * Count durable `llm/retry` events for the current (turn, step, provider) in
- * **always mode** (ADR-2; spec §2 clause 5). Normal-mode retries belong to
- * llm-retry's bounded budget and must not preempt the fallback, so only
- * `mode: 'always'` events count toward `alwaysModeRetryCap` (T3 review
- * Minor 2 — the real event carries the discriminator, llm-retry types.ts).
- *
- * Fast path (T3 review Minor 4): the session log is append-ordered, so the
- * scan runs backwards and stops at the first event older than the target
- * (turn, step) — a long session's earlier turns are never scanned.
- *
- * Exported for direct unit testing of the counting + fast path.
- */
-export declare function countRetryEvents(session: Session, turn: number, step: number, provider: string): number;
 /**
  * The live config reference the Loader hands `apply` for a
  * volatile Config schema: an identity-stable `{ get }` view (cosmokit's