openhands-sdk 1.7.3__py3-none-any.whl → 1.8.0__py3-none-any.whl

openhands/sdk/conversation/impl/remote_conversation.py

@@ -489,7 +489,23 @@ class RemoteConversation(BaseConversation):
         self._hook_processor = None
         self._cleanup_initiated = False
 
-        if conversation_id is None:
+        should_create = conversation_id is None
+        if conversation_id is not None:
+            # Try to attach to existing conversation
+            resp = _send_request(
+                self._client,
+                "GET",
+                f"/api/conversations/{conversation_id}",
+                acceptable_status_codes={404},
+            )
+            if resp.status_code == 404:
+                # Conversation doesn't exist, we'll create it
+                should_create = True
+            else:
+                # Conversation exists, use the provided ID
+                self._id = conversation_id
+
+        if should_create:
             # Import here to avoid circular imports
             from openhands.sdk.tool.registry import get_tool_module_qualnames
 
@@ -518,6 +534,9 @@ class RemoteConversation(BaseConversation):
                 else:
                     threshold_config = stuck_detection_thresholds
                 payload["stuck_detection_thresholds"] = threshold_config.model_dump()
+            # Include conversation_id if provided (for creating with specific ID)
+            if conversation_id is not None:
+                payload["conversation_id"] = str(conversation_id)
             resp = _send_request(
                 self._client, "POST", "/api/conversations", json=payload
             )
@@ -529,11 +548,6 @@ class RemoteConversation(BaseConversation):
                     "Invalid response from server: missing conversation id"
                 )
             self._id = uuid.UUID(cid)
-        else:
-            # Attach to existing
-            self._id = conversation_id
-            # Validate it exists
-            _send_request(self._client, "GET", f"/api/conversations/{self._id}")
 
         # Initialize the remote state
         self._state = RemoteState(self._client, str(self._id))
@@ -719,12 +733,8 @@ class RemoteConversation(BaseConversation):
 
         if resp.status_code == 409:
             logger.info("Conversation is already running; skipping run trigger")
-            if blocking:
-                # Still wait for the existing run to complete
-                self._wait_for_run_completion(poll_interval, timeout)
-            return
-
-        logger.info(f"run() triggered successfully: {resp}")
+        else:
+            logger.info(f"run() triggered successfully: {resp}")
 
         if blocking:
             self._wait_for_run_completion(poll_interval, timeout)
@@ -741,7 +751,9 @@ class RemoteConversation(BaseConversation):
             timeout: Maximum time in seconds to wait.
 
         Raises:
