openhands-sdk 1.7.0__py3-none-any.whl

openhands/sdk/context/skills/types.py

@@ -0,0 +1,48 @@
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, Field
+
+
+class InputMetadata(BaseModel):
+    """Metadata for task skill inputs."""
+
+    name: str = Field(description="Name of the input parameter")
+    description: str = Field(description="Description of the input parameter")
+
+
+class SkillKnowledge(BaseModel):
+    """Represents knowledge from a triggered skill."""
+
+    name: str = Field(description="The name of the skill that was triggered")
+    trigger: str = Field(description="The word that triggered this skill")
+    content: str = Field(description="The actual content/knowledge from the skill")
+
+
+class SkillResponse(BaseModel):
+    """Response model for skills endpoint.
+
+    Note: This model only includes basic metadata that can be determined
+    without parsing skill content. Use the separate content API
+    to get detailed skill information.
+    """
+
+    name: str = Field(description="The name of the skill")
+    path: str = Field(description="The path or identifier of the skill")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="Timestamp when the skill was created",
+    )
+
+
+class SkillContentResponse(BaseModel):
+    """Response model for individual skill content endpoint."""
+
+    content: str = Field(description="The full content of the skill")
+    path: str = Field(description="The path or identifier of the skill")
+    triggers: list[str] = Field(
+        description="List of triggers associated with the skill"
+    )
+    git_provider: str | None = Field(
+        None,
+        description="Git provider if the skill is sourced from a Git repository",
+    )

openhands/sdk/context/view.py

