BruceLanLan/dsh-tier-router

dsh-tier-router — Tiered model routing for DeepSeek Harness

handles planning / architecture / review**, while a cheap tier (deepseek-v4-flash by default) handles day-to-day implementation, with per-tier fallback chains and task-intensity reasoning effort. Inspired by Claude Code's /advisor (consult a stronger model for hard decisions) and opusplan (strong model in plan mode, cheap model for execution), implemented on DeepSeek Harness through its official seams, with an escalation gate, failure auto-escalation, and subagent tiering on top.

English · 中文

How it works

flowchart LR
    subgraph main["Main session (header-driven)"]
      U["User message"] --> IN["agent/inbox/inserted"]
      IN -->|"auto mode"| HW["write session request/header"]
      PM["plan/mode flip"] --> HW
      HW --> API["api-proxy selection layer"]
      API --> STEP["each step's model = header tier"]
    end
    subgraph child["Subagents (agent/request swap)"]
      W["tier_worker dispatch"] -->|"agentOptions injection"| C["subagent"]
      C --> AR["agent/request waterfall"]
      AR -->|"swap provider/model per tier"| STEP2["subagent steps"]
    end
    G["tools/pre-execute guard"] -.->|"cheap tier + high-impact pattern"| DENY["deny + escalation hint"]
    E["agent/error failures"] -.->|"within window"| ESC["temporary strong tier (TTL)"]

sequenceDiagram
    participant U as User
    participant S as Session (main agent)
    participant A as Strong v4-pro
    participant C as Cheap v4-flash
    U->>S: /tier plan (enter plan mode)
    S->>S: write header -> strong
    S->>A: planning / architecture / design
    U->>S: approve plan, leave plan mode
    S->>S: write header -> cheap
    S->>C: routine implementation
    S->>A: tier_advisor (hard decisions) / tier_review (final review)
    Note over S,C: high-impact actions (rm -rf / credential files) are denied by the guard until the strong tier is selected

Features

• Automatic tiered routing (auto mode, opusplan-style): steps run on the strong tier while plan mode is active and on the cheap tier during execution. Before a loop builds its first or resumed request, the router synchronizes the agent's model options and durable request/header; later route changes preserve unrelated request settings such as maxTokens.
• Per-session scoping: /tier strong|cheap|auto|delegated|off affects only the current session; other sessions in the process keep their own tier (global default auto). In delegated mode the main session stays on its model-picker selection while only subagents use tier routing; /tier auto remains an explicit per-session override. Sessions that should not be managed can opt out with a single /tier off.
• On-demand advice (advisor-style): the /advisor <question> command and the tier_advisor tool hand one decision question plus gathered evidence to the strong tier and return advice / evidence / risks / acceptance criteria; implementation stays on the current tier.
• Review phase: the tier_review tool and /tier review <focus> ask the strong tier to review a change set and return an APPROVE / NEEDS-CHANGES / BLOCKED verdict with issues ranked by severity.
• Failure auto-escalation: repeated step errors within a window (default 2 errors / 60s) temporarily escalate the session to the strong tier (default 180s), expiring via TTL; sessions in off mode never escalate.
• Configurable tiers (durable): /tier set <strong|cheap> <provider> <model> [effort] or the tier_configure tool can point either tier at any registered provider/model, configure the strong tier to follow the session selection, and set ordered fallback chains. Configuration persists in the tier-router settings namespace and survives restarts (pass sessionOnly: true for a transient change).
• WebUI settings: the Tier routing settings page configures providers, models, reasoning effort, follow-session behavior, fallback chains, routing mode, and the subagent policy. It uses the live model catalog when available and preserves custom routes when it is not.
• Per-tier fallback chains: if the primary model is unavailable (unknown model, quota, rate limit, missing/invalid credential, server/transport error, or any status >= 500 failure), the router changes route at the supported request-error boundary and retries the same step on the next entry. Remove every entry to disable fallback. Fallback state is per agent and tier, returns to the primary after the fallback TTL (default 5 min, state.fallbackTtlMs), and never crosses from a cheap chain to a strong chain during a plan transition.
• Task-intensity reasoning effort: the strong tier follows your session model selection by default (/tier set strong follow-session); the cheap tier starts at medium and raises itself to high/max (bounded by the model's declared efforts, e.g. deepseek models declare off/high/max) on cheap-tier retry errors, high-impact guard denials, or the tier_escalate_effort tool; /tier effort <medium|high|max> sets it manually. tier_configure and /tier set validate every effort against llm.resolveModelInfo when metadata is available.