Proactive per-provider token-bucket rate limiting that queues over-limit requests before they are sent, preventing upstream 429 errors.
Install
# from npm (prebuilt)
dsh plugin --profile web add @xidong-ai/dsh-rate-limiter
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:Xidong-AI/dsh-rate-limiter
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
A proactive rate limiter plugin for DeepSeek Harness (dsh): it controls the request rate per provider (token bucket) before model requests are issued, and queues the request with a delay instead of failing when the limit is exceeded — avoiding upstream 429s.
It complements the official dsh-llm-retry (exponential backoff after failure): rate limiting comes first (prevention), backoff comes last (safety net); the two do not interfere with each other.
Features
- Per-provider token bucket, enforced before the request is sent (proactive prevention)
- Over-limit requests are queued with a delay instead of rejected (no 429s, no lost requests)
- Unconfigured providers pass through untouched (zero intrusion)
- Queued waits honor the abort signal: stopping the user interrupts the wait immediately
- Hand-written reservation-based token bucket (concurrency-safe), zero third-party rate-limiting dependencies
- Mounts on
agent/request, coexists naturally withdsh-llm-retry
Installation
Install from npm:
dsh plugin --profile web add @xidong-ai/dsh-rate-limiter
npm registry URLs are case-sensitive; use the lowercase package name.
Or install directly from GitHub:
dsh plugin --profile web add github:Xidong-AI/dsh-rate-limiter
For local development, add the checkout directly:
dsh plugin --profile web add .
After installing, dsh --profile web --dump-config should show the plugin entry:
- id: rate-limiter
name: @xidong-ai/dsh-rate-limiter
config:
enabled: true
providers: {}
Configuration
Configure the token bucket per provider in the profile's cordis.patch.yml (or this plugin's cordis.patch.yml):
- id: rate-limiter
config:
enabled: true
providers:
nvidia:
rate: 0.5 # tokens/second (long-term average QPS)
burst: 1 # bucket capacity (allowed burst requests)
sensenova:
rate: 0.02778
burst: 1
rate: refill rate (tokens/second), i.e. the long-term average request rate.burst: bucket capacity, the number of burst requests allowed.- Providers not listed are not rate-limited; requests pass through untouched (zero intrusion).
enabled: falsedisables the plugin entirely.
How It Works
The plugin hooks onto the agent/request waterfall: it await next() first to obtain the call config (which carries the provider), then performs a per-provider token bucket check; when tokens are insufficient, it queues the request with a delay (interrupted immediately by the abort signal when the user stops), then returns the config unchanged — it never modifies request content, never changes routing, never swallows errors. It only controls when a request is issued.
The rate-limiting algorithm is a hand-written reservation-based token bucket (concurrency-safe), with zero third-party rate-limiting dependencies.
Relationship with dsh-llm-retry
| Plugin | Timing | Behavior |
|---|---|---|
dsh-rate-limiter |
Before the request is issued | Queue with a delay when over the limit (prevents 429s) |
dsh-llm-retry |
After the request fails | Exponential backoff retry (safety net) |
They mount at different points (agent/request vs agent/request-error) and coexist naturally.
Compatibility
Runtime feature detection lets one build run on both dsh 0.1.x and 0.2.x
hosts. On 0.2.x the settings form now saves without the
has no volatile fields error, and the card is registered on the bundle and
plugin-row config seats. Available since 0.3.3.
Uninstall
dsh plugin --profile web remove @xidong-ai/dsh-rate-limiter
Development
npm install
npm run typecheck # tsc --noEmit
npm run test # vitest run
npm run build # esbuild transpiles lib/*.ts → lib/*.js
Acknowledgements
Thanks to the Linux.do community for support.
Links
More in this category
bowenliang123/dsh-context★ 5191
DSH context insight panel: Context dashboard + /context command + Context browser — one-stop context lifecycle management with categorized composition, content details, evolution trends, compaction/injection events, and stats.
Han-1413141/dsh-cost-meter★ 705
Per-session and daily API cost, budget with usage %, official balance, history dashboard, and one-click official price sync with peak/off-peak pricing.
wssfk12138/dsh-damage-pulse★ 290
Tracks DeepSeek token usage, per-call and session costs, and account balance with cache-aware charge animations in the DSH Web UI.
zh667/TokenLedger★ 205
Sidebar usage panel that attributes tokens to the relay site that served each request, read from your existing provider config: today/month/all-time totals, per-site and per-model breakdowns, a year activity heatmap, and New API / Sub2API / DeepSeek balances.
Ychris12138/dsh-usage-stats★ 190
Multi-provider usage dashboard with provider/model token breakdowns, calendar drill-downs, account balances, and OpenCode Go / Z.ai subscription quota tracking.
Mt-Youya/dsh-plugins#sessions-insight★ 166
Browse Claude Code, DSH and Codex session logs by working directory, with per-turn context composition, token usage, compaction markers and cost estimates.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.