openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/conversation/stuck_detector.py

@@ -0,0 +1,311 @@
+from openhands.sdk.conversation.state import ConversationState
+from openhands.sdk.conversation.types import StuckDetectionThresholds
+from openhands.sdk.event import (
+    ActionEvent,
+    AgentErrorEvent,
+    CondensationSummaryEvent,
+    Event,
+    MessageEvent,
+    ObservationBaseEvent,
+    ObservationEvent,
+)
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class StuckDetector:
+    """Detects when an agent is stuck in repetitive or unproductive patterns.
+
+    This detector analyzes the conversation history to identify various stuck patterns:
+    1. Repeating action-observation cycles
+    2. Repeating action-error cycles
+    3. Agent monologue (repeated messages without user input)
+    4. Repeating alternating action-observation patterns
+    5. Context window errors indicating memory issues
+    """
+
+    state: ConversationState
+    thresholds: StuckDetectionThresholds
+
+    def __init__(
+        self,
+        state: ConversationState,
+        thresholds: StuckDetectionThresholds | None = None,
+    ):
+        self.state = state
+        self.thresholds = thresholds or StuckDetectionThresholds()
+
+    @property
+    def action_observation_threshold(self) -> int:
+        return self.thresholds.action_observation
+
+    @property
+    def action_error_threshold(self) -> int:
+        return self.thresholds.action_error
+
+    @property
+    def monologue_threshold(self) -> int:
+        return self.thresholds.monologue
+
+    @property
+    def alternating_pattern_threshold(self) -> int:
+        return self.thresholds.alternating_pattern
+
+    def is_stuck(self) -> bool:
+        """Check if the agent is currently stuck."""
+        events = list(self.state.events)
+
+        # Only look at history after the last user message
+        last_user_msg_index = next(
+            (
+                i
+                for i in reversed(range(len(events)))
+                if isinstance(events[i], MessageEvent) and events[i].source == "user"
+            ),
+            -1,  # Default to -1 if no user message found
+        )
+        if last_user_msg_index == -1:
+            logger.warning("No user message found in history, skipping stuck detection")
+            return False
+
+        events = events[last_user_msg_index + 1 :]
+
+        # Determine minimum events needed
+        min_threshold = min(
+            self.action_observation_threshold,
+            self.action_error_threshold,
+            self.monologue_threshold,
+        )
+        if len(events) < min_threshold:
+            return False
+
+        logger.debug(f"Checking for stuck patterns in {len(events)} events")
+        logger.debug(
+            f"Events after last user message: {[type(e).__name__ for e in events]}"
+        )
+
+        # Collect enough actions and observations for detection
+        max_needed = max(self.action_observation_threshold, self.action_error_threshold)
+        last_actions: list[Event] = []
+        last_observations: list[Event] = []
+
+        # Retrieve the last N actions and observations from the end of history
+        for event in reversed(events):
+            if isinstance(event, ActionEvent) and len(last_actions) < max_needed:
+                last_actions.append(event)
+            elif (
+                isinstance(event, ObservationBaseEvent)
+                and len(last_observations) < max_needed
+            ):
+                last_observations.append(event)
+            if len(last_actions) >= max_needed and len(last_observations) >= max_needed:
+                break
+
+        # Check all stuck patterns
+        # scenario 1: same action, same observation
+        if self._is_stuck_repeating_action_observation(last_actions, last_observations):
+            return True
+
+        # scenario 2: same action, errors
+        if self._is_stuck_repeating_action_error(last_actions, last_observations):
+            return True
+
+        # scenario 3: monologue
+        if self._is_stuck_monologue(events):
+            return True
+
+        # scenario 4: action, observation alternating pattern
+        if len(events) >= self.alternating_pattern_threshold:
+            if self._is_stuck_alternating_action_observation(events):
+                return True
+
+        # scenario 5: context window error loop
+        if len(events) >= 10:
+            if self._is_stuck_context_window_error(events):
+                return True
+
+        return False
+
+    def _is_stuck_repeating_action_observation(
+        self, last_actions: list[Event], last_observations: list[Event]
+    ) -> bool:
+        # scenario 1: same action, same observation
+        threshold = self.action_observation_threshold
+
+        # Check for a loop of identical action-observation pairs
+        if len(last_actions) >= threshold and len(last_observations) >= threshold:
+            logger.debug(
+                f"Found {len(last_actions)} actions and "
+                f"{len(last_observations)} observations, checking for equality"
+            )
+            actions_equal = all(
+                self._event_eq(last_actions[0], action)
+                for action in last_actions[:threshold]
+            )
+            observations_equal = all(
+                self._event_eq(last_observations[0], observation)
+                for observation in last_observations[:threshold]
+            )
+            logger.debug(
+                f"Actions equal: {actions_equal}, "
+                f"Observations equal: {observations_equal}"
+            )
+
+            if actions_equal and observations_equal:
+                logger.warning("Action, Observation loop detected")
+                return True
+        else:
+            logger.debug(
+                f"Not enough actions/observations: {len(last_actions)} actions,"
+                f" {len(last_observations)} observations"
+            )
+
+        return False
+
+    def _is_stuck_repeating_action_error(
+        self, last_actions: list[Event], last_observations: list[Event]
+    ) -> bool:
+        # scenario 2: same action, errors
+        threshold = self.action_error_threshold
+        if len(last_actions) < threshold or len(last_observations) < threshold:
+            return False
+
+        # are the last N actions the "same"?
+        if all(
+            self._event_eq(last_actions[0], action)
+            for action in last_actions[:threshold]
+        ):
+            # and the last N observations are all errors?
+            if all(
+                isinstance(obs, AgentErrorEvent)
+                for obs in last_observations[:threshold]
+            ):
+                logger.warning("Action, Error loop detected")
+                return True
+
+        # Check if observations are errors
+        return False
+
+    def _is_stuck_monologue(self, events: list[Event]) -> bool:
+        # scenario 3: monologue
+        # check for repeated MessageActions with source=AGENT
+        # see if the agent is engaged in a good old monologue, telling
+        # itself the same thing over and over
+        threshold = self.monologue_threshold
+        if len(events) < threshold:
+            return False
+
+        # Look for N consecutive agent messages without user interruption
+        agent_message_count = 0
+
+        for event in reversed(events):
+            if isinstance(event, MessageEvent):
+                if event.source == "agent":
+                    agent_message_count += 1
+                elif event.source == "user":
+                    break  # User interrupted, not a monologue
+            elif isinstance(event, CondensationSummaryEvent):
+                # Condensation events don't break the monologue pattern
+                continue
+            else:
+                # Other events (actions/observations) don't count as monologue
+                break
+
+        return agent_message_count >= threshold
+
+    def _is_stuck_alternating_action_observation(self, events: list[Event]) -> bool:
+        # scenario 4: alternating action-observation loop
+        threshold = self.alternating_pattern_threshold
+
+        last_actions: list[Event] = []
+        last_observations: list[Event] = []
+
+        # collect most recent N actions and N observations
+        for event in reversed(events):
+            if isinstance(event, ActionEvent) and len(last_actions) < threshold:
+                last_actions.append(event)
+            elif (
+                isinstance(event, (ObservationEvent, AgentErrorEvent))
+                and len(last_observations) < threshold
+            ):
+                last_observations.append(event)
+
+            if len(last_actions) == threshold and len(last_observations) == threshold:
+                break
+
+        if len(last_actions) == threshold and len(last_observations) == threshold:
+            # Check alternating pattern: [A, B, A, B, A, B] where even/odd match
+            actions_equal = all(
+                self._event_eq(last_actions[i], last_actions[i + 2])
+                for i in range(threshold - 2)
+            )
+            observations_equal = all(
+                self._event_eq(last_observations[i], last_observations[i + 2])
+                for i in range(threshold - 2)
+            )
+
+            if actions_equal and observations_equal:
+                logger.warning("Alternating Action, Observation loop detected")
+                return True
+
+        return False
+
+    def _is_stuck_context_window_error(self, _events: list[Event]) -> bool:
+        """Detects if we're stuck in a loop of context window errors.
+
+        This happens when we repeatedly get context window errors and try to trim,
+        but the trimming doesn't work, causing us to get more context window errors.
+        The pattern is repeated AgentCondensationObservation events without any other
+        events between them.
+        """
+        # TODO: blocked by https://github.com/OpenHands/agent-sdk/issues/282
+        return False
+
+    def _event_eq(self, event1: Event, event2: Event) -> bool:
+        """
+        Compare two events for equality, ignoring irrelevant
+        details like ids, metrics.
+        """
+        # Must be same type
+        if type(event1) is not type(event2):
+            return False
+
+        # For ActionEvents, compare the action content, ignoring IDs
+        if isinstance(event1, ActionEvent) and isinstance(event2, ActionEvent):
+            return (
+                event1.source == event2.source
+                and event1.thought == event2.thought
+                and event1.action == event2.action
+                and event1.tool_name == event2.tool_name
+                # Ignore tool_call_id, llm_response_id, action_id as they vary
+            )
+
+        # For ObservationEvents, compare the observation content, ignoring IDs
+        if isinstance(event1, ObservationEvent) and isinstance(
+            event2, ObservationEvent
+        ):
+            return (
+                event1.source == event2.source
+                and event1.observation == event2.observation
+                and event1.tool_name == event2.tool_name
+                # Ignore action_id, tool_call_id as they vary
+            )
+
+        # For AgentErrorEvents, compare the error content
+        if isinstance(event1, AgentErrorEvent) and isinstance(event2, AgentErrorEvent):
+            return (
+                event1.source == event2.source and event1.error == event2.error
+                # Ignore action_id as it varies
+            )
+
+        # For MessageEvents, compare the message content
+        if isinstance(event1, MessageEvent) and isinstance(event2, MessageEvent):
+            return (
+                event1.source == event2.source
+                and event1.llm_message == event2.llm_message
+            )
+
+        # Default fallback
+        return event1 == event2

openhands/sdk/conversation/title_utils.py

@@ -0,0 +1,191 @@
+"""Utility functions for generating conversation titles."""
+
+from collections.abc import Sequence
+
+from openhands.sdk.event import MessageEvent
+from openhands.sdk.event.base import Event
+from openhands.sdk.llm import LLM, Message, TextContent
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+categories = [
+    {"emoji": "💄", "name": "frontend", "description": "UI and style files"},
+    {"emoji": "👔", "name": "backend", "description": "Business logic"},
+    {"emoji": "✅", "name": "test", "description": "Tests"},
+    {"emoji": "👷", "name": "devops", "description": "CI build system"},
+    {"emoji": "🚀", "name": "deployment", "description": "Deploy stuff"},
+    {"emoji": "📦️", "name": "dependencies", "description": "Packages and dependencies"},
+    {"emoji": "🗃️", "name": "database", "description": "Database changes"},
+    {"emoji": "🔧", "name": "chores", "description": "Configuration and maintenance"},
+    {"emoji": "✨", "name": "features", "description": "New features"},
+    {"emoji": "🐛", "name": "bugfix", "description": "Bug fixes"},
+    {"emoji": "⚡️", "name": "performance", "description": "Performance improvements"},
+    {"emoji": "🔒️", "name": "security", "description": "Security fixes"},
+    {"emoji": "📝", "name": "documentation", "description": "Documentation"},
+    {"emoji": "♻️", "name": "refactor", "description": "Code refactoring"},
+]
+
+
+def extract_first_user_message(events: Sequence[Event]) -> str | None:
+    """Extract the first user message from conversation events.
+
+    Args:
+        events: List of conversation events.
+
+    Returns:
+        The first user message text, or None if no user message is found.
+    """
+    for event in events:
+        if (
+            isinstance(event, MessageEvent)
+            and event.source == "user"
+            and event.llm_message.content
+        ):
+            # Extract text content from the message
+            text_parts = []
+            for content in event.llm_message.content:
+                if isinstance(content, TextContent):
+                    text_parts.append(content.text)
+
+            if text_parts:
+                return " ".join(text_parts).strip()
+
+    return None
+
+
+def generate_title_with_llm(message: str, llm: LLM, max_length: int = 50) -> str | None:
+    """Generate a conversation title using LLM.
+
+    Args:
+        message: The first user message to generate title from.
+        llm: The LLM to use for title generation.
+        max_length: Maximum length of the generated title.
+
+    Returns:
+        Generated title, or None if LLM fails or returns empty response.
+    """
+    # Truncate very long messages to avoid excessive token usage
+    if len(message) > 1000:
+        truncated_message = message[:1000] + "...(truncated)"
+    else:
+        truncated_message = message
+
+    emojis_descriptions = "\n- ".join(
+        f"{c['emoji']} {c['name']}: {c['description']}" for c in categories
+    )
+
+    try:
+        # Create messages for the LLM to generate a title
+        messages = [
+            Message(
+                role="system",
+                content=[
+                    TextContent(
+                        text=(
+                            "You are a helpful assistant that generates concise, "
+                            "descriptive titles for conversations with OpenHands. "
+                            "OpenHands is a helpful AI agent that can interact "
+                            "with a computer to solve tasks using bash terminal, "
+                            "file editor, and browser. Given a user message "
+                            "(which may be truncated), generate a concise, "
+                            "descriptive title for the conversation. Return only "
+                            "the title, with no additional text, quotes, or "
+                            "explanations."
+                        )
+                    )
+                ],
+            ),
+            Message(
+                role="user",
+                content=[
+                    TextContent(
+                        text=(
+                            f"Generate a title (maximum {max_length} characters) "
+                            f"for a conversation that starts with this message:\n\n"
+                            f"{truncated_message}."
+                            "Also make sure to include ONE most relevant emoji at "
+                            "the start of the title."
+                            f" Choose the emoji from this list:{emojis_descriptions} "
+                        )
+                    )
+                ],
+            ),
+        ]
+
+        # Get completion from LLM
+        response = llm.completion(messages)
+
+        # Extract the title from the response
+        if response.message.content and isinstance(
+            response.message.content[0], TextContent
+        ):
+            title = response.message.content[0].text.strip()
+
+            # Ensure the title isn't too long
+            if len(title) > max_length:
+                title = title[: max_length - 3] + "..."
+
+            return title
+        else:
+            logger.warning("LLM returned empty response for title generation")
+            return None
+
+    except Exception as e:
+        logger.warning(f"Error generating conversation title with LLM: {e}")
+        return None
+
+
+def generate_fallback_title(message: str, max_length: int = 50) -> str:
+    """Generate a fallback title by truncating the first user message.
+
+    Args:
+        message: The first user message.
+        max_length: Maximum length of the title.
+
+    Returns:
+        A truncated title.
+    """
+    title = message.strip()
+    if len(title) > max_length:
+        title = title[: max_length - 3] + "..."
+    return title
+
+
+def generate_conversation_title(
+    events: Sequence[Event], llm: LLM | None = None, max_length: int = 50
+) -> str:
+    """Generate a title for a conversation based on the first user message.
+
+    This is the main utility function that orchestrates the title generation process:
+    1. Extract the first user message from events
+    2. Try to generate title using LLM
+    3. Fall back to simple truncation if LLM fails
+
+    Args:
+        events: List of conversation events.
+        llm: Optional LLM to use for title generation.
+        max_length: Maximum length of the generated title.
+
+    Returns:
+        A generated title for the conversation.
+
+    Raises:
+        ValueError: If no user messages are found in the conversation events.
+    """
+    # Find the first user message in the events
+    first_user_message = extract_first_user_message(events)
+
+    if not first_user_message:
+        raise ValueError("No user messages found in conversation events")
+
+    # Try to generate title with LLM if provided
+    if llm:
+        llm_title = generate_title_with_llm(first_user_message, llm, max_length)
+        if llm_title:
+            return llm_title
+
+    # Fall back to simple truncation
+    return generate_fallback_title(first_user_message, max_length)

