openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/event/base.py

@@ -0,0 +1,149 @@
+import uuid
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING, ClassVar
+
+from pydantic import ConfigDict, Field
+from rich.text import Text
+
+from openhands.sdk.event.types import EventID, SourceType
+from openhands.sdk.llm import ImageContent, Message, TextContent
+from openhands.sdk.utils.models import DiscriminatedUnionMixin
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.event.llm_convertible import ActionEvent
+
+N_CHAR_PREVIEW = 500
+
+
+class Event(DiscriminatedUnionMixin, ABC):
+    """Base class for all events."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", frozen=True)
+    id: EventID = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique event id (ULID/UUID)",
+    )
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now().isoformat(),
+        description="Event timestamp",
+    )  # consistent with V1
+    source: SourceType = Field(..., description="The source of this event")
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this event.
+
+        This is a fallback implementation for unknown event types.
+        Subclasses should override this method to provide specific visualization.
+        """
+        content = Text()
+        content.append(f"Unknown event type: {self.__class__.__name__}")
+        content.append(f"\n{self.model_dump()}")
+        return content
+
+    def __str__(self) -> str:
+        """Plain text string representation for display."""
+        return f"{self.__class__.__name__} ({self.source})"
+
+    def __repr__(self) -> str:
+        """Developer-friendly representation."""
+        return (
+            f"{self.__class__.__name__}(id='{self.id[:8]}...', "
+            f"source='{self.source}', timestamp='{self.timestamp}')"
+        )
+
+
+class LLMConvertibleEvent(Event, ABC):
+    """Base class for events that can be converted to LLM messages."""
+
+    @abstractmethod
+    def to_llm_message(self) -> Message:
+        raise NotImplementedError()
+
+    def __str__(self) -> str:
+        """Plain text string representation showing LLM message content."""
+        base_str = super().__str__()
+        try:
+            llm_message = self.to_llm_message()
+            # Extract text content from the message
+            text_parts = []
+            for content in llm_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)
+                # Truncate long content for display
+                if len(content_preview) > N_CHAR_PREVIEW:
+                    content_preview = content_preview[: N_CHAR_PREVIEW - 3] + "..."
+                return f"{base_str}\n  {llm_message.role}: {content_preview}"
+            else:
+                return f"{base_str}\n  {llm_message.role}: [no text content]"
+        except Exception:
+            # Fallback to base representation if LLM message conversion fails
+            return base_str
+
+    @staticmethod
+    def events_to_messages(events: list["LLMConvertibleEvent"]) -> list[Message]:
+        """Convert event stream to LLM message stream, handling multi-action batches"""
+        # TODO: We should add extensive tests for this
+        from openhands.sdk.event.llm_convertible import ActionEvent
+
+        messages = []
+        i = 0
+
+        while i < len(events):
+            event = events[i]
+
+            if isinstance(event, ActionEvent):
+                # Collect all ActionEvents from same LLM respone
+                # This happens when function calling happens
+                batch_events: list[ActionEvent] = [event]
+                response_id = event.llm_response_id
+
+                # Look ahead for related events
+                j = i + 1
+                while j < len(events) and isinstance(events[j], ActionEvent):
+                    event = events[j]
+                    assert isinstance(event, ActionEvent)  # for type checker
+                    if event.llm_response_id != response_id:
+                        break
+                    batch_events.append(event)
+                    j += 1
+
+                # Create combined message for the response
+                messages.append(_combine_action_events(batch_events))
+                i = j
+            else:
+                # Regular event - direct conversion
+                messages.append(event.to_llm_message())
+                i += 1
+
+        return messages
+
+
+def _combine_action_events(events: list["ActionEvent"]) -> Message:
+    """Combine multiple ActionEvents into single LLM message.
+
+    We receive multiple ActionEvents per LLM message WHEN LLM returns
+    multiple tool calls with parallel function calling.
+    """
+    if len(events) == 1:
+        return events[0].to_llm_message()
+    # Multi-action case - reconstruct original LLM response
+    for e in events[1:]:
+        assert len(e.thought) == 0, (
+            "Expected empty thought for multi-action events after the first one"
+        )
+
+    return Message(
+        role="assistant",
+        content=events[0].thought,  # Shared thought content only in the first event
+        tool_calls=[event.tool_call for event in events],
+        reasoning_content=events[0].reasoning_content,  # Shared reasoning content
+        thinking_blocks=events[0].thinking_blocks,  # Shared thinking blocks
+    )

