dsh-llm-fallbacks 0.6.1 → 0.6.3

package/dist/client/locales.d.ts

@@ -1,18 +1,9 @@
 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;
@@ -199,18 +190,9 @@ export declare const zh: {
 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;

package/dist/commands.d.ts

@@ -109,7 +109,12 @@ export interface FallbacksCommandSnapshot {
  * runtime) is summarized as `''` and rendered as `*`.
  */
 export interface FallbacksConfigSummary {
-    readonly enabled: boolean;
+    /**
+     * Content-presence gate (`isFallbackActive`, plan fallbacks-web-ux-alignment
+     * T2 — the removed config-level `enabled` switch re-keyed): the plugin
+     * intervenes exactly when a chain/time-slot/role is configured.
+     */
+    readonly active: boolean;
     readonly triggerCodes: readonly string[];
     readonly rootChain: readonly string[];
     /** Summarized time-slot rows (preset rows carry `preset`, custom rows carry `start`/`end`; both may carry a day mask). */

package/dist/config.d.ts

@@ -17,8 +17,14 @@
  * 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).
+ * 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.
  *
  * This module is pure logic: it must not import any `@deepseek-ai/*` package
  * (types included) — `FallbacksConfig` is the plugin's own type. Task 3
@@ -82,7 +88,6 @@ export interface FallbacksRoles {
  * field names).
  */
 export interface FallbacksConfig {
-    enabled: boolean;
     triggerCodes: string[];
     rootChain: string[];
     roles: FallbacksRoles;
@@ -142,10 +147,10 @@ export interface FallbacksConfig {
 }
 /**
  * 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).
+ * 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}).
  */
 export declare const defaultFallbacksConfig: FallbacksConfig;
 /**
@@ -153,6 +158,18 @@ export declare const defaultFallbacksConfig: FallbacksConfig;
  * the no-rule-match fallback, but FORBIDDEN in `roles.list[].id`.
  */
 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.
+ */
+export declare function isFallbackActive(config: FallbacksConfig): boolean;
 /** Role id format (aligned with yet-another-subagent `isValidProfileId`). */
 export declare const ROLE_ID_PATTERN: RegExp;
 /**

package/dist/gateway.d.ts

@@ -28,7 +28,12 @@
  * 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 — `enabled` is a plain config field, not a gate output.
+ * 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
+ * tolerated-and-stripped ({@link LEGACY_KEYS} — never read, never
+ * re-persisted).
  * `set` validates the patch against the `Config` schema first (unknown-key
  * rejection unchanged — the settings service itself is non-strict and would
  * merge the unknown key through), then writes the plugin's profile-entry
@@ -213,7 +218,8 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
     /**
      * 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 — `enabled` is a plain field, not a gate output.
+     * 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,

package/dist/index.d.ts

@@ -11,7 +11,8 @@
  *   `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: `!enabled` / code ∉ `triggerCodes`
+ * - `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 +

package/dist/index.js

@@ -323,7 +323,6 @@ var RecoveryStore = class {
 //#endregion
 //#region .build/host/config.js
 const defaultFallbacksConfig = {
-	enabled: false,
 	triggerCodes: [
 		"AUTH",
 		"QUOTA",
@@ -345,6 +344,9 @@ const defaultFallbacksConfig = {
 	recovery: "timer"
 };
 const INHERIT_ROLE_ID = "inherit";
+function isFallbackActive(config) {
+	return config.rootChain.length > 0 || (config.timeSlots?.length ?? 0) > 0 || config.roles.list.length > 0;
+}
 const ROLE_ID_PATTERN = /^[a-z0-9-]{1,32}$/;
 function validateFallbacksConfig(config, logger) {
 	const declaredIds = new Set();
@@ -412,7 +414,6 @@ function isRecordLike(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 const Config = z.object({
-	enabled: z.boolean().default(false),
 	triggerCodes: z.array(z.string()).default([
 		"AUTH",
 		"QUOTA",
@@ -874,7 +875,7 @@ const ROLE_STATE_SCHEMA = { parse(value) {
 			};
 		}
 	}
-	throw new TypeError(`role projection: expected null or a non-blank role id with its fork boundary, got ${describeValue(value)}`);
+	return null;
 } };
 function isInheritedEventCount(value) {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -1515,7 +1516,6 @@ function overrideConfigWithRouteRule(seed, to, explicitEffort) {
 //#region .build/host/gateway.js
 const FALLBACKS_PROFILE_ENTRY = "llm-fallbacks";
 const CONFIG_KEYS = {
-	enabled: true,
 	triggerCodes: true,
 	rootChain: true,
 	roles: true,
@@ -1533,6 +1533,7 @@ const ROLES_KEYS = {
 	list: true,
 	rules: true
 };
+const LEGACY_KEYS = new Set(["enabled"]);
 const SLOT_ROW_KEYS = {
 	kind: true,
 	preset: true,
@@ -1568,7 +1569,7 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 		if (Object.keys(patch).length === 0) return this.readResult();
 		const settings = this.settings;
 		if (settings === void 0) throw new Error("fallbacks: settings service is unavailable — configuration cannot be written");
-		const normalized = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== null));
+		const normalized = Object.fromEntries(Object.entries(patch).filter(([key, value]) => !LEGACY_KEYS.has(key) && value !== null));
 		if (Object.keys(normalized).length === 0) return this.readResult();
 		await settings.update(FALLBACKS_PROFILE_ENTRY, normalized);
 		return this.readResult();
@@ -1665,7 +1666,7 @@ function normalizeRoles(value) {
 function validateConfigPatch(patch) {
 	if (patch === null || typeof patch !== "object" || Array.isArray(patch)) throw new TypeError("dsh-llm-fallbacks: configuration patch must be a plain object");
 	for (const key of Object.keys(patch)) {
-		if (!Object.hasOwn(CONFIG_KEYS, key)) throw new Error(`dsh-llm-fallbacks: unknown config key "${key}"`);
+		if (!Object.hasOwn(CONFIG_KEYS, key) && !LEGACY_KEYS.has(key)) throw new Error(`dsh-llm-fallbacks: unknown config key "${key}"`);
 		if (key === "roles") {
 			const roles = patch[key];
 			if (roles !== null && typeof roles === "object" && !Array.isArray(roles)) {
@@ -2021,7 +2022,7 @@ function formatConfigRules(rules, t) {
 function fallbacksConfigText(summary, locale = "zh") {
 	const t = FALLBACKS_COMMAND_LOCALES[locale];
 	return [
-		`${t.configTitle}: ${summary.enabled ? t.configEnabled : t.configDisabled}`,
+		`${t.configTitle}: ${summary.active ? t.configEnabled : t.configDisabled}`,
 		`${t.configTriggerCodes}: ${summary.triggerCodes.length === 0 ? t.configEmpty : formatConfigList(summary.triggerCodes)}`,
 		`${t.configRootChain}: ${summary.rootChain.length === 0 ? t.configEmpty : formatConfigList(summary.rootChain)}`,
 		`${t.configTimeSlots}: ${summary.timeSlots.length === 0 ? t.configEmpty : formatConfigTimeSlots(summary.timeSlots, t)}`,
@@ -2513,16 +2514,6 @@ function buildFallbacksTuiSection() {
 			}
 		],
 		fields: [
-			{
-				path: ["enabled"],
-				label: "Enabled",
-				descriptions: {
-					zh: "启用回退",
-					en: "Enabled"
-				},
-				group: "general",
-				kind: "boolean"
-			},
 			{
 				path: ["roleAutoMatch"],
 				label: "LLM role auto-match",
@@ -2886,7 +2877,7 @@ function installFallbacksAdapter(ctx, readConfig) {
 	const logger = ctx.logger("llm-fallbacks");
 	const adapter = new FallbacksChainAdapter(readConfig, () => llm);
 	const reconcile = () => {
-		const shouldRegister = readConfig().enabled;
+		const shouldRegister = isFallbackActive(readConfig());
 		if (shouldRegister && !registered) {
 			if (llm === void 0) return;
 			try {
@@ -3296,7 +3287,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	}
 	ctx.on("agent/request-error", async ({ agent, turn, step, provider, failure }, next) => {
 		const config = source();
-		if (!config.enabled || !config.triggerCodes.includes(failure.code)) return next();
+		if (!isFallbackActive(config) || !config.triggerCodes.includes(failure.code)) return next();
 		const current = currentModel(agent, provider, config, new Date());
 		if (!current.model) return next();
 		try {
@@ -3322,7 +3313,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		const applied = state === void 0 ? void 0 : states.applyPending(state, turn, step);
 		if (applied !== void 0) return overrideConfig(seed, applied.to);
 		const config = source();
-		if (config.enabled && isAllDayConforming(config.rootChain) && (config.timeSlots?.length ?? 0) > 0 && agent.session?.header?.origin !== "subagent") {
+		if (isFallbackActive(config) && isAllDayConforming(config.rootChain) && (config.timeSlots?.length ?? 0) > 0 && agent.session?.header?.origin !== "subagent") {
 			const slot = resolveSlotState(config, new Date(), config.tz ?? "Asia/Shanghai");
 			const key = slotWinnerKey(slot.winner);
 			const previous = slotWinners.get(agent.id);
@@ -3332,7 +3323,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 				label: slot.label
 			});
 		}
-		if (config.enabled && hasChains && agent.session?.header?.origin === "subagent" && !dispatchInjected.has(agent.id)) {
+		if (isFallbackActive(config) && hasChains && agent.session?.header?.origin === "subagent" && !dispatchInjected.has(agent.id)) {
 			dispatchInjected.add(agent.id);
 			try {
 				const settingsRead = readGuardedPolicySettings(ctx, agent.id, lastKnownPolicySettings, logger.warn);
@@ -3390,7 +3381,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 				logger.warn("llm-fallbacks: dispatch role-injection failed, proceeding with the request unchanged: %s", error?.message ?? String(error));
 			}
 		}
-		if (hasChains && config.enabled && config.alwaysModeRetryCap > 0 && countRetryEvents(agent.session, turn, step, seed.provider) >= config.alwaysModeRetryCap) {
+		if (hasChains && isFallbackActive(config) && config.alwaysModeRetryCap > 0 && countRetryEvents(agent.session, turn, step, seed.provider) >= config.alwaysModeRetryCap) {
 			const decisionState = states.peek(agent.id);
 			const capRoute = anchorServedRoute(config, {
 				provider: seed.provider,
@@ -3469,7 +3460,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		getConfig() {
 			const config = source();
 			return {
-				enabled: config.enabled,
+				active: isFallbackActive(config),
 				triggerCodes: config.triggerCodes,
 				rootChain: config.rootChain,
 				timeSlots: (config.timeSlots ?? []).map((row) => row.kind === "preset" ? {

package/dist/tui-settings.d.ts

@@ -114,9 +114,12 @@ export declare const FALLBACKS_TUI_SECTION_NS = "fallbacks";
  */
 export declare const JSON_FIELD_MAX_DRAFT_BYTES: number;
 /**
- * The `fallbacks` /settings section: 13 fields covering all 15 web-card
+ * The `fallbacks` /settings section: 12 fields covering all 14 web-card
  * capabilities (the default-model choice rides `rootChain`'s last entry and
- * the per-role fallback strategy rides `roles.list` JSON). Scalar
+ * the per-role fallback strategy rides `roles.list` JSON; the config-level
+ * `enabled` switch is REMOVED — plan fallbacks-web-ux-alignment T2, the
+ * Plugins-page row toggle is the master switch and the runtime gates read
+ * content presence). Scalar
  * capabilities use native kinds (boolean/number/select); complex structures
  * use `text` fields with custom `format`/`parse` that mirror the gateway's
  * validation. Built fresh per call — the host deep-freezes whatever it

package/dist/virtual-adapter.d.ts

@@ -9,15 +9,20 @@
  * `ctx.inject(['llm'])` child — absent `llm` service (test harness) is a
  * clean no-op, and fiber unload ⇒ the child's disposer unregisters the
  * route. Registration is an idempotent transition-reconcile on COMMITTED
- * config snapshots: register on `enabled` false→true, unregister on
- * true→false, driven by the settings `onChange` hook (the returned
- * reconcile thunk, wired by `apply()`) plus child activation. The row is
- * visible whenever the plugin is enabled — a non-conforming all-day chain
- * does NOT hide it (PR #62 feedback); conformance still gates a
- * successful delegate (`effectiveHeadOf` below refuses a
- * non-conforming all-day). The condition deliberately ignores `timeSlots`
- * and conformance, so slot-row edits and chain edits never churn
- * registration.
+ * config snapshots: register when nothing is configured → something is
+ * (`isFallbackActive` — content presence, plan fallbacks-web-ux-alignment
+ * T2), unregister on the reverse, driven by the settings `onChange` hook
+ * (the returned reconcile thunk, wired by `apply()`) plus child activation.
+ * The row is visible whenever something is configured — a non-conforming
+ * all-day chain does NOT hide it (PR #62 feedback); conformance still gates
+ * a successful delegate (`effectiveHeadOf` below refuses a non-conforming
+ * all-day). The registration gate is `isFallbackActive` content presence
+ * (`rootChain` / `timeSlots` / declared roles): a slot-row edit that flips
+ * that gate (e.g. removing the only slot while `rootChain` and roles are
+ * empty) intentionally churns registration — the content-presence contract
+ * (plan fallbacks-web-ux-alignment T2), not churn to design away; do NOT
+ * re-narrow the condition to ignore `timeSlots`. Conformance-only chain
+ * edits still never churn (conformance gates the delegate, not the row).
  *
  * Adapter behavior (P1/P3): `listModels` advertises exactly the one virtual
  * row; `stream()` is a THIN single-hop delegate to the effective chain head
@@ -34,7 +39,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { LlmAdapter, type GenerateOptions, type LlmImageRequestPricing, type LlmModelInfo, type LlmResolvedModelInfo, type LlmRuntime, type ResolvedRetryPolicy, type StreamChunk } from '@deepseek-ai/dsh-llm';
-import type { FallbacksConfig } from './config.ts';
+import { type FallbacksConfig } from './config.ts';
 /** Provider route of the virtual adapter (exact string, spec lock). */
 export declare const FALLBACKS_PROVIDER = "FallbacksChain";
 /**

package/icon.svg

@@ -0,0 +1,16 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="dsh-llm-fallbacks-icon-a" x1="14.9894" y1="9.0697" x2="14.9894" y2="21.3063" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#69B9FF"/>
+      <stop offset="1" stop-color="#324DE2"/>
+    </linearGradient>
+    <linearGradient id="dsh-llm-fallbacks-icon-b" x1="21.1075" y1="15.1877" x2="21.1075" y2="27.4243" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#45E7A4"/>
+      <stop offset="1" stop-color="#05909D"/>
+    </linearGradient>
+  </defs>
+  <rect x="8.87109" y="9.0697" width="12.2365" height="12.2365" rx="2" fill="url(#dsh-llm-fallbacks-icon-a)" fill-opacity="0.8"/>
+  <rect x="14.9893" y="15.1877" width="12.2365" height="12.2365" rx="2" fill="url(#dsh-llm-fallbacks-icon-b)" fill-opacity="0.8"/>
+  <path d="M13.3 13.3L19.4 19.4" stroke="#F9FAFB" stroke-opacity="0.95" stroke-width="1.7" stroke-linecap="round"/>
+  <path d="M19.4 15.9V19.4H15.9" stroke="#F9FAFB" stroke-opacity="0.95" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Fallbacks",
+    "description": "Automatic provider/model fallback chains that keep agent steps running when LLM requests keep failing (auth, quota, rate limit)."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "故障降级",
+    "description": "模型请求持续失败（认证、配额、限流）时自动切换备用模型链，保持 agent 步骤继续运行。"
+  }
+}

package/package.json

@@ -5,10 +5,11 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "icon": "./icon.svg",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -18,12 +19,15 @@
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
     },
+    "./locale/*.json": "./locale/*.json",
     "./bundle/cordis.patch.yml": "./bundle/cordis.patch.yml",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "bundle",
+    "locale",
+    "icon.svg",
     "scripts"
   ],
   "dsh": {
@@ -71,7 +75,6 @@
     "@deepseek-ai/dsh-client-ui-chat": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-client-ui-conversation": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.2",

package/scripts/build-client.ts

@@ -74,7 +74,6 @@ export const CLIENT_EXTERNALS: readonly string[] = [
   '@deepseek-ai/cordis',
   '@deepseek-ai/dsh-client-store',
   '@deepseek-ai/dsh-client-ui-slots',
-  '@deepseek-ai/dsh-client-ui-primitives',
 ]
 
 /**