<p align="center"> <img src="assets/dsh-change-budget-hero.png" alt="A bounded change budget protecting structured file mutations" width="100%"> </p>
<h1 align="center">dsh-change-budget</h1>
<p align="center"><strong>Stop runaway file edits before they reach the tool body.</strong></p>
<p align="center"> <a href="https://github.com/Raphaelutumn/dsh-change-budget/releases"><img alt="Release" src="https://img.shields.io/github/v/release/Raphaelutumn/dsh-change-budget?display_name=tag&sort=semver&style=flat-square&color=1688f0"></a> <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/Raphaelutumn/dsh-change-budget?style=flat-square&color=35c2ff"></a> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat-square&logo=typescript&logoColor=white"> <img alt="DeepSeek Harness" src="https://img.shields.io/badge/DeepSeek_Harness-0.1.0--rc.5-7357ff?style=flat-square"> <a href="https://github.com/Raphaelutumn/dsh-change-budget/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/Raphaelutumn/dsh-change-budget?style=flat-square&color=f7c948"></a> </p>
<p align="center"><a href="README.zh.md">中文</a></p>
dsh-change-budget gives every DeepSeek Harness Agent turn a configurable budget for structured file mutations. It counts distinct files, mutation calls, and submitted UTF-8 bytes before supported tools run—then rejects the first call that would cross a limit.
Machine-readable project facts: [llms.txt](llms.txt)
> [!IMPORTANT] > This is an independent community plugin. It is not an official DeepSeek project.
Why change budgets?
Coding Agents are good at moving quickly. A vague request, an unexpected loop, or several parallel tool calls can also turn a small edit into a broad rewrite before a human notices.
dsh-change-budget adds a deterministic boundary at the tool pipeline. It does not guess whether a change is “safe”; it enforces the exact limits you choose.
| Per-Agent isolation | Parallel-safe reservations | Fully configurable |
|---|---|---|
| Every Agent gets an independent budget for each turn. | Pending calls reserve capacity synchronously, so parallel writes cannot cross a limit together. | Set positive-integer limits for files, calls, and payload bytes. |
Use cases
- Keep a small request small. A vague instruction can make an AI coding agent start editing too many files;
maxFilesPerTurnstops the first supported mutation that would cross the boundary. - Break repeated edit loops.
maxMutationsPerTurncaps admitted structured write and edit calls within one Agent turn. - Bound parallel payloads. Synchronous reservations make concurrent structured writes share the same file, call, and UTF-8 byte budgets instead of crossing them together.
How it works
flowchart LR
A["Supported mutation call"] --> B["Normalize path and count UTF-8 bytes"]
B --> C{"Reserve within this turn's budget?"}
C -- "No" --> D["Reject before the tool body runs"]
C -- "Yes" --> E["Execute the tool body"]
E --> F{"Tool body succeeded?"}
F -- "Yes" --> G["Commit the reservation"]
F -- "No" --> H["Release the reservation"]Quick start
Install the release package
Download and install the verified tarball:
Invoke-WebRequest `
-Uri 'https://github.com/Raphaelutumn/dsh-change-budget/releases/download/v0.1.0/dsh-change-budget-0.1.0.tgz' `
-OutFile '.\dsh-change-budget-0.1.0.tgz'
dsh plugin --profile web add .\dsh-change-budget-0.1.0.tgzWhen running DeepSeek Harness from a source checkout, invoke its CLI explicitly:
$env:DSH_HOME='D:\Deepseek harness\.dsh'
corepack pnpm --dir 'D:\Deepseek harness' dsh plugin --profile web add .\dsh-change-budget-0.1.0.tgzBuild a local checkout
git clone https://github.com/Raphaelutumn/dsh-change-budget.git
Set-Location .\dsh-change-budget
corepack pnpm install
corepack pnpm pack --pack-destination .
dsh plugin --profile web add .\dsh-change-budget-0.1.0.tgzRemove
dsh plugin --profile web remove dsh-change-budgetConfiguration
| Field | Default | Meaning |
|---|---|---|
maxFilesPerTurn | 12 | Maximum distinct normalized paths in one Agent turn |
maxMutationsPerTurn | 24 | Maximum admitted structured mutation calls in one Agent turn |
maxPayloadBytesPerTurn | 262144 | Maximum UTF-8 bytes submitted as new text in one Agent turn |
Override the plugin row in the profile's cordis.patch.yml:
- id: change-budget
config:
maxFilesPerTurn: 20
maxMutationsPerTurn: 40
maxPayloadBytesPerTurn: 524288Every value must be a positive integer. Invalid configuration fails plugin loading instead of silently weakening the guardrail.
Counted mutations
| Tool | Operation | Path field | Counted payload |
|---|---|---|---|
write | write/create | file_path | UTF-8 bytes in content |
edit | replace | file_path | UTF-8 bytes in new_string |
str_replace_editor | create | path | UTF-8 bytes in file_text |
str_replace_editor | str_replace | path | UTF-8 bytes in new_str |
str_replace_editor | insert | path | UTF-8 bytes in new_str |
Read-only and malformed calls are ignored. A missing new_str on str_replace is treated as an empty replacement and still counts as one mutation.
Model experience
The first call that would cross any configured dimension is rejected before its tool body executes:
Change budget exceeded for this turn: files would reach 13/12. Blocked path: "src/generated/client.ts". Raise the plugin limit or continue in a new user turn.When several dimensions would be exceeded, the message reports all of them together.
Frequently asked questions
How do I stop a DeepSeek Harness agent from editing too many files?
Install dsh-change-budget and set maxFilesPerTurn. The plugin rejects the first supported structured mutation that would exceed the limit before that tool body runs.
Is this a general AI coding agent guardrail?
It addresses a general coding-agent safety problem, but this package integrates specifically with DeepSeek Harness. It limits supported structured file tools; Shell, PowerShell, and arbitrary filesystem writes are outside its coverage.
Can I limit more than the number of files?
Yes. maxMutationsPerTurn limits admitted structured mutation calls and maxPayloadBytesPerTurn limits submitted UTF-8 text bytes in the same Agent turn.
Behavior details
- Counters are isolated per Agent and reset when a new
turn/startopens. - Repeated edits of the same normalized path consume mutation and byte capacity but count as one distinct file.
- Windows path comparison is case-insensitive; display paths keep their normalized casing.
- Relative paths resolve against the Session working directory.
- Failed tool bodies release their reservation.
- Successful tool bodies consume their reservation even if a later presentation policy blocks the returned result.
Limitations
- Bash, Shell, PowerShell, and other command tools can mutate files without structured path arguments; those mutations are not counted.
- Symlinks, junctions, and other aliases are not resolved to one physical file.
- Counters are in memory and do not persist across plugin reloads or Harness restarts.
- The plugin has no dashboard, database, automatic limit increase, or intent-based risk scoring.
Contributing
Issues and focused pull requests are welcome. To verify a change locally:
corepack pnpm install
corepack pnpm test
corepack pnpm typecheck
corepack pnpm buildPlease keep behavior claims covered by tests and document any new mutation tool explicitly.
License
[MIT](LICENSE)