dsh-llm-fallbacks 0.1.0-alpha.1

package/dist/client/locales.d.ts

@@ -0,0 +1,281 @@
+import type { FallbackSwitchReason } from '../events.ts';
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    title: string;
+    intro: string;
+    collapse: string;
+    expand: string;
+    unsaved: string;
+    discard: string;
+    retry: string;
+    readOnly: string;
+    'enabled.label': string;
+    'enabled.hint': string;
+    'enabled.tooltip': string;
+    'enabled.off': string;
+    'triggerCodes.label': string;
+    'triggerCodes.hint': string;
+    'triggerCodes.tooltip': string;
+    'triggerCodes.RATE_LIMIT': string;
+    'triggerCodes.QUOTA': string;
+    'triggerCodes.AUTH': string;
+    'triggerCodes.extra': string;
+    'revertPolicy.label': string;
+    'revertPolicy.cooldown-expiry': string;
+    'revertPolicy.never': string;
+    'revertPolicy.hint': string;
+    'revertPolicy.tooltip': string;
+    'cooldownMs.label': string;
+    'cooldownMs.hint': string;
+    'cooldownMs.tooltip': string;
+    'maxSwitchesPerStep.label': string;
+    'maxSwitchesPerStep.hint': string;
+    'maxSwitchesPerStep.tooltip': string;
+    'alwaysModeRetryCap.label': string;
+    'alwaysModeRetryCap.hint': string;
+    'alwaysModeRetryCap.tooltip': string;
+    'rootChain.label': string;
+    'rootChain.hint': string;
+    'rootChain.tooltip': string;
+    'rootChain.selector.add': string;
+    'chains.selector.remove': string;
+    'chains.selector.providerPlaceholder': string;
+    'chains.selector.modelPlaceholder': string;
+    'chains.selector.wildcard': string;
+    'chains.selector.noModels': string;
+    'roles.list.label': string;
+    'roles.list.hint': string;
+    'roles.list.tooltip': string;
+    'roles.id': string;
+    'roles.id.hint': string;
+    'roles.idPlaceholder': string;
+    'roles.label': string;
+    'roles.description': string;
+    'roles.fallback': string;
+    'roles.fallback.inherit-root': string;
+    'roles.fallback.none': string;
+    'roles.add': string;
+    'roles.remove': string;
+    'roles.selector.add': string;
+    'roles.rules': string;
+    'roles.rules.hint': string;
+    'roles.rules.tooltip': string;
+    'roles.rule.origin': string;
+    'roles.rule.origin.any': string;
+    'roles.rule.origin.root': string;
+    'roles.rule.origin.subagent': string;
+    'roles.rule.provider': string;
+    'roles.rule.provider.any': string;
+    'roles.rule.model': string;
+    'roles.rule.model.any': string;
+    'roles.rule.role': string;
+    'roles.rule.role.inherit': string;
+    'roles.rule.roleSelectPlaceholder': string;
+    'roles.rule.roleUndeclared.short': string;
+    'roles.addRule': string;
+    'roles.removeRule': string;
+    'validation.blocked': string;
+    'validation.roleIdFormat': string;
+    'validation.roleIdReserved': string;
+    'validation.roleIdDuplicate': string;
+    'validation.ruleRoleUndeclared': string;
+    'validation.ruleRoleRequired': string;
+    'validation.selector': string;
+    'legacy.banner': string;
+    'catalog.empty': string;
+    'catalog.error': string;
+    'catalog.partial': string;
+    'catalog.outside.hint': string;
+    'catalog.outside.tooltip': string;
+    'catalog.outside.short': string;
+    'catalog.unconfigured.short': string;
+    'status.title': string;
+    'status.effectiveModel.label': string;
+    'status.effectiveModel.unavailable': string;
+    'status.effectiveModel.note': string;
+    'status.switches.label': string;
+    'status.switches.empty': string;
+    'status.switches.error': string;
+    'status.switches.compact': string;
+    'status.switches.reason.trigger-code': string;
+    'status.switches.reason.always-cap': string;
+    'status.selectionNote': string;
+    'general.title': string;
+    'general.enabled': string;
+    'general.disabled': string;
+    'general.unknown': string;
+    'general.unavailable': string;
+    'general.switch': string;
+    'general.switch.empty': string;
+    'general.error': string;
+    'chat.switch.title': string;
+    'chat.switch.summary': string;
+    'defaults.prefix': string;
+    save: string;
+    'save.saving': string;
+    'save.error': string;
+    close: string;
+    reset: string;
+    'reset.confirmTitle': string;
+    'reset.confirm': string;
+    'reset.confirm.cancel': string;
+    'reset.confirm.action': string;
+    'reset.saving': string;
+    loading: string;
+    unavailable: string;
+    'error.generic': string;
+};
+/** The fallbacks dictionary key union. */
+export type FallbacksKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    title: string;
+    intro: string;
+    collapse: string;
+    expand: string;
+    unsaved: string;
+    discard: string;
+    retry: string;
+    readOnly: string;
+    'enabled.label': string;
+    'enabled.hint': string;
+    'enabled.tooltip': string;
+    'enabled.off': string;
+    'triggerCodes.label': string;
+    'triggerCodes.hint': string;
+    'triggerCodes.tooltip': string;
+    'triggerCodes.RATE_LIMIT': string;
+    'triggerCodes.QUOTA': string;
+    'triggerCodes.AUTH': string;
+    'triggerCodes.extra': string;
+    'revertPolicy.label': string;
+    'revertPolicy.cooldown-expiry': string;
+    'revertPolicy.never': string;
+    'revertPolicy.hint': string;
+    'revertPolicy.tooltip': string;
+    'cooldownMs.label': string;
+    'cooldownMs.hint': string;
+    'cooldownMs.tooltip': string;
+    'maxSwitchesPerStep.label': string;
+    'maxSwitchesPerStep.hint': string;
+    'maxSwitchesPerStep.tooltip': string;
+    'alwaysModeRetryCap.label': string;
+    'alwaysModeRetryCap.hint': string;
+    'alwaysModeRetryCap.tooltip': string;
+    'rootChain.label': string;
+    'rootChain.hint': string;
+    'rootChain.tooltip': string;
+    'rootChain.selector.add': string;
+    'chains.selector.remove': string;
+    'chains.selector.providerPlaceholder': string;
+    'chains.selector.modelPlaceholder': string;
+    'chains.selector.wildcard': string;
+    'chains.selector.noModels': string;
+    'roles.list.label': string;
+    'roles.list.hint': string;
+    'roles.list.tooltip': string;
+    'roles.id': string;
+    'roles.id.hint': string;
+    'roles.idPlaceholder': string;
+    'roles.label': string;
+    'roles.description': string;
+    'roles.fallback': string;
+    'roles.fallback.inherit-root': string;
+    'roles.fallback.none': string;
+    'roles.add': string;
+    'roles.remove': string;
+    'roles.selector.add': string;
+    'roles.rules': string;
+    'roles.rules.hint': string;
+    'roles.rules.tooltip': string;
+    'roles.rule.origin': string;
+    'roles.rule.origin.any': string;
+    'roles.rule.origin.root': string;
+    'roles.rule.origin.subagent': string;
+    'roles.rule.provider': string;
+    'roles.rule.provider.any': string;
+    'roles.rule.model': string;
+    'roles.rule.model.any': string;
+    'roles.rule.role': string;
+    'roles.rule.role.inherit': string;
+    'roles.rule.roleSelectPlaceholder': string;
+    'roles.rule.roleUndeclared.short': string;
+    'roles.addRule': string;
+    'roles.removeRule': string;
+    'validation.blocked': string;
+    'validation.roleIdFormat': string;
+    'validation.roleIdReserved': string;
+    'validation.roleIdDuplicate': string;
+    'validation.ruleRoleUndeclared': string;
+    'validation.ruleRoleRequired': string;
+    'validation.selector': string;
+    'legacy.banner': string;
+    'catalog.empty': string;
+    'catalog.error': string;
+    'catalog.partial': string;
+    'catalog.outside.hint': string;
+    'catalog.outside.tooltip': string;
+    'catalog.outside.short': string;
+    'catalog.unconfigured.short': string;
+    'status.title': string;
+    'status.effectiveModel.label': string;
+    'status.effectiveModel.unavailable': string;
+    'status.effectiveModel.note': string;
+    'status.switches.label': string;
+    'status.switches.empty': string;
+    'status.switches.error': string;
+    'status.switches.compact': string;
+    'status.switches.reason.trigger-code': string;
+    'status.switches.reason.always-cap': string;
+    'status.selectionNote': string;
+    'general.title': string;
+    'general.enabled': string;
+    'general.disabled': string;
+    'general.unknown': string;
+    'general.unavailable': string;
+    'general.switch': string;
+    'general.switch.empty': string;
+    'general.error': string;
+    'chat.switch.title': string;
+    'chat.switch.summary': string;
+    'defaults.prefix': string;
+    save: string;
+    'save.saving': string;
+    'save.error': string;
+    close: string;
+    reset: string;
+    'reset.confirmTitle': string;
+    'reset.confirm': string;
+    'reset.confirm.cancel': string;
+    'reset.confirm.action': string;
+    'reset.saving': string;
+    loading: string;
+    unavailable: string;
+    'error.generic': string;
+};
+/** The settings section's dictionary namespace. */
+export declare const NS = "fallbacks";
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** This feature's settings-section copy. */
+        fallbacks: FallbacksKey;
+    }
+}
+/**
+ * Reason → locale key map for switch summaries (S-c; shared by the card's
+ * status block and the General page status row). The session log is durable
+ * and forward-compatible: a reason value outside the current union (a newer
+ * plugin wrote it) renders raw instead of falling into a binary else branch.
+ */
+export declare const SWITCH_REASON_KEYS: Readonly<Partial<Record<FallbackSwitchReason, FallbacksKey>>>;
+/** Human-readable trigger-code labels (spec §4 用户直观性). */
+export declare const TRIGGER_CODE_LABELS: Readonly<Record<string, FallbacksKey>>;
+/**
+ * The known trigger codes the form toggles; unknown codes are preserved.
+ * M-04: derived from the host defaults so the toggle set can never drift from
+ * the decision set (`defaultFallbacksConfig.triggerCodes` is the single
+ * source of truth; the labels mapping above stays keyed by code).
+ */
+export declare const KNOWN_TRIGGER_CODES: readonly string[];
+/** Toggle one known code's membership in `codes` (used by the form; pure). */
+export declare function withTriggerCode(codes: readonly string[], code: string, present: boolean): string[];