openhands/sdk/conversation/types.py

@@ -0,0 +1,45 @@
+import uuid
+from collections.abc import Callable
+
+from pydantic import BaseModel, Field
+
+from openhands.sdk.event.base import Event
+from openhands.sdk.llm.streaming import TokenCallbackType
+
+
+ConversationCallbackType = Callable[[Event], None]
+"""Type alias for event callback functions."""
+
+ConversationTokenCallbackType = TokenCallbackType
+"""Callback type invoked for streaming LLM deltas."""
+
+ConversationID = uuid.UUID
+"""Type alias for conversation IDs."""
+
+
+class StuckDetectionThresholds(BaseModel):
+    """Configuration for stuck detection thresholds.
+
+    Attributes:
+        action_observation: Number of repetitions before triggering
+            action-observation loop detection
+        action_error: Number of repetitions before triggering
+            action-error loop detection
+        monologue: Number of consecutive agent messages before triggering
+            monologue detection
+        alternating_pattern: Number of repetitions before triggering
+            alternating pattern detection
+    """
+
+    action_observation: int = Field(
+        default=4, ge=1, description="Threshold for action-observation loop detection"
+    )
+    action_error: int = Field(
+        default=3, ge=1, description="Threshold for action-error loop detection"
+    )
+    monologue: int = Field(
+        default=3, ge=1, description="Threshold for agent monologue detection"
+    )
+    alternating_pattern: int = Field(
+        default=6, ge=1, description="Threshold for alternating pattern detection"
+    )

