Related to #7811 (open, circuit breaker + LLM fallback) and #14059 / #12632 (closed, same feature with dirty branches). Files changed here also include many unrelated modules (banner, skin_engine, tips, browser tests, TUI theme) — appears to be a dirty branch.

Thanks for the review, @alt-glitch!

I've rebased the branch onto latest upstream/main and force-pushed a clean set of 3 commits. The PR now only contains the circuit-breaker changes in run_agent.py (+296 lines).

The i18n changes have been moved to a separate branch and will be submitted as a separate PR.

Regarding related issues:

• feat: circuit breaker and LLM fallback engine #7811 (circuit breaker + LLM fallback): This PR implements the LLM fallback approach described there — using the compression model to judge looping behavior, with a self-reflection fallback for users without a compression model configured.
• feat: circuit breaker for infinite tool-call loops #14059 / fix: add circuit breaker for infinite tool-call loops #12632 (closed): Superseded by this PR. The original approach used hard-coded parameter hash matching; this version uses language model judgment instead, which avoids false positives (e.g., reading a large file in chunks).

The PR is now ready for review.

Hey @gzsiang, nice work on the circuit breaker concept! The compression-model-as-judge approach is clever. A couple of things I noticed:

1. function_result is undefined at the call site (will crash at runtime)

In _invoke_tool, the failure check is placed before the tool dispatch:

# Circuit breaker: track consecutive calls (before execution)
...
_cb_retry_msg = self._check_tool_failure(function_name, function_result)  # ← function_result not yet defined
if _cb_retry_msg is not None:
    return json.dumps({"error": _cb_retry_msg}, ensure_ascii=False)
if function_name == "todo":  # tool execution starts here

At this point function_result hasn't been assigned, so this raises NameError whenever the circuit breaker is enabled. The comment says "After execution" but the code sits above the dispatch block. Possibly the intent was to call _check_tool_failure after each tool returns?

2. Failure detection is inactive in sequential mode

In _execute_tool_calls_sequential, only the consecutive-call counter is incremented — _check_tool_failure is never called there. So Layer 2 (failure retry detection) silently does nothing in sequential execution, while the counter grows unboundedly.

3. Minor: _get_consecutive_suggestion / _try_auxiliary_model_consecutive appear unused

I don't see them called anywhere in the diff — they may be dead code.

Hope this helps!

The two-layer design is thoughtful: compression model as primary judge, main model self-reflection as fallback. This avoids a circular dependency where the main model would need to judge its own looping behavior.

1. Threshold calibration: consecutive_threshold: 5 and failure_threshold: 5 are hardcoded defaults. Have these been validated against any real production traces? The difference between "consecutive" and "cumulative" threshold matters significantly.

2. State persistence: When a circuit opens, is the state persisted across agent restarts? If the agent restarts, does the circuit automatically reset to "closed," potentially allowing the same looping pattern to immediately recur?

3. Compression model availability: If the configured compression model is unavailable, the fallback is main model self-reflection. But self-reflection is itself a call that could loop. Is there a depth limit on the reflection chain?

4. Disabled by default: The config-gated design is good. Has there been consideration of an opt-out for the compression model judgment specifically, separate from the circuit breaker enable flag?

Clean single-file implementation. Worth merging with documentation.

Thanks for the thorough review, @liuhao1024! All three issues are now fixed in the latest commit:

1. NameError fix — Removed the misplaced _check_tool_failure() call that sat above the tool dispatch in _invoke_tool() (where function_result was not yet defined). The call is now placed correctly after handle_function_call() returns, so function_result is always available.

2. Sequential path now active — Added a _check_tool_failure() call in _execute_tool_calls_sequential(), right after _detect_tool_failure() and before the result is appended to messages. Layer 2 failure detection is now functional in sequential mode.

3. Dead code removed — _get_consecutive_suggestion() and _try_auxiliary_model_consecutive() were never called in the current implementation (the equivalent logic lives in _check_tool_loop()). Both methods have been deleted.

All circuit-breaker tests still pass (18 passed, 3 skipped). The 3 pre-existing failures in test_concurrent_interrupt / test_real_interrupt_subagent are unrelated to this PR and already present on main.