-            ConversationRunError: If the wait times out.
+            ConversationRunError: If the run fails, the conversation disappears,
+                or the wait times out. Transient network errors, 429s, and 5xx
+                responses are retried until timeout.
         """
         start_time = time.monotonic()
 
@@ -757,56 +769,88 @@ class RemoteConversation(BaseConversation):
                 )
 
             try:
-                resp = _send_request(
-                    self._client,
-                    "GET",
-                    f"/api/conversations/{self._id}",
-                    timeout=30,
-                )
-                info = resp.json()
-                status = info.get("execution_status")
-
-                if status != ConversationExecutionStatus.RUNNING.value:
-                    if status == ConversationExecutionStatus.ERROR.value:
-                        detail = self._get_last_error_detail()
-                        raise ConversationRunError(
-                            self._id,
-                            RuntimeError(
-                                detail or "Remote conversation ended with error"
-                            ),
-                        )
-                    if status == ConversationExecutionStatus.STUCK.value:
-                        raise ConversationRunError(
-                            self._id,
-                            RuntimeError("Remote conversation got stuck"),
-                        )
+                status = self._poll_status_once()
+            except Exception as exc:
+                self._handle_poll_exception(exc)
+            else:
+                if self._handle_conversation_status(status):
                     logger.info(
-                        f"Run completed with status: {status} (elapsed: {elapsed:.1f}s)"
+                        "Run completed with status: %s (elapsed: %.1fs)",
+                        status,
+                        elapsed,
                     )
                     return
 
-            except Exception as e:
-                # Log but continue polling - transient network errors shouldn't
-                # stop us from waiting for the run to complete
-                logger.warning(f"Error polling status (will retry): {e}")
-
             time.sleep(poll_interval)
 
+    def _poll_status_once(self) -> str | None:
+        """Fetch the current execution status from the remote conversation."""
+        resp = _send_request(
+            self._client,
+            "GET",
+            f"/api/conversations/{self._id}",
+            timeout=30,
+        )
+        info = resp.json()
+        return info.get("execution_status")
+
+    def _handle_conversation_status(self, status: str | None) -> bool:
+        """Handle non-running statuses; return True if the run is complete."""
+        if status == ConversationExecutionStatus.RUNNING.value:
+            return False
+        if status == ConversationExecutionStatus.ERROR.value:
+            detail = self._get_last_error_detail()
+            raise ConversationRunError(
+                self._id,
+                RuntimeError(detail or "Remote conversation ended with error"),
+            )
+        if status == ConversationExecutionStatus.STUCK.value:
+            raise ConversationRunError(
+                self._id,
+                RuntimeError("Remote conversation got stuck"),
+            )
+        return True
+
+    def _handle_poll_exception(self, exc: Exception) -> None:
+        """Classify polling exceptions into retryable vs terminal failures."""
+        if isinstance(exc, httpx.HTTPStatusError):
+            status_code = exc.response.status_code
+            reason = exc.response.reason_phrase
+            if status_code == 404:
+                raise ConversationRunError(
+                    self._id,
+                    RuntimeError(
+                        "Remote conversation not found (404). "
+                        "The runtime may have been deleted."
+                    ),
+                ) from exc
+            if 400 <= status_code < 500 and status_code != 429:
+                raise ConversationRunError(
+                    self._id,
+                    RuntimeError(f"Polling failed with HTTP {status_code} {reason}"),
+                ) from exc
+            logger.warning(
+                "Error polling status (will retry): HTTP %d %s",
+                status_code,
+                reason,
+            )
+            return
+        if isinstance(exc, httpx.RequestError):
+            logger.warning(f"Error polling status (will retry): {exc}")
+            return
+        raise ConversationRunError(self._id, exc) from exc
+
     def _get_last_error_detail(self) -> str | None:
         """Return the most recent ConversationErrorEvent detail, if available."""
-        try:
-            events = self._state.events
-            for idx in range(len(events) - 1, -1, -1):
-                event = events[idx]
-                if isinstance(event, ConversationErrorEvent):
-                    detail = event.detail.strip()
-                    code = event.code.strip()
-                    if detail and code:
-                        return f"{code}: {detail}"
-                    return detail or code or None
-        except Exception as exc:
-            logger.debug("Failed to read conversation error detail: %s", exc)
-        return None
+        events = self._state.events
+        for idx in range(len(events) - 1, -1, -1):
+            event = events[idx]
+            if isinstance(event, ConversationErrorEvent):
+                detail = event.detail.strip()
+                code = event.code.strip()
+                if detail and code:
+                    return f"{code}: {detail}"
+                return detail or code or None
 
     def set_confirmation_policy(self, policy: ConfirmationPolicyBase) -> None:
         payload = {"policy": policy.model_dump()}

openhands/sdk/conversation/state.py

@@ -5,7 +5,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, Self
 
-from pydantic import AliasChoices, Field, PrivateAttr
+from pydantic import Field, PrivateAttr, model_validator
 
 from openhands.sdk.agent.base import AgentBase
 from openhands.sdk.conversation.conversation_stats import ConversationStats
@@ -60,7 +60,10 @@ class ConversationState(OpenHandsModel):
     )
     workspace: BaseWorkspace = Field(
         ...,
-        description="Working directory for agent operations and tool execution",
+        description=(
+            "Workspace used by the agent to execute commands and read/write files. "
+            "Not the process working directory."
+        ),
     )
     persistence_dir: str | None = Field(
         default="workspace/conversations",
@@ -116,8 +119,6 @@ class ConversationState(OpenHandsModel):
     secret_registry: SecretRegistry = Field(
         default_factory=SecretRegistry,
         description="Registry for handling secrets and sensitive data",
-        validation_alias=AliasChoices("secret_registry", "secrets_manager"),
-        serialization_alias="secret_registry",
     )
 
     # ===== Private attrs (NOT Fields) =====
@@ -133,7 +134,14 @@ class ConversationState(OpenHandsModel):
         default_factory=FIFOLock
     )  # FIFO lock for thread safety
 
-    # ===== Public "events" facade (Sequence[Event]) =====
+    @model_validator(mode="before")
+    @classmethod
+    def _handle_secrets_manager_alias(cls, data: Any) -> Any:
+        """Handle legacy 'secrets_manager' field name for backward compatibility."""
+        if isinstance(data, dict) and "secrets_manager" in data:
+            data["secret_registry"] = data.pop("secrets_manager")
+        return data
+
     @property
     def events(self) -> EventLog:
         return self._events
@@ -173,10 +181,35 @@ class ConversationState(OpenHandsModel):
         max_iterations: int = 500,
         stuck_detection: bool = True,
     ) -> "ConversationState":
-        """
-        If base_state.json exists: resume (attach EventLog,
-            reconcile agent, enforce id).
-        Else: create fresh (agent required), persist base, and return.
+        """Create a new conversation state or resume from persistence.
+
+        This factory method handles both new conversation creation and resumption
+        from persisted state.
+
+        **New conversation:**
+        The provided Agent is used directly. Pydantic validation happens via the
+        cls() constructor.
+
+        **Restored conversation:**
+        The provided Agent is validated against the persisted agent using
+        agent.load(). Tools must match (they may have been used in conversation
+        history), but all other configuration can be freely changed: LLM,
+        agent_context, condenser, system prompts, etc.
+
+        Args:
+            id: Unique conversation identifier
+            agent: The Agent to use (tools must match persisted on restore)
+            workspace: Working directory for agent operations
+            persistence_dir: Directory for persisting state and events
+            max_iterations: Maximum iterations per run
+            stuck_detection: Whether to enable stuck detection
+
+        Returns:
+            ConversationState ready for use
+
+        Raises:
+            ValueError: If conversation ID or tools mismatch on restore
+            ValidationError: If agent or other fields fail Pydantic validation
         """
         file_store = (
             LocalFileStore(persistence_dir, cache_limit_size=max_iterations)
@@ -193,23 +226,28 @@ class ConversationState(OpenHandsModel):
         if base_text:
             state = cls.model_validate(json.loads(base_text))
 
-            # Enforce conversation id match
+            # Restore the conversation with the same id
             if state.id != id:
                 raise ValueError(
                     f"Conversation ID mismatch: provided {id}, "
                     f"but persisted state has {state.id}"
                 )
 
-            # Reconcile agent config with deserialized one
-            resolved = agent.resolve_diff_from_deserialized(state.agent)
-
-            # Attach runtime handles and commit reconciled agent (may autosave)
+            # Attach event log early so we can read history for tool verification
             state._fs = file_store
             state._events = EventLog(file_store, dir_path=EVENTS_DIR)
+
+            # Verify compatibility (agent class + tools)
+            agent.verify(state.agent, events=state._events)
+
+            # Commit runtime-provided values (may autosave)
             state._autosave_enabled = True
-            state.agent = resolved
+            state.agent = agent
+            state.workspace = workspace
+            state.max_iterations = max_iterations
 
-            state.stats = ConversationStats()
+            # Note: stats are already deserialized from base_state.json above.
+            # Do NOT reset stats here - this would lose accumulated metrics.
 
             logger.info(
                 f"Resumed conversation {state.id} from persistent storage.\n"
@@ -232,8 +270,6 @@ class ConversationState(OpenHandsModel):
             max_iterations=max_iterations,
             stuck_detection=stuck_detection,
         )
-        # Record existing analyzer configuration in state
-        state.security_analyzer = state.security_analyzer
         state._fs = file_store
         state._events = EventLog(file_store, dir_path=EVENTS_DIR)
         state.stats = ConversationStats()

openhands/sdk/event/llm_convertible/action.py

@@ -65,6 +65,20 @@ class ActionEvent(LLMConvertibleEvent):
         description="The LLM's assessment of the safety risk of this action.",
     )
 
