openhands-sdk 1.10.0__py3-none-any.whl → 1.11.1__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,53 +106,82 @@ 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
 
         # 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)
+        #
+        # 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 events
+            isinstance(e, MessageEvent) and e.source == "user" for e in prefix_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"event_count={event_count}, "
             f"has_system_prompt={has_system_prompt}, "
-            f"has_user_message={has_user_message}, "
-            f"has_any_llm_event={has_any_llm_event}"
+            f"has_user_message={has_user_message}"
         )
 
         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."
+            # 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}."
             )
             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
+        # 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 events]
+            event_types = [type(e).__name__ for e in prefix_events]
             logger.error(
-                f"init_state: User message exists without SystemPromptEvent! "
-                f"conversation_id={state.id}, events={event_types}"
+                f"init_state: User message found in prefix before SystemPromptEvent! "
+                f"conversation_id={state.id}, prefix_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."
+            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

openhands/sdk/agent/base.py

@@ -503,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

@@ -18,7 +18,12 @@ from openhands.sdk.context.view import View
 from openhands.sdk.event.base import LLMConvertibleEvent
 from openhands.sdk.event.condenser import Condensation
 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):
@@ -47,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
@@ -120,6 +133,7 @@ class LLMSummarizingCondenser(RollingCondenser):
         self,
         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.
@@ -127,6 +141,8 @@ class LLMSummarizingCondenser(RollingCondenser):
         Args:
             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.
@@ -137,7 +153,10 @@ 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"),
@@ -232,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

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,
             )
@@ -732,10 +709,16 @@ def load_user_skills() -> list[Skill]:
 def load_project_skills(work_dir: str | Path) -> list[Skill]:
     """Load skills from project-specific directories.
 
-    Searches for skills in {work_dir}/.openhands/skills/ and
-    {work_dir}/.openhands/microagents/ (legacy). Skills from both
-    directories are merged, with skills/ taking precedence for
-    duplicate names.
+    Searches for skills in {work_dir}/.agents/skills/,
+    {work_dir}/.openhands/skills/, and {work_dir}/.openhands/microagents/
+    (legacy). Skills are merged in priority order, with earlier directories
+    taking precedence for duplicate names.
+
+    Use .agents/skills for new skills. .openhands/skills is the legacy
+    OpenHands location, and .openhands/microagents is deprecated.
+
+    Example: If "my-skill" exists in both .agents/skills/ and
+    .openhands/skills/, the version from .agents/skills/ is used.
 
     Also loads third-party skill files (AGENTS.md, .cursorrules, etc.)
     directly from the work directory.
@@ -768,8 +751,10 @@ def load_project_skills(work_dir: str | Path) -> list[Skill]:
         except (SkillError, OSError) as e:
             logger.warning(f"Failed to load third-party skill from {path}: {e}")
 
-    # Load project-specific skills from .openhands/skills and legacy microagents
+    # Load project-specific skills from .agents/skills, .openhands/skills,
+    # and legacy microagents (priority order; first wins for duplicates)
     project_skills_dirs = [
+        work_dir / ".agents" / "skills",
         work_dir / ".openhands" / "skills",
         work_dir / ".openhands" / "microagents",  # Legacy support
     ]

openhands/sdk/conversation/base.py

@@ -23,6 +23,7 @@ from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
     NeverConfirm,
 )
+from openhands.sdk.tool.schema import Action, Observation
 from openhands.sdk.workspace.base import BaseWorkspace
 
 
@@ -267,6 +268,36 @@ class BaseConversation(ABC):
         """
         ...
 
+    @abstractmethod
+    def execute_tool(self, tool_name: str, action: Action) -> Observation:
+        """Execute a tool directly without going through the agent loop.
+
+        This method allows executing tools before or outside of the normal
+        conversation.run() flow. It handles agent initialization automatically,
+        so tools can be executed before the first run() call.
+
+        Note: This method bypasses the agent loop, including confirmation
+        policies and security analyzer checks. Callers are responsible for
+        applying any safeguards before executing potentially destructive tools.
+
+        This is useful for:
+        - Pre-run setup operations (e.g., indexing repositories)
+        - Manual tool execution for environment setup
+        - Testing tool behavior outside the agent loop
+
+        Args:
+            tool_name: The name of the tool to execute (e.g., "sleeptime_compute")
+            action: The action to pass to the tool executor
+
+        Returns:
+            The observation returned by the tool execution
+
+        Raises:
+            KeyError: If the tool is not found in the agent's tools
+            NotImplementedError: If the tool has no executor
+        """
+        ...
+
     @staticmethod
     def compose_callbacks(callbacks: Iterable[CallbackType]) -> CallbackType:
         """Compose multiple callbacks into a single callback function.

openhands/sdk/conversation/conversation.py

@@ -74,6 +74,7 @@ class Conversation:
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+        delete_on_close: bool = False,
     ) -> "LocalConversation": ...
 
     @overload
@@ -96,6 +97,7 @@ class Conversation:
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+        delete_on_close: bool = False,
     ) -> "RemoteConversation": ...
 
     def __new__(
@@ -118,6 +120,7 @@ class Conversation:
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+        delete_on_close: bool = False,
     ) -> BaseConversation:
         from openhands.sdk.conversation.impl.local_conversation import LocalConversation
         from openhands.sdk.conversation.impl.remote_conversation import (
@@ -143,6 +146,7 @@ class Conversation:
                 visualizer=visualizer,
                 workspace=workspace,
                 secrets=secrets,
+                delete_on_close=delete_on_close,
             )
 
         return LocalConversation(
@@ -159,4 +163,5 @@ class Conversation:
             workspace=workspace,
             persistence_dir=persistence_dir,
             secrets=secrets,
+            delete_on_close=delete_on_close,
         )

openhands/sdk/conversation/impl/local_conversation.py

@@ -46,6 +46,7 @@ from openhands.sdk.security.analyzer import SecurityAnalyzerBase
 from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
 )
+from openhands.sdk.tool.schema import Action, Observation
 from openhands.sdk.utils.cipher import Cipher
 from openhands.sdk.workspace import LocalWorkspace
 
@@ -65,6 +66,7 @@ class LocalConversation(BaseConversation):
     llm_registry: LLMRegistry
     _cleanup_initiated: bool
     _hook_processor: HookEventProcessor | None
+    delete_on_close: bool = True
     # Plugin lazy loading state
     _plugin_specs: list[PluginSource] | None
     _resolved_plugins: list[ResolvedPluginSource] | None
@@ -90,6 +92,7 @@ class LocalConversation(BaseConversation):
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: Mapping[str, SecretValue] | None = None,
+        delete_on_close: bool = True,
         cipher: Cipher | None = None,
         **_: object,
     ):
@@ -242,6 +245,7 @@ class LocalConversation(BaseConversation):
 
         atexit.register(self.close)
         self._start_observability_span(str(desired_id))
+        self.delete_on_close = delete_on_close
 
     @property
     def id(self) -> ConversationID:
@@ -708,20 +712,23 @@ class LocalConversation(BaseConversation):
         except AttributeError:
             # Object may be partially constructed; span fields may be missing.
             pass
-        try:
-            tools_map = self.agent.tools_map
-        except (AttributeError, RuntimeError):
-            # Agent not initialized or partially constructed
-            return
-        for tool in tools_map.values():
+        if self.delete_on_close:
             try:
-                executable_tool = tool.as_executable()
-                executable_tool.executor.close()
-            except NotImplementedError:
-                # Tool has no executor, skip it without erroring
-                continue
-            except Exception as e:
-                logger.warning(f"Error closing executor for tool '{tool.name}': {e}")
+                tools_map = self.agent.tools_map
+            except (AttributeError, RuntimeError):
+                # Agent not initialized or partially constructed
+                return
+            for tool in tools_map.values():
+                try:
+                    executable_tool = tool.as_executable()
+                    executable_tool.executor.close()
+                except NotImplementedError:
+                    # Tool has no executor, skip it without erroring
+                    continue
+                except Exception as e:
+                    logger.warning(
+                        f"Error closing executor for tool '{tool.name}': {e}"
+                    )
 
     def ask_agent(self, question: str) -> str:
         """Ask the agent a simple, stateless question and get a direct LLM response.
@@ -861,6 +868,49 @@ class LocalConversation(BaseConversation):
 
         logger.info("Condensation request processed")
 
+    def execute_tool(self, tool_name: str, action: Action) -> Observation:
+        """Execute a tool directly without going through the agent loop.
+
+        This method allows executing tools before or outside of the normal
+        conversation.run() flow. It handles agent initialization automatically,
+        so tools can be executed before the first run() call.
+
+        Note: This method bypasses the agent loop, including confirmation
+        policies and security analyzer checks. Callers are responsible for
+        applying any safeguards before executing potentially destructive tools.
+
+        This is useful for:
+        - Pre-run setup operations (e.g., indexing repositories)
+        - Manual tool execution for environment setup
+        - Testing tool behavior outside the agent loop
+
+        Args:
+            tool_name: The name of the tool to execute (e.g., "sleeptime_compute")
+            action: The action to pass to the tool executor
+
+        Returns:
+            The observation returned by the tool execution
+
+        Raises:
+            KeyError: If the tool is not found in the agent's tools
+            NotImplementedError: If the tool has no executor
+        """
+        # Ensure agent is initialized (loads plugins and initializes tools)
+        self._ensure_agent_ready()
+
+        # Get the tool from the agent's tools_map
+        tool = self.agent.tools_map.get(tool_name)
+        if tool is None:
+            available_tools = list(self.agent.tools_map.keys())
+            raise KeyError(
+                f"Tool '{tool_name}' not found. Available tools: {available_tools}"
+            )
+
+        # Execute the tool
+        if not tool.executor:
+            raise NotImplementedError(f"Tool '{tool_name}' has no executor")
+        return tool(action, self)
+
     def __del__(self) -> None:
         """Ensure cleanup happens when conversation is destroyed."""
         try: