dsh-llm-fallbacks 0.6.13 → 0.8.0

package/dist/config.d.ts

@@ -4,32 +4,27 @@
  * module must stay free of `@deepseek-ai/*` value imports so the client
  * bundle never reaches schemastery).
  *
- * Two-block config model (plan fallbacks-role-config-model): block 1
- * `rootChain` — the root agent's single fallback chain (empty = no
- * degradation) — plus block 2 declared role entities: `roles.list`
- * (id/persona/prompt?/permissions?/chain?/fallback) and
- * `roles.rules` enum references into the declared ids (or the built-in
- * `'inherit'` role). The legacy `chains` / `roles.default` keys are gone
- * from the schema and type (zero residual, migration table excepted); the
- * runtime consumes the new shape directly and flags surviving legacy keys
- * at startup via `detectLegacyKeys` (see `src/index.ts` apply()).
+ * Named virtual chains (config v2, plan named-virtual-chains): N named
+ * chains each selectable as `FallbacksChain/<chain id>`, carrying their own
+ * `entries` (默认降级链 + 链尾) and `timeSlots`. Declared roles keep identity
+ * (`id`/`persona`/`prompt?`/`permissions?`) plus an OPTIONAL `chain`
+ * POINTER — a manually specified chain id (「指定降级链」), never an auto
+ * mode: absent/empty = NOT SPECIFIED, the plugin does not intervene and the
+ * child inherits the delegating agent's route. The v1 two-block model
+ * (`rootChain` + per-role inline chains + `roles.rules`) is deleted; the
+ * runtime consumes the v2 shape directly and flags surviving v1 keys at
+ * startup via `detectLegacyKeys` (warn-only migration — no auto-write).
  *
- * Spec §4 is authoritative for field names and default values — notably
+ * Spec §1 is authoritative for field names and default values — notably
  * `triggerCodes` defaults to dsh's stable failure codes `['AUTH', 'QUOTA',
- * 'RATE_LIMIT']` (there is no `QUOTA_EXCEEDED` code in dsh), and an
- * unconfigured install (empty `rootChain`, no time slots, empty roles) is a
- * no-op pass-through exactly like an uninstalled plugin (AC-8 —
- * {@link isFallbackActive}). There is NO config-level `enabled` switch
- * (plan fallbacks-web-ux-alignment T2): the Plugins-page row toggle is the
- * master switch (row disable = fiber destroy), and the runtime gates re-key
- * to content presence. A stored profile still carrying the removed
- * `enabled:` key loads cleanly — the gateway tolerates and strips it (the
- * advisor LEGACY_KEYS mechanism), it is never read and never re-persisted.
+ * 'RATE_LIMIT']`. An unconfigured install (empty `chains`) is a no-op
+ * pass-through exactly like an uninstalled plugin — there is NO config-level
+ * `enabled` switch: the Plugins-page row toggle is the master switch and the
+ * runtime gates re-key to `isFallbackActive` (`chains.length > 0`). Nothing
+ * pre-creates a default chain: empty `chains` is the ONLY first-run state.
  *
  * This module is pure logic: it must not import any `@deepseek-ai/*` package
- * (types included) — `FallbacksConfig` is the plugin's own type. Task 3
- * registers the schemastery schema (see `./schema.ts`) with
- * `installSettingsSection` under the `fallbacks` settings namespace.
+ * (types included) — `FallbacksConfig` is the plugin's own type.
  *
  * @module dsh-llm-fallbacks/config
  */
@@ -38,31 +33,31 @@ import type { SlotRowConfig } from './time-slots.ts';
 export type RecoveryPolicy = 'timer' | 'half-open';
 /** How a cooled-down model comes back (spec §4). */
 export type RevertPolicy = 'cooldown-expiry' | 'never';
-/** A single role rule: match on provider/model patterns (spec §3). */
-export interface FallbacksRoleRule {
-    /**
-     * Legacy persisted wire field (PR #62 feedback): rules are subagent-only,
-     * so this constraint is IGNORED at match time — root requests never
-     * match rules. Kept in the type/schema so pre-feedback `settings.yaml`
-     * files that carry `origin` still parse, validate, and save unchanged.
-     */
-    origin?: 'root' | 'subagent';
-    provider?: string;
-    model?: string;
-    role: string;
-}
+/** Chain id format (v2): case-sensitive, uppercase allowed so the migrated
+ * default id is exactly `Auto`. Deliberately NOT {@link ROLE_ID_PATTERN},
+ * which keeps governing role ids. */
+export declare const CHAIN_ID_PATTERN: RegExp;
 /**
- * Chain-append strategy of a declared role entity: `inherit-root` (the
- * default) runs the role's own chain and then appends `rootChain`;
- * `none` uses only the role's own chain.
+ * One named virtual chain (v2). `id` doubles as the picker model id —
+ * renaming it would orphan every saved selection, so only `label` is
+ * editable in the UI. The LAST `entries` element is the 链尾: exactly one
+ * official model. The FIRST matching `timeSlots` row REPLACES `entries`.
  */
