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.

  (pass sessionOnly: true for a transient change).

• High-impact escalation gate (deterministic guard): while the cheap tier executes, tools/pre-execute denies high-impact tool calls and requires switching to the strong tier first — no reliance on model self-discipline. Guard rules (pure logic in lib/pure.js, unit-tested):

  • every rm -rf spelling: combined flags (-rf), split flags (-r -f), case variants (-R), long flags (--recursive --force), runner prefixes (sudo rm -rf, busybox rm);
  • destructive commands: mkfs, dd if=, sudo, shutdown/reboot/halt, git push --force/-f, git clean -f*, find ... -delete / find ... -exec rm, python -c with shutil.rmtree / os.remove, curl|sh, wget|sh, chmod on .ssh, chown;
  • sensitive paths: .env (whitelist for .env.example/.template), credentials/secrets with common extensions, .ssh/, private keys such as id_rsa (case-insensitive), .pem, .key;
  • prose never false-positives: echo rm -rf, grep sudo do not trigger (command-position anchored).

• Subagent tiering: tier_worker dispatches bounded task packets to a fresh subagent on a chosen tier (agentOptions model injection), with outputSchema (structured results), toolFilter (restrict worker tools), maxDepth (delegation-depth cap), persona (per-child persona) and background (run via the jobs service). /tier subagent <inherit|cheap|strong> also routes ordinary subagent and subagent_fork children before their first request; an automatic escalation remains temporary and never permanently overrides an explicitly selected worker tier.

• Escalation rules injected into the system prompt: ambiguity unresolved, architecture / security / data integrity, two failed attempts, high-risk completion — the model is guided to call tier_advisor / tier_review at decision points.

Installation

Plane note. dsh-tier-router routing remains agent-plane: tools, slash commands, prompt sections, and routing listeners mount only when a session uses tiered. Its profile bundle now has one host-only responsibility: synchronize the packaged tiered preset into DSH's discovery root on startup.

# 1. Install into the profile. The host bundle synchronizes the packaged
#    tiered preset into ~/.dsh/.agent-presets on the next DSH startup.
dsh plugin --profile web add dsh-tier-router

# Local development uses the same installation path:
dsh plugin --profile web add .

# 2. Restart DSH, then choose "tiered" in the preset picker
#    for a new session (or make it the profile default through agent-presets).
#    No manual preset copy is required.

Uninstall: run dsh plugin --profile web remove dsh-tier-router; the next DSH startup no longer updates the tiered preset. Delete ~/.dsh/.agent-presets/tiered separately only when it is no longer wanted.

Installation is verified in practice: the package resolves from the profile store, the shipped agent-presets/tiered preset (a standard copy plus the - id: tier-routing / name: dsh-tier-router row) passes agentPresets.standingKeyFor mount validation, module loading is smoke-tested, and npm pack ships a clean tarball (lib + patch + preset + README/LICENSE).

Post-install acceptance checklist

1. Restart DSH: kill the process LISTENing on the web port first (lsof -tiTCP:<port> -sTCP:LISTEN | xargs kill -9), then start it again.
2. Open a NEW session — existing sessions keep the preset they were created with (this is by design).
3. Run /tier status — it must report:
   • config persisted: yes (tier-router settings namespace),
   • both tiers with their provider/model/effort,
   • a non-empty diag: line with live counters.
4. The tier_status, tier_route, tier_configure, tier_advisor, tier_review, and tier_worker tools must be callable in that session.
5. While executing on the cheap tier, a high-impact command (e.g. rm -rf, sudo …) must be denied by the guard with an escalation hint.
6. /tier set strong <provider> <model> [effort] must reply Saved to tier-router settings. and survive a restart.

If /tier status is unavailable, the row is missing from the session's preset (see Installation) or the session predates the preset switch.

Usage

Slash commands (typed in the composer; they affect only the current session)

/advisor <question>                          # one strong-tier consultation
/tier status                                # routing state, escalation state, diagnostics
/tier strong | cheap                        # force one tier for this session (optionally persist as session default)
/tier auto                                  # restore auto for this session (plan -> strong, execution -> cheap)
/tier delegated                             # keep the main session on the model picker; tier only subagents
/tier off                                   # disable routing for this session, restore its default model (other sessions unaffected)
/tier plan                                  # auto + enter plan mode, apply the strong header immediately
/tier models                                # list registered providers and their models
/tier set <strong|cheap> <provider> <model> [effort]
/tier subagent <inherit|cheap|strong>       # policy used to classify subagent execution (guard)
/tier review <focus>                        # strong-tier review

Sample output (/tier status):

Tiered model routing
  mode: global=auto, this session=auto (per-session via /tier strong|cheap|auto|delegated|off; escalate: 2 errors / 60s window -> 180s strong)
  strong: deepseek-official/deepseek-v4-pro (max)
  cheap:  deepseek-official/deepseek-v4-flash (medium)
  subagents: inherit
  diag: requestSteps=42 guardChecks=31 guardDenies=3 headerWrites=4 errorsSeen=0 escalations=0
  session default: deepseek-official/deepseek-v4-pro (max)
  providers: deepseek-official, opencode-go, minimax

Model tools (called by the model when needed)

Configuration

Runtime configuration (no restart needed):

/tier set strong deepseek-official deepseek-v4-pro max
/tier set cheap deepseek-official deepseek-v4-flash medium

/tier set and tier_configure persist the tier configuration in the tier-router settings namespace (survives restarts; pass sessionOnly: true for a transient change). tier_route strong|cheap|delegated scopes to the current session and does NOT persist by default; pass persist: true to also write the session default model (agent-default-model). Failure auto-escalation parameters (threshold / window / TTL) are currently built-in constants; configurable in a later version.

Tests

npm test        # node:test — 20 cases: guard positive/negative matrix, tier decision precedence, per-session overrides
npm run check   # syntax check for lib/index.js and lib/pure.js

Verified in live multi-round sessions (dynamic-plugin form):

FAQ

Q: Why was another session's model switched automatically? Early versions were process-global. Since v0.3.0 /tier commands scope to the current session only; other sessions default to auto independently. A session that should not be managed runs /tier off to opt out.

Q: The tier switch did not take effect immediately? Tier switches are written to the session header before the step is built, so they apply from the next step (one-step delay).

Q: How do I use subscription-channel models (OpenCode Go / MiniMax)? Run /tier models to confirm the provider is registered and its models are configured, then /tier set cheap opencode-go deepseek-v4-flash. pi-ai-style providers must declare baseURL / api / models in settings.yaml, otherwise every model id is rejected.

Q: A high-impact action was blocked. What now? The guard's message tells you: switch to the strong tier first (tier_route strong or /tier strong) and re-issue — the block exists precisely to keep the cheap tier from running destructive actions directly.

Q: /tier does not appear after installing the bundle? The package is an agent-plane plugin: it must be a row in the agent preset your session uses (see Installation). A host bundle row alone activates nothing — agent-plane services (tools, commands, systemPrompt) are only reachable from the preset scope, and this package ships no host insert by design. After adding the row, restart dsh web and verify with /tier status. (The dynamic-plugin form is a process-local temporary instance and disappears on restart.)

Known limitations

• Tier switches take effect from the next step (the header is written before the step builds).
• The subagent policy (/tier subagent) is process-wide and classifies child execution for the guard. A worker's tier is fixed at creation (tier_worker agentOptions); built-in subagent/subagent_fork children inherit the parent's model route.
• The full live "fail -> self-heal" sequence for failure auto-escalation has been verified at the event path and unit-logic level; trigger it live per the FAQ if desired.

License

MIT