dsh-route-keeper
Verifieddsh-route-keeper Β· v0.1.1 Β· MIT
Sticky model-route keeper for DeepSeek Harness: root/child sticky primary, bounded plugin-owned retry, cross-route fallback with same-activation auto-continue, host allowlist/role/egress enforcement, and optional bounded TypeSafe (Jev) advisory classifica
Install
dsh plugin add dsh-route-keeper Confirm the layer applied with dsh --profile default --dump-config β see the install guide.
Source
Creators
Readme
dsh-route-keeper
Sticky model-route keeper for DeepSeek Harness.
dsh-route-keeper holds a root agent on a subscription primary model
(e.g. openai-codex/gpt-6.1-sol), falls back to allowed routes on quota/failure,
and transparently auto-continues the same agent (root and authorized local
child) on the fallback without concatenating partial output. It owns same-route
retries for managed routes (prepended, so native dsh-llm-retry is never
doubled), enforces host allowlist / role / data-flow boundaries, and optionally
asks TypeSafe System One (Jev) for an advisory next-step route.
Why you might need it
A subscription model is the fastest route until the provider answers
HTTP 429 / the server is overloaded; retry shortly in the middle of a
working turn. Without a keeper the agent either stops with an error or the
turn is lost while the model is switched by hand.
Route-keeper exists for that one failure mode:
- the root agent stays on the chosen primary while it works (sticky residence),
- transient failures are retried a bounded number of times on the same route,
- a real failure moves the same activation to an allowed fallback route, and the turn continues from the same place β partial text, reasoning, and tool calls are never stitched together across routes,
- every hop is bounded and logged, and an empty allowlist denies the move rather than guessing a target.
It is not a model selector, a router UI, or a credential manager: it changes
nothing until enabled: true and an explicit allowHosts list are configured.
Installation
Tested against DeepSeek Harness 0.2.2-rc.1 on Node >=24.
The package is published on npm as dsh-route-keeper and listed in the DSH
plugin market index at
https://raw.githubusercontent.com/yario-ai/dsh-route-keeper/main/market/index.json
β add that URL under Settings β plugin indices, then install it from Discover.
Each release is additionally attached to a GitHub release together with
SHA256SUMS.
Desktop profiles are managed exclusively through the DSH bundle/plugin manager in the GUI: add the reviewed
dsh-route-keeper-<version>.tgzbundle there, then enable it in the profile settings.The isolated headless CLI is for tests only (never the desktop profile):
dsh plugin --profile headless add ./dsh-route-keeper-<version>.tgzThe plugin is disabled by default and does nothing until you set
enabled: trueand explicitly list the roleallowHosts.
Scope and profiles
When enabled in a profile, the plugin covers every root and local child agent in
all workspaces of that profile. Other profiles are unaffected. It never manages
credentials, other apps, or cross-process dispatch; credentials are resolved only
through the host credential reference (Jev's dedicated TYPESAFE_API_KEY).
Features
- Sticky primary with minimum residence; bounded cooldown and single-flight half-open return on real requests (no synthetic paid probes).
- Plugin-owned same-route retries:
maxRetries=Nβ 1+N attempts;Retry-Afteris honored (never shortened);maxFailureElapsedMsis a decision-boundary budget, not a hard deadline. - Same-activation auto-continue on zero-output failures only (reasoning IS output); partial text/reasoning/tool-call blocks never concatenate.
- Durable parent allowlist enforcement for child fallback (fail-closed).
- Optional bounded Jev advisory to the fixed
https://api.typesafe.ai/v1/systemoneendpoint using the dedicated hostTYPESAFE_API_KEYreference (no key copy, no login flows).
Configuration
- name: 'dsh-route-keeper'
config:
enabled: false
roles:
root:
primary: { provider: 'openai-codex', model: 'gpt-6.1-sol' }
fallbacks: [{ provider: 'opencode-go', model: 'deepseek-v4.1-flash' }]
allowHosts: ['openai-codex', 'opencode-go', 'deepseek']
noDowngradeRoutes: []
child:
primary: null
fallbacks: [{ provider: 'opencode-go', model: 'deepseek-v4.1-flash' }]
allowHosts: ['opencode-go', 'deepseek']
noDowngradeRoutes: []
sticky: { minResidenceMs: 3600000 }
cooldown: { baseMs: 60000, maxMs: 21600000 }
budget:
maxRetries: 2
backoffInitialMs: 500
backoffMaxMs: 10000
jitterRatio: 0.1
maxFailureElapsedMs: 0
consecutiveFailures: 0
failureWindowMs: 0
failureThreshold: 2
condition: any
maxFallbackHops: 1
maxAutoContinue: 3
jev:
enabled: false
model: jev-latest
maxPromptChars: 6000
maxRequestBytes: 32768
maxResponseBytes: 65536
timeoutMs: 25000
pin: null
enabled: false is a passive no-op. An empty allowHosts denies every
automatic target select (fail-closed): route-keeper never treats an empty list
as "allow all" β operators must list the exact providers they permit. Disable or
roll back without source changes by setting enabled: false or removing the
profile plugin row.
Provider notes
A provider that hangs silently is bounded only by its streamIdleTimeoutMs
(in dsh-llm-pi-ai providers settings, default 300000 ms). Route-keeper does
not promise a total-generation deadline; maxFailureElapsedMs measures elapsed
failure observation up to the fallback decision.
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md for the build, test, and review rules that keep routing behaviour safe. The project is MIT licensed and contributions are accepted under the same terms.
License
MIT. See LICENSE and NOTICE for retained dsh-shift-router attribution.