-export type FallbackStrategy = 'inherit-root' | 'none';
+export interface NamedChain {
+    id: string;
+    /** Settings tab title + picker display prefix (display-only). */
+    label: string;
+    /** 默认降级链 + 链尾. */
+    entries: string[];
+    /** 分时 rows scoped to this chain; first match replaces {@link entries}. */
+    timeSlots?: SlotRowConfig[];
+}
 /**
- * A declared role entity (plan fallbacks-role-config-model Task 1).
+ * A declared role entity (v2): identity + an optional chain POINTER.
  *
  * `prompt` / `permissions` are schema-reserved for the next iteration
- * (fallbacks-explicit-role-tool) — no consumer this round, and writing them
- * does NOT change this round's degradation behavior.
+ * — no consumer this round, and writing them does NOT change this
+ * round's degradation behavior.
  */
 export interface FallbacksRole {
     id: string;
@@ -75,58 +70,59 @@ export interface FallbacksRole {
         allow?: string[];
         deny?: string[];
     };
-    chain?: string[];
-    fallback?: FallbackStrategy;
+    /**
+     * Manually specified named chain id for children dispatched under this
+     * role (「指定降级链」) — a POINTER into `chains[]`, never a chain
+     * definition. Absent or empty ⇒ NOT SPECIFIED: the plugin does not
+     * intervene and the child inherits the delegating agent's route. The
+     * plugin never picks a chain on its own.
+     */
+    chain?: string;
 }
-/** Role grouping for fallback chains: declared entities + enum references. */
+/** Role grouping (v2): declared entities only — `rules` is deleted. */
 export interface FallbacksRoles {
     list: FallbacksRole[];
-    rules: FallbacksRoleRule[];
 }
 /**
- * The full `fallbacks` settings shape (two-block config model, verbatim
+ * One declared role as the SCHEMA may compose it: identical to
+ * {@link FallbacksRole} except that a v1 profile still carries the ARRAY form
+ * of `chain`. The schema must accept it (composition happens in cordis BEFORE
+ * `apply()`, so a rejection there kills the fiber and no migration can run);
+ * {@link migrateLegacyConfig} narrows it to the string pointer.
+ */
+export interface FallbacksRoleSource extends Omit<FallbacksRole, 'chain'> {
+    chain?: string | string[];
+}
+/**
+ * The composed settings shape produced by the schemastery `Config` — the input
+ * of {@link migrateLegacyConfig}, not the shape the runtime consumes.
+ */
+export interface FallbacksConfigSource extends Omit<FallbacksConfig, 'roles'> {
+    roles: {
+        list: FallbacksRoleSource[];
+    };
+}
+/**
+ * The full `fallbacks` settings shape (named virtual chains, verbatim
  * field names).
  */
 export interface FallbacksConfig {
     triggerCodes: string[];
-    rootChain: string[];
+    chains: NamedChain[];
     roles: FallbacksRoles;
     cooldownMs: number;
     revertPolicy: RevertPolicy;
     maxSwitchesPerStep: number;
-    alwaysModeRetryCap: number;
     /**
      * Preset-role injection switch: `'bundled'` declares the 5 preset roles
      * (spec §9.2) as seed rows on apply; `'none'` disables declaration.
      * Optional on purpose — a required field would break library consumers
-     * that construct `FallbacksConfig` literals with the existing 8 keys
-     * (additive, non-breaking). The value domain is guarded by the schema
-     * (`Config` in `src/schema.ts`), NOT by `validateFallbacksConfig`, and
-     * every resolved config carries a value via the schema default.
+     * that construct `FallbacksConfig` literals. The value domain is guarded
+     * by the schema (`Config` in `src/schema.ts`), NOT by
+     * `validateFallbacksConfig`, and every resolved config carries a value
+     * via the schema default.
      */
     presets?: 'bundled' | 'none';
-    /**
-     * Dispatch-time LLM role auto-match switch (plan fallbacks-role-automatch
-     * Task 1): when `true` (default), a subagent-origin request with no
-     * explicit/rules-resolved role may have the best-fit declared role picked
-     * by the LLM; `false` reproduces today's behavior exactly. Optional on
-     * purpose, mirroring `presets` — a required field would break library
-     * consumers that construct `FallbacksConfig` literals with the existing
-     * keys (additive, non-breaking). The value domain is guarded by the
-     * schema (`z.boolean().default(true)` in `src/schema.ts`), and the
-     * runtime reads it defensively as `config.roleAutoMatch ?? true` (safe
-     * for direct constructors that omit it).
-     */
-    roleAutoMatch?: boolean;
-    /**
-     * Extra time-slot rows (plan fallbacks-timeslots Task 1, P5): the FIRST
-     * matching row's chain becomes the effective root chain at request time;
-     * `rootChain` (the all-day chain) is always the last row.
-     * Optional on purpose, mirroring `presets` — additive, non-breaking for
-     * library consumers. Malformed rows warn once and are skipped by the
-     * resolver; the gateway rejects them on save (Task 3).
-     */
-    timeSlots?: SlotRowConfig[];
     /**
      * Config-level timezone for slot matching (default `Asia/Shanghai`,
      * UTC+8). Not per-slot.
@@ -137,41 +133,40 @@ export interface FallbacksConfig {
      * 1): `'timer'` restores the preferred candidate when the cooldown
      * expires (today's behavior); `'half-open'` leaves the route half-open
      * for one logged probe instead. Optional on purpose, mirroring
-     * `presets` — a required field would break library consumers that
-     * construct `FallbacksConfig` literals with the existing keys
-     * (additive, non-breaking). The value domain is guarded by the schema
-     * (`Config` in `src/schema.ts`), NOT by `validateFallbacksConfig`, and
-     * every resolved config carries a value via the schema default.
+     * `presets`. The value domain is guarded by the schema, NOT by
+     * `validateFallbacksConfig`, and every resolved config carries a value
+     * via the schema default.
      */
     recovery?: RecoveryPolicy;
 }
 /**
- * Spec §4 defaults — `Config({})` must equal this (no-op install).
- * There is no `enabled` default (the key is removed — the Plugins-page row
- * toggle is the master switch): an unconfigured install (empty rootChain,
- * no time slots, empty roles) behaves exactly like an uninstalled plugin
- * (AC-3 / no-op invariant, {@link isFallbackActive}).
+ * Spec §1 defaults — `Config({})` must equal this (no-op install).
+ * Empty `chains` is the ONLY first-run state: nothing pre-creates an
+ * `Auto` chain and nothing seeds `entries` — the picker row appears only
+ * after the user creates a chain in the card. The migrated/seeded default
+ * chain (`{ id: 'Auto', label: '默认链', entries, timeSlots }`) exists only
+ * in the migration table (docs) applied by hand — warn-only migration.
  */
 export declare const defaultFallbacksConfig: FallbacksConfig;
+/** Role id format (aligned with yet-another-subagent `isValidProfileId`). */
+export declare const ROLE_ID_PATTERN: RegExp;
 /**
- * Reserved role id: legal as a rule target (`roles.rules[].role`) and as
- * the no-rule-match fallback, but FORBIDDEN in `roles.list[].id`.
+ * Reserved role id: FORBIDDEN in `roles.list[].id` (the validator's reserved
+ * warn) and in seed declarations (`seeds.ts` reserved-id skip). `rules` that
+ * could target it are deleted (v2), but the id itself stays reserved so a
+ * declared role can never shadow the "no specific role" meaning.
  */
 export declare const INHERIT_ROLE_ID = "inherit";
 /**
- * The no-op gate (AC-8), re-keyed from the removed `enabled` switch to
- * CONTENT PRESENCE (plan fallbacks-web-ux-alignment T2): the plugin
- * intervenes exactly when something is configured — a non-empty `rootChain`
- * (the all-day chain), at least one time-slot row, or at least one declared
- * role. An inactive config is a pass-through exactly like an uninstalled
- * plugin; the Plugins-page row toggle remains the master switch (row
- * disable = fiber destroy). ONE helper for every runtime gate — the former
- * `config.enabled` sites (request waterfalls, picker-row registration, TUI
- * summary, General-row badge) all read through this.
+ * The no-op gate (AC-8): the plugin intervenes exactly when at least one
+ * named chain is configured. Roles alone no longer activate (a role
+ * without a chain is pure identity). An inactive config is a pass-through
+ * exactly like an uninstalled plugin; the Plugins-page row toggle remains
+ * the master switch (row disable = fiber destroy). A non-empty chain with
+ * empty `entries` still registers the picker row (content presence) but
+ * refuses to delegate (conformance gate in the walk).
  */
 export declare function isFallbackActive(config: FallbacksConfig): boolean;
