hermes-agent/agent/tool_fixation_detector.py

"""Tool fixation detection — break repetitive tool calling loops.

Detects when the agent latches onto one tool and calls it repeatedly
without making progress. Injects a nudge prompt to break the loop.

Usage:
    from agent.tool_fixation_detector import ToolFixationDetector
    detector = ToolFixationDetector()
    nudge = detector.record("execute_code")
    if nudge:
        # Inject nudge into conversation
        messages.append({"role": "system", "content": nudge})
"""

from __future__ import annotations

import os
from dataclasses import dataclass, field
from typing import Dict, List, Optional


# Default thresholds
_DEFAULT_THRESHOLD = int(os.getenv("TOOL_FIXATION_THRESHOLD", "5"))
_DEFAULT_WINDOW = int(os.getenv("TOOL_FIXATION_WINDOW", "10"))


@dataclass
class FixationEvent:
    """Record of a fixation detection."""
    tool_name: str
    streak_length: int
    threshold: int
    nudge_sent: bool = False


class ToolFixationDetector:
    """Detects and breaks tool fixation loops.

    Tracks the sequence of tool calls and detects when the same tool
    is called N times consecutively. When detected, returns a nudge
    prompt to inject into the conversation.
    """

    def __init__(self, threshold: int = 0, window: int = 0):
        self.threshold = threshold or _DEFAULT_THRESHOLD
        self.window = window or _DEFAULT_WINDOW
        self._history: List[str] = []
        self._current_streak: str = ""
        self._streak_count: int = 0
        self._nudges_sent: int = 0
        self._events: List[FixationEvent] = []

    @property
    def nudges_sent(self) -> int:
        return self._nudges_sent

    @property
    def events(self) -> List[FixationEvent]:
        return list(self._events)

    def record(self, tool_name: str) -> Optional[str]:
        """Record a tool call and return nudge prompt if fixation detected.

        Args:
            tool_name: Name of the tool that was called.

        Returns:
            Nudge prompt string if fixation detected, None otherwise.
        """
        self._history.append(tool_name)

        # Trim history to window
        if len(self._history) > self.window:
            self._history = self._history[-self.window:]

        # Update streak
        if tool_name == self._current_streak:
            self._streak_count += 1
        else:
            self._current_streak = tool_name
            self._streak_count = 1

        # Check for fixation
        if self._streak_count >= self.threshold:
            event = FixationEvent(
                tool_name=tool_name,
                streak_length=self._streak_count,
                threshold=self.threshold,
                nudge_sent=True,
            )
            self._events.append(event)
            self._nudges_sent += 1

            return self._build_nudge(tool_name, self._streak_count)

        return None

    def _build_nudge(self, tool_name: str, count: int) -> str:
        """Build a nudge prompt to break the fixation loop."""
        return (
            f"[SYSTEM: You have called `{tool_name}` {count} times in a row "
            f"without switching tools. This suggests a fixation loop. "
            f"Consider:\n"
            f"1. Is the tool returning an error? Read the error carefully.\n"
            f"2. Is there a different tool that could help?\n"
            f"3. Should you ask the user for clarification?\n"
            f"4. Is the task actually complete?\n"
            f"Break the loop by trying a different approach.]"
        )

    def reset(self) -> None:
        """Reset the detector state."""
        self._history.clear()
        self._current_streak = ""
        self._streak_count = 0

    def get_streak_info(self) -> dict:
        """Get current streak information."""
        return {
            "current_tool": self._current_streak,
            "streak_count": self._streak_count,
            "threshold": self.threshold,
            "at_threshold": self._streak_count >= self.threshold,
            "nudges_sent": self._nudges_sent,
        }

    def format_report(self) -> str:
        """Format fixation events as a report."""
        if not self._events:
            return "No tool fixation detected."

        lines = [
            f"Tool Fixation Report ({len(self._events)} events)",
            "=" * 40,
        ]
        for e in self._events:
            lines.append(f"  {e.tool_name}: {e.streak_length} consecutive calls (threshold: {e.threshold})")
        return "\n".join(lines)


# Singleton
_detector: Optional[ToolFixationDetector] = None


def get_fixation_detector() -> ToolFixationDetector:
    """Get or create the singleton detector."""
    global _detector
    if _detector is None:
        _detector = ToolFixationDetector()
    return _detector


def reset_fixation_detector() -> None:
    """Reset the singleton."""
    global _detector
    _detector = None