openhands-sdk 1.7.0__py3-none-any.whl → 1.7.1__py3-none-any.whl

openhands/sdk/hooks/manager.py

@@ -0,0 +1,170 @@
+"""Hook manager - orchestrates hook execution within conversations."""
+
+from typing import Any
+
+from openhands.sdk.hooks.config import HookConfig
+from openhands.sdk.hooks.executor import HookExecutor, HookResult
+from openhands.sdk.hooks.types import HookEvent, HookEventType
+
+
+class HookManager:
+    """Manages hook execution for a conversation."""
+
+    def __init__(
+        self,
+        config: HookConfig | None = None,
+        working_dir: str | None = None,
+        session_id: str | None = None,
+    ):
+        self.config = config or HookConfig.load(working_dir=working_dir)
+        self.executor = HookExecutor(working_dir=working_dir)
+        self.session_id = session_id
+        self.working_dir = working_dir
+
+    def _create_event(
+        self,
+        event_type: HookEventType,
+        tool_name: str | None = None,
+        tool_input: dict[str, Any] | None = None,
+        tool_response: dict[str, Any] | None = None,
+        message: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> HookEvent:
+        """Create a hook event with common fields populated."""
+        return HookEvent(
+            event_type=event_type,
+            tool_name=tool_name,
+            tool_input=tool_input,
+            tool_response=tool_response,
+            message=message,
+            session_id=self.session_id,
+            working_dir=self.working_dir,
+            metadata=metadata or {},
+        )
+
+    def run_pre_tool_use(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+    ) -> tuple[bool, list[HookResult]]:
+        """Run PreToolUse hooks. Returns (should_continue, results)."""
+        hooks = self.config.get_hooks_for_event(HookEventType.PRE_TOOL_USE, tool_name)
+        if not hooks:
+            return True, []
+
+        event = self._create_event(
+            HookEventType.PRE_TOOL_USE,
+            tool_name=tool_name,
+            tool_input=tool_input,
+        )
+
+        results = self.executor.execute_all(hooks, event, stop_on_block=True)
+
+        # Check if any hook blocked the operation
+        should_continue = all(r.should_continue for r in results)
+
+        return should_continue, results
+
+    def run_post_tool_use(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+        tool_response: dict[str, Any],
+    ) -> list[HookResult]:
+        """Run PostToolUse hooks after a tool completes."""
+        hooks = self.config.get_hooks_for_event(HookEventType.POST_TOOL_USE, tool_name)
+        if not hooks:
+            return []
+
+        event = self._create_event(
+            HookEventType.POST_TOOL_USE,
+            tool_name=tool_name,
+            tool_input=tool_input,
+            tool_response=tool_response,
+        )
+
+        # PostToolUse hooks don't block - they just run
+        return self.executor.execute_all(hooks, event, stop_on_block=False)
+
+    def run_user_prompt_submit(
+        self,
+        message: str,
+    ) -> tuple[bool, str | None, list[HookResult]]:
+        """Run UserPromptSubmit hooks."""
+        hooks = self.config.get_hooks_for_event(HookEventType.USER_PROMPT_SUBMIT)
+        if not hooks:
+            return True, None, []
+
+        event = self._create_event(
+            HookEventType.USER_PROMPT_SUBMIT,
+            message=message,
+        )
+
+        results = self.executor.execute_all(hooks, event, stop_on_block=True)
+
+        # Check if any hook blocked
+        should_continue = all(r.should_continue for r in results)
+
+        # Collect additional context from hooks
+        additional_context_parts = [
+            r.additional_context for r in results if r.additional_context
+        ]
+        additional_context = (
+            "\n".join(additional_context_parts) if additional_context_parts else None
+        )
+
+        return should_continue, additional_context, results
+
+    def run_session_start(self) -> list[HookResult]:
+        """Run SessionStart hooks when a conversation begins."""
+        hooks = self.config.get_hooks_for_event(HookEventType.SESSION_START)
+        if not hooks:
+            return []
+
+        event = self._create_event(HookEventType.SESSION_START)
+        return self.executor.execute_all(hooks, event, stop_on_block=False)
+
+    def run_session_end(self) -> list[HookResult]:
+        """Run SessionEnd hooks when a conversation ends."""
+        hooks = self.config.get_hooks_for_event(HookEventType.SESSION_END)
+        if not hooks:
+            return []
+
+        event = self._create_event(HookEventType.SESSION_END)
+        return self.executor.execute_all(hooks, event, stop_on_block=False)
+
+    def run_stop(
+        self,
+        reason: str | None = None,
+    ) -> tuple[bool, list[HookResult]]:
+        """Run Stop hooks. Returns (should_stop, results)."""
+        hooks = self.config.get_hooks_for_event(HookEventType.STOP)
+        if not hooks:
+            return True, []
+
+        event = self._create_event(
+            HookEventType.STOP,
+            metadata={"reason": reason} if reason else {},
+        )
+
+        results = self.executor.execute_all(hooks, event, stop_on_block=True)
+
+        # If a hook blocks, the agent should NOT stop (continue running)
+        should_stop = all(r.should_continue for r in results)
+
+        return should_stop, results
+
+    def has_hooks(self, event_type: HookEventType) -> bool:
+        """Check if there are hooks configured for an event type."""
+        return self.config.has_hooks_for_event(event_type)
+
+    def get_blocking_reason(self, results: list[HookResult]) -> str | None:
+        """Get the reason for blocking from hook results."""
+        for result in results:
+            if result.blocked:
+                if result.reason:
+                    return result.reason
+                if result.stderr:
+                    return result.stderr.strip()
+                return "Blocked by hook"
+        return None

openhands/sdk/hooks/types.py

@@ -0,0 +1,40 @@
+"""Hook event types and data structures."""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class HookEventType(str, Enum):
+    """Types of hook events that can trigger hooks."""
+
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"
+    USER_PROMPT_SUBMIT = "UserPromptSubmit"
+    SESSION_START = "SessionStart"
+    SESSION_END = "SessionEnd"
+    STOP = "Stop"
+
+
+class HookEvent(BaseModel):
+    """Data passed to hook scripts via stdin as JSON."""
+
+    event_type: HookEventType
+    tool_name: str | None = None
+    tool_input: dict[str, Any] | None = None
+    tool_response: dict[str, Any] | None = None
+    message: str | None = None
+    session_id: str | None = None
+    working_dir: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"use_enum_values": True}
+
+
+class HookDecision(str, Enum):
+    """Decisions a hook can make about an operation."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    # ASK = "ask"  # Future: prompt user for confirmation before proceeding

openhands/sdk/io/cache.py

@@ -0,0 +1,85 @@
+from typing import Any
+
+from cachetools import LRUCache
+
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class MemoryLRUCache(LRUCache):
+    """LRU cache with both entry count and memory size limits.
+
+    This cache enforces two limits:
+    1. Maximum number of entries (maxsize)
+    2. Maximum memory usage in bytes (max_memory)
+
+    When either limit is exceeded, the least recently used items are evicted.
+
+    Note: Memory tracking is based on string length for simplicity and accuracy.
+    For non-string values, sys.getsizeof is used as a rough approximation.
+    """
+
+    def __init__(self, max_memory: int, max_size: int, *args, **kwargs):
+        # Ensure minimum maxsize of 1 to avoid LRUCache issues
+        maxsize = max(1, max_size)
+        super().__init__(maxsize=maxsize, *args, **kwargs)
+        self.max_memory = max_memory
+        self.current_memory = 0
+
+    def _get_size(self, value: Any) -> int:
+        """Calculate size of value for memory tracking.
+
+        For strings (the common case in FileStore), we use len() which gives
+        accurate character count. For other types, we use sys.getsizeof() as
+        a rough approximation.
+        """
+        if isinstance(value, str):
+            # For strings, len() gives character count which is what we care about
+            # This is much more accurate than sys.getsizeof for our use case
+            return len(value)
+        elif isinstance(value, bytes):
+            return len(value)
+        else:
+            # For other types, fall back to sys.getsizeof
+            # This is mainly for edge cases and won't be accurate for nested
+            # structures, but it's better than nothing
+            try:
+                import sys
+
+                return sys.getsizeof(value)
+            except Exception:
+                return 0
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        new_size = self._get_size(value)
+
+        # Don't cache items that are larger than max_memory
+        # This prevents cache thrashing where one huge item evicts everything
+        if new_size > self.max_memory:
+            logger.debug(
+                f"Item too large for cache ({new_size} bytes > "
+                f"{self.max_memory} bytes), skipping cache"
+            )
+            return
+
+        # Update memory accounting if key exists
+        if key in self:
+            old_value = self[key]
+            self.current_memory -= self._get_size(old_value)
+
+        self.current_memory += new_size
+
+        # Evict items until we're under memory limit
+        while self.current_memory > self.max_memory and len(self) > 0:
+            self.popitem()
+
+        super().__setitem__(key, value)
+
+    def __delitem__(self, key: Any) -> None:
+        if key in self:
+            old_value = self[key]
+            self.current_memory -= self._get_size(old_value)
+
+        super().__delitem__(key)

openhands/sdk/io/local.py

@@ -1,6 +1,7 @@
 import os
 import shutil
 
+from openhands.sdk.io.cache import MemoryLRUCache
 from openhands.sdk.logger import get_logger
 from openhands.sdk.observability.laminar import observe
 
@@ -12,13 +13,31 @@ logger = get_logger(__name__)
 
 class LocalFileStore(FileStore):
     root: str
+    cache: MemoryLRUCache
 
-    def __init__(self, root: str):
+    def __init__(
+        self,
+        root: str,
+        cache_limit_size: int = 500,
+        cache_memory_size: int = 20 * 1024 * 1024,
+    ) -> None:
+        """Initialize a LocalFileStore with caching.
+
+        Args:
+            root: Root directory for file storage.
+            cache_limit_size: Maximum number of cached entries (default: 500).
+            cache_memory_size: Maximum cache memory in bytes (default: 20MB).
+
+        Note:
+            The cache assumes exclusive access to files. External modifications
+            to files will not be detected and may result in stale cache reads.
+        """
         if root.startswith("~"):
             root = os.path.expanduser(root)
         root = os.path.abspath(os.path.normpath(root))
         self.root = root
         os.makedirs(self.root, exist_ok=True)
+        self.cache = MemoryLRUCache(cache_memory_size, cache_limit_size)
 
     def get_full_path(self, path: str) -> str:
         # strip leading slash to keep relative under root
@@ -32,6 +51,7 @@ class LocalFileStore(FileStore):
         # ensure sandboxing
         if os.path.commonpath([self.root, full]) != self.root:
             raise ValueError(f"path escapes filestore root: {path}")
+
         return full
 
     @observe(name="LocalFileStore.write", span_type="TOOL")
@@ -41,14 +61,27 @@ class LocalFileStore(FileStore):
         if isinstance(contents, str):
             with open(full_path, "w", encoding="utf-8") as f:
                 f.write(contents)
+            self.cache[full_path] = contents
         else:
             with open(full_path, "wb") as f:
                 f.write(contents)
+            # Don't cache binary content - LocalFileStore is meant for JSON data
+            # If binary data is written and then read, it will error on read
 
     def read(self, path: str) -> str:
         full_path = self.get_full_path(path)
+
+        if full_path in self.cache:
+            return self.cache[full_path]
+
+        if not os.path.exists(full_path):
+            raise FileNotFoundError(path)
+
         with open(full_path, encoding="utf-8") as f:
-            return f.read()
+            result = f.read()
+
+        self.cache[full_path] = result
+        return result
 
     @observe(name="LocalFileStore.list", span_type="TOOL")
     def list(self, path: str) -> list[str]:
@@ -72,11 +105,15 @@ class LocalFileStore(FileStore):
             if not os.path.exists(full_path):
                 logger.debug(f"Local path does not exist: {full_path}")
                 return
+
             if os.path.isfile(full_path):
                 os.remove(full_path)
+                del self.cache[full_path]
                 logger.debug(f"Removed local file: {full_path}")
             elif os.path.isdir(full_path):
                 shutil.rmtree(full_path)
+                self.cache.clear()
                 logger.debug(f"Removed local directory: {full_path}")
+
         except Exception as e:
             logger.error(f"Error clearing local file store: {str(e)}")

openhands/sdk/llm/mixins/fn_call_converter.py

@@ -450,7 +450,8 @@ PLEASE follow the format strictly! PLEASE EMIT ONE AND ONLY ONE FUNCTION CALL PE
 """  # noqa: E501
 
 # Regex patterns for function call parsing
