openhands-sdk 1.7.4__py3-none-any.whl → 1.8.1__py3-none-any.whl

openhands/sdk/git/utils.py

@@ -73,6 +73,28 @@ def run_git_command(args: list[str], cwd: str | Path) -> str:
         ) from e
 
 
+def _repo_has_commits(repo_dir: str | Path) -> bool:
+    """Check if a git repository has any commits.
+
+    Uses 'git rev-list --count --all' which returns "0" for empty repos
+    without failing, avoiding ERROR logs for expected conditions.
+
+    Args:
+        repo_dir: Path to the git repository
+
+    Returns:
+        True if the repository has at least one commit, False otherwise
+    """
+    try:
+        count = run_git_command(
+            ["git", "--no-pager", "rev-list", "--count", "--all"], repo_dir
+        )
+        return count.strip() != "0"
+    except GitCommandError:
+        logger.debug("Could not check commit count")
+        return False
+
+
 def get_valid_ref(repo_dir: str | Path) -> str | None:
     """Get a valid git reference to compare against.
 
@@ -90,6 +112,12 @@ def get_valid_ref(repo_dir: str | Path) -> str | None:
     """
     refs_to_try = []
 
+    # Check if repo has any commits first. Empty repos (created with git init)
+    # won't have commits or remotes, so we can skip directly to the empty tree fallback.
+    if not _repo_has_commits(repo_dir):
+        logger.debug("Repository has no commits yet, using empty tree reference")
+        return GIT_EMPTY_TREE_HASH
+
     # Try current branch's origin
     try:
         current_branch = run_git_command(
@@ -136,10 +164,6 @@ def get_valid_ref(repo_dir: str | Path) -> str | None:
     except GitCommandError:
         logger.debug("Could not get remote information")
 
-    # Add empty tree as fallback for new repositories
-    refs_to_try.append(GIT_EMPTY_TREE_HASH)
-    logger.debug(f"Added empty tree reference: {GIT_EMPTY_TREE_HASH}")
-
     # Find the first valid reference
     for ref in refs_to_try:
         try:
@@ -153,8 +177,9 @@ def get_valid_ref(repo_dir: str | Path) -> str | None:
             logger.debug(f"Reference not valid: {ref}")
             continue
 
-    logger.warning("No valid git reference found")
-    return None
+    # Fallback to empty tree hash (always valid, no verification needed)
+    logger.debug(f"Using empty tree reference: {GIT_EMPTY_TREE_HASH}")
+    return GIT_EMPTY_TREE_HASH
 
 
 def validate_git_repository(repo_dir: str | Path) -> Path:

openhands/sdk/hooks/conversation_hooks.py

@@ -6,6 +6,7 @@ from openhands.sdk.event import ActionEvent, Event, MessageEvent, ObservationEve
 from openhands.sdk.hooks.config import HookConfig
 from openhands.sdk.hooks.manager import HookManager
 from openhands.sdk.hooks.types import HookEventType
+from openhands.sdk.llm import TextContent
 from openhands.sdk.logger import get_logger
 
 
@@ -41,6 +42,9 @@ class HookEventProcessor:
 
     def on_event(self, event: Event) -> None:
         """Process an event and run appropriate hooks."""
+        # Track the event to pass to callbacks (may be modified by hooks)
+        callback_event = event
+
         # Run PreToolUse hooks for action events
         if isinstance(event, ActionEvent) and event.action is not None:
             self._handle_pre_tool_use(event)
@@ -51,11 +55,11 @@ class HookEventProcessor:
 
         # Run UserPromptSubmit hooks for user messages
         if isinstance(event, MessageEvent) and event.source == "user":
-            self._handle_user_prompt_submit(event)
+            callback_event = self._handle_user_prompt_submit(event)
 
-        # Call original callback
+        # Call original callback with (possibly modified) event
         if self.original_callback:
-            self.original_callback(event)
+            self.original_callback(callback_event)
 
     def _handle_pre_tool_use(self, event: ActionEvent) -> None:
         """Handle PreToolUse hooks. Blocked actions are marked in conversation state."""
@@ -141,16 +145,18 @@ class HookEventProcessor:
             if result.error:
                 logger.warning(f"PostToolUse hook error: {result.error}")
 
-    def _handle_user_prompt_submit(self, event: MessageEvent) -> None:
-        """Handle UserPromptSubmit hooks before processing a user message."""
+    def _handle_user_prompt_submit(self, event: MessageEvent) -> MessageEvent:
+        """Handle UserPromptSubmit hooks before processing a user message.
+
+        Returns the (possibly modified) event. If hooks inject additional_context,
+        a new MessageEvent is created with the context appended to extended_content.
+        """
         if not self.hook_manager.has_hooks(HookEventType.USER_PROMPT_SUBMIT):
-            return
+            return event
 
         # Extract message text
         message = ""
         if event.llm_message and event.llm_message.content:
-            from openhands.sdk.llm import TextContent
-
             for content in event.llm_message.content:
                 if isinstance(content, TextContent):
                     message += content.text
@@ -175,9 +181,23 @@ class HookEventProcessor:
                     "after creating the Conversation."
                 )
 