-/** Role id format (aligned with yet-another-subagent `isValidProfileId`). */
-export declare const ROLE_ID_PATTERN: RegExp;
 /**
  * Minimal logger surface {@link validateFallbacksConfig} warns through —
  * keeps this module free of `@deepseek-ai/*` imports (a cordis Logger is
@@ -182,27 +177,67 @@ export interface FallbacksConfigLogger {
 }
 /**
  * Validate a fallbacks config (pure, warn-only — never throws, never
- * mutates): role id format/uniqueness/reserved word, rule role references
- * (declared ids + the built-in `'inherit'`), the `fallback` enum,
- * `rootChain`/role-chain selector legality, and the role model-config
- * requirement (a declared role with a missing/empty chain warns — a role
- * without a model config is meaningless, plan fallbacks-feedback-round
- * T2). `persona` is free text and is deliberately not
- * validated. Each violation emits one `llm-fallbacks: ...` warn and "does
- * not take effect" — the config stays usable (spec §4 / AC-4
- * warn-not-crash semantics).
+ * mutates). Per chain: id format (case-sensitive, {@link CHAIN_ID_PATTERN})
+ * + cross-chain uniqueness, tail conformance (the LAST entry must be
+ * exactly one official model — a non-conforming chain's slot rows and
+ * delegate stay inert), selector legality per entry, and the slot-row
+ * guards (unknown preset, duplicate preset per chain, preset rows carrying
+ * their own windows). Per role (after the chain loop, so the declared id
+ * set is complete): the existing id format/reserved/duplicate warns, and a
+ * non-empty `chain` pointer naming no declared chain id earns ONE warn and
+ * behaves as NOT SPECIFIED. Each violation emits one `llm-fallbacks: ...`
+ * warn — the config stays usable (warn-not-crash semantics). `persona` and
+ * `label` are free text and deliberately not validated.
  */
 export declare function validateFallbacksConfig(config: FallbacksConfig, logger: FallbacksConfigLogger): void;
 /**
- * Detect legacy (two-block-era) leftovers in a config SOURCE — the composed
- * object `source()` returns, or a raw settings document. Recognizes the
- * removed `chains` key, the removed `roles.default` field, the removed
- * role-entity fields `roles.list[].label` / `roles.list[].description`
- * (renamed to `persona`), and `roles.rules[].role` values that reference no
- * declared `roles.list` id and are not the built-in `'inherit'`. Returns
- * descriptive key/role names; the gateway attaches them as `get().legacyKeys`
- * so the client can show a migration banner (spec §9 — the source is read
- * directly because schemastery retains unknown keys, verified plan Task 1
- * Step 1).
+ * Detect legacy config leftovers in a config SOURCE — the composed object
+ * `source()` returns, or a raw settings document. Two generations:
+ *
+ * - Older removals: `alwaysModeRetryCap`, `roleAutoMatch` (direction C),
+ *   `roles.default`, and the renamed role-entity fields
+ *   `roles.list[].label` / `roles.list[].description`.
+ * - v1 two-block keys (named-virtual-chains): `rootChain`, top-level
+ *   `timeSlots`, `roles.rules`, `roles.list[].fallback`, and the v1 ARRAY
+ *   form of `roles.list[].chain` (an array where v2 declares a string —
+ *   stripped rather than coerced).
+ *
+ * Returns descriptive key names; the gateway attaches them as
+ * `get().legacyKeys` so the client can show a migration banner. Warn-only:
+ * no legacy value is ever read or re-persisted.
  */
 export declare function detectLegacyKeys(source: Record<string, unknown>): string[];
+/**
+ * The chain a v1 `rootChain` migrates into (plan fallbacks-v1-auto-migration):
+ * the id is stable so an already-selected `FallbacksChain/Auto` route keeps
+ * resolving, and the label is display-only.
+ */
+export declare const MIGRATED_CHAIN_ID = "Auto";
+/** Display label of {@link MIGRATED_CHAIN_ID}. */
+export declare const MIGRATED_CHAIN_LABEL = "\u9ED8\u8BA4\u94FE";
+/**
+ * Upgrade a config SOURCE to the v2 named-chain shape — in memory, at every
+ * read. Pure, total, idempotent: a v2 config comes back unchanged, a v1 one is
+ * converted, and any malformed shape degrades to the defaults instead of
+ * throwing (the banner keeps reporting the raw leftovers, so honesty survives
+ * the coercion).
+ *
+ * Conversion rules (plan §Goal):
+ * 1. v1 `rootChain` + top-level `timeSlots` become chain #0
+ *    (`{ id: 'Auto', label: '默认链', entries, timeSlots }`), so the picker
+ *    route the user already selected keeps working.
+ * 2. `roles.list[]` survive as identity rows (`id` / `persona` / reserved
+ *    `prompt` / `permissions`); a v1 ARRAY `chain` is dropped (NOT SPECIFIED —
+ *    the card's 指定降级链 select takes over) and `fallback` is dropped;
+ *    `roles.rules` / `roles.default` / `enabled` never reach the output.
+ * 3. A config that already carries a non-empty `chains` array keeps it and only
+ *    loses the v1 leftovers. An EMPTY `chains` alongside a v1 `rootChain` is a
+ *    profile that never had v2 content, so it migrates (otherwise the user's
+ *    chain would silently vanish).
+ *
+ * No file is rewritten here — the next explicit save persists the v2 shape.
+ * @param source - the composed config (schema defaults → plugin row → user
+ *   layer) or any raw document.
+ * @returns a complete {@link FallbacksConfig}; never the input object itself.
+ */
+export declare function migrateLegacyConfig(source: unknown): FallbacksConfig;

package/dist/cooldown.d.ts

@@ -1,15 +1,11 @@
 /**
- * Cooldown store + per-step failure set (spec §5.1; plan Task 2).
+ * Cooldown store (spec §5.1; plan Task 2).
  *
  * `CooldownStore` maps `provider/model` keys to an expiry epoch ms with lazy
  * evaluation: expired entries are dropped on read. `revertPolicy: 'never'`
  * is expressed by suppressing with `Infinity` — the entry never expires
  * within the session.
  *
- * `StepFailureSet` is the step's failed-model set (spec §5.1 `failed`).
- * `switchCount` / `maxSwitchesPerStep` judgement belongs to the caller
- * (Task 3) — this task only provides the data structure.
- *
  * @module dsh-llm-fallbacks/cooldown
  */
 /**
@@ -45,13 +41,3 @@ export declare class CooldownStore {
         untilEpochMs: number;
     }>;
 }
-/**
- * The current step's failed-model set (`${provider}/${model}` keys).
- */
-export declare class StepFailureSet {
-    private keys;
-    get size(): number;
-    add(key: string): void;
-    has(key: string): boolean;
-    reset(): void;
-}

package/dist/events.d.ts

@@ -15,15 +15,15 @@
  * @module dsh-llm-fallbacks/events
  */
 /**
- * Why a switch was decided (spec §5.1 `PendingSwitch.reason`).
+ * Why a switch was decided — a **history and bookkeeping vocabulary** since
+ * direction C, not a set of live decision paths.
  *
- * `role-inject` is the dispatch-time reason (plan fallbacks-role-automatch
- * Task 4): a subagent-origin agent's first request was re-routed to its
- * resolved role's chain head. It is ADDITIVE to the failure-time reasons —
- * the event shape stays a superset of the pre-feature payload, and existing
- * renderers show unknown reasons raw (AC-5). Unlike `trigger-code` /
- * `always-cap`, a `role-inject` event is NOT a failure decision: it carries
- * no pending switch / cooldown / failure bookkeeping (no `commit()`).
+ * `trigger-code` is the only reason the current code produces (the walk's
+ * swallowed trigger failure, and the blocked-attempt record that mirrors it).
+ * `always-cap` (retired always-mode cap) and `role-inject` (retired
+ * dispatch-time request override) survive only so legacy `fallbacks/switch`
+ * events and their renderers keep a label; nothing writes them any more, and
+ * an unknown reason still renders raw (AC-5).
  */
 export type FallbackSwitchReason = 'trigger-code' | 'always-cap' | 'role-inject';
 /** Durable payload of one provider/model switch (spec §5 table). */