openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/security/analyzer.py

@@ -0,0 +1,111 @@
+from abc import ABC, abstractmethod
+
+from openhands.sdk.event.base import Event
+from openhands.sdk.event.llm_convertible import ActionEvent
+from openhands.sdk.logger import get_logger
+from openhands.sdk.security.risk import SecurityRisk
+from openhands.sdk.utils.models import (
+    DiscriminatedUnionMixin,
+)
+
+
+logger = get_logger(__name__)
+
+
+class SecurityAnalyzerBase(DiscriminatedUnionMixin, ABC):
+    """Abstract base class for security analyzers.
+
+    Security analyzers evaluate the risk of actions before they are executed
+    and can influence the conversation flow based on security policies.
+
+    This is adapted from OpenHands SecurityAnalyzer but designed to work
+    with the agent-sdk's conversation-based architecture.
+    """
+
+    @abstractmethod
+    def security_risk(self, action: ActionEvent) -> SecurityRisk:
+        """Evaluate the security risk of an ActionEvent.
+
+        This is the core method that analyzes an ActionEvent and returns its risk level.
+        Implementations should examine the action's content, context, and potential
+        impact to determine the appropriate risk level.
+
+        Args:
+            action: The ActionEvent to analyze for security risks
+
+        Returns:
+            ActionSecurityRisk enum indicating the risk level
+        """
+        pass
+
+    def analyze_event(self, event: Event) -> SecurityRisk | None:
+        """Analyze an event for security risks.
+
+        This is a convenience method that checks if the event is an action
+        and calls security_risk() if it is. Non-action events return None.
+
+        Args:
+            event: The event to analyze
+
+        Returns:
+            ActionSecurityRisk if event is an action, None otherwise
+        """
+        if isinstance(event, ActionEvent):
+            return self.security_risk(event)
+        return None
+
+    def should_require_confirmation(
+        self, risk: SecurityRisk, confirmation_mode: bool = False
+    ) -> bool:
+        """Determine if an action should require user confirmation.
+
+        This implements the default confirmation logic based on risk level
+        and confirmation mode settings.
+
+        Args:
+            risk: The security risk level of the action
+            confirmation_mode: Whether confirmation mode is enabled
+
+        Returns:
+            True if confirmation is required, False otherwise
+        """
+        if risk == SecurityRisk.HIGH:
+            # HIGH risk actions always require confirmation
+            return True
+        elif risk == SecurityRisk.UNKNOWN and not confirmation_mode:
+            # UNKNOWN risk requires confirmation if no security analyzer is configured
+            return True
+        elif confirmation_mode:
+            # In confirmation mode, all actions require confirmation
+            return True
+        else:
+            # LOW and MEDIUM risk actions don't require confirmation by default
+            return False
+
+    def analyze_pending_actions(
+        self, pending_actions: list[ActionEvent]
+    ) -> list[tuple[ActionEvent, SecurityRisk]]:
+        """Analyze all pending actions in a conversation.
+
+        This method gets all unmatched actions from the conversation state
+        and analyzes each one for security risks.
+
+        Args:
+            conversation: The conversation to analyze
+
+        Returns:
+            List of tuples containing (action, risk_level) for each pending action
+        """
+        analyzed_actions = []
+
+        for action_event in pending_actions:
+            try:
+                risk = self.security_risk(action_event)
+                analyzed_actions.append((action_event, risk))
+                logger.debug(f"Action {action_event} analyzed with risk level: {risk}")
+            except Exception as e:
+                logger.error(f"Error analyzing action {action_event}: {e}")
+                # Default to HIGH risk on analysis error for safety
+                analyzed_actions.append((action_event, SecurityRisk.HIGH))
+
+        return analyzed_actions

openhands/sdk/security/confirmation_policy.py

@@ -0,0 +1,61 @@
+from abc import ABC, abstractmethod
+
+from pydantic import field_validator
+
+from openhands.sdk.security.risk import SecurityRisk
+from openhands.sdk.utils.models import DiscriminatedUnionMixin
+
+
+class ConfirmationPolicyBase(DiscriminatedUnionMixin, ABC):
+    @abstractmethod
+    def should_confirm(self, risk: SecurityRisk = SecurityRisk.UNKNOWN) -> bool:
+        """Determine if an action with the given risk level requires confirmation.
+
+        This method defines the core logic for determining whether user confirmation
+        is required before executing an action based on its security risk level.
+
+        Args:
+            risk: The security risk level of the action to be evaluated.
+                 Defaults to SecurityRisk.UNKNOWN if not specified.
+
+        Returns:
+            True if the action requires user confirmation before execution,
+            False if the action can proceed without confirmation.
+        """
+
+
+class AlwaysConfirm(ConfirmationPolicyBase):
+    def should_confirm(
+        self,
+        risk: SecurityRisk = SecurityRisk.UNKNOWN,  # noqa: ARG002
+    ) -> bool:
+        return True
+
+
+class NeverConfirm(ConfirmationPolicyBase):
+    def should_confirm(
+        self,
+        risk: SecurityRisk = SecurityRisk.UNKNOWN,  # noqa: ARG002
+    ) -> bool:
+        return False
+
+
+class ConfirmRisky(ConfirmationPolicyBase):
+    threshold: SecurityRisk = SecurityRisk.HIGH
+    confirm_unknown: bool = True
+
+    @field_validator("threshold")
+    def validate_threshold(cls, v: SecurityRisk) -> SecurityRisk:
+        if v == SecurityRisk.UNKNOWN:
+            raise ValueError("Threshold cannot be UNKNOWN")
+        return v
+
+    def should_confirm(self, risk: SecurityRisk = SecurityRisk.UNKNOWN) -> bool:
+        if risk == SecurityRisk.UNKNOWN:
+            return self.confirm_unknown
+
+        # This comparison is reflexive by default, so if the threshold is HIGH we will
+        # still require confirmation for HIGH risk actions. And since the threshold is
+        # guaranteed to never be UNKNOWN (by the validator), we're guaranteed to get a
+        # boolean here.
+        return risk.is_riskier(self.threshold)

openhands/sdk/security/llm_analyzer.py

@@ -0,0 +1,29 @@
+from openhands.sdk.event import ActionEvent
+from openhands.sdk.logger import get_logger
+from openhands.sdk.security.analyzer import SecurityAnalyzerBase
+from openhands.sdk.security.risk import SecurityRisk
+
+
+logger = get_logger(__name__)
+
+
+class LLMSecurityAnalyzer(SecurityAnalyzerBase):
+    """LLM-based security analyzer.
+
+    This analyzer respects the security_risk attribute that can be set by the LLM
+    when generating actions, similar to OpenHands' LLMRiskAnalyzer.
+
+    It provides a lightweight security analysis approach that leverages the LLM's
+    understanding of action context and potential risks.
+    """
+
+    def security_risk(self, action: ActionEvent) -> SecurityRisk:
+        """Evaluate security risk based on LLM-provided assessment.
+
+        This method checks if the action has a security_risk attribute set by the LLM
+        and returns it. The LLM may not always provide this attribute but it defaults to
+        UNKNOWN if not explicitly set.
+        """
+        logger.debug(f"Analyzing security risk: {action} -- {action.security_risk}")
+
+        return action.security_risk

openhands/sdk/security/risk.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from enum import Enum
+
+from rich.text import Text
+
+
+class SecurityRisk(str, Enum):
+    """Security risk levels for actions.
+
+    Based on OpenHands security risk levels but adapted for agent-sdk.
+    Integer values allow for easy comparison and ordering.
+    """
+
+    UNKNOWN = "UNKNOWN"
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+
+    @property
+    def description(self) -> str:
+        """Get a human-readable description of the risk level."""
+        descriptions = {
+            SecurityRisk.LOW: (
+                "Low risk - Safe operation with minimal security impact"
+            ),
+            SecurityRisk.MEDIUM: (
+                "Medium risk - Moderate security impact, review recommended"
+            ),
+            SecurityRisk.HIGH: (
+                "High risk - Significant security impact, confirmation required"
+            ),
+            SecurityRisk.UNKNOWN: ("Unknown risk - Risk level could not be determined"),
+        }
+        return descriptions.get(self, "Unknown risk level")
+
+    def __str__(self) -> str:
+        return self.name
+
+    def get_color(self) -> str:
+        """Get the color for displaying this risk level in Rich text."""
+        color_map = {
+            SecurityRisk.LOW: "green",
+            SecurityRisk.MEDIUM: "yellow",
+            SecurityRisk.HIGH: "red",
+            SecurityRisk.UNKNOWN: "white",
+        }
+        return color_map.get(self, "white")
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this risk level."""
+        content = Text()
+        content.append(
+            "Predicted Security Risk: ",
+            style="bold",
+        )
+        content.append(
+            f"{self.value}\n\n",
+            style=f"bold {self.get_color()}",
+        )
+        return content
+
+    def is_riskier(self, other: SecurityRisk, reflexive: bool = True) -> bool:
+        """Check if this risk level is riskier than another.
+
+        Risk levels follow the natural ordering: LOW is less risky than MEDIUM, which is
+        less risky than HIGH. UNKNOWN is not comparable to any other level.
+
+        To make this act like a standard well-ordered domain, we reflexively consider
+        risk levels to be riskier than themselves. That is:
+
+            for risk_level in list(SecurityRisk):
+                assert risk_level.is_riskier(risk_level)
+
+            # More concretely:
+            assert SecurityRisk.HIGH.is_riskier(SecurityRisk.HIGH)
+            assert SecurityRisk.MEDIUM.is_riskier(SecurityRisk.MEDIUM)
+            assert SecurityRisk.LOW.is_riskier(SecurityRisk.LOW)
+
+        This can be disabled by setting the `reflexive` parameter to False.
+
+        Args:
+            other (SecurityRisk): The other risk level to compare against.
+            reflexive (bool): Whether the relationship is reflexive.
+
+        Raises:
+            ValueError: If either risk level is UNKNOWN.
+        """
+        if self.value == SecurityRisk.UNKNOWN or other.value == SecurityRisk.UNKNOWN:
+            raise ValueError("Cannot compare unknown risk levels.")
+
+        # Map risk levels to a well-ordered domain for comparison. No need to map
+        # UNKNOWN since we'll already have raised an error by now if either is UNKNOWN.
+        risk_order = {
+            SecurityRisk.LOW: 1,
+            SecurityRisk.MEDIUM: 2,
+            SecurityRisk.HIGH: 3,
+        }
+        return risk_order[self] > risk_order[other] or (reflexive and self == other)

openhands/sdk/tool/__init__.py

@@ -0,0 +1,34 @@
+from openhands.sdk.tool.builtins import BUILT_IN_TOOLS, FinishTool, ThinkTool
+from openhands.sdk.tool.registry import (
+    list_registered_tools,
+    register_tool,
+    resolve_tool,
+)
+from openhands.sdk.tool.schema import (
+    Action,
+    Observation,
+)
+from openhands.sdk.tool.spec import Tool
+from openhands.sdk.tool.tool import (
+    ExecutableTool,
+    ToolAnnotations,
+    ToolDefinition,
+    ToolExecutor,
+)
+
+
+__all__ = [
+    "Tool",
+    "ToolDefinition",
+    "ToolAnnotations",
+    "ToolExecutor",
+    "ExecutableTool",
+    "Action",
+    "Observation",
+    "FinishTool",
+    "ThinkTool",
+    "BUILT_IN_TOOLS",
+    "register_tool",
+    "resolve_tool",
+    "list_registered_tools",
+]

openhands/sdk/tool/builtins/__init__.py

@@ -0,0 +1,34 @@
+"""Implementing essential tools that doesn't interact with the environment.
+
+These are built in and are *required* for the agent to work.
+
+For tools that require interacting with the environment, add them to `openhands-tools`.
+"""
+
+from openhands.sdk.tool.builtins.finish import (
+    FinishAction,
+    FinishExecutor,
+    FinishObservation,
+    FinishTool,
+)
+from openhands.sdk.tool.builtins.think import (
+    ThinkAction,
+    ThinkExecutor,
+    ThinkObservation,
+    ThinkTool,
+)
+
+
+BUILT_IN_TOOLS = [FinishTool, ThinkTool]
+
+__all__ = [
+    "BUILT_IN_TOOLS",
+    "FinishTool",
+    "FinishAction",
+    "FinishObservation",
+    "FinishExecutor",
+    "ThinkTool",
+    "ThinkAction",
+    "ThinkObservation",
+    "ThinkExecutor",
+]

openhands/sdk/tool/builtins/finish.py

@@ -0,0 +1,106 @@
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Self
+
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.tool.tool import (
+    Action,
+    Observation,
+    ToolAnnotations,
+    ToolDefinition,
+    ToolExecutor,
+)
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.base import BaseConversation
+    from openhands.sdk.conversation.state import ConversationState
+
+
+class FinishAction(Action):
+    message: str = Field(description="Final message to send to the user.")
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this action."""
+        content = Text()
+        content.append("Finish with message:\n", style="bold blue")
+        content.append(self.message)
+        return content
+
+
+class FinishObservation(Observation):
+    """
+    Observation returned after finishing a task.
+    The FinishAction itself contains the message sent to the user so no
+    extra fields are needed here.
+    """
+
+    @property
+    def visualize(self) -> Text:
+        """Return an empty Text representation since the message is in the action."""
+        return Text()
+
+
+TOOL_DESCRIPTION = """Signals the completion of the current task or conversation.
+
+Use this tool when:
+- You have successfully completed the user's requested task
+- You cannot proceed further due to technical limitations or missing information
+
+The message should include:
+- A clear summary of actions taken and their results
+- Any next steps for the user
+- Explanation if you're unable to complete the task
+- Any follow-up questions if more information is needed
+"""
+
+
+class FinishExecutor(ToolExecutor):
+    def __call__(
+        self,
+        action: FinishAction,
+        conversation: "BaseConversation | None" = None,  # noqa: ARG002
+    ) -> FinishObservation:
+        return FinishObservation.from_text(text=action.message)
+
+
+class FinishTool(ToolDefinition[FinishAction, FinishObservation]):
+    """Tool for signaling the completion of a task or conversation."""
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: "ConversationState | None" = None,  # noqa: ARG003
+        **params,
+    ) -> Sequence[Self]:
+        """Create FinishTool instance.
+
+        Args:
+            conv_state: Optional conversation state (not used by FinishTool).
+            **params: Additional parameters (none supported).
+
+        Returns:
+            A sequence containing a single FinishTool instance.
+
+        Raises:
+            ValueError: If any parameters are provided.
+        """
+        if params:
+            raise ValueError("FinishTool doesn't accept parameters")
+        return [
+            cls(
+                action_type=FinishAction,
+                observation_type=FinishObservation,
+                description=TOOL_DESCRIPTION,
+                executor=FinishExecutor(),
+                annotations=ToolAnnotations(
+                    title="finish",
+                    readOnlyHint=True,
+                    destructiveHint=False,
+                    idempotentHint=True,
+                    openWorldHint=False,
+                ),
+            )
+        ]

openhands/sdk/tool/builtins/think.py

@@ -0,0 +1,117 @@
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Self
+
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.tool.tool import (
+    Action,
+    Observation,
+    ToolAnnotations,
+    ToolDefinition,
+    ToolExecutor,
+)
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.base import BaseConversation
+    from openhands.sdk.conversation.state import ConversationState
+
+
+class ThinkAction(Action):
+    """Action for logging a thought without making any changes."""
+
+    thought: str = Field(description="The thought to log.")
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation with thinking styling."""
+        content = Text()
+
+        # Add thinking icon and header
+        content.append("🤔 ", style="yellow")
+        content.append("Thinking: ", style="bold yellow")
+
+        # Add the thought content with proper formatting
+        if self.thought:
+            # Split into lines for better formatting
+            lines = self.thought.split("\n")
+            for i, line in enumerate(lines):
+                if i > 0:
+                    content.append("\n")
+                content.append(line.strip(), style="italic white")
+
+        return content
+
+
+class ThinkObservation(Observation):
+    """
+    Observation returned after logging a thought.
+    The ThinkAction itself contains the thought logged so no extra
+    fields are needed here.
+    """
+
+    @property
+    def visualize(self) -> Text:
+        """Return an empty Text representation since the thought is in the action."""
+        return Text()
+
+
+THINK_DESCRIPTION = """Use the tool to think about something. It will not obtain new information or make any changes to the repository, but just log the thought. Use it when complex reasoning or brainstorming is needed.
+
+Common use cases:
+1. When exploring a repository and discovering the source of a bug, call this tool to brainstorm several unique ways of fixing the bug, and assess which change(s) are likely to be simplest and most effective.
+2. After receiving test results, use this tool to brainstorm ways to fix failing tests.
+3. When planning a complex refactoring, use this tool to outline different approaches and their tradeoffs.
+4. When designing a new feature, use this tool to think through architecture decisions and implementation details.
+5. When debugging a complex issue, use this tool to organize your thoughts and hypotheses.
+
+The tool simply logs your thought process for better transparency and does not execute any code or make changes."""  # noqa: E501
+
+
+class ThinkExecutor(ToolExecutor):
+    def __call__(
+        self,
+        _: ThinkAction,
+        conversation: "BaseConversation | None" = None,  # noqa: ARG002
+    ) -> ThinkObservation:
+        return ThinkObservation.from_text(text="Your thought has been logged.")
+
+
+class ThinkTool(ToolDefinition[ThinkAction, ThinkObservation]):
+    """Tool for logging thoughts without making changes."""
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: "ConversationState | None" = None,  # noqa: ARG003
+        **params,
+    ) -> Sequence[Self]:
+        """Create ThinkTool instance.
+
+        Args:
+            conv_state: Optional conversation state (not used by ThinkTool).
+            **params: Additional parameters (none supported).
+
+        Returns:
+            A sequence containing a single ThinkTool instance.
+
+        Raises:
+            ValueError: If any parameters are provided.
+        """
+        if params:
+            raise ValueError("ThinkTool doesn't accept parameters")
+        return [
+            cls(
+                description=THINK_DESCRIPTION,
+                action_type=ThinkAction,
+                observation_type=ThinkObservation,
+                executor=ThinkExecutor(),
+                annotations=ToolAnnotations(
+                    readOnlyHint=True,
+                    destructiveHint=False,
+                    idempotentHint=True,
+                    openWorldHint=False,
+                ),
+            )
+        ]