openhands-sdk 1.5.0__py3-none-any.whl → 1.7.2__py3-none-any.whl

openhands/sdk/conversation/stuck_detector.py

@@ -1,4 +1,5 @@
 from openhands.sdk.conversation.state import ConversationState
+from openhands.sdk.conversation.types import StuckDetectionThresholds
 from openhands.sdk.event import (
     ActionEvent,
     AgentErrorEvent,
@@ -26,9 +27,31 @@ class StuckDetector:
     """
 
     state: ConversationState
+    thresholds: StuckDetectionThresholds
 
-    def __init__(self, state: ConversationState):
+    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."""
@@ -49,8 +72,13 @@ class StuckDetector:
 
         events = events[last_user_msg_index + 1 :]
 
-        # it takes 3 actions minimum to detect a loop, otherwise nothing to do here
-        if len(events) < 3:
+        # 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")
@@ -58,19 +86,21 @@ class StuckDetector:
             f"Events after last user message: {[type(e).__name__ for e in events]}"
         )
 
-        # the first few scenarios detect 3 or 4 repeated steps
-        # prepare the last 4 actions and observations, to check them out
+        # 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 four actions and observations starting from
-        # the end of history, wherever they are
+        # 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) < 4:
+            if isinstance(event, ActionEvent) and len(last_actions) < max_needed:
                 last_actions.append(event)
-            elif isinstance(event, ObservationBaseEvent) and len(last_observations) < 4:
+            elif (
+                isinstance(event, ObservationBaseEvent)
+                and len(last_observations) < max_needed
+            ):
                 last_observations.append(event)
-            if len(last_actions) >= 4 and len(last_observations) >= 4:
+            if len(last_actions) >= max_needed and len(last_observations) >= max_needed:
                 break
 
         # Check all stuck patterns
@@ -86,8 +116,8 @@ class StuckDetector:
         if self._is_stuck_monologue(events):
             return True
 
-        # scenario 4: action, observation alternating pattern on the last six steps
-        if len(events) >= 6:
+        # scenario 4: action, observation alternating pattern
+        if len(events) >= self.alternating_pattern_threshold:
             if self._is_stuck_alternating_action_observation(events):
                 return True
 
@@ -102,18 +132,21 @@ class StuckDetector:
         self, last_actions: list[Event], last_observations: list[Event]
     ) -> bool:
         # scenario 1: same action, same observation
-        # it takes 4 actions and 4 observations to detect a loop
-        # assert len(last_actions) == 4 and len(last_observations) == 4
+        threshold = self.action_observation_threshold
 
-        # Check for a loop of 4 identical action-observation pairs
-        if len(last_actions) == 4 and len(last_observations) == 4:
-            logger.debug("Found 4 actions and 4 observations, checking for equality")
+        # 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
+                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
+                for observation in last_observations[:threshold]
             )
             logger.debug(
                 f"Actions equal: {actions_equal}, "
@@ -135,15 +168,20 @@ class StuckDetector:
         self, last_actions: list[Event], last_observations: list[Event]
     ) -> bool:
         # scenario 2: same action, errors
-        # it takes 3 actions and 3 observations to detect a loop
-        # check if the last three actions are the same and result in errors
-        if len(last_actions) < 3 or len(last_observations) < 3:
+        threshold = self.action_error_threshold
+        if len(last_actions) < threshold or len(last_observations) < threshold:
             return False
 
-        # are the last three actions the "same"?
-        if all(self._event_eq(last_actions[0], action) for action in last_actions[:3]):
-            # and the last three observations are all errors?
-            if all(isinstance(obs, AgentErrorEvent) for obs in last_observations[:3]):
+        # 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
 
@@ -155,10 +193,11 @@ class StuckDetector:
         # 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
-        if len(events) < 3:
+        threshold = self.monologue_threshold
+        if len(events) < threshold:
             return False
 
-        # Look for 3 consecutive agent messages without user interruption
+        # Look for N consecutive agent messages without user interruption
         agent_message_count = 0
 
         for event in reversed(events):
@@ -174,40 +213,37 @@ class StuckDetector:
                 # Other events (actions/observations) don't count as monologue
                 break
 
-        return agent_message_count >= 3
+        return agent_message_count >= threshold
 
     def _is_stuck_alternating_action_observation(self, events: list[Event]) -> bool:
         # scenario 4: alternating action-observation loop
-        # needs 6 actions and 6 observations to detect the ping-pong pattern
+        threshold = self.alternating_pattern_threshold
 
         last_actions: list[Event] = []
         last_observations: list[Event] = []
 
-        # collect most recent 6 actions and 6 observations
+        # collect most recent N actions and N observations
         for event in reversed(events):
-            if isinstance(event, ActionEvent) and len(last_actions) < 6:
+            if isinstance(event, ActionEvent) and len(last_actions) < threshold:
                 last_actions.append(event)
             elif (
                 isinstance(event, (ObservationEvent, AgentErrorEvent))
-                and len(last_observations) < 6
+                and len(last_observations) < threshold
             ):
                 last_observations.append(event)
 