package/dist/client/switch-guard.d.ts

@@ -0,0 +1,17 @@
+import type { FallbacksSwitchEventData } from '../events.ts';
+/**
+ * True when `value` is a well-formed `fallbacks/switch` payload — the ONE
+ * client-side shape guard, shared by the conversation node definition's
+ * `match`/`start` and the renderer's degrade check (both in
+ * `src/client/ConversationFallbackSwitch.tsx`).
+ *
+ * The durable session log is append-only and survives plugin/host upgrades,
+ * so a `fallbacks/switch` event or node payload may carry a stale or
+ * corrupted shape — version skew must degrade the transcript line (a
+ * title-only notice), never crash the session assembly or the renderer.
+ *
+ * The HOST-side mirror (`src/commands.ts` `isFallbacksSwitchData`) lives in
+ * a DIFFERENT bundle (host vs client) — it intentionally stays separate; do
+ * not merge the two guards across the bundle boundary.
+ */
+export declare function isFallbacksSwitchData(value: unknown): value is FallbacksSwitchEventData;

package/dist/commands.d.ts

@@ -0,0 +1,176 @@
+/**
+ * `/fallbacks` slash command (plan fallbacks-role-runtime T3, AC-5).
+ *
+ * Session-scoped, read-only diagnostic: current session origin → resolved
+ * role → resolved chain (role chain, else rootChain — an `inherit: true`
+ * tail is annotated 「（inherit-root）」) → recent `fallbacks/switch` events
+ * (newest first, capped) → cooldown status. Mirrors dsh-advisor's
+ * `/advisor` command pattern: a conditional `ctx.inject(['commands'])` child
+ * in `src/index.ts` calls {@link registerFallbacksCommands} with a
+ * factory-bound handler; `commands` never joins the top-level inject list, so
+ * the command is silently absent when no command registry is composed (no
+ * top-level inject pollution — advisor T1 fix).
+ *
+ * The handler is **read-only**: it never mutates fallback state (no cooldown
+ * reset, no pending-switch writes). zh/en copy lives in this file — the
+ * client half's `src/client/locales.ts` is a separate client-side dictionary.
+ * The host carries no per-session locale signal (the `locale` service is
+ * client-side), so the wiring picks a deterministic default (`zh`, this
+ * repo's primary language); both dictionaries are unit-tested.
+ *
+ * @module dsh-llm-fallbacks/commands
+ */
+import type { CommandDefinition } from '@deepseek-ai/dsh-commands';
+import { type FallbacksRole } from './config.ts';
+import type { Origin } from './roles.ts';
+import type { FallbacksSwitchEventData } from './events.ts';
+/** How many recent `fallbacks/switch` events `/fallbacks` shows (newest first). */
+export declare const RECENT_SWITCHES_LIMIT = 5;
+/** Minimal command registry surface (satisfied by the dsh `CommandService`). */
+export interface FallbacksCommandRegistry {
+    register(definition: CommandDefinition): () => void;
+}
+/** Minimal agent/session surface the command reads (satisfied by the real `Agent`). */
+export interface FallbacksCommandAgent {
+    readonly id: string;
+    readonly options?: {
+        readonly provider?: string;
+        readonly model?: string;
+    };
+    readonly session: {
+        readonly header?: {
+            readonly origin?: Origin;
+        };
+        readonly events: readonly unknown[];
+    };
+}
+/** One active cooldown entry displayed by `/fallbacks`. */
+export interface FallbacksCooldownEntry {
+    /** `${provider}/${model}` key. */
+    readonly key: string;
+    /** Expiry epoch ms; `Infinity` for `revertPolicy: 'never'`. */
+    readonly untilEpochMs: number;
+}
+/** The read-only diagnostic snapshot the `/fallbacks` handler renders. */
+export interface FallbacksCommandSnapshot {
+    /** Session origin: `'root'` when the agent carries no header origin. */
+    readonly origin: Origin;
+    /** Resolved role (first matching `roles.rules` entry → built-in `'inherit'`, spec §7.1). */
+    readonly role: string;
+    /** True when the role's own chain is non-empty and shown; false when rootChain (or none) is shown. */
+    readonly chainRole: boolean;
+    /** The displayed chain entries: the role's own chain when non-empty, else
+     * rootChain — except `fallback: 'none'` with an empty own chain, which
+     * yields `[]` even when rootChain is non-empty (nothing appended, mirroring
+     * resolveChainViews' `[...[], ...[]]`); empty = not configured. */
+    readonly chain: readonly string[];
+    /** True when rootChain is appended as the inherit fallback tail (role's
+     * `fallback` is `'inherit-root'` — or the role is unknown — and rootChain
+     * is non-empty; the diagnostic annotation source, spec §7.4). */
+    readonly inherit: boolean;
+    /** Recent `fallbacks/switch` events, newest first, capped at {@link RECENT_SWITCHES_LIMIT}. */
+    readonly switches: readonly FallbacksSwitchEventData[];
+    /** Active cooldown entries for the agent. */
+    readonly cooldown: readonly FallbacksCooldownEntry[];
+}
+/**
+ * The session-scoped read-only operations the `/fallbacks` handler drives.
+ * Implemented by the wiring (`src/index.ts`) against the live config source
+ * (`roles.list` / `rootChain` — no chain map anymore) and the per-agent
+ * state store; faked in unit tests.
+ */
+export interface FallbacksCommandController {
+    /** Snapshot the session's fallback diagnostics. Never mutates state. */
+    getSnapshot(agent: FallbacksCommandAgent): FallbacksCommandSnapshot;
+}
+/** zh/en dictionaries for the `/fallbacks` output. */
+export declare const FALLBACKS_COMMAND_LOCALES: {
+    readonly zh: {
+        readonly title: "当前会话 fallback 诊断（只读）";
+        readonly description: "查看当前会话的降级链、最近切换与冷却状态（只读）";
+        readonly origin: "会话来源";
+        readonly role: "角色";
+        readonly chain: "链";
+        readonly inheritRoot: "（inherit-root）";
+        readonly chainNone: "未配置";
+        readonly switches: "最近切换";
+        readonly switchesNone: "本会话暂无 fallback 切换";
+        readonly switchLine: "{from} → {to}（role={role}，reason={reason}）";
+        readonly cooldown: "冷却";
+        readonly cooldownNone: "无活跃冷却";
+        readonly cooldownLine: "{key} 冷却至 {time}";
+        readonly cooldownNever: "{key} 会话内不再回主";
+        readonly reason: {
+            readonly 'trigger-code': "触发码";
+            readonly 'always-cap': "always 上限";
+        };
+    };
+    readonly en: {
+        readonly title: "Session fallback diagnostics (read-only)";
+        readonly description: "Inspect fallback chain, recent switches, and cooldown for this session (read-only)";
+        readonly origin: "Session origin";
+        readonly role: "Role";
+        readonly chain: "Chain";
+        readonly inheritRoot: " (inherit-root)";
+        readonly chainNone: "not configured";
+        readonly switches: "Recent switches";
+        readonly switchesNone: "No fallback switches in this session";
+        readonly switchLine: "{from} → {to} (role={role}, reason={reason})";
+        readonly cooldown: "Cooldown";
+        readonly cooldownNone: "none active";
+        readonly cooldownLine: "{key} suppressed until {time}";
+        readonly cooldownNever: "{key} not reverting this session";
+        readonly reason: {
+            readonly 'trigger-code': "trigger-code";
+            readonly 'always-cap': "always-cap";
+        };
+    };
+};
+/** A locale id supported by {@link FALLBACKS_COMMAND_LOCALES}. */
+export type FallbacksCommandLocale = keyof typeof FALLBACKS_COMMAND_LOCALES;
+/**
+ * The newest `limit` `fallbacks/switch` events from a session's raw event
+ * log, newest first. Unknown event shapes and malformed `fallbacks/switch`
+ * payloads are skipped defensively (a session log may carry any
+ * `SessionEventMap` type, and the durable log can outlive schema versions).
+ */
+export declare function recentFallbacksSwitches(events: readonly unknown[], limit: number): FallbacksSwitchEventData[];
+/**
+ * The chain entries `/fallbacks` shows for a role (spec §7.4): the declared
+ * role's own chain when non-empty (`chainRole: true`); an empty own chain
+ * defers to `rootChain` unless `fallback: 'none'` — then nothing is appended
+ * and the display chain is empty, mirroring `resolveChainViews`'s
+ * `[...[], ...[]]` exactly; undeclared ids and the built-in `'inherit'`
+ * role resolve to `rootChain`. `inherit: true` marks the append-not-replace
+ * tail — the role's `fallback` is `'inherit-root'` (the default) or the role
+ * is unknown/built-in `'inherit'`, and `rootChain` is non-empty. Mirrors
+ * `resolveChainViews`'s concatenation (see {@link buildRoleEntries} —
+ * `src/chains.ts`; the diagnostic keeps its display semantics: the role's
+ * own chain renders in full, `rootChain` only when the role has no own
+ * chain, with the inherit tail as an annotation) without a failing model to
+ * resolve against (the diagnostic is model-independent).
+ *
+ * `warn` mirrors {@link resolveChainViews}' defensive unknown-role warn
+ * (qc2 F-002 — routed through the injected logger; the `/fallbacks` path
+ * never reaches here unsanitized, as {@link resolveRole} resolves to a
+ * declared id or `'inherit'` first, so this is direct-caller parity).
+ */
+export declare function resolveChainForDiagnostic(roles: readonly FallbacksRole[], rootChain: readonly string[], role: string, warn?: (message: string) => void): {
+    readonly chainRole: boolean;
+    readonly chain: readonly string[];
+    readonly inherit: boolean;
+};
+/**
+ * Render the `/fallbacks` status surface for one snapshot. Kept minimal and
+ * truthful: origin → role → chain (+ inherit tail) → recent switches →
+ * cooldown.
+ */
+export declare function fallbacksCommandText(snapshot: FallbacksCommandSnapshot, locale?: FallbacksCommandLocale): string;
+/**
+ * Register the `/fallbacks` command with a command registry (the dsh
+ * `CommandService`, or a fake in tests). Called from the plugin's conditional
+ * `ctx.inject(['commands'], ...)` child — the command exists only when a
+ * registry is composed.
+ * @returns the registry disposer (the inject child owns its lifetime).
+ */
+export declare function registerFallbacksCommands(registry: FallbacksCommandRegistry, controller: FallbacksCommandController, locale?: FallbacksCommandLocale): () => void;

