openhands-sdk 1.7.4__py3-none-any.whl → 1.8.1__py3-none-any.whl

openhands/sdk/plugin/plugin.py

@@ -0,0 +1,299 @@
+"""Plugin class for loading and managing plugins."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from openhands.sdk.context.skills import Skill
+from openhands.sdk.context.skills.utils import (
+    discover_skill_resources,
+    find_skill_md,
+    load_mcp_config,
+)
+from openhands.sdk.hooks import HookConfig
+from openhands.sdk.logger import get_logger
+from openhands.sdk.plugin.types import (
+    AgentDefinition,
+    CommandDefinition,
+    PluginAuthor,
+    PluginManifest,
+)
+
+
+logger = get_logger(__name__)
+
+# Directories to check for plugin manifest
+PLUGIN_MANIFEST_DIRS = [".plugin", ".claude-plugin"]
+PLUGIN_MANIFEST_FILE = "plugin.json"
+
+
+class Plugin(BaseModel):
+    """A plugin that bundles skills, hooks, MCP config, agents, and commands.
+
+    Plugins follow the Claude Code plugin structure for compatibility:
+
+    ```
+    plugin-name/
+    ├── .claude-plugin/           # or .plugin/
+    │   └── plugin.json          # Plugin metadata
+    ├── commands/                # Slash commands (optional)
+    ├── agents/                  # Specialized agents (optional)
+    ├── skills/                  # Agent Skills (optional)
+    ├── hooks/                   # Event handlers (optional)
+    │   └── hooks.json
+    ├── .mcp.json                # External tool configuration (optional)
+    └── README.md                # Plugin documentation
+    ```
+    """
+
+    manifest: PluginManifest = Field(description="Plugin manifest from plugin.json")
+    path: str = Field(description="Path to the plugin directory")
+    skills: list[Skill] = Field(
+        default_factory=list, description="Skills loaded from skills/ directory"
+    )
+    hooks: HookConfig | None = Field(
+        default=None, description="Hook configuration from hooks/hooks.json"
+    )
+    mcp_config: dict[str, Any] | None = Field(
+        default=None, description="MCP configuration from .mcp.json"
+    )
+    agents: list[AgentDefinition] = Field(
+        default_factory=list, description="Agent definitions from agents/ directory"
+    )
+    commands: list[CommandDefinition] = Field(
+        default_factory=list, description="Command definitions from commands/ directory"
+    )
+
+    @property
+    def name(self) -> str:
+        """Get the plugin name."""
+        return self.manifest.name
+
+    @property
+    def version(self) -> str:
+        """Get the plugin version."""
+        return self.manifest.version
+
+    @property
+    def description(self) -> str:
+        """Get the plugin description."""
+        return self.manifest.description
+
+    @classmethod
+    def load(cls, plugin_path: str | Path) -> Plugin:
+        """Load a plugin from a directory.
+
+        Args:
+            plugin_path: Path to the plugin directory.
+
+        Returns:
+            Loaded Plugin instance.
+
+        Raises:
+            FileNotFoundError: If the plugin directory doesn't exist.
+            ValueError: If the plugin manifest is invalid.
+        """
+        plugin_dir = Path(plugin_path).resolve()
+        if not plugin_dir.is_dir():
+            raise FileNotFoundError(f"Plugin directory not found: {plugin_dir}")
+
+        # Load manifest
+        manifest = _load_manifest(plugin_dir)
+
+        # Load skills
+        skills = _load_skills(plugin_dir)
+
+        # Load hooks
+        hooks = _load_hooks(plugin_dir)
+
+        # Load MCP config
+        mcp_config = _load_mcp_config(plugin_dir)
+
+        # Load agents
+        agents = _load_agents(plugin_dir)
+
+        # Load commands
+        commands = _load_commands(plugin_dir)
+
+        return cls(
+            manifest=manifest,
+            path=str(plugin_dir),
+            skills=skills,
+            hooks=hooks,
+            mcp_config=mcp_config,
+            agents=agents,
+            commands=commands,
+        )
+
+    @classmethod
+    def load_all(cls, plugins_dir: str | Path) -> list[Plugin]:
+        """Load all plugins from a directory.
+
+        Args:
+            plugins_dir: Path to directory containing plugin subdirectories.
+
+        Returns:
+            List of loaded Plugin instances.
+        """
+        plugins_path = Path(plugins_dir).resolve()
+        if not plugins_path.is_dir():
+            logger.warning(f"Plugins directory not found: {plugins_path}")
+            return []
+
+        plugins: list[Plugin] = []
+        for item in plugins_path.iterdir():
+            if item.is_dir():
+                try:
+                    plugin = cls.load(item)
+                    plugins.append(plugin)
+                    logger.debug(f"Loaded plugin: {plugin.name} from {item}")
+                except Exception as e:
+                    logger.warning(f"Failed to load plugin from {item}: {e}")
+
+        return plugins
+
+
+def _load_manifest(plugin_dir: Path) -> PluginManifest:
+    """Load plugin manifest from plugin.json.
+
+    Checks both .plugin/ and .claude-plugin/ directories.
+    Falls back to inferring from directory name if no manifest found.
+    """
+    manifest_path = None
+
+    # Check for manifest in standard locations
+    for manifest_dir in PLUGIN_MANIFEST_DIRS:
+        candidate = plugin_dir / manifest_dir / PLUGIN_MANIFEST_FILE
+        if candidate.exists():
+            manifest_path = candidate
+            break
+
+    if manifest_path:
+        try:
+            with open(manifest_path) as f:
+                data = json.load(f)
+
+            # Handle author field - can be string or object
+            if "author" in data and isinstance(data["author"], str):
+                data["author"] = PluginAuthor.from_string(data["author"]).model_dump()
+
+            return PluginManifest.model_validate(data)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {manifest_path}: {e}") from e
+        except Exception as e:
+            raise ValueError(f"Failed to parse manifest {manifest_path}: {e}") from e
+
+    # Fall back to inferring from directory name
+    logger.debug(f"No manifest found for {plugin_dir}, inferring from directory name")
+    return PluginManifest(
+        name=plugin_dir.name,
+        version="1.0.0",
+        description=f"Plugin loaded from {plugin_dir.name}",
+    )
+
+
+def _load_skills(plugin_dir: Path) -> list[Skill]:
+    """Load skills from the skills/ directory.
+
+    Note: Plugin skills are loaded with relaxed validation (strict=False)
+    to support Claude Code plugins which may use different naming conventions.
+    """
+    skills_dir = plugin_dir / "skills"
+    if not skills_dir.is_dir():
+        return []
+
+    skills: list[Skill] = []
+    for item in skills_dir.iterdir():
+        if item.is_dir():
+            skill_md = find_skill_md(item)
+            if skill_md:
+                try:
+                    skill = Skill.load(skill_md, skills_dir, strict=False)
+                    # Discover and attach resources
+                    skill.resources = discover_skill_resources(item)
+                    skills.append(skill)
+                    logger.debug(f"Loaded skill: {skill.name} from {skill_md}")
+                except Exception as e:
+                    logger.warning(f"Failed to load skill from {item}: {e}")
+        elif item.suffix == ".md" and item.name.lower() != "readme.md":
+            # Also support single .md files in skills/ directory
+            try:
+                skill = Skill.load(item, skills_dir, strict=False)
+                skills.append(skill)
+                logger.debug(f"Loaded skill: {skill.name} from {item}")
+            except Exception as e:
+                logger.warning(f"Failed to load skill from {item}: {e}")
+
+    return skills
+
+
+def _load_hooks(plugin_dir: Path) -> HookConfig | None:
+    """Load hooks configuration from hooks/hooks.json."""
+    hooks_json = plugin_dir / "hooks" / "hooks.json"
+    if not hooks_json.exists():
+        return None
+
+    try:
+        hook_config = HookConfig.load(path=hooks_json)
+        # load() returns empty config on error, check if it has hooks
+        if hook_config.hooks:
+            return hook_config
+        return None
+    except Exception as e:
+        logger.warning(f"Failed to load hooks from {hooks_json}: {e}")
+        return None
+
+
+def _load_mcp_config(plugin_dir: Path) -> dict[str, Any] | None:
+    """Load MCP configuration from .mcp.json."""
+    mcp_json = plugin_dir / ".mcp.json"
+    if not mcp_json.exists():
+        return None
+
+    try:
+        return load_mcp_config(mcp_json, skill_root=plugin_dir)
+    except Exception as e:
+        logger.warning(f"Failed to load MCP config from {mcp_json}: {e}")
+        return None
+
+
+def _load_agents(plugin_dir: Path) -> list[AgentDefinition]:
+    """Load agent definitions from the agents/ directory."""
+    agents_dir = plugin_dir / "agents"
+    if not agents_dir.is_dir():
+        return []
+
+    agents: list[AgentDefinition] = []
+    for item in agents_dir.iterdir():
+        if item.suffix == ".md" and item.name.lower() != "readme.md":
+            try:
+                agent = AgentDefinition.load(item)
+                agents.append(agent)
+                logger.debug(f"Loaded agent: {agent.name} from {item}")
+            except Exception as e:
+                logger.warning(f"Failed to load agent from {item}: {e}")
+
+    return agents
+
+
+def _load_commands(plugin_dir: Path) -> list[CommandDefinition]:
+    """Load command definitions from the commands/ directory."""
+    commands_dir = plugin_dir / "commands"
+    if not commands_dir.is_dir():
+        return []
+
+    commands: list[CommandDefinition] = []
+    for item in commands_dir.iterdir():
+        if item.suffix == ".md" and item.name.lower() != "readme.md":
+            try:
+                command = CommandDefinition.load(item)
+                commands.append(command)
+                logger.debug(f"Loaded command: {command.name} from {item}")
+            except Exception as e:
+                logger.warning(f"Failed to load command from {item}: {e}")
+
+    return commands

openhands/sdk/plugin/types.py

@@ -0,0 +1,226 @@
+"""Type definitions for Plugin module."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import frontmatter
+from pydantic import BaseModel, Field
+
+
+class PluginAuthor(BaseModel):
+    """Author information for a plugin."""
+
+    name: str = Field(description="Author's name")
+    email: str | None = Field(default=None, description="Author's email address")
+
+    @classmethod
+    def from_string(cls, author_str: str) -> PluginAuthor:
+        """Parse author from string format 'Name <email>'."""
+        if "<" in author_str and ">" in author_str:
+            name = author_str.split("<")[0].strip()
+            email = author_str.split("<")[1].split(">")[0].strip()
+            return cls(name=name, email=email)
+        return cls(name=author_str.strip())
+
+
+class PluginManifest(BaseModel):
+    """Plugin manifest from plugin.json."""
+
+    name: str = Field(description="Plugin name")
+    version: str = Field(default="1.0.0", description="Plugin version")
+    description: str = Field(default="", description="Plugin description")
+    author: PluginAuthor | None = Field(default=None, description="Plugin author")
+
+    model_config = {"extra": "allow"}
+
+
+def _extract_examples(description: str) -> list[str]:
+    """Extract <example> tags from description for agent triggering."""
+    pattern = r"<example>(.*?)</example>"
+    matches = re.findall(pattern, description, re.DOTALL | re.IGNORECASE)
+    return [m.strip() for m in matches if m.strip()]
+
+
+class AgentDefinition(BaseModel):
+    """Agent definition loaded from markdown file.
+
+    Agents are specialized configurations that can be triggered based on
+    user input patterns. They define custom system prompts and tool access.
+    """
+
+    name: str = Field(description="Agent name (from frontmatter or filename)")
+    description: str = Field(default="", description="Agent description")
+    model: str = Field(
+        default="inherit", description="Model to use ('inherit' uses parent model)"
+    )
+    color: str | None = Field(default=None, description="Display color for the agent")
+    tools: list[str] = Field(
+        default_factory=list, description="List of allowed tools for this agent"
+    )
+    system_prompt: str = Field(default="", description="System prompt content")
+    source: str | None = Field(
+        default=None, description="Source file path for this agent"
+    )
+    # whenToUse examples extracted from description
+    when_to_use_examples: list[str] = Field(
+        default_factory=list,
+        description="Examples of when to use this agent (for triggering)",
+    )
+    # Raw frontmatter for any additional fields
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata from frontmatter"
+    )
+
+    @classmethod
+    def load(cls, agent_path: Path) -> AgentDefinition:
+        """Load an agent definition from a markdown file.
+
+        Agent markdown files have YAML frontmatter with:
+        - name: Agent name
+        - description: Description with optional <example> tags for triggering
+        - model: Model to use (default: 'inherit')
+        - color: Display color
+        - tools: List of allowed tools
+
+        The body of the markdown is the system prompt.
+
+        Args:
+            agent_path: Path to the agent markdown file.
+
+        Returns:
+            Loaded AgentDefinition instance.
+        """
+        with open(agent_path) as f:
+            post = frontmatter.load(f)
+
+        fm = post.metadata
+        content = post.content.strip()
+
+        # Extract frontmatter fields with proper type handling
+        name = str(fm.get("name", agent_path.stem))
+        description = str(fm.get("description", ""))
+        model = str(fm.get("model", "inherit"))
+        color_raw = fm.get("color")
+        color: str | None = str(color_raw) if color_raw is not None else None
+        tools_raw = fm.get("tools", [])
+
+        # Ensure tools is a list of strings
+        tools: list[str]
+        if isinstance(tools_raw, str):
+            tools = [tools_raw]
+        elif isinstance(tools_raw, list):
+            tools = [str(t) for t in tools_raw]
+        else:
+            tools = []
+
+        # Extract whenToUse examples from description
+        when_to_use_examples = _extract_examples(description)
+
+        # Remove known fields from metadata to get extras
+        known_fields = {"name", "description", "model", "color", "tools"}
+        metadata = {k: v for k, v in fm.items() if k not in known_fields}
+
+        return cls(
+            name=name,
+            description=description,
+            model=model,
+            color=color,
+            tools=tools,
+            system_prompt=content,
+            source=str(agent_path),
+            when_to_use_examples=when_to_use_examples,
+            metadata=metadata,
+        )
+
+
+class CommandDefinition(BaseModel):
+    """Command definition loaded from markdown file.
+
+    Commands are slash commands that users can invoke directly.
+    They define instructions for the agent to follow.
+    """
+
+    name: str = Field(description="Command name (from filename, e.g., 'review')")
+    description: str = Field(default="", description="Command description")
+    argument_hint: str | None = Field(
+        default=None, description="Hint for command arguments"
+    )
+    allowed_tools: list[str] = Field(
+        default_factory=list, description="List of allowed tools for this command"
+    )
+    content: str = Field(default="", description="Command instructions/content")
+    source: str | None = Field(
+        default=None, description="Source file path for this command"
+    )
+    # Raw frontmatter for any additional fields
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata from frontmatter"
+    )
+
+    @classmethod
+    def load(cls, command_path: Path) -> CommandDefinition:
+        """Load a command definition from a markdown file.
+
+        Command markdown files have YAML frontmatter with:
+        - description: Command description
+        - argument-hint: Hint for command arguments (string or list)
+        - allowed-tools: List of allowed tools
+
+        The body of the markdown is the command instructions.
+
+        Args:
+            command_path: Path to the command markdown file.
+
+        Returns:
+            Loaded CommandDefinition instance.
+        """
+        with open(command_path) as f:
+            post = frontmatter.load(f)
+
+        # Extract frontmatter fields with proper type handling
+        fm = post.metadata
+        name = command_path.stem  # Command name from filename
+        description = str(fm.get("description", ""))
+        argument_hint_raw = fm.get("argument-hint") or fm.get("argumentHint")
+        allowed_tools_raw = fm.get("allowed-tools") or fm.get("allowedTools") or []
+
+        # Handle argument_hint as list (join with space) or string
+        argument_hint: str | None
+        if isinstance(argument_hint_raw, list):
+            argument_hint = " ".join(str(h) for h in argument_hint_raw)
+        elif argument_hint_raw is not None:
+            argument_hint = str(argument_hint_raw)
+        else:
+            argument_hint = None
+
+        # Ensure allowed_tools is a list of strings
+        allowed_tools: list[str]
+        if isinstance(allowed_tools_raw, str):
+            allowed_tools = [allowed_tools_raw]
+        elif isinstance(allowed_tools_raw, list):
+            allowed_tools = [str(t) for t in allowed_tools_raw]
+        else:
+            allowed_tools = []
+
+        # Remove known fields from metadata to get extras
+        known_fields = {
+            "description",
+            "argument-hint",
+            "argumentHint",
+            "allowed-tools",
+            "allowedTools",
+        }
+        metadata = {k: v for k, v in fm.items() if k not in known_fields}
+
+        return cls(
+            name=name,
+            description=description,
+            argument_hint=argument_hint,
+            allowed_tools=allowed_tools,
+            content=post.content.strip(),
+            source=str(command_path),
+            metadata=metadata,
+        )

