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

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.7.2
+Version: 1.7.4
 Summary: OpenHands SDK - Core functionality for building AI agents
 Requires-Python: >=3.12
 Requires-Dist: deprecation>=2.1.0
 Requires-Dist: fastmcp>=2.11.3
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: litellm>=1.80.10
-Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic>=2.12.5
 Requires-Dist: python-frontmatter>=1.1.0
 Requires-Dist: python-json-logger>=3.3.0
 Requires-Dist: tenacity>=9.1.2

{openhands_sdk-1.7.2 → openhands_sdk-1.7.4}/openhands/sdk/agent/agent.py

@@ -27,7 +27,10 @@ from openhands.sdk.event import (
     TokenEvent,
     UserRejectObservation,
 )
-from openhands.sdk.event.condenser import Condensation, CondensationRequest
+from openhands.sdk.event.condenser import (
+    Condensation,
+    CondensationRequest,
+)
 from openhands.sdk.llm import (
     LLMResponse,
     Message,
@@ -502,16 +505,29 @@ class Agent(AgentBase):
             )
 
         # Execute actions!
-        if should_enable_observability():
-            tool_name = extract_action_name(action_event)
-            observation: Observation = observe(name=tool_name, span_type="TOOL")(tool)(
-                action_event.action, conversation
+        try:
+            if should_enable_observability():
+                tool_name = extract_action_name(action_event)
+                observation: Observation = observe(name=tool_name, span_type="TOOL")(
+                    tool
+                )(action_event.action, conversation)
+            else:
+                observation = tool(action_event.action, conversation)
+            assert isinstance(observation, Observation), (
+                f"Tool '{tool.name}' executor must return an Observation"
             )
-        else:
-            observation = tool(action_event.action, conversation)
-        assert isinstance(observation, Observation), (
-            f"Tool '{tool.name}' executor must return an Observation"
-        )
+        except ValueError as e:
+            # Tool execution raised a ValueError (e.g., invalid argument combination)
+            # Convert to AgentErrorEvent so the agent can correct itself
+            err = f"Error executing tool '{tool.name}': {e}"
+            logger.warning(err)
+            error_event = AgentErrorEvent(
+                error=err,
+                tool_name=tool.name,
+                tool_call_id=action_event.tool_call.id,
+            )
+            on_event(error_event)
+            return error_event
 
         obs_event = ObservationEvent(
             observation=observation,

{openhands_sdk-1.7.2 → openhands_sdk-1.7.4}/openhands/sdk/agent/base.py

@@ -2,7 +2,7 @@ import os
 import re
 import sys
 from abc import ABC, abstractmethod
-from collections.abc import Generator, Iterable
+from collections.abc import Generator, Iterable, Sequence
 from concurrent.futures import ThreadPoolExecutor
 from typing import TYPE_CHECKING, Any
 
@@ -300,10 +300,19 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         NOTE: state will be mutated in-place.
         """
 
-    def resolve_diff_from_deserialized(self, persisted: "AgentBase") -> "AgentBase":
+    def resolve_diff_from_deserialized(
+        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`.
+
+        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).
         """
         if persisted.__class__ is not self.__class__:
             raise ValueError(
@@ -338,28 +347,57 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         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}
-
-        # Check that tool names match
-        runtime_names = set(runtime_tools_map.keys())
-        persisted_names = set(persisted_tools_map.keys())
+        # 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
+            from openhands.sdk.event import ActionEvent
+
+            used_tools = {
+                event.tool_name
+                for event in events
+                if isinstance(event, ActionEvent) and event.tool_name
+            }
 
-        if runtime_names != persisted_names:
+            # 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 "
+                    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: {missing_in_runtime}."
+                error_msg += f" Missing in runtime: {sorted(missing_in_runtime)}."
             if missing_in_persisted:
-                error_msg += f" Missing in persisted: {missing_in_persisted}."
+                error_msg += f" Missing in persisted: {sorted(missing_in_persisted)}."
             raise ValueError(error_msg)
 
         reconciled = persisted.model_copy(update=updates)
-        if self.model_dump(exclude_none=True) != reconciled.model_dump(
-            exclude_none=True
-        ):
+
+        # 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)}"

{openhands_sdk-1.7.2 → openhands_sdk-1.7.4}/openhands/sdk/context/condenser/__init__.py

@@ -1,5 +1,6 @@
 from openhands.sdk.context.condenser.base import (
     CondenserBase,
+    NoCondensationAvailableException,
     RollingCondenser,
 )
 from openhands.sdk.context.condenser.llm_summarizing_condenser import (
@@ -15,4 +16,5 @@ __all__ = [
     "NoOpCondenser",
     "PipelineCondenser",
     "LLMSummarizingCondenser",
+    "NoCondensationAvailableException",
 ]

{openhands_sdk-1.7.2 → openhands_sdk-1.7.4}/openhands/sdk/context/condenser/base.py

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from enum import Enum
 from logging import getLogger
 
 from openhands.sdk.context.view import View
@@ -66,6 +67,29 @@ class PipelinableCondenserBase(CondenserBase):
     condenser should not nest another pipeline condenser)"""
 
 
+class NoCondensationAvailableException(Exception):
+    """Raised when a condenser is asked to provide a condensation but none is available.
+
+    This can happen if the condenser's `should_condense` method returns True, but due to
+    API constraints no condensation can be generated.
+
+    When this exception is raised from a rolling condenser's `get_condensation` method,
+    the agent will fall back to using the uncondensed view for the next agent step.
+    """
+
+
+class CondensationRequirement(Enum):
+    """The type of condensation required by a rolling condenser."""
+
+    HARD = "hard"
+    """Indicates that a condensation is required right now, and the agent cannot proceed
+    without it.
+    """
+
+    SOFT = "soft"
+    """Indicates that a condensation is desired but not strictly required."""
+
+
 class RollingCondenser(PipelinableCondenserBase, ABC):
     """Base class for a specialized condenser strategy that applies condensation to a
     rolling history.
@@ -73,15 +97,27 @@ class RollingCondenser(PipelinableCondenserBase, ABC):
     The rolling history is generated by `View.from_events`, which analyzes all events in
     the history and produces a `View` object representing what will be sent to the LLM.
 
-    If `should_condense` says so, the condenser is then responsible for generating a
-    `Condensation` object from the `View` object. This will be added to the event
-    history which should -- when given to `get_view` -- produce the condensed `View` to
-    be passed to the LLM.
+    If `condensation_requirement` says so, the condenser is then responsible for
+    generating a `Condensation` object from the `View` object. This will be added to the
+    event history which should -- when given to `get_view` -- produce the condensed
+    `View` to be passed to the LLM.
     """
 
     @abstractmethod
-    def should_condense(self, view: View, agent_llm: LLM | None = None) -> bool:
-        """Determine if a view should be condensed."""
+    def condensation_requirement(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> CondensationRequirement | None:
+        """Determine how a view should be condensed.
+
+        Args:
+            view: The current view of the conversation history.
+            agent_llm: LLM instance used by the agent. Condensers use this for token
+                counting purposes. Defaults to None.
+
+        Returns:
+            CondensationRequirement | None: The type of condensation required, or None
+            if no condensation is needed.
+        """
 
     @abstractmethod
     def get_condensation(
@@ -92,8 +128,23 @@ class RollingCondenser(PipelinableCondenserBase, ABC):
     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, agent_llm=agent_llm):
-            return self.get_condensation(view, agent_llm=agent_llm)
+        request = self.condensation_requirement(view, agent_llm=agent_llm)
+        if request is not None:
+            try:
+                return self.get_condensation(view, agent_llm=agent_llm)
+
+            except NoCondensationAvailableException as e:
+                logger.debug(f"No condensation available: {e}")
+
+                if request == CondensationRequirement.SOFT:
+                    # For soft requests, we can just return the uncondensed view. This
+                    # request will _eventually_ be handled, but it's not critical that
+                    # we do so immediately.
+                    return view
+
+                # Otherwise re-raise the exception.
+                else:
+                    raise e
 
         # Otherwise we're safe to just return the view.
         else:

{openhands_sdk-1.7.2 → openhands_sdk-1.7.4}/openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -4,7 +4,11 @@ from enum import Enum
 
 from pydantic import Field, model_validator
 
-from openhands.sdk.context.condenser.base import RollingCondenser
+from openhands.sdk.context.condenser.base import (
+    CondensationRequirement,
+    NoCondensationAvailableException,
+    RollingCondenser,
+)
 from openhands.sdk.context.condenser.utils import (
     get_suffix_length_for_token_reduction,
     get_total_token_count,
@@ -84,9 +88,30 @@ class LLMSummarizingCondenser(RollingCondenser):
 
         return reasons
 
-    def should_condense(self, view: View, agent_llm: LLM | None = None) -> bool:
+    def condensation_requirement(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> CondensationRequirement | None:
         reasons = self.get_condensation_reasons(view, agent_llm)
-        return reasons != set()
+
+        # No reasons => no condensation needed.
+        if reasons == set():
+            return None
+
+        # If the reasons are for resource constraints, we can treat it as a soft
+        # requirement. We want to condense when we can, but there's still space in the
+        # context window or we'd also see Reason.REQUEST. That means we can delay the
+        # condensation if there isn't one available (based on the view's manipulation
+        # indices).
+        resource_reasons = {Reason.TOKENS, Reason.EVENTS}
+        if reasons.issubset(resource_reasons):
+            return CondensationRequirement.SOFT
+
+        # Requests -- whether they come from the user or the agent -- are always hard
+        # requirements. We need to condense now because:
+        # 1. the user expects it
+        # 2. the agent has no more room in the context window and can't continue
+        if Reason.REQUEST in reasons:
+            return CondensationRequirement.HARD
 
     def _get_summary_event_content(self, view: View) -> str:
         """Extract the text content from the summary event in the view, if any.
@@ -120,7 +145,12 @@ class LLMSummarizingCondenser(RollingCondenser):
 
         Returns:
             Condensation: The generated condensation object.
+
+        Raises:
+            ValueError: If forgotten_events is empty (0 events to condense).
         """
+        assert len(forgotten_events) > 0, "No events to condense."
+
         # Convert events to strings for the template
         event_strings = [str(forgotten_event) for forgotten_event in forgotten_events]
 
@@ -226,11 +256,19 @@ class LLMSummarizingCondenser(RollingCondenser):
     ) -> 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
         )
 
+        if not forgotten_events:
+            raise NoCondensationAvailableException(
+                "Cannot condense 0 events. This typically occurs when a tool loop "
+                "spans almost the entire view, leaving no valid range for forgetting "
+                "events. Consider adjusting keep_first or max_size parameters."
+            )
+
+        summary_event_content = self._get_summary_event_content(view)
+
         return self._generate_condensation(
             summary_event_content=summary_event_content,
             forgotten_events=forgotten_events,