openhands-sdk 1.7.0__tar.gz → 1.7.2__tar.gz

{openhands_sdk-1.7.0 → openhands_sdk-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.7.0
+Version: 1.7.2
 Summary: OpenHands SDK - Core functionality for building AI agents
 Requires-Python: >=3.12
 Requires-Dist: deprecation>=2.1.0

{openhands_sdk-1.7.0 → openhands_sdk-1.7.2}/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 (
@@ -144,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
@@ -462,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-1.7.0 → openhands_sdk-1.7.2}/openhands/sdk/agent/base.py

@@ -194,7 +194,10 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             **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

{openhands_sdk-1.7.0 → openhands_sdk-1.7.2}/openhands/sdk/agent/prompts/model_specific/openai_gpt/gpt-5-codex.j2

@@ -1,3 +1,2 @@
 * 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.
+* 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-1.7.0 → openhands_sdk-1.7.2}/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():

{openhands_sdk-1.7.0 → openhands_sdk-1.7.2}/openhands/sdk/context/agent_context.py

@@ -13,6 +13,7 @@ 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 SecretSource, SecretValue
 
@@ -154,7 +155,11 @@ class AgentContext(BaseModel):
             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:
@@ -164,11 +169,30 @@ 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_infos = self.get_secret_infos()
         if repo_skills or self.system_message_suffix or secret_infos:
-            # TODO(test): add a test for this rendering to make sure they work
             formatted_text = render_template(
                 prompt_dir=str(PROMPT_DIR),
                 template_name="system_message_suffix.j2",

{openhands_sdk-1.7.0 → openhands_sdk-1.7.2}/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:

openhands_sdk-1.7.2/openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -0,0 +1,238 @@
+import os
+from collections.abc import Sequence
+from enum import Enum
+
+from pydantic import Field, model_validator
+
+from openhands.sdk.context.condenser.base import RollingCondenser
+from openhands.sdk.context.condenser.utils import (
+    get_suffix_length_for_token_reduction,
+    get_total_token_count,
+)
+from openhands.sdk.context.prompts import render_template
+from openhands.sdk.context.view import View
+from openhands.sdk.event.base import LLMConvertibleEvent
+from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.event.llm_convertible import MessageEvent
+from openhands.sdk.llm import LLM, Message, TextContent
+from openhands.sdk.observability.laminar import observe
+
+
+class Reason(Enum):
+    """Reasons for condensation."""
+
+    REQUEST = "request"
+    TOKENS = "tokens"
+    EVENTS = "events"
+
+
+class LLMSummarizingCondenser(RollingCondenser):
+    """LLM-based condenser that summarizes forgotten events.
+
+    Uses an independent LLM (stored in the `llm` attribute) for generating summaries
+    of forgotten events. The optional `agent_llm` parameter passed to condense() is
+    the LLM used by the agent for token counting purposes, and you should not assume
+    it is the same as the one defined in this condenser.
+    """
+
+    llm: LLM
+    max_size: int = Field(default=240, gt=0)
+    max_tokens: int | None = None
+    keep_first: int = Field(default=2, ge=0)
+
+    @model_validator(mode="after")
+    def validate_keep_first_vs_max_size(self):
+        events_from_tail = self.max_size // 2 - self.keep_first - 1
+        if events_from_tail <= 0:
+            raise ValueError(
+                "keep_first must be less than max_size // 2 to leave room for "
+                "condensation"
+            )
+        return self
+
+    def handles_condensation_requests(self) -> bool:
+        return True
+
+    def get_condensation_reasons(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> set[Reason]:
+        """Determine the reasons why the view should be condensed.
+
+        Args:
+            view: The current view to evaluate.
+            agent_llm: The LLM used by the agent. Required if token counting is needed.
+
+        Returns:
+            A set of Reason enums indicating why condensation is needed.
+        """
+        reasons = set()
+
+        # Reason 1: Unhandled condensation request. The view handles the detection of
+        # these requests while processing the event stream.
+        if view.unhandled_condensation_request:
+            reasons.add(Reason.REQUEST)
+
+        # Reason 2: Token limit is provided and exceeded.
+        if self.max_tokens and agent_llm:
+            total_tokens = get_total_token_count(view.events, agent_llm)
+            if total_tokens > self.max_tokens:
+                reasons.add(Reason.TOKENS)
+
+        # Reason 3: View exceeds maximum size in number of events.
+        if len(view) > self.max_size:
+            reasons.add(Reason.EVENTS)
+
+        return reasons
+
+    def should_condense(self, view: View, agent_llm: LLM | None = None) -> bool:
+        reasons = self.get_condensation_reasons(view, agent_llm)
+        return reasons != set()
+
+    def _get_summary_event_content(self, view: View) -> str:
+        """Extract the text content from the summary event in the view, if any.
+
+        If there is no summary event or it does not contain text content, returns an
+        empty string.
+        """
+        summary_event_content: str = ""
+
+        summary_event = view.summary_event
+        if isinstance(summary_event, MessageEvent):
+            message_content = summary_event.llm_message.content[0]
+            if isinstance(message_content, TextContent):
+                summary_event_content = message_content.text
+
+        return summary_event_content
+
+    def _generate_condensation(
+        self,
+        summary_event_content: str,
+        forgotten_events: Sequence[LLMConvertibleEvent],
+        summary_offset: int,
+    ) -> Condensation:
+        """Generate a condensation by using the condenser's LLM to summarize forgotten
+        events.
+
+        Args:
+            summary_event_content: The content of the previous summary event.
+            forgotten_events: The list of events to be summarized.
+            summary_offset: The index where the summary event should be inserted.
+
+        Returns:
+            Condensation: The generated condensation object.
+        """
+        # Convert events to strings for the template
+        event_strings = [str(forgotten_event) for forgotten_event in forgotten_events]
+
+        prompt = render_template(
+            os.path.join(os.path.dirname(__file__), "prompts"),
+            "summarizing_prompt.j2",
+            previous_summary=summary_event_content,
+            events=event_strings,
+        )
+
+        messages = [Message(role="user", content=[TextContent(text=prompt)])]
+
+        # Do not pass extra_body explicitly. The LLM handles forwarding
+        # litellm_extra_body only when it is non-empty.
+        llm_response = self.llm.completion(
+            messages=messages,
+        )
+        # Extract summary from the LLMResponse message
+        summary = None
+        if llm_response.message.content:
+            first_content = llm_response.message.content[0]
+            if isinstance(first_content, TextContent):
+                summary = first_content.text
+
+        return Condensation(
+            forgotten_event_ids=[event.id for event in forgotten_events],
+            summary=summary,
+            summary_offset=summary_offset,
+            llm_response_id=llm_response.id,
+        )
+
+    def _get_forgotten_events(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> tuple[Sequence[LLMConvertibleEvent], int]:
+        """Identify events to be forgotten and the summary offset.
+
+        Relies on the condensation reasons to determine how many events we need to drop
+        in order to maintain our resource constraints. Uses manipulation indices to
+        ensure forgetting ranges respect atomic unit boundaries.
+
+        Args:
+            view: The current view from which to identify forgotten events.
+            agent_llm: The LLM used by the agent, required for token-based calculations.
+
+        Returns:
+            A tuple of (events to forget, summary_offset).
+        """
+        reasons = self.get_condensation_reasons(view, agent_llm=agent_llm)
+        assert reasons != set(), "No condensation reasons found."
+
+        suffix_events_to_keep: set[int] = set()
+
+        if Reason.REQUEST in reasons:
+            target_size = len(view) // 2
+            suffix_events_to_keep.add(target_size - self.keep_first - 1)
+
+        if Reason.EVENTS in reasons:
+            target_size = self.max_size // 2
+            suffix_events_to_keep.add(target_size - self.keep_first - 1)
+
+        if Reason.TOKENS in reasons:
+            # Compute the number of tokens we need to eliminate to be under half the
+            # max_tokens value. We know max_tokens and the agent LLM are not None here
+            # because we can't have Reason.TOKENS without them.
+            assert self.max_tokens is not None
+            assert agent_llm is not None
+
+            total_tokens = get_total_token_count(view.events, agent_llm)
+            tokens_to_reduce = total_tokens - (self.max_tokens // 2)
+
+            suffix_events_to_keep.add(
+                get_suffix_length_for_token_reduction(
+                    events=view.events[self.keep_first :],
+                    llm=agent_llm,
+                    token_reduction=tokens_to_reduce,
+                )
+            )
+
+        # We might have multiple reasons to condense, so pick the strictest condensation
+        # to ensure all resource constraints are met.
+        events_from_tail = min(suffix_events_to_keep)
+
+        # Calculate naive forgetting end (without considering atomic boundaries)
+        naive_end = len(view) - events_from_tail
+
+        # Find actual forgetting_start: smallest manipulation index > keep_first
+        forgetting_start = view.find_next_manipulation_index(
+            self.keep_first, strict=True
+        )
+
+        # Find actual forgetting_end: smallest manipulation index >= naive_end
+        forgetting_end = view.find_next_manipulation_index(naive_end, strict=False)
+
+        # Extract events to forget using boundary-aware indices
+        forgotten_events = view[forgetting_start:forgetting_end]
+
+        # Summary offset is the same as forgetting_start
+        return forgotten_events, forgetting_start
+
+    @observe(ignore_inputs=["view", "agent_llm"])
+    def get_condensation(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> Condensation:
+        # The condensation is dependent on the events we want to drop and the previous
+        # summary.
+        summary_event_content = self._get_summary_event_content(view)
+        forgotten_events, summary_offset = self._get_forgotten_events(
+            view, agent_llm=agent_llm
+        )
+
+        return self._generate_condensation(
+            summary_event_content=summary_event_content,
+            forgotten_events=forgotten_events,
+            summary_offset=summary_offset,
+        )

{openhands_sdk-1.7.0 → openhands_sdk-1.7.2}/openhands/sdk/context/condenser/no_op_condenser.py

@@ -1,6 +1,7 @@
 from openhands.sdk.context.condenser.base import CondenserBase
 from openhands.sdk.context.view import View
 from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.llm import LLM
 
 
 class NoOpCondenser(CondenserBase):
@@ -9,5 +10,5 @@ class NoOpCondenser(CondenserBase):
     Primarily intended for testing purposes.
     """
 
-    def condense(self, view: View) -> View | Condensation:
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:  # noqa: ARG002
         return view

{openhands_sdk-1.7.0 → openhands_sdk-1.7.2}/openhands/sdk/context/condenser/pipeline_condenser.py

@@ -1,15 +1,16 @@
 from openhands.sdk.context.condenser.base import CondenserBase
 from openhands.sdk.context.view import View
 from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.llm import LLM
 
 
 class PipelineCondenser(CondenserBase):
     """A condenser that applies a sequence of condensers in order.
 
     All condensers are defined primarily by their `condense` method, which takes a
-    `View` and returns either a new `View` or a `Condensation` event. That means we can
-    chain multiple condensers together by passing `View`s along and exiting early if any
-    condenser returns a `Condensation`.
+    `View` and an optional `agent_llm` parameter, returning either a new `View` or a
+    `Condensation` event. That means we can chain multiple condensers together by
+    passing `View`s along and exiting early if any condenser returns a `Condensation`.
 
     For example:
 
@@ -20,20 +21,20 @@ class PipelineCondenser(CondenserBase):
             CondenserC(...),
         ])
 
-        result = condenser.condense(view)
+        result = condenser.condense(view, agent_llm=agent_llm)
 
         # Doing the same thing without the pipeline condenser requires more boilerplate
         # for the monadic chaining
         other_result = view
 
         if isinstance(other_result, View):
-            other_result = CondenserA(...).condense(other_result)
+            other_result = CondenserA(...).condense(other_result, agent_llm=agent_llm)
 
         if isinstance(other_result, View):
-            other_result = CondenserB(...).condense(other_result)
+            other_result = CondenserB(...).condense(other_result, agent_llm=agent_llm)
 
         if isinstance(other_result, View):
-            other_result = CondenserC(...).condense(other_result)
+            other_result = CondenserC(...).condense(other_result, agent_llm=agent_llm)
 
         assert result == other_result
     """
@@ -41,12 +42,12 @@ class PipelineCondenser(CondenserBase):
     condensers: list[CondenserBase]
     """The list of condensers to apply in order."""
 
-    def condense(self, view: View) -> View | Condensation:
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
         result: View | Condensation = view
         for condenser in self.condensers:
             if isinstance(result, Condensation):
                 break
-            result = condenser.condense(result)
+            result = condenser.condense(result, agent_llm=agent_llm)
         return result
 
     def handles_condensation_requests(self) -> bool: