Introduction

In DeepSeek Harness, a single Prompt invocation may expand into a large session tree through recursive calls by Subagents. While this structure can handle complex tasks, it can also lead to rapid expenditure: a single session may generate a large number of model requests in a short period, or search and delegation operations across the tree may consume a large amount of API quota.

Without independent controls specifically targeting the session tree, it is difficult for developers to stop the damage in time before the tree structure runs out of control. dsh-session-budget-guard is designed to solve this problem. It acts as a “circuit breaker” at runtime to ensure that the total expenditure and spending rate of the session tree remain within controllable limits.

Plugin Overview

  • Name: dsh-session-budget-guard
  • Position: Session-tree-level budget and spending-rate circuit breaker for DeepSeek Harness
  • Maintainer: erya2000
  • Category: admin-security
  • License: MIT

Core Features

This plugin mainly provides the following control capabilities:

  1. Spend Monitoring: Monitors the cumulative spend and spending rate across the entire session tree (root node + all Subagents).
  2. Circuit Breaker Rejection: Rejects the next model request or delegation operation when cumulative spend or spending rate exceeds the configured limits.
  3. Structural Limits: Limits tree depth, node count, and search count to prevent excessive quota-consuming delegation or search.
  4. Administrative Controls: Managed through logging and notification mechanisms.
  5. Custom Notifications: Supports custom notification commands via Shell templates.

Installation and Configuration

Installation

Use the official installation command to add the plugin to the specified Profile:

dsh plugin --profile web add github:erya2000/dsh-session-budget-guard

Alternatively, use it via local mounting (no installation step required) by configuring the path in cordis.patch.yml:

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

Configuration Example

All configuration options are optional; refer to the source code defaults for specific parameters. The following is a configuration example that enables enforcement (enforce) mode:

config:
  mode: enforce
  treeWarnCny: 5
  treeStopCny: 10
  maxDelegationDepth: 1

Applicable Scenarios and Considerations

Use Cases

Suitable for scenarios that require strict control of the cost of a single Prompt invocation or that need to prevent unbounded recursive expansion of Subagents.

Key Considerations

  1. In-Process Operation: This is an in-process guard plugin. Once the Harness process restarts, accounting data is not restored, and previous budget records will be lost.
  2. Mode Differences: The default mode is notify (logging and notifications only). If enforce mode is enabled, the plugin directly cancels the session and rejects requests, which may interrupt running tasks. It is recommended to observe logs in notify mode first, adjust the thresholds, and then enable enforce.
  3. Rate Limit Dependency: Rate limiting requires at least one prior sample value. Therefore, the first time window after the plugin is loaded may not trigger rate limiting, but cumulative spend and structural limits remain effective.
  4. Branch Exclusion: Regular branches (origin=fork) are intentionally excluded from tree statistics and do not count against budget limits.
  5. Environment Requirements: Node.js version 20 or later is required.

Summary

dsh-session-budget-guard provides financial and structural safeguards for multi-agent collaboration in DeepSeek Harness. By setting dual circuit breaker thresholds for cumulative spend and spending rate, it can effectively avoid spikes in API consumption caused by uncontrolled tree expansion. For more details and source code, see the SkillHub Plugin Catalog or the GitHub repository.