openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/llm/utils/verified_models.py

@@ -0,0 +1,65 @@
+VERIFIED_OPENAI_MODELS = [
+    "gpt-5.2",
+    "gpt-5.1",
+    "gpt-5.1-codex-max",
+    "gpt-5.1-codex",
+    "gpt-5.1-codex-mini",
+    "gpt-5-codex",
+    "gpt-5-2025-08-07",
+    "gpt-5-mini-2025-08-07",
+    "o4-mini",
+    "gpt-4o",
+    "gpt-4o-mini",
+    "gpt-4-32k",
+    "gpt-4.1",
+    "gpt-4.1-2025-04-14",
+    "o1-mini",
+    "o3",
+    "codex-mini-latest",
+]
+
+VERIFIED_ANTHROPIC_MODELS = [
+    "claude-sonnet-4-5-20250929",
+    "claude-haiku-4-5-20251001",
+    "claude-opus-4-5-20251101",
+    "claude-sonnet-4-20250514",
+    "claude-opus-4-20250514",
+    "claude-opus-4-1-20250805",
+    "claude-3-7-sonnet-20250219",
+    "claude-3-sonnet-20240229",
+    "claude-3-opus-20240229",
+    "claude-3-haiku-20240307",
+    "claude-3-5-haiku-20241022",
+    "claude-3-5-sonnet-20241022",
+    "claude-3-5-sonnet-20240620",
+]
+
+VERIFIED_MISTRAL_MODELS = [
+    "devstral-small-2505",
+    "devstral-small-2507",
+    "devstral-medium-2507",
+    "devstral-2512",
+    "devstral-medium-2512",
+]
+
+VERIFIED_OPENHANDS_MODELS = [
+    "claude-opus-4-5-20251101",
+    "claude-sonnet-4-5-20250929",
+    "gpt-5.2",
+    "gpt-5.1-codex-max",
+    "gpt-5.1-codex",
+    "gpt-5.1",
+    "gemini-3-pro-preview",
+    "deekseek-chat",
+    "kimi-k2-thinking",
+    "devstral-medium-2512",
+    "devstral-2512",
+]
+
+
+VERIFIED_MODELS = {
+    "openhands": VERIFIED_OPENHANDS_MODELS,
+    "anthropic": VERIFIED_ANTHROPIC_MODELS,
+    "openai": VERIFIED_OPENAI_MODELS,
+    "mistral": VERIFIED_MISTRAL_MODELS,
+}

openhands/sdk/logger/__init__.py

@@ -0,0 +1,22 @@
+from .logger import (
+    DEBUG,
+    ENV_JSON,
+    ENV_LOG_DIR,
+    ENV_LOG_LEVEL,
+    IN_CI,
+    get_logger,
+    setup_logging,
+)
+from .rolling import rolling_log_view
+
+
+__all__ = [
+    "get_logger",
+    "setup_logging",
+    "DEBUG",
+    "ENV_JSON",
+    "ENV_LOG_LEVEL",
+    "ENV_LOG_DIR",
+    "IN_CI",
+    "rolling_log_view",
+]

openhands/sdk/logger/logger.py