@@ -0,0 +1,306 @@
+from collections.abc import Sequence
+from logging import getLogger
+from typing import overload
+
+from pydantic import BaseModel
+
+from openhands.sdk.event import (
+    Condensation,
+    CondensationRequest,
+    CondensationSummaryEvent,
+    LLMConvertibleEvent,
+)
+from openhands.sdk.event.base import Event, EventID
+from openhands.sdk.event.llm_convertible import (
+    ActionEvent,
+    ObservationBaseEvent,
+)
+from openhands.sdk.event.types import ToolCallID
+
+
+logger = getLogger(__name__)
+
+
+class View(BaseModel):
+    """Linearly ordered view of events.
+
+    Produced by a condenser to indicate the included events are ready to process as LLM
+    input. Also contains fields with information from the condensation process to aid
+    in deciding whether further condensation is needed.
+    """
+
+    events: list[LLMConvertibleEvent]
+
+    unhandled_condensation_request: bool = False
+    """Whether there is an unhandled condensation request in the view."""
+
+    condensations: list[Condensation] = []
+    """A list of condensations that were processed to produce the view."""
+
+    def __len__(self) -> int:
+        return len(self.events)
+
+    @property
+    def most_recent_condensation(self) -> Condensation | None:
+        """Return the most recent condensation, or None if no condensations exist."""
+        return self.condensations[-1] if self.condensations else None
+
+    @property
+    def summary_event_index(self) -> int | None:
+        """Return the index of the summary event, or None if no summary exists."""
+        recent_condensation = self.most_recent_condensation
+        if (
+            recent_condensation is not None
+            and recent_condensation.summary is not None
+            and recent_condensation.summary_offset is not None
+        ):
+            return recent_condensation.summary_offset
+        return None
+
+    @property
+    def summary_event(self) -> CondensationSummaryEvent | None:
+        """Return the summary event, or None if no summary exists."""
+        if self.summary_event_index is not None:
+            event = self.events[self.summary_event_index]
+            if isinstance(event, CondensationSummaryEvent):
+                return event
+        return None
+
+    # To preserve list-like indexing, we ideally support slicing and position-based
+    # indexing. The only challenge with that is switching the return type based on the
+    # input type -- we can mark the different signatures for MyPy with `@overload`
+    # decorators.
+
+    @overload
+    def __getitem__(self, key: slice) -> list[LLMConvertibleEvent]: ...
+
+    @overload
+    def __getitem__(self, key: int) -> LLMConvertibleEvent: ...
+
+    def __getitem__(
+        self, key: int | slice
+    ) -> LLMConvertibleEvent | list[LLMConvertibleEvent]:
+        if isinstance(key, slice):
+            start, stop, step = key.indices(len(self))
+            return [self[i] for i in range(start, stop, step)]
+        elif isinstance(key, int):
+            return self.events[key]
+        else:
+            raise ValueError(f"Invalid key type: {type(key)}")
+
+    @staticmethod
+    def _build_action_batches(
+        events: Sequence[Event],
+    ) -> tuple[
+        dict[EventID, list[EventID]], dict[EventID, EventID], dict[EventID, ToolCallID]
+    ]:
+        """Build a map of llm_response_id -> list of ActionEvent IDs.
+
+        Returns:
+            A tuple of:
+            - batches: dict mapping llm_response_id to list of ActionEvent IDs
+            - action_id_to_response_id: dict mapping ActionEvent ID to llm_response_id
+            - action_id_to_tool_call_id: dict mapping ActionEvent ID to tool_call_id
+        """
+        batches: dict[EventID, list[EventID]] = {}
+        action_id_to_response_id: dict[EventID, EventID] = {}
+        action_id_to_tool_call_id: dict[EventID, ToolCallID] = {}
+
+        for event in events:
+            if isinstance(event, ActionEvent):
+                llm_response_id = event.llm_response_id
+                if llm_response_id not in batches:
+                    batches[llm_response_id] = []
+                batches[llm_response_id].append(event.id)
+                action_id_to_response_id[event.id] = llm_response_id
+                action_id_to_tool_call_id[event.id] = event.tool_call_id
+
+        return batches, action_id_to_response_id, action_id_to_tool_call_id
+
+    @staticmethod
+    def _enforce_batch_atomicity(
+        events: Sequence[Event],
+        removed_event_ids: set[EventID],
+    ) -> set[EventID]:
+        """Ensure that if any ActionEvent in a batch is removed, all ActionEvents
+        in that batch are removed.
+
+        This prevents partial batches from being sent to the LLM, which can cause
+        API errors when thinking blocks are separated from their tool calls.
+
+        Args:
+            events: The original list of events
+            removed_event_ids: Set of event IDs that are being removed
+
+        Returns:
+            Updated set of event IDs that should be removed (including all
+            ActionEvents in batches where any ActionEvent was removed)
+        """
+        batches, action_id_to_response_id, _ = View._build_action_batches(events)
+
+        if not batches:
+            return removed_event_ids
+
+        updated_removed_ids = set(removed_event_ids)
+
+        for llm_response_id, batch_event_ids in batches.items():
+            # Check if any ActionEvent in this batch is being removed
+            if any(event_id in removed_event_ids for event_id in batch_event_ids):
+                # If so, remove all ActionEvents in this batch
+                updated_removed_ids.update(batch_event_ids)
+                logger.debug(
+                    f"Enforcing batch atomicity: removing entire batch "
+                    f"with llm_response_id={llm_response_id} "
+                    f"({len(batch_event_ids)} events)"
+                )
+
+        return updated_removed_ids
+
+    @staticmethod
+    def filter_unmatched_tool_calls(
+        events: list[LLMConvertibleEvent],
+    ) -> list[LLMConvertibleEvent]:
+        """Filter out unmatched tool call events.
+
+        Removes ActionEvents and ObservationEvents that have tool_call_ids
+        but don't have matching pairs. Also enforces batch atomicity - if any
+        ActionEvent in a batch is filtered out, all ActionEvents in that batch
+        are also filtered out.
+        """
+        action_tool_call_ids = View._get_action_tool_call_ids(events)
+        observation_tool_call_ids = View._get_observation_tool_call_ids(events)
+
+        # Build batch info for batch atomicity enforcement
+        _, _, action_id_to_tool_call_id = View._build_action_batches(events)
+
+        # First pass: identify which events would NOT be kept based on matching
+        removed_event_ids: set[EventID] = set()
+        for event in events:
+            if not View._should_keep_event(
+                event, action_tool_call_ids, observation_tool_call_ids
+            ):
+                removed_event_ids.add(event.id)
+
+        # Second pass: enforce batch atomicity for ActionEvents
+        # If any ActionEvent in a batch is removed, all ActionEvents in that
+        # batch should also be removed
+        removed_event_ids = View._enforce_batch_atomicity(events, removed_event_ids)
+
+        # Third pass: also remove ObservationEvents whose ActionEvents were removed
+        # due to batch atomicity
+        tool_call_ids_to_remove: set[ToolCallID] = set()
+        for action_id in removed_event_ids:
+            if action_id in action_id_to_tool_call_id:
+                tool_call_ids_to_remove.add(action_id_to_tool_call_id[action_id])
+
+        # Filter out removed events
+        result = []
+        for event in events:
+            if event.id in removed_event_ids:
+                continue
+            if isinstance(event, ObservationBaseEvent):
+                if event.tool_call_id in tool_call_ids_to_remove:
+                    continue
+            result.append(event)
+
+        return result
+
+    @staticmethod
+    def _get_action_tool_call_ids(events: list[LLMConvertibleEvent]) -> set[ToolCallID]:
+        """Extract tool_call_ids from ActionEvents."""
+        tool_call_ids = set()
+        for event in events:
+            if isinstance(event, ActionEvent) and event.tool_call_id is not None:
+                tool_call_ids.add(event.tool_call_id)
+        return tool_call_ids
+
+    @staticmethod
+    def _get_observation_tool_call_ids(
+        events: list[LLMConvertibleEvent],
+    ) -> set[ToolCallID]:
+        """Extract tool_call_ids from ObservationEvents."""
+        tool_call_ids = set()
+        for event in events:
+            if (
+                isinstance(event, ObservationBaseEvent)
+                and event.tool_call_id is not None
+            ):
+                tool_call_ids.add(event.tool_call_id)
+        return tool_call_ids
+
+    @staticmethod
+    def _should_keep_event(
+        event: LLMConvertibleEvent,
+        action_tool_call_ids: set[ToolCallID],
+        observation_tool_call_ids: set[ToolCallID],
+    ) -> bool:
+        """Determine if an event should be kept based on tool call matching."""
+        if isinstance(event, ObservationBaseEvent):
+            return event.tool_call_id in action_tool_call_ids
+        elif isinstance(event, ActionEvent):
+            return event.tool_call_id in observation_tool_call_ids
+        else:
+            return True
+
+    @staticmethod
+    def from_events(events: Sequence[Event]) -> "View":
+        """Create a view from a list of events, respecting the semantics of any
+        condensation events.
+        """
+        forgotten_event_ids: set[EventID] = set()
+        condensations: list[Condensation] = []
+        for event in events:
+            if isinstance(event, Condensation):
+                condensations.append(event)
+                forgotten_event_ids.update(event.forgotten_event_ids)
+                # Make sure we also forget the condensation action itself
+                forgotten_event_ids.add(event.id)
+            if isinstance(event, CondensationRequest):
+                forgotten_event_ids.add(event.id)
+
+        # Enforce batch atomicity: if any event in a multi-action batch is forgotten,
+        # forget all events in that batch to prevent partial batches with thinking
+        # blocks separated from their tool calls
+        forgotten_event_ids = View._enforce_batch_atomicity(events, forgotten_event_ids)
+
+        kept_events = [
+            event
+            for event in events
+            if event.id not in forgotten_event_ids
+            and isinstance(event, LLMConvertibleEvent)
+        ]
+
+        # If we have a summary, insert it at the specified offset.
+        summary: str | None = None
+        summary_offset: int | None = None
+
+        # The relevant summary is always in the last condensation event (i.e., the most
+        # recent one).
+        for event in reversed(events):
+            if isinstance(event, Condensation):
+                if event.summary is not None and event.summary_offset is not None:
+                    summary = event.summary
+                    summary_offset = event.summary_offset
+                    break
+
+        if summary is not None and summary_offset is not None:
+            logger.debug(f"Inserting summary at offset {summary_offset}")
+
+            _new_summary_event = CondensationSummaryEvent(summary=summary)
+            kept_events.insert(summary_offset, _new_summary_event)
+
+        # Check for an unhandled condensation request -- these are events closer to the
+        # end of the list than any condensation action.
+        unhandled_condensation_request = False
+        for event in reversed(events):
+            if isinstance(event, Condensation):
+                break
+            if isinstance(event, CondensationRequest):
+                unhandled_condensation_request = True
+                break
+
+        return View(
+            events=View.filter_unmatched_tool_calls(kept_events),
+            unhandled_condensation_request=unhandled_condensation_request,
+            condensations=condensations,
+        )

