openhands-sdk 1.9.1__py3-none-any.whl → 1.11.0__py3-none-any.whl

openhands/sdk/agent/agent.py

@@ -67,6 +67,10 @@ from openhands.sdk.tool.builtins import (
 logger = get_logger(__name__)
 maybe_init_laminar()
 
+# Maximum number of events to scan during init_state defensive checks.
+# SystemPromptEvent must appear within this prefix (at index 0 or 1).
+INIT_STATE_PREFIX_SCAN_WINDOW = 3
+
 
 class Agent(AgentBase):
     """Main agent implementation for OpenHands.
@@ -102,24 +106,94 @@ class Agent(AgentBase):
         state: ConversationState,
         on_event: ConversationCallbackType,
     ) -> None:
+        """Initialize conversation state.
+
+        Invariants enforced by this method:
+        - If a SystemPromptEvent is already present, it must be within the first 3
+          events (index 0 or 1 in practice; index 2 is included in the scan window
+          to detect a user message appearing before the system prompt).
+        - A user MessageEvent should not appear before the SystemPromptEvent.
+
+        These invariants keep event ordering predictable for downstream components
+        (condenser, UI, etc.) and also prevent accidentally materializing the full
+        event history during initialization.
+        """
         super().init_state(state, on_event=on_event)
-        # 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
+        #
+        # NOTE: len() is O(1) for EventLog (file-backed implementation).
+        event_count = len(state.events)
+
+        # NOTE: state.events is intentionally an EventsListBase (Sequence-like), not
+        # a plain list. Avoid materializing the full history via list(state.events)
+        # here (conversations can reach 30k+ events).
+        #
+        # Invariant: when init_state is called, SystemPromptEvent (if present) must be
+        # at index 0 or 1.
+        #
+        # Rationale:
+        # - Local conversations start empty and init_state is responsible for adding
+        #   the SystemPromptEvent as the first event.
+        # - Remote conversations may receive an initial ConversationStateUpdateEvent
+        #   from the agent-server immediately after subscription. In a typical remote
+        #   session prefix you may see:
+        #     [ConversationStateUpdateEvent, SystemPromptEvent, MessageEvent, ...]
+        #
+        # We intentionally only inspect the first few events (cheap for both local and
+        # remote) to enforce this invariant.
+        prefix_events = state.events[:INIT_STATE_PREFIX_SCAN_WINDOW]
+
+        has_system_prompt = any(isinstance(e, SystemPromptEvent) for e in prefix_events)
+        has_user_message = any(
+            isinstance(e, MessageEvent) and e.source == "user" for e in prefix_events
+        )
+        # Log state for debugging initialization order issues
+        logger.debug(
+            f"init_state called: conversation_id={state.id}, "
+            f"event_count={event_count}, "
+            f"has_system_prompt={has_system_prompt}, "
+            f"has_user_message={has_user_message}"
+        )
+
+        if has_system_prompt:
+            # Restoring/resuming conversations is normal: a system prompt already
+            # present means this conversation was initialized previously.
+            logger.debug(
+                "init_state: SystemPromptEvent already present; skipping init. "
+                f"conversation_id={state.id}, event_count={event_count}."
             )
-            on_event(event)
+            return
+
+        # Assert: A user message should never appear before the system prompt.
+        #
+        # NOTE: This is a best-effort check based on the first few events only.
+        # Remote conversations can include a ConversationStateUpdateEvent near the
+        # start, so we scan a small prefix window.
+        if has_user_message:
+            event_types = [type(e).__name__ for e in prefix_events]
+            logger.error(
+                f"init_state: User message found in prefix before SystemPromptEvent! "
+                f"conversation_id={state.id}, prefix_events={event_types}"
+            )
+            raise AssertionError(
+                "Unexpected state: user message exists before SystemPromptEvent. "
+                f"conversation_id={state.id}, event_count={event_count}, "
+                f"prefix_event_types={event_types}."
+            )
+
+        # 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):
@@ -516,5 +503,5 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             RuntimeError: If the agent has not been initialized.
         """
         if not self._initialized:
-            raise RuntimeError("Agent not initialized; call initialize() before use")
+            raise RuntimeError("Agent not initialized; call _initialize() before use")
         return self._tools

openhands/sdk/context/condenser/base.py

@@ -103,6 +103,23 @@ class RollingCondenser(PipelinableCondenserBase, ABC):
     `View` to be passed to the LLM.
     """
 
+    def hard_context_reset(
+        self,
+        view: View,  # noqa: ARG002
+        agent_llm: LLM | None = None,  # noqa: ARG002
+    ) -> Condensation | None:
+        """Perform a hard context reset, if supported by the condenser.
+
+        By default, rolling condensers do not support hard context resets. Override this
+        method to implement hard context reset logic by returning a `Condensation`
+        object.
+
+        This method is invoked when:
+        - A HARD condensation requirement is triggered (e.g., by user request)
+        - But the condenser raises a NoCondensationAvailableException error
+        """
+        return None
+
     @abstractmethod
     def condensation_requirement(
         self, view: View, agent_llm: LLM | None = None
@@ -142,9 +159,25 @@ class RollingCondenser(PipelinableCondenserBase, ABC):
                     # we do so immediately.
                     return view
 
-                # Otherwise re-raise the exception.
-                else:
-                    raise e
+                elif request == CondensationRequirement.HARD:
+                    # The agent has found itself in a situation where it cannot proceed
+                    # without condensation, but the condenser cannot provide one. We'll
+                    # try to recover from this situation by performing a hard context
+                    # reset, if supported by the condenser.
+                    try:
+                        hard_reset_condensation = self.hard_context_reset(
+                            view, agent_llm=agent_llm
+                        )
+                        if hard_reset_condensation is not None:
+                            return hard_reset_condensation
+
+                    # And if something goes wrong with the hard reset make sure we keep
+                    # both errors in the stack
+                    except Exception as hard_reset_exception:
+                        raise hard_reset_exception from e
+
+                # In all other situations re-raise the exception.
+                raise e
 
         # Otherwise we're safe to just return the view.
         else:

openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -17,9 +17,13 @@ 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.logger import get_logger
 from openhands.sdk.observability.laminar import observe
+from openhands.sdk.utils import maybe_truncate
+
+
+logger = get_logger(__name__)
 
 
 class Reason(Enum):
@@ -48,6 +52,14 @@ class LLMSummarizingCondenser(RollingCondenser):
     `keep_first` events in the conversation will never be condensed or summarized.
     """
 
+    hard_context_reset_max_retries: int = Field(default=5, gt=0)
+    """Number of attempts to perform hard context reset before raising an error."""
+
+    hard_context_reset_context_scaling: float = Field(default=0.8, gt=0.0, lt=1.0)
+    """When performing hard context reset, if the summarization fails, reduce the max
+    size of each event string by this factor and retry.
+    """
+
     @model_validator(mode="after")
     def validate_keep_first_vs_max_size(self):
         events_from_tail = self.max_size // 2 - self.keep_first - 1
@@ -117,35 +129,20 @@ 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,
+        max_event_str_length: int | None = None,
     ) -> 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.
+            max_event_str_length: Optional maximum length for each event string. If
+                provided, event strings longer than this will be truncated.
 
         Returns:
             Condensation: The generated condensation object.
@@ -156,12 +153,14 @@ class LLMSummarizingCondenser(RollingCondenser):
         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]
+        event_strings = [
+            maybe_truncate(str(forgotten_event), truncate_after=max_event_str_length)
+            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,
         )
 
@@ -252,6 +251,51 @@ class LLMSummarizingCondenser(RollingCondenser):
         # Summary offset is the same as forgetting_start
         return forgotten_events, forgetting_start
 
+    @observe(ignore_inputs=["view", "agent_llm"])
+    def hard_context_reset(
+        self,
+        view: View,
+        agent_llm: LLM | None = None,  # noqa: ARG002
+    ) -> Condensation | None:
+        """Perform a hard context reset by summarizing all events in the view.
+
+        Depending on how the hard context reset is triggered, this may fail (e.g., if
+        the view is too large for the summarizing LLM to handle). In that case, we keep
+        trimming down the contents until a summary can be generated.
+        """
+        max_event_str_length: int | None = None
+        attempts_remaining: int = self.hard_context_reset_max_retries
+
+        while attempts_remaining > 0:
+            try:
+                return self._generate_condensation(
+                    forgotten_events=view.events,
+                    summary_offset=0,
+                    max_event_str_length=max_event_str_length,
+                )
+            except Exception as e:
+                # If we haven't set a max_event_str_length yet, set it as the largest
+                # event string length.
+                if max_event_str_length is None:
+                    max_event_str_length = max(len(str(event)) for event in view.events)
+
+                # Since the summarization failed, reduce the max_event_str_length by 20%
+                assert max_event_str_length is not None
+                max_event_str_length = int(
+                    max_event_str_length * self.hard_context_reset_context_scaling
+                )
+
+                # Log the exception so we can track these failures
+                logger.warning(
+                    f"Hard context reset summarization failed with exception: {e}. "
+                    f"Reducing max event size to {max_event_str_length} and retrying."
+                )
+
+            attempts_remaining -= 1
+
+        logger.error("Hard context reset summarization failed after multiple attempts.")
+        return None
+
     @observe(ignore_inputs=["view", "agent_llm"])
     def get_condensation(
         self, view: View, agent_llm: LLM | None = None
@@ -269,10 +313,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/prompts/templates/system_message_suffix.j2

@@ -27,9 +27,10 @@ You can also directly look up a skill's full content by reading its location pat
 <CUSTOM_SECRETS>
 ### Credential Access
 * Automatic secret injection: When you reference a registered secret key in your bash command, the secret value will be automatically exported as an environment variable before your command executes.
-* How to use secrets: Simply reference the secret key in your command (e.g., `echo ${GITHUB_TOKEN:0:8}` or `curl -H "Authorization: Bearer $API_KEY" https://api.example.com`). The system will detect the key name in your command text and export it as environment variable before it executes your command.
+* How to use secrets: Simply reference the secret key in your command (e.g., `curl -H "Authorization: Bearer $API_KEY" https://api.example.com`). The system will detect the key name in your command text and export it as environment variable before it executes your command.
 * Secret detection: The system performs case-insensitive matching to find secret keys in your command text. If a registered secret key appears anywhere in your command, its value will be made available as an environment variable.
 * Security: Secret values are automatically masked in command output to prevent accidental exposure. You will see `<secret-hidden>` instead of the actual secret value in the output.
+* Avoid exposing raw secrets: Never echo or print the full value of secrets (e.g., avoid `echo $SECRET`). The conversation history may be logged or shared, and exposing raw secret values could compromise security. Instead, use secrets directly in commands where they serve their intended purpose (e.g., in curl headers or git URLs).
 * Refreshing expired secrets: Some secrets (like GITHUB_TOKEN) may be updated periodically or expire over time. If a secret stops working (e.g., authentication failures), try using it again in a new command - the system should automatically use the refreshed value. For example, if GITHUB_TOKEN was used in a git remote URL and later expired, you can update the remote URL with the current token: `git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git` to pick up the refreshed token value.
 * If it still fails, report it to the user.
 

openhands/sdk/context/skills/skill.py

@@ -27,15 +27,10 @@ from openhands.sdk.context.skills.utils import (
     validate_skill_name,
 )
 from openhands.sdk.logger import get_logger
-from openhands.sdk.utils import maybe_truncate
 
 
 logger = get_logger(__name__)
 
-# Maximum characters for third-party skill files (e.g., AGENTS.md, CLAUDE.md, GEMINI.md)
-# These files are always active, so we want to keep them reasonably sized
-THIRD_PARTY_SKILL_MAX_CHARS = 10_000
-
 
 class SkillInfo(BaseModel):
     """Lightweight representation of a skill's essential information.
@@ -485,32 +480,14 @@ class Skill(BaseModel):
         """Handle third-party skill files (e.g., .cursorrules, AGENTS.md).
 
         Creates a Skill with None trigger (always active) if the file type
-        is recognized. Truncates content if it exceeds the limit.
+        is recognized.
         """
         skill_name = cls.PATH_TO_THIRD_PARTY_SKILL_NAME.get(path.name.lower())
 
         if skill_name is not None:
-            truncated_content = maybe_truncate(
-                file_content,
-                truncate_after=THIRD_PARTY_SKILL_MAX_CHARS,
-                truncate_notice=(
-                    f"\n\n<TRUNCATED><NOTE>The file {path} exceeded the "
-                    f"maximum length ({THIRD_PARTY_SKILL_MAX_CHARS} "
-                    f"characters) and has been truncated. Only the "
-                    f"beginning and end are shown. You can read the full "
-                    f"file if needed.</NOTE>\n\n"
-                ),
-            )
-
-            if len(file_content) > THIRD_PARTY_SKILL_MAX_CHARS:
-                logger.warning(
-                    f"Third-party skill file {path} ({len(file_content)} chars) "
-                    f"exceeded limit ({THIRD_PARTY_SKILL_MAX_CHARS} chars), truncating"
-                )
-
             return Skill(
                 name=skill_name,
-                content=truncated_content,
+                content=file_content,
                 source=str(path),
                 trigger=None,
             )