openhands-sdk 1.5.0__py3-none-any.whl → 1.7.2__py3-none-any.whl

openhands/sdk/context/skills/skill.py

@@ -40,6 +40,9 @@ class Skill(BaseModel):
     - None: Always active, for repository-specific guidelines
     - KeywordTrigger: Activated when keywords appear in user messages
     - TaskTrigger: Activated for specific tasks, may require user input
+
+    This model supports both OpenHands-specific fields and AgentSkills standard
+    fields (https://agentskills.io/specification) for cross-platform compatibility.
     """
 
     name: str
@@ -74,6 +77,65 @@ class Skill(BaseModel):
         description="Input metadata for the skill (task skills only)",
     )
 
+    # AgentSkills standard fields (https://agentskills.io/specification)
+    description: str | None = Field(
+        default=None,
+        description=(
+            "A brief description of what the skill does and when to use it. "
+            "AgentSkills standard field (max 1024 characters)."
+        ),
+    )
+    license: str | None = Field(
+        default=None,
+        description=(
+            "The license under which the skill is distributed. "
+            "AgentSkills standard field (e.g., 'Apache-2.0', 'MIT')."
+        ),
+    )
+    compatibility: str | None = Field(
+        default=None,
+        description=(
+            "Environment requirements or compatibility notes for the skill. "
+            "AgentSkills standard field (e.g., 'Requires git and docker')."
+        ),
+    )
+    metadata: dict[str, str] | None = Field(
+        default=None,
+        description=(
+            "Arbitrary key-value metadata for the skill. "
+            "AgentSkills standard field for extensibility."
+        ),
+    )
+    allowed_tools: list[str] | None = Field(
+        default=None,
+        description=(
+            "List of pre-approved tools for this skill. "
+            "AgentSkills standard field (parsed from space-delimited string)."
+        ),
+    )
+
+    @field_validator("allowed_tools", mode="before")
+    @classmethod
+    def _parse_allowed_tools(cls, v: str | list | None) -> list[str] | None:
+        """Parse allowed_tools from space-delimited string or list."""
+        if v is None:
+            return None
+        if isinstance(v, str):
+            return v.split()
+        if isinstance(v, list):
+            return [str(t) for t in v]
+        raise SkillValidationError("allowed-tools must be a string or list")
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def _convert_metadata_values(cls, v: dict | None) -> dict[str, str] | None:
+        """Convert metadata values to strings."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return {str(k): str(val) for k, val in v.items()}
+        raise SkillValidationError("metadata must be a dictionary")
+
     PATH_TO_THIRD_PARTY_SKILL_NAME: ClassVar[dict[str, str]] = {
         ".cursorrules": "cursorrules",
         "agents.md": "agents",
@@ -129,6 +191,9 @@ class Skill(BaseModel):
         """Load a skill from a markdown file with frontmatter.
 
         The agent's name is derived from its path relative to the skill_dir.
+
+        Supports both OpenHands-specific frontmatter fields and AgentSkills
+        standard fields (https://agentskills.io/specification).
         """
         path = Path(path) if isinstance(path, str) else path
 
@@ -162,6 +227,23 @@ class Skill(BaseModel):
         # Use name from frontmatter if provided, otherwise use derived name
         agent_name = str(metadata_dict.get("name", skill_name))
 
+        # Extract AgentSkills standard fields (Pydantic validators handle
+        # transformation). Handle "allowed-tools" to "allowed_tools" key mapping.
+        allowed_tools_value = metadata_dict.get(
+            "allowed-tools", metadata_dict.get("allowed_tools")
+        )
+        agentskills_fields = {
+            "description": metadata_dict.get("description"),
+            "license": metadata_dict.get("license"),
+            "compatibility": metadata_dict.get("compatibility"),
+            "metadata": metadata_dict.get("metadata"),
+            "allowed_tools": allowed_tools_value,
+        }
+        # Remove None values to avoid passing unnecessary kwargs
+        agentskills_fields = {
+            k: v for k, v in agentskills_fields.items() if v is not None
+        }
+
         # Get trigger keywords from metadata
         keywords = metadata_dict.get("triggers", [])
         if not isinstance(keywords, list):
@@ -188,6 +270,7 @@ class Skill(BaseModel):
                 source=str(path),
                 trigger=TaskTrigger(triggers=keywords),
                 inputs=inputs,
+                **agentskills_fields,
             )
 
         elif metadata_dict.get("triggers", None):
@@ -196,6 +279,7 @@ class Skill(BaseModel):
                 content=content,
                 source=str(path),
                 trigger=KeywordTrigger(keywords=keywords),
+                **agentskills_fields,
             )
         else:
             # No triggers, default to None (always active)
@@ -208,6 +292,7 @@ class Skill(BaseModel):
                 source=str(path),
                 trigger=None,
                 mcp_tools=mcp_tools,
+                **agentskills_fields,
             )
 
     # Field-level validation for mcp_tools
@@ -326,7 +411,10 @@ def load_skills_from_dir(
     # Process all files in one loop
     for file in chain(special_files, md_files):
         try:
-            skill = Skill.load(file, skill_dir)
+            skill = Skill.load(
+                file,
+                skill_dir,
+            )
             if skill.trigger is None:
                 repo_skills[skill.name] = skill
             else:
@@ -398,6 +486,67 @@ def load_user_skills() -> list[Skill]:
     return all_skills
 
 
+def load_project_skills(work_dir: str | Path) -> list[Skill]:
+    """Load skills from project-specific directories.
+
+    Searches for skills in {work_dir}/.openhands/skills/ and
+    {work_dir}/.openhands/microagents/ (legacy). Skills from both
+    directories are merged, with skills/ taking precedence for
+    duplicate names.
+
+    Args:
+        work_dir: Path to the project/working directory.
+
+    Returns:
+        List of Skill objects loaded from project directories.
+        Returns empty list if no skills found or loading fails.
+    """
+    if isinstance(work_dir, str):
+        work_dir = Path(work_dir)
+
+    all_skills = []
+    seen_names = set()
+
+    # Load project-specific skills from .openhands/skills and legacy microagents
+    project_skills_dirs = [
+        work_dir / ".openhands" / "skills",
+        work_dir / ".openhands" / "microagents",  # Legacy support
+    ]
+
+    for project_skills_dir in project_skills_dirs:
+        if not project_skills_dir.exists():
+            logger.debug(
+                f"Project skills directory does not exist: {project_skills_dir}"
+            )
+            continue
+
+        try:
+            logger.debug(f"Loading project skills from {project_skills_dir}")
+            repo_skills, knowledge_skills = load_skills_from_dir(project_skills_dir)
+
+            # Merge repo and knowledge skills
+            for skills_dict in [repo_skills, knowledge_skills]:
+                for name, skill in skills_dict.items():
+                    if name not in seen_names:
+                        all_skills.append(skill)
+                        seen_names.add(name)
+                    else:
+                        logger.warning(
+                            f"Skipping duplicate skill '{name}' from "
+                            f"{project_skills_dir}"
+                        )
+
+        except Exception as e:
+            logger.warning(
+                f"Failed to load project skills from {project_skills_dir}: {str(e)}"
+            )
+
+    logger.debug(
+        f"Loaded {len(all_skills)} project skills: {[s.name for s in all_skills]}"
+    )
+    return all_skills
+
+
 # Public skills repository configuration
 PUBLIC_SKILLS_REPO = "https://github.com/OpenHands/skills"
 PUBLIC_SKILLS_BRANCH = "main"
@@ -554,6 +703,8 @@ def load_public_skills(
                     path=skill_file,
                     skill_dir=repo_path,
                 )
+                if skill is None:
+                    continue
                 all_skills.append(skill)
                 logger.debug(f"Loaded public skill: {skill.name}")
             except Exception as e:

openhands/sdk/context/view.py

@@ -1,8 +1,12 @@
+from __future__ import annotations
+
+from collections import defaultdict
 from collections.abc import Sequence
+from functools import cached_property
 from logging import getLogger
 from typing import overload
 
-from pydantic import BaseModel
+from pydantic import BaseModel, computed_field
 
 from openhands.sdk.event import (
     Condensation,
@@ -21,6 +25,48 @@ from openhands.sdk.event.types import ToolCallID
 logger = getLogger(__name__)
 
 
+class ActionBatch(BaseModel):
+    """Represents a batch of ActionEvents grouped by llm_response_id.
+
+    This is a utility class used to help detect and manage batches of ActionEvents
+    that share the same llm_response_id, which indicates they were generated together
+    by the LLM. This is important for ensuring atomicity when manipulating events
+    in a View, such as during condensation.
+    """
+
+    batches: dict[EventID, list[EventID]]
+    """dict mapping llm_response_id to list of ActionEvent IDs"""
+
+    action_id_to_response_id: dict[EventID, EventID]
+    """dict mapping ActionEvent ID to llm_response_id"""
+
+    action_id_to_tool_call_id: dict[EventID, ToolCallID]
+    """dict mapping ActionEvent ID to tool_call_id"""
+
+    @staticmethod
+    def from_events(
+        events: Sequence[Event],
+    ) -> ActionBatch:
+        """Build a map of llm_response_id -> list of ActionEvent IDs."""
+        batches: dict[EventID, list[EventID]] = defaultdict(list)
+        action_id_to_response_id: dict[EventID, EventID] = {}
+        action_id_to_tool_call_id: dict[EventID, ToolCallID] = {}
+
+        for event in events:
+            if isinstance(event, ActionEvent):
+                llm_response_id = event.llm_response_id
+                batches[llm_response_id].append(event.id)
+                action_id_to_response_id[event.id] = llm_response_id
+                if event.tool_call_id is not None:
+                    action_id_to_tool_call_id[event.id] = event.tool_call_id
+
+        return ActionBatch(
+            batches=batches,
+            action_id_to_response_id=action_id_to_response_id,
+            action_id_to_tool_call_id=action_id_to_tool_call_id,
+        )
+
+
 class View(BaseModel):
     """Linearly ordered view of events.
 
@@ -66,6 +112,161 @@ class View(BaseModel):
                 return event
         return None
 
+    @computed_field  # type: ignore[prop-decorator]
+    @cached_property
+    def manipulation_indices(self) -> list[int]:
+        """Return cached manipulation indices for this view's events.
+
+        These indices represent boundaries between atomic units where events can be
+        safely manipulated (inserted or forgotten). An atomic unit is either:
+        - A tool loop: a sequence of batches starting with thinking blocks and
+          continuing through all subsequent batches until a non-batch event
+        - A batch of ActionEvents with the same llm_response_id and their
+          corresponding ObservationBaseEvents (when not part of a tool loop)
+        - A single event that is neither an ActionEvent nor an ObservationBaseEvent
+
+        Tool loops are identified by thinking blocks and must remain atomic to
+        preserve Claude API requirements that the final assistant message must
+        have thinking blocks when thinking is enabled.
+
+        The returned indices can be used for:
+        - Inserting new events: any returned index is safe
+        - Forgetting events: select a range between two consecutive indices
+
+        Consecutive indices define atomic units that must stay together:
+        - events[indices[i]:indices[i+1]] is an atomic unit
+
+        Returns:
+            Sorted list of indices representing atomic unit boundaries. Always
+            includes 0 and len(events) as boundaries.
+        """
+        if not self.events:
+            return [0]
+
+        # Build mapping of llm_response_id -> list of event indices
+        batches: dict[EventID, list[int]] = {}
+        for idx, event in enumerate(self.events):
+            if isinstance(event, ActionEvent):
+                llm_response_id = event.llm_response_id
+                if llm_response_id not in batches:
+                    batches[llm_response_id] = []
+                batches[llm_response_id].append(idx)
+
+        # Build mapping of tool_call_id -> observation indices
+        observation_indices: dict[ToolCallID, int] = {}
+        for idx, event in enumerate(self.events):
+            if (
+                isinstance(event, ObservationBaseEvent)
+                and event.tool_call_id is not None
+            ):
+                observation_indices[event.tool_call_id] = idx
+
+        # For each batch, find the range of indices that includes all actions
+        # and their corresponding observations, and track if batch has thinking blocks
+        batch_ranges: list[tuple[int, int, bool]] = []
+        for llm_response_id, action_indices in batches.items():
+            min_idx = min(action_indices)
+            max_idx = max(action_indices)
+
+            # Check if this batch has thinking blocks (only first action has them)
+            first_action = self.events[min_idx]
+            has_thinking = (
+                isinstance(first_action, ActionEvent)
+                and len(first_action.thinking_blocks) > 0
+            )
+
+            # Extend the range to include all corresponding observations
+            for action_idx in action_indices:
+                action_event = self.events[action_idx]
+                if (
+                    isinstance(action_event, ActionEvent)
+                    and action_event.tool_call_id is not None
+                ):
+                    if action_event.tool_call_id in observation_indices:
+                        obs_idx = observation_indices[action_event.tool_call_id]
+                        max_idx = max(max_idx, obs_idx)
+
+            batch_ranges.append((min_idx, max_idx, has_thinking))
+
+        # Sort batch ranges by start index for tool loop detection
+        batch_ranges.sort(key=lambda x: x[0])
+
+        # Identify tool loops: A tool loop starts with a batch that has thinking
+        # blocks and continues through all subsequent batches until we hit a
+        # non-ActionEvent/ObservationEvent (like a user MessageEvent).
+        tool_loop_ranges: list[tuple[int, int]] = []
+        if batch_ranges:
+            i = 0
+            while i < len(batch_ranges):
+                min_idx, max_idx, has_thinking = batch_ranges[i]
+
+                # If this batch has thinking blocks, start a tool loop
+                if has_thinking:
+                    loop_start = min_idx
+                    loop_end = max_idx
+
+                    # Continue through ALL subsequent batches until we hit
+                    # a non-batch event
+                    j = i + 1
+                    while j < len(batch_ranges):
+                        next_min, next_max, _ = batch_ranges[j]
+
+                        # Check if there's a non-batch event between current
+                        # and next batch
+                        has_non_batch_between = False
+                        for k in range(loop_end + 1, next_min):
+                            event = self.events[k]
+                            if not isinstance(
+                                event, (ActionEvent, ObservationBaseEvent)
+                            ):
+                                has_non_batch_between = True
+                                break
+
+                        if has_non_batch_between:
+                            # Tool loop ends before this non-batch event
+                            break
+
+                        # Include this batch in the tool loop
+                        loop_end = max(loop_end, next_max)
+                        j += 1
+
+                    tool_loop_ranges.append((loop_start, loop_end))
+                    i = j
+                else:
+                    i += 1
+
+        # Merge batch ranges that are part of tool loops
+        # Create a mapping of batch index ranges to whether they're in a tool loop
+        merged_ranges: list[tuple[int, int]] = []
+
+        if tool_loop_ranges:
+            # Add tool loop ranges as atomic units
+            merged_ranges.extend(tool_loop_ranges)
+
+            # Add non-tool-loop batch ranges
+            tool_loop_indices = set()
+            for loop_start, loop_end in tool_loop_ranges:
+                tool_loop_indices.update(range(loop_start, loop_end + 1))
+
+            for min_idx, max_idx, has_thinking in batch_ranges:
+                # Only add if not already covered by a tool loop
+                if min_idx not in tool_loop_indices:
+                    merged_ranges.append((min_idx, max_idx))
+        else:
+            # No tool loops, just use regular batch ranges
+            merged_ranges = [(min_idx, max_idx) for min_idx, max_idx, _ in batch_ranges]
+
+        # Start with all possible indices (subtractive approach)
+        result_indices = set(range(len(self.events) + 1))
+
+        # Remove indices inside merged ranges (keep only boundaries)
+        for min_idx, max_idx in merged_ranges:
+            # Remove interior indices, keeping min_idx and max_idx+1 as boundaries
+            for idx in range(min_idx + 1, max_idx + 1):
+                result_indices.discard(idx)
+
+        return sorted(result_indices)
+
     # To preserve list-like indexing, we ideally support slicing and position-based
     # indexing. The only challenge with that is switching the return type based on the
     # input type -- we can mark the different signatures for MyPy with `@overload`
@@ -91,36 +292,41 @@ class View(BaseModel):
     @staticmethod
     def _enforce_batch_atomicity(
         events: Sequence[Event],
-        forgotten_event_ids: set[EventID],
+        removed_event_ids: set[EventID],
     ) -> set[EventID]:
-        """Ensure that if any event in a batch is forgotten, all events in that
-        batch are forgotten.
+        """Ensure that if any ActionEvent in a batch is removed, all ActionEvents
+        in that batch are removed.
 
         This prevents partial batches from being sent to the LLM, which can cause
         API errors when thinking blocks are separated from their tool calls.
+
+        Args:
+            events: The original list of events
+            removed_event_ids: Set of event IDs that are being removed
+
+        Returns:
+            Updated set of event IDs that should be removed (including all
+            ActionEvents in batches where any ActionEvent was removed)
         """
-        batches: dict[EventID, list[EventID]] = {}
-        for event in events:
-            if isinstance(event, ActionEvent):
-                llm_response_id = event.llm_response_id
-                if llm_response_id not in batches:
-                    batches[llm_response_id] = []
-                batches[llm_response_id].append(event.id)
+        action_batch = ActionBatch.from_events(events)
+
+        if not action_batch.batches:
+            return removed_event_ids
 
-        updated_forgotten_ids = set(forgotten_event_ids)
+        updated_removed_ids = set(removed_event_ids)
 
-        for llm_response_id, batch_event_ids in batches.items():
-            # Check if any event in this batch is being forgotten
-            if any(event_id in forgotten_event_ids for event_id in batch_event_ids):
-                # If so, forget all events in this batch
-                updated_forgotten_ids.update(batch_event_ids)
+        for llm_response_id, batch_event_ids in action_batch.batches.items():
+            # Check if any ActionEvent in this batch is being removed
+            if any(event_id in removed_event_ids for event_id in batch_event_ids):
+                # If so, remove all ActionEvents in this batch
+                updated_removed_ids.update(batch_event_ids)
                 logger.debug(
-                    f"Enforcing batch atomicity: forgetting entire batch "
+                    f"Enforcing batch atomicity: removing entire batch "
                     f"with llm_response_id={llm_response_id} "
                     f"({len(batch_event_ids)} events)"
                 )
 
-        return updated_forgotten_ids
+        return updated_removed_ids
 
     @staticmethod
     def filter_unmatched_tool_calls(
@@ -129,18 +335,49 @@ class View(BaseModel):
         """Filter out unmatched tool call events.
 
         Removes ActionEvents and ObservationEvents that have tool_call_ids
-        but don't have matching pairs.
+        but don't have matching pairs. Also enforces batch atomicity - if any
+        ActionEvent in a batch is filtered out, all ActionEvents in that batch
+        are also filtered out.
         """
         action_tool_call_ids = View._get_action_tool_call_ids(events)
         observation_tool_call_ids = View._get_observation_tool_call_ids(events)
 
-        return [
-            event
-            for event in events
-            if View._should_keep_event(
+        # Build batch info for batch atomicity enforcement
+        action_batch = ActionBatch.from_events(events)
+
+        # First pass: identify which events would NOT be kept based on matching
+        removed_event_ids: set[EventID] = set()
+        for event in events:
+            if not View._should_keep_event(
                 event, action_tool_call_ids, observation_tool_call_ids
-            )
-        ]
+            ):
+                removed_event_ids.add(event.id)
+
+        # Second pass: enforce batch atomicity for ActionEvents
+        # If any ActionEvent in a batch is removed, all ActionEvents in that
+        # batch should also be removed
+        removed_event_ids = View._enforce_batch_atomicity(events, removed_event_ids)
+
+        # Third pass: also remove ObservationEvents whose ActionEvents were removed
+        # due to batch atomicity
+        tool_call_ids_to_remove: set[ToolCallID] = set()
+        for action_id in removed_event_ids:
+            if action_id in action_batch.action_id_to_tool_call_id:
+                tool_call_ids_to_remove.add(
+                    action_batch.action_id_to_tool_call_id[action_id]
+                )
+
+        # Filter out removed events
+        result = []
+        for event in events:
+            if event.id in removed_event_ids:
+                continue
+            if isinstance(event, ObservationBaseEvent):
+                if event.tool_call_id in tool_call_ids_to_remove:
+                    continue
+            result.append(event)
+
+        return result
 
     @staticmethod
     def _get_action_tool_call_ids(events: list[LLMConvertibleEvent]) -> set[ToolCallID]:
@@ -179,8 +416,31 @@ class View(BaseModel):
         else:
             return True
 
+    def find_next_manipulation_index(self, threshold: int, strict: bool = False) -> int:
+        """Find the smallest manipulation index greater than (or equal to) a threshold.
+
+        This is a helper method for condensation logic that needs to find safe
+        boundaries for forgetting events. Uses the cached manipulation_indices property.
+
+        Args:
+            threshold: The threshold value to compare against
+            strict: If True, finds index > threshold. If False, finds index >= threshold
+
+        Returns:
+            The smallest manipulation index that satisfies the condition, or the
+            threshold itself if no such index exists
+        """
+        for idx in self.manipulation_indices:
+            if strict:
+                if idx > threshold:
+                    return idx
+            else:
+                if idx >= threshold:
+                    return idx
+        return threshold
+
     @staticmethod
-    def from_events(events: Sequence[Event]) -> "View":
+    def from_events(events: Sequence[Event]) -> View:
         """Create a view from a list of events, respecting the semantics of any
         condensation events.
         """

openhands/sdk/conversation/base.py

@@ -245,6 +245,23 @@ class BaseConversation(ABC):
         """
         ...
 
+    @abstractmethod
+    def condense(self) -> None:
+        """Force condensation of the conversation history.
+
+        This method uses the existing condensation request pattern to trigger
+        condensation. It adds a CondensationRequest event to the conversation
+        and forces the agent to take a single step to process it.
+
+        The condensation will be applied immediately and will modify the conversation
+        state by adding a condensation event to the history.
+
+        Raises:
+            ValueError: If no condenser is configured or the condenser doesn't
+                       handle condensation requests.
+        """
+        ...
+
     @staticmethod
     def compose_callbacks(callbacks: Iterable[CallbackType]) -> CallbackType:
         """Compose multiple callbacks into a single callback function.