openhands-sdk 1.7.3__py3-none-any.whl → 1.8.0__py3-none-any.whl

openhands/sdk/llm/llm.py

@@ -28,8 +28,6 @@ from openhands.sdk.utils.pydantic_secrets import serialize_secret, validate_secr
 if TYPE_CHECKING:  # type hints only, avoid runtime import cycle
     from openhands.sdk.tool.tool import ToolDefinition
 
-from openhands.sdk.utils.pydantic_diff import pretty_pydantic_diff
-
 
 with warnings.catch_warnings():
     warnings.simplefilter("ignore")
@@ -139,7 +137,12 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     retry_min_wait: int = Field(default=8, ge=0)
     retry_max_wait: int = Field(default=64, ge=0)
 
-    timeout: int | None = Field(default=None, ge=0, description="HTTP timeout (s).")
+    timeout: int | None = Field(
+        default=300,
+        ge=0,
+        description="HTTP timeout in seconds. Default is 300s (5 minutes). "
+        "Set to None to disable timeout (not recommended for production).",
+    )
 
     max_message_chars: int = Field(
         default=30_000,
@@ -158,7 +161,6 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     top_p: float | None = Field(default=1.0, ge=0, le=1)
     top_k: float | None = Field(default=None, ge=0)
 
-    custom_llm_provider: str | None = Field(default=None)
     max_input_tokens: int | None = Field(
         default=None,
         ge=1,
@@ -323,26 +325,13 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         exclude=True,
     )
     _metrics: Metrics | None = PrivateAttr(default=None)
-    # ===== Plain class vars (NOT Fields) =====
-    # When serializing, these fields (SecretStr) will be dump to "****"
-    # When deserializing, these fields will be ignored and we will override
-    # them from the LLM instance provided at runtime.
-    OVERRIDE_ON_SERIALIZE: tuple[str, ...] = (
-        "api_key",
-        "aws_access_key_id",
-        "aws_secret_access_key",
-        # Dynamic runtime metadata for telemetry/routing that can differ across sessions
-        # and should not cause resume-time diffs. Always prefer the runtime value.
-        "litellm_extra_body",
-    )
-
     # Runtime-only private attrs
     _model_info: Any = PrivateAttr(default=None)
     _tokenizer: Any = PrivateAttr(default=None)
     _telemetry: Telemetry | None = PrivateAttr(default=None)
 
     model_config: ClassVar[ConfigDict] = ConfigDict(
-        extra="forbid", arbitrary_types_allowed=True
+        extra="ignore", arbitrary_types_allowed=True
     )
 
     # =========================================================================
@@ -499,9 +488,21 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         This is the method for getting responses from the model via Completion API.
         It handles message formatting, tool calling, and response processing.
 
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of tools available to the model
+            _return_metrics: Whether to return usage metrics
+            add_security_risk_prediction: Add security_risk field to tool schemas
+            on_token: Optional callback for streaming tokens
+            **kwargs: Additional arguments passed to the LLM API
+
         Returns:
             LLMResponse containing the model's response and metadata.
 
+        Note:
+            Summary field is always added to tool schemas for transparency and
+            explainability of agent actions.
+
         Raises:
             ValueError: If streaming is requested (not supported).
 
@@ -529,7 +530,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         if tools:
             cc_tools = [
                 t.to_openai_tool(
-                    add_security_risk_prediction=add_security_risk_prediction
+                    add_security_risk_prediction=add_security_risk_prediction,
                 )
                 for t in tools
             ]
@@ -551,18 +552,20 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         # Behavior-preserving: delegate to select_chat_options
         call_kwargs = select_chat_options(self, kwargs, has_tools=has_tools_flag)
 
-        # 4) optional request logging context (kept small)
+        # 4) request context for telemetry (always include context_window for metrics)
         assert self._telemetry is not None
-        log_ctx = None
+        # Always pass context_window so metrics are tracked even when logging disabled
+        telemetry_ctx: dict[str, Any] = {"context_window": self.max_input_tokens or 0}
         if self._telemetry.log_enabled:
-            log_ctx = {
-                "messages": formatted_messages[:],  # already simple dicts
-                "tools": tools,
-                "kwargs": {k: v for k, v in call_kwargs.items()},
-                "context_window": self.max_input_tokens or 0,
-            }
+            telemetry_ctx.update(
+                {
+                    "messages": formatted_messages[:],  # already simple dicts
+                    "tools": tools,
+                    "kwargs": {k: v for k, v in call_kwargs.items()},
+                }
+            )
             if tools and not use_native_fc:
-                log_ctx["raw_messages"] = original_fncall_msgs
+                telemetry_ctx["raw_messages"] = original_fncall_msgs
 
         # 5) do the call with retries
         @self.retry_decorator(
@@ -575,7 +578,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         )
         def _one_attempt(**retry_kwargs) -> ModelResponse:
             assert self._telemetry is not None
-            self._telemetry.on_request(log_ctx=log_ctx)
+            self._telemetry.on_request(telemetry_ctx=telemetry_ctx)
             # Merge retry-modified kwargs (like temperature) with call_kwargs
             final_kwargs = {**call_kwargs, **retry_kwargs}
             resp = self._transport_call(
@@ -646,6 +649,20 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         """Alternative invocation path using OpenAI Responses API via LiteLLM.
 
         Maps Message[] -> (instructions, input[]) and returns LLMResponse.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of tools available to the model
+            include: Optional list of fields to include in response
+            store: Whether to store the conversation
+            _return_metrics: Whether to return usage metrics
+            add_security_risk_prediction: Add security_risk field to tool schemas
+            on_token: Optional callback for streaming tokens (not yet supported)
+            **kwargs: Additional arguments passed to the API
+
+        Note:
+            Summary field is always added to tool schemas for transparency and
+            explainability of agent actions.
         """
         # Streaming not yet supported
         if kwargs.get("stream", False) or self.stream or on_token is not None:
@@ -659,7 +676,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         resp_tools = (
             [
                 t.to_responses_tool(
-                    add_security_risk_prediction=add_security_risk_prediction
+                    add_security_risk_prediction=add_security_risk_prediction,
                 )
                 for t in tools
             ]
@@ -672,17 +689,19 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
             self, kwargs, include=include, store=store
         )
 
-        # Optional request logging
+        # Request context for telemetry (always include context_window for metrics)
         assert self._telemetry is not None
-        log_ctx = None
+        # Always pass context_window so metrics are tracked even when logging disabled
+        telemetry_ctx: dict[str, Any] = {"context_window": self.max_input_tokens or 0}
         if self._telemetry.log_enabled:
-            log_ctx = {
-                "llm_path": "responses",
-                "input": input_items[:],
-                "tools": tools,
-                "kwargs": {k: v for k, v in call_kwargs.items()},
-                "context_window": self.max_input_tokens or 0,
-            }
+            telemetry_ctx.update(
+                {
+                    "llm_path": "responses",
+                    "input": input_items[:],
+                    "tools": tools,
+                    "kwargs": {k: v for k, v in call_kwargs.items()},
+                }
+            )
 
         # Perform call with retries
         @self.retry_decorator(
@@ -695,7 +714,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         )
         def _one_attempt(**retry_kwargs) -> ResponsesAPIResponse:
             assert self._telemetry is not None
-            self._telemetry.on_request(log_ctx=log_ctx)
+            self._telemetry.on_request(telemetry_ctx=telemetry_ctx)
             final_kwargs = {**call_kwargs, **retry_kwargs}
             with self._litellm_modify_params_ctx(self.modify_params):
                 with warnings.catch_warnings():
@@ -1102,39 +1121,3 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
             if v is not None:
                 data[field_name] = v
         return cls(**data)
-
-    def resolve_diff_from_deserialized(self, persisted: LLM) -> LLM:
-        """Resolve differences between a deserialized LLM and the current instance.
-
-        This is due to fields like api_key being serialized to "****" in dumps,
-        and we want to ensure that when loading from a file, we still use the
-        runtime-provided api_key in the self instance.
-
-        Return a new LLM instance equivalent to `persisted` but with
-        explicitly whitelisted fields (e.g. api_key) taken from `self`.
-        """
-        if persisted.__class__ is not self.__class__:
-            raise ValueError(
-                f"Cannot resolve_diff_from_deserialized between {self.__class__} "
-                f"and {persisted.__class__}"
-            )
-
-        # Copy allowed fields from runtime llm into the persisted llm
-        llm_updates = {}
-        persisted_dump = persisted.model_dump(context={"expose_secrets": True})
-        for field in self.OVERRIDE_ON_SERIALIZE:
-            if field in persisted_dump.keys():
-                llm_updates[field] = getattr(self, field)
-        if llm_updates:
-            reconciled = persisted.model_copy(update=llm_updates)
-        else:
-            reconciled = persisted
-
-        dump = self.model_dump(context={"expose_secrets": True})
-        reconciled_dump = reconciled.model_dump(context={"expose_secrets": True})
-        if dump != reconciled_dump:
-            raise ValueError(
-                "The LLM provided is different from the one in persisted state.\n"
-                f"Diff: {pretty_pydantic_diff(self, reconciled)}"
-            )
-        return reconciled

openhands/sdk/llm/options/chat_options.py

@@ -51,9 +51,12 @@ def select_chat_options(
     # Extended thinking models
     if get_features(llm.model).supports_extended_thinking:
         if llm.extended_thinking_budget:
+            # Anthropic throws errors if thinking budget equals or exceeds max output
+            # tokens -- force the thinking budget lower if there's a conflict
+            budget_tokens = min(llm.extended_thinking_budget, llm.max_output_tokens - 1)
             out["thinking"] = {
                 "type": "enabled",
-                "budget_tokens": llm.extended_thinking_budget,
+                "budget_tokens": budget_tokens,
             }
             # Enable interleaved thinking
             # Merge default header with any user-provided headers; user wins on conflict

openhands/sdk/llm/router/base.py

@@ -59,6 +59,18 @@ class RouterLLM(LLM):
         """
         This method intercepts completion calls and routes them to the appropriate
         underlying LLM based on the routing logic implemented in select_llm().
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of tools available to the model
+            return_metrics: Whether to return usage metrics
+            add_security_risk_prediction: Add security_risk field to tool schemas
+            on_token: Optional callback for streaming tokens
+            **kwargs: Additional arguments passed to the LLM API
+
+        Note:
+            Summary field is always added to tool schemas for transparency and
+            explainability of agent actions.
         """
         # Select appropriate LLM
         selected_model = self.select_llm(messages)

openhands/sdk/llm/utils/telemetry.py

@@ -73,9 +73,9 @@ class Telemetry(BaseModel):
         """
         self._stats_update_callback = callback
 
-    def on_request(self, log_ctx: dict | None) -> None:
+    def on_request(self, telemetry_ctx: dict | None) -> None:
         self._req_start = time.time()
-        self._req_ctx = log_ctx or {}
+        self._req_ctx = telemetry_ctx or {}
 
     def on_response(
         self,

openhands/sdk/llm/utils/verified_models.py

@@ -50,7 +50,7 @@ VERIFIED_OPENHANDS_MODELS = [
     "gpt-5.1-codex",
     "gpt-5.1",
     "gemini-3-pro-preview",
-    "deekseek-chat",
+    "deepseek-chat",
     "kimi-k2-thinking",
     "devstral-medium-2512",
     "devstral-2512",

openhands/sdk/mcp/tool.py

@@ -186,7 +186,9 @@ class MCPToolDefinition(ToolDefinition[MCPToolAction, MCPToolObservation]):
         # Use exclude_none to avoid injecting nulls back to the call
         # Exclude DiscriminatedUnionMixin fields (e.g., 'kind') as they're
         # internal to OpenHands and not part of the MCP tool schema
-        exclude_fields = set(DiscriminatedUnionMixin.model_fields.keys())
+        exclude_fields = set(DiscriminatedUnionMixin.model_fields.keys()) | set(
+            DiscriminatedUnionMixin.model_computed_fields.keys()
+        )
         sanitized = validated.model_dump(exclude_none=True, exclude=exclude_fields)
         return MCPToolAction(data=sanitized)
 

openhands/sdk/plugin/__init__.py

@@ -0,0 +1,22 @@
+"""Plugin module for OpenHands SDK.
+
+This module provides support for loading and managing plugins that bundle
+skills, hooks, MCP configurations, agents, and commands together.
+"""
+
+from openhands.sdk.plugin.plugin import Plugin
+from openhands.sdk.plugin.types import (
+    AgentDefinition,
+    CommandDefinition,
+    PluginAuthor,
+    PluginManifest,
+)
+
+
+__all__ = [
+    "Plugin",
+    "PluginManifest",
+    "PluginAuthor",
+    "AgentDefinition",
+    "CommandDefinition",
+]

openhands/sdk/plugin/plugin.py

@@ -0,0 +1,299 @@
+"""Plugin class for loading and managing plugins."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from openhands.sdk.context.skills import Skill
+from openhands.sdk.context.skills.utils import (
+    discover_skill_resources,
+    find_skill_md,
+    load_mcp_config,
+)
+from openhands.sdk.hooks import HookConfig
+from openhands.sdk.logger import get_logger
+from openhands.sdk.plugin.types import (
+    AgentDefinition,
+    CommandDefinition,
+    PluginAuthor,
+    PluginManifest,
+)
+
+
+logger = get_logger(__name__)
+
+# Directories to check for plugin manifest
+PLUGIN_MANIFEST_DIRS = [".plugin", ".claude-plugin"]
+PLUGIN_MANIFEST_FILE = "plugin.json"
+
+
+class Plugin(BaseModel):
+    """A plugin that bundles skills, hooks, MCP config, agents, and commands.
+
+    Plugins follow the Claude Code plugin structure for compatibility:
+
+    ```
+    plugin-name/
+    ├── .claude-plugin/           # or .plugin/
+    │   └── plugin.json          # Plugin metadata
+    ├── commands/                # Slash commands (optional)
+    ├── agents/                  # Specialized agents (optional)
+    ├── skills/                  # Agent Skills (optional)
+    ├── hooks/                   # Event handlers (optional)
+    │   └── hooks.json
+    ├── .mcp.json                # External tool configuration (optional)
+    └── README.md                # Plugin documentation
+    ```
+    """
+
+    manifest: PluginManifest = Field(description="Plugin manifest from plugin.json")
+    path: str = Field(description="Path to the plugin directory")
+    skills: list[Skill] = Field(
+        default_factory=list, description="Skills loaded from skills/ directory"
+    )
+    hooks: HookConfig | None = Field(
+        default=None, description="Hook configuration from hooks/hooks.json"
+    )
+    mcp_config: dict[str, Any] | None = Field(
+        default=None, description="MCP configuration from .mcp.json"
+    )
+    agents: list[AgentDefinition] = Field(
+        default_factory=list, description="Agent definitions from agents/ directory"
+    )
+    commands: list[CommandDefinition] = Field(
+        default_factory=list, description="Command definitions from commands/ directory"
+    )
+
+    @property
+    def name(self) -> str:
+        """Get the plugin name."""
+        return self.manifest.name
+
+    @property
+    def version(self) -> str:
+        """Get the plugin version."""
+        return self.manifest.version
+
+    @property
+    def description(self) -> str:
+        """Get the plugin description."""
+        return self.manifest.description
+
+    @classmethod
+    def load(cls, plugin_path: str | Path) -> Plugin:
+        """Load a plugin from a directory.
+
+        Args:
+            plugin_path: Path to the plugin directory.
+
+        Returns:
+            Loaded Plugin instance.
+
+        Raises:
+            FileNotFoundError: If the plugin directory doesn't exist.
+            ValueError: If the plugin manifest is invalid.
+        """
+        plugin_dir = Path(plugin_path).resolve()
+        if not plugin_dir.is_dir():
+            raise FileNotFoundError(f"Plugin directory not found: {plugin_dir}")
+
+        # Load manifest
+        manifest = _load_manifest(plugin_dir)
+
+        # Load skills
+        skills = _load_skills(plugin_dir)
+
+        # Load hooks
+        hooks = _load_hooks(plugin_dir)
+
+        # Load MCP config
+        mcp_config = _load_mcp_config(plugin_dir)
+
+        # Load agents
+        agents = _load_agents(plugin_dir)
+
+        # Load commands
+        commands = _load_commands(plugin_dir)
+
+        return cls(
+            manifest=manifest,
+            path=str(plugin_dir),
+            skills=skills,
+            hooks=hooks,
+            mcp_config=mcp_config,
+            agents=agents,
+            commands=commands,
+        )
+
+    @classmethod
+    def load_all(cls, plugins_dir: str | Path) -> list[Plugin]:
+        """Load all plugins from a directory.
+
+        Args:
+            plugins_dir: Path to directory containing plugin subdirectories.
+
+        Returns:
+            List of loaded Plugin instances.
+        """
+        plugins_path = Path(plugins_dir).resolve()
+        if not plugins_path.is_dir():
+            logger.warning(f"Plugins directory not found: {plugins_path}")
+            return []
+
+        plugins: list[Plugin] = []
+        for item in plugins_path.iterdir():
+            if item.is_dir():
+                try:
+                    plugin = cls.load(item)
+                    plugins.append(plugin)
+                    logger.debug(f"Loaded plugin: {plugin.name} from {item}")
+                except Exception as e:
+                    logger.warning(f"Failed to load plugin from {item}: {e}")
+
+        return plugins
+
+
+def _load_manifest(plugin_dir: Path) -> PluginManifest:
+    """Load plugin manifest from plugin.json.
+
+    Checks both .plugin/ and .claude-plugin/ directories.
+    Falls back to inferring from directory name if no manifest found.
+    """
+    manifest_path = None
+
+    # Check for manifest in standard locations
+    for manifest_dir in PLUGIN_MANIFEST_DIRS:
+        candidate = plugin_dir / manifest_dir / PLUGIN_MANIFEST_FILE
+        if candidate.exists():
+            manifest_path = candidate
+            break
+
+    if manifest_path:
+        try:
+            with open(manifest_path) as f:
+                data = json.load(f)
+
+            # Handle author field - can be string or object
+            if "author" in data and isinstance(data["author"], str):
+                data["author"] = PluginAuthor.from_string(data["author"]).model_dump()
+
+            return PluginManifest.model_validate(data)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {manifest_path}: {e}") from e
+        except Exception as e:
+            raise ValueError(f"Failed to parse manifest {manifest_path}: {e}") from e
+
+    # Fall back to inferring from directory name
+    logger.debug(f"No manifest found for {plugin_dir}, inferring from directory name")
+    return PluginManifest(
+        name=plugin_dir.name,
+        version="1.0.0",
+        description=f"Plugin loaded from {plugin_dir.name}",
+    )
+
+
+def _load_skills(plugin_dir: Path) -> list[Skill]:
+    """Load skills from the skills/ directory.
+
+    Note: Plugin skills are loaded with relaxed validation (strict=False)
+    to support Claude Code plugins which may use different naming conventions.
+    """
+    skills_dir = plugin_dir / "skills"
+    if not skills_dir.is_dir():
+        return []
+
+    skills: list[Skill] = []
+    for item in skills_dir.iterdir():
+        if item.is_dir():
+            skill_md = find_skill_md(item)
+            if skill_md:
+                try:
+                    skill = Skill.load(skill_md, skills_dir, strict=False)
+                    # Discover and attach resources
+                    skill.resources = discover_skill_resources(item)
+                    skills.append(skill)
+                    logger.debug(f"Loaded skill: {skill.name} from {skill_md}")
+                except Exception as e:
+                    logger.warning(f"Failed to load skill from {item}: {e}")
+        elif item.suffix == ".md" and item.name.lower() != "readme.md":
+            # Also support single .md files in skills/ directory
+            try:
+                skill = Skill.load(item, skills_dir, strict=False)
+                skills.append(skill)
+                logger.debug(f"Loaded skill: {skill.name} from {item}")
+            except Exception as e:
+                logger.warning(f"Failed to load skill from {item}: {e}")
+
+    return skills
+
+
+def _load_hooks(plugin_dir: Path) -> HookConfig | None:
+    """Load hooks configuration from hooks/hooks.json."""
+    hooks_json = plugin_dir / "hooks" / "hooks.json"
+    if not hooks_json.exists():
+        return None
+
+    try:
+        hook_config = HookConfig.load(path=hooks_json)
+        # load() returns empty config on error, check if it has hooks
+        if hook_config.hooks:
+            return hook_config
+        return None
+    except Exception as e:
+        logger.warning(f"Failed to load hooks from {hooks_json}: {e}")
+        return None
+
+
+def _load_mcp_config(plugin_dir: Path) -> dict[str, Any] | None:
+    """Load MCP configuration from .mcp.json."""
+    mcp_json = plugin_dir / ".mcp.json"
+    if not mcp_json.exists():
+        return None
+
+    try:
+        return load_mcp_config(mcp_json, skill_root=plugin_dir)
+    except Exception as e:
+        logger.warning(f"Failed to load MCP config from {mcp_json}: {e}")
+        return None
+
+
+def _load_agents(plugin_dir: Path) -> list[AgentDefinition]:
+    """Load agent definitions from the agents/ directory."""
+    agents_dir = plugin_dir / "agents"
+    if not agents_dir.is_dir():
+        return []
+
+    agents: list[AgentDefinition] = []
+    for item in agents_dir.iterdir():
+        if item.suffix == ".md" and item.name.lower() != "readme.md":
+            try:
+                agent = AgentDefinition.load(item)
+                agents.append(agent)
+                logger.debug(f"Loaded agent: {agent.name} from {item}")
+            except Exception as e:
+                logger.warning(f"Failed to load agent from {item}: {e}")
+
+    return agents
+
+
+def _load_commands(plugin_dir: Path) -> list[CommandDefinition]:
+    """Load command definitions from the commands/ directory."""
+    commands_dir = plugin_dir / "commands"
+    if not commands_dir.is_dir():
+        return []
+
+    commands: list[CommandDefinition] = []
+    for item in commands_dir.iterdir():
+        if item.suffix == ".md" and item.name.lower() != "readme.md":
+            try:
+                command = CommandDefinition.load(item)
+                commands.append(command)
+                logger.debug(f"Loaded command: {command.name} from {item}")
+            except Exception as e:
+                logger.warning(f"Failed to load command from {item}: {e}")
+
+    return commands