+    summary: str | None = Field(
+        default=None,
+        description=(
+            "A concise summary (approximately 10 words) of what this action does, "
+            "provided by the LLM for explainability and debugging. "
+            "Examples of good summaries: "
+            "'editing configuration file for deployment settings' | "
+            "'searching codebase for authentication function definitions' | "
+            "'installing required dependencies from package manifest' | "
+            "'running tests to verify bug fix' | "
+            "'viewing directory structure to locate source files'"
+        ),
+    )
+
     @property
     def visualize(self) -> Text:
         """Return Rich Text representation of this action event."""
@@ -73,6 +87,12 @@ class ActionEvent(LLMConvertibleEvent):
         if self.security_risk != risk.SecurityRisk.UNKNOWN:
             content.append(self.security_risk.visualize)
 
+        # Display summary if available
+        if self.summary:
+            content.append("Summary: ", style="bold cyan")
+            content.append(self.summary)
+            content.append("\n\n")
+
         # Display reasoning content first if available
         if self.reasoning_content:
             content.append("Reasoning:\n", style="bold")

openhands/sdk/git/utils.py

@@ -73,6 +73,28 @@ def run_git_command(args: list[str], cwd: str | Path) -> str:
         ) from e
 
 
+def _repo_has_commits(repo_dir: str | Path) -> bool:
+    """Check if a git repository has any commits.
+
+    Uses 'git rev-list --count --all' which returns "0" for empty repos
+    without failing, avoiding ERROR logs for expected conditions.
+
+    Args:
+        repo_dir: Path to the git repository
+
+    Returns:
+        True if the repository has at least one commit, False otherwise
+    """
+    try:
+        count = run_git_command(
+            ["git", "--no-pager", "rev-list", "--count", "--all"], repo_dir
+        )
+        return count.strip() != "0"
+    except GitCommandError:
+        logger.debug("Could not check commit count")
+        return False
+
+
 def get_valid_ref(repo_dir: str | Path) -> str | None:
     """Get a valid git reference to compare against.
 
@@ -90,6 +112,12 @@ def get_valid_ref(repo_dir: str | Path) -> str | None:
     """
     refs_to_try = []
 