-        # TODO: Inject additional_context into the message
+        # Inject additional_context into extended_content
         if additional_context:
-            logger.info(f"Hook injected context: {additional_context[:100]}...")
+            logger.debug(f"Hook injecting context: {additional_context[:100]}...")
+            new_extended_content = list(event.extended_content) + [
+                TextContent(text=additional_context)
+            ]
+            # MessageEvent is frozen, so create a new one
+            event = MessageEvent(
+                source=event.source,
+                llm_message=event.llm_message,
+                llm_response_id=event.llm_response_id,
+                activated_skills=event.activated_skills,
+                extended_content=new_extended_content,
+                sender=event.sender,
+            )
+
+        return event
 
     def is_action_blocked(self, action_id: str) -> bool:
         """Check if an action was blocked by a hook."""
@@ -205,6 +225,33 @@ class HookEventProcessor:
             if r.error:
                 logger.warning(f"SessionEnd hook error: {r.error}")
 
+    def run_stop(self, reason: str | None = None) -> tuple[bool, str | None]:
+        """Run Stop hooks. Returns (should_stop, feedback)."""
+        if not self.hook_manager.has_hooks(HookEventType.STOP):
+            return True, None
+
+        should_stop, results = self.hook_manager.run_stop(reason=reason)
+
+        # Log any errors
+        for r in results:
+            if r.error:
+                logger.warning(f"Stop hook error: {r.error}")
+
+        # Collect feedback if denied
+        feedback = None
+        if not should_stop:
+            reason_text = self.hook_manager.get_blocking_reason(results)
+            logger.info(f"Stop hook denied stopping: {reason_text}")
+            feedback_parts = [
+                r.additional_context for r in results if r.additional_context
+            ]
+            if feedback_parts:
+                feedback = "\n".join(feedback_parts)
+            elif reason_text:
+                feedback = reason_text
+
+        return should_stop, feedback
+
 
 def create_hook_callback(
     hook_config: HookConfig | None = None,

openhands/sdk/llm/llm.py

@@ -28,8 +28,6 @@ from openhands.sdk.utils.pydantic_secrets import serialize_secret, validate_secr
 if TYPE_CHECKING:  # type hints only, avoid runtime import cycle
     from openhands.sdk.tool.tool import ToolDefinition
 
-from openhands.sdk.utils.pydantic_diff import pretty_pydantic_diff
-
 
 with warnings.catch_warnings():
     warnings.simplefilter("ignore")
@@ -139,7 +137,12 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     retry_min_wait: int = Field(default=8, ge=0)
     retry_max_wait: int = Field(default=64, ge=0)
 
-    timeout: int | None = Field(default=None, ge=0, description="HTTP timeout (s).")
+    timeout: int | None = Field(
+        default=300,
+        ge=0,
+        description="HTTP timeout in seconds. Default is 300s (5 minutes). "
+        "Set to None to disable timeout (not recommended for production).",
+    )
 
     max_message_chars: int = Field(
         default=30_000,
@@ -322,19 +325,6 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         exclude=True,
     )
     _metrics: Metrics | None = PrivateAttr(default=None)
-    # ===== Plain class vars (NOT Fields) =====
-    # When serializing, these fields (SecretStr) will be dump to "****"
-    # When deserializing, these fields will be ignored and we will override
-    # them from the LLM instance provided at runtime.
-    OVERRIDE_ON_SERIALIZE: tuple[str, ...] = (
-        "api_key",
-        "aws_access_key_id",
-        "aws_secret_access_key",
-        # Dynamic runtime metadata for telemetry/routing that can differ across sessions
-        # and should not cause resume-time diffs. Always prefer the runtime value.
-        "litellm_extra_body",
-    )
-
     # Runtime-only private attrs
     _model_info: Any = PrivateAttr(default=None)
     _tokenizer: Any = PrivateAttr(default=None)
@@ -498,9 +488,21 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         This is the method for getting responses from the model via Completion API.
         It handles message formatting, tool calling, and response processing.
 
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of tools available to the model
+            _return_metrics: Whether to return usage metrics
+            add_security_risk_prediction: Add security_risk field to tool schemas
+            on_token: Optional callback for streaming tokens
+            **kwargs: Additional arguments passed to the LLM API
+
         Returns:
             LLMResponse containing the model's response and metadata.
 
+        Note:
+            Summary field is always added to tool schemas for transparency and
+            explainability of agent actions.
+
         Raises:
             ValueError: If streaming is requested (not supported).
 
@@ -528,7 +530,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         if tools:
             cc_tools = [
                 t.to_openai_tool(
-                    add_security_risk_prediction=add_security_risk_prediction
+                    add_security_risk_prediction=add_security_risk_prediction,
                 )
                 for t in tools
             ]
@@ -550,18 +552,20 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         # Behavior-preserving: delegate to select_chat_options
         call_kwargs = select_chat_options(self, kwargs, has_tools=has_tools_flag)
 
-        # 4) optional request logging context (kept small)
+        # 4) request context for telemetry (always include context_window for metrics)
         assert self._telemetry is not None
-        log_ctx = None
+        # Always pass context_window so metrics are tracked even when logging disabled
+        telemetry_ctx: dict[str, Any] = {"context_window": self.max_input_tokens or 0}
         if self._telemetry.log_enabled:
-            log_ctx = {
-                "messages": formatted_messages[:],  # already simple dicts
-                "tools": tools,
-                "kwargs": {k: v for k, v in call_kwargs.items()},
-                "context_window": self.max_input_tokens or 0,
-            }
+            telemetry_ctx.update(
+                {
+                    "messages": formatted_messages[:],  # already simple dicts
+                    "tools": tools,
+                    "kwargs": {k: v for k, v in call_kwargs.items()},
+                }
+            )
             if tools and not use_native_fc:
-                log_ctx["raw_messages"] = original_fncall_msgs
+                telemetry_ctx["raw_messages"] = original_fncall_msgs
 
         # 5) do the call with retries
         @self.retry_decorator(
@@ -574,7 +578,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         )
         def _one_attempt(**retry_kwargs) -> ModelResponse:
             assert self._telemetry is not None
-            self._telemetry.on_request(log_ctx=log_ctx)
+            self._telemetry.on_request(telemetry_ctx=telemetry_ctx)
             # Merge retry-modified kwargs (like temperature) with call_kwargs
             final_kwargs = {**call_kwargs, **retry_kwargs}
             resp = self._transport_call(
@@ -645,6 +649,20 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         """Alternative invocation path using OpenAI Responses API via LiteLLM.
 
         Maps Message[] -> (instructions, input[]) and returns LLMResponse.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of tools available to the model
+            include: Optional list of fields to include in response
+            store: Whether to store the conversation
+            _return_metrics: Whether to return usage metrics
+            add_security_risk_prediction: Add security_risk field to tool schemas
+            on_token: Optional callback for streaming tokens (not yet supported)
+            **kwargs: Additional arguments passed to the API
+
+        Note:
+            Summary field is always added to tool schemas for transparency and
+            explainability of agent actions.
         """
         # Streaming not yet supported
         if kwargs.get("stream", False) or self.stream or on_token is not None:
@@ -658,7 +676,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         resp_tools = (
             [
                 t.to_responses_tool(
-                    add_security_risk_prediction=add_security_risk_prediction
+                    add_security_risk_prediction=add_security_risk_prediction,
                 )
                 for t in tools
             ]
@@ -671,17 +689,19 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
             self, kwargs, include=include, store=store
         )
 
-        # Optional request logging
+        # Request context for telemetry (always include context_window for metrics)
         assert self._telemetry is not None
-        log_ctx = None
+        # Always pass context_window so metrics are tracked even when logging disabled
+        telemetry_ctx: dict[str, Any] = {"context_window": self.max_input_tokens or 0}
         if self._telemetry.log_enabled:
-            log_ctx = {
-                "llm_path": "responses",
-                "input": input_items[:],
-                "tools": tools,
-                "kwargs": {k: v for k, v in call_kwargs.items()},
-                "context_window": self.max_input_tokens or 0,
-            }
+            telemetry_ctx.update(
+                {
+                    "llm_path": "responses",
+                    "input": input_items[:],
+                    "tools": tools,
+                    "kwargs": {k: v for k, v in call_kwargs.items()},
+                }
+            )
 
         # Perform call with retries
         @self.retry_decorator(
@@ -694,7 +714,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         )
         def _one_attempt(**retry_kwargs) -> ResponsesAPIResponse:
             assert self._telemetry is not None
-            self._telemetry.on_request(log_ctx=log_ctx)
+            self._telemetry.on_request(telemetry_ctx=telemetry_ctx)
             final_kwargs = {**call_kwargs, **retry_kwargs}
             with self._litellm_modify_params_ctx(self.modify_params):
                 with warnings.catch_warnings():
@@ -1101,39 +1121,3 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
             if v is not None:
                 data[field_name] = v
         return cls(**data)
-
-    def resolve_diff_from_deserialized(self, persisted: LLM) -> LLM:
-        """Resolve differences between a deserialized LLM and the current instance.
-
-        This is due to fields like api_key being serialized to "****" in dumps,
-        and we want to ensure that when loading from a file, we still use the
-        runtime-provided api_key in the self instance.
-
-        Return a new LLM instance equivalent to `persisted` but with
-        explicitly whitelisted fields (e.g. api_key) taken from `self`.
-        """
-        if persisted.__class__ is not self.__class__:
-            raise ValueError(
-                f"Cannot resolve_diff_from_deserialized between {self.__class__} "
-                f"and {persisted.__class__}"
-            )
-
-        # Copy allowed fields from runtime llm into the persisted llm
-        llm_updates = {}
-        persisted_dump = persisted.model_dump(context={"expose_secrets": True})
-        for field in self.OVERRIDE_ON_SERIALIZE:
-            if field in persisted_dump.keys():
-                llm_updates[field] = getattr(self, field)
-        if llm_updates:
-            reconciled = persisted.model_copy(update=llm_updates)
-        else:
-            reconciled = persisted
-
-        dump = self.model_dump(context={"expose_secrets": True})
-        reconciled_dump = reconciled.model_dump(context={"expose_secrets": True})
-        if dump != reconciled_dump:
-            raise ValueError(
-                "The LLM provided is different from the one in persisted state.\n"
-                f"Diff: {pretty_pydantic_diff(self, reconciled)}"
-            )
-        return reconciled

openhands/sdk/llm/router/base.py

@@ -59,6 +59,18 @@ class RouterLLM(LLM):
         """
         This method intercepts completion calls and routes them to the appropriate
         underlying LLM based on the routing logic implemented in select_llm().
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of tools available to the model
+            return_metrics: Whether to return usage metrics
+            add_security_risk_prediction: Add security_risk field to tool schemas
+            on_token: Optional callback for streaming tokens
+            **kwargs: Additional arguments passed to the LLM API
+
+        Note:
+            Summary field is always added to tool schemas for transparency and
+            explainability of agent actions.
         """
         # Select appropriate LLM
         selected_model = self.select_llm(messages)

openhands/sdk/llm/utils/telemetry.py

@@ -73,9 +73,9 @@ class Telemetry(BaseModel):
         """
         self._stats_update_callback = callback
 
-    def on_request(self, log_ctx: dict | None) -> None:
+    def on_request(self, telemetry_ctx: dict | None) -> None:
         self._req_start = time.time()
-        self._req_ctx = log_ctx or {}
+        self._req_ctx = telemetry_ctx or {}
 
     def on_response(
         self,

openhands/sdk/plugin/__init__.py

@@ -0,0 +1,22 @@
+"""Plugin module for OpenHands SDK.
+
+This module provides support for loading and managing plugins that bundle
+skills, hooks, MCP configurations, agents, and commands together.
+"""
+
+from openhands.sdk.plugin.plugin import Plugin
+from openhands.sdk.plugin.types import (
+    AgentDefinition,
+    CommandDefinition,
+    PluginAuthor,
+    PluginManifest,
+)
+
+
+__all__ = [
+    "Plugin",
+    "PluginManifest",
+    "PluginAuthor",
+    "AgentDefinition",
+    "CommandDefinition",
+]