openhands-sdk 1.7.0__py3-none-any.whl → 1.7.1__py3-none-any.whl

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/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/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/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/context/condenser/llm_summarizing_condenser.py

@@ -1,19 +1,43 @@
 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=120, gt=0)
+    max_tokens: int | None = None
     keep_first: int = Field(default=4, ge=0)
 
     @model_validator(mode="after")
@@ -29,23 +53,47 @@ class LLMSummarizingCondenser(RollingCondenser):
     def handles_condensation_requests(self) -> bool:
         return True
 
-    def should_condense(self, view: View) -> bool:
-        if view.unhandled_condensation_request:
-            return True
-        return len(view) > self.max_size
+    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.
 
-    @observe(ignore_inputs=["view"])
-    def get_condensation(self, view: View) -> Condensation:
-        head = view[: self.keep_first]
-        target_size = self.max_size // 2
+        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:
-            # Condensation triggered by a condensation request
-            # should be calculated based on the view size.
-            target_size = len(view) // 2
-        # Number of events to keep from the tail -- target size, minus however many
-        # prefix events from the head, minus one for the summarization event
-        events_from_tail = target_size - len(head) - 1
+            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
@@ -54,9 +102,25 @@ class LLMSummarizingCondenser(RollingCondenser):
             if isinstance(message_content, TextContent):
                 summary_event_content = message_content.text
 
-        # Identify events to be forgotten (those not in head or tail)
-        forgotten_events = view[self.keep_first : -events_from_tail]
-
+        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]
 
@@ -84,6 +148,91 @@ class LLMSummarizingCondenser(RollingCondenser):
         return Condensation(
             forgotten_event_ids=[event.id for event in forgotten_events],
             summary=summary,
-            summary_offset=self.keep_first,
+            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/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/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:

openhands/sdk/context/condenser/utils.py

@@ -0,0 +1,149 @@
+from collections.abc import Sequence
+
+from openhands.sdk.event.base import LLMConvertibleEvent
+from openhands.sdk.llm import LLM
+
+
+def get_total_token_count(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+) -> int:
+    """Calculate the total token count for a list of LLM convertible events.
+
+    This function converts the events to LLM messages and uses the provided LLM
+    to count the total number of tokens. This is useful for understanding how many
+    tokens a sequence of events will consume in the context window.
+
+    Args:
+        events: List of LLM convertible events to count tokens for
+        llm: The LLM instance to use for token counting (uses the litellm's token
+            counting utilities)
+
+    Returns:
+        Total token count for all events converted to messages
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Hello, how are you?", source="user"),
+        ...     MessageEvent.from_text("I'm doing great!", source="agent"),
+        ... ]
+        >>> token_count = get_total_token_count(events, llm)
+        >>> print(f"Total tokens: {token_count}")
+    """
+    messages = LLMConvertibleEvent.events_to_messages(list(events))
+    return llm.get_token_count(messages)
+
+
+def get_shortest_prefix_above_token_count(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+    token_count: int,
+) -> int:
+    """Find the length of the shortest prefix whose token count exceeds the target.
+
+    This function performs a binary search to efficiently find the shortest prefix
+    of events that, when converted to messages, has a total token count greater than
+    the specified target token count.
+
+    Args:
+        events: List of LLM convertible events to search through
+        llm: The LLM instance to use for token counting (uses the model's tokenizer)
+        token_count: The target token count threshold
+
+    Returns:
+        The length of the shortest prefix that exceeds the token count.
+        Returns 0 if no events are provided.
+        Returns len(events) if all events combined don't exceed the token count.
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Hi", source="user"),
+        ...     MessageEvent.from_text("Hello", source="agent"),
+        ...     MessageEvent.from_text("How are you?", source="user"),
+        ...     MessageEvent.from_text("Great!", source="agent"),
+        ... ]
+        >>> prefix_len = get_shortest_prefix_above_token_count(events, llm, 20)
+        >>> # prefix_len might be 2 if first 2 events exceed 20 tokens
+    """
+    if not events:
+        return 0
+
+    # Check if all events combined don't exceed the token count
+    total_tokens = get_total_token_count(events, llm)
+    if total_tokens <= token_count:
+        return len(events)
+
+    # Binary search for the shortest prefix
+    left, right = 1, len(events)
+
+    while left < right:
+        mid = (left + right) // 2
+        prefix_tokens = get_total_token_count(events[:mid], llm)
+
+        if prefix_tokens > token_count:
+            # This prefix exceeds the count, try to find a shorter one
+            right = mid
+        else:
+            # This prefix doesn't exceed, we need a longer one
+            left = mid + 1
+
+    return left
+
+
+def get_suffix_length_for_token_reduction(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+    token_reduction: int,
+) -> int:
+    """Find how many suffix events can be kept while reducing tokens by target amount.
+
+    This function determines the maximum number of events from the end of the list
+    that can be retained while ensuring the total token count is reduced by at least
+    the specified amount. It uses the get_shortest_prefix_above_token_count function
+    to find the prefix that must be removed.
+
+    Args:
+        events: List of LLM convertible events
+        llm: The LLM instance to use for token counting (uses the model's tokenizer)
+        token_reduction: The minimum number of tokens to reduce by
+
+    Returns:
+        The number of events from the end that can be kept (suffix length).
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Event 1", source="user"),
+        ...     MessageEvent.from_text("Event 2", source="agent"),
+        ...     MessageEvent.from_text("Event 3", source="user"),
+        ...     MessageEvent.from_text("Event 4", source="agent"),
+        ... ]
+        >>> # Suppose total is 100 tokens, and we want to reduce by 40 tokens
+        >>> suffix_len = get_suffix_length_for_token_reduction(events, llm, 40)
+        >>> # suffix_len tells us how many events from the end we can keep
+        >>> # If first 2 events = 45 tokens, suffix_len = 2 (keep last 2 events)
+    """
+    if not events:
+        return 0
+
+    if token_reduction <= 0:
+        return len(events)
+
+    # Find the shortest prefix that exceeds the token reduction target
+    prefix_length = get_shortest_prefix_above_token_count(events, llm, token_reduction)
+
+    # The suffix length is what remains after removing the prefix
+    suffix_length = len(events) - prefix_length
+
+    return suffix_length