dsh-llm-fallbacks

dsh-llm-fallbacks

English | Chinese

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.

Works in both dsh front ends: the web profile (Settings → Plugins → Fallbacks card) and the dsh-tui terminal profile (/fallbacks session diagnostics, /fallbacks config readback, and the /settings fallbacks section for editing).

Three core capabilities

Automatic model failover

Any agent — root or subagent — that keeps failing on a listed failure code walks its chain to the next available provider/model and keeps the step alive. No manual model switching, and nothing happens until you configure content.

• Triggers: triggerCodes (default AUTH / QUOTA / RATE_LIMIT) — any dsh failure code is accepted, including CONTEXT_WINDOW_EXCEEDED, which fails over to a larger-context candidate. Retryable failures (5xx, TRANSPORT, TIMEOUT, …) stay with llm-retry first.
• Recovery: a failed / switched-away model is held out of selection for cooldownMs, and revertPolicy: cooldown-expiry returns to the primary model on expiry. The opt-in recovery: half-open mode (YAML-only) makes that return evidence-driven instead of timer-based.
• Safety valves: maxSwitchesPerStep caps switches per step and alwaysModeRetryCap caps always-mode retries — chain loops cannot amplify latency.
• Visibility: every switch is recorded in an info-level log line (from/to/role/reason) — no silent model switching.

→ Automatic model failover · Context-window-aware fallback

Peak/valley time slots

Time slots rotate the effective root chain by wall-clock windows: each row carries its own fallback chain, and the first row whose window contains the current moment replaces the all-day chain for the next root request — the all-day chain stays the last resort when no row matches. Rotation is a routing seed, not a failure decision: it consumes no cooldown and leaves the failure walk (fallback switch) untouched.

Four frozen UTC+8 presets (windows are code constants; preset rows lock tz to Asia/Shanghai):

Preset	Window
liang-peak	Monday–Friday 09:00–12:00 and 14:00–18:00
liang-valley	every other UTC+8 time (complement of Liang Peak)
glm-peak	Monday–Friday 14:00–18:00
glm-valley	every other time (complement of GLM Peak)

GLM Peak and GLM Valley are offered in the card picker only when zai-coding-cn is configured. Custom rows take start / end (HH:mm, may wrap midnight) and an optional days list.

→ Time slots

Role-based subagents

A subagent's role is declared in its dispatch prompt — the Assignment header **Execute as**: <id> — and it is resolved against the role ids declared in roles.list. Only that declared header delivers the child's identity: the role's persona is installed on the child as a system-prompt section, the child's own session gets exactly one [role: <id>] notice row, and its session header shows a role badge.

Role routing is resolved separately, in four ordered stages, first hit winning — explicit agentPreset → dispatch-declared **Execute as**: <id> header → rules → LLM auto-match. If the child's dispatch prompt declares **Execute as**: <id>, that role's persona, [role: <id>] notice and badge are delivered regardless of which routing stage wins — an earlier explicit agentPreset can route the child as another role while the identity carriers stay the declared header's. A child with no declared dispatch header gets no persona, notice row or badge, even when rules or auto-match resolve a role for routing. Making the resolved role's chain head the child's model is plugin-originated and conditional: with the host subagent-model-selection policy enabled, an explicit authorized route is preserved (inject skipped) and an injected head must be inside the effective allowlist — an empty intersection injects nothing (host policy).

This covers an ordinary subagent dispatch and an Agent Team teammate (spawn_teammate) alike: both are children dispatched with the same header, which the model writes — the same dispatch seam, no mechanism-specific configuration.

→ Role-based subagents

Quick start

Install