openhands/sdk/tool/__init__.py

@@ -1,4 +1,9 @@
-from openhands.sdk.tool.builtins import BUILT_IN_TOOLS, FinishTool, ThinkTool
+from openhands.sdk.tool.builtins import (
+    BUILT_IN_TOOL_CLASSES,
+    BUILT_IN_TOOLS,
+    FinishTool,
+    ThinkTool,
+)
 from openhands.sdk.tool.registry import (
     list_registered_tools,
     register_tool,
@@ -28,6 +33,7 @@ __all__ = [
     "FinishTool",
     "ThinkTool",
     "BUILT_IN_TOOLS",
+    "BUILT_IN_TOOL_CLASSES",
     "register_tool",
     "resolve_tool",
     "list_registered_tools",

openhands/sdk/tool/builtins/__init__.py

@@ -21,8 +21,12 @@ from openhands.sdk.tool.builtins.think import (
 
 BUILT_IN_TOOLS = [FinishTool, ThinkTool]
 
+# Mapping of built-in tool class names to their classes, generated dynamically
+BUILT_IN_TOOL_CLASSES = {tool.__name__: tool for tool in BUILT_IN_TOOLS}
+
 __all__ = [
     "BUILT_IN_TOOLS",
+    "BUILT_IN_TOOL_CLASSES",
     "FinishTool",
     "FinishAction",
     "FinishObservation",

openhands/sdk/tool/tool.py

@@ -41,6 +41,7 @@ if TYPE_CHECKING:
 ActionT = TypeVar("ActionT", bound=Action)
 ObservationT = TypeVar("ObservationT", bound=Observation)
 _action_types_with_risk: dict[type, type] = {}
+_action_types_with_summary: dict[type, type] = {}
 
 
 def _camel_to_snake(name: str) -> str:
@@ -364,17 +365,18 @@ class ToolDefinition[ActionT, ObservationT](DiscriminatedUnionMixin, ABC):
         action_type: type[Schema] | None = None,
     ) -> dict[str, Any]:
         action_type = action_type or self.action_type
-        action_type_with_risk = create_action_type_with_risk(action_type)
 
+        # Apply security risk enhancement if enabled
         add_security_risk_prediction = add_security_risk_prediction and (
             self.annotations is None or (not self.annotations.readOnlyHint)
         )
-        schema = (
-            action_type_with_risk.to_mcp_schema()
-            if add_security_risk_prediction
-            else action_type.to_mcp_schema()
-        )
-        return schema
+        if add_security_risk_prediction:
+            action_type = create_action_type_with_risk(action_type)
+
+        # Always add summary field for transparency and explainability
+        action_type = _create_action_type_with_summary(action_type)
+
+        return action_type.to_mcp_schema()
 
     def to_openai_tool(
         self,
@@ -391,6 +393,10 @@ class ToolDefinition[ActionT, ObservationT](DiscriminatedUnionMixin, ABC):
             action_type: Optionally override the action_type to use for the schema.
                 This is useful for MCPTool to use a dynamically created action type
                 based on the tool's input schema.
+
+        Note:
+            Summary field is always added to the schema for transparency and
+            explainability of agent actions.
         """
         return ChatCompletionToolParam(
             type="function",
@@ -398,7 +404,8 @@ class ToolDefinition[ActionT, ObservationT](DiscriminatedUnionMixin, ABC):
                 name=self.name,
                 description=self.description,
                 parameters=self._get_tool_schema(
-                    add_security_risk_prediction, action_type
+                    add_security_risk_prediction,
+                    action_type,
                 ),
             ),
         )
@@ -412,6 +419,14 @@ class ToolDefinition[ActionT, ObservationT](DiscriminatedUnionMixin, ABC):
 
         For Responses API, function tools expect top-level keys:
         { "type": "function", "name": ..., "description": ..., "parameters": ... }
+
+        Args:
+            add_security_risk_prediction: Whether to add a `security_risk` field
+            action_type: Optional override for the action type
+
+        Note:
+            Summary field is always added to the schema for transparency and
+            explainability of agent actions.
         """
 
         return {
@@ -419,7 +434,8 @@ class ToolDefinition[ActionT, ObservationT](DiscriminatedUnionMixin, ABC):
             "name": self.name,
             "description": self.description,
             "parameters": self._get_tool_schema(
-                add_security_risk_prediction, action_type
+                add_security_risk_prediction,
+                action_type,
             ),
             "strict": False,
         }
@@ -479,3 +495,38 @@ def create_action_type_with_risk(action_type: type[Schema]) -> type[Schema]:
     )
     _action_types_with_risk[action_type] = action_type_with_risk
     return action_type_with_risk
+
+
+def _create_action_type_with_summary(action_type: type[Schema]) -> type[Schema]:
+    """Create a new action type with summary field for LLM to predict.
+
+    This dynamically adds a 'summary' field to the action schema, allowing
+    the LLM to provide a brief explanation of what each action does.
+
+    Args:
+        action_type: The original action type to enhance
+
+    Returns:
+        A new type that includes the summary field
+    """
+    action_type_with_summary = _action_types_with_summary.get(action_type)
+    if action_type_with_summary:
+        return action_type_with_summary
+
+    action_type_with_summary = type(
+        f"{action_type.__name__}WithSummary",
+        (action_type,),
+        {
+            "summary": Field(
+                default=None,
+                description=(
+                    "A concise summary (approximately 10 words) describing what "
+                    "this specific action does. Focus on the key operation and target. "
+                    "Example: 'List all Python files in current directory'"
+                ),
+            ),
+            "__annotations__": {"summary": str | None},
+        },
+    )
+    _action_types_with_summary[action_type] = action_type_with_summary
+    return action_type_with_summary