openhands-sdk 1.9.1__py3-none-any.whl → 1.10.0__py3-none-any.whl

openhands/sdk/event/condenser.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from pydantic import Field
 from rich.text import Text
 
@@ -22,8 +24,9 @@ class Condensation(Event):
     summary_offset: int | None = Field(
         default=None,
         ge=0,
-        description="An optional offset to the start of the resulting view"
-        " indicating where the summary should be inserted.",
+        description="An optional offset to the start of the resulting view (after"
+        " forgotten events have been removed) indicating where the summary should be"
+        " inserted. If not provided, the summary will not be inserted into the view.",
     )
     llm_response_id: EventID = Field(
         description=(
@@ -45,6 +48,53 @@ class Condensation(Event):
             text.append(f"{self.summary}\n")
         return text
 
+    @property
+    def summary_event(self) -> CondensationSummaryEvent:
+        """Generates a CondensationSummaryEvent.
+
+        Since summary events are not part of the main event store and are generated
+        dynamically, this property ensures the created event has a unique and consistent
+        ID based on the condensation event's ID.
+
+        Raises:
+            ValueError: If no summary is present.
+        """
+        if self.summary is None:
+            raise ValueError("No summary present to generate CondensationSummaryEvent.")
+
+        # Create a deterministic ID for the summary event.
+        # This ID will be unique amongst all auto-generated IDs (by virtue of the
+        # "-summary" suffix).
+        # These events are not intended to be stored alongside regular events, but the
+        # ID is still compatible with the file-based event store.
+        summary_id = f"{self.id}-summary"
+
+        return CondensationSummaryEvent(
+            id=summary_id,
+            summary=self.summary,
+            source=self.source,
+        )
+
+    @property
+    def has_summary_metadata(self) -> bool:
+        """Checks if both summary and summary_offset are present."""
+        return self.summary is not None and self.summary_offset is not None
+
+    def apply(self, events: list[LLMConvertibleEvent]) -> list[LLMConvertibleEvent]:
+        """Applies the condensation to a list of events.
+
+        This method removes events that are marked to be forgotten and returns a new
+        list of events. If the summary metadata is present (both summary and offset),
+        the corresponding CondensationSummaryEvent will be inserted at the specified
+        offset _after_ the forgotten events have been removed.
+        """
+        output = [event for event in events if event.id not in self.forgotten_event_ids]
+        if self.has_summary_metadata:
+            assert self.summary_offset is not None
+            summary_event = self.summary_event
+            output.insert(self.summary_offset, summary_event)
+        return output
+
 
 class CondensationRequest(Event):
     """This action is used to request a condensation of the conversation history.

openhands/sdk/git/cached_repo.py

@@ -170,6 +170,25 @@ class GitHelper:
             # origin/HEAD may not be set (e.g., bare clone, or never configured)
             return None
 
+    def get_head_commit(self, repo_path: Path, timeout: int = 10) -> str:
+        """Get the current HEAD commit SHA.
+
+        Args:
+            repo_path: Path to the repository.
+            timeout: Timeout in seconds.
+
+        Returns:
+            Full 40-character commit SHA of HEAD.
+
+        Raises:
+            GitCommandError: If command fails.
+        """
+        return run_git_command(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_path,
+            timeout=timeout,
+        )
+
 
 def try_cached_clone_or_update(
     url: str,

openhands/sdk/hooks/__init__.py

@@ -6,6 +6,7 @@ during agent execution, enabling deterministic control over agent behavior.
 """
 
 from openhands.sdk.hooks.config import (
+    HOOK_EVENT_FIELDS,
     HookConfig,
     HookDefinition,
     HookMatcher,
@@ -21,6 +22,7 @@ from openhands.sdk.hooks.types import HookDecision, HookEvent, HookEventType
 
 
 __all__ = [
+    "HOOK_EVENT_FIELDS",
     "HookConfig",
     "HookDefinition",
     "HookMatcher",

openhands/sdk/hooks/config.py

@@ -22,8 +22,9 @@ def _pascal_to_snake(name: str) -> str:
     return result
 
 
-# Valid snake_case field names for hook events
-_VALID_HOOK_FIELDS: frozenset[str] = frozenset(
+# Valid snake_case field names for hook events.
+# This is the single source of truth for hook event types.
+HOOK_EVENT_FIELDS: frozenset[str] = frozenset(
     {
         "pre_tool_use",
         "post_tool_use",
@@ -188,8 +189,8 @@ class HookConfig(BaseModel):
 
             if is_pascal_case:
                 # Validate that PascalCase key maps to a known field
-                if snake_key not in _VALID_HOOK_FIELDS:
-                    valid_types = ", ".join(sorted(_VALID_HOOK_FIELDS))
+                if snake_key not in HOOK_EVENT_FIELDS:
+                    valid_types = ", ".join(sorted(HOOK_EVENT_FIELDS))
                     raise ValueError(
                         f"Unknown event type '{key}'. Valid types: {valid_types}"
                     )
@@ -287,3 +288,42 @@ class HookConfig(BaseModel):
 
         with open(path, "w") as f:
             json.dump(self.model_dump(mode="json", exclude_defaults=True), f, indent=2)
+
+    @classmethod
+    def merge(cls, configs: list["HookConfig"]) -> "HookConfig | None":
+        """Merge multiple hook configs by concatenating handlers per event type.
+
+        Each hook config may have multiple event types (pre_tool_use,
+        post_tool_use, etc.). This method combines all matchers from all
+        configs for each event type.
+
+        Args:
+            configs: List of HookConfig objects to merge.
+
+        Returns:
+            A merged HookConfig with all matchers concatenated, or None if no configs
+            or if the result is empty.
+
+        Example:
+            >>> config1 = HookConfig(pre_tool_use=[HookMatcher(matcher="*")])
+            >>> config2 = HookConfig(pre_tool_use=[HookMatcher(matcher="terminal")])
+            >>> merged = HookConfig.merge([config1, config2])
+            >>> len(merged.pre_tool_use)  # Both matchers combined
+            2
+        """
+        if not configs:
+            return None
+
+        # Collect all matchers by event type using the canonical field list
+        collected: dict[str, list] = {field: [] for field in HOOK_EVENT_FIELDS}
+        for config in configs:
+            for field in HOOK_EVENT_FIELDS:
+                collected[field].extend(getattr(config, field))
+
+        merged = cls(**collected)
+
+        # Return None if the merged config is empty
+        if merged.is_empty():
+            return None
+
+        return merged

openhands/sdk/hooks/executor.py

@@ -8,6 +8,7 @@ from pydantic import BaseModel
 
 from openhands.sdk.hooks.config import HookDefinition
 from openhands.sdk.hooks.types import HookDecision, HookEvent
+from openhands.sdk.utils import sanitized_env
 
 
 class HookResult(BaseModel):
@@ -50,7 +51,7 @@ class HookExecutor:
     ) -> HookResult:
         """Execute a single hook."""
         # Prepare environment
-        hook_env = os.environ.copy()
+        hook_env = sanitized_env()
         hook_env["OPENHANDS_PROJECT_DIR"] = self.working_dir
         hook_env["OPENHANDS_SESSION_ID"] = event.session_id or ""
         hook_env["OPENHANDS_EVENT_TYPE"] = event.event_type

openhands/sdk/llm/llm.py

@@ -22,6 +22,7 @@ from pydantic import (
 from pydantic.json_schema import SkipJsonSchema
 
 from openhands.sdk.llm.utils.model_info import get_litellm_model_info
+from openhands.sdk.utils.deprecation import warn_deprecated
 from openhands.sdk.utils.pydantic_secrets import serialize_secret, validate_secret
 
 
@@ -283,10 +284,15 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     seed: int | None = Field(
         default=None, description="The seed to use for random number generation."
     )
+    # REMOVE_AT: 1.15.0 - Remove this field and its handling in chat_options.py
     safety_settings: list[dict[str, str]] | None = Field(
         default=None,
         description=(
-            "Safety settings for models that support them (like Mistral AI and Gemini)"
+            "Deprecated: Safety settings for models that support them "
+            "(like Mistral AI and Gemini). This field is deprecated in 1.10.0 "
+            "and will be removed in 1.15.0. Safety settings are designed for "
+            "consumer-facing content moderation, which is not relevant for "
+            "coding agents."
         ),
     )
     usage_id: str = Field(
@@ -342,6 +348,26 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     def _validate_secrets(cls, v: str | SecretStr | None, info) -> SecretStr | None:
         return validate_secret(v, info)
 
+    # REMOVE_AT: 1.15.0 - Remove this validator
+    @field_validator("safety_settings", mode="before")
+    @classmethod
+    def _warn_safety_settings_deprecated(
+        cls, v: list[dict[str, str]] | None
+    ) -> list[dict[str, str]] | None:
+        """Emit deprecation warning when safety_settings is explicitly set."""
+        if v is not None:
+            warn_deprecated(
+                "LLM.safety_settings",
+                deprecated_in="1.10.0",
+                removed_in="1.15.0",
+                details=(
+                    "Safety settings are designed for consumer-facing content "
+                    "moderation, which is not relevant for coding agents."
+                ),
+                stacklevel=4,
+            )
+        return v
+
     @model_validator(mode="before")
     @classmethod
     def _coerce_inputs(cls, data):
@@ -989,19 +1015,27 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         if self.is_caching_prompt_active():
             self._apply_prompt_caching(messages)
 
-        for message in messages:
-            message.cache_enabled = self.is_caching_prompt_active()
-            message.vision_enabled = self.vision_is_active()
-            message.function_calling_enabled = self.native_tool_calling
-            model_features = get_features(self._model_name_for_capabilities())
-            message.force_string_serializer = (
-                self.force_string_serializer
-                if self.force_string_serializer is not None
-                else model_features.force_string_serializer
+        model_features = get_features(self._model_name_for_capabilities())
+        cache_enabled = self.is_caching_prompt_active()
+        vision_enabled = self.vision_is_active()
+        function_calling_enabled = self.native_tool_calling
+        force_string_serializer = (
+            self.force_string_serializer
+            if self.force_string_serializer is not None
+            else model_features.force_string_serializer
+        )
+        send_reasoning_content = model_features.send_reasoning_content
+
+        formatted_messages = [
+            message.to_chat_dict(
+                cache_enabled=cache_enabled,
+                vision_enabled=vision_enabled,
+                function_calling_enabled=function_calling_enabled,
+                force_string_serializer=force_string_serializer,
+                send_reasoning_content=send_reasoning_content,
             )
-            message.send_reasoning_content = model_features.send_reasoning_content
-
-        formatted_messages = [message.to_chat_dict() for message in messages]
+            for message in messages
+        ]
 
         return formatted_messages
 

openhands/sdk/llm/message.py

@@ -11,10 +11,11 @@ from litellm.types.responses.main import (
 from litellm.types.utils import Message as LiteLLMMessage
 from openai.types.responses.response_output_message import ResponseOutputMessage
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from openhands.sdk.logger import get_logger
 from openhands.sdk.utils import DEFAULT_TEXT_CONTENT_LIMIT, maybe_truncate
+from openhands.sdk.utils.deprecation import warn_deprecated
 
 
 logger = get_logger(__name__)
@@ -209,30 +210,11 @@ class Message(BaseModel):
     # These are the roles in the LLM's APIs
     role: Literal["user", "system", "assistant", "tool"]
     content: Sequence[TextContent | ImageContent] = Field(default_factory=list)
-    cache_enabled: bool = False
-    vision_enabled: bool = False
-    # function calling
-    function_calling_enabled: bool = False
     # - tool calls (from LLM)
     tool_calls: list[MessageToolCall] | None = None
     # - tool execution result (to LLM)
     tool_call_id: str | None = None
     name: str | None = None  # name of the tool
-    force_string_serializer: bool = Field(
-        default=False,
-        description=(
-            "Force using string content serializer when sending to LLM API. "
-            "Useful for providers that do not support list content, "
-            "like HuggingFace and Groq."
-        ),
-    )
-    send_reasoning_content: bool = Field(
-        default=False,
-        description=(
-            "Whether to include the full reasoning content when sending to the LLM. "
-            "Useful for models that support extended reasoning, like Kimi-K2-thinking."
-        ),
-    )
     # reasoning content (from reasoning models like o1, Claude thinking, DeepSeek R1)
     reasoning_content: str | None = Field(
         default=None,
@@ -249,6 +231,47 @@ class Message(BaseModel):
         description="OpenAI Responses reasoning item from model output",
     )
 
+    # Deprecated fields that were moved to to_chat_dict() parameters.
+    # These fields are ignored but accepted for backward compatibility.
+    # REMOVE_AT: 1.12.0 - Remove this list and the _handle_deprecated_fields validator
+    _DEPRECATED_FIELDS: ClassVar[tuple[str, ...]] = (
+        "cache_enabled",
+        "vision_enabled",
+        "function_calling_enabled",
+        "force_string_serializer",
+        "send_reasoning_content",
+    )
+
+    model_config = ConfigDict(extra="ignore")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _handle_deprecated_fields(cls, data: Any) -> Any:
+        """Handle deprecated fields by emitting warnings and removing them.
+
+        REMOVE_AT: 1.12.0 - Remove this validator along with _DEPRECATED_FIELDS
+        """
+        if not isinstance(data, dict):
+            return data
+
+        deprecated_found = [f for f in cls._DEPRECATED_FIELDS if f in data]
+        for field in deprecated_found:
+            warn_deprecated(
+                f"Message.{field}",
+                deprecated_in="1.9.1",
+                removed_in="1.12.0",
+                details=(
+                    f"The '{field}' field has been removed from Message. "
+                    "Pass it as a parameter to to_chat_dict() instead, or use "
+                    "LLM.format_messages_for_llm() which handles this automatically."
+                ),
+                stacklevel=4,  # Adjust for validator call depth
+            )
+            # Remove the deprecated field so Pydantic doesn't complain
+            del data[field]
+
+        return data
+
     @property
     def contains_image(self) -> bool:
         return any(isinstance(content, ImageContent) for content in self.content)
@@ -264,17 +287,32 @@ class Message(BaseModel):
             return [TextContent(text=v)]
         return v
 
-    def to_chat_dict(self) -> dict[str, Any]:
+    def to_chat_dict(
+        self,
+        *,
+        cache_enabled: bool,
+        vision_enabled: bool,
+        function_calling_enabled: bool,
+        force_string_serializer: bool,
+        send_reasoning_content: bool,
+    ) -> dict[str, Any]:
         """Serialize message for OpenAI Chat Completions.
 
+        Args:
+            cache_enabled: Whether prompt caching is active.
+            vision_enabled: Whether vision/image processing is enabled.
+            function_calling_enabled: Whether native function calling is enabled.
+            force_string_serializer: Force string serializer instead of list format.
+            send_reasoning_content: Whether to include reasoning_content in output.
+
         Chooses the appropriate content serializer and then injects threading keys:
         - Assistant tool call turn: role == "assistant" and self.tool_calls
         - Tool result turn: role == "tool" and self.tool_call_id (with name)
         """
-        if not self.force_string_serializer and (
-            self.cache_enabled or self.vision_enabled or self.function_calling_enabled
+        if not force_string_serializer and (
+            cache_enabled or vision_enabled or function_calling_enabled
         ):
-            message_dict = self._list_serializer()
+            message_dict = self._list_serializer(vision_enabled=vision_enabled)
         else:
             # some providers, like HF and Groq/llama, don't support a list here, but a
             # single string
@@ -294,7 +332,7 @@ class Message(BaseModel):
             message_dict["name"] = self.name
 
         # Required for model like kimi-k2-thinking
-        if self.send_reasoning_content and self.reasoning_content:
+        if send_reasoning_content and self.reasoning_content:
             message_dict["reasoning_content"] = self.reasoning_content
 
         return message_dict
@@ -309,7 +347,7 @@ class Message(BaseModel):
         # tool call keys are added in to_chat_dict to centralize behavior
         return message_dict
 
-    def _list_serializer(self) -> dict[str, Any]:
+    def _list_serializer(self, *, vision_enabled: bool) -> dict[str, Any]:
         content: list[dict[str, Any]] = []
         role_tool_with_prompt_caching = False
 
@@ -337,7 +375,7 @@ class Message(BaseModel):
                     d.pop("cache_control", None)
 
             # Handle vision-enabled filtering for ImageContent
-            if isinstance(item, ImageContent) and self.vision_enabled:
+            if isinstance(item, ImageContent) and vision_enabled:
                 content.extend(item_dicts)
             elif not isinstance(item, ImageContent):
                 # Add non-image content (TextContent, etc.)

openhands/sdk/llm/options/chat_options.py

@@ -71,7 +71,8 @@ def select_chat_options(
         out.pop("temperature", None)
         out.pop("top_p", None)
 
-    # Mistral / Gemini safety
+    # REMOVE_AT: 1.15.0 - Remove this block along with LLM.safety_settings field
+    # Mistral / Gemini safety (deprecated)
     if llm.safety_settings:
         ml = llm.model.lower()
         if "mistral" in ml or "gemini" in ml:

openhands/sdk/mcp/client.py

@@ -2,27 +2,53 @@
 
 import asyncio
 import inspect
-from collections.abc import Callable
-from typing import Any
+from collections.abc import Callable, Iterator
+from typing import TYPE_CHECKING, Any
 
 from fastmcp import Client as AsyncMCPClient
 
 from openhands.sdk.utils.async_executor import AsyncExecutor
 
 
+if TYPE_CHECKING:
+    from openhands.sdk.mcp.tool import MCPToolDefinition
+
+
 class MCPClient(AsyncMCPClient):
-    """
-    Behaves exactly like fastmcp.Client (same constructor & async API),
-    but owns a background event loop and offers:
+    """MCP client with sync helpers and lifecycle management.
+
+    Extends fastmcp.Client with:
       - call_async_from_sync(awaitable_or_fn, *args, timeout=None, **kwargs)
       - call_sync_from_async(fn, *args, **kwargs)  # await this from async code
+
+    After create_mcp_tools() populates it, use as a sync context manager:
+
+        with create_mcp_tools(config) as client:
+            for tool in client.tools:
+                # use tool
+        # Connection automatically closed
+
+    Or manage lifecycle manually by calling sync_close() when done.
     """
 
     _executor: AsyncExecutor
+    _closed: bool
+    _tools: "list[MCPToolDefinition]"
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self._executor = AsyncExecutor()
+        self._closed = False
+        self._tools = []
+
+    @property
+    def tools(self) -> "list[MCPToolDefinition]":
+        """The MCP tools using this client connection (returns a copy)."""
+        return list(self._tools)
+
+    async def connect(self) -> None:
+        """Establish connection to the MCP server."""
+        await self.__aenter__()
 
     def call_async_from_sync(
         self,
@@ -56,8 +82,11 @@ class MCPClient(AsyncMCPClient):
         Synchronously close the MCP client and cleanup resources.
 
         This will attempt to call the async close() method if available,
-        then shutdown the background event loop.
+        then shutdown the background event loop. Safe to call multiple times.
         """
+        if self._closed:
+            return
+
         # Best-effort: try async close if parent provides it
         if hasattr(self, "close") and inspect.iscoroutinefunction(self.close):
             try:
@@ -67,6 +96,7 @@ class MCPClient(AsyncMCPClient):
 
         # Always cleanup the executor
         self._executor.close()
+        self._closed = True
 
     def __del__(self):
         """Cleanup on deletion."""
@@ -74,3 +104,20 @@ class MCPClient(AsyncMCPClient):
             self.sync_close()
         except Exception:
             pass  # Ignore cleanup errors during deletion
+
+    # Sync context manager support
+    def __enter__(self) -> "MCPClient":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.sync_close()
+
+    # Iteration support for tools
+    def __iter__(self) -> "Iterator[MCPToolDefinition]":
+        return iter(self._tools)
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __getitem__(self, index: int) -> "MCPToolDefinition":
+        return self._tools[index]

openhands/sdk/mcp/tool.py

@@ -52,27 +52,30 @@ class MCPToolExecutor(ToolExecutor):
 
     @observe(name="MCPToolExecutor.call_tool", span_type="TOOL")
     async def call_tool(self, action: MCPToolAction) -> MCPToolObservation:
-        async with self.client:
-            assert self.client.is_connected(), "MCP client is not connected."
-            try:
-                logger.debug(
-                    f"Calling MCP tool {self.tool_name} "
-                    f"with args: {action.model_dump()}"
-                )
-                result: mcp.types.CallToolResult = await self.client.call_tool_mcp(
-                    name=self.tool_name, arguments=action.to_mcp_arguments()
-                )
-                return MCPToolObservation.from_call_tool_result(
-                    tool_name=self.tool_name, result=result
-                )
-            except Exception as e:
-                error_msg = f"Error calling MCP tool {self.tool_name}: {str(e)}"
-                logger.error(error_msg, exc_info=True)
-                return MCPToolObservation.from_text(
-                    text=error_msg,
-                    is_error=True,
-                    tool_name=self.tool_name,
-                )
+        """Execute the MCP tool call using the already-connected client."""
+        if not self.client.is_connected():
+            raise RuntimeError(
+                f"MCP client not connected for tool '{self.tool_name}'. "
+                "The connection may have been closed or failed to establish."
+            )
+        try:
+            logger.debug(
+                f"Calling MCP tool {self.tool_name} with args: {action.model_dump()}"
+            )
+            result: mcp.types.CallToolResult = await self.client.call_tool_mcp(
+                name=self.tool_name, arguments=action.to_mcp_arguments()
+            )
+            return MCPToolObservation.from_call_tool_result(
+                tool_name=self.tool_name, result=result
+            )
+        except Exception as e:
+            error_msg = f"Error calling MCP tool {self.tool_name}: {str(e)}"
+            logger.error(error_msg, exc_info=True)
+            return MCPToolObservation.from_text(
+                text=error_msg,
+                is_error=True,
+                tool_name=self.tool_name,
+            )
 
     def __call__(
         self,