dsh plugin --profile web add dsh-llm-fallbacks      # web profile (Settings → Fallbacks card)
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. The plugin ships localized metadata (title/description for the Plugins-page detail view, English + Simplified Chinese) and an icon — both declared in the package (locale/*.json + icon.svg) and picked up by the host automatically.

Configure

The plugin's settings live in a shared fallbacks: namespace, editable from three surfaces:

Surface	What it is	Notes
Web settings card	Settings → Plugins → Fallbacks	Full GUI editor for the fallbacks: namespace; writes the shared settings document
$DSH_HOME/settings.yaml	fallbacks: section in the dsh settings document	The shared source of truth — the same file the web card writes; readable and editable everywhere, including scripted setups
TUI /settings	fallbacks section in the dsh-tui settings screen	dsh-tui ≥ v0.8.5; native fields for simple keys, JSON text fields for complex structures

(/fallbacks and /fallbacks config are diagnostics — read-only views, not edit surfaces.) A minimal section:

fallbacks:
  rootChain:               # all-day chain: leading entries = fallback walk, last = Default model (official)
    - anthropic/claude-3-5-sonnet
    - deepseek-official/deepseek-flash
  timeSlots:               # optional: rotate the effective root chain by wall-clock windows
    - kind: preset
      preset: liang-peak
      chain:
        - anthropic/claude-3-5-sonnet
  roles:                   # optional: declare role entities, then reference them from rules
    list:
      - id: reviewer
        persona: Code-review subagents
        chain:
          - openai/gpt-4o-mini
        fallback: inherit-root
    rules:                 # subagent-only: rules never match root requests
      - role: reviewer

Three rules of thumb:

• There is no feature switch: the plugin intervenes exactly when content is configured — a non-empty rootChain, at least one timeSlots row, or one declared role. An empty section is a complete no-op, and the Plugins-page row toggle is the master switch.
• The all-day rootChain tail must be exactly one official model — deepseek-official/deepseek-flash or deepseek-official/deepseek-v4-pro (XOR); the leading entries are the fallback walk, walked first.
• Slots and roles are optional: the first time-slot row whose window matches replaces the all-day chain for the next root request; rules map subagents to declared roles and never match root requests.

Full reference (keys, entry syntax, selector rules, migration) → docs/configuration.md.

Upgrade note (breaking): the config-level enabled switch is removed — a stored section still carrying enabled: true/false loads cleanly (the key is ignored and stripped on the next save), but the switch no longer gates anything. If you relied on enabled: false to keep the plugin inert, empty the section (or disable the plugin row on the Plugins page) instead.

Verify

Save the config and restart the session, then type /fallbacks — the read-only in-session diagnostics (origin, resolved role, chain, recent fallback switches, cooldown status). In a dsh-tui profile, /fallbacks config reads back the composed configuration.

Feature highlights

• Automatic failover for root and subagents — any agent walks its chain on a listed failure code and the step continues. → details
• Context-window-aware fallback — CONTEXT_WINDOW_EXCEEDED fails over to a larger-context candidate; the switch is request-scoped (no cooldown). → details
• Peak/valley time slots — four frozen UTC+8 presets or custom windows rotate the effective root chain. → details
• Role-based subagents — a dispatch-declared role brings persona, notice row and badge to the child; its chain head is injected subject to host policy. → details
• FallbacksChain in the picker — select FallbacksChain / Auto to make the chain the root primary; any real model stays fallback-only. → details
• Host subagent model policy — the dsh 0.1.2 allowlist is a hard constraint on every plugin-originated subagent route. → details
• Five bundled preset roles — reviewer / scout / security-reviewer / sonic / task, declared on apply. → details
• dsh-tui surfaces — /fallbacks, /fallbacks config, and a /settings section with web-card parity. → details

Mount-only

The plugin installs as a pure mount: bundle insert + client inject + its own gateway channel (/api/fallbacks/get|set|reset) — no dsh patches, no postinstall step, and dsh upgrades never require re-patching. Stale leftover patches from an older patched install are harmless.

Documentation

Doc	Content
docs/install.md	profile install (web + dsh-tui) / registry / git / local variants / uninstall / --dump-config verification
docs/configuration.md	full fallbacks namespace reference, selector syntax, example YAML, plugin-config card usage, TUI readback, behavior notes, preset roles
docs/features.md	capability reference: failover, context-window fallback, time slots, role-based subagents, picker, host policy, preset roles, agent presets, dsh-tui
docs/repair.md	session-log repair: refusal classes, --apply publishing, flags, exit codes, lossy --drop-legacy-events
docs/consumer-api.md	developer consumption contract: library API + named llm-fallbacks service + role seeds, export inventory, lifecycle, typing
docs/release.md	release process: Trusted Publishing setup, Release prep SOP, fragment format, rollback
docs/verification.md	verification records (test matrix, bundle layer order, runtime contracts, QA gate script)
CHANGELOG.md	released changes, assembled from .changes/ fragments

License

Released under the MIT License — see LICENSE. The LICENSE file is authoritative for copyright and license terms.