openhands/sdk/conversation/__init__.py

@@ -0,0 +1,40 @@
+from openhands.sdk.conversation.base import BaseConversation
+from openhands.sdk.conversation.conversation import Conversation
+from openhands.sdk.conversation.event_store import EventLog
+from openhands.sdk.conversation.events_list_base import EventsListBase
+from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+from openhands.sdk.conversation.impl.remote_conversation import RemoteConversation
+from openhands.sdk.conversation.response_utils import get_agent_final_response
+from openhands.sdk.conversation.secret_registry import SecretRegistry
+from openhands.sdk.conversation.state import (
+    ConversationExecutionStatus,
+    ConversationState,
+)
+from openhands.sdk.conversation.stuck_detector import StuckDetector
+from openhands.sdk.conversation.types import (
+    ConversationCallbackType,
+    ConversationTokenCallbackType,
+)
+from openhands.sdk.conversation.visualizer import (
+    ConversationVisualizerBase,
+    DefaultConversationVisualizer,
+)
+
+
+__all__ = [
+    "Conversation",
+    "BaseConversation",
+    "ConversationState",
+    "ConversationExecutionStatus",
+    "ConversationCallbackType",
+    "ConversationTokenCallbackType",
+    "DefaultConversationVisualizer",
+    "ConversationVisualizerBase",
+    "SecretRegistry",
+    "StuckDetector",
+    "EventLog",
+    "LocalConversation",
+    "RemoteConversation",
+    "EventsListBase",
+    "get_agent_final_response",
+]

