Introduction¶

When running agents with third-party models, the most common problem is “this route isn’t working today.” Rate limits (429) require immediately switching to another route, while timeouts are intermittent—switching might fix them, but the handling differs. Manually changing configuration and restarting, or writing custom retry logic, becomes messy over time.

Below is an introduction to dsh-model-rotation: a DSH plugin maintained by Chrono-rigger. The idea is to arrange a set of models into a chain, attempting them in a defined order. It handles specific failure types like rate limits, timeouts, and missing adapters differently, finally falling back to a DSH platform model. It belongs to the Model Inference category and currently has 0 stars on the community directory.

What is it¶

One-sentence positioning: Rewriting routing on the DeepSeek Harness agent/request waterfall event to implement “sequential failure transfer + timeout retest + platform fallback.”

It solves the problem of replacing a single model choice with a logical model chain, so manual intervention isn’t needed during upstream fluctuations, and the entire chain doesn’t fail just because one model is glitching temporarily.

The difference from hand-written retry logic is that failure classifications here are agreed-upon (rate limits switch immediately, timeouts only switch after accumulating a threshold, quota exhaustion switches immediately, missing adapters/auth failures skip directly), and after the chain is exhausted, there is a round of retest and a sticky platform fallback.

Core Capabilities¶

• Sequential Failure Transfer: Member order is the attempt order, which can be freely arranged.
• Rate Limits (429) switch immediately; timeouts are counted per model and only switch when the timeout limit set for the chain is reached.
• Retest Round: In the first round, only the models that timed out get a new timeout budget to be tested again.
• DSH Platform Fallback: When the entire chain fails, it falls back to your specified platform model (e.g., deepseek-account/deepseek-flash), and it is sticky, meaning it won’t jump back just because a third-party route recovers.
• Non-intrusive to other choices: Saved combinations appear as models under the “Model Auto Switch” provider in the model selector. Requests are completely unchanged when selecting other options.
• Currently unavailable members are marked as “currently unavailable” and skipped during the tour, rather than causing the request to fail.

Installation & Activation¶

Install from npm:

dsh plugin --profile <your-profile> add dsh-model-rotation

Or install directly from the repository:

dsh plugin --profile <your-profile> add github:Chrono-rigger/dsh-model-rotation

Restart DSH after installation.

Prerequisites: DSH needs to provide agent/request and agent/request-error waterfall events (0.2.x and above).

Creating a Combination¶

1. Open Settings → Model Auto Switch (or enter the plugin’s own page under Plugins).
2. Create a combination, fill in the name, and add members. Search by model ID or name. Use ↑/↓ to adjust the order; the order is the failure transfer order.
3. Optional: Specify a “DSH Fallback Model” to use when the chain is exhausted.
4. Save the combination, then select this chain by name in the model selector.

The combination card displays the members of each saved combination, the timeout limits for each chain, and whether it is currently available.

Configuration Items per Chain¶

State Machine¶

round1   Traverse members in order
           Rate limit / Quota exhaustion → Mark dead, continue to next
           Timeout            → Count +1, continue to next if limit reached
           No adapter / Auth   → Mark dead, continue to next
              ↓ All members dead or exhausted
retest   Only timed-out models from the first round get a new timeout budget and are tested again
              ↓ Exhausted
fallback DSH Platform Model (specified or auto-discovered) — Sticky

Failures not handled by the plugin (SERVER, TRANSPORT, EMPTY_RESPONSE, etc.) are returned to the harness’s own retry strategy as-is.

Runtime state is written to ~/.dsh/model-auto-switch-state.json (or $DSH_HOME). This is best-effort: if the file is corrupted, it falls back to the plugin configuration and will not prevent startup.

Manipulating via Tools¶

The agent side can also manipulate this state:

• model_rotation_catalog — List all available provider/model combinations in this installation.
• model_rotation_set — Replace members of the current chain.
• model_rotation_status — View real-time stages and decision logs for each chain and each agent.
• model_rotation_reset — Forget failure records and start the tour again.

Typical Usage¶

A typical scenario is: you have two or three third-party model routes, plus a DSH platform model. Arrange them in a chain, for example:

1. Place the primary third-party model first, with a timeout limit of 2.
2. Place the backup third-party model second, with a timeout limit of 2.
3. Specify a DSH fallback model.

When a rate limit occurs, it immediately jumps to the second one; when two timeouts occur, it also jumps to the second one. If the first one has a sporadic timeout, it gets one more chance in the retest round after the first round ends. When all are exhausted, it falls back to the platform model, and it does not auto-jump back.

Simply select this chain in the selector; no need to change any configuration daily.

Additionally, if your provider supports image input, the harness registers a -vision variant listing the same batch of models, the only difference being the acceptance of images. Selectors hide them by default. Open “Show ‘Auto Image Recognition’ Variants” when needed. Use the normal entry for text-only tasks (cheaper, same context) and add the vision variant only when you actually need to send images.

Compatibility with Provider-level Rotation¶

The plugin rewrites routing in the agent/request waterfall event, which is earlier than adapter binding. Therefore, if a member itself is already rotating accounts after the provider ID (e.g., WorkBuddy, Free Model Pool, etc.), its rotation behavior remains unchanged: it runs its own failure transfer first; the entire pool must fail before reaching this plugin.

Applicable Scenarios & Notes¶

Suitable for: DSH users and agent developers who worry about single third-party route instability, want to handle rate limits and timeouts separately, or want to use platform models as a final line of defense.

Please note:

• The plugin runs with the permissions of the current DSH process and will read/write state files under ~/.dsh. Read the source code and verify the license before installing.
• The license in the current documentation is MIT; the repository is written in JavaScript.
• The plugin cannot work if it depends on a low version of DSH (below 0.2.x, lacking those two waterfall events).

Conclusion¶

Its value lies in turning “model switching” from a manual operation into a stateful chain: rate limits switch immediately, timeouts accumulate, timed-out models are retested, and the end of the chain has a sticky fallback. It only works for model combinations you explicitly configured; it doesn’t interfere when selecting other options.

Directory page: https://www.skillhub.cn/plugins/Chrono-rigger/dsh-model-rotation
GitHub: https://github.com/Chrono-rigger/dsh-model-rotation