@@ -0,0 +1,195 @@
+# simple_logger.py
+"""
+Minimal logger setup that encourages per-module loggers,
+with Rich for humans and JSON for machines.
+
+Usage:
+    from openhands.sdk.logger import get_logger
+    logger = get_logger(__name__)
+    logger.info("Hello from this module!")
+"""
+
+import logging
+import os
+from logging.handlers import TimedRotatingFileHandler
+
+import litellm
+from pythonjsonlogger.json import JsonFormatter
+from rich.console import Console
+from rich.logging import RichHandler
+
+
+# ========= ENV (loaded at import) =========
+LEVEL_MAP = (
+    logging.getLevelNamesMapping()
+    if hasattr(logging, "getLevelNamesMapping")
+    else logging._nameToLevel
+)
+
+DEBUG = os.environ.get("DEBUG", "false").lower() in {"1", "true", "yes"}
+ENV_LOG_LEVEL_STR = os.getenv("LOG_LEVEL", "INFO").upper()
+ENV_LOG_LEVEL = LEVEL_MAP.get(ENV_LOG_LEVEL_STR, logging.INFO)
+if DEBUG:
+    ENV_LOG_LEVEL = logging.DEBUG
+
+ENV_LOG_TO_FILE = os.getenv("LOG_TO_FILE", "false").lower() in {"1", "true", "yes"}
+ENV_LOG_DIR = os.getenv("LOG_DIR", "logs")
+ENV_ROTATE_WHEN = os.getenv("LOG_ROTATE_WHEN", "midnight")
+ENV_BACKUP_COUNT = int(os.getenv("LOG_BACKUP_COUNT", "7"))
+
+# Rich vs JSON
+ENV_JSON = os.getenv("LOG_JSON", "false").lower() in {"1", "true", "yes"}
+IN_CI = os.getenv("CI", "false").lower() in {"1", "true", "yes"} or bool(
+    os.environ.get("GITHUB_ACTIONS")
+)
+ENV_RICH_TRACEBACKS = os.getenv("LOG_RICH_TRACEBACKS", "true").lower() in {
+    "1",
+    "true",
+    "yes",
+}
+
+
+ENV_AUTO_CONFIG = os.getenv("LOG_AUTO_CONFIG", "true").lower() in {"1", "true", "yes"}
+ENV_DEBUG_LLM = os.getenv("DEBUG_LLM", "false").lower() in {"1", "true", "yes"}
+
+
+# ========= LiteLLM controls =========
+_ENABLE_LITELLM_DEBUG = False
+if ENV_DEBUG_LLM:
+    confirmation = input(
+        "\n⚠️ WARNING: You are enabling DEBUG_LLM which may expose sensitive "
+        "information like API keys.\nThis should NEVER be enabled in production.\n"
+        "Type 'y' to confirm you understand the risks: "
+    )
+    if confirmation.lower() == "y":
+        _ENABLE_LITELLM_DEBUG = True
+        litellm.suppress_debug_info = False
+        litellm.set_verbose = True  # type: ignore
+    else:
+        print("DEBUG_LLM disabled due to lack of confirmation")
+        litellm.suppress_debug_info = True
+        litellm.set_verbose = False  # type: ignore
+else:
+    litellm.suppress_debug_info = True
+    litellm.set_verbose = False  # type: ignore
+
+
+def disable_logger(name: str, level: int = logging.CRITICAL) -> None:
+    """Disable or quiet down a specific logger by name."""
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    logger.propagate = False
+
+
+# Quiet chatty third-party loggers
+for name in ["litellm", "LiteLLM", "openai"]:
+    disable_logger(name, logging.DEBUG if _ENABLE_LITELLM_DEBUG else logging.ERROR)
+for name in ["httpcore", "httpx", "libtmux"]:
+    disable_logger(name, logging.WARNING)
+
+
+# ========= SETUP =========
+def setup_logging(
+    level: int | None = None,
+    log_to_file: bool | None = None,
+    log_dir: str | None = None,
+    fmt: str | None = None,
+    when: str | None = None,
+    backup_count: int | None = None,
+) -> None:
+    """Configure the root logger. All child loggers inherit this setup."""
+    lvl = ENV_LOG_LEVEL if level is None else level
+    to_file = ENV_LOG_TO_FILE if log_to_file is None else log_to_file
+    directory = ENV_LOG_DIR if log_dir is None else log_dir
+    rotate_when = ENV_ROTATE_WHEN if when is None else when
+    keep = ENV_BACKUP_COUNT if backup_count is None else backup_count
+
+    root = logging.getLogger()
+    old_level = root.level
+    root.setLevel(lvl)
+
+    # Set the level for any existing logger with the same intial level
+    for logger in logging.root.manager.loggerDict.values():
+        if isinstance(logger, logging.Logger) and logger.level == old_level:
+            logger.setLevel(lvl)
+
+    # Do NOT clear existing handlers; Uvicorn installs these before importing the app.
+    # Only add ours if there isn't already a comparable stream handler.
+    has_stream = any(isinstance(h, logging.StreamHandler) for h in root.handlers)
+
+    if not has_stream:
+        if ENV_JSON or IN_CI:
+            # JSON console handler
+            ch = logging.StreamHandler()
+            ch.setLevel(lvl)
+            ch.setFormatter(
+                JsonFormatter(
+                    fmt="%(asctime)s %(levelname)s %(name)s "
+                    "%(filename)s %(lineno)d %(message)s"
+                )
+            )
+            root.addHandler(ch)
+        else:
+            # Rich console handler
+            rich_handler = RichHandler(
+                console=Console(stderr=True),
+                omit_repeated_times=False,
+                rich_tracebacks=ENV_RICH_TRACEBACKS,
+            )
+            rich_handler.setFormatter(logging.Formatter("%(message)s"))
+            rich_handler.setLevel(lvl)
+            root.addHandler(rich_handler)
+
+    if to_file:
+        os.makedirs(directory, exist_ok=True)
+        fh = TimedRotatingFileHandler(
+            os.path.join(directory, "app.log"),
+            when=rotate_when,
+            backupCount=keep,
+            encoding="utf-8",
+        )
+        fh.setLevel(lvl)
+        if ENV_JSON:
+            fh.setFormatter(
+                JsonFormatter(
+                    fmt="%(asctime)s %(levelname)s %(name)s "
+                    "%(filename)s %(lineno)d %(message)s"
+                )
+            )
+        else:
+            log_fmt = (
+                fmt
+                or "%(asctime)s - %(levelname)s - %(name)s "
+                "- %(filename)s:%(lineno)d - %(message)s"
+            )
+            fh.setFormatter(logging.Formatter(log_fmt))
+        root.addHandler(fh)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger instance for the specified module.
+
+    This function returns a configured logger that inherits from the root logger
+    setup. The logger supports both Rich formatting for human-readable output
+    and JSON formatting for machine processing, depending on environment configuration.
+
+    Args:
+        name: The name of the module, typically __name__.
+
+    Returns:
+        A configured Logger instance.
+
+    Example:
+        >>> from openhands.sdk.logger import get_logger
+        >>> logger = get_logger(__name__)
+        >>> logger.info("This is an info message")
+        >>> logger.error("This is an error message")
+    """
+    logger = logging.getLogger(name)
+    logger.propagate = True
+    return logger
+
+
+# Auto-configure if desired
+if ENV_AUTO_CONFIG:
+    setup_logging()

openhands/sdk/logger/rolling.py

@@ -0,0 +1,113 @@
+# rolling_view.py
+import logging
+import sys
+from collections import deque
+from collections.abc import Callable
+from contextlib import contextmanager
+
+from rich.live import Live
+
+from .logger import ENV_JSON, IN_CI
+
+
+RenderFnType = Callable[[], str]
+
+
+class _RollingViewHandler(logging.Handler):
+    def __init__(self, max_lines: int, use_live: bool):
+        super().__init__()
+        self._buf: deque[str] = deque(maxlen=max_lines)
+        self._use_live: bool = use_live
+        self._live: Live | None = None  # set by rolling_log_view when Live is active
+        self.render_fn: RenderFnType | None = None
+
+    def emit(self, record: logging.LogRecord):
+        msg = self.format(record)
+        self._buf.append(msg)
+
+        if self._use_live and self._live:
+            # Live mode: repaint using either a custom render_fn or the buffer
+            self._live.update(
+                self.render_fn() if self.render_fn else "\n".join(self._buf)
+            )
+            return
+
+        # Non-live paths
+        if ENV_JSON:
+            # JSON mode: do nothing here; rely on other handlers via propagation
+            return
+
+        # CI / non-TTY plain pass-through (avoid double newlines)
+        sys.stdout.write(msg + "\n")
+        sys.stdout.flush()
+
+    @property
+    def snapshot(self) -> str:
+        return "\n".join(self._buf)
+
+
+@contextmanager
+def rolling_log_view(
+    logger: logging.Logger,
+    max_lines: int = 60,
+    level: int = logging.INFO,
+    propagate: bool = False,
+    header: str | None = None,
+    footer: str | None = None,
+    *,
+    json_flush_level: int
+    | None = None,  # optional: separate level for the final JSON flush
+):
+    """
+    Temporarily attach a rolling view handler that renders the last N log lines.
+
+    - Local TTY & not CI & not JSON: pretty, live-updating view (Rich.Live)
+    - CI / non-TTY: plain line-by-line (no terminal control)
+    - JSON mode: buffer only; on exit emit ONE large log record with the full snapshot.
+    """
+    is_tty = sys.stdout.isatty()
+    use_live = (not IN_CI) and is_tty and (not ENV_JSON)
+
+    handler = _RollingViewHandler(max_lines=max_lines, use_live=use_live)
+    handler.setLevel(level)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+
+    prev_propagate = logger.propagate
+    # Let other handlers (e.g., your JSON handler) run if needed
+    logger.propagate = bool(propagate or ENV_JSON)
+
+    logger.addHandler(handler)
+
+    def _render() -> str:
+        parts: list[str] = []
+        if header:
+            parts.append(header.rstrip())
+        parts.append("\n".join(handler._buf))
+        if footer:
+            parts.append(footer.rstrip())
+        return "\n".join(parts)
+
+    try:
+        if use_live:
+            with Live(_render(), refresh_per_second=8) as live:
+                handler._live = live
+                handler.render_fn = _render
+                yield handler
+        else:
+            yield handler
+    finally:
+        final_text = _render()
+
+        # Freeze final frame if Live was active
+        if handler._live:
+            handler._live.update(final_text)
+
+        # Detach our handler BEFORE flushing to avoid recursion
+        logger.removeHandler(handler)
+        logger.propagate = prev_propagate
+
+        # JSON mode: emit one big record at exit
+        if ENV_JSON:
+            logger.log(
+                json_flush_level if json_flush_level is not None else level, final_text
+            )

openhands/sdk/mcp/__init__.py

@@ -0,0 +1,24 @@
+"""MCP (Model Context Protocol) integration for agent-sdk."""
+
+from openhands.sdk.mcp.client import MCPClient
+from openhands.sdk.mcp.definition import MCPToolAction, MCPToolObservation
+from openhands.sdk.mcp.exceptions import MCPError, MCPTimeoutError
+from openhands.sdk.mcp.tool import (
+    MCPToolDefinition,
+    MCPToolExecutor,
+)
+from openhands.sdk.mcp.utils import (
+    create_mcp_tools,
+)
+
+
+__all__ = [
+    "MCPClient",
+    "MCPToolDefinition",
+    "MCPToolAction",
+    "MCPToolObservation",
+    "MCPToolExecutor",
+    "create_mcp_tools",
+    "MCPError",
+    "MCPTimeoutError",
+]

openhands/sdk/mcp/client.py

@@ -0,0 +1,76 @@
+"""Minimal sync helpers on top of fastmcp.Client, preserving original behavior."""
+
+import asyncio
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from fastmcp import Client as AsyncMCPClient
+
+from openhands.sdk.utils.async_executor import AsyncExecutor
+
+
+class MCPClient(AsyncMCPClient):
+    """
+    Behaves exactly like fastmcp.Client (same constructor & async API),
+    but owns a background event loop and offers:
+      - call_async_from_sync(awaitable_or_fn, *args, timeout=None, **kwargs)
+      - call_sync_from_async(fn, *args, **kwargs)  # await this from async code
+    """
+
+    _executor: AsyncExecutor
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._executor = AsyncExecutor()
+
+    def call_async_from_sync(
+        self,
+        awaitable_or_fn: Callable[..., Any] | Any,
+        *args,
+        timeout: float,
+        **kwargs,
+    ) -> Any:
+        """
+        Run a coroutine or async function on this client's loop from sync code.
+
+        Usage:
+            mcp.call_async_from_sync(async_fn, arg1, kw=...)
+            mcp.call_async_from_sync(coro)
+        """
+        return self._executor.run_async(
+            awaitable_or_fn, *args, timeout=timeout, **kwargs
+        )
+
+    async def call_sync_from_async(
+        self, fn: Callable[..., Any], *args, **kwargs
+    ) -> Any:
+        """
+        Await running a blocking function in the default threadpool from async code.
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, lambda: fn(*args, **kwargs))
+
+    def sync_close(self) -> None:
+        """
+        Synchronously close the MCP client and cleanup resources.
+
+        This will attempt to call the async close() method if available,
+        then shutdown the background event loop.
+        """
+        # Best-effort: try async close if parent provides it
+        if hasattr(self, "close") and inspect.iscoroutinefunction(self.close):
+            try:
+                self._executor.run_async(self.close, timeout=10.0)
+            except Exception:
+                pass  # Ignore close errors during cleanup
+
+        # Always cleanup the executor
+        self._executor.close()
+
+    def __del__(self):
+        """Cleanup on deletion."""
+        try:
+            self.sync_close()
+        except Exception:
+            pass  # Ignore cleanup errors during deletion

