perrylink/dsh-budget
Cost governance: aggregate token and cost measurement by model/session/day, session/day/month budget upper limit + threshold alarm (desktop notification + webhook) and over-limit alert/block/degrade policy, carbon footprint estimation, model-by-model delay benchmark, Settings budget page and /budget command
Cost governance for DSH that turns the session event stream into a four-in-one loop: aggregated metering of uncached input / output / cache-read / cache-write tokens with estimated USD cost and carbon footprint per model, session and day; budget governance with session/daily/monthly caps, a warn-ratio threshold alert (webhook POST + optional desktop notification) and three over-limit policies (alert, block, or degrade with guidance naming the cheaper model from your degradation map); a token-to-carbon bridge and per-model latency percentiles; and the Settings budget tab (usage bars, per-day curve, model breakdown, alerts, cap editors, unblock buttons) plus /budget, /budget models and /budget unblock <scope>.
Install
dsh plugin --profile web add dsh-budgetREADME npm channel (dsh plugin --profile web add dsh-budget for published releases). The git channel installs the latest main: dsh plugin --profile web add "github:PerryLink/dsh-budget#main" (its prepare script builds with production dependencies only); a tarball channel (pnpm pack, then dsh plugin --profile web add ./dsh-budget-<version>.tgz) and a deepseek1024 store channel are also documented. Verify the row with dsh --profile web --dump-config | grep -A2 'id: budget'. npm package dsh-budget 0.4.8 (registry-verified 2026-09-10; registry repository field -> github.com/PerryLink/dsh-budget). If pnpm reports ERR_PNPM_IGNORED_BUILDS for esbuild, add allowBuilds: { esbuild: true } to pnpm-workspace.yaml.
Compatibility
Verified against DeepSeek Harness dsh-v0.1.5-rc.1 (GitHub tag verified 2026-09-10; npm pin 0.1.5-rc.1 adapted the same day; peer range >=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0). Node ^22.19.0 || >=24.0.0. Audit events are written on harnesses before 0.1.2-rc.1 and suppressed with a logged degradation reason on 0.1.2-rc.1 and later. Surfaces: host + Web client (Settings budget tab) and a /budget command.
Details
- Repo: perrylink/dsh-budget
- Category: Agent Capabilities
- Stars: 1
- Version: npm dsh-budget 0.4.8 (registry-verified 2026-09-10)
- Last push: 2026-09-21
- First seen: 2026-08-16
Recent updates
README documents the full tunable surface with defaults (session/daily/monthly caps 10/50/500 USD, warnRatio 0.8, overLimit alert, alertCooldownMs 3600000, refreshIntervalMs 5000, alertsEnabled on, desktopNotifications off, webhookUrl optional) and notes that a cordis.patch.yml id-targeted override replaces the whole row, so every key you keep must be restated.
FAQ
- How do I install dsh-budget?
- Run: dsh plugin --profile web add dsh-budget (npm channel), or dsh plugin --profile web add "github:PerryLink/dsh-budget#main" for the latest main. Then verify with dsh --profile web --dump-config | grep -A2 'id: budget' and ask the agent /budget.
- What happens when a budget cap is crossed?
- The overLimit policy decides: alert only notifies, block short-circuits new model requests until you lift the block, and degrade blocks with corrective guidance naming the cheaper model from your degradation map. warnRatio (default 0.8) fires the threshold alert before the cap.
- Can it estimate carbon footprint and latency?
- Yes — it bridges tokens to carbon (tokens x kWh/token x PUE x regional grid intensity, ported from AI-Carbon-Footprint-Calculator) and reports per-model latency percentiles alongside cost.