dsh-llm-fallbacks 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-external
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# dsh-llm-fallbacks
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
+![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
+![dsh](https://img.shields.io/badge/dsh-DeepSeek%20Harness%20compatible-4B32C3.svg)
+
+Automatic provider/model fallback chains for dsh (DeepSeek Harness): when an agent's LLM requests keep failing — retries exhausted, auth errors, quota exceeded, rate limiting (429) — the plugin switches provider/model along the fallback chain for the current role, and the current step/turn continues on the target model: tasks are not interrupted by model problems.
+
+Install with a single command (pnpm ≥ 10 needs one build-allow step — see [Install](#install)):
+
+```sh
+dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # pin a commit with #<sha>
+```
+
+## Features
+
+- **Automatic fallback for root and subagents**: any agent switches down the chain to the next available provider/model on model failure — no manual model switching.
+- **Two-block config**: block 1 `rootChain` — the root agent's single fallback chain (empty = root does not fall back); block 2 declared roles — `roles.list` role entities (id/label/description/chain/fallback) that `roles.rules` reference by id (or the built-in `inherit`); no rule match → `inherit` → `rootChain`.
+- **Entry syntax**: chain entries are `provider/model` (exact switch) or `provider/*` (keep the failed model id, switch provider only) — the old chain-key namespace (provider/model keys, role-name keys) is gone.
+- **Cooldown and revert**: models that were switched away from / failed are not re-selected during the cooldown period; `revertPolicy: cooldown-expiry` automatically returns to the primary model when the cooldown expires, while `never` does not return within the session.
+- **Visible behavior**: every switch appends a persisted session event `fallbacks/switch` (from/to/role/reason), alongside info-level logs (candidate attempt order and skip reasons) and the read-only status block on the Settings → 插件配置 → Fallbacks card — no silent model switching.
+- **Safety valves**: switching stops and the original error semantics are kept once `maxSwitchesPerStep` is exceeded for a step, preventing chain loops from amplifying latency; `mode: 'always'` providers additionally have a retry cap (`alwaysModeRetryCap`).
+- **No-config no-op**: `enabled` defaults to off (`false`); with no `rootChain`/role chains, unmatched trigger codes, or unresolved roles the plugin is a complete no-op — identical to not being installed, and no events are emitted.
+
+## Install
+
+### One-line git install
+
+```sh
+dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # pin a commit with #<sha>
+```
+
+A git install fetches **sources, not built artifacts**, so the bundle builds itself on install (`prepare` self-build). The plugin is **mount-only**: it never modifies the dsh source tree, and no patch / postinstall step exists — dsh upgrades never require re-patching. pnpm ≥ 10 blocks a git dependency's `prepare` by default: the first `add` fails with `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, and pnpm prints the exact package key. Allow the build in the profile's `pnpm-workspace.yaml` (`onlyBuiltDependencies: [dsh-llm-fallbacks]`, or run `dsh plugin --profile web approve-builds`), then re-run the `add`. Treat that allowance as permission to execute the package's code on your machine at install time, and pin a commit (`github:btspoony/dsh-llm-fallbacks#<sha>`) so a later push cannot silently change what runs. The full URL form works equivalently: `dsh plugin --profile web add https://github.com/btspoony/dsh-llm-fallbacks.git`.
+
+### Local directory install (recommended for development / verification)
+
+```sh
+# 1) Build in the plugin repo (the prepare self-build runs the pnpm toolchain: tsdown + tsc, no bun)
+pnpm install
+# 2) Add to the target profile (example: web)
+dsh plugin --profile web add .
+```
+
+> **Development prerequisite**: type-checking and tests resolve the real
+> `@deepseek-ai/*` packages (peer deps, host-provided at runtime) from the npm
+> registry at `0.1.0-rc.6` — `autoInstallPeers` + the registry auth token in
+> the user-level `~/.npmrc` (pnpm 11 no longer expands `${NPM_TOKEN}` from a
+> project `.npmrc`), no local link farm.
+
+> Both methods, uninstall, and `--dump-config` verification — including the bundle-layer ordering requirements — are covered in [docs/install.md](docs/install.md).
+
+## Quick start
+
+### Minimal configuration
+
+Add a `fallbacks:` section to the dsh settings document (default `$DSH_HOME/settings.yaml`):
+
+```yaml
+fallbacks:
+  enabled: true            # feature switch; defaults to false — set explicitly to enable
+  rootChain:               # block 1: root agent's chain; tried in order after the primary model fails
+    - anthropic/claude-3-5-sonnet
+    - openai/*
+  roles:                   # block 2: declare roles first, then let rules reference them
+    list:
+      - id: reviewer       # role entity: unique id (/^[a-z0-9-]{1,32}$/); "inherit" is reserved
+        label: Reviewer
+        description: Code-review subagents
+        chain:
+          - openai/gpt-4o-mini
+        fallback: inherit-root   # default: role chain, then append rootChain
+    rules:
+      - origin: subagent   # all subagents → reviewer role (own chain + inherited root)
+        role: reviewer
+```
+
+Roles are declared entities: `roles.list` holds role cards (id/label/description + optional chain/fallback), and `roles.rules` match origin/provider/model in order to a declared role id or the built-in `inherit` (first match wins) — **no rule match → `inherit` → `rootChain`**. A declared role is only ever hit when a rule references it. The legacy chain-key namespace and role-default field are gone (migration table: [docs/configuration.md](docs/configuration.md)).
+
+Save and restart the web session for the changes to take effect. The feature switch `fallbacks.enabled` **defaults to off (`false`)** — the plugin only engages once it is turned on; `triggerCodes` defaults to `AUTH` / `QUOTA` / `RATE_LIMIT`; and with **no `rootChain`/role chains configured the behavior is identical to not having the plugin installed**. More examples (role entities, fallback strategies, rules referencing `inherit`) → [docs/configuration.md](docs/configuration.md).
+
+> **Upgrade note (behavior change)**: an existing `fallbacks:` section **without an explicit `enabled` key** now resolves to `false` after upgrading — add `enabled: true` to keep the plugin active.
+
+## `/fallbacks` command (in-session diagnostics)
+
+Type `/fallbacks` in any session to inspect this session's fallback state — no need to open the settings page:
+
+- **Session origin** (`root` / `subagent`) and the **resolved role** (the `role` of the first matching `roles.rules` entry, otherwise the built-in `inherit`);
+- the **resolved chain** for that role (the role's own chain entries, annotated `（inherit-root）` when `rootChain` is appended — `rootChain` entries render in full only when the role has no own chain; `fallback: none` with an empty own chain, or no chain at all, → `not configured`);
+- the **recent switches** (`fallbacks/switch` events, newest first, up to 5): from/to provider/model, role, reason;
+- the **cooldown status**: which `provider/model` keys are currently suppressed and until when.
+
+The command is **read-only** — it never mutates fallback state (no cooldown reset, no pending-switch writes). It registers through a conditional `commands` child, so it appears only when the host composes the slash-command registry — with no registry the command is silently unavailable (no top-level inject pollution). Output is zh by default (the host carries no per-session locale signal); the en dictionary lives in the same copy table.
+
+## Mount-only (no dsh modification)
+
+The plugin installs as a **pure mount** — it never modifies the dsh source tree:
+
+- **Install = bundle insert + client inject + own gateway**: `bundle/cordis.patch.yml`
+  inserts the plugin row over the profile bundle stack, `dsh.client.inject` mounts
+  the Fallbacks card on the Settings → 插件配置 page, and settings read/write/reset
+  go through the plugin's own gateway channel (`/api/fallbacks/get|set|reset`).
+- **No patches, no auto-apply step**: there are no dsh-body patch files and no install
+  lifecycle step that applies one. A one-line git install works as-is.
+- **dsh upgrades never require re-patching**: a dsh upgrade that resets the source
+  tree changes nothing for this plugin — it keeps working without any re-apply step.
+- **Stale leftover patches are harmless**: the plugin never depends on a patch
+  export (role resolution is rules-only; the model-selection marker coordination
+  was removed), so a previously patched dsh tree can be left as-is or manually
+  reverted — neither is required.
+
+## Documentation
+
+| Doc | Content |
+|---|---|
+| [docs/install.md](docs/install.md) | profile install / git install / uninstall / `--dump-config` verification |
+| [docs/configuration.md](docs/configuration.md) | full `fallbacks` namespace reference, selector syntax, example YAML, plugin-config card usage, behavior notes |
+| [docs/verification.md](docs/verification.md) | verification records (test matrix, bundle layer order, runtime contracts, QA gate script) |
+
+## License
+
+Released under the **MIT** License — see [LICENSE](LICENSE). The LICENSE file is authoritative for copyright and license terms.

package/README.zh-CN.md

@@ -0,0 +1,119 @@
+# dsh-llm-fallbacks
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
+![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
+![dsh](https://img.shields.io/badge/dsh-DeepSeek%20Harness%20compatible-4B32C3.svg)
+
+dsh（DeepSeek Harness）的自动模型降级插件：当 root agent 或 subagent 的模型请求持续失败（重试耗尽、权限、配额超限、限流 429）时，按角色/模型 fallback 链自动切换 provider/model，当前 step/turn 在目标模型上继续完成——任务不因模型问题中断。
+
+一句话安装（pnpm ≥ 10 需一次构建放行，见 [安装](#安装)）：
+
+```sh
+dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # 钉 commit：加 #<sha>
+```
+
+## 能力一览
+
+- **root / subagent 自动降级**：任意 agent 在模型故障下按链切换到下一个可用 provider/model，无需手动换模型。
+- **两块制配置**：块 1 `rootChain`——root 主代理唯一降级链（空 = root 不降级）；块 2 声明式角色——`roles.list` 角色实体（id/label/description/chain/fallback）供 `roles.rules` 按 id 引用（或内置 `inherit`）；未命中规则 → `inherit` → `rootChain`。
+- **条目语法**：链条目为 `provider/model`（精确切换）或 `provider/*`（保留失败模型 id 仅换 provider）——旧链键命名空间（provider/model 键、角色名键）已删除。
+- **冷却与回主**：被切离/失败的模型在冷却期内不再入选；`revertPolicy: cooldown-expiry` 冷却到期后自动回主模型，`never` 会话内不回。
+- **行为可见**：每次切换追加持久化会话事件 `fallbacks/switch`（from/to/role/reason），配合 info 级日志（候选尝试顺序与跳过原因）与设置 → 插件配置 → Fallbacks 卡片上的只读状态块，无静默换模型。
+- **安全阀**：每 step 的 `maxSwitchesPerStep` 超限后停止切换、保持原错误语义，防止链循环放大延迟；`mode: 'always'` 的 provider 另有重试上限（`alwaysModeRetryCap`）。
+- **无配置回归（no-op）**：`enabled` 默认关闭（`false`），无 `rootChain`/角色链 / 未命中触发码 / 角色解析失败时插件完全 no-op——行为与未安装时一致，不产生任何事件。
+
+## 安装
+
+### 一句话 git 安装
+
+```sh
+dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # 钉 commit：加 #<sha>
+```
+
+git 安装拉取的是**源码而非构建产物**，安装时由包自行构建（`prepare` 自构建）。插件为**纯挂载**：对 dsh 源码树零修改，无任何补丁 / postinstall 步骤——dsh 升级无需重打。pnpm ≥ 10 默认不执行 git 依赖的 `prepare`：第一次 `add` 会失败并打印 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，同时给出精确的包 key。在该 profile 的 `pnpm-workspace.yaml` 中放行构建（`onlyBuiltDependencies: [dsh-llm-fallbacks]`，或运行 `dsh plugin --profile web approve-builds`），然后重跑 `add`。请把这次放行当作它本来的样子：允许该包代码在安装期于你的机器上执行——建议钉 commit（`github:btspoony/dsh-llm-fallbacks#<sha>`），防止后续 push 悄悄改变实际运行的代码。完整 URL 形式等价：`dsh plugin --profile web add https://github.com/btspoony/dsh-llm-fallbacks.git`。
+
+### 本地目录安装（开发/验证推荐）
+
+```sh
+# 1) 在插件仓库目录构建（prepare 自构建走 pnpm 工具链：tsdown + tsc，无 bun）
+pnpm install
+# 2) 装入目标 profile（示例为 web）
+dsh plugin --profile web add .
+```
+
+> **开发前置**：类型检查与测试解析的是**真实** `@deepseek-ai/*` 包（peer 依赖，运行时由宿主提供），
+> 来源为 npm registry 的 `0.1.0-rc.6`（`autoInstallPeers` + 用户级 `~/.npmrc` 的 registry
+> 认证令牌——pnpm 11 起项目级 `.npmrc` 不再展开 `${NPM_TOKEN}`，无本地 link farm）。
+
+> 两种安装方式、卸载与 `--dump-config` 验证（含 bundle 层顺序要求）详见 [docs/install.md](docs/install.md)。
+
+## 快速开始
+
+### 最小配置
+
+在 dsh 的设置文档（默认 `$DSH_HOME/settings.yaml`）中添加 `fallbacks:` 分节：
+
+```yaml
+fallbacks:
+  enabled: true          # 功能级开关；默认关闭（false），需显式打开后生效
+  rootChain:             # 块 1：root 主代理降级链；主模型失败后按顺序尝试
+    - anthropic/claude-3-5-sonnet
+    - openai/*
+  roles:                 # 块 2：先声明角色，再让规则引用
+    list:
+      - id: reviewer     # 角色实体：id 唯一（/^[a-z0-9-]{1,32}$/）；inherit 为保留字
+        label: 审查者
+        description: 代码审查子代理
+        chain:
+          - openai/gpt-4o-mini
+        fallback: inherit-root   # 默认：角色链后追加 rootChain
+    rules:
+      - origin: subagent # 所有 subagent → reviewer 角色（自身链 + 继承 root）
+        role: reviewer
+```
+
+角色是声明式实体：`roles.list` 存放角色卡（id/label/description + 可选 chain/fallback），`roles.rules` 按 origin/provider/model 顺序匹配到**已声明角色 id 或内置 `inherit`**（首个命中即停）——**未命中 → `inherit` → `rootChain`**。只声明不写规则的角色永不命中。旧链键命名空间与角色兜底字段已删除（迁移表见 [docs/configuration.md](docs/configuration.md)）。
+
+保存并重启 web 会话后生效。功能级开关 `fallbacks.enabled` **默认关闭（`false`）**——打开开关后插件才会介入；`triggerCodes` 默认覆盖 `AUTH` / `QUOTA` / `RATE_LIMIT`；**未配置任何 `rootChain`/角色链时行为与未安装插件完全一致**。更多示例（角色实体、fallback 策略、引用 `inherit` 的规则）见 [docs/configuration.md](docs/configuration.md)。
+
+> **升级提示（行为变更）**：已有 `fallbacks:` 配置若**未显式写 `enabled` 键**，升级后解析为 `false`——请补上 `enabled: true` 以保持插件继续生效。
+
+## `/fallbacks` 命令（会话内诊断）
+
+在任意会话中键入 `/fallbacks` 即可查看当前会话的 fallback 状态，无需打开设置页：
+
+- **会话来源**（`root` / `subagent`）与**解析角色**（首个命中规则的 `role`，未命中则内置 `inherit`）；
+- 该角色的**解析链**（角色自身链 + 继承的 `rootChain`，`fallback: none` 时仅角色链）——无链时显示「未配置」；
+- **最近切换**（`fallbacks/switch` 事件，最新在前，至多 5 条）：from/to provider/model、role、reason；
+- **冷却状态**：哪些 `provider/model` 处于冷却、冷却至何时（`revertPolicy: 'never'` 显示「会话内不再回主」）。
+
+命令**只读**——绝不修改 fallback 状态（不重置冷却、不写待应用切换）。它经条件 `commands` 子注入注册，仅在宿主组合了斜杠命令注册表时出现；无注册表时命令静默不可用（无顶层 inject 污染）。输出默认中文（宿主侧无会话级 locale 信号）；英文词典在同一副本表中。
+
+## 纯挂载（零 dsh 修改）
+
+插件以**纯挂载**方式安装，**从不修改 dsh 源码树**：
+
+- **安装 = bundle 行插入 + client inject + 自有 gateway**：`bundle/cordis.patch.yml`
+  把插件行插入 profile bundle 栈，`dsh.client.inject` 在设置 → 插件配置页挂载
+  Fallbacks 卡片，设置读写/重置
+  走插件自有 gateway 通道（`/api/fallbacks/get|set|reset`）。
+- **无补丁、无自动打补丁**：没有 dsh 本体 patch 文件，也没有任何安装期 apply 步骤；
+  一句话 git 安装即可用。
+- **dsh 升级永不需重打**：dsh 升级重置源码树对本插件无影响——无需任何重打步骤。
+- **残留旧补丁无害**：插件不依赖任何补丁导出（角色解析 rules-only；model-selection
+  标记协调已移除）——已打过旧补丁的 dsh 树可原样保留或手动回滚，均非必需。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [docs/install.md](docs/install.md) | profile 安装 / git 安装 / 卸载 / `--dump-config` 验证 |
+| [docs/configuration.md](docs/configuration.md) | `fallbacks` 命名空间全字段、selector 语法、示例 YAML、插件配置卡使用、行为说明 |
+| [docs/verification.md](docs/verification.md) | 验证记录（测试矩阵、bundle 层序、运行契约、QA gate 剧本） |
+
+## 许可
+
+本项目以 **MIT** 许可证发布，全文见 [LICENSE](LICENSE)。版权与许可条款以 LICENSE 文件为准。

package/bundle/cordis.patch.yml

@@ -0,0 +1,19 @@
+# The dsh-llm-fallbacks profile-bundle patch: ONE insert of the plugin row over
+# the profile's bundle stack (`dsh.profile.bundles` order — dsh-base first,
+# this bundle after the llm-retry bundle; later layers win per row).
+#
+# Insert position matters for the host waterfall: the profile must list the
+# llm-retry bundle BEFORE dsh-llm-fallbacks, so this plugin's
+# `agent/request-error` listener composes after llm-retry and only intervenes
+# once retry policy is exhausted (normal mode) or delegates downstream first
+# (always mode). See plan Risk table.
+#
+# A patch replaces the targeted row's whole `config` rather than merging into
+# it, so a user-level override must restate every field it keeps. The row
+# ships only neutral defaults; profile-layer (`cordis.patch.yml`) overrides
+# win.
+
+- insert:
+    - id: llm-fallbacks
+      name: 'dsh-llm-fallbacks'
+      config: {}

package/dist/chains.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Fallback chain resolution (spec §7.2; plan fallbacks-role-runtime Task 1).
+ *
+ * `resolveChain` returns the ordered candidate list for a failing
+ * (provider, model). Candidates come from the role's own chain plus
+ * `rootChain` appended as an inherit-root fallback — **append-not-replace**:
+ * `[...(roleDef.chain ?? []), ...(roleDef.fallback === 'none' ? [] :
+ * rootChain)]` (role entries first, rootChain entries after). The reserved
+ * built-in `inherit` id (INHERIT_ROLE_ID) resolves to `rootChain` silently —
+ * it is the legal no-rule-match role, not a typo'd id. A truly undeclared
+ * role id (defense) resolves to `rootChain` alone + one warn. Chain-key
+ * specificity lookup (`exact` / `provider/*` / role / `default` keys) is
+ * deleted — the two-block config model has no chain keys.
+ *
+ * Wildcard entries (`provider/*`) are resolved against the failing model —
+ * keep the model id, swap only the provider; the "target provider has no
+ * such model id" skip is judged by {@link resolveCandidate} (via
+ * `modelExists`) or by the caller's filter.
+ *
+ * The concatenation itself lives in ONE helper — {@link buildRoleEntries}
+ * (qc1 S-3 SSOT) — shared by {@link resolveChainViews} and
+ * {@link hasWildcardEntry}, so the wildcard probe is exact (qc2 F-003:
+ * `fallback: 'none'` excludes `rootChain`) and can never diverge from the
+ * resolution. Defensive warns (unknown role / undeclared rule target) go
+ * through an injected `warn` callback — the wiring passes the cordis
+ * `logger.warn` (qc2 F-002 / qc3 S-3), with `console.warn` as the
+ * direct-call default.
+ *
+ * Cooldown / failed-set / same-as-current filtering is caller-side;
+ * {@link createCandidateFilter} provides the ready-made predicate.
+ *
+ * @module dsh-llm-fallbacks/chains
+ */
+import { type FallbacksRole } from './config.ts';
+import type { CooldownStore, StepFailureSet } from './cooldown.ts';
+import { type Selector } from './selectors.ts';
+/** The model that just failed — the anchor for chain resolution. */
+export interface FailingModel {
+    provider: string;
+    model: string;
+}
+/**
+ * Resolve one chain entry against the failing model.
+ *
+ * - `provider/model` → that exact selector (not subject to `modelExists` —
+ *   the user explicitly listed it).
+ * - `provider/*` → keeps the failing model id, swaps only the provider; when
+ *   `modelExists` is given and the target provider has no such model id →
+ *   `null` (skip).
+ * - Malformed entries → `null`: they "do not take effect"; the strict throw
+ *   path is {@link parseSelector}, used by the Task 3 config-warning path.
+ */
+export declare function resolveCandidate(entry: string, failing: FailingModel, modelExists?: (provider: string, model: string) => boolean): Selector | null;
+/**
+ * Single-pass chain resolution for the decision path (T1 review Important
+ * #2). Walks the role's concatenated entries ONCE and returns the unfiltered
+ * view — `all` (every resolvable candidate, no filter and no existence
+ * probe: the caller's early-exit / annotation view) — plus the parallel
+ * `wildcard` provenance (`wildcard[i]` = candidate `all[i]` came from a
+ * `provider/*` entry). The caller builds the existence probe from `all` and
+ * then derives the surviving view with {@link selectCandidates}, so the
+ * decision path never resolves the chain twice (and an unknown role warns
+ * at most once per decision).
+ *
+ * The reserved built-in `inherit` id (INHERIT_ROLE_ID) is legal — it
+ * resolves to `rootChain` silently (the no-rule-match role, not a typo'd
+ * id). Only a truly undeclared id (∉ declared ids ∪ {'inherit'}) warns once
+ * (defensive — never crashes) through `warn` (defaults to `console.warn`
+ * for direct-call compatibility; the decision path injects the cordis
+ * `logger.warn` — qc2 F-002 / qc3 S-3). Malformed entries never become
+ * candidates.
+ */
+export declare function resolveChainViews(roles: readonly FallbacksRole[], rootChain: readonly string[], role: string, provider: string, model: string, warn?: (message: string) => void): {
+    all: Selector[];
+    wildcard: boolean[];
+};
+/**
+ * Derive the surviving candidates from a {@link resolveChainViews} pass:
+ * the caller filter plus the wildcard-only existence probe. `modelExists`
+ * applies to `provider/*`-origin candidates only (scoped by the parallel
+ * `wildcard` provenance — T2 review Important #1: exact entries are never
+ * existence-filtered), mirroring how {@link resolveCandidate} receives it.
+ * Order and duplicates are preserved.
+ */
+export declare function selectCandidates(all: readonly Selector[], wildcard: readonly boolean[], filter?: (candidate: Selector) => boolean, modelExists?: (provider: string, model: string) => boolean): Selector[];
+/**
+ * Ordered fallback candidates for the failing (provider, model).
+ *
+ * Candidates are the role's concatenated entries (spec §7.2, see
+ * {@link buildRoleEntries} — the single concatenation SSOT): the declared
+ * role's own `chain` followed by `rootChain` unless `fallback: 'none'`
+ * (append-not-replace — role entries first, rootChain as the tail). The
+ * reserved built-in `inherit` id resolves to `rootChain` silently; a truly
+ * undeclared/unknown `role` id resolves to `rootChain` alone and warns once
+ * (defensive — never crashes). `filter` optionally drops candidates — the
+ * caller owns cooldown/failed-set/same-model filtering (see
+ * {@link createCandidateFilter}). The `modelExists` existence probe is NOT
+ * applied per entry here: {@link resolveChainViews} returns the parallel
+ * `wildcard` provenance, and {@link selectCandidates} applies `modelExists`
+ * to `provider/*`-origin candidates ONLY (qc1 S-2 — exact entries are never
+ * existence-filtered, spec §2 clause 2 / T2 review Important #1
+ * decision-path contract). `warn` forwards to {@link resolveChainViews}
+ * (defaults to `console.warn`; the decision path injects `logger.warn`).
+ *
+ * Single-pass: delegates to {@link resolveChainViews} + {@link selectCandidates}
+ * (one concatenated-entry walk, warn at most once per call).
+ */
+export declare function resolveChain(roles: readonly FallbacksRole[], rootChain: readonly string[], role: string, provider: string, model: string, filter?: (candidate: Selector) => boolean, modelExists?: (provider: string, model: string) => boolean, warn?: (message: string) => void): Selector[];
+/**
+ * Whether any entry of the role's concatenated candidates is a wildcard
+ * (`provider/*`). F-002: {@link resolveChain} resolves wildcard entries to
+ * concrete models, so the wildcard provenance is invisible on the resolved
+ * candidate list — the decision path consults the same concatenation
+ * `resolveChain` walks to decide whether the catalog existence probe is
+ * needed at all.
+ *
+ * The probe walks {@link buildRoleEntries} — the SAME concatenation
+ * {@link resolveChainViews} resolves (qc1 S-3 single SSOT) — so it is
+ * exact, never an over-approximation (qc2 F-003 / qc3 S-1): for
+ * `fallback: 'none'` roles `rootChain` is excluded, and a wildcard that can
+ * never reach the candidate list never builds a catalog probe. No
+ * false-negative is possible: any wildcard the resolution could reach is on
+ * this concatenation by construction. Malformed entries never become
+ * candidates and are skipped.
+ */
+export declare function hasWildcardEntry(roles: readonly FallbacksRole[], rootChain: readonly string[], role: string): boolean;
+/** Inputs for {@link createCandidateFilter}. */
+export interface CandidateFilterOptions {
+    /** The currently active (failing) model — skipped as "same as current". */
+    current: FailingModel;
+    /** Cooldown store: suppressed candidates are skipped (keyed `provider/model`). */
+    cooldown: Pick<CooldownStore, 'isSuppressed'>;
+    /** Failed-set for the current step: already-failed candidates are skipped. */
+    failed: Pick<StepFailureSet, 'has'>;
+    /** Optional existence probe: candidates the target provider lacks are skipped. */
+    modelExists?: (provider: string, model: string) => boolean;
+}
+/**
+ * The caller-side candidate filter (Task 3): a candidate is usable when it
+ * differs from the current model, is not cooldown-suppressed, has not failed
+ * in this step, and (when `modelExists` is given) exists on its provider.
+ */
+export declare function createCandidateFilter(options: CandidateFilterOptions): (candidate: Selector) => boolean;
+/** Why one considered candidate was excluded from the selection (spec §2 行为可见性). */
+export type CandidateSkipReason = 'same-as-current' | 'cooldown' | 'step-failed' | 'missing-id';
+/** One entry of the ordered, per-candidate annotation (T3 review Minor 1). */
+export interface AnnotatedCandidate {
+    candidate: Selector;
+    /** Why this candidate was excluded; `undefined` = it survived every exclusion. */
+    skip?: CandidateSkipReason;
+}
+/**
+ * Annotate the ordered "considered" candidate list with each candidate's skip
+ * reason (spec §2 行为可见性: the switch log must show the attempt order and
+ * why each candidate was skipped). The selection-relevant view is the
+ * `surviving` list the decision path resolved with filter + existence probe:
+ * a candidate absent from it failed one of the exclusions, and the concrete
+ * reason is derived from the same checks {@link createCandidateFilter}
+ * applies, in the same precedence. `missing-id` therefore only ever labels
+ * entries the existence probe dropped — exact entries are never
+ * existence-probed (T2 contract), so they stay in `surviving` and are
+ * reported as usable, never as missing-id.
+ *
+ * This is the diagnostic counterpart of {@link createCandidateFilter} — pure,
+ * order-preserving, and duplicate-preserving.
+ */
+export declare function annotateCandidates(candidates: readonly Selector[], surviving: readonly Selector[], options: Pick<CandidateFilterOptions, 'current' | 'cooldown' | 'failed'>): AnnotatedCandidate[];

package/dist/client/ConversationFallbackSwitch.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Conversation-level fallback-switch visibility (plan fallbacks-aux-seams,
+ * task 2, D1+D2 seam).
+ *
+ * Every `fallbacks/switch` session event becomes its own chat-transcript
+ * node (`fallbacks-switch`), rendered as a compact system-style line at the
+ * switch's event seq — the user sees the recovery happen in place
+ * (provider/model A → B, role · reason), instead of the event existing only
+ * in the raw `sessions.history` event feed (it is NOT a SurfaceEventType,
+ * so the `unknown-surface` fallback never picked it up and the transcript
+ * showed nothing).
+ *
+ * Contract notes (dsh-private, verified 2026-08-12):
+ * - D1 registry: `ConversationEventRegistry.register(definition)` — service
+ *   on the client Context (`runtime/src/client/index.ts:171,189-192`);
+ *   external registration precedent `ui-workflow-run/src/client/index.ts:18-28`.
+ *   The engine feeds EVERY session event to each definition's `match`
+ *   (`runtime/src/client/sessions/conversation-assembler.ts:370-382`) —
+ *   non-surface plugin events included — and the client session appends live
+ *   events into the engine (`sessions/session.ts:673` `conversation.append`).
+ * - D2 seat: `conversation.chat.node` is a keyed seat dispatched by
+ *   `ChatConversationViewNode.kind` (`ui-conversation contract/slots.ts:56-63`;
+ *   `chat/ChatNodeSeat.tsx:48-51`), externally registrable as
+ *   `{ name, key, locale }` (precedents: ui-tool `tool-call`, ui-goal
+ *   `command-input`, ui-workflow-run `workflow-run`).
+ * - Purity: this file only type-imports `@deepseek-ai/dsh-client-runtime/client`
+ *   and `@deepseek-ai/dsh-client-ui-conversation/client` (both erased at
+ *   build); the renderer self-draws on `--dsw-alias-*` tokens. Render-only:
+ *   the Definition is a pure view contribution — no message construction,
+ *   no model-context injection (C4 excluded by scope).
+ */
+import type { ReactNode } from 'react';
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ConversationNodeDefinition } from '@deepseek-ai/dsh-client-runtime/client';
+import type { FallbackSwitchReason } from '../events.ts';
+/** Final chat payload of one decided fallback switch (snapshot of the event). */
+export interface FallbacksSwitchChatData {
+    readonly seq: number;
+    readonly time: number;
+    readonly turn: number;
+    readonly step: number;
+    /** The model the request was using when the switch was decided. */
+    readonly from: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    /** The chain candidate the switch moves to. */
+    readonly to: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    /** The fallback-chain role the decision resolved for the agent. */
+    readonly role: string;
+    readonly reason: FallbackSwitchReason;
+}
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+    interface ChatNodeDataMap {
+        /** One decided fallback provider/model switch, rendered at its event seq. */
+        'fallbacks-switch': FallbacksSwitchChatData;
+    }
+}
+/**
+ * One switch event → one chat node. Each `fallbacks/switch` event is its own
+ * Context (id = event seq — the durable unique key), so every match is a
+ * `start`; `update` is a passthrough (no aggregation — D3's per-Turn
+ * counting is a separate, unselected seam).
+ */
+export declare const fallbackSwitchDefinition: ConversationNodeDefinition<FallbacksSwitchChatData>;
+/**
+ * Props delivered by the keyed chat-node seat: runtime share + the `fallbacks` locale seat.
+ */
+export type ConversationFallbackSwitchProps = PropsRuntime<'conversation.chat.node', 'fallbacks-switch'> & PropsLocale<'fallbacks'>;
+/**
+ * Render one fallback switch as a compact system-style transcript line.
+ *
+ * Geometry follows the upstream chat system rows (the compaction boundary
+ * notice: dim title + separator + ellipsized summary — `chat/MessageItem
+ * .module.css:38-122`); every color resolves through a `--dsw-alias-*`
+ * token. A reason outside the current union renders raw (forward-compatible
+ * durable log, same rule as the card/general row summaries). A malformed or
+ * partial payload (version skew) degrades to the title-only line instead of
+ * throwing during interpolation — the transcript slot stays visible with a
+ * truthful "a switch happened" notice and no summary details.
+ * @param props - composed keyed seat props.
+ * @returns the switch line element tree.
+ */
+export declare function ConversationFallbackSwitch({ node, t }: ConversationFallbackSwitchProps): ReactNode;

package/dist/client/FallbacksCard.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Fallbacks settings card — the `fallbacks` plugin card on the web settings
+ * "插件配置" page (spec §4). Registered into the `settings.plugin.item` slot
+ * (id `fallbacks`, order 30, alongside the upstream bash/agent-loop/web-search
+ * cards and the advisor card); owner props are empty and all data flows
+ * through {@link FallbacksSettingsController}.
+ *
+ * The card chrome replicates the upstream `PluginCard` contract (self-drawn:
+ * the upstream client value face exports no reusable card): a collapsible
+ * `<li>` whose header is a button stacking the plugin name over its
+ * description, with a dirty "unsaved" pill and a rotating chevron
+ * (`IconChevronDownOutline14` from ui-primitives — a CLIENT_EXTERNALS value
+ * import), `aria-expanded`/`aria-label` like the upstream header; a divider
+ * under the header; then the form content; then a footer with
+ * Discard / Reset / Save carrying the upstream disabled semantics — save =
+ * `!dirty || saving || !writable`, discard = `!dirty || saving` (KD-U1).
+ * Disclosure is card-local state: which card a user has open is a reading
+ * gesture, and staged edits outlive collapsing — the pill rides the header
+ * (upstream rationale).
+ *
+ * The form body is the two-block editing surface (spec §8): the `enabled`
+ * checkbox row, the 6 top-level scalar fields (trigger codes / revert
+ * policy / three numeric fields), the `rootChain` block (block 1 — the
+ * root agent's single chain, no key input), and the roles block (block 2 —
+ * declared role entity cards from `roles.list` plus the rule rows from
+ * `roles.rules`, whose role field is a dropdown bound to the declared ids
+ * + the built-in `inherit`, same-page live). Saving runs `validateDraft`
+ * first — id format/reserved word/duplicates, undeclared rule role
+ * references, and illegal selectors block the write with a validation
+ * banner + inline red borders (never touching the store error path); a
+ * non-empty `state.legacyKeys` renders the migration banner at the top of
+ * the card body. The row editors keep their filled editorCard surface
+ * inside the card, with `--dsw-alias-*` tokens throughout. The reset-
+ * to-defaults confirmation stays a `Modal` (the delete-confirm pattern of
+ * the Models page) — no `window.confirm`.
+ *
+ * The page-only chrome is gone (720px column wrapper, title/intro banners,
+ * page-bottom status block): the AC-7 read-only status (derived effective
+ * model + recent-switch summary) is folded into the card body above the
+ * footer, and the plugin-config section owns the column width.
+ *
+ * Degraded/error/loading states keep the same card chrome (KD-U3): the
+ * header always renders title+description+chevron, and the body carries the
+ * config-channel notice or the load error. A card that cannot reach the
+ * `fallbacks/get` gateway channel (`ready && !present`) keeps the USABLE
+ * skeleton — the form stays writable and saves are attempted (KD-G5) — with
+ * the `unavailable` notice ALWAYS visible (derived open — the header cannot
+ * collapse it away), while a healthy card is collapsed until the user
+ * expands it (AC-1, the documented divergence from upstream whose
+ * unavailable card renders nothing). A hard load failure (`status ===
+ * 'error'`) also forces the body open with an error notice and — when the
+ * form is inert (`!writable`, i.e. the load never landed) — a Retry button;
+ * a save failure keeps the editable form so the Save action itself is the
+ * retry (the single `state.error` surface covers both, unlike the advisor's
+ * separate apply-failure hints).
+ *
+ * The degraded derivation is latched in the card (the store stays untouched):
+ * `present` only ever changes inside the store's `accept()`, so the settled
+ * `ready` read is authoritative, and a card-local latch carries that value
+ * through refresh/save windows (`loading`/`saving`) so the notice body can
+ * never collapse mid-refresh (the advisor's latched `degraded` field,
+ * implemented without a store change); on a first mount the latch is false,
+ * so the healthy card starts (and stays) collapsed through its first load.
+ */
+import type { ReactNode } from 'react';
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react';
+import { FallbacksSettingsController, type FallbacksSettingsState } from './fallbacks-store.ts';
+/** Injected dependencies of {@link FallbacksCard} (slot `inject`). */
+export interface FallbacksCardInjected {
+    /** The card store (loaded on mount, refreshed on pushed invalidations). */
+    controller: FallbacksSettingsController;
+    /** uSES subscription hook bound to the store (inject face — advisor pattern). */
+    useSnapshot: SnapshotSelectorHook<FallbacksSettingsState>;
+}
+/** Props delivered by the slot outlet: runtime share + locale seat + inject face. */
+export type FallbacksCardProps = PropsRuntime<'settings.plugin.item'> & PropsLocale<'fallbacks'> & FallbacksCardInjected;
+/**
+ * Render the Fallbacks settings card inside the plugin-config section,
+ * replicating the upstream PluginCard chrome (KD-U1). The body carries the
+ * existing form content unchanged plus the folded-in status block and the
+ * footer actions (Discard / Reset / Save).
+ * @param props - slot-delivered injected dependencies and the synthesized t seat.
+ * @returns the card.
+ */
+export declare function FallbacksCard({ controller, useSnapshot, t }: FallbacksCardProps): ReactNode;