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

openhands/sdk/__init__.py

@@ -1,7 +1,12 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from openhands.sdk.agent import Agent, AgentBase
-from openhands.sdk.context import AgentContext
+from openhands.sdk.context import (
+    AgentContext,
+    load_project_skills,
+    load_skills_from_dir,
+    load_user_skills,
+)
 from openhands.sdk.context.condenser import (
     LLMSummarizingCondenser,
 )
@@ -99,5 +104,8 @@ __all__ = [
     "Workspace",
     "LocalWorkspace",
     "RemoteWorkspace",
+    "load_project_skills",
+    "load_skills_from_dir",
+    "load_user_skills",
     "__version__",
 ]

openhands/sdk/agent/agent.py

@@ -25,6 +25,7 @@ from openhands.sdk.event import (
     ObservationEvent,
     SystemPromptEvent,
     TokenEvent,
+    UserRejectObservation,
 )
 from openhands.sdk.event.condenser import Condensation, CondensationRequest
 from openhands.sdk.llm import (
@@ -109,17 +110,10 @@ class Agent(AgentBase):
             event = SystemPromptEvent(
                 source="agent",
                 system_prompt=TextContent(text=self.system_message),
-                # Always expose a 'security_risk' parameter in tool schemas.
-                # This ensures the schema remains consistent, even if the
-                # security analyzer is disabled. Validation of this field
-                # happens dynamically at runtime depending on the analyzer
-                # 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.
-                tools=[
-                    t.to_openai_tool(add_security_risk_prediction=True)
-                    for t in self.tools_map.values()
-                ],
+                # Tools are stored as ToolDefinition objects and converted to
+                # OpenAI format with security_risk parameter during LLM completion.
+                # See make_llm_completion() in agent/utils.py for details.
+                tools=list(self.tools_map.values()),
             )
             on_event(event)
 
@@ -151,9 +145,20 @@ class Agent(AgentBase):
             self._execute_actions(conversation, pending_actions, on_event)
             return
 
+        # Check if the last user message was blocked by a UserPromptSubmit hook
+        # If so, skip processing and mark conversation as finished
+        for event in reversed(list(state.events)):
+            if isinstance(event, MessageEvent) and event.source == "user":
+                reason = state.pop_blocked_message(event.id)
+                if reason is not None:
+                    logger.info(f"User message blocked by hook: {reason}")
+                    state.execution_status = ConversationExecutionStatus.FINISHED
+                    return
+                break  # Only check the most recent user message
+
         # Prepare LLM messages using the utility function
         _messages_or_condensation = prepare_llm_messages(
-            state.events, condenser=self.condenser
+            state.events, condenser=self.condenser, llm=self.llm
         )
 
         # Process condensation event before agent sampels another action
@@ -469,8 +474,26 @@ class Agent(AgentBase):
 
         It will call the tool's executor and update the state & call callback fn
         with the observation.
+
+        If the action was blocked by a PreToolUse hook (recorded in
+        state.blocked_actions), a UserRejectObservation is emitted instead
+        of executing the action.
         """
         state = conversation.state
+
+        # Check if this action was blocked by a PreToolUse hook
+        reason = state.pop_blocked_action(action_event.id)
+        if reason is not None:
+            logger.info(f"Action '{action_event.tool_name}' blocked by hook: {reason}")
+            rejection = UserRejectObservation(
+                action_id=action_event.id,
+                tool_name=action_event.tool_name,
+                tool_call_id=action_event.tool_call_id,
+                rejection_reason=reason,
+            )
+            on_event(rejection)
+            return rejection
+
         tool = self.tools_map.get(action_event.tool_name, None)
         if tool is None:
             raise RuntimeError(

openhands/sdk/agent/base.py

@@ -3,6 +3,7 @@ import re
 import sys
 from abc import ABC, abstractmethod
 from collections.abc import Generator, Iterable
+from concurrent.futures import ThreadPoolExecutor
 from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
@@ -11,6 +12,7 @@ from openhands.sdk.context.agent_context import AgentContext
 from openhands.sdk.context.condenser import CondenserBase, LLMSummarizingCondenser
 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
@@ -119,6 +121,15 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             "- An absolute path (e.g., '/path/to/custom_prompt.j2')"
         ),
     )
+    security_policy_filename: str = Field(
+        default="security_policy.j2",
+        description=(
+            "Security policy template filename. Can be either:\n"
+            "- A relative filename (e.g., 'security_policy.j2') loaded from the "
+            "agent's prompts directory\n"
+            "- An absolute path (e.g., '/path/to/custom_security_policy.j2')"
+        ),
+    )
     system_prompt_kwargs: dict[str, object] = Field(
         default_factory=dict,
         description="Optional kwargs to pass to the system prompt Jinja2 template.",
@@ -163,13 +174,30 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
     def system_message(self) -> str:
         """Compute system message on-demand to maintain statelessness."""
         template_kwargs = dict(self.system_prompt_kwargs)
+        # Add security_policy_filename to template kwargs
+        template_kwargs["security_policy_filename"] = self.security_policy_filename
+        template_kwargs.setdefault("model_name", self.llm.model)
+        if (
+            "model_family" not in template_kwargs
+            or "model_variant" not in template_kwargs
+        ):
+            spec = get_model_prompt_spec(
+                self.llm.model, getattr(self.llm, "model_canonical_name", None)
+            )
+            if "model_family" not in template_kwargs and spec.family:
+                template_kwargs["model_family"] = spec.family
+            if "model_variant" not in template_kwargs and spec.variant:
+                template_kwargs["model_variant"] = spec.variant
         system_message = render_template(
             prompt_dir=self.prompt_dir,
             template_name=self.system_prompt_filename,
             **template_kwargs,
         )
         if self.agent_context:
-            _system_message_suffix = self.agent_context.get_system_message_suffix()
+            _system_message_suffix = self.agent_context.get_system_message_suffix(
+                llm_model=self.llm.model,
+                llm_model_canonical=self.llm.model_canonical_name,
+            )
             if _system_message_suffix:
                 system_message += "\n\n" + _system_message_suffix
         return system_message
@@ -196,13 +224,25 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             return
 
         tools: list[ToolDefinition] = []
-        for tool_spec in self.tools:
-            tools.extend(resolve_tool(tool_spec, state))
 
-        # Add MCP tools if configured
-        if self.mcp_config:
-            mcp_tools = create_mcp_tools(self.mcp_config, timeout=30)
-            tools.extend(mcp_tools)
+        # Use ThreadPoolExecutor to parallelize tool resolution
+        with ThreadPoolExecutor(max_workers=4) as executor:
+            futures = []
+
+            # Submit tool resolution tasks
+            for tool_spec in self.tools:
+                future = executor.submit(resolve_tool, tool_spec, state)
+                futures.append(future)
+
+            # Submit MCP tools creation if configured
+            if self.mcp_config:
+                future = executor.submit(create_mcp_tools, self.mcp_config, 30)
+                futures.append(future)
+
+            # Collect results as they complete
+            for future in futures:
+                result = future.result()
+                tools.extend(result)
 
         logger.info(
             f"Loaded {len(tools)} tools from spec: {[tool.name for tool in tools]}"
@@ -292,6 +332,12 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
                 )
                 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
+
         # Create maps by tool name for easy lookup
         runtime_tools_map = {tool.name: tool for tool in self.tools}
         persisted_tools_map = {tool.name: tool for tool in persisted.tools}

openhands/sdk/agent/prompts/model_specific/anthropic_claude.j2

@@ -0,0 +1,3 @@
+* Try to follow the instructions exactly as given - don't make extra or fewer actions if not asked.
+* Avoid unnecessary defensive programming; do not add redundant fallbacks or default values — fail fast instead of masking misconfigurations.
+* When backward compatibility expectations are unclear, confirm with the user before making changes that could break existing behavior.

openhands/sdk/agent/prompts/model_specific/google_gemini.j2

@@ -0,0 +1 @@
+* Avoid being too proactive. Fulfill the user's request thoroughly: if they ask questions/investigations, answer them; if they ask for implementations, provide them. But do not take extra steps beyond what is requested.

openhands/sdk/agent/prompts/model_specific/openai_gpt/gpt-5-codex.j2

@@ -0,0 +1,2 @@
+* Stream your thinking and responses while staying concise; surface key assumptions and environment prerequisites explicitly.
+* You have access to external resources and should actively use available tools to try accessing them first, rather than claiming you can’t access something without making an attempt.

openhands/sdk/agent/prompts/model_specific/openai_gpt/gpt-5.j2

@@ -0,0 +1,3 @@
+* Stream your thinking and responses while staying concise; surface key assumptions and environment prerequisites explicitly.
+* ALWAYS send a brief preamble to the user explaining what you're about to do before each tool call, using 8 - 12 words, with a friendly and curious tone.
+* You have access to external resources and should actively use available tools to try accessing them first, rather than claiming you can’t access something without making an attempt.

openhands/sdk/agent/prompts/self_documentation.j2

@@ -0,0 +1,15 @@
+When the user directly asks about any of the following:
+- OpenHands capabilities (e.g., "can OpenHands do...", "does OpenHands have...")
+- what you're able to do in second person (e.g., "are you able...", "can you...")
+- how to use a specific OpenHands feature or product
+- how to use the OpenHands SDK, CLI, GUI, or other OpenHands products
+
+Get accurate information from the official OpenHands documentation at <https://docs.openhands.dev/>. The documentation includes:
+
+**OpenHands SDK** (`/sdk/*`): Python library for building AI agents; Getting Started, Architecture, Guides (agent, llm, conversation, tools), API Reference
+**OpenHands CLI** (`/openhands/usage/run-openhands/cli-mode`): Command-line interface
+**OpenHands GUI** (`/openhands/usage/run-openhands/local-setup`): Local GUI and REST API
+**OpenHands Cloud** (`/openhands/usage/run-openhands/cloud`): Hosted solution with integrations
+**OpenHands Enterprise**: Self-hosted deployment with extended support
+
+Always provide links to the relevant documentation pages for users who want to learn more.

openhands/sdk/agent/prompts/system_prompt.j2

@@ -5,6 +5,13 @@ You are OpenHands agent, a helpful AI assistant that can interact with a compute
 * If the user asks a question, like "why is X happening", don't try to fix the problem. Just give an answer to the question.
 </ROLE>
 
+<MEMORY>
+* Use `.openhands/skills/repo.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
+</MEMORY>
+
 <EFFICIENCY>
 * Each action you take is somewhat expensive. Wherever possible, combine multiple actions into a single action, e.g. combine multiple bash commands into one, using sed and grep to edit/view multiple files at once.
 * When exploring the codebase, use efficient tools like find, grep, and git commands with appropriate filters to minimize unnecessary operations.
@@ -62,8 +69,12 @@ You are OpenHands agent, a helpful AI assistant that can interact with a compute
 5. VERIFICATION: If the environment is set up to run tests, test your implementation thoroughly, including edge cases. If the environment is not set up to run tests, consult with the user first before investing time to run tests.
 </PROBLEM_SOLVING_WORKFLOW>
 
+<SELF_DOCUMENTATION>
+{% include 'self_documentation.j2' %}
+</SELF_DOCUMENTATION>
+
 <SECURITY>
-{% include 'security_policy.j2' %}
+{% include security_policy_filename %}
 </SECURITY>
 
 {% if llm_security_analyzer %}
@@ -102,3 +113,20 @@ You are OpenHands agent, a helpful AI assistant that can interact with a compute
   - Prefer using `ps aux` to find the exact process ID (PID) first, then kill that specific PID
   - When possible, use more targeted approaches like finding the PID from a pidfile or using application-specific shutdown commands
 </PROCESS_MANAGEMENT>
+
+{%- set _imp -%}
+{%- if model_family -%}
+{%- include "model_specific/" ~ model_family ~ ".j2" ignore missing -%}
+{%- if model_variant -%}
+{%- include "model_specific/" ~ model_family ~ "/" ~ model_variant ~ ".j2" ignore missing -%}
+{%- endif -%}
+{%- endif -%}
+{%- endset -%}
+
+{%- set _imp_trimmed = _imp | trim -%}
+{%- if _imp_trimmed %}
+
+<IMPORTANT>
+{{ _imp_trimmed }}
+</IMPORTANT>
+{%- endif %}

openhands/sdk/agent/utils.py

@@ -117,6 +117,7 @@ def prepare_llm_messages(
     events: Sequence[Event],
     condenser: None = None,
     additional_messages: list[Message] | None = None,
+    llm: LLM | None = None,
 ) -> list[Message]: ...
 
 
@@ -125,6 +126,7 @@ def prepare_llm_messages(
     events: Sequence[Event],
     condenser: CondenserBase,
     additional_messages: list[Message] | None = None,
+    llm: LLM | None = None,
 ) -> list[Message] | Condensation: ...
 
 
@@ -132,6 +134,7 @@ def prepare_llm_messages(
     events: Sequence[Event],
     condenser: CondenserBase | None = None,
     additional_messages: list[Message] | None = None,
+    llm: LLM | None = None,
 ) -> list[Message] | Condensation:
     """Prepare LLM messages from conversation context.
 
@@ -140,13 +143,15 @@ def prepare_llm_messages(
     It handles condensation internally and calls the callback when needed.
 
     Args:
-        state: The conversation state containing events
+        events: Sequence of events to prepare messages from
         condenser: Optional condenser for handling context window limits
         additional_messages: Optional additional messages to append
-        on_event: Optional callback for handling condensation events
+        llm: Optional LLM instance from the agent, passed to condenser for
+            token counting or other LLM features
 
     Returns:
-        List of messages ready for LLM completion
+        List of messages ready for LLM completion, or a Condensation event
+        if condensation is needed
 
     Raises:
         RuntimeError: If condensation is needed but no callback is provided
@@ -160,7 +165,7 @@ def prepare_llm_messages(
     # produce a list of events, exactly as expected, or a
     # new condensation that needs to be processed
     if condenser is not None:
-        condensation_result = condenser.condense(view)
+        condensation_result = condenser.condense(view, agent_llm=llm)
 
         match condensation_result:
             case View():
@@ -195,6 +200,15 @@ def make_llm_completion(
 
     Returns:
         LLMResponse from the LLM completion call
+
+    Note:
+        Always exposes a 'security_risk' parameter in tool schemas via
+        add_security_risk_prediction=True. This ensures the schema remains
+        consistent, even if the security analyzer is disabled. Validation of
+        this field happens dynamically at runtime depending on the analyzer
+        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.
     """
     if llm.uses_responses_api():
         return llm.responses(

openhands/sdk/context/__init__.py

@@ -7,6 +7,7 @@ from openhands.sdk.context.skills import (
     SkillKnowledge,
     SkillValidationError,
     TaskTrigger,
+    load_project_skills,
     load_skills_from_dir,
     load_user_skills,
 )
@@ -21,6 +22,7 @@ __all__ = [
     "SkillKnowledge",
     "load_skills_from_dir",
     "load_user_skills",
+    "load_project_skills",
     "render_template",
     "SkillValidationError",
 ]

openhands/sdk/context/agent_context.py

@@ -13,8 +13,9 @@ from openhands.sdk.context.skills import (
     load_user_skills,
 )
 from openhands.sdk.llm import Message, TextContent
+from openhands.sdk.llm.utils.model_prompt_spec import get_model_prompt_spec
 from openhands.sdk.logger import get_logger
-from openhands.sdk.secret import SecretValue
+from openhands.sdk.secret import SecretSource, SecretValue
 
 
 logger = get_logger(__name__)
@@ -136,17 +137,29 @@ class AgentContext(BaseModel):
             logger.warning(f"Failed to load public skills: {str(e)}")
         return self
 
-    def get_secret_names(self) -> list[str]:
-        """Get the list of secret names from the secrets field.
+    def get_secret_infos(self) -> list[dict[str, str]]:
+        """Get secret information (name and description) from the secrets field.
 
         Returns:
-            List of secret names. Returns an empty list if no secrets are configured.
+            List of dictionaries with 'name' and 'description' keys.
+            Returns an empty list if no secrets are configured.
+            Description will be None if not available.
         """
         if not self.secrets:
             return []
-        return list(self.secrets.keys())
+        secret_infos = []
+        for name, secret_value in self.secrets.items():
+            description = None
+            if isinstance(secret_value, SecretSource):
+                description = secret_value.description
+            secret_infos.append({"name": name, "description": description})
+        return secret_infos
 
-    def get_system_message_suffix(self) -> str | None:
+    def get_system_message_suffix(
+        self,
+        llm_model: str | None = None,
+        llm_model_canonical: str | None = None,
+    ) -> str | None:
         """Get the system message with repo skill content and custom suffix.
 
         Custom suffix can typically includes:
@@ -156,17 +169,36 @@ class AgentContext(BaseModel):
         - Repository-specific instructions (collected from repo skills)
         """
         repo_skills = [s for s in self.skills if s.trigger is None]
+
+        # Gate vendor-specific repo skills based on model family.
+        if llm_model or llm_model_canonical:
+            spec = get_model_prompt_spec(llm_model or "", llm_model_canonical)
+            family = (spec.family or "").lower()
+            if family:
+                filtered: list[Skill] = []
+                for s in repo_skills:
+                    n = (s.name or "").lower()
+                    if n == "claude" and not (
+                        "anthropic" in family or "claude" in family
+                    ):
+                        continue
+                    if n == "gemini" and not (
+                        "gemini" in family or "google_gemini" in family
+                    ):
+                        continue
+                    filtered.append(s)
+                repo_skills = filtered
+
         logger.debug(f"Triggered {len(repo_skills)} repository skills: {repo_skills}")
         # Build the workspace context information
-        secret_names = self.get_secret_names()
-        if repo_skills or self.system_message_suffix or secret_names:
-            # TODO(test): add a test for this rendering to make sure they work
+        secret_infos = self.get_secret_infos()
+        if repo_skills or self.system_message_suffix or secret_infos:
             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_names=secret_names,
+                secret_infos=secret_infos,
             ).strip()
             return formatted_text
         elif self.system_message_suffix and self.system_message_suffix.strip():

openhands/sdk/context/condenser/base.py

@@ -3,6 +3,7 @@ from logging import getLogger
 
 from openhands.sdk.context.view import View
 from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.llm import LLM
 from openhands.sdk.utils.models import (
     DiscriminatedUnionMixin,
 )
@@ -28,7 +29,7 @@ class CondenserBase(DiscriminatedUnionMixin, ABC):
     """
 
     @abstractmethod
-    def condense(self, view: View) -> View | Condensation:
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
         """Condense a sequence of events into a potentially smaller list.
 
         New condenser strategies should override this method to implement their own
@@ -37,6 +38,8 @@ class CondenserBase(DiscriminatedUnionMixin, ABC):
 
         Args:
             view: A view of the history containing all events that should be condensed.
+            agent_llm: LLM instance used by the agent. Condensers use this for token
+                counting purposes. Defaults to None.
 
         Returns:
             View | Condensation: A condensed view of the events or an event indicating
@@ -77,18 +80,20 @@ class RollingCondenser(PipelinableCondenserBase, ABC):
     """
 
     @abstractmethod
-    def should_condense(self, view: View) -> bool:
+    def should_condense(self, view: View, agent_llm: LLM | None = None) -> bool:
         """Determine if a view should be condensed."""
 
     @abstractmethod
-    def get_condensation(self, view: View) -> Condensation:
+    def get_condensation(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> Condensation:
         """Get the condensation from a view."""
 
-    def condense(self, view: View) -> View | Condensation:
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
         # If we trigger the condenser-specific condensation threshold, compute and
         # return the condensation.
-        if self.should_condense(view):
-            return self.get_condensation(view)
+        if self.should_condense(view, agent_llm=agent_llm):
+            return self.get_condensation(view, agent_llm=agent_llm)
 
         # Otherwise we're safe to just return the view.
         else: