💰 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 插件家族的一员（40+ 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 40+ plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

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 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.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 <scope>).

Quick start

# 1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-budget#main"

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

Install & uninstall

• git channel (latest main): dsh plugin --profile web add "github:PerryLink/dsh-budget#main" — 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.

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 <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 one of the 45 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

| Plugin | One-liner | |---|---| | dsh-auto-review | Second-model auto-review on the approval chain, fail-closed by default | | | dsh-autotier | Automatic strong/cheap model-tier routing with deterministic risk guards and a /tier command | | | dsh-background-agents | Durable background child agents with a Web UI sidebar, messaging and interrupt | | | dsh-budget | Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel. | | | dsh-catalog | DSH Desktop Market standard catalog source for the PerryLink family | | | dsh-cert-mcp | Read-only MCP server exposing the certification registry: grades, snapshots and five-dimension evidence | | | dsh-checkpoint-rewind | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore | | | dsh-claude-move | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH | | | dsh-click | Cross-platform native desktop control for DeepSeek Harness — Windows first. | | | dsh-composer-history | Terminal-style input history for the web composer: arrows, Ctrl+R search | | | dsh-data-quality | Dataset quality checks and citation cross-checks (the optional numeric bridge consumed here) | | | dsh-defend | Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness. | | | dsh-doublecheck | Engineering-discipline guard: requirements grill, test gates, adversary review | | | dsh-draw | Unified static-image generation routing for DeepSeek Harness. | | | dsh-fast | Read-only performance diagnostics for DeepSeek Harness. | | | dsh-fund-research | Deterministic research reports for Chinese public mutual funds | | | dsh-github | GitHub PR/issues integration for DSH, every write gated by approval | | | dsh-industry-research | Industry research orchestration that seals its deliverables through this plugin's ctx.researchReport.assemble | | | dsh-laya | Laya typed decisions (noul/choice/score) as a first-class Cordis service and model-visible tools | | | dsh-library | Local document knowledge base for DeepSeek Harness. | | | dsh-local-ai | Local-model (Ollama) integration for DeepSeek Harness. | | | dsh-lsp-actions | LSP diagnostics, formatting, completion, code actions and rename over language servers | | | dsh-mask | PII masking middleware: anonymize at the model boundary, restore at the display layer | | | dsh-mcp-panel | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors | | | dsh-memento | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | | | dsh-observe | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | | | dsh-output-styles | Claude Code outputStyles-equivalent runtime style switching | | | dsh-permission-rules | Claude Code-style declarative allow/deny/ask permission rules with audit | | | dsh-plugin-certification | Community certification registry with repro-checkable grades and badges | | | dsh-plugin-doctor | Zero-dependency static + sandbox smoke detector for DSH plugins | | | dsh-plugin-guide | Plugin-development knowledge base as an on-demand agent skill | | | dsh-plugin-kit | Shared zero-runtime-dependency toolkit for the PerryLink DSH plugins | | | dsh-plugin-upgrade | One-package, one-corridor-index plugin upgrade skill: routes a repository to the matching closed corridor card | | | dsh-reach | Multi-channel approval/question bridge: WeChat/Telegram/Feishu, session console | | | dsh-research-report | Verifiable research-report engine: content-addressed evidence ledger and sealed versions | | | dsh-score | Multi-dimensional quality scoring for DeepSeek Harness plugins. | | | dsh-session-pin | Pin sessions in the Web sidebar with durable ordering | | | dsh-session-sync | Cross-device session sync for DeepSeek Harness — a dedicated git mirror of your session store. | | | dsh-skill-pack-security | Security-audit skill pack: secret scan, dependency and supply-chain review | | | dsh-talk | Voice-first session loop for DeepSeek Harness: talk to it, hear it answer. | | | dsh-team-rooms | Cross-session team rooms: shared message bus, task board and timeline | | | dsh-test-drive | Isolated install-and-smoke test drives for DeepSeek Harness plugins. | | | dsh-ticktick | TickTick/Dida365 task bridge: session-header panel + 11 tools | | | dsh-translate | Vendor parameter translation and deterministic JSON repair for DeepSeek Harness. | |

Install from the DSH Desktop Market

All PerryLink plugins are browsable in the built-in DSH Desktop Market: Market → Sources → add source → paste https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → select it. Installation still goes through the Market's npm-identity verification and your confirmation.

License

Apache License 2.0 © 2026 dsh-budget contributors