openhands-sdk 1.7.3__py3-none-any.whl → 1.8.0__py3-none-any.whl

openhands/sdk/context/skills/types.py

@@ -16,6 +16,10 @@ class SkillKnowledge(BaseModel):
     name: str = Field(description="The name of the skill that was triggered")
     trigger: str = Field(description="The word that triggered this skill")
     content: str = Field(description="The actual content/knowledge from the skill")
+    location: str | None = Field(
+        default=None,
+        description="Path to the SKILL.md file (for resolving relative resource paths)",
+    )
 
 
 class SkillResponse(BaseModel):

openhands/sdk/context/skills/utils.py

@@ -0,0 +1,442 @@
+"""Utility functions for skill loading and management."""
+
+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.logger import get_logger
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.context.skills.skill import Skill, SkillResources
+
+logger = get_logger(__name__)
+
+# Standard resource directory names per AgentSkills spec
+RESOURCE_DIRECTORIES = ("scripts", "references", "assets")
+
+# Regex pattern for valid AgentSkills names
+# - 1-64 characters
+# - Lowercase alphanumeric + hyphens only (a-z, 0-9, -)
+# - Must not start or end with hyphen
+# - Must not contain consecutive hyphens (--)
+SKILL_NAME_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def find_skill_md(skill_dir: Path) -> Path | None:
+    """Find SKILL.md file in a directory (case-insensitive).
+
+    Args:
+        skill_dir: Path to the skill directory to search.
+
+    Returns:
+        Path to SKILL.md if found, None otherwise.
+    """
+    if not skill_dir.is_dir():
+        return None
+    for item in skill_dir.iterdir():
+        if item.is_file() and item.name.lower() == "skill.md":
+            return item
+    return None
+
+
+def find_mcp_config(skill_dir: Path) -> Path | None:
+    """Find .mcp.json file in a skill directory.
+
+    Args:
+        skill_dir: Path to the skill directory to search.
+
+    Returns:
+        Path to .mcp.json if found, None otherwise.
+    """
+    if not skill_dir.is_dir():
+        return None
+    mcp_json = skill_dir / ".mcp.json"
+    if mcp_json.exists() and mcp_json.is_file():
+        return mcp_json
+    return None
+
+
+def expand_mcp_variables(
+    config: dict,
+    variables: dict[str, str],
+) -> dict:
+    """Expand variables in MCP configuration.
+
+    Supports variable expansion similar to Claude Code:
+    - ${VAR} - Environment variables or provided variables
+    - ${VAR:-default} - With default value
+
+    Args:
+        config: MCP configuration dictionary.
+        variables: Dictionary of variable names to values.
+
+    Returns:
+        Configuration with variables expanded.
+    """
+    # Convert to JSON string for easy replacement
+    config_str = json.dumps(config)
+
+    # Pattern for ${VAR} or ${VAR:-default}
+    var_pattern = re.compile(r"\$\{([a-zA-Z_][a-zA-Z0-9_]*)(?::-([^}]*))?\}")
+
+    def replace_var(match: re.Match) -> str:
+        var_name = match.group(1)
+        default_value = match.group(2)
+
+        # Check provided variables first, then environment
+        if var_name in variables:
+            return variables[var_name]
+        if var_name in os.environ:
+            return os.environ[var_name]
+        if default_value is not None:
+            return default_value
+        # Return original if not found
+        return match.group(0)
+
+    config_str = var_pattern.sub(replace_var, config_str)
+    return json.loads(config_str)
+
+
+def load_mcp_config(
+    mcp_json_path: Path,
+    skill_root: Path | None = None,
+) -> dict:
+    """Load and parse .mcp.json with variable expansion.
+
+    Args:
+        mcp_json_path: Path to the .mcp.json file.
+        skill_root: Root directory of the skill (for ${SKILL_ROOT} expansion).
+
+    Returns:
+        Parsed MCP configuration dictionary.
+
+    Raises:
+        SkillValidationError: If the file cannot be parsed or is invalid.
+    """
+    try:
+        with open(mcp_json_path) as f:
+            config = json.load(f)
+    except json.JSONDecodeError as e:
+        raise SkillValidationError(f"Invalid JSON in {mcp_json_path}: {e}") from e
+    except OSError as e:
+        raise SkillValidationError(f"Cannot read {mcp_json_path}: {e}") from e
+
+    if not isinstance(config, dict):
+        raise SkillValidationError(
+            f"Invalid .mcp.json format: expected object, got {type(config).__name__}"
+        )
+
+    # Prepare variables for expansion
+    variables: dict[str, str] = {}
+    if skill_root:
+        variables["SKILL_ROOT"] = str(skill_root)
+
+    # Expand variables
+    config = expand_mcp_variables(config, variables)
+
+    # Validate using MCPConfig
+    try:
+        MCPConfig.model_validate(config)
+    except Exception as e:
+        raise SkillValidationError(f"Invalid MCP configuration: {e}") from e
+
+    return config
+
+
+def validate_skill_name(name: str, directory_name: str | None = None) -> list[str]:
+    """Validate skill name according to AgentSkills spec.
+
+    Args:
+        name: The skill name to validate.
+        directory_name: Optional directory name to check for match.
+
+    Returns:
+        List of validation error messages (empty if valid).
+    """
+    errors = []
+
+    if not name:
+        errors.append("Name cannot be empty")
+        return errors
+
+    if len(name) > 64:
+        errors.append(f"Name exceeds 64 characters: {len(name)}")
+
+    if not SKILL_NAME_PATTERN.match(name):
+        errors.append(
+            "Name must be lowercase alphanumeric with single hyphens "
+            "(e.g., 'my-skill', 'pdf-tools')"
+        )
+
+    if directory_name and name != directory_name:
+        errors.append(f"Name '{name}' does not match directory '{directory_name}'")
+
+    return errors
+
+
+def find_third_party_files(
+    repo_root: Path, third_party_skill_names: dict[str, str]
+) -> list[Path]:
+    """Find third-party skill files in the repository root.
+
+    Searches for files like .cursorrules, AGENTS.md, CLAUDE.md, etc.
+    with case-insensitive matching.
+
+    Args:
+        repo_root: Path to the repository root directory.
+        third_party_skill_names: Mapping of lowercase filenames to skill names.
+
+    Returns:
+        List of paths to third-party skill files found.
+    """
+    if not repo_root.exists():
+        return []
+
+    # Build a set of target filenames (lowercase) for case-insensitive matching
+    target_names = {name.lower() for name in third_party_skill_names}
+
+    files: list[Path] = []
+    seen_names: set[str] = set()
+    for item in repo_root.iterdir():
+        if item.is_file() and item.name.lower() in target_names:
+            # Avoid duplicates (e.g., AGENTS.md and agents.md in same dir)
+            name_lower = item.name.lower()
+            if name_lower in seen_names:
+                logger.warning(
+                    f"Duplicate third-party skill file ignored: {item} "
+                    f"(already found a file with name '{name_lower}')"
+                )
+            else:
+                files.append(item)
+                seen_names.add(name_lower)
+    return files
+
+
+def find_skill_md_directories(skill_dir: Path) -> list[Path]:
+    """Find AgentSkills-style directories containing SKILL.md files.
+
+    Args:
+        skill_dir: Path to the skills directory.
+
+    Returns:
+        List of paths to SKILL.md files.
+    """
+    results: list[Path] = []
+    if not skill_dir.exists():
+        return results
+    for subdir in skill_dir.iterdir():
+        if subdir.is_dir():
+            skill_md = find_skill_md(subdir)
+            if skill_md:
+                results.append(skill_md)
+    return results
+
+
+def find_regular_md_files(skill_dir: Path, exclude_dirs: set[Path]) -> list[Path]:
+    """Find regular .md skill files, excluding SKILL.md and files in excluded dirs.
+
+    Args:
+        skill_dir: Path to the skills directory.
+        exclude_dirs: Set of directories to exclude (e.g., SKILL.md directories).
+
+    Returns:
+        List of paths to regular .md skill files.
+    """
+    files: list[Path] = []
+    if not skill_dir.exists():
+        return files
+    for f in skill_dir.rglob("*.md"):
+        is_readme = f.name == "README.md"
+        is_skill_md = f.name.lower() == "skill.md"
+        is_in_excluded_dir = any(f.is_relative_to(d) for d in exclude_dirs)
+        if not is_readme and not is_skill_md and not is_in_excluded_dir:
+            files.append(f)
+    return files
+
+
+def load_and_categorize(
+    path: Path,
+    skill_base_dir: Path,
+    repo_skills: dict[str, Skill],
+    knowledge_skills: dict[str, Skill],
+    agent_skills: dict[str, Skill],
+) -> None:
+    """Load a skill and categorize it.
+
+    Categorizes into repo_skills, knowledge_skills, or agent_skills.
+
+    Args:
+        path: Path to the skill file.
+        skill_base_dir: Base directory for skills (used to derive relative names).
+        repo_skills: Dictionary for skills with trigger=None (permanent context).
+        knowledge_skills: Dictionary for skills with triggers (progressive).
+        agent_skills: Dictionary for AgentSkills standard SKILL.md files.
+    """
+    # Import here to avoid circular dependency
+    from openhands.sdk.context.skills.skill import Skill
+
+    skill = Skill.load(path, skill_base_dir)
+
+    # AgentSkills (SKILL.md directories) are a separate category from OpenHands skills.
+    # They follow the AgentSkills standard and should be handled differently.
+    is_skill_md = path.name.lower() == "skill.md"
+    if is_skill_md:
+        agent_skills[skill.name] = skill
+    elif skill.trigger is None:
+        repo_skills[skill.name] = skill
+    else:
+        knowledge_skills[skill.name] = skill
+
+
+def get_skills_cache_dir() -> Path:
+    """Get the local cache directory for public skills repository.
+
+    Returns:
+        Path to the skills cache directory (~/.openhands/cache/skills).
+    """
+    cache_dir = Path.home() / ".openhands" / "cache" / "skills"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def update_skills_repository(
+    repo_url: str,
+    branch: str,
+    cache_dir: Path,
+) -> Path | None:
+    """Clone or update the local skills repository.
+
+    Args:
+        repo_url: URL of the skills repository.
+        branch: Branch name to use.
+        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
+
+
+def discover_skill_resources(skill_dir: Path) -> SkillResources:
+    """Discover resource directories in a skill directory.
+
+    Scans for standard AgentSkills resource directories:
+    - scripts/: Executable scripts
+    - references/: Reference documentation
+    - assets/: Static assets
+
+    Args:
+        skill_dir: Path to the skill directory.
+
+    Returns:
+        SkillResources with lists of files in each resource directory.
+    """
+    # Import here to avoid circular dependency
+    from openhands.sdk.context.skills.skill import SkillResources
+
+    resources = SkillResources(skill_root=str(skill_dir.resolve()))
+
+    for resource_type in RESOURCE_DIRECTORIES:
+        resource_dir = skill_dir / resource_type
+        if resource_dir.is_dir():
+            files = _list_resource_files(resource_dir, resource_type)
+            setattr(resources, resource_type, files)
+
+    return resources
+
+
+def _list_resource_files(
+    resource_dir: Path,
+    resource_type: str,
+) -> list[str]:
+    """List files in a resource directory.
+
+    Args:
+        resource_dir: Path to the resource directory.
+        resource_type: Type of resource (scripts, references, assets).
+
+    Returns:
+        List of relative file paths within the resource directory.
+    """
+    files: list[str] = []
+    try:
+        for item in resource_dir.rglob("*"):
+            if item.is_file():
+                # Store relative path from resource directory
+                rel_path = item.relative_to(resource_dir)
+                files.append(str(rel_path))
+    except OSError as e:
+        logger.warning(f"Error listing {resource_type} directory: {e}")
+    return sorted(files)

openhands/sdk/context/view.py

@@ -489,9 +489,11 @@ class View(BaseModel):
         # Check for an unhandled condensation request -- these are events closer to the
         # end of the list than any condensation action.
         unhandled_condensation_request = False
+
         for event in reversed(events):
             if isinstance(event, Condensation):
                 break
+
             if isinstance(event, CondensationRequest):
                 unhandled_condensation_request = True
                 break

openhands/sdk/conversation/impl/local_conversation.py

@@ -140,19 +140,7 @@ class LocalConversation(BaseConversation):
         def _default_callback(e):
             self._state.events.append(e)
 
-        self._hook_processor = None
-        hook_callback = None
-        if hook_config is not None:
-            self._hook_processor, hook_callback = create_hook_callback(
-                hook_config=hook_config,
-                working_dir=str(self.workspace.working_dir),
-                session_id=str(desired_id),
-            )
-
         callback_list = list(callbacks) if callbacks else []
-        if hook_callback is not None:
-            callback_list.insert(0, hook_callback)
-
         composed_list = callback_list + [_default_callback]
         # Handle visualization configuration
         if isinstance(visualizer, ConversationVisualizerBase):
@@ -175,7 +163,20 @@ class LocalConversation(BaseConversation):
             # No visualization (visualizer is None)
             self._visualizer = None
 
-        self._on_event = BaseConversation.compose_callbacks(composed_list)
+        # Compose the base callback chain (visualizer -> user callbacks -> default)
+        base_callback = BaseConversation.compose_callbacks(composed_list)
+
+        # If hooks configured, wrap with hook processor that forwards to base chain
+        self._hook_processor = None
+        if hook_config is not None:
+            self._hook_processor, self._on_event = create_hook_callback(
+                hook_config=hook_config,
+                working_dir=str(self.workspace.working_dir),
+                session_id=str(desired_id),
+                original_callback=base_callback,
+            )
+        else:
+            self._on_event = base_callback
         self._on_token = (
             BaseConversation.compose_callbacks(token_callbacks)
             if token_callbacks
@@ -335,12 +336,39 @@ class LocalConversation(BaseConversation):
                     # Before value can be modified step can be taken
                     # Ensure step conditions are checked when lock is already acquired
                     if self._state.execution_status in [
-                        ConversationExecutionStatus.FINISHED,
                         ConversationExecutionStatus.PAUSED,
                         ConversationExecutionStatus.STUCK,
                     ]:
                         break
 
+                    # Handle stop hooks on FINISHED
+                    if (
+                        self._state.execution_status
+                        == ConversationExecutionStatus.FINISHED
+                    ):
+                        if self._hook_processor is not None:
+                            should_stop, feedback = self._hook_processor.run_stop(
+                                reason="agent_finished"
+                            )
+                            if not should_stop:
+                                logger.info("Stop hook denied agent stopping")
+                                if feedback:
+                                    prefixed = f"[Stop hook feedback] {feedback}"
+                                    feedback_msg = MessageEvent(
+                                        source="user",
+                                        llm_message=Message(
+                                            role="user",
+                                            content=[TextContent(text=prefixed)],
+                                        ),
+                                    )
+                                    self._on_event(feedback_msg)
+                                self._state.execution_status = (
+                                    ConversationExecutionStatus.RUNNING
+                                )
+                                continue
+                        # No hooks or hooks allowed stopping
+                        break
+
                     # Check for stuck patterns if enabled
                     if self._stuck_detector:
                         is_stuck = self._stuck_detector.is_stuck()