deer-flow/backend/docs/LOOP_DETECTION.md
Eilen Shin 25a744a99a
fix(harness): reflect progress in loop detection and plan todos (#8248)
* feat(frontend): improve file attachment recovery and artifact presentation

* feat(extensions): add Office artifact previews with search and navigation

* fix: preserve public viewers and HTTP Office previews

* fix: address file preview and upload review findings

* fix: use typed upload errors and linear bookmark allocation

* fix(office-preview): isolate parsing and bound preview resources

* fix(ci): install Office preview fixture dependencies for E2E

* fix(ci): provision matching Playwright browsers before E2E tests

* fix(ci): isolate Python libraries and include Office documentation

* test(frontend): wait for download status to finish rendering

* fix(harness): account for tool results in loop detection

* fix(harness): make tool frequency detection observational

* fix(harness): support blocked and waiting plan todos

* style(harness): wrap overlong system prompt lines

* Improve loop detection and todo message formatting

Refactor middleware logic for handling repeated results and update messages for todo list.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Address plan progress and loop detection review

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
2026-11-19 08:09:43 +08:00

2.0 KiB

Loop detection lifecycle

LoopDetectionMiddleware owns call-pattern detection. Its place in the chain and audit contract are documented in the middleware guide.

Run-scoped state

Hash histories, frequency windows/counters, and frequency-metric reporting sets share a (thread_id, run_id) key. This gives a fresh budget to each user run when a compiled graph is cached and reused, while keeping one budget across repeated graph entries belonging to the same Gateway run (including hidden goal continuations). after_agent clears only transient pending warnings for its own scope, not those histories; the sync/async before_agent hooks remain topology-preserving no-ops and must not delete a sibling run's pending warning. Direct LangGraph embedders may omit context.run_id; that fallback is anchored to the invocation's shared Runtime.control object and mapped to an opaque generated ID, because LangGraph replaces Runtime per node and CPython can reuse freed object addresses. after_agent releases the anchor mapping, while the bounded map covers abnormal exits. The compatibility-named max_tracked_threads limit bounds run scopes, and reset(thread_id) clears every retained run scope for that thread.

Decision ordering

Hash-based loop decisions are evaluated before the frequency metric is updated. A hash warning does not prevent the remaining tool names in the same response from being counted. Frequency thresholds only emit INFO metrics with action="observe_only"; they never enqueue a model warning, strip tool calls, or set a stop reason. The hash warning and hard-stop behavior remains scoped to identical calls whose results show no progress.

The lead agent applies the subagent call limit before loop detection, so the detector reconciles results against the admitted batch. A successful write_file or str_replace invalidates the predicted result for older reads of the same path. The next read observes the current version and completed results remain in the repetition window.