💰 dsh-budget
Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.
Know what every session costs — before it costs you.
Official repository. This is the only official repository of dsh-budget, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.
DSH Market
English · 简体中文 · Español · Português · हिन्दी
dsh plugin --profile <name> add dsh-budget
📖 Ecosystem knowledge base — measured data, not marketing: plugin development guide · plugin-selection data · maintenance criteria.
Install & uninstall
- git channel (latest
main): dsh plugin --profile web add github:PerryLink/dsh-budget — the prepare script builds with production dependencies only.
- npm channel (published releases):
dsh plugin --profile web add dsh-budget.
- tarball channel:
pnpm pack in this repo, then dsh plugin --profile web add ./dsh-budget-<version>.tgz.
- uninstall:
dsh plugin --profile web remove dsh-budget.
If pnpm reports ERR_PNPM_IGNORED_BUILDS for this package (esbuild's harmless platform-binary validation), add allowBuilds: { esbuild: true } to your pnpm-workspace.yaml — the dsh CLI prints the exact snippet.
⭐ 如果它帮到了你
这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。
English: part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.
What is dsh-budget?
Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.
Know what every session costs — before it costs you.
Workflow diagram for dsh-budget: request → policy / review → verdict.
Workflow overview: request → policy / review → verdict. The examples below use the real command surface.
Maintenance status: 🧊 FROZEN
Frozen on 2026-10-05. No new features. This package still works, and it is not retired — but it no longer receives feature work. Only a genuine breakage will be fixed.
Maintainers treat this capability as one where the ecosystem has converged on a more widely adopted implementation, so effort has moved elsewhere. The comparison below was measured on 2026-10-05 and is recorded so nobody has to redo it.
| package | weekly downloads |
|---|
| this package | dsh-budget | 1,079 |
| more widely adopted implementation | dsh-cost-meter | 33,526 |
| another alternative | dsh-usage-stats | not measured |
| another alternative | @dougen/dsh-deepseek-usage | 6,019 |
Why it is the mainstream choice. dsh-cost-meter provides a 170+ model price catalog with automatic matching, and Coding-Plan quota lookup for 11 providers.
Compatibility. Its declared dsh peer range admits the 0.2.x line, so it loads on current hosts.
👉 For new work, dsh-cost-meter is the mainstream choice. Existing installs keep working unchanged; nothing is being removed.
Full evidence, including the host-version compatibility matrix: dsh-plugin-supersession-review-20261005.md.
Comparison
Measured comparison chart for dsh-budget
measured 2026-10-05 · from the README's FROZEN maintenance table (npm weekly downloads)
Compatibility
| Surface | Status |
|---|
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1 (GitHub tag, adapted 2026-09-24; peer range `>=0.1.2-rc.1 <0.2.0 |
| Audit events | Written on harnesses before 0.1.2-rc.1; suppressed with a logged degradation reason on 0.1.2-rc.1 and later (fail-closed session event vocabulary, no external registration surface) || Node | ^22.19.0 \|\| >=24.0.0 |
| Surfaces | Host + Web client (Settings budget tab); /budget command |
What you get
dsh-budget turns the session event stream into a four-in-one cost governance loop:
- Aggregated metering — tokens (uncached input / output / cache read / cache write), estimated USD cost, and carbon footprint per model, session, and day, priced through a built-in USD-per-1M table merged with your
config.prices.
- Budget governance — session/daily/monthly caps; a warn-ratio threshold alert (webhook POST + desktop-notification flag) and three over-limit policies:
alert (notify only), block (short-circuit new model requests until the user lifts the block), degrade (block with corrective guidance naming the cheaper model from your degradation map).
- Carbon & latency — token→carbon bridge (tokens × kWh/token × PUE × regional grid intensity, ported from AI-Carbon-Footprint-Calculator) and per-model latency percentiles.
- Surfaces — the Settings budget tab (usage bars, per-day usage curve, model breakdown, alerts, cap editors, unblock buttons) and the
/budget command (/budget, /budget models, /budget unblock <scope>).
Quick start
dsh plugin --profile web add github:PerryLink/dsh-budget
# 1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-budget
# or from npm (published releases)
dsh plugin --profile web add dsh-budget
# 2. restart and verify the row
dsh --profile web --dump-config | grep -A2 'id: budget'
Then ask the agent: /budget — and watch the Settings tab fill in.
Examples
These are the plugin's real entry points; install once, then call one.
Detailed example
Command
/budget
Output
session: 5.00 USD / 10.00 USD (50% · 1000 tokens · 0.0010 kg CO2e)
daily: 60.00 USD / 50.00 USD (120% · 20000 tokens · 0.0200 kg CO2e) BLOCKED
monthly: 60.00 USD / unlimited (0% · 20000 tokens · 0.0200 kg CO2e)
deepseek/deepseek-chat: 0.05 USD (100 in / 50 out · p50 20ms · 0.0001 kg CO2e)
Observed from tests/command.spec.ts:14-62 (STATUS fixture and overview test); src/command.ts:65-88
Failure branch
Input
/budget unblock yearly
Output
usage: /budget [unblock session|daily|monthly | models]
Observed from plugins/dsh-budget/src/command.ts:35; plugins/dsh-budget/src/command.ts:99-103; plugins/dsh-budget/src/command.ts:128; plugins/dsh-budget/tests/command.spec.ts:49-50
Brief examples
/budget models/budget unblock <scope>
Configuration
All tunables are Schemastery Config fields (changeable from cordis.yml). cordis.patch.yml documents each key inline.
| Key | Default | Meaning |
|---|
prices | {} | Per-model USD prices per 1M tokens, merged over the built-in table |
defaultPrice | unpriced signal (priced: false, zero numbers) | Fallback for models absent from both tables: the default contributes 0 to accounting and surfaces as "unpriced"; set numbers with priced: true to price unknown models explicitly |
budgets.session / daily / monthly | 10 / 50 / 500 | Budget caps in USD per scope; omit for unlimited |
warnRatio | 0.8 | Alert once usage reaches this fraction of a cap (0..1) |
overLimit | alert | alert / block / degrade after a cap is crossed |
degradation | {} | Model id → cheaper model id of the same provider |
webhookUrl | (none) | Optional webhook URL for threshold alerts (POST JSON) |
webhookTimeoutMs | 5000 | Webhook request timeout |
alertsEnabled | true | Master switch for threshold alerts |
alertCooldownMs | 3600000 | Minimum ms between two alerts of the same scope |
desktopNotifications | false | Browser desktop notifications while the tab is open |
refreshIntervalMs | 5000 | Settings tab polling interval |
carbon.enabled / region / pue / energyKwhPerToken | true / global / 1.58 / 0.000007 | Carbon bridge (regions: global, us, eu, china, india, uk, france, iceland) |
| / |
Tools & surfaces
| Surface | Kind | Notes |
|---|
/budget | Command | Per-scope overview (usage, ratio, carbon, blocked state) |
/budget models | Command | Per-model breakdown with latency percentiles |
/budget unblock <scope> | Command | Lift a blocked scope (session / daily / monthly) |
| Settings → Plugins → Budget | Settings tab | Usage bars, per-day usage curve, model breakdown, alerts, cap editors, unblock buttons |
budget/status, budget/setSettings, budget/unblock | Typert Remote | The client channel (the tab consumes these) |
Permissions & data
- Permissions:
network:outbound (the optional alert webhook only), session:append (audit events), native-code:none.
- Data: everything displayed comes from the session event stream; the only host-side network call is the configured webhook, whose URL is validated at load and credential-stripped before any log. No prompts or payloads ever leave the host.
- Session log:
budget/alert and budget/block are log-only audit events carrying scope names and USD amounts (microtask-deferred past the session-append reentrancy guard). On harnesses 0.1.2-rc.1 and later they are not written — the fail-closed event vocabulary rejects logs with unregistered event types and offers no external registration surface — so the audit trail degrades to the budget logger and webhook only.
Security boundaries
- No fabrication: a budget block yields a corrective error finish on the
llm/stream waterfall — the plugin never invents model output.
- No request rewriting: loop-built requests are frozen;
degrade therefore names the target model in the corrective message instead of swapping the request.
- Fail loud: invalid prices, URLs, ratios, regions, and bounds fail the mount.
- Honest scope: runtime edits from the panel are session-scoped; a reload restores the cordis.yml values.
Known limitations
- Aggregation is process-local: usage resets when the harness restarts (per-day/per-month buckets rebuild from the current session log view).
block/degrade rely on the llm/stream waterfall; harness builds without that seam cannot block requests (alerts still work).- Built-in prices drift; override entries via
config.prices.
Development
pnpm install # node ^22.19 || >=24
pnpm run typecheck # tsc: src + tests against the local harness checkout
pnpm run typecheck:ci # tsc against the published types (no paths)
pnpm test # vitest
pnpm run build # tsc declarations + tsdown bundles (lib/)
pnpm run verify:self-contained # dependency specs resolve from the registry
pnpm run verify:artifacts # built ESM face + typert manifest + client bundle
pnpm pack # the published tarball
Interoperability with other DSH plugins
Verified against DSH 0.2.0-rc.2 (the runtime this README ships for) and the high-star plugin set surveyed on 2026-10-05.
This plugin does not interfere with other plugins, including the widely installed high-star ones:
- No tool-name collision. Every tool is namespaced; no bare name owned by a shipped tool or another plugin is registered.
- No service-key collision. It provides
budget; that key is not a built-in seam and is not provided by any surveyed high-star plugin.
- No slot collision. It registers no client slot key, so it cannot contend for a
shadows-shipped-ui seat.
- No HTTP route collision. It registers no
webServer prefix.
- No patch-layer collision. The bundle patch only
inserts its own row; it never overrides a built-in row's config.
- No global mutation. It does not patch prototypes, rewrite
process.env, or replace the global fetch dispatcher.
Shared event listeners are non-interfering by construction. It observes the ordering-sensitive event llm/stream with ctx.on() — Cordis's broadcast registration, where every listener runs and none can starve another. Every listener here delegates through next(), so the chain is never short-circuited, and a mutation is applied to the value next() produced rather than returned in its place:
llm/stream — also used by dsh-routing-suite (7000★).
Static evidence: dsh-plugin-doctor K10–K13 report pass for every check on this repository.
Topics
dsh, dsh-plugin, deepseek-harness, deepseek, cordis, budget, cost-tracking, carbon-footprint, latency-benchmark, token-usage
Contributors
- @PerryLink — creator and maintainer: aggregation, budget governance, carbon and latency ports, the Settings tab, and the five-language docs.
PerryLink DSH Plugin Family
This project is part of the DeepSeek Harness plugin family from PerryLink. The roster stays collapsed below so every README keeps a short first screen; expand it to see every row and its status.
Expand all plugins
License
Apache License 2.0 © 2026 dsh-budget contributors
