dsh-llm-fallbacks 0.2.1 → 0.2.2

package/README.md

@@ -24,6 +24,20 @@ dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui terminal profile
 
 Same plugin, either front end — the only difference is the `--profile` flag. Pin a version with `@<version>`. A registry install fetches the **built package** (`dist/`), nothing builds on the target machine. Registry / git / local-directory variants, uninstall, and `--dump-config` verification → [docs/install.md](docs/install.md).
 
+### Repair existing sessions (versions before 0.2.2)
+
+Versions before 0.2.2 wrote durable `fallbacks/switch` session events that newer dsh releases refuse to load (issue #52 — the apply()-time event-type registration is ineffective because plugin and host resolve different module instances). If existing sessions fail to open after an upgrade, clone this repository and repair the logs (stop dsh first):
+
+```sh
+git clone https://github.com/omdsh-dev/dsh-llm-fallbacks.git
+cd dsh-llm-fallbacks
+pnpm install
+pnpm repair:fallbacks-switch-logs -- --dry-run            # preview which sessions would change
+pnpm repair:fallbacks-switch-logs -- --apply --backup     # mark legacy events ignorable
+```
+
+The script scans `~/.dsh/sessions` by default (override with `--root <dir>`), marks legacy `fallbacks/switch` events `ignorable: true` so the host read path accepts the session again, and keeps a `<file>.bak` per repaired log. `--apply` requires `--backup` and must run with dsh stopped. From 0.2.2 on, the plugin stops writing durable switch events, so no new sessions need repair.
+
 ### Minimal configuration
 
 Add a `fallbacks:` section to the dsh settings document (default `$DSH_HOME/settings.yaml`):
@@ -52,14 +66,15 @@ No rule match → the built-in `inherit` → `rootChain`. `enabled` defaults to
 
 ### Verify
 
-Save and restart the session, then type `/fallbacks` — the read-only in-session diagnostics (origin, resolved role, chain, recent `fallbacks/switch` events, cooldown status). Sessions containing `fallbacks/switch` events load after a restart because the plugin registers the event type at startup (rc.6 runtime registration; an upstream registration surface is pending) — without the plugin installed, such sessions refuse to load again until the upstream surface lands (see the Features note below). In a dsh-tui profile, `/fallbacks config` additionally reads back the composed configuration (the TUI has no settings page — config is file-only; see [docs/configuration.md](docs/configuration.md)).
+Save and restart the session, then type `/fallbacks` — the read-only in-session diagnostics (origin, resolved role, chain, recent `fallbacks/switch` events, cooldown status). The plugin no longer writes durable `fallbacks/switch` session events (issue #52 — the apply()-time registration was proven ineffective), so new switches show up in the info logs, not in the recent-switch surfaces; sessions written by older plugin versions that contain `fallbacks/switch` events are repaired with `scripts/repair-fallbacks-switch-logs.ts`, which marks legacy events ignorable so those sessions load again (see the Features note below). In a dsh-tui profile, `/fallbacks config` additionally reads back the composed configuration (the TUI has no settings page — config is file-only; see [docs/configuration.md](docs/configuration.md)).
 
 ## 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**: `rootChain` for the root agent; declared role entities (`roles.list`) referenced by `roles.rules` (or the built-in `inherit`).
+- **Dispatch-time role resolution**: on a subagent's first request its role is resolved in three stages — explicit (`agentPreset` matches a declared role id) → deterministic rules (unchanged) → LLM auto-match from the declared role taxonomy (`fallbacks.roleAutoMatch`, default `true`). The resolved role's chain-head model is injected into the first request and recorded via an explicit `role → model` log line (no durable `fallbacks/switch` event is written — issue #52 stop-write); set `roleAutoMatch: false` to disable the LLM auto-match stage (the explicit `agentPreset` stage still applies — with no explicit role this reproduces the previous rules-only behavior). The settings card always renders an **Enable role auto-match** switch (default `true`) to toggle it — the schema default applies even to legacy configs that never declared the key.
 - **Cooldown and revert**: failed / switched-away models are not re-selected during cooldown; `revertPolicy: cooldown-expiry` returns to the primary model automatically.
-- **Visible behavior**: every switch appends a persisted `fallbacks/switch` session event (from/to/role/reason) with info-level logs — no silent model switching. The event type is registered with the harness at plugin startup (rc.6 runtime registration; an upstream registration surface is pending), so persisted events stay loadable across restarts while the plugin is installed.
+- **Visible behavior**: every switch is recorded in an info-level log line (from/to/role/reason) — no silent model switching. The plugin deliberately writes **no** durable `fallbacks/switch` session events (issue #52: the apply()-time event-type registration was proven ineffective, and a session containing the event refused to load after a dsh restart). Sessions written by older plugin versions that contain such events are repaired by `scripts/repair-fallbacks-switch-logs.ts`, which marks legacy events ignorable so affected sessions load again.
 - **Safety valves**: `maxSwitchesPerStep` caps switches per step and `alwaysModeRetryCap` caps always-mode retries — chain loops cannot amplify latency.
 - **No-config no-op**: `enabled` defaults to off; with no chains configured the plugin behaves exactly like not being installed.
 

package/README.zh-CN.md

@@ -24,6 +24,20 @@ dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui 终端 profile
 
 同一个插件、两个前端——区别只在 `--profile` 参数。钉版本：加 `@<version>`。registry 安装拉取的是**已构建产物**（`dist/`），目标机无需构建。registry / git / 本地目录变体、卸载与 `--dump-config` 验证 → [docs/install.md](docs/install.md)。
 
+### 修复旧会话（0.2.2 之前的版本）
+
+0.2.2 之前的版本会把 `fallbacks/switch` 事件写入会话持久化日志，而新版 dsh 拒绝加载这类会话（issue #52——apply() 时的注册因插件与宿主解析到不同模块实例而无效）。如果升级后已有会话打不开，clone 本仓库并修复日志（先停 dsh）：
+
+```sh
+git clone https://github.com/omdsh-dev/dsh-llm-fallbacks.git
+cd dsh-llm-fallbacks
+pnpm install
+pnpm repair:fallbacks-switch-logs -- --dry-run            # 预览哪些会话会被改动
+pnpm repair:fallbacks-switch-logs -- --apply --backup     # 给旧事件打 ignorable 标记
+```
+
+脚本默认扫描 `~/.dsh/sessions`（可用 `--root <dir>` 覆盖），把遗留 `fallbacks/switch` 事件标记为 `ignorable: true`，宿主读路径即可重新接受该会话；每个被修复的日志保留一份 `<file>.bak`。`--apply` 必须搭配 `--backup`，且须在 dsh 停止时运行。从 0.2.2 起插件不再写 durable 切换事件，新会话无需修复。
+
 ### 最小配置
 
 在 dsh 的设置文档（默认 `$DSH_HOME/settings.yaml`）中添加 `fallbacks:` 分节：
@@ -52,14 +66,15 @@ fallbacks:
 
 ### 验证
 
-保存并重启会话后，键入 `/fallbacks`——只读的会话内诊断（来源、解析角色、链、最近的 `fallbacks/switch` 事件、冷却状态）。含 `fallbacks/switch` 事件的会话能在重启后正常加载，是因为插件在启动时注册了该事件类型（rc.6 运行时注册；上游注册面待落地）——卸载插件后，含此类事件的会话将再次拒绝加载，直到上游注册面落地（见下方「能力一览」说明）。在 dsh-tui profile 中，`/fallbacks config` 额外回读组合配置（TUI 无设置页——配置仅文件，见 [docs/configuration.md](docs/configuration.md)）。
+保存并重启会话后，键入 `/fallbacks`——只读的会话内诊断（来源、解析角色、链、最近的 `fallbacks/switch` 事件、冷却状态）。插件**不再写入** durable `fallbacks/switch` 会话事件（issue #52——apply() 时的注册被证伪无效），因此新切换只出现在 info 日志中，不再出现在 recent-switch 展示面；由旧版插件写入、含 `fallbacks/switch` 事件的会话，可用 `scripts/repair-fallbacks-switch-logs.ts` 修复——脚本把旧事件标记为 ignorable，会话即可重新加载（见下方「能力一览」说明）。在 dsh-tui profile 中，`/fallbacks config` 额外回读组合配置（TUI 无设置页——配置仅文件，见 [docs/configuration.md](docs/configuration.md)）。
 
 ## 能力一览
 
 - **root / subagent 自动降级**：任意 agent 在模型故障下按链切换到下一个可用 provider/model，无需手动换模型。
 - **两块制配置**：`rootChain` 管 root 代理；声明式角色实体（`roles.list`）供 `roles.rules` 引用（或内置 `inherit`）。
+- **派发时角色解析**：在 subagent 的首次请求上，其角色按三个阶段解析——显式（`agentPreset` 匹配已声明角色 id）→ 确定性规则（不变）→ LLM 自动匹配（从已声明角色体系中选择，`fallbacks.roleAutoMatch` 默认 `true`）。解析出的角色的链头模型注入首次请求，并以显式 `role → model` 日志行记录（不写 durable `fallbacks/switch` 事件——issue #52 停写）；设 `roleAutoMatch: false` 仅关闭 LLM 自动匹配阶段（显式 `agentPreset` 阶段仍生效——无显式角色时即复现原有仅规则行为）。设置卡总是渲染「启用角色自动匹配」开关（默认 `true`）以切换之——即使是从未声明过该键的旧配置，schema 默认值同样生效。
 - **冷却与回主**：被切离/失败的模型在冷却期内不再入选；`revertPolicy: cooldown-expiry` 冷却到期后自动回主模型。
-- **行为可见**：每次切换追加持久化会话事件 `fallbacks/switch`（from/to/role/reason），配合 info 级日志——无静默换模型。插件在启动时把该事件类型注册进宿主（rc.6 运行时注册；上游注册面待落地），持久化事件在插件安装期间可跨重启加载。
+- **行为可见**：每次切换以 info 级日志行（from/to/role/reason）记录——无静默换模型。插件**刻意不写** durable `fallbacks/switch` 会话事件（issue #52——apply() 时的事件类型注册被证伪无效，含该事件的会话在 dsh 重启后拒绝加载）。由旧版插件写入、含此类事件的会话由 `scripts/repair-fallbacks-switch-logs.ts` 修复——旧事件被标记 ignorable 后，受影响会话可重新加载。
 - **安全阀**：`maxSwitchesPerStep` 限制每 step 切换次数、`alwaysModeRetryCap` 限制 always 模式重试——链循环不会放大延迟。
 - **无配置回归（no-op）**：`enabled` 默认关闭；未配置任何链时行为与未安装插件完全一致。
 

package/dist/automatch.d.ts

@@ -0,0 +1,98 @@
+/**
+ * LLM auto-match role selection (plan fallbacks-role-automatch Task 3).
+ *
+ * This module is the bounded LLM caller behind the resolver's stage-3
+ * auto-match hook (`resolveRoleAtDispatch`, `role-resolution.ts`). When the
+ * explicit and rules stages resolve to `'inherit'` and `roleAutoMatch` is
+ * enabled, `pickRoleByLlm` asks the model to pick the best-fit declared role
+ * from the taxonomy and returns its declared RAW id, or `null` (= `'inherit'`).
+ *
+ * Contract (architect-locked, plan Global Constraints · Auto-match bounded):
+ * - ONE bounded completion per decision: small `maxTokens`
+ *   ({@link AUTOMATCH_MAX_TOKENS}) and a timeout
+ *   ({@link AUTOMATCH_TIMEOUT_MS}, default 5s) that abandons the stream via
+ *   the streaming contract's cancellation (`options.signal`) — no dangling
+ *   iterator, no unhandled rejection.
+ * - Never throws. Every failure mode — throw, timeout, `none`, no valid id,
+ *   garbage answer, malformed inputs — resolves to `null`, so the "never
+ *   throws out of `agent/request`" invariant holds end-to-end (the resolver
+ *   deliberately does NOT catch the hook).
+ * - Fast paths that avoid an LLM call entirely: empty taxonomy, absent
+ *   `ctx.llm` service, and no concrete provider/model route for the judgment
+ *   call. The plugin does NOT listen on `llm/stream`, so this call cannot
+ *   recurse into the plugin.
+ *
+ * Judgment-call route choice (documented): the concrete provider/model for the
+ * judgment call is taken from the roles' DECLARED context first — the first
+ * exact (non-wildcard) `provider/model` selector across the declared chains,
+ * in declaration order (the operator's own taxonomy is the most stable route
+ * set). If no declared chain yields an exact selector, the agent's current
+ * `options.provider`/`options.model` is used when both halves are present;
+ * otherwise the call is skipped (`null`).
+ *
+ * Pure helpers exported for unit testing:
+ * - {@link buildAutomatchPrompt} — the taxonomy prompt (declared ids +
+ *   personas + agent origin/agentPreset; instructs exactly-one-declared-id-or-
+ *   `none`).
+ * - {@link parseAutomatchAnswer} — parses a declared id out of the model
+ *   answer with surrounding whitespace/punctuation/quote/backtick tolerance;
+ *   `none` (case-insensitive) and unknown ids → `null`. `roleIds` is the
+ *   trimmed-id → declared-raw-id map, the same canonicalization the resolver
+ *   uses.
+ *
+ * @module dsh-llm-fallbacks/automatch
+ */
+import { type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { FallbacksRole, FallbacksRoles } from './config.ts';
+import type { AgentLike } from './roles.ts';
+/** Default auto-match completion timeout in ms — abandons the stream. */
+export declare const AUTOMATCH_TIMEOUT_MS = 5000;
+/** Output bound (tokens) for the judgment call: one id or the literal `none`. */
+export declare const AUTOMATCH_MAX_TOKENS = 32;
+/**
+ * Minimal `llm` service surface {@link pickRoleByLlm} reads. The real
+ * `LlmRuntime.stream(options)` matches structurally; this face keeps the
+ * module free of the full cordis Context merge.
+ */
+export interface AutomatchLlm {
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/**
+ * Minimal context surface: `ctx.get('llm')` (optional service — absent →
+ * `null` fast-path). The broad `get(name: string)` face is satisfied by the
+ * real cordis `Context` (`ReflectService.get` overloads return `any`/the
+ * merged service), so the Task-4 wiring can pass `ctx` directly.
+ */
+export interface AutomatchContext {
+    get(name: string): AutomatchLlm | undefined;
+}
+/** Options for {@link pickRoleByLlm}. */
+export interface PickRoleByLlmOptions {
+    /** Completion timeout in ms; defaults to {@link AUTOMATCH_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Warning sink — the decision path injects the plugin logger. */
+    warn: (message: string) => void;
+}
+/**
+ * Build the auto-match taxonomy prompt: every declared role's trimmed id and
+ * persona, the agent's origin (and non-empty `agentPreset` when present), and
+ * the exactly-one-declared-id-or-`none` instruction. Pure — no I/O.
+ */
+export declare function buildAutomatchPrompt(roles: readonly FallbacksRole[], agent: AgentLike): string;
+/**
+ * Parse the model's answer into a declared role id.
+ *
+ * The answer is expected to BE an id (possibly wrapped in whitespace, quotes,
+ * backticks, or trailing punctuation); surrounding characters outside the id
+ * grammar (`[a-zA-Z0-9-]`) are stripped, then the remaining string must match
+ * a declared id exactly (case-insensitive) via `roleIds` (trimmed id →
+ * declared RAW id, the resolver's canonicalization). `none` (case-insensitive)
+ * and any unknown/malformed answer → `null`.
+ */
+export declare function parseAutomatchAnswer(answer: string, roleIds: ReadonlyMap<string, string>): string | null;
+/**
+ * Bounded LLM role-selection call (see module header). Resolves the declared
+ * RAW id of the best-fit role, or `null` on any fast path or failure. NEVER
+ * throws.
+ */
+export declare function pickRoleByLlm(ctx: AutomatchContext, roles: FallbacksRoles, agent: AgentLike, opts: PickRoleByLlmOptions): Promise<string | null>;

package/dist/client/FallbacksCard.d.ts

@@ -1,8 +1,9 @@
 /**
  * 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
+ * "插件配置" page (spec §4). Registered into the `settings.plugin.item` keyed
+ * slot (key `fallbacks`, the settings namespace the card edits, alongside
+ * the upstream bash/agent-loop/web-search cards and the advisor card, in
+ * registration order); owner props are empty and all data flows
  * through {@link FallbacksSettingsController}.
  *
  * The card chrome replicates the upstream `PluginCard` contract (self-drawn:

package/dist/client/fallbacks-store.d.ts

@@ -180,12 +180,18 @@ export declare function classifyModel(provider: string, raw: string, catalog: Ca
  */
 export declare function extractRecentSwitches(entries: readonly HistoryEntry[], limit?: number): FallbacksSwitchSnapshot[];
 /**
- * Derive the status block's "current effective model" (spec §2.5 D-6): ①
- * disabled / empty rootChain → unavailable; ② a recent switch exists → the
- * latest one's `to`; ③ otherwise → the config's primary target. A **display
- * value** — never a live route probe (the section appends the non-probing
- * note inline right after the derived value, available case only; the
- * unavailable 空态 renders its own copy without the note).
+ * Derive the "current effective model" (spec §2.5 D-6): ① disabled / empty
+ * rootChain → unavailable; ② a recent switch exists → the latest one's `to`;
+ * ③ otherwise → the config's primary target. A **display value** — never a
+ * live route probe.
+ *
+ * INTENTIONAL D-6 CONTRACT RETENTION: after the AC-2 trim (plan
+ * fallbacks-settings-visibility Task 2) the settings card's status block no
+ * longer consumes this derivation, and no other production code imports it —
+ * it is retained (NOT dead code to delete) as the spec §2.5 D-6 derived-value
+ * surface, pinned by `tests/fallbacks-store.spec.ts` (D-6 display-value
+ * contract). Keep both exports until the spec derivation is removed or gains
+ * a real consumer.
  */
 export declare function deriveEffectiveModel(config: FallbacksConfig, switches: readonly FallbacksSwitchSnapshot[]): EffectiveModelView;
 /** One chain selector row: provider + model (or wildcard). */

package/dist/client/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * dsh-llm-fallbacks client half: registers the Fallbacks card into the
- * plugin-config page's `settings.plugin.item` slot (the official "插件配置"
- * settings page — id `fallbacks`, order 30, alongside the upstream bash /
- * agent-loop / web-search cards and the advisor card).
+ * plugin-config page's `settings.plugin.item` keyed slot (the official
+ * "插件配置" settings page — key `fallbacks`, the settings namespace the card
+ * edits, appearing after the upstream bash / agent-loop / web-search cards
+ * and the advisor card in registration order).
  *
  * Wiring (mirrors dsh-advisor):
  * - Registers the `fallbacks` locale dictionaries (zh/en).
@@ -11,10 +12,11 @@
  *   `/api/fallbacks/get|set|reset`), while `settings.describe` (writable +
  *   namespace directory) and the provider/model catalog stay on
  *   `connection.api` (see `fallbacks-store.ts`).
- * - Registers the `settings.plugin.item` card `id: 'fallbacks'` (order 30)
- *   with a business-only inject face ({@link FallbacksSettingsController} +
- *   the snapshot-selector hook); the old Settings-nav section registration
- *   is removed — deleting the section registration deletes the nav entry.
+ * - Registers the `settings.plugin.item` card `key: 'fallbacks'` (the rc.7
+ *   keyed slot — no `id`/`order`) with a business-only inject face
+ *   ({@link FallbacksSettingsController} + the snapshot-selector hook); the
+ *   old Settings-nav section registration is removed — deleting the section
+ *   registration deletes the nav entry.
  * - Refreshes the store on pushed invalidations — the forwarded remote
  *   events `settings/document-updated` (ns-filtered to the fallbacks
  *   namespace; refetches the descriptor + recent-switch summary) and