package/dist/config.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The `fallbacks` settings namespace: plugin config schema + defaults.
+ *
+ * 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/label/description/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()).
+ *
+ * Spec §4 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 (`enabled: false`, empty `rootChain`, empty roles)
+ * is a no-op pass-through exactly like an uninstalled plugin (AC-8).
+ *
+ * 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 this schema with `installSettingsSection` under the `fallbacks`
+ * settings namespace.
+ *
+ * @module dsh-llm-fallbacks/config
+ */
+import z from 'schemastery';
+/** How a cooled-down model comes back (spec §4). */
+export type RevertPolicy = 'cooldown-expiry' | 'never';
+/** A single role rule: match on origin/provider/model patterns (spec §3). */
+export interface FallbacksRoleRule {
+    origin?: 'root' | 'subagent';
+    provider?: string;
+    model?: string;
+    role: string;
+}
+/**
+ * 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.
+ */
+export type FallbackStrategy = 'inherit-root' | 'none';
+/**
+ * A declared role entity (plan fallbacks-role-config-model Task 1).
+ *
+ * `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.
+ */
+export interface FallbacksRole {
+    id: string;
+    label: string;
+    description: string;
+    /** Reserved for next iteration — no consumer this round. */
+    prompt?: string;
+    /** Reserved for next iteration — no consumer this round. */
+    permissions?: {
+        allow?: string[];
+        deny?: string[];
+    };
+    chain?: string[];
+    fallback?: FallbackStrategy;
+}
+/** Role grouping for fallback chains: declared entities + enum references. */
+export interface FallbacksRoles {
+    list: FallbacksRole[];
+    rules: FallbacksRoleRule[];
+}
+/**
+ * The full `fallbacks` settings shape (two-block config model, verbatim
+ * field names).
+ */
+export interface FallbacksConfig {
+    enabled: boolean;
+    triggerCodes: string[];
+    rootChain: string[];
+    roles: FallbacksRoles;
+    cooldownMs: number;
+    revertPolicy: RevertPolicy;
+    maxSwitchesPerStep: number;
+    alwaysModeRetryCap: number;
+}
+/**
+ * Spec §4 defaults — `Config({})` must equal this (no-op install).
+ * `enabled` defaults to `false` (readme-settings spec §1.2): the feature
+ * switch is off until the user turns it on in the settings page; an
+ * unconfigured install (`enabled: false`, empty rootChain, empty roles)
+ * behaves exactly like an uninstalled plugin (AC-3 / no-op invariant).
+ */
+export declare const defaultFallbacksConfig: FallbacksConfig;
+/**
+ * Reserved role id: legal as a rule target (`roles.rules[].role`) and as
+ * the no-rule-match fallback, but FORBIDDEN in `roles.list[].id`.
+ */
+export declare const INHERIT_ROLE_ID = "inherit";
+/** 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
+ * structurally compatible).
+ */
+export interface FallbacksConfigLogger {
+    warn(message: string): void;
+}
+/**
+ * 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, and
+ * `rootChain`/role-chain selector legality. `label`/`description` are free
+ * text and are 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).
+ */
+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, 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).
+ */
+export declare function detectLegacyKeys(source: Record<string, unknown>): string[];
+/**
+ * Plugin Config schema (schemastery), mirroring {@link FallbacksConfig}.
+ * Object fields are optional by default in schemastery; `.default()` fills
+ * the spec defaults, `.required()` keeps mandatory fields. Unknown keys are
+ * RETAINED by the composition (verified plan Task 1 Step 1) — that is what
+ * lets `detectLegacyKeys` flag two-block-era leftovers (`chains` /
+ * `roles.default`) on the composed object at startup (warn + gateway
+ * `legacyKeys`, see `src/index.ts` apply()).
+ */
+export declare const Config: z<FallbacksConfig>;

package/dist/cooldown.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cooldown store + per-step failure set (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
+ */
+/**
+ * Per-agent model cooldown: `suppress(key, untilEpochMs)` then
+ * `isSuppressed(key, now?)` with lazy expiry.
+ */
+export declare class CooldownStore {
+    private entries;
+    /** Number of tracked keys (expired entries are dropped lazily on read). */
+    get size(): number;
+    /** Suppress `key` until `untilEpochMs` (use `Infinity` for `revertPolicy: 'never'`). */
+    suppress(key: string, untilEpochMs: number): void;
+    /** True while `key` is suppressed at time `now` (default `Date.now()`); expired entries are removed. */
+    isSuppressed(key: string, now?: number): boolean;
+    /**
+     * Read-only diagnostic accessor: the active (non-expired) entries, in
+     * insertion order. This is a pure read — expired entries are FILTERED OUT
+     * but left in the store; the lazy delete happens only in
+     * {@link isSuppressed} (the decision path). `Infinity` entries are always
+     * active. Consumed by the `/fallbacks` command's cooldown display.
+     */
+    snapshot(now?: number): Array<{
+        key: string;
+        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;
+}