dsh-cost-governor
Cost governance & budget enforcement for DeepSeek Harness.
A finance-grade "cost governor" layered on top of DSH's built-in token metering: it turns the harness's already-disjoint token buckets (input / output / cache-read / cache-write / reasoning) into money, then enforces a budget — soft warn → hard ceiling → block or steer to a cheaper model — with a polished in-app dashboard.
Not another "cost counter". The counter exists (dsh-token-meter). This plugin is the budget keeper that says how much you're spending, what it will cost by month-end, and stops you when you told it to.
Why this one
| Capability | core dsh-token-meter | typical community cost plugins | dsh-cost-governor |
|---|
| Disjoint token buckets | ✅ | partial | ✅ (reuses core) |
| Compaction-safe accounting | ✅ | ⚠️ often drifts | ✅ (official projection seam) |
| Multi-provider precise pricing | — | mostly DeepSeek-only | ✅ catalog + cache/reasoning buckets |
| Budget warn | — | display only | ✅ threshold events + webhook |
| Budget enforce (block / steer) | — | ❌ | ✅ |
| Cross-session trends + CSV | — | ❌ | ✅ |
| Model cost comparison + savings tip | — | ❌ | ✅ |
Features
- Per-model cost accounting on the official
sessionProjections seam — stays correct through compaction and cold reads, and re-prices history instantly when you edit a price.
- Multi-provider price catalog (DeepSeek, OpenAI, Anthropic, Google, xAI, Qwen, GLM, Moonshot) with separate cache-read/write and reasoning rates. Fully overridable.
- Budget governance:
daily | weekly | monthly | unlimited budget, warnRatio soft threshold, hardRatio ceiling, and a hardAction of notify-only | block-new-requests | steer-to-cheaper-model.
- Webhook notifications (Slack-style / Feishu / DingTalk) on threshold crossings — fail-soft.
- Dashboard (
Settings → Usage & Cost): KPI cards, animated budget bar, per-model spend table, daily chart, savings tip, CSV export.
- Compact HUD budget ring for the sidebar rail.
Install
# 1. install the plugin
npm i -g dsh-cost-governor # or add it to your project
# 2. add to your DSH composition (cordis.yml)
- name: dsh-cost-governor
config:
currency: USD
budget:
period: monthly
budgetUsd: 20
warnRatio: 0.8
hardRatio: 1.0
hardAction: notify-only # notify-only | block-new-requests | steer-to-cheaper-model
notifyWebhook: "" # optional
# 3. restart dsh — the dashboard appears under Settings → Usage & Cost
Configuration
| key | default | description |
|---|
currency | USD | display currency |
budget.period | monthly | daily | weekly | monthly | unlimited |
budget.budgetUsd | 20 | period cap |
budget.warnRatio | 0.8 | soft-warn at 80% |
budget.hardRatio | 1.0 | ceiling at 100% |
budget.hardAction | notify-only | ceiling behavior |
notifyWebhook | — | optional webhook URL |
priceCatalog | built-in | per-model overrides (USD / 1M tokens) |
Architecture
client dashboard / HUD
▲ session/projection frames + settings scope
host UsageCost service ── BudgetGovernor · CostLedger · Notifier
▲ ctx.sessionProjections.register(costUsage)
costUsage projection (pure fold: raw per-model token buckets)
▲ reuses core token buckets (request/context → model attribution)
dsh-token-meter · dsh-llm (TokenUsage)
The costUsage projection stores raw token buckets only — never currency — so it is replay-safe and a price-table edit re-prices history without refolding the log.
Development
pnpm install
pnpm build # tsc (see PUBLISHING.md for the full DSH toolchain notes)
Open preview/dashboard.html for a zero-build visual preview of the dashboard.
Limitations
- Only final
assistant/message usage is billed; input spend of a request that fails before assembling a message is not captured (a provider still charges it). This matches the harness's own usage-carrier semantics and is a documented edge, not a miscount.
block-new-requests / steer-to-cheaper-model are exposed as a governance gate (BudgetGovernor.gate) and emitted events; wiring them into the LLM waterfall is the one integration point to verify against the official DSH plugin docs at first build.- Prices in the built-in catalog are community placeholders — verify against each provider before trusting absolute dollar figures.
License
MIT