@ether-btc Thanks for the thoughtful questions! Addressing each:

1. Threshold calibration
The default of 5 was chosen based on practical testing — it gives the agent enough room for legitimate retries (e.g., reading different sections of a large file, fixing parameters after an error) while still catching loops early. Importantly, Layer 1 (consecutive call check) does not hard-break at the threshold; it asks the auxiliary model to judge whether the calls are purposeful. The threshold only determines when to invite judgment, not when to block. Layer 2 (failure check) does hard-break, but that triggers only on actual failures, not on successful repeated calls.

Regarding consecutive vs cumulative: the current implementation is strictly consecutive — the counter resets when a different tool is called. This is intentional: cumulative counting would produce false positives on agents that legitimately use the same tool at different stages of a task.

2. State persistence across restarts
The counters (_consecutive_tool_calls, _tool_failure_count) are in-memory only — they reset on agent restart. This is by design: circuit breaker protects against loops within a single session. Cross-session persistence would introduce complexity (when to decay? how to handle context changes?) without clear benefit, since a restart implies a fresh session with different context.

3. Self-reflection depth / loop risk
The self-reflection fallback does not create a recursive call chain — it returns a text prompt injected into the current turn as a tool error message, not a new LLM invocation. However, there is a practical concern: weak or heavily-quantized models may ignore the self-reflection prompt, leading to a "soft loop" where the agent is told to stop but keeps going. The counter continues to increment, and on the next threshold crossing the same self-reflection message is returned, which the model may again ignore. This is an inherent limitation of self-reflection on low-capability models — the auxiliary model judgment path avoids it entirely.

4. Separate opt-out for compression model judgment
Currently not supported — enabled: true activates both layers together. However, the architecture makes this easy to add: a single boolean config (e.g., use_auxiliary_judgment: false) would skip the call_llm step in _check_tool_loop and go straight to the self-reflection fallback. The main use case would be users who have a compression model configured but don't trust its judgment (e.g., a weak local model producing too many false positives). I'd suggest adding this in a follow-up PR rather than bloating the initial implementation.

Appreciate the review! 🙏

Circuit Breaker Redesign: From Loop Detection to Suggestion-Based Break

This commit significantly refactors the circuit breaker, shifting from a loop detection model to an auxiliary model suggestion mechanism.

Core Changes

1. Phase 1 bug fix
Fixed a bug in : when tools return JSON with format, is a value rather than a key. The JSON key check never matched and returned early without falling back to non-JSON text pattern matching. Now it properly falls through to text pattern checks (e.g., , , etc.) when JSON key conditions are not met.

2. Phase 2 redesign: from detector to breaker

• Old behavior: asks auxiliary model is this a loop? -> answer yes/no -> if yes, returns STOP
• New behavior: asks auxiliary model to directly suggest an alternative approach -> main LLM executes it -> breaks the deadlock
• Auxiliary model increased from 10 to 1024
• Added parameter so the auxiliary model can see the last call arguments

3. Fixed auxiliary model response parsing
Reasoning models like Qwen3.5 output responses in instead of . The old code only read , causing the auxiliary model to always return empty suggestions. Now both fields are checked.

4. All circuit breaker messages localized to Chinese

Test Results

Setup: Hermes Agent + Qwen3.6-35B-A3B (main model, IQ4_XS quantized) + Qwen3.5-4B (auxiliary model)

Scenario: The main model was stuck in a loop repeatedly calling with persistent errors during an HTML parsing task.

Actual session log excerpt:

Key finding:

• Even when the 4B auxiliary model's suggestions are not perfectly accurate, the act of providing a suggestion alone is sufficient to break the main LLM's reasoning deadlock
• The main model acts on the suggestion, receives new feedback during execution, and naturally returns to productive work
• The IQ4_XS quantized main model can now complete tasks without getting stuck in unproductive tool loops

After extensive real-world usage, I've found a number of issues that need addressing, and the feature's use case is quite niche. I don't plan to maintain it going forward. Closing this PR.