openhands/sdk/event/condenser.py

@@ -0,0 +1,82 @@
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.event.base import Event, LLMConvertibleEvent
+from openhands.sdk.event.types import EventID, SourceType
+from openhands.sdk.llm import Message, TextContent
+
+
+class Condensation(Event):
+    """This action indicates a condensation of the conversation history is happening."""
+
+    forgotten_event_ids: list[EventID] = Field(
+        default_factory=list,
+        description="The IDs of the events that are being forgotten "
+        "(removed from the `View` given to the LLM).",
+    )
+
+    summary: str | None = Field(
+        default=None, description="An optional summary of the events being forgotten."
+    )
+
+    summary_offset: int | None = Field(
+        default=None,
+        ge=0,
+        description="An optional offset to the start of the resulting view"
+        " indicating where the summary should be inserted.",
+    )
+    llm_response_id: EventID = Field(
+        description=(
+            "Completion or Response ID of the LLM response that generated this event"
+        ),
+    )
+
+    source: SourceType = "environment"
+
+    @property
+    def visualize(self) -> Text:
+        text = Text()
+
+        text.append("Auto Conversation Condensation Triggered.\n", style="bold")
+
+        text.append(f"Forgetting {len(self.forgotten_event_ids)} events\n")
+        if self.summary:
+            text.append("\n[Summary of Events Being Forgotten]\n", style="bold")
+            text.append(f"{self.summary}\n")
+        return text
+
+
+class CondensationRequest(Event):
+    """This action is used to request a condensation of the conversation history.
+
+    Attributes:
+        action (str): The action type, namely ActionType.CONDENSATION_REQUEST.
+    """
+
+    source: SourceType = "environment"
+
+    @property
+    def visualize(self) -> Text:
+        text = Text()
+        text.append("Conversation Condensation Requested\n", style="bold")
+        message = (
+            "A condensation of the conversation history has been requested to "
+            "manage context window usage.\n"
+        )
+        text.append(message)
+        return text
+
+
+class CondensationSummaryEvent(LLMConvertibleEvent):
+    """This event represents a summary generated by a condenser."""
+
+    summary: str
+    """The summary text."""
+
+    source: SourceType = "environment"
+
+    def to_llm_message(self) -> Message:
+        return Message(
+            role="user",
+            content=[TextContent(text=self.summary)],
+        )

openhands/sdk/event/conversation_error.py

@@ -0,0 +1,25 @@
+from pydantic import Field
+
+from openhands.sdk.event.base import Event
+
+
+class ConversationErrorEvent(Event):
+    """
+    Conversation-level failure that is NOT sent back to the LLM.
+
+    This event is emitted by the conversation runtime when an unexpected
+    exception bubbles up and prevents the run loop from continuing. It is
+    intended for client applications (e.g., UIs) to present a top-level error
+    state, and for orchestration to react. It is not an observation and it is
+    not LLM-convertible.
+
+    Differences from AgentErrorEvent:
+    - Not tied to any tool_name/tool_call_id (AgentErrorEvent is a tool
+      observation).
+    - Typically source='environment' and the run loop moves to an ERROR state,
+      while AgentErrorEvent has source='agent' and the conversation can
+      continue.
+    """
+
+    code: str = Field(description="Code for the error - typically a type")
+    detail: str = Field(description="Details about the error")

openhands/sdk/event/conversation_state.py

