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

openhands/sdk/__init__.py

@@ -41,6 +41,7 @@ from openhands.sdk.mcp import (
     MCPToolObservation,
     create_mcp_tools,
 )
+from openhands.sdk.plugin import Plugin
 from openhands.sdk.tool import (
     Action,
     Observation,
@@ -98,6 +99,7 @@ __all__ = [
     "LLMSummarizingCondenser",
     "FileStore",
     "LocalFileStore",
+    "Plugin",
     "register_tool",
     "resolve_tool",
     "list_registered_tools",

openhands/sdk/agent/agent.py

@@ -362,6 +362,30 @@ class Agent(AgentBase):
         security_risk = risk.SecurityRisk(raw)
         return security_risk
 
+    def _extract_summary(self, tool_name: str, arguments: dict) -> str:
+        """Extract and validate the summary field from tool arguments.
+
+        Summary field is always requested but optional - if LLM doesn't provide
+        it or provides invalid data, we generate a default summary using the
+        tool name and arguments.
+
+        Args:
+            tool_name: Name of the tool being called
+            arguments: Dictionary of tool arguments from LLM
+
+        Returns:
+            The summary string - either from LLM or a default generated one
+        """
+        summary = arguments.pop("summary", None)
+
+        # If valid summary provided by LLM, use it
+        if summary is not None and isinstance(summary, str) and summary.strip():
+            return summary
+
+        # Generate default summary: {tool_name}: {arguments}
+        args_str = json.dumps(arguments)
+        return f"{tool_name}: {args_str}"
+
     def _get_action_event(
         self,
         tool_call: MessageToolCall,
@@ -423,6 +447,8 @@ class Agent(AgentBase):
                 "Unexpected 'security_risk' key found in tool arguments"
             )
 
+            summary = self._extract_summary(tool.name, arguments)
+
             action: Action = tool.action_from_arguments(arguments)
         except (json.JSONDecodeError, ValidationError, ValueError) as e:
             err = (
@@ -462,6 +488,7 @@ class Agent(AgentBase):
             tool_call=tool_call,
             llm_response_id=llm_response_id,
             security_risk=security_risk,
+            summary=summary,
         )
         on_event(action_event)
         return action_event

openhands/sdk/agent/base.py

@@ -6,18 +6,28 @@ from collections.abc import Generator, Iterable, Sequence
 from concurrent.futures import ThreadPoolExecutor
 from typing import TYPE_CHECKING, Any
 
-from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+)
 
 from openhands.sdk.context.agent_context import AgentContext
-from openhands.sdk.context.condenser import CondenserBase, LLMSummarizingCondenser
+from openhands.sdk.context.condenser import CondenserBase
 from openhands.sdk.context.prompts.prompt import render_template
 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
 from openhands.sdk.mcp import create_mcp_tools
-from openhands.sdk.tool import BUILT_IN_TOOLS, Tool, ToolDefinition, resolve_tool
+from openhands.sdk.tool import (
+    BUILT_IN_TOOL_CLASSES,
+    BUILT_IN_TOOLS,
+    Tool,
+    ToolDefinition,
+    resolve_tool,
+)
 from openhands.sdk.utils.models import DiscriminatedUnionMixin
-from openhands.sdk.utils.pydantic_diff import pretty_pydantic_diff
 
 
 if TYPE_CHECKING:
@@ -81,6 +91,17 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         " added.",
         examples=["^(?!repomix)(.*)|^repomix.*pack_codebase.*$"],
     )
