Compatibility

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

Tools & surfaces

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

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.0-rc.6 types (no paths)
pnpm test           # vitest: 45 tests
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 29 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

License

Apache License 2.0 © 2026 dsh-budget contributors