Introduction

When building agent trees in DeepSeek Harness (DSH), the root agent and its ephemeral, resumable subagents often consume tokens in parallel, easily exceeding per-conversation or global budget limits. The dsh-plugin-agent-budget plugin provides shared token budget management for these agent trees. It treats the entire agent tree as a single budget account, or accounts for each session independently, helping prevent uncontrolled token consumption.

Core Features

This plugin is maintained by winter-street and is an MIT-licensed open source project. Its core functionality focuses on token accounting and control for agent trees:

  1. Scope management: Supports treating the entire agent tree as one budget account (scope: tree), or allowing each session to use its own budget independently (scope: session).
  2. Separate storage: The ledger is stored in a plugin-owned sidecar directory ~/.dsh/agent-budget/ and is not written into session logs. This means uninstalling the plugin will not corrupt session data.
  3. Ledger behavior: Maintains an append-only, replayable, and recoverable log structure, ensuring data persistence and auditability.
  4. Model awareness: Provides a read-only budget_status tool so the model itself can proactively perceive remaining quota.
  5. No external dependencies: Runs as a pure local Bundle and does not rely on external services.

Installation and Configuration

The package is not currently published to npm, so it needs to be installed as a local package or Git dependency.

  1. Install the plugin:
    dsh plugin --profile <name> add dsh-plugin-agent-budget

Or use pnpm:

    pnpm add dsh-plugin-agent-budget
  1. Basic configuration:
    The plugin depends on the dsh.profile.bundles layer and is usually configured through cordis.patch.yml. maxTokens (a positive integer) is required.
    - insert:
        - id: agent-budget
          name: dsh-plugin-agent-budget
          config:
            maxTokens: 200000
            missingUsage: exhaust
            scope: tree

*   `maxTokens`: Limits the maximum number of tokens in the scope.
*   `missingUsage`: Defaults to `exhaust` (exhausted); if the provider does not return usage and you intentionally want to ignore it, set it to `ignore`.
*   `scope`: Defaults to `tree`. If set to `session`, each session is accounted for independently.

Scope and Semantics

The plugin determines the granularity and rules for token accounting based on its configuration:

  • Tree scope (scope: tree):
    • Prefers resolving the root node through DSH runtime agent ownership.
    • Falls back to the persisted parentSession chain if the runtime is unavailable.
    • If neither is available, it creates a standalone budget account with a warning.
    • The plugin does not merge unrelated sessions into the same account.
  • Session scope (scope: session):
    • Each session has its own independent budget, including subagents.
  • Accounting rules:
    • Includes all llm/stream calls with a sessionId (conversations, subagents, workflows, compression, and title generation).
    • Uncached input, cache reads, cache writes, and output are divided into four separate buckets.
    • Reasoning tokens are already included in output and are not counted again.

Control and Degradation

The plugin provides an optional control layer that intervenes proactively when budget limits are approaching, helping prevent overspending:

  • degradeRatio (0–1):
    When the remaining ratio in a scope falls below this threshold, subsequent calls are degraded. maxTokens is clamped to the remaining budget (minimum value is 1), and can be combined with maxOutputTokens to set a hard output cap.
  • pressurePrompt (defaults to true):
    When usage exceeds 50% and reaches 80%, a budget-pressure prompt is injected into the system prompt. This leverages the model’s own throttling ability to self-constrain before hitting hard limits.
  • maxConcurrentCalls:
    Limits the maximum number of concurrent provider calls allowed per scope. Calls exceeding the limit fail before dispatch with a TOKEN_BUDGET_CONCURRENT_LIMIT error.

API and Settings

The plugin includes a built-in local HTTP API and settings panel.

  • Settings panel:
    A “Token Budget” section is registered in the DSH settings page. It can list all open scopes, display progress bars, and allow adjusting limits or resetting usage without directly manipulating log files.
  • HTTP API (local):
    The server runs at /agent-budget/api and is limited to local access. Requests must include the X-Agent-Budget-Request: 1 header.
    • GET /scopes: Lists scopes and current usage.
    • POST /adjust-limit: Adjusts scope limits.
    • POST /reset: Clears usage for the specified scope.

Notes

  1. Experimental status: The plugin is currently experimental and has been validated against DSH 0.1.0-rc.6.
  2. Dependencies and builds:
    • Specific peer dependencies are required, such as @deepseek-ai/cordis and @deepseek-ai/dsh-agent.
    • When installing Git dependencies with pnpm >= 10, build scripts are blocked by default. Add allowBuilds: dsh-plugin-agent-budget: true to pnpm-workspace.yaml.
  3. Concurrent races:
    • Calls allowed concurrent admits may eventually result in usage exceeding the limit.
    • Once settled usage reaches the limit, subsequent calls fail before dispatch with TOKEN_BUDGET_EXHAUSTED.
  4. Data storage and uninstallation:
    • Data is stored in ~/.dsh/agent-budget/.
    • Uninstalling the plugin will not corrupt session logs, but to fully remove budget data, manually delete that directory.
    • Concurrent writes are rejected by the lock; corrupt logs or indexes will cause startup failure.

Summary

dsh-plugin-agent-budget provides fine-grained, persistent token budget management for agent trees in DeepSeek Harness. By configuring scope, enabling degradation strategies, or using model-side prompt intervention, you can build cost-controlled agent workflows. For more details, refer to the plugin directory or GitHub repository.