+    include_default_tools: list[str] = Field(
+        default_factory=lambda: [tool.__name__ for tool in BUILT_IN_TOOLS],
+        description=(
+            "List of default tool class names to include. By default, the agent "
+            "includes 'FinishTool' and 'ThinkTool'. Set to an empty list to disable "
+            "all default tools, or provide a subset to include only specific ones. "
+            "Example: include_default_tools=['FinishTool'] to only include FinishTool, "
+            "or include_default_tools=[] to disable all default tools."
+        ),
+        examples=[["FinishTool", "ThinkTool"], ["FinishTool"], []],
+    )
     agent_context: AgentContext | None = Field(
         default=None,
         description="Optional AgentContext to initialize "
@@ -89,7 +110,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             {
                 "skills": [
                     {
-                        "name": "repo.md",
+                        "name": "AGENTS.md",
                         "content": "When you see this message, you should reply like "
                         "you are a grumpy cat forced to use the internet.",
                         "type": "repo",
@@ -155,6 +176,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
 
     # Runtime materialized tools; private and non-serializable
     _tools: dict[str, ToolDefinition] = PrivateAttr(default_factory=dict)
+    _initialized: bool = PrivateAttr(default=False)
 
     @property
     def prompt_dir(self) -> str:
@@ -219,7 +241,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
     def _initialize(self, state: "ConversationState"):
         """Create an AgentBase instance from an AgentSpec."""
 
-        if self._tools:
+        if self._initialized:
             logger.warning("Agent already initialized; skipping re-initialization.")
             return
 
@@ -255,10 +277,17 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
                 f"{[tool.name for tool in tools]}",
             )
 
-        # Always include built-in tools; not subject to filtering
-        # Instantiate built-in tools using their .create() method
-        for tool_class in BUILT_IN_TOOLS:
-            tools.extend(tool_class.create(state))
+        # Include default tools from include_default_tools; not subject to regex
+        # filtering. Use explicit mapping to resolve tool class names.
+        for tool_name in self.include_default_tools:
+            tool_class = BUILT_IN_TOOL_CLASSES.get(tool_name)
+            if tool_class is None:
+                raise ValueError(
+                    f"Unknown built-in tool class: '{tool_name}'. "
+                    f"Expected one of: {list(BUILT_IN_TOOL_CLASSES.keys())}"
+                )
+            tool_instances = tool_class.create(state)
+            tools.extend(tool_instances)
 
         # Check tool types
         for tool in tools:
@@ -276,6 +305,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
 
         # Store tools in a dict for easy access
         self._tools = {tool.name: tool for tool in tools}
+        self._initialized = True
 
     @abstractmethod
     def step(
@@ -300,64 +330,52 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         NOTE: state will be mutated in-place.
         """
 
-    def resolve_diff_from_deserialized(
+    def verify(
         self,
         persisted: "AgentBase",
         events: "Sequence[Any] | None" = None,
     ) -> "AgentBase":
-        """
-        Return a new AgentBase instance equivalent to `persisted` but with
-        explicitly whitelisted fields (e.g. api_key) taken from `self`.
+        """Verify that we can resume this agent from persisted state.
+
+        This PR's goal is to *not* reconcile configuration between persisted and
+        runtime Agent instances. Instead, we verify compatibility requirements
+        and then continue with the runtime-provided Agent.
+
+        Compatibility requirements:
+        - Agent class/type must match.
+        - Tools:
+          - If events are provided, only tools that were actually used in history
+            must exist in runtime.
+          - If events are not provided, tool names must match exactly.
+
+        All other configuration (LLM, agent_context, condenser, system prompts,
+        etc.) can be freely changed between sessions.
 
         Args:
-            persisted: The persisted agent from the conversation state.
-            events: Optional event sequence to scan for used tools if tool
-                names don't match. Only scanned when needed (O(n) fallback).
+            persisted: The agent loaded from persisted state.
+            events: Optional event sequence to scan for used tools if tool names
+                don't match.
+
+        Returns:
+            This runtime agent (self) if verification passes.
+
+        Raises:
+            ValueError: If agent class or tools don't match.
         """
         if persisted.__class__ is not self.__class__:
             raise ValueError(
-                f"Cannot resolve from deserialized: persisted agent is of type "
+                "Cannot load from persisted: persisted agent is of type "
                 f"{persisted.__class__.__name__}, but self is of type "
                 f"{self.__class__.__name__}."
             )
 
-        # Get all LLMs from both self and persisted to reconcile them
-        new_llm = self.llm.resolve_diff_from_deserialized(persisted.llm)
-        updates: dict[str, Any] = {"llm": new_llm}
-
-        # Reconcile the condenser's LLM if it exists
-        if self.condenser is not None and persisted.condenser is not None:
-            # Check if both condensers are LLMSummarizingCondenser
-            # (which has an llm field)
-
-            if isinstance(self.condenser, LLMSummarizingCondenser) and isinstance(
-                persisted.condenser, LLMSummarizingCondenser
-            ):
-                new_condenser_llm = self.condenser.llm.resolve_diff_from_deserialized(
-                    persisted.condenser.llm
-                )
-                new_condenser = persisted.condenser.model_copy(
-                    update={"llm": new_condenser_llm}
-                )
-                updates["condenser"] = new_condenser
-
-        # Reconcile agent_context - always use the current environment's agent_context
-        # This allows resuming conversations from different directories and handles
-        # cases where skills, working directory, or other context has changed
-        if self.agent_context is not None:
-            updates["agent_context"] = self.agent_context
-
-        # Get tool names for comparison
         runtime_names = {tool.name for tool in self.tools}
         persisted_names = {tool.name for tool in persisted.tools}
 
-        # If tool names match exactly, no need to check event history
         if runtime_names == persisted_names:
-            # Tools unchanged, proceed normally
-            pass
-        elif events is not None:
-            # Tool names differ - scan events to find which tools were actually used
-            # This is O(n) but only happens when tools change
+            return self
+
+        if events is not None:
             from openhands.sdk.event import ActionEvent
 
             used_tools = {
@@ -366,43 +384,31 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
                 if isinstance(event, ActionEvent) and event.tool_name
             }
 
-            # Only require tools that were actually used in history
+            # Only require tools that were actually used in history.
             missing_used_tools = used_tools - runtime_names
             if missing_used_tools:
                 raise ValueError(
-                    f"Cannot resume conversation: tools that were used in history "
+                    "Cannot resume conversation: tools that were used in history "
                     f"are missing from runtime: {sorted(missing_used_tools)}. "
                     f"Available tools: {sorted(runtime_names)}"
                 )
-            # Update tools to match runtime (allows new tools to be added)
-            updates["tools"] = self.tools
-        else:
-            # No events provided - strict matching (legacy behavior)
-            missing_in_runtime = persisted_names - runtime_names
-            missing_in_persisted = runtime_names - persisted_names
-            error_msg = "Tools don't match between runtime and persisted agents."
-            if missing_in_runtime:
-                error_msg += f" Missing in runtime: {sorted(missing_in_runtime)}."
-            if missing_in_persisted:
-                error_msg += f" Missing in persisted: {sorted(missing_in_persisted)}."
-            raise ValueError(error_msg)
-
-        reconciled = persisted.model_copy(update=updates)
-
-        # Validate agent equality - exclude tools from comparison since we
-        # already validated tool requirements above
-        exclude_fields = {"tools"} if events is not None else set()
-        self_dump = self.model_dump(exclude_none=True, exclude=exclude_fields)
-        reconciled_dump = reconciled.model_dump(
-            exclude_none=True, exclude=exclude_fields
-        )
 
-        if self_dump != reconciled_dump:
-            raise ValueError(
-                "The Agent provided is different from the one in persisted state.\n"
-                f"Diff: {pretty_pydantic_diff(self, reconciled)}"
-            )
-        return reconciled
+            return self
+
+        # No events provided: strict tool name matching.
+        missing_in_runtime = persisted_names - runtime_names
+        missing_in_persisted = runtime_names - persisted_names
+
+        details: list[str] = []
+        if missing_in_runtime:
+            details.append(f"Missing in runtime: {sorted(missing_in_runtime)}")
+        if missing_in_persisted:
+            details.append(f"Missing in persisted: {sorted(missing_in_persisted)}")
+
+        suffix = f" ({'; '.join(details)})" if details else ""
+        raise ValueError(
+            "Tools don't match between runtime and persisted agents." + suffix
+        )
 
     def model_dump_succint(self, **kwargs):
         """Like model_dump, but excludes None fields by default."""
@@ -490,6 +496,6 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         Raises:
             RuntimeError: If the agent has not been initialized.
         """
-        if not self._tools:
+        if not self._initialized:
             raise RuntimeError("Agent not initialized; call initialize() before use")
         return self._tools

openhands/sdk/agent/prompts/system_prompt.j2

@@ -6,7 +6,7 @@ You are OpenHands agent, a helpful AI assistant that can interact with a compute
 </ROLE>
 
 <MEMORY>
-* Use `.openhands/skills/repo.md` under the repository root as your persistent memory for repository-specific knowledge and context.
+* Use `AGENTS.md` under the repository root as your persistent memory for repository-specific knowledge and context.
 * Add important insights, patterns, and learnings to this file to improve future task performance.
 * This repository skill is automatically loaded for every conversation and helps maintain context across sessions.
 * For more information about skills, see: https://docs.openhands.dev/overview/skills

openhands/sdk/agent/utils.py

@@ -209,6 +209,9 @@ def make_llm_completion(
         configured. This allows weaker models to omit risk field and bypass
         validation requirements when analyzer is disabled. For detailed logic,
         see `_extract_security_risk` method in agent.py.
+
+        Summary field is always added to tool schemas for transparency and
+        explainability of agent actions.
     """
     if llm.uses_responses_api():
         return llm.responses(

openhands/sdk/context/agent_context.py

@@ -11,6 +11,7 @@ from openhands.sdk.context.skills import (
     SkillKnowledge,
     load_public_skills,
     load_user_skills,
+    to_prompt,
 )
 from openhands.sdk.llm import Message, TextContent
 from openhands.sdk.llm.utils.model_prompt_spec import get_model_prompt_spec
@@ -167,8 +168,32 @@ class AgentContext(BaseModel):
         - Runtime information (e.g., available hosts, current date)
         - Conversation instructions (e.g., user preferences, task details)
         - Repository-specific instructions (collected from repo skills)
+        - Available skills list (for AgentSkills-format and triggered skills)
+
+        Skill categorization:
+        - AgentSkills-format (SKILL.md): Always in <available_skills> (progressive
+          disclosure). If has triggers, content is ALSO auto-injected on trigger
+          in user prompts.
+        - Legacy with trigger=None: Full content in <REPO_CONTEXT> (always active)
+        - Legacy with triggers: Listed in <available_skills>, injected on trigger
         """
-        repo_skills = [s for s in self.skills if s.trigger is None]
+        # Categorize skills based on format and trigger:
+        # - AgentSkills-format: always in available_skills (progressive disclosure)
+        # - Legacy: trigger=None -> REPO_CONTEXT, else -> available_skills
+        repo_skills: list[Skill] = []
+        available_skills: list[Skill] = []
+
+        for s in self.skills:
+            if s.is_agentskills_format:
+                # AgentSkills: always list (triggers also auto-inject via
+                # get_user_message_suffix)
+                available_skills.append(s)
+            elif s.trigger is None:
+                # Legacy OpenHands: no trigger = full content in REPO_CONTEXT
+                repo_skills.append(s)
+            else:
+                # Legacy OpenHands: has trigger = list in available_skills
+                available_skills.append(s)
 
         # Gate vendor-specific repo skills based on model family.
         if llm_model or llm_model_canonical:
@@ -189,16 +214,32 @@ class AgentContext(BaseModel):
                     filtered.append(s)
                 repo_skills = filtered
 
-        logger.debug(f"Triggered {len(repo_skills)} repository skills: {repo_skills}")
+        logger.debug(f"Loaded {len(repo_skills)} repository skills: {repo_skills}")
+
+        # Generate available skills prompt
+        available_skills_prompt = ""
+        if available_skills:
+            available_skills_prompt = to_prompt(available_skills)
+            logger.debug(
+                f"Generated available skills prompt for {len(available_skills)} skills"
+            )
+
         # Build the workspace context information
         secret_infos = self.get_secret_infos()
-        if repo_skills or self.system_message_suffix or secret_infos:
+        has_content = (
+            repo_skills
+            or self.system_message_suffix
+            or secret_infos
+            or available_skills_prompt
+        )
+        if has_content:
             formatted_text = render_template(
                 prompt_dir=str(PROMPT_DIR),
                 template_name="system_message_suffix.j2",
                 repo_skills=repo_skills,
                 system_message_suffix=self.system_message_suffix or "",
                 secret_infos=secret_infos,
+                available_skills_prompt=available_skills_prompt,
             ).strip()
             return formatted_text
         elif self.system_message_suffix and self.system_message_suffix.strip():
@@ -245,6 +286,7 @@ class AgentContext(BaseModel):
                         name=skill.name,
                         trigger=trigger,
                         content=skill.content,
+                        location=skill.source,
                     )
                 )
         if recalled_knowledge:

openhands/sdk/context/prompts/templates/skill_knowledge_info.j2

@@ -2,6 +2,10 @@
 <EXTRA_INFO>
 The following information has been included based on a keyword match for "{{ agent_info.trigger }}".
 It may or may not be relevant to the user's request.
+{% if agent_info.location %}
+Skill location: {{ agent_info.location }}
+(Use this path to resolve relative file references in the skill content below)
+{% endif %}
 
 {{ agent_info.content }}
 </EXTRA_INFO>

openhands/sdk/context/prompts/templates/system_message_suffix.j2

@@ -10,6 +10,15 @@ Please follow them while working.
 {% endfor %}
 </REPO_CONTEXT>
 {% endif %}
+{% if available_skills_prompt %}
+<SKILLS>
+The following skills are available and may be triggered by keywords or task types in your messages.
+When a skill is triggered, you will receive additional context and instructions.
+You can also directly look up a skill's full content by reading its location path, and use the skill's guidance proactively when relevant to your task.
+
+{{ available_skills_prompt }}
+</SKILLS>
+{% endif %}
 {% if system_message_suffix %}
 
 {{ system_message_suffix }}

openhands/sdk/context/skills/__init__.py

@@ -1,10 +1,12 @@
 from openhands.sdk.context.skills.exceptions import SkillValidationError
 from openhands.sdk.context.skills.skill import (
     Skill,
+    SkillResources,
     load_project_skills,
     load_public_skills,
     load_skills_from_dir,
     load_user_skills,
+    to_prompt,
 )
 from openhands.sdk.context.skills.trigger import (
     BaseTrigger,
@@ -12,10 +14,16 @@ from openhands.sdk.context.skills.trigger import (
     TaskTrigger,
 )
 from openhands.sdk.context.skills.types import SkillKnowledge
+from openhands.sdk.context.skills.utils import (
+    RESOURCE_DIRECTORIES,
+    discover_skill_resources,
+    validate_skill_name,
+)
 
 
 __all__ = [
     "Skill",
+    "SkillResources",
     "BaseTrigger",
     "KeywordTrigger",
     "TaskTrigger",
@@ -25,4 +33,8 @@ __all__ = [
     "load_project_skills",
     "load_public_skills",
     "SkillValidationError",
+    "discover_skill_resources",
+    "RESOURCE_DIRECTORIES",
+    "to_prompt",
+    "validate_skill_name",
 ]