@@ -0,0 +1,104 @@
+"""Events related to conversation state updates."""
+
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from pydantic import Field, field_validator
+
+from openhands.sdk.event.base import Event
+from openhands.sdk.event.types import SourceType
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.state import ConversationState
+
+FULL_STATE_KEY = "full_state"
+
+
+class ConversationStateUpdateEvent(Event):
+    """Event that contains conversation state updates.
+
+    This event is sent via websocket whenever the conversation state changes,
+    allowing remote clients to stay in sync without making REST API calls.
+
+    All fields are serialized versions of the corresponding ConversationState fields
+    to ensure compatibility with websocket transmission.
+    """
+
+    source: SourceType = "environment"
+    key: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique key for this state update event",
+    )
+    value: Any = Field(
+        default_factory=dict,
+        description="Serialized conversation state updates",
+    )
+
+    @field_validator("key")
+    def validate_key(cls, key):
+        if not isinstance(key, str):
+            raise ValueError("Key must be a string")
+        # Allow special key "full_state" for full state snapshots
+        if key == FULL_STATE_KEY:
+            return key
+        # Allow any string key for flexibility (testing, future extensibility)
+        # In practice, keys should match ConversationState fields,
+        # but we don't enforce it
+        return key
+
+    @field_validator("value")
+    def validate_value(cls, value, info):
+        # Prevent circular import
+        from openhands.sdk.conversation.conversation_stats import ConversationStats
+
+        # For ConversationStats, use snapshot serialization to avoid
+        # sending lengthy lists over WebSocket
+        if isinstance(value, ConversationStats):
+            return value.model_dump(mode="json", context={"use_snapshot": True})
+
+        key = info.data.get("key")
+        if key is None:
+            # Allow value without key for flexibility
+            return value
+
+        # Skip validation for special "full_state" key
+        if key == FULL_STATE_KEY:
+            return value
+
+        # Prevent circular import
+        from openhands.sdk.conversation.state import ConversationState
+
+        field_info = ConversationState.model_fields.get(key)
+        if field_info is None:
+            # Allow arbitrary keys for testing/future extensibility
+            return value
+
+        # Skip type validation - just accept any value
+        # The actual type conversion will happen when the state is updated
+        return value
+
+    @classmethod
+    def from_conversation_state(
+        cls, state: "ConversationState"
+    ) -> "ConversationStateUpdateEvent":
+        """Create a state update event from a ConversationState object.
+
+        This creates an event containing a snapshot of important state fields.
+
+        Args:
+            state: The ConversationState to serialize
+            conversation_id: The conversation ID for the event
+
+        Returns:
+            A ConversationStateUpdateEvent with serialized state data
+        """
+        # Create a snapshot with all important state fields
+        # Use mode='json' to ensure proper serialization including SecretStr
+        state_snapshot = state.model_dump(mode="json", exclude_none=True)
+
+        # Use a special key "full_state" to indicate this is a full snapshot
+        return cls(key=FULL_STATE_KEY, value=state_snapshot)
+
+    def __str__(self) -> str:
+        return f"ConversationStateUpdate(key={self.key}, value={self.value})"

openhands/sdk/event/llm_completion_log.py

@@ -0,0 +1,39 @@
+"""Event for streaming LLM completion logs from remote agents to clients."""
+
+from pydantic import Field
+
+from openhands.sdk.event.base import Event
+from openhands.sdk.event.types import SourceType
+
+
+class LLMCompletionLogEvent(Event):
+    """Event containing LLM completion log data.
+
+    When an LLM is configured with log_completions=True in a remote conversation,
+    this event streams the completion log data back to the client through WebSocket
+    instead of writing it to a file inside the Docker container.
+    """
+
+    source: SourceType = "environment"
+    filename: str = Field(
+        ...,
+        description="The intended filename for this log (relative to log directory)",
+    )
+    log_data: str = Field(
+        ...,
+        description="The JSON-encoded log data to be written to the file",
+    )
+    model_name: str = Field(
+        default="unknown",
+        description="The model name for context",
+    )
+    usage_id: str = Field(
+        default="default",
+        description="The LLM usage_id that produced this log",
+    )
+
+    def __str__(self) -> str:
+        return (
+            f"LLMCompletionLog(usage_id={self.usage_id}, model={self.model_name}, "
+            f"file={self.filename})"
+        )

openhands/sdk/event/llm_convertible/__init__.py

@@ -0,0 +1,20 @@
+from openhands.sdk.event.llm_convertible.action import ActionEvent
+from openhands.sdk.event.llm_convertible.message import MessageEvent
+from openhands.sdk.event.llm_convertible.observation import (
+    AgentErrorEvent,
+    ObservationBaseEvent,
+    ObservationEvent,
+    UserRejectObservation,
+)
+from openhands.sdk.event.llm_convertible.system import SystemPromptEvent
+
+
+__all__ = [
+    "SystemPromptEvent",
+    "ActionEvent",
+    "ObservationEvent",
+    "ObservationBaseEvent",
+    "MessageEvent",
+    "AgentErrorEvent",
+    "UserRejectObservation",
+]

openhands/sdk/event/llm_convertible/action.py

