openhands-sdk 1.5.1__tar.gz → 1.10.0__tar.gz

{openhands_sdk-1.5.1 → openhands_sdk-1.10.0}/PKG-INFO

@@ -1,17 +1,22 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.5.1
+Version: 1.10.0
 Summary: OpenHands SDK - Core functionality for building AI agents
+Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
+Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk
+Project-URL: Documentation, https://docs.openhands.dev/sdk
+Project-URL: Bug Tracker, https://github.com/OpenHands/software-agent-sdk/issues
 Requires-Python: >=3.12
 Requires-Dist: deprecation>=2.1.0
 Requires-Dist: fastmcp>=2.11.3
+Requires-Dist: filelock>=3.20.1
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: litellm>=1.80.7
-Requires-Dist: pydantic>=2.11.7
+Requires-Dist: litellm>=1.80.10
+Requires-Dist: pydantic>=2.12.5
 Requires-Dist: python-frontmatter>=1.1.0
 Requires-Dist: python-json-logger>=3.3.0
 Requires-Dist: tenacity>=9.1.2
 Requires-Dist: websockets>=12
-Requires-Dist: lmnr>=0.7.20
+Requires-Dist: lmnr>=0.7.24
 Provides-Extra: boto3
 Requires-Dist: boto3>=1.35.0; extra == "boto3"

{openhands_sdk-1.5.1 → openhands_sdk-1.10.0}/openhands/sdk/__init__.py

@@ -1,7 +1,12 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from openhands.sdk.agent import Agent, AgentBase
-from openhands.sdk.context import AgentContext
+from openhands.sdk.context import (
+    AgentContext,
+    load_project_skills,
+    load_skills_from_dir,
+    load_user_skills,
+)
 from openhands.sdk.context.condenser import (
     LLMSummarizingCondenser,
 )
@@ -36,6 +41,7 @@ from openhands.sdk.mcp import (
     MCPToolObservation,
     create_mcp_tools,
 )
+from openhands.sdk.plugin import Plugin
 from openhands.sdk.tool import (
     Action,
     Observation,
@@ -93,11 +99,15 @@ __all__ = [
     "LLMSummarizingCondenser",
     "FileStore",
     "LocalFileStore",
+    "Plugin",
     "register_tool",
     "resolve_tool",
     "list_registered_tools",
     "Workspace",
     "LocalWorkspace",
     "RemoteWorkspace",
+    "load_project_skills",
+    "load_skills_from_dir",
+    "load_user_skills",
     "__version__",
 ]

{openhands_sdk-1.5.1 → openhands_sdk-1.10.0}/openhands/sdk/agent/agent.py

@@ -17,6 +17,7 @@ from openhands.sdk.conversation import (
     LocalConversation,
 )
 from openhands.sdk.conversation.state import ConversationExecutionStatus
+from openhands.sdk.critic.base import CriticResult
 from openhands.sdk.event import (
     ActionEvent,
     AgentErrorEvent,
@@ -25,8 +26,12 @@ from openhands.sdk.event import (
     ObservationEvent,
     SystemPromptEvent,
     TokenEvent,
+    UserRejectObservation,
+)
+from openhands.sdk.event.condenser import (
+    Condensation,
+    CondensationRequest,
 )
-from openhands.sdk.event.condenser import Condensation, CondensationRequest
 from openhands.sdk.llm import (
     LLMResponse,
     Message,
@@ -101,27 +106,103 @@ class Agent(AgentBase):
         # TODO(openhands): we should add test to test this init_state will actually
         # modify state in-place
 
-        llm_convertible_messages = [
-            event for event in state.events if isinstance(event, LLMConvertibleEvent)
-        ]
-        if len(llm_convertible_messages) == 0:
-            # Prepare system message
-            event = SystemPromptEvent(
-                source="agent",
-                system_prompt=TextContent(text=self.system_message),
-                # Always expose a 'security_risk' parameter in tool schemas.
-                # This ensures the schema remains consistent, even if the
-                # security analyzer is disabled. Validation of this field
-                # happens dynamically at runtime depending on the analyzer
-                # configured. This allows weaker models to omit risk field
-                # and bypass validation requirements when analyzer is disabled.
-                # For detailed logic, see `_extract_security_risk` method.
-                tools=[
-                    t.to_openai_tool(add_security_risk_prediction=True)
-                    for t in self.tools_map.values()
-                ],
+        # Defensive check: Analyze state to detect unexpected initialization scenarios
+        # These checks help diagnose issues related to lazy loading and event ordering
+        # See: https://github.com/OpenHands/software-agent-sdk/issues/1785
+        events = list(state.events)
+        has_system_prompt = any(isinstance(e, SystemPromptEvent) for e in events)
+        has_user_message = any(
+            isinstance(e, MessageEvent) and e.source == "user" for e in events
+        )
+        has_any_llm_event = any(isinstance(e, LLMConvertibleEvent) for e in events)
+
+        # Log state for debugging initialization order issues
+        logger.debug(
+            f"init_state called: conversation_id={state.id}, "
+            f"event_count={len(events)}, "
+            f"has_system_prompt={has_system_prompt}, "
+            f"has_user_message={has_user_message}, "
+            f"has_any_llm_event={has_any_llm_event}"
+        )
+
+        if has_system_prompt:
+            # SystemPromptEvent already exists - this is unexpected during normal flow
+            # but could happen in persistence/resume scenarios
+            logger.warning(
+                f"init_state called but SystemPromptEvent already exists. "
+                f"conversation_id={state.id}, event_count={len(events)}. "
+                f"This may indicate double initialization or a resume scenario."
             )
-            on_event(event)
+            return
+
+        # Assert: If there are user messages but no system prompt, something is wrong
+        # The system prompt should always be added before any user messages
+        if has_user_message:
+            event_types = [type(e).__name__ for e in events]
+            logger.error(
+                f"init_state: User message exists without SystemPromptEvent! "
+                f"conversation_id={state.id}, events={event_types}"
+            )
+            assert not has_user_message, (
+                f"Unexpected state: User message exists before SystemPromptEvent. "
+                f"conversation_id={state.id}, event_count={len(events)}, "
+                f"event_types={event_types}. "
+                f"This indicates an initialization order bug - init_state should be "
+                f"called before any user messages are added to the conversation."
+            )
+
+        # Prepare system message
+        event = SystemPromptEvent(
+            source="agent",
+            system_prompt=TextContent(text=self.system_message),
+            # Tools are stored as ToolDefinition objects and converted to
+            # OpenAI format with security_risk parameter during LLM completion.
+            # See make_llm_completion() in agent/utils.py for details.
+            tools=list(self.tools_map.values()),
+        )
+        on_event(event)
+
+    def _should_evaluate_with_critic(self, action: Action | None) -> bool:
+        """Determine if critic should evaluate based on action type and mode."""
+        if self.critic is None:
+            return False
+
+        if self.critic.mode == "all_actions":
+            return True
+
+        # For "finish_and_message" mode, only evaluate FinishAction
+        # (MessageEvent will be handled separately in step())
+        if isinstance(action, FinishAction):
+            return True
+
+        return False
+
+    def _evaluate_with_critic(
+        self, conversation: LocalConversation, event: ActionEvent | MessageEvent
+    ) -> CriticResult | None:
+        """Run critic evaluation on the current event and history."""
+        if self.critic is None:
+            return None
+
+        try:
+            # Build event history including the current event
+            events = list(conversation.state.events) + [event]
+            llm_convertible_events = [
+                e for e in events if isinstance(e, LLMConvertibleEvent)
+            ]
+
+            # Evaluate without git_patch for now
+            critic_result = self.critic.evaluate(
+                events=llm_convertible_events, git_patch=None
+            )
+            logger.info(
+                f"✓ Critic evaluation: score={critic_result.score:.3f}, "
+                f"success={critic_result.success}"
+            )
+            return critic_result
+        except Exception as e:
+            logger.error(f"✗ Critic evaluation failed: {e}", exc_info=True)
+            return None
 
     def _execute_actions(
         self,
@@ -151,9 +232,20 @@ class Agent(AgentBase):
             self._execute_actions(conversation, pending_actions, on_event)
             return
 
+        # Check if the last user message was blocked by a UserPromptSubmit hook
+        # If so, skip processing and mark conversation as finished
+        for event in reversed(list(state.events)):
+            if isinstance(event, MessageEvent) and event.source == "user":
+                reason = state.pop_blocked_message(event.id)
+                if reason is not None:
+                    logger.info(f"User message blocked by hook: {reason}")
+                    state.execution_status = ConversationExecutionStatus.FINISHED
+                    return
+                break  # Only check the most recent user message
+
         # Prepare LLM messages using the utility function
         _messages_or_condensation = prepare_llm_messages(
-            state.events, condenser=self.condenser
+            state.events, condenser=self.condenser, llm=self.llm
         )
 
         # Process condensation event before agent sampels another action
@@ -229,6 +321,7 @@ class Agent(AgentBase):
             for i, tool_call in enumerate(message.tool_calls):
                 action_event = self._get_action_event(
                     tool_call,
+                    conversation=conversation,
                     llm_response_id=llm_response.id,
                     on_event=on_event,
                     security_analyzer=state.security_analyzer,
@@ -267,6 +360,14 @@ class Agent(AgentBase):
             llm_message=message,
             llm_response_id=llm_response.id,
         )
+        # Run critic evaluation if configured for finish_and_message mode
+        if self.critic is not None and self.critic.mode == "finish_and_message":
+            critic_result = self._evaluate_with_critic(conversation, msg_event)
+            if critic_result is not None:
+                # Create new event with critic result
+                msg_event = msg_event.model_copy(
+                    update={"critic_result": critic_result}
+                )
         on_event(msg_event)
 
         # Emit VLLM token ids if enabled
@@ -354,9 +455,34 @@ class Agent(AgentBase):
         security_risk = risk.SecurityRisk(raw)
         return security_risk
 
+    def _extract_summary(self, tool_name: str, arguments: dict) -> str:
+        """Extract and validate the summary field from tool arguments.
+
+        Summary field is always requested but optional - if LLM doesn't provide
+        it or provides invalid data, we generate a default summary using the
+        tool name and arguments.
+
+        Args:
+            tool_name: Name of the tool being called
+            arguments: Dictionary of tool arguments from LLM
+
+        Returns:
+            The summary string - either from LLM or a default generated one
+        """
+        summary = arguments.pop("summary", None)
+
+        # If valid summary provided by LLM, use it
+        if summary is not None and isinstance(summary, str) and summary.strip():
+            return summary
+
+        # Generate default summary: {tool_name}: {arguments}
+        args_str = json.dumps(arguments)
+        return f"{tool_name}: {args_str}"
+
     def _get_action_event(
         self,
         tool_call: MessageToolCall,
+        conversation: LocalConversation,
         llm_response_id: str,
         on_event: ConversationCallbackType,
         security_analyzer: analyzer.SecurityAnalyzerBase | None = None,
@@ -415,6 +541,8 @@ class Agent(AgentBase):
                 "Unexpected 'security_risk' key found in tool arguments"
             )
 
+            summary = self._extract_summary(tool.name, arguments)
+
             action: Action = tool.action_from_arguments(arguments)
         except (json.JSONDecodeError, ValidationError, ValueError) as e:
             err = (
@@ -443,6 +571,7 @@ class Agent(AgentBase):
             on_event(event)
             return
 
+        # Create initial action event
         action_event = ActionEvent(
             action=action,
             thought=thought or [],
@@ -454,7 +583,18 @@ class Agent(AgentBase):
             tool_call=tool_call,
             llm_response_id=llm_response_id,
             security_risk=security_risk,
+            summary=summary,
         )
+
+        # Run critic evaluation if configured
+        if self._should_evaluate_with_critic(action):
+            critic_result = self._evaluate_with_critic(conversation, action_event)
+            if critic_result is not None:
+                # Create new event with critic result
+                action_event = action_event.model_copy(
+                    update={"critic_result": critic_result}
+                )
+
         on_event(action_event)
         return action_event
 
@@ -469,8 +609,26 @@ class Agent(AgentBase):
 
         It will call the tool's executor and update the state & call callback fn
         with the observation.
+
+        If the action was blocked by a PreToolUse hook (recorded in
+        state.blocked_actions), a UserRejectObservation is emitted instead
+        of executing the action.
         """
         state = conversation.state
+
+        # Check if this action was blocked by a PreToolUse hook
+        reason = state.pop_blocked_action(action_event.id)
+        if reason is not None:
+            logger.info(f"Action '{action_event.tool_name}' blocked by hook: {reason}")
+            rejection = UserRejectObservation(
+                action_id=action_event.id,
+                tool_name=action_event.tool_name,
+                tool_call_id=action_event.tool_call_id,
+                rejection_reason=reason,
+            )
+            on_event(rejection)
+            return rejection
+
         tool = self.tools_map.get(action_event.tool_name, None)
         if tool is None:
             raise RuntimeError(
@@ -479,16 +637,29 @@ class Agent(AgentBase):
             )
 
         # Execute actions!
-        if should_enable_observability():
-            tool_name = extract_action_name(action_event)
-            observation: Observation = observe(name=tool_name, span_type="TOOL")(tool)(
-                action_event.action, conversation
+        try:
+            if should_enable_observability():
+                tool_name = extract_action_name(action_event)
+                observation: Observation = observe(name=tool_name, span_type="TOOL")(
+                    tool
+                )(action_event.action, conversation)
+            else:
+                observation = tool(action_event.action, conversation)
+            assert isinstance(observation, Observation), (
+                f"Tool '{tool.name}' executor must return an Observation"
             )
-        else:
-            observation = tool(action_event.action, conversation)
-        assert isinstance(observation, Observation), (
-            f"Tool '{tool.name}' executor must return an Observation"
-        )
+        except ValueError as e:
+            # Tool execution raised a ValueError (e.g., invalid argument combination)
+            # Convert to AgentErrorEvent so the agent can correct itself
+            err = f"Error executing tool '{tool.name}': {e}"
+            logger.warning(err)
+            error_event = AgentErrorEvent(
+                error=err,
+                tool_name=tool.name,
+                tool_call_id=action_event.tool_call.id,
+            )
+            on_event(error_event)
+            return error_event
 
         obs_event = ObservationEvent(
             observation=observation,