+    # Check if repo has any commits first. Empty repos (created with git init)
+    # won't have commits or remotes, so we can skip directly to the empty tree fallback.
+    if not _repo_has_commits(repo_dir):
+        logger.debug("Repository has no commits yet, using empty tree reference")
+        return GIT_EMPTY_TREE_HASH
+
     # Try current branch's origin
     try:
         current_branch = run_git_command(
@@ -136,10 +164,6 @@ def get_valid_ref(repo_dir: str | Path) -> str | None:
     except GitCommandError:
         logger.debug("Could not get remote information")
 
-    # Add empty tree as fallback for new repositories
-    refs_to_try.append(GIT_EMPTY_TREE_HASH)
-    logger.debug(f"Added empty tree reference: {GIT_EMPTY_TREE_HASH}")
-
     # Find the first valid reference
     for ref in refs_to_try:
         try:
@@ -153,8 +177,9 @@ def get_valid_ref(repo_dir: str | Path) -> str | None:
             logger.debug(f"Reference not valid: {ref}")
             continue
 
-    logger.warning("No valid git reference found")
-    return None
+    # Fallback to empty tree hash (always valid, no verification needed)
+    logger.debug(f"Using empty tree reference: {GIT_EMPTY_TREE_HASH}")
+    return GIT_EMPTY_TREE_HASH
 
 
 def validate_git_repository(repo_dir: str | Path) -> Path:

openhands/sdk/hooks/conversation_hooks.py

@@ -6,6 +6,7 @@ from openhands.sdk.event import ActionEvent, Event, MessageEvent, ObservationEve
 from openhands.sdk.hooks.config import HookConfig
 from openhands.sdk.hooks.manager import HookManager
 from openhands.sdk.hooks.types import HookEventType
+from openhands.sdk.llm import TextContent
 from openhands.sdk.logger import get_logger
 
 
@@ -41,6 +42,9 @@ class HookEventProcessor:
 
     def on_event(self, event: Event) -> None:
         """Process an event and run appropriate hooks."""
+        # Track the event to pass to callbacks (may be modified by hooks)
+        callback_event = event
+
         # Run PreToolUse hooks for action events
         if isinstance(event, ActionEvent) and event.action is not None:
             self._handle_pre_tool_use(event)
@@ -51,11 +55,11 @@ class HookEventProcessor:
 
         # Run UserPromptSubmit hooks for user messages
         if isinstance(event, MessageEvent) and event.source == "user":
-            self._handle_user_prompt_submit(event)
+            callback_event = self._handle_user_prompt_submit(event)
 
-        # Call original callback
+        # Call original callback with (possibly modified) event
         if self.original_callback:
-            self.original_callback(event)
+            self.original_callback(callback_event)
 
     def _handle_pre_tool_use(self, event: ActionEvent) -> None:
         """Handle PreToolUse hooks. Blocked actions are marked in conversation state."""
@@ -141,16 +145,18 @@ class HookEventProcessor:
             if result.error:
                 logger.warning(f"PostToolUse hook error: {result.error}")
 
-    def _handle_user_prompt_submit(self, event: MessageEvent) -> None:
-        """Handle UserPromptSubmit hooks before processing a user message."""
+    def _handle_user_prompt_submit(self, event: MessageEvent) -> MessageEvent:
+        """Handle UserPromptSubmit hooks before processing a user message.
+
+        Returns the (possibly modified) event. If hooks inject additional_context,
+        a new MessageEvent is created with the context appended to extended_content.
+        """
         if not self.hook_manager.has_hooks(HookEventType.USER_PROMPT_SUBMIT):
-            return
+            return event
 
         # Extract message text
         message = ""
         if event.llm_message and event.llm_message.content:
-            from openhands.sdk.llm import TextContent
-
             for content in event.llm_message.content:
                 if isinstance(content, TextContent):
                     message += content.text
@@ -175,9 +181,23 @@ class HookEventProcessor:
                     "after creating the Conversation."
                 )
 
