[Proposal] HarnessGuardMiddleware: Pre-write syntax validation, error diagnosis, and anti-doom-loop guard

[Yakyou7]

Background & Motivation

When agents execute complex, multi-turn coding and execution workflows within DeerFlow's sandbox, two frequent failure modes degrade agent reliability and waste LLM token budgets:

1. Pre-write Syntax Corruption: An LLM occasionally generates corrupted syntax (e.g. malformed AST in Python or invalid JSON) during write_file or str_replace. When written directly to the sandbox filesystem, these files cause subsequent tool executions (e.g. bash script execution) to crash with syntax errors, triggering avoidable multi-turn recovery cycles.
2. Error Doom Loops (Repetitive and Oscillating Failures): When a tool execution fails with a classic error signature (such as ModuleNotFoundError, missing dependency, or invalid syntax), the agent may repeatedly attempt identical or alternating failing commands without addressing root causes.

While LoopDetectionMiddleware exists in core to perform exact-call input hash frequency counting with hard-stop tool stripping, there is currently no pre-write syntax gate or semantic error diagnosis mechanism in the inner tool execution loop.

Design Goals & Proposed Capability

We propose HarnessGuardMiddleware, designed to operate alongside ReadBeforeWriteMiddleware in the agent tool execution pipeline:

1. Pre-Execution Syntax Validation Gate (Write-Verify):

   • Intercepts writes to .py (via ast.parse) and .json (via json.loads) before disk I/O.
   • Preserves standard write_file append-in-chunks patterns by distinguishing incomplete code fragments awaiting subsequent chunks (codeop.compile_command, premature EOF detection) from genuine syntax errors.
   • Supports atomic str_replace splicing validation with native CRLF/LF line ending normalization (_match_line_endings).
   • Blocks invalid writes with normalized ToolMessage (deerflow_tool_meta stamped) and actionable syntax error line numbers, keeping corrupted code out of the sandbox.

2. Targeted Remediation Hint Injection:

   • Diagnoses classic error signatures (MODULE_NOT_FOUND, COMMAND_NOT_FOUND, FILE_NOT_FOUND, SYNTAX_ERROR, PERMISSION_DENIED, PORT_IN_USE) from tool failure outputs (status == "error").
   • Injects concise, actionable remediation hints directly into the ToolMessage to steer the model out of confusion.

3. Anti-Doom-Loop & Oscillation Detection:

   • Tracks recent execution history scoped per (thread_id, run_id) using BoundedDict.
   • Warns when identical error signatures repeat consecutively or when alternating failing tool loops ($A \to B \to A \to B$) occur.

Implementation & PR

An implementation with comprehensive unit tests and regression coverage is proposed in PR #7624.
We welcome community feedback on the architecture, placement, and configuration defaults.