openhands-sdk 1.7.3__py3-none-any.whl

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)

openhands/sdk/conversation/conversation.py

@@ -0,0 +1,152 @@
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Self, overload
+
+from openhands.sdk.agent.base import AgentBase
+from openhands.sdk.conversation.base import BaseConversation
+from openhands.sdk.conversation.types import (
+    ConversationCallbackType,
+    ConversationID,
+    ConversationTokenCallbackType,
+    StuckDetectionThresholds,
+)
+from openhands.sdk.conversation.visualizer import (
+    ConversationVisualizerBase,
+    DefaultConversationVisualizer,
+)
+from openhands.sdk.hooks import HookConfig
+from openhands.sdk.logger import get_logger
+from openhands.sdk.secret import SecretValue
+from openhands.sdk.workspace import LocalWorkspace, RemoteWorkspace
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+    from openhands.sdk.conversation.impl.remote_conversation import RemoteConversation
+
+logger = get_logger(__name__)
+
+
+class Conversation:
+    """Factory class for creating conversation instances with OpenHands agents.
+
+    This factory automatically creates either a LocalConversation or RemoteConversation
+    based on the workspace type provided. LocalConversation runs the agent locally,
+    while RemoteConversation connects to a remote agent server.
+
+    Returns:
+        LocalConversation if workspace is local, RemoteConversation if workspace
+        is remote.
+
+    Example:
+        >>> from openhands.sdk import LLM, Agent, Conversation
+        >>> llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key"))
+        >>> agent = Agent(llm=llm, tools=[])
+        >>> conversation = Conversation(agent=agent, workspace="./workspace")
+        >>> conversation.send_message("Hello!")
+        >>> conversation.run()
+    """
+
+    @overload
+    def __new__(
+        cls: type[Self],
+        agent: AgentBase,
+        *,
+        workspace: str | Path | LocalWorkspace = "workspace/project",
+        persistence_dir: str | Path | None = None,
+        conversation_id: ConversationID | None = None,
+        callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
+        max_iteration_per_run: int = 500,
+        stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
+        visualizer: (
+            type[ConversationVisualizerBase] | ConversationVisualizerBase | None
+        ) = DefaultConversationVisualizer,
+        secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+    ) -> "LocalConversation": ...
+
+    @overload
+    def __new__(
+        cls: type[Self],
+        agent: AgentBase,
+        *,
+        workspace: RemoteWorkspace,
+        conversation_id: ConversationID | None = None,
+        callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
+        max_iteration_per_run: int = 500,
+        stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
+        visualizer: (
+            type[ConversationVisualizerBase] | ConversationVisualizerBase | None
+        ) = DefaultConversationVisualizer,
+        secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+    ) -> "RemoteConversation": ...
+
+    def __new__(
+        cls: type[Self],
+        agent: AgentBase,
+        *,
+        workspace: str | Path | LocalWorkspace | RemoteWorkspace = "workspace/project",
+        persistence_dir: str | Path | None = None,
+        conversation_id: ConversationID | None = None,
+        callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
+        max_iteration_per_run: int = 500,
+        stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
+        visualizer: (
+            type[ConversationVisualizerBase] | ConversationVisualizerBase | None
+        ) = DefaultConversationVisualizer,
+        secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+    ) -> BaseConversation:
+        from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+        from openhands.sdk.conversation.impl.remote_conversation import (
+            RemoteConversation,
+        )
+
+        if isinstance(workspace, RemoteWorkspace):
+            # For RemoteConversation, persistence_dir should not be used
+            # Only check if it was explicitly set to something other than the default
+            if persistence_dir is not None:
+                raise ValueError(
+                    "persistence_dir should not be set when using RemoteConversation"
+                )
+            return RemoteConversation(
+                agent=agent,
+                conversation_id=conversation_id,
+                callbacks=callbacks,
+                token_callbacks=token_callbacks,
+                hook_config=hook_config,
+                max_iteration_per_run=max_iteration_per_run,
+                stuck_detection=stuck_detection,
+                stuck_detection_thresholds=stuck_detection_thresholds,
+                visualizer=visualizer,
+                workspace=workspace,
+                secrets=secrets,
+            )
+
+        return LocalConversation(
+            agent=agent,
+            conversation_id=conversation_id,
+            callbacks=callbacks,
+            token_callbacks=token_callbacks,
+            hook_config=hook_config,
+            max_iteration_per_run=max_iteration_per_run,
+            stuck_detection=stuck_detection,
+            stuck_detection_thresholds=stuck_detection_thresholds,
+            visualizer=visualizer,
+            workspace=workspace,
+            persistence_dir=persistence_dir,
+            secrets=secrets,
+        )

openhands/sdk/conversation/conversation_stats.py

@@ -0,0 +1,85 @@
+from typing import Any
+
+from pydantic import BaseModel, Field, PrivateAttr, model_serializer
+
+from openhands.sdk.llm.llm_registry import RegistryEvent
+from openhands.sdk.llm.utils.metrics import Metrics
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class ConversationStats(BaseModel):
+    """Track per-LLM usage metrics observed during conversations."""
+
+    usage_to_metrics: dict[str, Metrics] = Field(
+        default_factory=dict,
+        description="Active usage metrics tracked by the registry.",
+    )
+
+    _restored_usage_ids: set[str] = PrivateAttr(default_factory=set)
+
+    @model_serializer(mode="wrap")
+    def _serialize_with_context(self, serializer: Any, info: Any) -> dict[str, Any]:
+        """Serialize metrics based on context.
+
+        By default, preserves full metrics history including costs,
+        response_latencies, and token_usages lists for persistence.
+
+        When context={'use_snapshot': True} is passed, converts Metrics to
+        MetricsSnapshot format to minimize payload size for network transmission.
+
+        Args:
+            serializer: Pydantic's default serializer
+            info: Serialization info containing context
+
+        Returns:
+            Dictionary with metrics serialized based on context
+        """
+        # Get the default serialization
+        data = serializer(self)
+
+        # Check if we should use snapshot serialization
+        context = info.context if info else None
+        use_snapshot = context.get("use_snapshot", False) if context else False
+
+        if use_snapshot and "usage_to_metrics" in data:
+            # Replace each Metrics with its snapshot
+            usage_to_snapshots = {}
+            for usage_id, metrics in self.usage_to_metrics.items():
+                snapshot = metrics.get_snapshot()
+                usage_to_snapshots[usage_id] = snapshot.model_dump()
+
+            data["usage_to_metrics"] = usage_to_snapshots
+
+        return data
+
+    def get_combined_metrics(self) -> Metrics:
+        total_metrics = Metrics()
+        for metrics in self.usage_to_metrics.values():
+            total_metrics.merge(metrics)
+        return total_metrics
+
+    def get_metrics_for_usage(self, usage_id: str) -> Metrics:
+        if usage_id not in self.usage_to_metrics:
+            raise Exception(f"LLM usage does not exist {usage_id}")
+
+        return self.usage_to_metrics[usage_id]
+
+    def register_llm(self, event: RegistryEvent):
+        # Listen for LLM creations and track their metrics
+        llm = event.llm
+        usage_id = llm.usage_id
+
+        # Usage costs exist but have not been restored yet
+        if (
+            usage_id in self.usage_to_metrics
+            and usage_id not in self._restored_usage_ids
+        ):
+            llm.restore_metrics(self.usage_to_metrics[usage_id])
+            self._restored_usage_ids.add(usage_id)
+
+        # Usage is new, track its metrics
+        if usage_id not in self.usage_to_metrics and llm.metrics:
+            self.usage_to_metrics[usage_id] = llm.metrics

openhands/sdk/conversation/event_store.py

@@ -0,0 +1,157 @@
+# state.py
+import operator
+from collections.abc import Iterator
+from typing import SupportsIndex, overload
+
+from openhands.sdk.conversation.events_list_base import EventsListBase
+from openhands.sdk.conversation.persistence_const import (
+    EVENT_FILE_PATTERN,
+    EVENT_NAME_RE,
+    EVENTS_DIR,
+)
+from openhands.sdk.event import Event, EventID
+from openhands.sdk.io import FileStore
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class EventLog(EventsListBase):
+    _fs: FileStore
+    _dir: str
+    _length: int
+
+    def __init__(self, fs: FileStore, dir_path: str = EVENTS_DIR) -> None:
+        self._fs = fs
+        self._dir = dir_path
+        self._id_to_idx: dict[EventID, int] = {}
+        self._idx_to_id: dict[int, EventID] = {}
+        self._length = self._scan_and_build_index()
+
+    def get_index(self, event_id: EventID) -> int:
+        """Return the integer index for a given event_id."""
+        try:
+            return self._id_to_idx[event_id]
+        except KeyError:
+            raise KeyError(f"Unknown event_id: {event_id}")
+
+    def get_id(self, idx: int) -> EventID:
+        """Return the event_id for a given index."""
+        if idx < 0:
+            idx += self._length
+        if idx < 0 or idx >= self._length:
+            raise IndexError("Event index out of range")
+        return self._idx_to_id[idx]
+
+    @overload
+    def __getitem__(self, idx: int) -> Event: ...
+
+    @overload
+    def __getitem__(self, idx: slice) -> list[Event]: ...
+
+    def __getitem__(self, idx: SupportsIndex | slice) -> Event | list[Event]:
+        if isinstance(idx, slice):
+            start, stop, step = idx.indices(self._length)
+            return [self._get_single_item(i) for i in range(start, stop, step)]
+        # idx is int-like (SupportsIndex)
+        return self._get_single_item(idx)
+
+    def _get_single_item(self, idx: SupportsIndex) -> Event:
+        i = operator.index(idx)
+        if i < 0:
+            i += self._length
+        if i < 0 or i >= self._length:
+            raise IndexError("Event index out of range")
+        txt = self._fs.read(self._path(i))
+        if not txt:
+            raise FileNotFoundError(f"Missing event file: {self._path(i)}")
+        return Event.model_validate_json(txt)
+
+    def __iter__(self) -> Iterator[Event]:
+        for i in range(self._length):
+            txt = self._fs.read(self._path(i))
+            if not txt:
+                continue
+            evt = Event.model_validate_json(txt)
+            evt_id = evt.id
+            # only backfill mapping if missing
+            if i not in self._idx_to_id:
+                self._idx_to_id[i] = evt_id
+                self._id_to_idx.setdefault(evt_id, i)
+            yield evt
+
+    def append(self, event: Event) -> None:
+        evt_id = event.id
+        # Check for duplicate ID
+        if evt_id in self._id_to_idx:
+            existing_idx = self._id_to_idx[evt_id]
+            raise ValueError(
+                f"Event with ID '{evt_id}' already exists at index {existing_idx}"
+            )
+
+        path = self._path(self._length, event_id=evt_id)
+        self._fs.write(path, event.model_dump_json(exclude_none=True))
+        self._idx_to_id[self._length] = evt_id
+        self._id_to_idx[evt_id] = self._length
+        self._length += 1
+
+    def __len__(self) -> int:
+        return self._length
+
+    def _path(self, idx: int, *, event_id: EventID | None = None) -> str:
+        return f"{self._dir}/{
+            EVENT_FILE_PATTERN.format(
+                idx=idx, event_id=event_id or self._idx_to_id[idx]
+            )
+        }"
+
+    def _scan_and_build_index(self) -> int:
+        try:
+            paths = self._fs.list(self._dir)
+        except Exception:
+            self._id_to_idx.clear()
+            self._idx_to_id.clear()
+            return 0
+
+        by_idx: dict[int, EventID] = {}
+        for p in paths:
+            name = p.rsplit("/", 1)[-1]
+            m = EVENT_NAME_RE.match(name)
+            if m:
+                idx = int(m.group("idx"))
+                evt_id = m.group("event_id")
+                by_idx[idx] = evt_id
+            else:
+                logger.warning(f"Unrecognized event file name: {name}")
+
+        if not by_idx:
+            self._id_to_idx.clear()
+            self._idx_to_id.clear()
+            return 0
+
+        n = 0
+        while True:
+            if n not in by_idx:
+                if any(i > n for i in by_idx.keys()):
+                    logger.warning(
+                        "Event index gap detected: "
+                        f"expect next index {n} but got {sorted(by_idx.keys())}"
+                    )
+                break
+            n += 1
+
+        self._id_to_idx.clear()
+        self._idx_to_id.clear()
+        for i in range(n):
+            evt_id = by_idx[i]
+            self._idx_to_id[i] = evt_id
+            if evt_id in self._id_to_idx:
+                logger.warning(
+                    f"Duplicate event ID '{evt_id}' found during scan. "
+                    f"Keeping first occurrence at index {self._id_to_idx[evt_id]}, "
+                    f"ignoring duplicate at index {i}"
+                )
+            else:
+                self._id_to_idx[evt_id] = i
+        return n

openhands/sdk/conversation/events_list_base.py

@@ -0,0 +1,17 @@
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from openhands.sdk.event import Event
+
+
+class EventsListBase(Sequence[Event], ABC):
+    """Abstract base class for event lists that can be appended to.
+
+    This provides a common interface for both local EventLog and remote
+    RemoteEventsList implementations, avoiding circular imports in protocols.
+    """
+
+    @abstractmethod
+    def append(self, event: Event) -> None:
+        """Add a new event to the list."""
+        ...