-        # TODO: Inject additional_context into the message
+        # Inject additional_context into extended_content
         if additional_context:
-            logger.info(f"Hook injected context: {additional_context[:100]}...")
+            logger.debug(f"Hook injecting context: {additional_context[:100]}...")
+            new_extended_content = list(event.extended_content) + [
+                TextContent(text=additional_context)
+            ]
+            # MessageEvent is frozen, so create a new one
+            event = MessageEvent(
+                source=event.source,
+                llm_message=event.llm_message,
+                llm_response_id=event.llm_response_id,
+                activated_skills=event.activated_skills,
+                extended_content=new_extended_content,
+                sender=event.sender,
+            )
+
+        return event
 
     def is_action_blocked(self, action_id: str) -> bool:
         """Check if an action was blocked by a hook."""
@@ -205,6 +225,33 @@ class HookEventProcessor:
             if r.error:
                 logger.warning(f"SessionEnd hook error: {r.error}")
 
+    def run_stop(self, reason: str | None = None) -> tuple[bool, str | None]:
+        """Run Stop hooks. Returns (should_stop, feedback)."""
+        if not self.hook_manager.has_hooks(HookEventType.STOP):
+            return True, None
+
+        should_stop, results = self.hook_manager.run_stop(reason=reason)
+
+        # Log any errors
+        for r in results:
+            if r.error:
+                logger.warning(f"Stop hook error: {r.error}")
+
+        # Collect feedback if denied
+        feedback = None
+        if not should_stop:
+            reason_text = self.hook_manager.get_blocking_reason(results)
+            logger.info(f"Stop hook denied stopping: {reason_text}")
+            feedback_parts = [
+                r.additional_context for r in results if r.additional_context
+            ]
+            if feedback_parts:
+                feedback = "\n".join(feedback_parts)
+            elif reason_text:
+                feedback = reason_text
+
+        return should_stop, feedback
+
 
 def create_hook_callback(
     hook_config: HookConfig | None = None,