openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/event/llm_convertible/message.py

@@ -0,0 +1,142 @@
+import copy
+from collections.abc import Sequence
+from typing import ClassVar
+
+from pydantic import ConfigDict, Field
+from rich.text import Text
+
+from openhands.sdk.event.base import N_CHAR_PREVIEW, EventID, LLMConvertibleEvent
+from openhands.sdk.event.types import SourceType
+from openhands.sdk.llm import (
+    ImageContent,
+    Message,
+    RedactedThinkingBlock,
+    TextContent,
+    ThinkingBlock,
+    content_to_str,
+)
+
+
+class MessageEvent(LLMConvertibleEvent):
+    """Message from either agent or user.
+
+    This is originally the "MessageAction", but it suppose not to be tool call."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", frozen=True)
+
+    source: SourceType
+    llm_message: Message = Field(
+        ..., description="The exact LLM message for this message event"
+    )
+    llm_response_id: EventID | None = Field(
+        default=None,
+        description=(
+            "Completion or Response ID of the LLM response that generated this event"
+            "If the source != 'agent', this field is None"
+        ),
+    )
+
+    # context extensions stuff / skill can go here
+    activated_skills: list[str] = Field(
+        default_factory=list, description="List of activated skill name"
+    )
+    extended_content: list[TextContent] = Field(
+        default_factory=list, description="List of content added by agent context"
+    )
+    sender: str | None = Field(
+        default=None,
+        description=(
+            "Optional identifier of the sender. "
+            "Can be used to track message origin in multi-agent scenarios."
+        ),
+    )
+
+    @property
+    def reasoning_content(self) -> str:
+        return self.llm_message.reasoning_content or ""
+
+    @property
+    def thinking_blocks(self) -> Sequence[ThinkingBlock | RedactedThinkingBlock]:
+        """Return the Anthropic thinking blocks from the LLM message."""
+        return self.llm_message.thinking_blocks
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this message event."""
+        content = Text()
+
+        # Message text content
+        text_parts = content_to_str(self.llm_message.content)
+        if text_parts:
+            full_content = "".join(text_parts)
+            content.append(full_content)
+        else:
+            content.append("[no text content]")
+
+        # Responses API reasoning (plaintext only; never render encrypted_content)
+        reasoning_item = self.llm_message.responses_reasoning_item
+        if reasoning_item is not None:
+            content.append("\n\nReasoning:\n", style="bold")
+            if reasoning_item.summary:
+                for s in reasoning_item.summary:
+                    content.append(f"- {s}\n")
+            if reasoning_item.content:
+                for b in reasoning_item.content:
+                    content.append(f"{b}\n")
+
+        # Add skill information if present
+        if self.activated_skills:
+            content.append(
+                f"\n\nActivated Skills: {', '.join(self.activated_skills)}",
+            )
+
+        # Add extended content if available
+        if self.extended_content:
+            assert not any(
+                isinstance(c, ImageContent) for c in self.extended_content
+            ), "Extended content should not contain images"
+            text_parts = content_to_str(self.extended_content)
+            content.append(
+                "\n\nPrompt Extension based on Agent Context:\n", style="bold"
+            )
+            content.append(" ".join(text_parts))
+
+        return content
+
+    def to_llm_message(self) -> Message:
+        msg = copy.deepcopy(self.llm_message)
+        msg.content = list(msg.content) + list(self.extended_content)
+        return msg
+
+    def __str__(self) -> str:
+        """Plain text string representation for MessageEvent."""
+        base_str = f"{self.__class__.__name__} ({self.source})"
+        # Extract text content from the message
+        text_parts = []
+        message = self.to_llm_message()
+        for content in message.content:
+            if isinstance(content, TextContent):
+                text_parts.append(content.text)
+            elif isinstance(content, ImageContent):
+                text_parts.append(f"[Image: {len(content.image_urls)} URLs]")
+
+        if text_parts:
+            content_preview = " ".join(text_parts)
+            if len(content_preview) > N_CHAR_PREVIEW:
+                content_preview = content_preview[: N_CHAR_PREVIEW - 3] + "..."
+            skill_info = (
+                f" [Skills: {', '.join(self.activated_skills)}]"
+                if self.activated_skills
+                else ""
+            )
+            thinking_info = (
+                f" [Thinking blocks: {len(self.thinking_blocks)}]"
+                if self.thinking_blocks
+                else ""
+            )
+            return (
+                f"{base_str}\n  {message.role}: "
+                f"{content_preview}{skill_info}{thinking_info}"
+            )
+        else:
+            return f"{base_str}\n  {message.role}: [no text content]"

openhands/sdk/event/llm_convertible/observation.py

@@ -0,0 +1,141 @@
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.event.base import N_CHAR_PREVIEW, LLMConvertibleEvent
+from openhands.sdk.event.types import EventID, SourceType, ToolCallID
+from openhands.sdk.llm import Message, TextContent, content_to_str
+from openhands.sdk.tool.schema import Observation
+
+
+class ObservationBaseEvent(LLMConvertibleEvent):
+    """Base class for anything as a response to a tool call.
+
+    Examples include tool execution, error, user reject.
+    """
+
+    source: SourceType = "environment"
+    tool_name: str = Field(
+        ..., description="The tool name that this observation is responding to"
+    )
+    tool_call_id: ToolCallID = Field(
+        ..., description="The tool call id that this observation is responding to"
+    )
+
+
+class ObservationEvent(ObservationBaseEvent):
+    observation: Observation = Field(
+        ..., description="The observation (tool call) sent to LLM"
+    )
+    action_id: EventID = Field(
+        ..., description="The action id that this observation is responding to"
+    )
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this observation event."""
+        to_viz = self.observation.visualize
+        content = Text()
+        if to_viz.plain.strip():
+            content.append("Tool: ", style="bold")
+            content.append(self.tool_name)
+            content.append("\nResult:\n", style="bold")
+            content.append(to_viz)
+        return content
+
+    def to_llm_message(self) -> Message:
+        return Message(
+            role="tool",
+            content=self.observation.to_llm_content,
+            name=self.tool_name,
+            tool_call_id=self.tool_call_id,
+        )
+
+    def __str__(self) -> str:
+        """Plain text string representation for ObservationEvent."""
+        base_str = f"{self.__class__.__name__} ({self.source})"
+        content_str = "".join(content_to_str(self.observation.to_llm_content))
+        obs_preview = (
+            content_str[:N_CHAR_PREVIEW] + "..."
+            if len(content_str) > N_CHAR_PREVIEW
+            else content_str
+        )
+        return f"{base_str}\n  Tool: {self.tool_name}\n  Result: {obs_preview}"
+
+
+class UserRejectObservation(ObservationBaseEvent):
+    """Observation when user rejects an action in confirmation mode."""
+
+    rejection_reason: str = Field(
+        default="User rejected the action",
+        description="Reason for rejecting the action",
+    )
+    action_id: EventID = Field(
+        ..., description="The action id that this observation is responding to"
+    )
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this user rejection event."""
+        content = Text()
+        content.append("Tool: ", style="bold")
+        content.append(self.tool_name)
+        content.append("\n\nRejection Reason:\n", style="bold")
+        content.append(self.rejection_reason)
+        return content
+
+    def to_llm_message(self) -> Message:
+        return Message(
+            role="tool",
+            content=[TextContent(text=f"Action rejected: {self.rejection_reason}")],
+            name=self.tool_name,
+            tool_call_id=self.tool_call_id,
+        )
+
+    def __str__(self) -> str:
+        """Plain text string representation for UserRejectObservation."""
+        base_str = f"{self.__class__.__name__} ({self.source})"
+        reason_preview = (
+            self.rejection_reason[:N_CHAR_PREVIEW] + "..."
+            if len(self.rejection_reason) > N_CHAR_PREVIEW
+            else self.rejection_reason
+        )
+        return f"{base_str}\n  Tool: {self.tool_name}\n  Reason: {reason_preview}"
+
+
+class AgentErrorEvent(ObservationBaseEvent):
+    """Error triggered by the agent.
+
+    Note: This event should not contain model "thought" or "reasoning_content". It
+    represents an error produced by the agent/scaffold, not model output.
+    """
+
+    source: SourceType = "agent"
+    error: str = Field(..., description="The error message from the scaffold")
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this agent error event."""
+        content = Text()
+        content.append("Error Details:\n", style="bold")
+        content.append(self.error)
+        return content
+
+    def to_llm_message(self) -> Message:
+        # Provide plain string error content; serializers handle Chat vs Responses.
+        # For Responses API, output is a string; JSON is not required.
+        return Message(
+            role="tool",
+            content=[TextContent(text=self.error)],
+            name=self.tool_name,
+            tool_call_id=self.tool_call_id,
+        )
+
+    def __str__(self) -> str:
+        """Plain text string representation for AgentErrorEvent."""
+        base_str = f"{self.__class__.__name__} ({self.source})"
+        error_preview = (
+            self.error[:N_CHAR_PREVIEW] + "..."
+            if len(self.error) > N_CHAR_PREVIEW
+            else self.error
+        )
+        return f"{base_str}\n  Error: {error_preview}"

openhands/sdk/event/llm_convertible/system.py

@@ -0,0 +1,61 @@
+import json
+
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.event.base import N_CHAR_PREVIEW, LLMConvertibleEvent
+from openhands.sdk.event.types import SourceType
+from openhands.sdk.llm import Message, TextContent
+from openhands.sdk.tool import ToolDefinition
+
+
+class SystemPromptEvent(LLMConvertibleEvent):
+    """System prompt added by the agent."""
+
+    source: SourceType = "agent"
+    system_prompt: TextContent = Field(..., description="The system prompt text")
+    tools: list[ToolDefinition] = Field(
+        ..., description="List of tools as ToolDefinition objects"
+    )
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this system prompt event."""
+        content = Text()
+        content.append("System Prompt:\n", style="bold")
+        content.append(self.system_prompt.text)
+        content.append(f"\n\nTools Available: {len(self.tools)}")
+        for tool in self.tools:
+            # Use ToolDefinition properties directly
+            description = tool.description.split("\n")[0][:100]
+            if len(description) < len(tool.description):
+                description += "..."
+
+            content.append(f"\n  - {tool.name}: {description}\n")
+
+            # Get parameters from the action type schema
+            try:
+                params_dict = tool.action_type.to_mcp_schema()
+                params_str = json.dumps(params_dict)
+                if len(params_str) > 200:
+                    params_str = params_str[:197] + "..."
+                content.append(f"  Parameters: {params_str}")
+            except Exception:
+                content.append("  Parameters: <unavailable>")
+        return content
+
+    def to_llm_message(self) -> Message:
+        return Message(role="system", content=[self.system_prompt])
+
+    def __str__(self) -> str:
+        """Plain text string representation for SystemPromptEvent."""
+        base_str = f"{self.__class__.__name__} ({self.source})"
+        prompt_preview = (
+            self.system_prompt.text[:N_CHAR_PREVIEW] + "..."
+            if len(self.system_prompt.text) > N_CHAR_PREVIEW
+            else self.system_prompt.text
+        )
+        tool_count = len(self.tools)
+        return (
+            f"{base_str}\n  System: {prompt_preview}\n  Tools: {tool_count} available"
+        )

openhands/sdk/event/token.py

@@ -0,0 +1,16 @@
+from pydantic import Field
+
+from openhands.sdk.event.base import Event
+from openhands.sdk.event.types import SourceType
+
+
+class TokenEvent(Event):
+    """Event from VLLM representing token IDs used in LLM interaction."""
+
+    source: SourceType
+    prompt_token_ids: list[int] = Field(
+        ..., description="The exact prompt token IDs for this message event"
+    )
+    response_token_ids: list[int] = Field(
+        ..., description="The exact response token IDs for this message event"
+    )

openhands/sdk/event/types.py

@@ -0,0 +1,11 @@
+from typing import Literal
+
+
+EventType = Literal["action", "observation", "message", "system_prompt", "agent_error"]
+SourceType = Literal["agent", "user", "environment"]
+
+EventID = str
+"""Type alias for event IDs."""
+
+ToolCallID = str
+"""Type alias for tool call IDs."""

openhands/sdk/event/user_action.py

@@ -0,0 +1,21 @@
+from rich.text import Text
+
+from openhands.sdk.event.base import Event
+from openhands.sdk.event.types import SourceType
+
+
+class PauseEvent(Event):
+    """Event indicating that the agent execution was paused by user request."""
+
+    source: SourceType = "user"
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this pause event."""
+        content = Text()
+        content.append("Conversation Paused", style="bold")
+        return content
+
+    def __str__(self) -> str:
+        """Plain text string representation for PauseEvent."""
+        return f"{self.__class__.__name__} ({self.source}): Agent execution paused"

openhands/sdk/git/exceptions.py

@@ -0,0 +1,43 @@
+"""Git-related exceptions for OpenHands SDK."""
+
+
+class GitError(Exception):
+    """Base exception for git-related errors."""
+
+    pass
+
+
+class GitRepositoryError(GitError):
+    """Exception raised when git repository operations fail."""
+
+    command: str | None
+    exit_code: int | None
+
+    def __init__(
+        self, message: str, command: str | None = None, exit_code: int | None = None
+    ):
+        self.command = command
+        self.exit_code = exit_code
+        super().__init__(message)
+
+
+class GitCommandError(GitError):
+    """Exception raised when git command execution fails."""
+
+    command: list[str]
+    exit_code: int
+    stderr: str
+
+    def __init__(
+        self, message: str, command: list[str], exit_code: int, stderr: str = ""
+    ):
+        self.command = command
+        self.exit_code = exit_code
+        self.stderr = stderr
+        super().__init__(message)
+
+
+class GitPathError(GitError):
+    """Exception raised when git path operations fail."""
+
+    pass

openhands/sdk/git/git_changes.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Get git changes in the current working directory relative to the remote origin
+if possible.
+"""
+
+import glob
+import json
+import logging
+import os
+from pathlib import Path
+
+from openhands.sdk.git.exceptions import GitCommandError
+from openhands.sdk.git.models import GitChange, GitChangeStatus
+from openhands.sdk.git.utils import (
+    get_valid_ref,
+    run_git_command,
+    validate_git_repository,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+def _map_git_status_to_enum(status: str) -> GitChangeStatus:
+    """Map git status codes to GitChangeStatus enum values."""
+    status_mapping = {
+        "M": GitChangeStatus.UPDATED,
+        "A": GitChangeStatus.ADDED,
+        "D": GitChangeStatus.DELETED,
+        "U": GitChangeStatus.UPDATED,  # Unmerged files are treated as updated
+    }
+    if status not in status_mapping:
+        raise ValueError(f"Unknown git status: {status}")
+    return status_mapping[status]
+
+
+def get_changes_in_repo(repo_dir: str | Path) -> list[GitChange]:
+    """Get git changes in a repository relative to the origin default branch.
+
+    This is different from `git status` as it compares against the remote branch
+    rather than the staging area.
+
+    Args:
+        repo_dir: Path to the git repository
+
+    Returns:
+        List of GitChange objects representing the changes
+
+    Raises:
+        GitRepositoryError: If the directory is not a valid git repository
+        GitCommandError: If git commands fail
+    """
+    # Validate the repository first
+    validated_repo = validate_git_repository(repo_dir)
+
+    ref = get_valid_ref(validated_repo)
+    if not ref:
+        logger.warning(f"No valid git reference found for {validated_repo}")
+        return []
+
+    # Get changed files using secure git command
+    try:
+        changed_files_output = run_git_command(
+            ["git", "--no-pager", "diff", "--name-status", ref], validated_repo
+        )
+        changed_files = (
+            changed_files_output.splitlines() if changed_files_output else []
+        )
+    except GitCommandError as e:
+        logger.error(f"Failed to get git diff for {validated_repo}: {e}")
+        raise
+    changes = []
+    for line in changed_files:
+        if not line.strip():
+            logger.warning("Empty line in git diff output, skipping")
+            continue
+
+        # Handle different output formats from git diff --name-status
+        # Depending on git config, format can be either:
+        # * "A file.txt"
+        # * "A       file.txt"
+        # * "R100    old_file.txt    new_file.txt" (rename with similarity percentage)
+        parts = line.split()
+        if len(parts) < 2:
+            logger.error(f"Unexpected git diff line format: {line}")
+            raise GitCommandError(
+                message=f"Unexpected git diff output format: {line}",
+                command=["git", "diff", "--name-status"],
+                exit_code=0,
+                stderr="Invalid output format",
+            )
+
+        status = parts[0].strip()
+
+        # Handle rename operations (status starts with 'R' followed
+        # by similarity percentage)
+        if status.startswith("R") and len(parts) == 3:
+            # Rename: convert to delete (old path) + add (new path)
+            old_path = parts[1].strip()
+            new_path = parts[2].strip()
+            changes.append(
+                GitChange(
+                    status=GitChangeStatus.DELETED,
+                    path=Path(old_path),
+                )
+            )
+            changes.append(
+                GitChange(
+                    status=GitChangeStatus.ADDED,
+                    path=Path(new_path),
+                )
+            )
+            logger.debug(f"Found git rename: {old_path} -> {new_path}")
+            continue
+
+        # Handle copy operations (status starts with 'C' followed by
+        # similarity percentage)
+        elif status.startswith("C") and len(parts) == 3:
+            # Copy: only add the new path (original remains)
+            new_path = parts[2].strip()
+            changes.append(
+                GitChange(
+                    status=GitChangeStatus.ADDED,
+                    path=Path(new_path),
+                )
+            )
+            logger.debug(f"Found git copy: -> {new_path}")
+            continue
+
+        # Handle regular operations (M, A, D, etc.)
+        elif len(parts) == 2:
+            path = parts[1].strip()
+        else:
+            logger.error(f"Unexpected git diff line format: {line}")
+            raise GitCommandError(
+                message=f"Unexpected git diff output format: {line}",
+                command=["git", "diff", "--name-status"],
+                exit_code=0,
+                stderr="Invalid output format",
+            )
+
+        if status == "??":
+            status = "A"
+        elif status == "*":
+            status = "M"
+
+        # Check for valid single-character status codes
+        if status in {"M", "A", "D", "U"}:
+            try:
+                changes.append(
+                    GitChange(
+                        status=_map_git_status_to_enum(status),
+                        path=Path(path),
+                    )
+                )
+                logger.debug(f"Found git change: {status} {path}")
+            except ValueError as e:
+                logger.error(f"Unknown git status '{status}' for file {path}")
+                raise GitCommandError(
+                    message=f"Unknown git status: {status}",
+                    command=["git", "diff", "--name-status"],
+                    exit_code=0,
+                    stderr=f"Unknown status code: {status}",
+                ) from e
+        else:
+            logger.error(f"Unexpected git status '{status}' for file {path}")
+            raise GitCommandError(
+                message=f"Unexpected git status: {status}",
+                command=["git", "diff", "--name-status"],
+                exit_code=0,
+                stderr=f"Unexpected status code: {status}",
+            )
+
+    # Get untracked files
+    try:
+        untracked_output = run_git_command(
+            ["git", "--no-pager", "ls-files", "--others", "--exclude-standard"],
+            validated_repo,
+        )
+        untracked_files = untracked_output.splitlines() if untracked_output else []
+    except GitCommandError as e:
+        logger.error(f"Failed to get untracked files for {validated_repo}: {e}")
+        untracked_files = []
+    for path in untracked_files:
+        if path.strip():
+            changes.append(
+                GitChange(
+                    status=GitChangeStatus.ADDED,
+                    path=Path(path.strip()),
+                )
+            )
+            logger.debug(f"Found untracked file: {path}")
+
+    logger.info(f"Found {len(changes)} total git changes in {validated_repo}")
+    return changes
+
+
+def get_git_changes(cwd: str | Path) -> list[GitChange]:
+    git_dirs = {
+        os.path.dirname(f)[2:]
+        for f in glob.glob("./*/.git", root_dir=cwd, recursive=True)
+    }
+
+    # First try the workspace directory
+    changes = get_changes_in_repo(cwd)
+
+    # Filter out any changes which are in one of the git directories
+    changes = [
+        change
+        for change in changes
+        if next(
+            iter(
+                git_dir for git_dir in git_dirs if str(change.path).startswith(git_dir)
+            ),
+            None,
+        )
+        is None
+    ]
+
+    # Add changes from git directories
+    for git_dir in git_dirs:
+        git_dir_changes = get_changes_in_repo(str(Path(cwd, git_dir)))
+        for change in git_dir_changes:
+            # Create a new GitChange with the updated path
+            updated_change = GitChange(
+                status=change.status,
+                path=Path(git_dir) / change.path,
+            )
+            changes.append(updated_change)
+
+    changes.sort(key=lambda change: str(change.path))
+
+    return changes
+
+
+if __name__ == "__main__":
+    try:
+        changes = get_git_changes(os.getcwd())
+        # Convert GitChange objects to dictionaries for JSON serialization
+        changes_dict = [
+            {
+                "status": change.status.value,
+                "path": str(change.path),
+            }
+            for change in changes
+        ]
+        print(json.dumps(changes_dict))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))