[yuhengcai1]

HUMAN:

---

AGENT:

Why

Valid custom stuck-detection thresholds can silently disable their detector when the bounded scan cannot hold the required history. An action-observation threshold of 12 requires 24 events. Large alternating-pattern, error-recovery, and monologue thresholds have the same problem.

The current main also widens error history for parallel tool calls (#6278). Both changes must compose: with an action-error threshold of 12 and two failing calls per response, 13 responses plus the corrective nudge require 53 events. Adding the parallel increment to the old 20-event base only provides 46.

Summary

Size the bounded active-branch scan from the configured thresholds, including the extra error response and nudge and the corrective messages accompanying monologues. Use the configured error window as the base for upstream's parallel-call expansion. The default base remains 20 events.

The merge preserves #6278's validation-error matching and response-counted error streaks. Native regressions explicitly opt into ThinkTool because current main no longer includes it by default.

Companion documentation: OpenHands/docs#1010 (matching branch).

Issue Number

No existing issue found for this configuration limit. This follows the bounded-history optimization in #1829 and is independent of #6235, #6236, and #6237.

How to Test

LITELLM_LOCAL_MODEL_COST_MAP=True uv run --frozen pytest \
  tests/cross/test_stuck_detector.py \
  tests/cross/test_stuck_detector_config.py \
  tests/cross/test_validation_loops.py \
  tests/sdk/conversation/local/test_stuck_detector_nudge.py \
  tests/sdk/conversation/local/test_stuck_detector_window.py -q

uv run pre-commit run --files \
  openhands-sdk/openhands/sdk/conversation/stuck_detector.py \
  tests/sdk/conversation/local/test_stuck_detector_window.py

Verified against main c048a1eb82353b0586f3ce600708394a68ebb246:

• The seven-case native window suite has 5 failed, 2 passed with the exact main detector. All other runtime files match main.
• Keeping the threshold-aware scan but using 20 as the parallel-error base still fails the new threshold-12/two-call regression.
• The resolved implementation has 66 passed across the command above, including all seven window cases and upstream validation-loop regressions. Applicable pre-commit checks and git diff --check pass.

Repeated-success and alternating runs stop at 12 calls. The single-call error run emits one nudge after failure 11 and stops at failure 12. The parallel run emits one nudge after 12 responses (24 errors) and stops after response 13 (26 errors). The monologue run stops after 12 empty assistant responses, accounting for accompanying environment messages. Below-threshold runs and new-user-message resets remain valid.

Environment: macOS arm64, Python 3.13.17, committed uv lock. Only model responses are scripted with TestLLM; Agent, ThinkTool execution/validation, event creation, and Conversation.run() are real. No paid inference or model-behavior benchmark was run. The scan remains a bounded heuristic; this does not promise arbitrary-history or arbitrary-period loop detection.

Video/Screenshots

Non-visual change; native before/after results are above.

Design Doc

Small bounded-window correction; no separate design document.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

Larger configured thresholds inspect proportionally more history. Public defaults, event serialization, and upstream matching rules remain unchanged. The TypeScript implementation already scans the full post-user history and does not have this fixed-window limit.

The HUMAN section is reserved for the contributor. The agent-behavior evaluation requires the integration-test label; no real-model benchmark was run locally.

[github-actions]

  ✅ **PR Artifacts Cleaned Up**

  This PR no longer adds or changes files under `.pr/`.