Preface¶

There are already many plugins in the DSH ecosystem that can tell you how much a target costs and how many tokens it used, but most of these plugins stop there: read-only, just display. Long-running tasks truly lack the next step—stopping the target when the budget is exhausted, rather than letting it continue auto-renewing. boom-10’s dsh-goal-budget fills this gap: it attributes session consumption to the goal and calls the official policy entry to block the goal when the limit is exceeded. Below is an introduction to what it actually does, and how to install and use it.

What is it¶

One-sentence positioning: Set a token / cost (and calculation time) limit for DSH’s long-running task goals; stop when exceeded, not just report a number.

Basic information comes from the README and package.json:

• Plugin name: dsh-goal-budget
• Maintainer: boom-10
• Category: Workflow
• Star: 0
• Version: 0.10.2, license MIT
• Runtime requirements: Node ≥ 22, DSH >=0.2.1-rc.5 <0.3.0

This gap has been explicitly acknowledged in DSH’s built-in code. The README for goal-round-driver states: its round limit is not a resource budget; token, currency, time, and other strategies are independent; session events “will not be attributed to the goal message” nor “mapped to the goal’s block code”. This plugin fills three gaps: attribution based on goalId + round, providing the third block code budget-exceeded in the tree, and adding calculation time budget in 0.8.0.

Core Features¶

Goal-level Attribution¶

The plugin doesn’t store its own ledger. It reconstructs attribution from session event logs: agent/inbox/claimed is the unique event that pairs a message with the turn it started, assistant/message carries turn and usage; based on this, it accumulates the consumption of each turn to the corresponding {goalId, round}. Restarting won’t cause double billing, nor will it reset to zero.

Blocking, Not Warnings¶

When the budget is exceeded, the plugin calls ctx.goals.block(), marking the goal as blocked and cancelling auto-renewal in a single call. The block reason is a stable code plus a readable description, e.g., budget-exceeded. Optional configuration onExceed: block | warn, warn mode only logs and does not block.

Unified Display and Judgment¶

A pill appears in the input box status bar; clicking it shows the spending breakdown. The pill doesn’t calculate money itself; it reads the same projection used for blocking decisions, so the numbers on the interface and the numbers used by the gate won’t diverge. There are two display states: when no limit is set, the panel prompts how to set it; after setting, a usage percentage appears on the right side of the title bar, and the pill grows a progress bar, turning amber at 80%, and red at 100%.

Calculation Time Budget¶

In addition to tokens and cost, you can also set a calculation time limit. Duration = sum of each round’s span (from turn/start to the last turn/end), rather than now - creation time, so a goal paused overnight won’t accidentally blow the budget; the trade-off is that idle time between rounds isn’t counted. Time uses SessionEvent.time, not Date.now(), so replaying the same log yields the same number. It was added in 0.8.0 and is not currently displayed on the pill.

Installation and Enablement¶

Installation commands are from the original README, two equivalent forms, choose based on your registry:

dsh plugin --profile desktop add dsh-goal-budget                 # npm source
dsh plugin --profile desktop add github:boom-10/dsh-goal-budget  # GitHub source

After installation, restart DSH (both client and host load during startup). Two points to note:

• If the local default registry is an internal corporate proxy and hasn’t synced to this package, add dsh-goal-budget will report ERR_PNPM_NO_VERSIONS, switch to the GitHub source.
• The versioned form is not available on both sources, do not write ...@0.10.0.

You can also search for “Goal Budget” in the open plugin marketplace to install (already indexed). It can be installed without any budget configured—the plugin will run idle until you use /budget to set values.

Configuration and Usage¶

Setting Limits within a Session¶

Type commands directly in the input box, no YAML editing, no restart:

/budget            View currently effective limits and usage
/budget $5         Set session cost limit to $5
/budget 500k       Set session token limit to 500k
/budget $5 500k    Set both, whichever comes first counts
/budget $5 30min   Set cost and calculation time, supports s / min / h
/budget off        Clear session override, revert to profile default

Time units use min instead of m because m is already used to represent millions of tokens. Budgets are parsed as “Session Override ?? Profile Default”: fixed quotas are written in the config, temporary tightening is done by typing a line in the input box.

Profile Defaults¶

YAML configuration for a fixed quota for all sessions, fields with comments:

- id: dsh-goal-budget
  config:
    budget:
      tokens: 2000000
      costUsd: 5.00
    onExceed: block        # or 'warn', only logs without blocking
    warnAtRatio: 0.8
    currency: auto                       # auto: use DeepSeek balance API (official line); gateway line write USD or CNY
    deepseekCredentialRef: DEEPSEEK_API_KEY   # Key reference name in credential service
    modelAliases: {}                     # Mapping when gateway renames models, e.g., cm-ais/deepseek-v5-flash: deepseek-flash
    peakPricing: false                   # Official line true; gateway charges fixed unit price when false (otherwise overestimates by double during peak hours)

The design of the two-layer interface is that budget is a runtime decision, while plugin configuration is a deployment decision read at startup; putting the budget only in the config means changing a temporary value requires editing YAML and restarting. Session-level budget matches session-level interface, which is why /budget exists.

Differences from Other Usage Plugins¶

Plugins reporting spending in the ecosystem are saturated, and all are read-only, e.g., @kenz1117/dsh-ui-usage-billing (billing dashboard, 95 stars), dsh-credits (tracking balance and plans), dsh-composer-balance (displaying balance). They answer “how much I spent”. This plugin answers “should I continue” and executes that answer.

Applicable Scenarios and Notes¶

Suitable for users who need to add hard budgets to long-running task goals and do not want to burn through quotas and stop themselves, especially scenarios configured with goal auto-renewal. The README also lists known failure modes that need to be understood as expected: if human messages and goal messages are mixed in a round, human consumption might be recorded to the goal, causing early blocking; the mitigation is strictly filtering source.kind === 'goal'.

The plugin runs with the permissions of the current DSH process; it will read events in the sessions you start, register commands, and call the blocking entry. It is recommended to read the source code (license MIT) before installation to confirm behavior matches expectations, especially if planning to use it as a default deployment strategy.

Ending¶

The value of dsh-goal-budget lies in turning “budget exceeded” from a number into an action: making the goal stop, rather than continuing to burn. It reuses DSH’s existing event and command mechanisms, doesn’t create a separate ledger, and shares the same projection for interface and judgment. If more fine-grained attribution rules or new budget dimensions are needed, it is suggested to start from the source code.

• Directory page: https://www.skillhub.cn/plugins/boom-10/dsh-goal-budget
• Source code: https://github.com/boom-10/dsh-goal-budget