openhands/sdk/mcp/definition.py

@@ -0,0 +1,106 @@
+"""MCPTool definition and implementation."""
+
+import json
+from typing import Any
+
+import mcp.types
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.llm import ImageContent, TextContent
+from openhands.sdk.logger import get_logger
+from openhands.sdk.tool import (
+    Observation,
+)
+from openhands.sdk.tool.schema import Action
+from openhands.sdk.utils.visualize import display_json
+
+
+logger = get_logger(__name__)
+
+
+# NOTE: We don't define MCPToolAction because it
+# will be dynamically created from the MCP tool schema.
+
+
+class MCPToolAction(Action):
+    """Schema for MCP input action.
+
+    It is just a thin wrapper around raw JSON and does
+    not do any validation.
+
+    Validation will be performed by MCPTool.__call__
+    by constructing dynamically created Pydantic model
+    from the MCP tool input schema.
+    """
+
+    data: dict[str, Any] = Field(
+        default_factory=dict, description="Dynamic data fields from the tool call"
+    )
+
+    def to_mcp_arguments(self) -> dict:
+        """Return the data field as MCP tool call arguments.
+
+        This is used to convert this action to MCP tool call arguments.
+        The data field contains the dynamic fields from the tool call.
+        """
+        return self.data
+
+
+class MCPToolObservation(Observation):
+    """Observation from MCP tool execution."""
+
+    tool_name: str = Field(description="Name of the tool that was called")
+
+    @classmethod
+    def from_call_tool_result(
+        cls, tool_name: str, result: mcp.types.CallToolResult
+    ) -> "MCPToolObservation":
+        """Create an MCPToolObservation from a CallToolResult."""
+
+        native_content: list[mcp.types.ContentBlock] = result.content
+        content: list[TextContent | ImageContent] = [
+            TextContent(text=f"[Tool '{tool_name}' executed.]")
+        ]
+        for block in native_content:
+            if isinstance(block, mcp.types.TextContent):
+                content.append(TextContent(text=block.text))
+            elif isinstance(block, mcp.types.ImageContent):
+                content.append(
+                    ImageContent(
+                        image_urls=[f"data:{block.mimeType};base64,{block.data}"],
+                    )
+                )
+            else:
+                logger.warning(
+                    f"Unsupported MCP content block type: {type(block)}. Ignoring."
+                )
+
+        return cls(
+            content=content,
+            is_error=result.isError,
+            tool_name=tool_name,
+        )
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this observation."""
+        text = Text()
+
+        if self.is_error:
+            text.append("❌ ", style="red bold")
+            text.append(self.ERROR_MESSAGE_HEADER, style="bold red")
+
+        text.append(f"[MCP Tool '{self.tool_name}' Observation]\n", style="bold")
+        for block in self.content:
+            if isinstance(block, TextContent):
+                # try to see if block.text is a JSON
+                try:
+                    parsed = json.loads(block.text)
+                    text.append(display_json(parsed))
+                    continue
+                except (json.JSONDecodeError, TypeError):
+                    text.append(block.text + "\n")
+            elif isinstance(block, ImageContent):
+                text.append(f"[Image with {len(block.image_urls)} URLs]\n")
+        return text

openhands/sdk/mcp/exceptions.py

@@ -0,0 +1,19 @@
+"""MCP-related exceptions for OpenHands SDK."""
+
+
+class MCPError(Exception):
+    """Base exception for MCP-related errors."""
+
+    pass
+
+
+class MCPTimeoutError(MCPError):
+    """Exception raised when MCP operations timeout."""
+
+    timeout: float
+    config: dict | None
+
+    def __init__(self, message: str, timeout: float, config: dict | None = None):
+        self.timeout = timeout
+        self.config = config
+        super().__init__(message)