-FN_REGEX_PATTERN = r"<function=([^>]+)>\n(.*?)</function>"
+# Note: newline after function name is optional for compatibility with various models
+FN_REGEX_PATTERN = r"<function=([^>]+)>\n?(.*?)</function>"
 FN_PARAM_REGEX_PATTERN = r"<parameter=([^>]+)>(.*?)</parameter>"
 
 # Add new regex pattern for tool execution results
@@ -702,7 +703,7 @@ def convert_fncall_messages_to_non_fncall_messages(
     first_user_message_encountered = False
     for message in messages:
         role = message["role"]
-        content: Content = message["content"]
+        content: Content = message.get("content") or ""
 
         # 1. SYSTEM MESSAGES
         # append system prompt suffix to content
@@ -880,6 +881,9 @@ def _extract_and_validate_params(
     for param_match in param_matches:
         param_name = param_match.group(1)
         param_value = param_match.group(2)
+        # Normalize whitespace: some models add extra newlines around values
+        if isinstance(param_value, str):
+            param_value = param_value.strip()
 
         # Validate parameter is allowed
         if allowed_params and param_name not in allowed_params:
@@ -927,7 +931,11 @@ def _extract_and_validate_params(
         found_params.add(param_name)
 
     # Check all required parameters are present
-    missing_params = required_params - found_params
+    # Note: security_risk is excluded here because its validation happens later
+    # in Agent._extract_security_risk(), which has context about whether a security
+    # analyzer is configured. This allows weaker models to omit it when no analyzer
+    # is active, while still enforcing it for stronger models with LLMSecurityAnalyzer.
+    missing_params = required_params - found_params - {"security_risk"}
     if missing_params:
         raise FunctionCallValidationError(
             f"Missing required parameters for function '{fn_name}': {missing_params}"
@@ -935,12 +943,31 @@ def _extract_and_validate_params(
     return params
 
 
+def _preprocess_model_output(content: str) -> str:
+    """Clean up model-specific formatting before parsing function calls.
+
+    Removes wrapper tags that some models (like Nemotron) emit around function calls:
+    - </think> before the function call
+    - <tool_call>...</tool_call> around the function call
+
+    Only strips tags at boundaries, not inside parameter values.
+    """
+    # Strip </think> when it appears before <function= (Nemotron reasoning end)
+    content = re.sub(r"</think>\s*(?=<function=)", "", content)
+    # Strip <tool_call> when it appears right before <function=
+    content = re.sub(r"<tool_call>\s*(?=<function=)", "", content)
+    # Strip </tool_call> when it appears right after </function>
+    content = re.sub(r"(?<=</function>)\s*</tool_call>", "", content)
+    return content
+
+
 def _fix_stopword(content: str) -> str:
     """Fix the issue when some LLM would NOT return the stopword."""
+    content = _preprocess_model_output(content)
     if "<function=" in content and content.count("<function=") == 1:
         if content.endswith("</"):
             content = content.rstrip() + "function>"
-        else:
+        elif not content.rstrip().endswith("</function>"):
             content = content + "\n</function>"
     return content
 
@@ -981,8 +1008,8 @@ def convert_non_fncall_messages_to_fncall_messages(
 
     first_user_message_encountered = False
     for message in messages:
-        role, content = message["role"], message["content"]
-        content = content or ""  # handle cases where content is None
+        role = message["role"]
+        content = message.get("content") or ""
         # For system messages, remove the added suffix
         if role == "system":
             if isinstance(content, str):
@@ -1124,15 +1151,32 @@ def convert_non_fncall_messages_to_fncall_messages(
             if fn_match:
                 fn_name = fn_match.group(1)
                 fn_body = _normalize_parameter_tags(fn_match.group(2))
-                matching_tool: ChatCompletionToolParamFunctionChunk | None = next(
-                    (
-                        tool["function"]
-                        for tool in tools
-                        if tool["type"] == "function"
-                        and tool["function"]["name"] == fn_name
-                    ),
-                    None,
-                )
+
+                def _find_tool(
+                    name: str,
+                ) -> ChatCompletionToolParamFunctionChunk | None:
+                    return next(
+                        (
+                            tool["function"]
+                            for tool in tools
+                            if tool["type"] == "function"
+                            and tool["function"]["name"] == name
+                        ),
+                        None,
+                    )
+
+                matching_tool = _find_tool(fn_name)
+                # Try aliases if tool not found (some models use legacy names)
+                if not matching_tool:
+                    TOOL_NAME_ALIASES = {
+                        "str_replace_editor": "file_editor",
+                        "bash": "terminal",
+                        "execute_bash": "terminal",
+                        "str_replace": "file_editor",
+                    }
+                    if fn_name in TOOL_NAME_ALIASES:
+                        fn_name = TOOL_NAME_ALIASES[fn_name]
+                        matching_tool = _find_tool(fn_name)
                 # Validate function exists in tools
                 if not matching_tool:
                     available_tools = [
@@ -1203,7 +1247,8 @@ def convert_from_multiple_tool_calls_to_single_tool_call_messages(
     for message in messages:
         role: str
         content: Content
-        role, content = message["role"], message["content"]
+        role = message["role"]
+        content = message.get("content") or ""
         if role == "assistant":
             if message.get("tool_calls") and len(message["tool_calls"]) > 1:
                 # handle multiple tool calls by breaking them into multiple messages

openhands/sdk/llm/mixins/non_native_fc.py

@@ -41,7 +41,11 @@ class NonNativeToolCallingMixin:
         kwargs: dict,
     ) -> tuple[list[dict], dict]:
         """Convert to non-fncall prompting when native tool-calling is off."""
-        add_iclex = not any(s in self.model for s in ("openhands-lm", "devstral"))
+        # Skip in-context learning examples for models that understand the format
+        # or have limited context windows
+        add_iclex = not any(
+            s in self.model for s in ("openhands-lm", "devstral", "nemotron")
+        )
         messages = convert_fncall_messages_to_non_fncall_messages(
             messages, tools, add_in_context_learning_example=add_iclex
         )

openhands/sdk/tool/schema.py

@@ -22,6 +22,16 @@ S = TypeVar("S", bound="Schema")
 def py_type(spec: dict[str, Any]) -> Any:
     """Map JSON schema types to Python types."""
     t = spec.get("type")
+
+    # Normalize union types like ["string", "null"] to a single representative type.
+    # MCP schemas often mark optional fields this way; we keep the non-null type.
+    if isinstance(t, (list, tuple, set)):
+        types = list(t)
+        non_null = [tp for tp in types if tp != "null"]
+        if len(non_null) == 1:
+            t = non_null[0]
+        else:
+            return Any
     if t == "array":
         items = spec.get("items", {})
         inner = py_type(items) if isinstance(items, dict) else Any

{openhands_sdk-1.7.0.dist-info → openhands_sdk-1.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.7.0
+Version: 1.7.1
 Summary: OpenHands SDK - Core functionality for building AI agents
 Requires-Python: >=3.12
 Requires-Dist: deprecation>=2.1.0