openhands/sdk/conversation/visualizer/__init__.py

@@ -0,0 +1,12 @@
+from openhands.sdk.conversation.visualizer.base import (
+    ConversationVisualizerBase,
+)
+from openhands.sdk.conversation.visualizer.default import (
+    DefaultConversationVisualizer,
+)
+
+
+__all__ = [
+    "ConversationVisualizerBase",
+    "DefaultConversationVisualizer",
+]

openhands/sdk/conversation/visualizer/base.py

@@ -0,0 +1,67 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, final
+
+from openhands.sdk.event.base import Event
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.base import ConversationStateProtocol
+    from openhands.sdk.conversation.conversation_stats import ConversationStats
+
+
+class ConversationVisualizerBase(ABC):
+    """Base class for conversation visualizers.
+
+    This abstract base class defines the interface that all conversation visualizers
+    must implement. Visualizers can be created before the Conversation is initialized
+    and will be configured with the conversation state automatically.
+
+    The typical usage pattern:
+    1. Create a visualizer instance:
+       `viz = MyVisualizer()`
+    2. Pass it to Conversation: `conv = Conversation(agent, visualizer=viz)`
+    3. Conversation automatically calls `viz.initialize(state)` to attach the state
+
+    You can also pass the uninstantiated class if you don't need extra args
+        for initialization, and Conversation will create it:
+         `conv = Conversation(agent, visualizer=MyVisualizer)`
+    Conversation will then calls `MyVisualizer()` followed by `initialize(state)`
+    """
+
+    _state: "ConversationStateProtocol | None"
+
+    def __init__(self):
+        """Initialize the visualizer base."""
+        self._state = None
+
+    @final
+    def initialize(self, state: "ConversationStateProtocol") -> None:
+        """Initialize the visualizer with conversation state.
+
+        This method is called by Conversation after the state is created,
+        allowing the visualizer to access conversation stats and other
+        state information.
+
+        Subclasses should not override this method, to ensure the state is set.
+
+        Args:
+            state: The conversation state object
+        """
+        self._state = state
+
+    @property
+    def conversation_stats(self) -> "ConversationStats | None":
+        """Get conversation stats from the state."""
+        return self._state.stats if self._state else None
+
+    @abstractmethod
+    def on_event(self, event: Event) -> None:
+        """Handle a conversation event.
+
+        This method is called for each event in the conversation and should
+        implement the visualization logic.
+
+        Args:
+            event: The event to visualize
+        """
+        pass