dsh-session-budget-guard

English | 中文

A per-session-tree budget and burn-rate circuit breaker for DeepSeek Harness.

One prompt can fan out into a tree of subagents that all spend money at once. This plugin watches each tree — the root session plus every subagent descendant — and refuses the next model request (or the next delegation) when either the tree's total spend or its spend rate crosses a limit you set.

- insert:
    - id: session-budget-guard
      name: dsh-session-budget-guard

Why it exists

On 2026-09-16 a single session ("research a robot dog for the farm") fanned out three levels deep: 3 subagents, then 14, then 28 — 3 494 model calls in 20 minutes, 2 266 of them web searches. It cost ¥82 and drained the API balance; the Harness had no per-session budget, and a cumulative budget alone would have been too slow to matter, because the tree was spending roughly ¥4/minute.

That is why there are two independent gates: cumulative spend and spend rate.

Install

dsh plugin --profile web add dsh-session-budget-guard     # npm (once published)
dsh plugin --profile web add github:erya2000/dsh-session-budget-guard

Or mount it by path from a local checkout (no install step):

# ~/.dsh/cordis.patch.yml
- insert:
    - id: session-budget-guard
      name: /absolute/path/to/dsh-session-budget-guard/lib/index.js

Restart the Harness once after installing (patch layers apply live, but the first mount of a new package needs a boot).

Configuration

Every key is optional; the defaults live in lib/rules.js. Unknown keys are logged and ignored rather than silently dropped.

Key	Default	Meaning
mode	notify	notify = log + notify only. enforce = also refuse the next step, deny over-quota delegations/searches and stop the tree.
enabled	true	Master switch.
treeWarnCny	20	Warn once per tree at this cumulative spend.
treeStopCny	50	Stop the tree at this cumulative spend.
rateWarnPerMin	4	Warn when the tree grows faster than ¥4/min.
rateStopPerMin	8	Stop the tree when it grows faster than ¥8/min.
windowsSeconds	[60, 180]	Sliding windows used for the rate, in seconds.
maxDelegationDepth	null (off)	Deepest allowed subagent depth. 1 means subagents may not spawn subagents.
maxTreeNodes	null (off)	Most subagents allowed in one tree.
maxSearchesPerSession	null (off)	Most web_search/web_fetch calls allowed per session.
dailyWarnCny / dailyStopCny	100 / 300	Reported in warnings for the whole day across trees.
stopStreak	2	Consecutive over-limit checks before acting.
notifyCooldownSeconds	300	Minimum gap between notifications for the same tree.
notify	auto	auto (macOS: osascript), none, or a shell command template containing {text}.
exchangeRate	7.2	Used to convert the cost-meter ledger (USD) into CNY.
statePath / logPath	$DSH_HOME/state/...	Where persistent state and the log live.

A configuration tuned for enforcement (this is what the incident above led to):

config:
  mode: enforce
  treeWarnCny: 5
  treeStopCny: 10
  rateWarnPerMin: 1.5
  rateStopPerMin: 3
  maxDelegationDepth: 1
  maxTreeNodes: 6
  maxSearchesPerSession: 40

What it does when a limit is hit

1. agent/pre-step returns {kind:'reject'} — the next model request never happens, so a stopped tree stops costing money immediately.
2. tools/pre-execute returns {kind:'deny', reason} for a new subagent / subagent_fork / workflow call past the structure limits, or for a web_search/web_fetch past the quota. The reason is model-visible, so the agent adapts instead of retrying blindly.
3. Descendants are interrupted deepest-first, then the session turn is cancelled (keepInbox, so queued messages survive).
4. The event is written to the log, and a notification is sent.

In notify mode only step 4 happens.

Where the numbers come from

• If the dsh-cost-meter plugin is mounted, the guard reads its ledger through the costMeter service (complete history, user-edited prices; the ledger is USD and is converted with exchangeRate).
• Otherwise the guard prices calls itself from the llm/stream waterfall using DeepSeek list prices (peak/off-peak, Beijing time) — no dependency, but the totals start when the plugin loads.

Lineage (which session is whose subagent) is read from each session log's first record — id, parentSession, origin, delegationDepth — plus the live session store. Message content is never read.

Limits

• It is an in-process guard: it stops a tree that is running, it does not resurrect accounting after a Harness restart.
• notify mode is the default. Turning on enforce means the plugin will cancel a session; tune the thresholds to your own traffic first (run in notify for a day and read the log).
• Rate limits need at least one sample older than the window, so the first minute of a fresh guard cannot trip on rate — cumulative and structure limits still apply.
• Plain forks (origin=fork) are deliberately excluded from tree aggregation.

Tests

node --test

18 tests cover the rule engine (lineage, tree aggregation including cycles, sliding-window rate, threshold decisions, waivers, structure gates) and the plugin wiring against a fake host (reject/deny behaviour, search quota, own llm/stream accounting).

License

MIT