openhands/sdk/conversation/base.py

@@ -0,0 +1,281 @@
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, TypeVar, cast
+
+from openhands.sdk.conversation.conversation_stats import ConversationStats
+from openhands.sdk.conversation.events_list_base import EventsListBase
+from openhands.sdk.conversation.secret_registry import SecretValue
+from openhands.sdk.conversation.types import (
+    ConversationCallbackType,
+    ConversationID,
+    ConversationTokenCallbackType,
+)
+from openhands.sdk.llm.llm import LLM
+from openhands.sdk.llm.message import Message
+from openhands.sdk.observability.laminar import (
+    end_active_span,
+    should_enable_observability,
+    start_active_span,
+)
+from openhands.sdk.security.analyzer import SecurityAnalyzerBase
+from openhands.sdk.security.confirmation_policy import (
+    ConfirmationPolicyBase,
+    NeverConfirm,
+)
+from openhands.sdk.workspace.base import BaseWorkspace
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.agent.base import AgentBase
+    from openhands.sdk.conversation.state import ConversationExecutionStatus
+
+
+CallbackType = TypeVar(
+    "CallbackType",
+    ConversationCallbackType,
+    ConversationTokenCallbackType,
+)
+
+
+class ConversationStateProtocol(Protocol):
+    """Protocol defining the interface for conversation state objects."""
+
+    @property
+    def id(self) -> ConversationID:
+        """The conversation ID."""
+        ...
+
+    @property
+    def events(self) -> EventsListBase:
+        """Access to the events list."""
+        ...
+
+    @property
+    def execution_status(self) -> "ConversationExecutionStatus":
+        """The current conversation execution status."""
+        ...
+
+    @property
+    def confirmation_policy(self) -> ConfirmationPolicyBase:
+        """The confirmation policy."""
+        ...
+
+    @property
+    def security_analyzer(self) -> SecurityAnalyzerBase | None:
+        """The security analyzer."""
+        ...
+
+    @property
+    def activated_knowledge_skills(self) -> list[str]:
+        """List of activated knowledge skills."""
+        ...
+
+    @property
+    def workspace(self) -> BaseWorkspace:
+        """The workspace for agent operations and tool execution."""
+        ...
+
+    @property
+    def persistence_dir(self) -> str | None:
+        """The persistence directory from the FileStore.
+
+        If None, it means the conversation is not being persisted.
+        """
+        ...
+
+    @property
+    def agent(self) -> "AgentBase":
+        """The agent running in the conversation."""
+        ...
+
+    @property
+    def stats(self) -> ConversationStats:
+        """The conversation statistics."""
+        ...
+
+
+class BaseConversation(ABC):
+    """Abstract base class for conversation implementations.
+
+    This class defines the interface that all conversation implementations must follow.
+    Conversations manage the interaction between users and agents, handling message
+    exchange, execution control, and state management.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the base conversation with span tracking."""
+        self._span_ended = False
+
+    def _start_observability_span(self, session_id: str) -> None:
+        """Start an observability span if observability is enabled.
+
+        Args:
+            session_id: The session ID to associate with the span
+        """
+        if should_enable_observability():
+            start_active_span("conversation", session_id=session_id)
+
+    def _end_observability_span(self) -> None:
+        """End the observability span if it hasn't been ended already."""
+        if not self._span_ended and should_enable_observability():
+            end_active_span()
+            self._span_ended = True
+
+    @property
+    @abstractmethod
+    def id(self) -> ConversationID: ...
+
+    @property
+    @abstractmethod
+    def state(self) -> ConversationStateProtocol: ...
+
+    @property
+    @abstractmethod
+    def conversation_stats(self) -> ConversationStats: ...
+
+    @abstractmethod
+    def send_message(self, message: str | Message, sender: str | None = None) -> None:
+        """Send a message to the agent.
+
+        Args:
+            message: Either a string (which will be converted to a user message)
+                    or a Message object
+            sender: Optional identifier of the sender. Can be used to track
+                   message origin in multi-agent scenarios. For example, when
+                   one agent delegates to another, the sender can be set to
+                   identify which agent is sending the message.
+        """
+        ...
+
+    @abstractmethod
+    def run(self) -> None:
+        """Execute the agent to process messages and perform actions.
+
+        This method runs the agent until it finishes processing the current
+        message or reaches the maximum iteration limit.
+        """
+        ...
+
+    @abstractmethod
+    def set_confirmation_policy(self, policy: ConfirmationPolicyBase) -> None:
+        """Set the confirmation policy for the conversation."""
+        ...
+
+    @property
+    def confirmation_policy_active(self) -> bool:
+        return not isinstance(self.state.confirmation_policy, NeverConfirm)
+
+    @property
+    def is_confirmation_mode_active(self) -> bool:
+        """Check if confirmation mode is active.
+
+        Returns True if BOTH conditions are met:
+        1. The conversation state has a security analyzer set (not None)
+        2. The confirmation policy is active
+
+        """
+        return (
+            self.state.security_analyzer is not None and self.confirmation_policy_active
+        )
+
+    @abstractmethod
+    def reject_pending_actions(
+        self, reason: str = "User rejected the action"
+    ) -> None: ...
+
+    @abstractmethod
+    def pause(self) -> None: ...
+
+    @abstractmethod
+    def update_secrets(self, secrets: Mapping[str, SecretValue]) -> None: ...
+
+    @abstractmethod
+    def close(self) -> None: ...
+
+    @abstractmethod
+    def generate_title(self, llm: LLM | None = None, max_length: int = 50) -> str:
+        """Generate a title for the conversation based on the first user message.
+
+        Args:
+            llm: Optional LLM to use for title generation. If not provided,
+                 uses the agent's LLM.
+            max_length: Maximum length of the generated title.
+
+        Returns:
+            A generated title for the conversation.
+
+        Raises:
+            ValueError: If no user messages are found in the conversation.
+        """
+        ...
+
+    @staticmethod
+    def get_persistence_dir(
+        persistence_base_dir: str | Path, conversation_id: ConversationID
+    ) -> str:
+        """Get the persistence directory for the conversation.
+
+        Args:
+            persistence_base_dir: Base directory for persistence. Can be a string
+                path or Path object.
+            conversation_id: Unique conversation ID.
+
+        Returns:
+            String path to the conversation-specific persistence directory.
+            Always returns a normalized string path even if a Path was provided.
+        """
+        return str(Path(persistence_base_dir) / conversation_id.hex)
+
+    @abstractmethod
+    def ask_agent(self, question: str) -> str:
+        """Ask the agent a simple, stateless question and get a direct LLM response.
+
+        This bypasses the normal conversation flow and does **not** modify, persist,
+        or become part of the conversation state. The request is not remembered by
+        the main agent, no events are recorded, and execution status is untouched.
+        It is also thread-safe and may be called while `conversation.run()` is
+        executing in another thread.
+
+        Args:
+            question: A simple string question to ask the agent
+
+        Returns:
+            A string response from the agent
+        """
+        ...
+
+    @abstractmethod
+    def condense(self) -> None:
+        """Force condensation of the conversation history.
+
+        This method uses the existing condensation request pattern to trigger
+        condensation. It adds a CondensationRequest event to the conversation
+        and forces the agent to take a single step to process it.
+
+        The condensation will be applied immediately and will modify the conversation
+        state by adding a condensation event to the history.
+
+        Raises:
+            ValueError: If no condenser is configured or the condenser doesn't
+                       handle condensation requests.
+        """
+        ...
+
+    @staticmethod
+    def compose_callbacks(callbacks: Iterable[CallbackType]) -> CallbackType:
+        """Compose multiple callbacks into a single callback function.
+
+        Args:
+            callbacks: An iterable of callback functions
+
+        Returns:
+            A single callback function that calls all provided callbacks
+        """
+
+        def composed(event) -> None:
+            for cb in callbacks:
+                if cb:
+                    cb(event)
+
+        return cast(CallbackType, composed)