dsh-loop-brake

A DeepSeek Harness function plugin: a circuit breaker for identical tool calls.

An agent gets stuck. It calls search with {"q":"weather"}, reads the result, decides it needs to call search with {"q":"weather"}, and does. Nothing is wrong with any single call, so nothing stops it, and the loop runs until a budget, a turn limit, or a human notices.

This plugin notices on the third one.

LoopBrakeError: loop brake: tool "search" called 3 times in a row with identical
arguments (call 9f2c1a7b3e04…, limit 3); the call was denied before it ran.
Change the arguments, call a different tool, or stop.

The tool body does not run. The error carries code: 'LOOP_BRAKE', the count, the limit, and twelve hex characters of the call hash, so the denial is legible in a log without the arguments themselves being copied into one.

What it is not

This is not an LLM similarity judge. It is not embeddings, not a fuzzy match, not a semantic "are these two calls basically the same" question put to a model, not a workflow engine, and not a second agent loop watching the first one. There is no model call anywhere in this package and no threshold to tune.

Exact hash match only. Two calls are the same call when

sha256(toolName + "\n" + canonicalJson(args))

produces the same digest, and are different calls otherwise. Canonicalization sorts object keys at every nesting level and nothing else — so {"a":1,"b":2} and {"b":2,"a":1} are one call, and {"q":"weather"} and {"q":"weather "} are two.

That boundary is worth stating plainly, because it decides what this catches:

• An agent repeating a call byte for byte — caught, on the Nth try.
• An agent looping while a timestamp, a nonce, a page cursor, or a retry counter changes in its arguments — not caught. Every call hashes differently, and this plugin has no opinion about whether they mean the same thing.
• An agent alternating between two calls forever — not caught. The counter is a consecutive-repeat streak, so A, B, A, B never reaches three of anything.

A brake that fired on "these look similar" would need a model to decide what similar means, which is a model call in front of every tool call in the composition, with a false-positive rate and a bill. The exact-match version costs microseconds, cannot hallucinate, and is explainable to whoever reads the denial at three in the morning. It catches the single most common shape of a stuck agent and it is honest about the rest.

Install

dsh plugin --profile default add github:jwilson411/dsh-loop-brake

The installer reads dsh.bundle.patch from the package manifest and appends this package to the profile's ordered bundle list. Its cordis.patch.yml carries one insert row, id: loop-brake, with no config — the defaults.

Pin the tools package at 0.1.1-rc.2; that is the release candidate this plugin is developed and tested against.

Configure

One knob, in the plugin's row in the composed patch:

- id: loop-brake
  config:
    maxRepeats: 5

Key	Default	Meaning
maxRepeats	3	Consecutive identical calls a session may make before the next one is denied. Counting includes the denied call, so at 3 two identical calls run and the third is refused.

Must be an integer of at least 1. An unusable value is rejected when the plugin applies, not at the first call: a brake with different teeth than the one a profile asked for is discovered, if ever, only when a loop is already burning tokens. 1 denies every repeat immediately, including the first call of any streak — a debugging setting rather than a deployment one.

The environment fallback DSH_LOOP_BRAKE_MAX_REPEATS is read only when the config key is absent. The patch row is the deployment's stated intent, so it wins over an ambient variable.

An id-targeted patch replaces the row's whole config rather than merging into it, so an override must restate every field it means to keep.

Counting

Counts are per session, and per session the plugin keeps one current hash and one count — a streak, not a histogram.

• Call A, A → the streak is at 2.
• Call B → the A streak is gone; B is at 1.
• Call A → back to 1, not 3.

Two sessions never share a count: two agents legitimately making the same call are not one agent looping. A session is the explicit sessionId a caller passes, else the calling agent's id from the execution input, else default.

Memory does not grow with session length — one slot per session, not one entry per distinct call ever made.

The error

error.code       // 'LOOP_BRAKE'
error.toolName   // 'search'
error.count      // 3 — which consecutive repeat this was, counting this call
error.maxRepeats // 3
error.hashPrefix // '9f2c1a7b3e04' — the first 12 hex characters, and no more
error.sessionId  // the session whose streak tripped
error.plugin     // 'dsh-loop-brake'

LoopBrakeError is thrown, not returned. A brake a caller can drive past by ignoring a return value is not a brake, and the failure this exists to stop is precisely the case where nobody is reading return values carefully.

The arguments are never put in the error. They are the thing most likely to hold a path, a query, or a credential the caller passed in, and the error message is the thing most likely to be logged, shown, or handed back to a model.

How it attaches

apply patches the injected tool registry in two places and returns the LoopBrake instance, so a host that wants to inspect or reset it can.

• ctx.tools.register is patched, so every definition registered for the lifetime of this fiber carries a braked execute. This is the mandatory path and the only one this plugin assumes exists.
• ctx.tools.execute is patched when the runtime exposes it, which catches what the register patch cannot: a tool registered before this plugin applied.

One host call passing through both seams is counted once, keyed by its call id. A pair of wrappers that both counted would bite at half the configured limit.

Both patches are undone on dispose, so stopping or reloading the plugin leaves the registry exactly as it was found — and forgets every streak, which is the right default. A brake that remembered across a reload would deny the first call of a fresh run for something the previous run did.

No tool is registered. This plugin adds nothing to the model's tool surface. A brake the model can call is a brake it can be talked into arguing with, and there is nothing a status tool could report that the denial does not already say.

Using the library directly

The counting half is exported on its own for a host that owns its call sites:

import { LoopBrake, decorateTool, wrapExecute } from 'dsh-loop-brake/loop-brake'

const brake = new LoopBrake({ maxRepeats: 3 })

// Wrap one execute…
const guarded = wrapExecute(execute, brake, { tool: 'search', sessionId: 's1' })

// …or copy a whole definition with its execute braked.
const braked = decorateTool(definition, brake)

decorateTool returns a copy; the original definition is left alone. Also exported: callHash, canonicalJson, hashPrefix, sessionKey, normalizeMaxRepeats, resolveMaxRepeats, LoopBrakeError, InvalidMaxRepeatsError.

Dependencies

None at runtime. The shipped source imports node:crypto and nothing else — it opens no socket, reads no file, and spawns no process, all of which the test suite asserts rather than promises. @deepseek-ai/cordis and @deepseek-ai/dsh-tools are peer dependencies, provided by the harness.

Node >=22.14.0.

Tests

npm install
npm test

No network, no credentials, no model weights. CI runs the same suite on Node 22.x and 24.x.

License

MIT. Copyright (c) 2026 jwilson411.