frozo-ai / dsh-budget

dsh-cost-gate

Spend enforcement for DeepSeek Harness — not another dashboard.

The dsh ecosystem has plenty of cost plugins. Every one of them measures: ledgers, statistics, heatmaps, balance widgets. They tell you what you spent after you spent it.

This one stops the call.

        ┌─ over budget? ──> throw, before a single token is billed
llm/stream waterfall ─┼─ past 80%? ────> silently route to the cheap model
        └─ fine? ────────> pass through, then meter the usage chunk

llm/stream is a cordis waterfall — the decision happens before next() runs, which is the only place enforcement can actually work.

Install

dsh plugin --profile web add github:frozo-ai/dsh-budget   # npm: dsh-cost-gate

- insert:
    - id: budget
      name: 'dsh-cost-gate/plugin'
      config:
        limitUsd: 50
        period: monthly          # daily | monthly | total
        softFraction: 0.8        # start downgrading at 80%
        downgradeModel: 'deepseek/deepseek-chat'
        storePath: '~/.dsh/spend.json'
        rates:                   # USD per MILLION tokens
          'deepseek/deepseek-chat': { input: 0.28, output: 0.42 }
          'anthropic/claude-3.5-sonnet': { input: 3, output: 15 }

Set dryRun: true to log decisions without blocking — roll out safely, then turn it on.

Design notes

Integer micro-dollars. Costs accumulate as integers, never floats. A test runs 10,000 calls and asserts zero drift, because this decides whether people get blocked.

Cache tokens are disjoint. Per dsh's TokenUsage contract, cacheRead and cacheWrite are not included in inputTokens, so they're added at their own rates rather than folded in.

Atomic ledger writes. Temp file plus rename — a torn write must not lose budget state.

UTC period boundaries, so a daily budget resets at a time everyone agrees on.

Fails open, deliberately. No limitUsd means metering only. Enforcement is opt-in: a budget plugin that accidentally blocks your whole team is worse than one that doesn't block at all.

Related work

PerryLink/dsh-budget covers similar ground — metering, caps, alerts, carbon estimates, a Settings tab. If you want dashboards and reporting, look there first. This plugin is narrower on purpose: it gates the llm/stream waterfall so an over-budget call is refused before it is billed, and does little else.

Known limitations

• Scope is the whole deployment, not per-user. Per-user attribution needs identity plumbed from the gateway down to the llm layer; dsh has no user concept at that seam yet. One budget per deployment still prevents the surprise bill, which is the thing people actually get hurt by.
• Unknown models price as $0 rather than crashing. Add them to rates.
• Pricing tables are yours to maintain; providers change rates.

Test

npm test   # 17 checks: pricing, drift, periods, durability, decisions

MIT. Not affiliated with DeepSeek AI.