openhands-sdk 1.9.0__py3-none-any.whl → 1.10.0__py3-none-any.whl

openhands/sdk/agent/agent.py

@@ -106,20 +106,61 @@ class Agent(AgentBase):
         # TODO(openhands): we should add test to test this init_state will actually
         # modify state in-place
 
-        llm_convertible_messages = [
-            event for event in state.events if isinstance(event, LLMConvertibleEvent)
-        ]
-        if len(llm_convertible_messages) == 0:
-            # Prepare system message
-            event = SystemPromptEvent(
-                source="agent",
-                system_prompt=TextContent(text=self.system_message),
-                # 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()),
+        # Defensive check: Analyze state to detect unexpected initialization scenarios
+        # These checks help diagnose issues related to lazy loading and event ordering
+        # See: https://github.com/OpenHands/software-agent-sdk/issues/1785
+        events = list(state.events)
+        has_system_prompt = any(isinstance(e, SystemPromptEvent) for e in events)
+        has_user_message = any(
+            isinstance(e, MessageEvent) and e.source == "user" for e in events
+        )
+        has_any_llm_event = any(isinstance(e, LLMConvertibleEvent) for e in events)
+
+        # Log state for debugging initialization order issues
+        logger.debug(
+            f"init_state called: conversation_id={state.id}, "
+            f"event_count={len(events)}, "
+            f"has_system_prompt={has_system_prompt}, "
+            f"has_user_message={has_user_message}, "
+            f"has_any_llm_event={has_any_llm_event}"
+        )
+
+        if has_system_prompt:
+            # SystemPromptEvent already exists - this is unexpected during normal flow
+            # but could happen in persistence/resume scenarios
+            logger.warning(
+                f"init_state called but SystemPromptEvent already exists. "
+                f"conversation_id={state.id}, event_count={len(events)}. "
+                f"This may indicate double initialization or a resume scenario."
             )
-            on_event(event)
+            return
+
+        # Assert: If there are user messages but no system prompt, something is wrong
+        # The system prompt should always be added before any user messages
+        if has_user_message:
+            event_types = [type(e).__name__ for e in events]
+            logger.error(
+                f"init_state: User message exists without SystemPromptEvent! "
+                f"conversation_id={state.id}, events={event_types}"
+            )
+            assert not has_user_message, (
+                f"Unexpected state: User message exists before SystemPromptEvent. "
+                f"conversation_id={state.id}, event_count={len(events)}, "
+                f"event_types={event_types}. "
+                f"This indicates an initialization order bug - init_state should be "
+                f"called before any user messages are added to the conversation."
+            )
+
+        # Prepare system message
+        event = SystemPromptEvent(
+            source="agent",
+            system_prompt=TextContent(text=self.system_message),
+            # 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)
 
     def _should_evaluate_with_critic(self, action: Action | None) -> bool:
         """Determine if critic should evaluate based on action type and mode."""

openhands/sdk/agent/base.py

@@ -345,28 +345,28 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
     def verify(
         self,
         persisted: AgentBase,
-        events: Sequence[Any] | None = None,
+        events: Sequence[Any] | None = None,  # noqa: ARG002
     ) -> AgentBase:
         """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.
+        We do not merge 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.
+        - Tools must match exactly (same tool names).
 
-        All other configuration (LLM, agent_context, condenser, system prompts,
-        etc.) can be freely changed between sessions.
+        Tools are part of the system prompt and cannot be changed mid-conversation.
+        To use different tools, start a new conversation or use conversation forking
+        (see https://github.com/OpenHands/OpenHands/issues/8560).
+
+        All other configuration (LLM, agent_context, condenser, etc.) can be
+        freely changed between sessions.
 
         Args:
             persisted: The agent loaded from persisted state.
-            events: Optional event sequence to scan for used tools if tool names
-                don't match.
+            events: Unused, kept for API compatibility.
 
         Returns:
             This runtime agent (self) if verification passes.
@@ -381,52 +381,39 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
                 f"{self.__class__.__name__}."
             )
 
+        # Collect explicit tool names
         runtime_names = {tool.name for tool in self.tools}
         persisted_names = {tool.name for tool in persisted.tools}
 
-        if runtime_names == persisted_names:
-            return self
-
-        if events is not None:
-            from openhands.sdk.event import ActionEvent
-
-            used_tools = {
-                event.tool_name
-                for event in events
-                if isinstance(event, ActionEvent) and event.tool_name
-            }
+        # Add builtin tool names from include_default_tools
+        # These are runtime names like 'finish', 'think'
+        for tool_class_name in self.include_default_tools:
+            tool_class = BUILT_IN_TOOL_CLASSES.get(tool_class_name)
+            if tool_class is not None:
+                runtime_names.add(tool_class.name)
 
-            # Add builtin tool names from include_default_tools
-            # These are runtime names like 'finish', 'think'
-            for tool_class_name in self.include_default_tools:
-                tool_class = BUILT_IN_TOOL_CLASSES.get(tool_class_name)
-                if tool_class is not None:
-                    runtime_names.add(tool_class.name)
-
-            # Only require tools that were actually used in history.
-            missing_used_tools = used_tools - runtime_names
-            if missing_used_tools:
-                raise ValueError(
-                    "Cannot resume conversation: tools that were used in history "
-                    f"are missing from runtime: {sorted(missing_used_tools)}. "
-                    f"Available tools: {sorted(runtime_names)}"
-                )
+        for tool_class_name in persisted.include_default_tools:
+            tool_class = BUILT_IN_TOOL_CLASSES.get(tool_class_name)
+            if tool_class is not None:
+                persisted_names.add(tool_class.name)
 
+        if runtime_names == persisted_names:
             return self
 
-        # No events provided: strict tool name matching.
+        # Tools don't match - this is not allowed
         missing_in_runtime = persisted_names - runtime_names
-        missing_in_persisted = runtime_names - persisted_names
+        added_in_runtime = 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)}")
+            details.append(f"removed: {sorted(missing_in_runtime)}")
+        if added_in_runtime:
+            details.append(f"added: {sorted(added_in_runtime)}")
 
-        suffix = f" ({'; '.join(details)})" if details else ""
         raise ValueError(
-            "Tools don't match between runtime and persisted agents." + suffix
+            f"Cannot resume conversation: tools cannot be changed mid-conversation "
+            f"({'; '.join(details)}). "
+            f"To use different tools, start a new conversation."
         )
 
     def model_dump_succint(self, **kwargs):

openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -17,7 +17,6 @@ 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
 
@@ -117,25 +116,8 @@ class LLMSummarizingCondenser(RollingCondenser):
         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.
-
-        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:
@@ -143,7 +125,6 @@ class LLMSummarizingCondenser(RollingCondenser):
         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.
 
@@ -161,7 +142,6 @@ class LLMSummarizingCondenser(RollingCondenser):
         prompt = render_template(
             os.path.join(os.path.dirname(__file__), "prompts"),
             "summarizing_prompt.j2",
-            previous_summary=summary_event_content,
             events=event_strings,
         )
 
@@ -269,10 +249,7 @@ class LLMSummarizingCondenser(RollingCondenser):
                 "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,
             summary_offset=summary_offset,
         )

openhands/sdk/context/condenser/prompts/summarizing_prompt.j2

@@ -1,5 +1,5 @@
 You are maintaining a context-aware state summary for an interactive agent.
-You will be given a list of events corresponding to actions taken by the agent, and the most recent previous summary if one exists.
+You will be given a list of events corresponding to actions taken by the agent, which will include previous summaries.
 If the events being summarized contain ANY task-tracking, you MUST include a TASK_TRACKING section to maintain continuity.
 When referencing tasks make sure to preserve exact task IDs and statuses.
 
@@ -46,10 +46,6 @@ COMPLETED: 15 haikus written for results [T,H,T,H,T,H,T,T,H,T,H,T,H,T,H]
 PENDING: 5 more haikus needed
 CURRENT_STATE: Last flip: Heads, Haiku count: 15/20
 
-<PREVIOUS SUMMARY>
-{{ previous_summary }}
-</PREVIOUS SUMMARY>
-
 {% for event in events %}
 <EVENT>
 {{ event }}

openhands/sdk/context/view.py

@@ -11,7 +11,6 @@ from pydantic import BaseModel, computed_field
 from openhands.sdk.event import (
     Condensation,
     CondensationRequest,
-    CondensationSummaryEvent,
     LLMConvertibleEvent,
 )
 from openhands.sdk.event.base import Event, EventID
@@ -86,32 +85,6 @@ class View(BaseModel):
     def __len__(self) -> int:
         return len(self.events)
 
-    @property
-    def most_recent_condensation(self) -> Condensation | None:
-        """Return the most recent condensation, or None if no condensations exist."""
-        return self.condensations[-1] if self.condensations else None
-
-    @property
-    def summary_event_index(self) -> int | None:
-        """Return the index of the summary event, or None if no summary exists."""
-        recent_condensation = self.most_recent_condensation
-        if (
-            recent_condensation is not None
-            and recent_condensation.summary is not None
-            and recent_condensation.summary_offset is not None
-        ):
-            return recent_condensation.summary_offset
-        return None
-
-    @property
-    def summary_event(self) -> CondensationSummaryEvent | None:
-        """Return the summary event, or None if no summary exists."""
-        if self.summary_event_index is not None:
-            event = self.events[self.summary_event_index]
-            if isinstance(event, CondensationSummaryEvent):
-                return event
-        return None
-
     @computed_field  # type: ignore[prop-decorator]
     @cached_property
     def manipulation_indices(self) -> list[int]:
@@ -291,46 +264,53 @@ class View(BaseModel):
 
     @staticmethod
     def _enforce_batch_atomicity(
-        events: Sequence[Event],
-        removed_event_ids: set[EventID],
-    ) -> set[EventID]:
-        """Ensure that if any ActionEvent in a batch is removed, all ActionEvents
-        in that batch are removed.
+        view_events: Sequence[LLMConvertibleEvent],
+        all_events: Sequence[Event],
+    ) -> list[LLMConvertibleEvent]:
+        """Ensure that if any ActionEvent in a batch is removed from the view,
+        all ActionEvents in that batch are removed.
 
         This prevents partial batches from being sent to the LLM, which can cause
         API errors when thinking blocks are separated from their tool calls.
 
         Args:
-            events: The original list of events
-            removed_event_ids: Set of event IDs that are being removed
+            view_events: The list of events that are being kept in the view
+            all_events: The complete original list of all events
 
         Returns:
-            Updated set of event IDs that should be removed (including all
-            ActionEvents in batches where any ActionEvent was removed)
+            Filtered list of view events with batch atomicity enforced
+            (removing all ActionEvents from batches where any ActionEvent
+            was already removed)
         """
-        action_batch = ActionBatch.from_events(events)
+        action_batch = ActionBatch.from_events(all_events)
 
         if not action_batch.batches:
-            return removed_event_ids
+            return list(view_events)
+
+        # Get set of event IDs currently in the view
+        view_event_ids = {event.id for event in view_events}
 
-        updated_removed_ids = set(removed_event_ids)
+        # Track which event IDs should be removed due to batch atomicity
+        ids_to_remove: set[EventID] = set()
 
         for llm_response_id, batch_event_ids in action_batch.batches.items():
-            # Check if any ActionEvent in this batch is being removed
-            if any(event_id in removed_event_ids for event_id in batch_event_ids):
+            # Check if any ActionEvent in this batch is missing from view
+            if any(event_id not in view_event_ids for event_id in batch_event_ids):
                 # If so, remove all ActionEvents in this batch
-                updated_removed_ids.update(batch_event_ids)
+                ids_to_remove.update(batch_event_ids)
                 logger.debug(
                     f"Enforcing batch atomicity: removing entire batch "
                     f"with llm_response_id={llm_response_id} "
                     f"({len(batch_event_ids)} events)"
                 )
 
-        return updated_removed_ids
+        # Filter out events that need to be removed
+        return [event for event in view_events if event.id not in ids_to_remove]
 
     @staticmethod
-    def filter_unmatched_tool_calls(
-        events: list[LLMConvertibleEvent],
+    def _filter_unmatched_tool_calls(
+        view_events: Sequence[LLMConvertibleEvent],
+        all_events: Sequence[Event],
     ) -> list[LLMConvertibleEvent]:
         """Filter out unmatched tool call events.
 
@@ -338,49 +318,58 @@ class View(BaseModel):
         but don't have matching pairs. Also enforces batch atomicity - if any
         ActionEvent in a batch is filtered out, all ActionEvents in that batch
         are also filtered out.
+
+        Args:
+            view_events: The list of events to filter
+            all_events: The complete original list of all events
+
+        Returns:
+            Filtered list of events with unmatched tool calls removed
         """
-        action_tool_call_ids = View._get_action_tool_call_ids(events)
-        observation_tool_call_ids = View._get_observation_tool_call_ids(events)
+        action_tool_call_ids = View._get_action_tool_call_ids(view_events)
+        observation_tool_call_ids = View._get_observation_tool_call_ids(view_events)
 
         # Build batch info for batch atomicity enforcement
-        action_batch = ActionBatch.from_events(events)
+        batch = ActionBatch.from_events(all_events)
 
-        # First pass: identify which events would NOT be kept based on matching
-        removed_event_ids: set[EventID] = set()
-        for event in events:
-            if not View._should_keep_event(
+        # First pass: filter out events that don't match based on tool call pairing
+        kept_events = [
+            event
+            for event in view_events
+            if View._should_keep_event(
                 event, action_tool_call_ids, observation_tool_call_ids
-            ):
-                removed_event_ids.add(event.id)
+            )
+        ]
 
         # Second pass: enforce batch atomicity for ActionEvents
         # If any ActionEvent in a batch is removed, all ActionEvents in that
         # batch should also be removed
-        removed_event_ids = View._enforce_batch_atomicity(events, removed_event_ids)
+        kept_events = View._enforce_batch_atomicity(kept_events, all_events)
 
         # Third pass: also remove ObservationEvents whose ActionEvents were removed
         # due to batch atomicity
-        tool_call_ids_to_remove: set[ToolCallID] = set()
-        for action_id in removed_event_ids:
-            if action_id in action_batch.action_id_to_tool_call_id:
-                tool_call_ids_to_remove.add(
-                    action_batch.action_id_to_tool_call_id[action_id]
-                )
-
-        # Filter out removed events
-        result = []
-        for event in events:
-            if event.id in removed_event_ids:
-                continue
-            if isinstance(event, ObservationBaseEvent):
-                if event.tool_call_id in tool_call_ids_to_remove:
-                    continue
-            result.append(event)
+        # Find which action IDs are now missing after batch atomicity enforcement
+        kept_event_ids = {event.id for event in kept_events}
+        tool_call_ids_to_remove: set[ToolCallID] = {
+            tool_call_id
+            for action_id, tool_call_id in batch.action_id_to_tool_call_id.items()
+            if action_id not in kept_event_ids
+        }
+
+        # Filter out ObservationEvents whose ActionEvents were removed
+        result = [
+            event
+            for event in kept_events
+            if not (
+                isinstance(event, ObservationBaseEvent)
+                and event.tool_call_id in tool_call_ids_to_remove
+            )
+        ]
 
         return result
 
     @staticmethod
-    def _get_action_tool_call_ids(events: list[LLMConvertibleEvent]) -> set[ToolCallID]:
+    def _get_action_tool_call_ids(events: Sequence[Event]) -> set[ToolCallID]:
         """Extract tool_call_ids from ActionEvents."""
         tool_call_ids = set()
         for event in events:
@@ -390,7 +379,7 @@ class View(BaseModel):
 
     @staticmethod
     def _get_observation_tool_call_ids(
-        events: list[LLMConvertibleEvent],
+        events: Sequence[Event],
     ) -> set[ToolCallID]:
         """Extract tool_call_ids from ObservationEvents."""
         tool_call_ids = set()
@@ -404,7 +393,7 @@ class View(BaseModel):
 
     @staticmethod
     def _should_keep_event(
-        event: LLMConvertibleEvent,
+        event: Event,
         action_tool_call_ids: set[ToolCallID],
         observation_tool_call_ids: set[ToolCallID],
     ) -> bool:
@@ -434,67 +423,64 @@ class View(BaseModel):
                 return idx
         return threshold
 
+    @staticmethod
+    def unhandled_condensation_request_exists(
+        events: Sequence[Event],
+    ) -> bool:
+        """Check if there is an unhandled condensation request in the list of events.
+
+        An unhandled condensation request is defined as a CondensationRequest event
+        that appears after the most recent Condensation event in the list.
+        """
+        for event in reversed(events):
+            if isinstance(event, Condensation):
+                return False
+            if isinstance(event, CondensationRequest):
+                return True
+        return False
+
     @staticmethod
     def from_events(events: Sequence[Event]) -> View:
         """Create a view from a list of events, respecting the semantics of any
         condensation events.
         """
-        forgotten_event_ids: set[EventID] = set()
+        output: list[LLMConvertibleEvent] = []
         condensations: list[Condensation] = []
+
+        # Generate the LLMConvertibleEvent objects the agent can send to the LLM by
+        # removing un-sendable events and applying condensations in order.
         for event in events:
+            # By the time we come across a Condensation event, the output list should
+            # already reflect the events seen by the agent up to that point. We can
+            # therefore apply the condensation semantics directly to the output list.
             if isinstance(event, Condensation):
                 condensations.append(event)
-                forgotten_event_ids.update(event.forgotten_event_ids)
-                # Make sure we also forget the condensation action itself
-                forgotten_event_ids.add(event.id)
-            if isinstance(event, CondensationRequest):
-                forgotten_event_ids.add(event.id)
-
-        # Enforce batch atomicity: if any event in a multi-action batch is forgotten,
-        # forget all events in that batch to prevent partial batches with thinking
-        # blocks separated from their tool calls
-        forgotten_event_ids = View._enforce_batch_atomicity(events, forgotten_event_ids)
-
-        kept_events = [
-            event
-            for event in events
-            if event.id not in forgotten_event_ids
-            and isinstance(event, LLMConvertibleEvent)
-        ]
+                output = event.apply(output)
 
-        # If we have a summary, insert it at the specified offset.
-        summary: str | None = None
-        summary_offset: int | None = None
+            elif isinstance(event, LLMConvertibleEvent):
+                output.append(event)
 
-        # The relevant summary is always in the last condensation event (i.e., the most
-        # recent one).
-        for event in reversed(events):
-            if isinstance(event, Condensation):
-                if event.summary is not None and event.summary_offset is not None:
-                    summary = event.summary
-                    summary_offset = event.summary_offset
-                    break
-
-        if summary is not None and summary_offset is not None:
-            logger.debug(f"Inserting summary at offset {summary_offset}")
-
-            _new_summary_event = CondensationSummaryEvent(summary=summary)
-            kept_events.insert(summary_offset, _new_summary_event)
-
-        # Check for an unhandled condensation request -- these are events closer to the
-        # end of the list than any condensation action.
-        unhandled_condensation_request = False
-
-        for event in reversed(events):
-            if isinstance(event, Condensation):
-                break
+            # If the event isn't related to condensation and isn't LLMConvertible, it
+            # should not be in the resulting view. Examples include certain internal
+            # events used for state tracking that the LLM does not need to see -- see,
+            # for example, ConversationStateUpdateEvent, PauseEvent, and (relevant here)
+            # CondensationRequest.
+            else:
+                logger.debug(
+                    f"Skipping non-LLMConvertibleEvent of type {type(event)} "
+                    f"in View.from_events"
+                )
 
-            if isinstance(event, CondensationRequest):
-                unhandled_condensation_request = True
-                break
+        # Enforce batch atomicity: if any event in a multi-action batch is removed,
+        # remove all events in that batch to prevent partial batches with thinking
+        # blocks separated from their tool calls
+        output = View._enforce_batch_atomicity(output, events)
+        output = View._filter_unmatched_tool_calls(output, events)
 
         return View(
-            events=View.filter_unmatched_tool_calls(kept_events),
-            unhandled_condensation_request=unhandled_condensation_request,
+            events=output,
+            unhandled_condensation_request=View.unhandled_condensation_request_exists(
+                events
+            ),
             condensations=condensations,
         )

openhands/sdk/conversation/__init__.py

@@ -2,6 +2,7 @@ from openhands.sdk.conversation.base import BaseConversation
 from openhands.sdk.conversation.conversation import Conversation
 from openhands.sdk.conversation.event_store import EventLog
 from openhands.sdk.conversation.events_list_base import EventsListBase
+from openhands.sdk.conversation.exceptions import WebSocketConnectionError
 from openhands.sdk.conversation.impl.local_conversation import LocalConversation
 from openhands.sdk.conversation.impl.remote_conversation import RemoteConversation
 from openhands.sdk.conversation.response_utils import get_agent_final_response
@@ -37,4 +38,5 @@ __all__ = [
     "RemoteConversation",
     "EventsListBase",
     "get_agent_final_response",
+    "WebSocketConnectionError",
 ]