📦 @goodandready/dsh-agent-loop-guard

⚡ Overview & Problem Solved

When autonomous AI coding agents encounter unexpected tool failures, ambiguous instructions, or hallucination loops, they often enter infinite retry cycles — repeatedly reading the same directory, editing identical lines without progress, or echoing identical output lines across streaming turns. These loops rapidly exhaust token budgets, lock execution threads, and waste API credits without ever completing user goals.

@goodandready/dsh-agent-loop-guard is a native host runtime plugin for DeepSeek Harness that intercepts and breaks loops before they spiral out of control:

1. Progress-Aware Tool-Call Guard: Employs epoch-based state tracking so that repeated calls are blocked only when no meaningful state changes or new evidence appear. Legitimate productive iterations (e.g. read ➔ edit ➔ read ➔ edit) remain fully unrestricted.
2. Assistant Output Loop Breaker: Detects text-only repetition (identical streaming lines or multi-line markdown blocks) across turns and steps, cleanly canceling runaway generation without damaging session history.
3. Answer-Only Graceful Fallback: Instead of terminating abruptly, the plugin triggers structured DSH denials that guide the LLM into answering with text explaining the bottleneck.
4. Zero Core Modifications: Implemented purely through Cordis lifecycle hooks (ctx.tools.guard, agent/pre-step, tools/execute, session/event).

🏗️ Architecture

graph TD
    subgraph DSH ["DeepSeek Harness Core Runtime"]
        Turn["Agent Turn Execution<br/>(LLM Reasoning & Tool Calls)"]
        Stream["Assistant Output Stream<br/>(text-delta & block-end)"]
        UserStop["User Message Analysis<br/>(Stop words: stop, halt, прекрати)"]
    end

    subgraph LoopGuard ["@goodandready/dsh-agent-loop-guard"]
        ToolInterceptor["ctx.tools.guard Interceptor<br/>(denyReason evaluation)"]
        ProgressEpoch["Progress Epoch Tracker<br/>(Result & Argument Fingerprints)"]
        OutputState["AssistantOutputGuardState<br/>(Line & Block Deduplication)"]
        SafeLogger["Sanitized Event Logger<br/>(Token/Secret Redaction)"]
    end

    subgraph Actions ["Enforcement Actions"]
        Allow["Allow Tool Execution<br/>(Fresh state or valid progress)"]
        Deny["Answer-Only Denial<br/>(Mandates text summary from agent)"]
        Cancel["Session Cancel<br/>(keepInbox: false on runaway text)"]
    end

    Turn -->|Pre-step & Tool call| ToolInterceptor
    ToolInterceptor --> ProgressEpoch
    ProgressEpoch -->|Productive Result Diff| Allow
    ProgressEpoch -->|Duplicate / Budget Exceeded| Deny
    Stream --> OutputState
    OutputState -->|Exceeds Line/Block Repeat Limit| Cancel
    UserStop -->|Immediate Latch| Deny
    Deny -.-> SafeLogger
    Cancel -.-> SafeLogger

✨ Full Feature Breakdown

1. Progress-Aware Tool Execution Tracking

Unlike naive counters that blindly limit tool invocations, dsh-agent-loop-guard distinguishes between productive iteration and stagnant loops:

• Canonical Fingerprinting: Creates deterministic JSON signatures of tool arguments (callFingerprint) and results (resultFingerprint).
• Progress Epochs: When an edit or command yields a different result, the session transitions to a new progress epoch, resetting the failure budget.
• Granular HTTP/VCS Safety: Distinct endpoints and HTTP methods (e.g., Gitea API operations or curl scripts) are never collapsed under a shared base URL.
• Progress Tool Whitelist: Designated progress tools (todo_write, etc.) maintain independent no-progress budgets so task checklists do not trigger false positives.

2. Guard Violation Codes & Enforcement Modes

When a loop is detected, the guard rejects the call with structured diagnostics and enforces Answer-Only Mode for the rest of the turn:

3. Assistant Output Stream Guard

Runaway LLM generation can manifest as repetitive narration without tool calls. The output guard monitors streaming text in real time:

• Line Normalization: Collapses carriage returns and whitespace to catch formatted repetition.
• Multi-Line Block Detection: Hashes blocks up to maxAssistantBlockChars (16,384 bytes) to detect cyclical paragraph generation.
• Active Tool Immunity: While tool calls are executing, output cancellation is temporarily suppressed to avoid false alarms during long tasks.
• Lossless Deduplication: Cleanses streaming chunks and message buffers without losing valid context.

4. Enterprise Privacy & Token Redaction

All loop guard warning logs automatically redact sensitive credentials:

• Bearer tokens, passwords, cookies, and query parameter secrets (token=, api-key=, secret=) are replaced with [redacted] before reaching logs.
• Deeply nested argument trees are bounded to prevent memory leaks during massive JSON payloads.

5. Native WebUI Settings, Telemetry & One-Click Updater

• Integrated Settings Card: Placed directly inside DSH Web UI under Settings ➔ Plugins ➔ Plugin Settings (settings.plugin.item, order 95).
• Native DSH Design System: Styled exclusively using standard DSH design variables (--dsw-alias-*), accessible <label>/<input> associations (htmlFor/id), and smooth chevron rotation without external UI dependencies.
• Live Protection Telemetry: Real-time counters of blocked loops (LOOP_GUARD_DUPLICATE, LOOP_GUARD_REPEAT, LOOP_GUARD_LIMIT, LOOP_GUARD_OUTPUT) with instant statistics reset via /api/@goodandready/dsh-agent-loop-guard/telemetry.
• One-Click In-Place Updater: Seamless version verification against the npm registry and one-click upgrades via authenticated loopback API (/api/@goodandready/dsh-agent-loop-guard/update).

📦 Installation

Install via DeepSeek Harness CLI:

dsh plugin --profile web add @goodandready/dsh-agent-loop-guard

Restart DSH Web UI and reload your workspace.

⚙️ Configuration

Configure via config.yaml or through the Web UI settings:

# config.yaml
dsh-agent-loop-guard:
  maxToolAttemptsPerTurn: 64
  maxProgressToolCallsPerTurn: 16
  progressToolNames:
    - todo_write
  maxCallsPerRepeatGroup: 5
  blockExactDuplicates: true
  assistantOutputGuard: true
  maxRepeatedAssistantLines: 5
  maxRepeatedAssistantBlocks: 5
  maxAssistantBlockChars: 16384

Settings Reference Table

🧪 Testing & Verification

Run the full automated test suite covering all loop denial paths, streaming output guards, and progress epochs:

npm test
npm run check

📄 License

• License: MIT © GooDAnDReaDY
• Changelog: Detailed release history and migration notes are maintained in CHANGELOG.md.