-            if len(last_actions) == 6 and len(last_observations) == 6:
+            if len(last_actions) == threshold and len(last_observations) == threshold:
                 break
 
-        if len(last_actions) == 6 and len(last_observations) == 6:
-            actions_equal = (
-                self._event_eq(last_actions[0], last_actions[2])
-                and self._event_eq(last_actions[0], last_actions[4])
-                and self._event_eq(last_actions[1], last_actions[3])
-                and self._event_eq(last_actions[1], last_actions[5])
+        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 = (
-                self._event_eq(last_observations[0], last_observations[2])
-                and self._event_eq(last_observations[0], last_observations[4])
-                and self._event_eq(last_observations[1], last_observations[3])
-                and self._event_eq(last_observations[1], last_observations[5])
+            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:

openhands/sdk/conversation/types.py

@@ -1,6 +1,8 @@
 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
 
@@ -13,3 +15,31 @@ ConversationTokenCallbackType = TokenCallbackType
 
 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/event/llm_convertible/system.py

@@ -1,12 +1,12 @@
 import json
 
-from litellm import ChatCompletionToolParam
 from pydantic import Field
 from rich.text import Text
 
 from openhands.sdk.event.base import N_CHAR_PREVIEW, LLMConvertibleEvent
 from openhands.sdk.event.types import SourceType
 from openhands.sdk.llm import Message, TextContent
+from openhands.sdk.tool import ToolDefinition
 
 
 class SystemPromptEvent(LLMConvertibleEvent):
@@ -14,8 +14,8 @@ class SystemPromptEvent(LLMConvertibleEvent):
 
     source: SourceType = "agent"
     system_prompt: TextContent = Field(..., description="The system prompt text")
-    tools: list[ChatCompletionToolParam] = Field(
-        ..., description="List of tools in OpenAI tool format"
+    tools: list[ToolDefinition] = Field(
+        ..., description="List of tools as ToolDefinition objects"
     )
 
     @property
@@ -26,26 +26,22 @@ class SystemPromptEvent(LLMConvertibleEvent):
         content.append(self.system_prompt.text)
         content.append(f"\n\nTools Available: {len(self.tools)}")
         for tool in self.tools:
-            # Build display-only copy to avoid mutating event data
-            tool_display = {
-                k: (v[:27] + "..." if isinstance(v, str) and len(v) > 30 else v)
-                for k, v in tool.items()
-            }
-            tool_fn = tool_display.get("function", None)
-            if tool_fn and isinstance(tool_fn, dict):
-                assert "name" in tool_fn
-                assert "description" in tool_fn
-                assert "parameters" in tool_fn
-                params_str = json.dumps(tool_fn["parameters"])
+            # Use ToolDefinition properties directly
+            description = tool.description.split("\n")[0][:100]
+            if len(description) < len(tool.description):
+                description += "..."
+
+            content.append(f"\n  - {tool.name}: {description}\n")
+
+            # Get parameters from the action type schema
+            try:
+                params_dict = tool.action_type.to_mcp_schema()
+                params_str = json.dumps(params_dict)
                 if len(params_str) > 200:
                     params_str = params_str[:197] + "..."
-                content.append(
-                    f"\n  - {tool_fn['name']}: "
-                    f"{tool_fn['description'].split('\n')[0][:100]}...\n",
-                )
                 content.append(f"  Parameters: {params_str}")
-            else:
-                content.append(f"\n  - Cannot access .function for {tool_display}")
+            except Exception:
+                content.append("  Parameters: <unavailable>")
         return content
 
     def to_llm_message(self) -> Message:

openhands/sdk/hooks/__init__.py

@@ -0,0 +1,30 @@
+"""
+OpenHands Hooks System - Event-driven hooks for automation and control.
+
+Hooks are event-driven scripts that execute at specific lifecycle events
+during agent execution, enabling deterministic control over agent behavior.
+"""
+
+from openhands.sdk.hooks.config import HookConfig, HookDefinition, HookMatcher
+from openhands.sdk.hooks.conversation_hooks import (
+    HookEventProcessor,
+    create_hook_callback,
+)
+from openhands.sdk.hooks.executor import HookExecutor, HookResult
+from openhands.sdk.hooks.manager import HookManager
+from openhands.sdk.hooks.types import HookDecision, HookEvent, HookEventType
+
+
+__all__ = [
+    "HookConfig",
+    "HookDefinition",
+    "HookMatcher",
+    "HookExecutor",
+    "HookResult",
+    "HookManager",
+    "HookEvent",
+    "HookEventType",
+    "HookDecision",
+    "HookEventProcessor",
+    "create_hook_callback",
+]

openhands/sdk/hooks/config.py

@@ -0,0 +1,180 @@
+"""Hook configuration loading and management."""
+
+import json
+import logging
+import re
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from openhands.sdk.hooks.types import HookEventType
+
+
+logger = logging.getLogger(__name__)
+
+
+class HookType(str, Enum):
+    """Types of hooks that can be executed."""
+
+    COMMAND = "command"  # Shell command executed via subprocess
+    PROMPT = "prompt"  # LLM-based evaluation (future)
+
+
+class HookDefinition(BaseModel):
+    """A single hook definition."""
+
+    type: HookType = HookType.COMMAND
+    command: str
+    timeout: int = 60
+
+
+class HookMatcher(BaseModel):
+    """Matches events to hooks based on patterns.
+
+    Supports exact match, wildcard (*), and regex (auto-detected or /pattern/).
+    """
+
+    matcher: str = "*"
+    hooks: list[HookDefinition] = Field(default_factory=list)
+
+    # Regex metacharacters that indicate a pattern should be treated as regex
+    _REGEX_METACHARACTERS = set("|.*+?[]()^$\\")
+
+    def matches(self, tool_name: str | None) -> bool:
+        """Check if this matcher matches the given tool name."""
+        # Wildcard matches everything
+        if self.matcher == "*" or self.matcher == "":
+            return True
+
+        if tool_name is None:
+            return self.matcher in ("*", "")
+
+        # Check for explicit regex pattern (enclosed in /)
+        is_regex = (
+            self.matcher.startswith("/")
+            and self.matcher.endswith("/")
+            and len(self.matcher) > 2
+        )
+        if is_regex:
+            pattern = self.matcher[1:-1]
+            try:
+                return bool(re.fullmatch(pattern, tool_name))
+            except re.error:
+                return False
+
+        # Auto-detect regex: if matcher contains metacharacters, treat as regex
+        if any(c in self.matcher for c in self._REGEX_METACHARACTERS):
+            try:
+                return bool(re.fullmatch(self.matcher, tool_name))
+            except re.error:
+                # Invalid regex, fall through to exact match
+                pass
+
+        # Exact match
+        return self.matcher == tool_name
+
+
+class HookConfig(BaseModel):
+    """Configuration for all hooks, loaded from .openhands/hooks.json."""
+
+    hooks: dict[str, list[HookMatcher]] = Field(default_factory=dict)
+
+    @classmethod
+    def load(
+        cls, path: str | Path | None = None, working_dir: str | Path | None = None
+    ) -> "HookConfig":
+        """Load config from path or search .openhands/hooks.json locations.
+
+        Args:
+            path: Explicit path to hooks.json file. If provided, working_dir is ignored.
+            working_dir: Project directory for discovering .openhands/hooks.json.
+                Falls back to cwd if not provided.
+        """
+        if path is None:
+            # Search for hooks.json in standard locations
+            base_dir = Path(working_dir) if working_dir else Path.cwd()
+            search_paths = [
+                base_dir / ".openhands" / "hooks.json",
+                Path.home() / ".openhands" / "hooks.json",
+            ]
+            for search_path in search_paths:
+                if search_path.exists():
+                    path = search_path
+                    break
+
+        if path is None:
+            return cls()
+
+        path = Path(path)
+        if not path.exists():
+            return cls()
+
+        try:
+            with open(path) as f:
+                data = json.load(f)
+            return cls.from_dict(data)
+        except (json.JSONDecodeError, OSError) as e:
+            # Log warning but don't fail - just return empty config
+            logger.warning(f"Failed to load hooks from {path}: {e}")
+            return cls()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "HookConfig":
+        """Create HookConfig from a dictionary."""
+        hooks_data = data.get("hooks", {})
+        hooks: dict[str, list[HookMatcher]] = {}
+
+        for event_type, matchers in hooks_data.items():
+            if not isinstance(matchers, list):
+                continue
+
+            hooks[event_type] = []
+            for matcher_data in matchers:
+                if isinstance(matcher_data, dict):
+                    # Parse hooks within the matcher
+                    hook_defs = []
+                    for hook_data in matcher_data.get("hooks", []):
+                        if isinstance(hook_data, dict):
+                            hook_defs.append(HookDefinition(**hook_data))
+
+                    hooks[event_type].append(
+                        HookMatcher(
+                            matcher=matcher_data.get("matcher", "*"),
+                            hooks=hook_defs,
+                        )
+                    )
+
+        return cls(hooks=hooks)
+
+    def get_hooks_for_event(
+        self, event_type: HookEventType, tool_name: str | None = None
+    ) -> list[HookDefinition]:
+        """Get all hooks that should run for an event."""
+        event_key = event_type.value
+        matchers = self.hooks.get(event_key, [])
+
+        result: list[HookDefinition] = []
+        for matcher in matchers:
+            if matcher.matches(tool_name):
+                result.extend(matcher.hooks)
+
+        return result
+
+    def has_hooks_for_event(self, event_type: HookEventType) -> bool:
+        """Check if there are any hooks configured for an event type."""
+        return event_type.value in self.hooks and len(self.hooks[event_type.value]) > 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary format for serialization."""
+        hooks_dict = {k: [m.model_dump() for m in v] for k, v in self.hooks.items()}
+        return {"hooks": hooks_dict}
+
+    def save(self, path: str | Path) -> None:
+        """Save hook configuration to a JSON file."""
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(path, "w") as f:
+            json.dump(self.to_dict(), f, indent=2)