dsh-quota-router: policy-only multi-source quota router (task profiles × source priority, health-aware fallback)

[Liyuk]

Unofficial project, independently developed and maintained by community members.

What it is

dsh-quota-router 1.0.0 is a policy-only multi-source model routing and failure-recovery plugin for DeepSeek Harness (DSH).

It selects among provider/model routes already registered and natively validated by DSH. It does not manage providers or credentials, and it does not implement tool lazy-loading, context compaction, or model-quality evaluation.

1.0 capabilities

• Task Profile matching with first-match semantics;
• Global source priority × per-task model mapping to build ordered candidate chains;
• Native DSH provider/model validation;
• Explicit paid opt-in; manual/emergency sources are never auto-selected;
• Stable failures advance immediately, while transient failures first use DSH retry;
• Forward-only fallback with cooldown;
• Per-turn route identity, bounded idempotent receipts, and an in-memory ledger;
• DSH Web Settings → Quota Router configuration and candidate-chain preview;
• SubtaskRouter with explicit capability constraints and model leases;
• quota_router_status and session Route Receipt observability.

How it integrates with DSH

Install:

npm install @liyuk/dsh-quota-router

Register providers/models in DSH Models first. Then configure source priority, task Profiles, model mappings, paid-fallback protection, transient thresholds, and cooldown in Settings → Quota Router.

The router only chooses candidates that DSH already knows and accepts. It does not replace the Agent Loop or create a second session store.

Cost and scope

The plugin can reduce unnecessary provider calls by using appropriate routes, skipping known-bad candidates, and avoiding repeated retries of stable failures. It does not claim guaranteed token savings or guaranteed lower total cost; evaluate route cost together with quality, rework, and a comparable baseline.

Route cost and context cost are separate:

• route cost: provider/model, input/output/cache/reasoning tokens, fallback;
• context cost: tool schemas, prompts, cache, compaction, and context visibility.

Links

• Project: https://github.com/Liyuk/dsh-quota-router
• npm: https://www.npmjs.com/package/@liyuk/dsh-quota-router
• Release/community notes: https://github.com/Liyuk/dsh-quota-router/blob/main/docs/RELEASE-1.0.0.md
• Architecture diagram: https://raw.githubusercontent.com/Liyuk/dsh-quota-router/main/docs/assets/architecture.svg

Feedback is welcome on Profile matching, fallback recovery, DSH adapter compatibility, and composition with context/tooling plugins.

[MajidAsghariTabrizi]

Adjacent project here — free-best-router sits one layer below this (provider layer, not policy layer) and could be a natural composition target.

The split I would propose:

• dsh-quota-router (yours): task-profile x source-priority x health-aware policy. Decides which logical model class to ask for, given budget, task type, and provider health signals.
• free-best-router (mine): provider layer that turns the "free LLM" request into a concrete provider/model call, handling discovery, capability ranking, per-failure cooldowns, bounded failover, and exploration. Decides which actual concrete model satisfies the request, and what to do when the first attempt fails.

The composition: DSH -> dsh-quota-router -> free-best-router -> concrete provider. The quota router asks for free-best; the free router picks the model. The quota router never has to know which provider is healthy at 3am, and the free router never has to know about task profiles or budgets.

Two technical details that make this composable today:

• free-best-router exposes a single OpenAI-compat route, so dsh-quota-router can treat it as one provider (not 7) and apply one policy block to it
• Both routers can coexist as DSH providers — free-best for the "free" lane, your existing providers for the paid lanes

Full write-up in DSH Show Your Plugins! discussion #5508. Would love to know what the policy layer would actually need from the routing layer to make this work cleanly — happy to align on the headers / response shape.

[MajidAsghariTabrizi]

Reply to #3544 — dsh-quota-router as a peer

UEA positions itself on the orchestration side of the same surface that quota-router and free-best-router occupy on the routing side. Here is the full stack for reference:

DSH session
  └── UEA kernel (engineering loop)
        └── llm block → model router → upstream providers

The DSH ecosystem currently has strong coverage of the routing layer — quota-router for per-key budgets, free-best-router for free-model fan-out, native LLM blocks for vendor SDKs. UEA is the missing piece above that: the operating kernel that decides what to do next after a failure, how to stage work, and how to verify it before the next routing decision matters.

The 10-class failure classifier is what makes these compose: a PROVIDER_ERROR from the routing layer is handed to the kernel's recover stage, which applies bounded exponential backoff. A PERMISSION_ERROR from a tool call is explicitly non-retryable and falls through to the operator. The router decides where the call goes; the kernel decides whether another call is safe.

MajidAsghariTabrizi/universal-engineering-agent · MIT · 9-stage operating kernel · 31 self-tests

The docs/OPERATING-Kernel.md has the full contract, including how the classify → recover pipeline interacts with the routing layer.

[Liyuk]

Thanks — I think this could be a good opportunity for collaboration. The separation between the policy layer and provider-routing layer makes sense, and I’d be happy to see this developed further.
Given my current focus, I probably won’t be able to drive all of the implementation myself. If you’re interested, feel free to open a design issue and take the lead on an initial PR. It would also be useful to explore whether the routing layer should be packaged and published through npm, with a clear interface and release process.
I’d be happy to review the proposal and implementation, help with the integration points, and discuss the package ownership and publishing setup as the design becomes clearer.