Introduction¶

Agent developers often face the same class of problem: how many free model platforms are there, and what are their different quotas and reset times? When running on a specific platform, if a quota cap is triggered midway, the entire task is interrupted, and all the context accumulated up to that point is wasted. Manually monitoring and switching platforms or models can solve the problem, but it is not sustainable, especially when platforms are added or removed, or when model names differ across channels.

puppy-bai/dsh-quota-takeover handles this by adding a layer of “relay” logic on top of Our Free Model (hereinafter referred to as OFM)—when a platform’s quota is insufficient, it switches to the next one in the order you set; if a platform doesn’t have the model you want, it skips it; if none are available, it switches to the next model tier and iterates through them again. When a task is interrupted due to a quota, it automatically switches to a new platform and sends a “continue” message to the interrupted session. The maintainer is puppy-bai, and the category is Model Inference.

This article is based solely on the contents of the plugin README and package.json and does not involve unlisted features.

What Problem Does It Solve¶

OFM is responsible for aggregating accounts, models, and remaining quotas from multiple platforms. Its shortcoming is a fixed order: when a platform’s quota is exhausted, the relay does not happen automatically. This plugin compiles “Platform Order × Model Tiers” into an ordered candidate chain and writes it back to OFM’s combo (auto:main), which is then attempted item by item using OFM’s fallback strategy.

In other words, the plugin does not directly call the models; its job is to compile the plan and write back the plan.

Core Capabilities¶

Below are the implemented behaviors listed item by item based on the “What it does” table in the README.

1. Switch to the next platform when quota is exhausted: Compiles “Platform Order × Model Tiers” into a candidate chain and writes it back to OFM’s combo (auto:main).
2. Skip if model does not exist: Each model tier has an alias table. If a platform’s model list does not match, it is marked as missing and skipped. Alias matching performs an exact comparison first, followed by a lowercase comparison of the -free/-preview/eac: prefixes, and finally a comparison of the last segment of the ID—e.g., the aggregation channel’s siliconflow/deepseek-ai/DeepSeek-V3 can be matched by DeepSeek-V3.
3. Switch tiers and re-iterate if all are exhausted: The traversal shape is tier-major (tiers first), first searching for Tier 1 across all platforms, then searching for Tier 2.
4. Fallback: When finalResort.fallbackModels (e.g., groq/llama-3.3-70b) is not empty, it compiles a fallback chain; if empty, it enters “Waiting for recovery”.
5. Resume on interruption: Listens to the error endpoint of llm/stream, classifies it as quota/throttling, then writes a cooldown, recompiles the plan, and calls agent.followup(a "continue" message) for that session.
6. Automatic maintenance of platform list: There are three sources for platforms—channel-pack account pool, OFM aggregation channels /providers, and new channels in the catalog (e.g., subscription:magpie/siliconflow/…). Every round reads these synchronously. Platforms not read for platformPolicy.pruneAfterMisses (default 3) consecutive rounds are removed from the order; pruneZeroAccounts (default on) hides channels with zero accounts, and accounts will automatically return once added; you can also manually delete platforms row by row on the settings page, writing to hiddenPlatforms and excludePlatforms, and clicking ↺ at the bottom “Hidden N” can restore them.

Why Two Halves¶

OFM’s API hangs behind the harness’s trusted fence, so fetch inside the plugin process always returns 401 (as mentioned in the README, verified, see Design Document §12.1). Therefore, the two tasks of reading accounts/quota and writing combos can only be done by the browser side, while the host side is responsible for compiling the plan.

Browser (with DSH auth cookie)                Host process
  │ ① GET /api/our-free-model/combos         │
  │ ① GET /api/our-free-model/subscriptions  │
  │ ② POST /api/quota-takeover/snapshot ────▶│ Compile plan (Platform Order × Model Tiers × Quota × Cooldown)
  │ ③ GET /api/quota-takeover/pending ◀──────│ Combos to be written back
  │ ④ POST /api/our-free-model/combos        │   (Only browser has write permission)
  │ ⑤ POST /api/quota-takeover/applied ─────▶│ Record written back

Resume on interruption is not affected by this restriction because it uses agent.followup() within the process, bypassing HTTP.

Installation and Activation¶

Prerequisite: Install Our Free Model first. Without OFM, this plugin only retains resume capabilities and no platforms to relay to.

Install from the market (available after release):

DSH → Plugins → Discover and search quota-takeover

Install manually (for development or unreleased versions), the command given in the README is as follows:

cd ~/.dsh/profiles/desktop
npm i /path/to/dsh-quota-takeover-0.1.1.tgz   # or copy the source directory to node_modules/dsh-quota-takeover

# Then append "dsh-quota-takeover" to the dsh.profile.bundles array in package.json
# Packages referenced by bundles have their own cordis.patch.yml automatically applied;
# Do not manually write the same entry in cordis.patch.yml, otherwise it will report duplicate loader entry id