@@ -0,0 +1,139 @@
+from collections.abc import Sequence
+
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.event.base import N_CHAR_PREVIEW, EventID, LLMConvertibleEvent
+from openhands.sdk.event.types import SourceType, ToolCallID
+from openhands.sdk.llm import (
+    Message,
+    MessageToolCall,
+    ReasoningItemModel,
+    RedactedThinkingBlock,
+    TextContent,
+    ThinkingBlock,
+)
+from openhands.sdk.security import risk
+from openhands.sdk.tool.schema import Action
+
+
+class ActionEvent(LLMConvertibleEvent):
+    source: SourceType = "agent"
+    thought: Sequence[TextContent] = Field(
+        ..., description="The thought process of the agent before taking this action"
+    )
+    reasoning_content: str | None = Field(
+        default=None,
+        description="Intermediate reasoning/thinking content from reasoning models",
+    )
+    thinking_blocks: list[ThinkingBlock | RedactedThinkingBlock] = Field(
+        default_factory=list,
+        description="Anthropic thinking blocks from the LLM response",
+    )
+    responses_reasoning_item: ReasoningItemModel | None = Field(
+        default=None, description="OpenAI Responses reasoning item from model output"
+    )
+    action: Action | None = Field(
+        default=None,
+        description="Single tool call returned by LLM (None when non-executable)",
+    )
+    tool_name: str = Field(..., description="The name of the tool being called")
+    tool_call_id: ToolCallID = Field(
+        ..., description="The unique id returned by LLM API for this tool call"
+    )
+    tool_call: MessageToolCall = Field(
+        ...,
+        description=(
+            "The tool call received from the LLM response. We keep a copy of it "
+            "so it is easier to construct it into LLM message"
+            "This could be different from `action`: e.g., `tool_call` may contain "
+            "`security_risk` field predicted by LLM when LLM risk analyzer is enabled"
+            ", while `action` does not."
+        ),
+    )
+    llm_response_id: EventID = Field(
+        description=(
+            "Completion or Response ID of the LLM response that generated this event"
+            "E.g., Can be used to group related actions from same LLM response. "
+            "This helps in tracking and managing results of parallel function calling "
+            "from the same LLM response."
+        ),
+    )
+
+    security_risk: risk.SecurityRisk = Field(
+        default=risk.SecurityRisk.UNKNOWN,
+        description="The LLM's assessment of the safety risk of this action.",
+    )
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this action event."""
+        content = Text()
+
+        if self.security_risk != risk.SecurityRisk.UNKNOWN:
+            content.append(self.security_risk.visualize)
+
+        # Display reasoning content first if available
+        if self.reasoning_content:
+            content.append("Reasoning:\n", style="bold")
+            content.append(self.reasoning_content)
+            content.append("\n\n")
+
+        # Display complete thought content
+        thought_text = " ".join([t.text for t in self.thought])
+        if thought_text:
+            content.append("Thought:\n", style="bold")
+            content.append(thought_text)
+            content.append("\n\n")
+
+        # Responses API reasoning (plaintext only; never render encrypted_content)
+        reasoning_item = self.responses_reasoning_item
+        if reasoning_item is not None:
+            content.append("Reasoning:\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")
+
+        # Display action information using action's visualize method
+        if self.action:
+            content.append(self.action.visualize)
+        else:
+            # When action is None (non-executable), show the function call
+            content.append("Function call:\n", style="bold")
+            content.append(f"- {self.tool_call.name} ({self.tool_call.id})\n")
+
+        return content
+
+    def to_llm_message(self) -> Message:
+        """Individual message - may be incomplete for multi-action batches"""
+        return Message(
+            role="assistant",
+            content=self.thought,
+            tool_calls=[self.tool_call],
+            reasoning_content=self.reasoning_content,
+            thinking_blocks=self.thinking_blocks,
+            responses_reasoning_item=self.responses_reasoning_item,
+        )
+
+    def __str__(self) -> str:
+        """Plain text string representation for ActionEvent."""
+        base_str = f"{self.__class__.__name__} ({self.source})"
+        thought_text = " ".join([t.text for t in self.thought])
+        thought_preview = (
+            thought_text[:N_CHAR_PREVIEW] + "..."
+            if len(thought_text) > N_CHAR_PREVIEW
+            else thought_text
+        )
+        if self.action:
+            action_name = self.action.__class__.__name__
+            return f"{base_str}\n  Thought: {thought_preview}\n  Action: {action_name}"
+        else:
+            # When action is None (non-executable), show the tool call
+            call = f"{self.tool_call.name}:{self.tool_call.id}"
+            return (
+                f"{base_str}\n  Thought: {thought_preview}\n  Action: (not executed)"
+                f"\n  Call: {call}"
+            )