openhands-sdk 1.8.2__tar.gz → 1.9.0__tar.gz

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/PKG-INFO

@@ -1,7 +1,11 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.8.2
+Version: 1.9.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

{openhands_sdk-1.8.2 → openhands_sdk-1.9.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,
@@ -120,6 +121,48 @@ class Agent(AgentBase):
             )
             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,
         conversation: LocalConversation,
@@ -237,6 +280,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,
@@ -275,6 +319,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
@@ -389,6 +441,7 @@ class Agent(AgentBase):
     def _get_action_event(
         self,
         tool_call: MessageToolCall,
+        conversation: LocalConversation,
         llm_response_id: str,
         on_event: ConversationCallbackType,
         security_analyzer: analyzer.SecurityAnalyzerBase | None = None,
@@ -477,6 +530,7 @@ class Agent(AgentBase):
             on_event(event)
             return
 
+        # Create initial action event
         action_event = ActionEvent(
             action=action,
             thought=thought or [],
@@ -490,6 +544,16 @@ class Agent(AgentBase):
             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
 

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/agent/base.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 import re
 import sys
@@ -16,6 +18,7 @@ from pydantic import (
 from openhands.sdk.context.agent_context import AgentContext
 from openhands.sdk.context.condenser import CondenserBase
 from openhands.sdk.context.prompts.prompt import render_template
+from openhands.sdk.critic.base import CriticBase
 from openhands.sdk.llm import LLM
 from openhands.sdk.llm.utils.model_prompt_spec import get_model_prompt_spec
 from openhands.sdk.logger import get_logger
@@ -37,7 +40,6 @@ if TYPE_CHECKING:
         ConversationTokenCallbackType,
     )
 
-
 logger = get_logger(__name__)
 
 
@@ -174,6 +176,16 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         ],
     )
 
+    critic: CriticBase | None = Field(
+        default=None,
+        description=(
+            "EXPERIMENTAL: Optional critic to evaluate agent actions and messages "
+            "in real-time. API and behavior may change without notice. "
+            "May impact performance, especially in 'all_actions' mode."
+        ),
+        examples=[{"kind": "AgentFinishedCritic"}],
+    )
+
     # Runtime materialized tools; private and non-serializable
     _tools: dict[str, ToolDefinition] = PrivateAttr(default_factory=dict)
     _initialized: bool = PrivateAttr(default=False)
@@ -226,8 +238,8 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
 
     def init_state(
         self,
-        state: "ConversationState",
-        on_event: "ConversationCallbackType",  # noqa: ARG002
+        state: ConversationState,
+        on_event: ConversationCallbackType,  # noqa: ARG002
     ) -> None:
         """Initialize the empty conversation state to prepare the agent for user
         messages.
@@ -238,7 +250,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         """
         self._initialize(state)
 
-    def _initialize(self, state: "ConversationState"):
+    def _initialize(self, state: ConversationState):
         """Create an AgentBase instance from an AgentSpec."""
 
         if self._initialized:
@@ -310,9 +322,9 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
     @abstractmethod
     def step(
         self,
-        conversation: "LocalConversation",
-        on_event: "ConversationCallbackType",
-        on_token: "ConversationTokenCallbackType | None" = None,
+        conversation: LocalConversation,
+        on_event: ConversationCallbackType,
+        on_token: ConversationTokenCallbackType | None = None,
     ) -> None:
         """Taking a step in the conversation.
 
@@ -332,9 +344,9 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
 
     def verify(
         self,
-        persisted: "AgentBase",
-        events: "Sequence[Any] | None" = None,
-    ) -> "AgentBase":
+        persisted: AgentBase,
+        events: Sequence[Any] | None = None,
+    ) -> AgentBase:
         """Verify that we can resume this agent from persisted state.
 
         This PR's goal is to *not* reconcile configuration between persisted and

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/context/skills/skill.py

@@ -1,7 +1,7 @@
 import io
 import re
 from pathlib import Path
-from typing import Annotated, ClassVar, Union
+from typing import Annotated, ClassVar, Literal, Union
 from xml.sax.saxutils import escape as xml_escape
 
 import frontmatter
@@ -37,6 +37,22 @@ logger = get_logger(__name__)
 THIRD_PARTY_SKILL_MAX_CHARS = 10_000
 
 
+class SkillInfo(BaseModel):
+    """Lightweight representation of a skill's essential information.
+
+    This class provides a standardized, serializable format for skill metadata
+    that can be used across different components of the system.
+    """
+
+    name: str
+    type: Literal["repo", "knowledge", "agentskills"]
+    content: str
+    triggers: list[str] = Field(default_factory=list)
+    source: str | None = None
+    description: str | None = None
+    is_agentskills_format: bool = False
+
+
 class SkillResources(BaseModel):
     """Resource directories for a skill (AgentSkills standard).
 
@@ -560,6 +576,48 @@ class Skill(BaseModel):
         logger.debug(f"This skill requires user input: {variables}")
         return len(variables) > 0
 
+    def get_skill_type(self) -> Literal["repo", "knowledge", "agentskills"]:
+        """Determine the type of this skill.
+
+        Returns:
+            "agentskills" for AgentSkills format, "repo" for always-active skills,
+            "knowledge" for trigger-based skills.
+        """
+        if self.is_agentskills_format:
+            return "agentskills"
+        elif self.trigger is None:
+            return "repo"
+        else:
+            return "knowledge"
+
+    def get_triggers(self) -> list[str]:
+        """Extract trigger keywords from this skill.
+
+        Returns:
+            List of trigger strings, or empty list if no triggers.
+        """
+        if isinstance(self.trigger, KeywordTrigger):
+            return self.trigger.keywords
+        elif isinstance(self.trigger, TaskTrigger):
+            return self.trigger.triggers
+        return []
+
+    def to_skill_info(self) -> SkillInfo:
+        """Convert this skill to a SkillInfo.
+
+        Returns:
+            SkillInfo containing the skill's essential information.
+        """
+        return SkillInfo(
+            name=self.name,
+            type=self.get_skill_type(),
+            content=self.content,
+            triggers=self.get_triggers(),
+            source=self.source,
+            description=self.description,
+            is_agentskills_format=self.is_agentskills_format,
+        )
+
 
 def load_skills_from_dir(
     skill_dir: str | Path,

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/context/skills/utils.py

@@ -5,14 +5,13 @@ from __future__ import annotations
 import json
 import os
 import re
-import shutil
-import subprocess
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 from fastmcp.mcp_config import MCPConfig
 
 from openhands.sdk.context.skills.exceptions import SkillValidationError
+from openhands.sdk.git.cached_repo import try_cached_clone_or_update
 from openhands.sdk.logger import get_logger
 
 
@@ -316,77 +315,19 @@ def update_skills_repository(
 ) -> Path | None:
     """Clone or update the local skills repository.
 
+    Uses the shared git caching infrastructure from openhands.sdk.git.cached_repo.
+    When updating, performs: fetch -> checkout ref -> reset --hard to origin/ref.
+
     Args:
         repo_url: URL of the skills repository.
