dsh-budget

💰 dsh-budget

• 1024 store channel: npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-budget (counts toward the deepseek1024.com install ranking).

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.

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-.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 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 better-adopted alternatives now exist, 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 better-adopted alternative · dsh-cost-meter · 33,526 another alternative · dsh-usage-stats · not measured another alternative · @dougen/dsh-deepseek-usage · 6,019

Why the alternative leads. 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, prefer dsh-cost-meter. 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 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.1.5-alpha.1 =0.1.6-0 =0.1.7-0 <0.2.0): the alpha.2 catalog prices are built into the price table and unknown models surface as unpriced instead of a fabricated estimate; the audit gate keeps suppressing budget/alert/budget/block appends (fail-closed session event vocabulary). Verified 2026-09-24 by the two-ruler typecheck chain and the full local gate; the browser-panel items stay 人工·未测即未完成 (maintainer manual checklist).

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 ).

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

~~~sh /budget ~~~

Output

~~~text 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

~~~text /budget unblock yearly ~~~

Output

~~~text 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

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) latency.enabled / windowSize · true / 200 · Per-model latency percentiles and their window currency · {code: USD, rate: 1.0, decimals: 2} · Display currency (costs are computed in USD) outputLanguage · en · /budget output language: en / zh historyDays · 30 · Per-day usage history kept in the panel snapshot persistence.enabled / intervalMs · true / 10000 · Durable day/month persistence across restarts (storage domain); degrades to in-memory when the domain is absent

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 · 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.