---

Compatibility

| Surface | Status | |---|---| | Harness | DeepSeek Harness dsh-v0.1.5-rc.2 (GitHub tag, verified 2026-09-11; npm pin 0.1.5-rc.2 adapted 2026-09-10; peer range >=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0): the session envelope keeps its ignorable field for stored-log read compatibility only - Session.append still cannot stamp it, so audit-gate behavior is unchanged. Verified 2026-09-11 against the dsh-v0.1.5-rc.2 master checkout (full local gate chain; the profile install smoke runs in the monthly Compat workflow). |

| 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 | {input: 1.0, output: 3.0} | Fallback for models absent from both tables | | 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 0.1.5-rc.2 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

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 40 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-background-agents | Durable background child agents with a Web UI sidebar, messaging and interrupt | | | 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-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-personal-directive | Personal directive injector with top-bar toggle (framework edition) | | dsh-plugin-guide | Plugin-development knowledge base as an on-demand agent skill | | | dsh-plugin-doctor | Zero-dependency static + sandbox smoke detector for DSH plugins | | | 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-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. | | | dsh-wechat | WeChat ↔ DSH bridge (Tencent iLink bot): text/image/file/voice, approvals in chat | | dsh-autotier | Automatic strong/cheap model-tier routing with deterministic risk guards and a /tier command | | | 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-kit | One-command starter pack that installs the core family | | | dsh-plugin-certification | Community certification registry with repro-checkable grades and badges | | | dsh-plugin-kit | Shared zero-runtime-dependency toolkit for the PerryLink DSH plugins | | | dsh-plugin-portal | Zero-dependency static portal rendering the whole plugin family as one page | | | dsh-plugin-upgrade-015 | Merged 0.1.3-alpha.1 → 0.1.5-rc.1 upgrade corridor card plus a zero-dependency seam scanner | | | dsh-team-rooms | Cross-session team rooms: shared message bus, task board and timeline | |

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