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.

Attribution

scopeBy: session          # deployment (default) | session | user
perScopeLimitUsd:
  'system:compaction': null    # unlimited — overhead must never block the agent
  'user:alice': 100

session uses GenerateOptions.sessionId, which dsh genuinely provides.

user needs a mapping dsh cannot supply — there is no user identity at the
llm seam. So it is given, never guessed:

• userEnv: 'DSH_USER' — one dsh instance per user
• sessionUsers: { <sessionId>: 'alice' } — an operator-supplied map

An unattributable call lands in user:unattributed. It is never charged to
whoever happens to be handy — a chargeback report that invents attributions is
worse than one that admits gaps.

System overhead is separated. Compaction and session-title calls carry a
purpose and are billed to system:*, so background work can never exhaust a
person's budget. Give them a null limit so they cannot be blocked.

Known limitations

• Per-user requires operator setup — see Attribution above. dsh has no user
  concept at the llm seam, so nothing can infer it.
• Unknown models price as $0 rather than crashing. Add them to rates.
• Pricing tables are yours to maintain; providers change rates.

Test

npm test   # 29 checks: pricing, drift, periods, durability, decisions, attribution

MIT. Not affiliated with DeepSeek AI.