After installation, completely exit DeepSeek Harness and reopen it. The host half is only apply-ed once when the process starts; refreshing the page only reloads the browser half.

Three checkpoints:

Runtime data is placed in ~/.dsh/quota-takeover/{config,plan,bench,resume,platforms}.json and journal.jsonl.

Configuration¶

The configuration file is ~/.dsh/quota-takeover/config.json, which can also be written to by the settings page “Quota Relay”. The example provided in the README:

{
  "enabled": true,
  "platformOrder": ["trae", "minimax", "zcode", "loomy", "raccoon", "gemini"],
  "platformPolicy": {
    "unknownTail": true,
    "excludePlatforms": [],
    "pruneMissing": true,        // Automatically remove channels from the order if they cannot be read
    "pruneAfterMisses": 3,       // Remove only after consecutive absences (prevents accidental deletion from one detection failure)
    "pruneZeroAccounts": true    // Automatically hide empty channels with 0 accounts (return automatically once accounts are added)
  },
  "modelTiers": [
    { "id": "deepseek-flash", "label": "DeepSeek V4.1 Flash", "pinned": true,
      "aliases": ["deepseek-v4.1-flash", "deepseek-v4-flash-0731", "deepseek-flash"] },
    { "id": "glm-flash", "label": "GLM 5.3 Flash", "aliases": ["glm-5.3-flash"] }
  ],
  "traversal": { "order": "tier-major", "maxChainLength": 16, "optimisticOnUnknown": true },
  "finalResort": { "fallbackModels": [], "retryAfterMinutes": 10 },
  "resume": { "enabled": true, "onlyQuotaLike": true, "maxPerSession": 5, "requireCandidateChange": true }
}

A few common pitfalls:

1. Platforms not listed in platformOrder are placed at the end (controlled by platformPolicy.unknownTail).
2. pruneMissing / pruneAfterMisses determine when channels are removed; the number of absences is recorded in platforms.json. If a round cannot read any platform, the entire round is skipped. The README explains this is to distinguish relay faults from deleted channels.
3. optimisticOnUnknown: When the platform model list is unknown, the slot is first put into the chain. If it truly doesn’t exist, OFM’s combo will naturally fail and move forward—unknown does not mean non-existent.
4. resume.requireCandidateChange is the core anti-bug feature: if the candidate chain doesn’t change, don’t repeatedly inject “continue” to avoid repeatedly triggering on the same quota-exhausted platform.

HTTP API¶

The following interfaces are used on the browser side and require DSH auth cookies:

Developer Self-Testing¶

Several commands given in the README, suitable for running after code changes:

node --test tests/*.test.js     # Unit tests (Compiler / Classifier / Resume State Machine, README lists 32)
node probes/smoke-host.mjs      # Mock ctx loading host half, running through the relay loop
node probes/plan-preview.mjs    # Preview a compilation using local state.json
node probes/ofm-probe.mjs <gui address>   # Probe: OFM API reachability (expected 401)

Known Limitations¶

Listed according to the “Known Limitations” section in the README:

1. Writeback depends on the GUI being open. When the browser is closed, the chain stops on the old plan; the candidate chain already includes resolved model IDs, so the old chain can still run.
2. By default, it does not directly modify OFM’s settings.json (except explicitly writeBack.mode: "file"). OFM keeps settings in memory; modifying disk files doesn’t take effect hot and will be overwritten on the next save.
3. Resume only works on “quota/throttling” type failures (onlyQuotaLike); user-initiated aborts never resume.
4. llm/stream currently only observes and does not reroute (Probe 4 not verified), rerouting capability is reserved for M2.

Applicable Scenarios and Notes¶

Suitable for developers already using OFM to aggregate multiple free or low-cost platforms: those who want to leave platform additions/deletions, model tier order, and resume after quota interruption to the plugin for maintenance, rather than manually modifying combos. When there are many platforms, model names vary across channels, and quota exhaustion happens frequently, this layer of relay can significantly reduce manual intervention.

Points to note:

• The plugin runs with the permissions of the current dsh process; you should check the source code and license before installing (the license field in the README is MIT).
• It is a layer on top of OFM, requiring OFM to be properly configured and channel-pack enabled; without OFM, only resume capabilities remain.
• Writeback depends on the browser half; in long-running environments, the GUI cannot be closed arbitrarily.

Conclusion¶

The value of dsh-quota-takeover lies in automating the chain “Quota exhausted → Switch platform/model tier → Continue”, and using configurations like resume.requireCandidateChange to control accidental resumes. If your needs fall outside the reach of OFM, you can first check the plugin directory page and source code before deciding:

• Directory page: https://www.skillhub.cn/plugins/puppy-bai/dsh-quota-takeover
• GitHub: https://github.com/puppy-bai/dsh-quota-takeover

The directory site is an independent site and has no official affiliation with DeepSeek / Hyperscience.