-        branch: Branch name to use.
+        branch: Branch name to checkout and track.
         cache_dir: Directory where the repository should be cached.
 
     Returns:
         Path to the local repository if successful, None otherwise.
     """
     repo_path = cache_dir / "public-skills"
-
-    try:
-        if repo_path.exists() and (repo_path / ".git").exists():
-            logger.debug(f"Updating skills repository at {repo_path}")
-            try:
-                subprocess.run(
-                    ["git", "fetch", "origin"],
-                    cwd=repo_path,
-                    check=True,
-                    capture_output=True,
-                    timeout=30,
-                )
-                subprocess.run(
-                    ["git", "reset", "--hard", f"origin/{branch}"],
-                    cwd=repo_path,
-                    check=True,
-                    capture_output=True,
-                    timeout=10,
-                )
-                logger.debug("Skills repository updated successfully")
-            except subprocess.TimeoutExpired:
-                logger.warning("Git pull timed out, using existing cached repository")
-            except subprocess.CalledProcessError as e:
-                logger.warning(
-                    f"Failed to update repository: {e.stderr.decode()}, "
-                    f"using existing cached version"
-                )
-        else:
-            logger.info(f"Cloning public skills repository from {repo_url}")
-            if repo_path.exists():
-                shutil.rmtree(repo_path)
-
-            subprocess.run(
-                [
-                    "git",
-                    "clone",
-                    "--depth",
-                    "1",
-                    "--branch",
-                    branch,
-                    repo_url,
-                    str(repo_path),
-                ],
-                check=True,
-                capture_output=True,
-                timeout=60,
-            )
-            logger.debug(f"Skills repository cloned to {repo_path}")
-
-        return repo_path
-
-    except subprocess.TimeoutExpired:
-        logger.warning(f"Git operation timed out for {repo_url}")
-        return None
-    except subprocess.CalledProcessError as e:
-        logger.warning(
-            f"Failed to clone/update repository {repo_url}: {e.stderr.decode()}"
-        )
-        return None
-    except Exception as e:
-        logger.warning(f"Error managing skills repository: {str(e)}")
-        return None
+    return try_cached_clone_or_update(repo_url, repo_path, ref=branch, update=True)
 
 
 def discover_skill_resources(skill_dir: Path) -> SkillResources:

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/conversation/base.py

@@ -162,6 +162,11 @@ class BaseConversation(ABC):
         """Set the confirmation policy for the conversation."""
         ...
 
+    @abstractmethod
+    def set_security_analyzer(self, analyzer: SecurityAnalyzerBase | None) -> None:
+        """Set the security analyzer for the conversation."""
+        ...
+
     @property
     def confirmation_policy_active(self) -> bool:
         return not isinstance(self.state.confirmation_policy, NeverConfirm)

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/conversation/impl/remote_conversation.py

@@ -1,4 +1,5 @@
 import asyncio
+import bisect
 import json
 import os
 import threading
@@ -219,13 +220,25 @@ class RemoteEventsList(EventsListBase):
         logger.debug(f"Full sync completed, {len(events)} events cached")
 
     def add_event(self, event: Event) -> None:
-        """Add a new event to the local cache (called by WebSocket callback)."""
+        """Add a new event to the local cache (called by WebSocket callback).
+
+        Events are inserted in sorted order by timestamp to maintain correct
+        temporal ordering regardless of WebSocket delivery order.
+        """
         with self._lock:
             # Check if event already exists to avoid duplicates
             if event.id not in self._cached_event_ids:
-                self._cached_events.append(event)
+                # Use bisect with key function for O(log N) insertion
+                # This ensures events are always ordered correctly even if
+                # WebSocket delivers them out of order
+                insert_pos = bisect.bisect_right(
+                    self._cached_events, event.timestamp, key=lambda e: e.timestamp
+                )
+                self._cached_events.insert(insert_pos, event)
                 self._cached_event_ids.add(event.id)
-                logger.debug(f"Added event {event.id} to local cache")
+                logger.debug(
+                    f"Added event {event.id} to local cache at position {insert_pos}"
+                )
 
     def append(self, event: Event) -> None:
         """Add a new event to the list (for compatibility with EventLog interface)."""

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/conversation/visualizer/base.py

@@ -65,3 +65,26 @@ class ConversationVisualizerBase(ABC):
             event: The event to visualize
         """
         pass
+
+    def create_sub_visualizer(
+        self,
+        agent_id: str,  # noqa: ARG002
+    ) -> "ConversationVisualizerBase | None":
+        """Create a visualizer for a sub-agent during delegation.
+
+        Override this method to support sub-agent visualization in multi-agent
+        delegation scenarios. The sub-visualizer will be used to display events
+        from the spawned sub-agent.
+
+        By default, returns None which means sub-agents will not have visualization.
+        Subclasses that support delegation (like DelegationVisualizer) should
+        override this method to create appropriate sub-visualizers.
+
+        Args:
+            agent_id: The identifier of the sub-agent being spawned
+
+        Returns:
+            A visualizer instance for the sub-agent, or None if sub-agent
+            visualization is not supported
+        """
+        return None

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/critic/__init__.py

@@ -1,15 +1,18 @@
-from openhands.sdk.critic.base import CriticBase, CriticResult
+from openhands.sdk.critic.base import CriticBase
 from openhands.sdk.critic.impl import (
     AgentFinishedCritic,
+    APIBasedCritic,
     EmptyPatchCritic,
     PassCritic,
 )
+from openhands.sdk.critic.result import CriticResult
 
 
 __all__ = [
     "CriticBase",
     "CriticResult",
     "AgentFinishedCritic",
+    "APIBasedCritic",
     "EmptyPatchCritic",
     "PassCritic",
 ]

openhands_sdk-1.9.0/openhands/sdk/critic/base.py

@@ -0,0 +1,35 @@
+import abc
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import Field
+
+from openhands.sdk.critic.result import CriticResult
+from openhands.sdk.utils.models import DiscriminatedUnionMixin
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.event.base import LLMConvertibleEvent
+
+
+class CriticBase(DiscriminatedUnionMixin, abc.ABC):
+    """A critic is a function that takes in a list of events,
+    optional git patch, and returns a score about the quality of agent's action.
+    """
+
+    mode: Literal["finish_and_message", "all_actions"] = Field(
+        default="finish_and_message",
+        description=(
+            "When to run critic evaluation:\n"
+            "- 'finish_and_message': Evaluate on FinishAction and agent"
+            " MessageEvent (default, minimal performance impact)\n"
+            "- 'all_actions': Evaluate after every agent action (WARNING: "
+            "significantly slower due to API calls on each action)"
+        ),
+    )
+
+    @abc.abstractmethod
+    def evaluate(
+        self, events: Sequence["LLMConvertibleEvent"], git_patch: str | None = None
+    ) -> CriticResult:
+        pass

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/critic/impl/__init__.py

@@ -1,12 +1,14 @@
 """Critic implementations module."""
 
 from openhands.sdk.critic.impl.agent_finished import AgentFinishedCritic
+from openhands.sdk.critic.impl.api import APIBasedCritic
 from openhands.sdk.critic.impl.empty_patch import EmptyPatchCritic
 from openhands.sdk.critic.impl.pass_critic import PassCritic
 
 
 __all__ = [
     "AgentFinishedCritic",
+    "APIBasedCritic",
     "EmptyPatchCritic",
     "PassCritic",
 ]

{openhands_sdk-1.8.2 → openhands_sdk-1.9.0}/openhands/sdk/critic/impl/agent_finished.py

@@ -7,13 +7,17 @@ This critic evaluates whether an agent properly finished a task by checking:
 """
 
 from collections.abc import Sequence
+from typing import TYPE_CHECKING
 
 from openhands.sdk.critic.base import CriticBase, CriticResult
-from openhands.sdk.event import ActionEvent, LLMConvertibleEvent
 from openhands.sdk.logger import get_logger
 from openhands.sdk.tool.builtins.finish import FinishAction
 
 
+if TYPE_CHECKING:
+    from openhands.sdk.event.base import LLMConvertibleEvent
+
+
 logger = get_logger(__name__)
 
 
@@ -27,7 +31,7 @@ class AgentFinishedCritic(CriticBase):
     """
 
     def evaluate(
-        self, events: Sequence[LLMConvertibleEvent], git_patch: str | None = None
+        self, events: Sequence["LLMConvertibleEvent"], git_patch: str | None = None
     ) -> CriticResult:
         """
         Evaluate if an agent properly finished with a non-empty git patch.
@@ -66,18 +70,18 @@ class AgentFinishedCritic(CriticBase):
             message="Agent completed with FinishAction and non-empty patch",
         )
 
-    def _has_finish_action(self, events: Sequence[LLMConvertibleEvent]) -> bool:
+    def _has_finish_action(self, events: Sequence["LLMConvertibleEvent"]) -> bool:
         """Check if the last action was a FinishAction."""
         if not events:
             return False
 
         # Look for the last ActionEvent in the history
+        from openhands.sdk.event.llm_convertible.action import ActionEvent
+
         for event in reversed(events):
             if isinstance(event, ActionEvent):
-                # Check if this is a FinishAction
                 if event.action and isinstance(event.action, FinishAction):
                     return True
-                # If we find any other action type, the agent didn't finish
                 return False
 
         return False

openhands_sdk-1.9.0/openhands/sdk/critic/impl/api/__init__.py

@@ -0,0 +1,18 @@
+from openhands.sdk.critic.impl.api.client import (
+    ClassificationItem,
+    ClassificationResponse,
+    CriticClient,
+    LabelProbMap,
+    UsageTokens,
+)
+from openhands.sdk.critic.impl.api.critic import APIBasedCritic
+
+
+__all__ = [
+    "APIBasedCritic",
+    "CriticClient",
+    "ClassificationItem",
+    "ClassificationResponse",
+    "LabelProbMap",
+    "UsageTokens",
+]