In the DSH (DeepSeek Harness) ecosystem, agent invocations of tools often lack fine-grained control. A seemingly harmless search tool may be called dozens of times in succession or return multi-megabyte result payloads, causing context bloat or resource waste. The jwilson411/dsh-tool-quota plugin is designed to solve this problem.

Plugin Overview

This is a DeepSeek Harness plugin whose core function is to limit call counts and returned result sizes per session and per tool name. Unlike silent truncation, the plugin throws explicit errors when limits are reached, forcing the system or developer to intervene.

  • Maintainer: jwilson411
  • License: MIT
  • Category: Model reasoning

Installation and Enablement

Installing this plugin requires using DSH plugin management commands. After installation, the plugin does not include any default limits; specific quota rules must be specified through the configuration file.

dsh plugin --profile default add github:jwilson411/dsh-tool-quota

Prerequisites:
* Node.js version must be >= 22.14.0
* The following peer dependencies must be satisfied: @deepseek-ai/cordis ^4.0.1 and @deepseek-ai/dsh-tools ^0.1.1-rc.2

Configuration

After installation, specific rules must be defined through the DSH configuration file (typically involving dsh.bundle.patch or related configuration). The configuration is a YAML structure whose top-level keys are tool names, or the wildcard * to define a default rule.

Each rule contains the following fields (all integers, minimum 0):

  • maxCalls: Limits the maximum number of times this tool may be invoked in a single session. Once the limit is reached, the Nth call is rejected directly.
  • maxResultBytes: Limits the maximum byte size (UTF-8) of the result returned by this tool. If the result exceeds this limit, the result is discarded and the call throws an error.

Configuration example:

- id: tool-quota
  config:
    arxiv_search:
      maxCalls: 8
      maxResultBytes: 32000
    "*":
      maxCalls: 40
      maxResultBytes: 64000

Rule Override Logic

  • Specific tools take priority: If a tool is explicitly specified in the configuration (such as arxiv_search), that tool uses its own rule and will not merge fields with the * rule.
  • Default rule: Tools not explicitly specified use the * rule.
  • Unlimited: If a tool is not listed in the configuration and no * rule exists, the tool is unrestricted.

Features

1. Session and Counting Mechanism

  • Per-session counting: Quotas belong to a session; when multiple agents share a process, they do not consume each other’s quotas. The session ID is taken, in priority order, from the sessionId passed at invocation, otherwise from the agent ID in the execution input, and finally defaults to default.
  • Per-tool counting: Each tool name has its own quota pool. For example, if the * rule sets maxCalls: 40, this means each individually unconfigured tool has 40 call opportunities, rather than all tools sharing 40 calls.
  • Rejected calls are not counted: Rejected calls are not recorded in the used counter.

2. Result Byte Limits

Byte limits are checked after tool execution. This means the call has already occurred (and may have incurred cost); the plugin’s role is to protect the conversational context by preventing oversized results from being passed to subsequent models. If a result cannot be measured (for example, a BigInt or circular reference), it is treated as exceeding the limit and an error is thrown.

3. Error Handling

The plugin throws two specific error types to facilitate branch-specific handling by the caller:

  • ToolQuotaCallsError: Call count exceeded.
    • Includes code, toolName, sessionId, count (the sequence number of the rejected call), used (number of calls already used), and maxCalls.
  • ToolQuotaBytesError: Result bytes exceeded.
    • Includes code, toolName, sessionId, byteLength, maxResultBytes, and reason (OVER_LIMIT or UNMEASURABLE).

4. Status Query Tool

The plugin registers a tool named tool_quota_status that enables agents to query the remaining quota for the current session. This tool takes no arguments and returns status information in JSON format, including the used count, maximum count, and remaining count for each tool.

{
  "plugin": "dsh-tool-quota",
  "sessionId": "agent-1",
  "tools": [
    {
      "name": "arxiv_search",
      "rule": "tool",
      "used": 3,
      "maxCalls": 8,
      "remaining": 5,
      "maxResultBytes": 32000
    }
  ]
}

Use Cases and Considerations

  • Resource control: Suitable for preventing a tool from being overused (such as search or database queries) and causing excessive system load.
  • Context protection: Suitable for preventing oversized files or long documents from being read by the model, which could lead to context overflow.
  • Note: This is not a budget system (no USD involved) and not a time limiter (no time windows involved). It only concerns the total amount within a single session.

Conclusion

jwilson411/dsh-tool-quota provides an enforced mechanism for controlling tool-use boundaries. Through explicit error throwing and session-level counting, it helps developers build more stable and controllable DeepSeek Harness agent applications.

  • GitHub repository: https://github.com/jwilson411/dsh-tool-quota
  • Plugin directory: https://www.skillhub.cn/plugins/jwilson411/dsh-tool-quota