openhands-sdk 1.49.1__tar.gz → 1.49.2__tar.gz

{openhands_sdk-1.49.1 → openhands_sdk-1.49.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.49.1
+Version: 1.49.2
 Summary: OpenHands SDK - Core functionality for building AI agents
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk
@@ -10,7 +10,7 @@ Requires-Python: >=3.12
 Requires-Dist: agent-client-protocol<0.11.0,>=0.10.1
 Requires-Dist: deprecation>=2.1.0
 Requires-Dist: fakeredis[lua]>=2.32.1
-Requires-Dist: fastmcp>=3.2.0
+Requires-Dist: fastmcp<4,>=3.2.0
 Requires-Dist: filelock>=3.20.1
 Requires-Dist: httpx[socks]>=0.27.0
 Requires-Dist: jsonschema>=4.23.0

{openhands_sdk-1.49.1 → openhands_sdk-1.49.2}/openhands/sdk/conversation/impl/local_conversation.py

@@ -63,8 +63,6 @@ from openhands.sdk.marketplace.registry import MarketplaceRegistry
 from openhands.sdk.mcp.client import MCPClient
 from openhands.sdk.mcp.config import (
     MCPServer,
-    coerce_mcp_config,
-    dump_mcp_config,
     enabled_mcp_servers,
 )
 from openhands.sdk.mcp.tool import MCPToolDefinition
@@ -100,7 +98,7 @@ from openhands.sdk.skills import (
     merge_skills_by_name,
 )
 from openhands.sdk.skills.utils import (
-    expand_mcp_variables,
+    expand_mcp_servers,
     expand_variable_references,
 )
 from openhands.sdk.subagent import (
@@ -1205,16 +1203,13 @@ class LocalConversation(BaseConversation):
         # - Variables with defaults that don't have secrets fall back to their defaults
         # - This is the ONLY place where defaults are applied (plugin loading preserves
         #   placeholders with expand_defaults=False to avoid double-expansion)
+        # Agent Plugins servers are left literal (see expand_mcp_servers).
         if merged_mcp:
             # Pass the registry's lookup method as a callback - secrets are retrieved
             # lazily, one at a time, only when actually referenced in the config
-            expanded_mcp = expand_mcp_variables(
-                {"mcpServers": dump_mcp_config(merged_mcp)},
-                {},
-                get_secret=self._state.secret_registry.get_secret_value,
-                expand_defaults=True,
+            merged_mcp = expand_mcp_servers(
+                merged_mcp, self._state.secret_registry.get_secret_value
             )
-            merged_mcp = coerce_mcp_config(expanded_mcp["mcpServers"])
             logger.debug("Expanded MCP config variables")
 
         # Update agent with merged content only if something changed.
@@ -1447,25 +1442,13 @@ class LocalConversation(BaseConversation):
         get_secret = self._state.secret_registry.get_secret_value
         runtime_plugin_mcp: dict[str, MCPServer] = {}
         if plugin.mcp_config:
-            expanded_plugin_mcp = expand_mcp_variables(
-                {"mcpServers": dump_mcp_config(plugin.mcp_config)},
-                {},
-                get_secret=get_secret,
-                expand_defaults=True,
-            )
-            runtime_plugin_mcp = coerce_mcp_config(expanded_plugin_mcp["mcpServers"])
+            runtime_plugin_mcp = expand_mcp_servers(plugin.mcp_config, get_secret)
         merged_context = plugin.add_skills_to(self.agent.agent_context)
         merged_mcp = plugin.add_mcp_config_to(
             dict(self.agent.mcp_config) if self.agent.mcp_config else {}
         )
         if merged_mcp:
-            expanded_mcp = expand_mcp_variables(
-                {"mcpServers": dump_mcp_config(merged_mcp)},
-                {},
-                get_secret=get_secret,
-                expand_defaults=True,
-            )
-            merged_mcp = coerce_mcp_config(expanded_mcp["mcpServers"])
+            merged_mcp = expand_mcp_servers(merged_mcp, get_secret)
         runtime_mcp_tools = (
             self._runtime_mcp_tools(
                 runtime_plugin_mcp,

{openhands_sdk-1.49.1 → openhands_sdk-1.49.2}/openhands/sdk/mcp/config.py

@@ -14,6 +14,7 @@ from pydantic import (
     Field,
     GetCoreSchemaHandler,
     GetJsonSchemaHandler,
+    PrivateAttr,
     SecretStr,
     SerializationInfo,
     TypeAdapter,
@@ -520,6 +521,9 @@ class MCPServer(_MCPBaseModel):
             "ACP subprocess."
         ),
     )
+    # Never a field: data from outside must not be able to exempt a server from
+    # expansion. Only code sets it, via ``as_literal()``.
+    _literal_values: bool = PrivateAttr(default=False)
 
     @field_validator("env", "headers", mode="after")
     @classmethod
@@ -554,6 +558,20 @@ class MCPServer(_MCPBaseModel):
                 )
         return self
 
+    @property
+    def literal_values(self) -> bool:
+        """True if built by :meth:`as_literal`: never ``${VAR}``-expanded.
+
+        In memory only; input cannot set it and dumps do not write it.
+        """
+        return self._literal_values
+
+    def as_literal(self) -> MCPServer:
+        """Return a copy exempt from ``${VAR}`` expansion, for package servers."""
+        server = self.model_copy()
+        server._literal_values = True
+        return server
+
     @property
     def effective_transport(self) -> MCPTransport | None:
         return self.transport

{openhands_sdk-1.49.1 → openhands_sdk-1.49.2}/openhands/sdk/mcp/utils.py

@@ -6,12 +6,15 @@ import logging
 from collections.abc import Callable, Mapping, Sequence
 from typing import Protocol
 
+import httpx
 import mcp.types
 from fastmcp.client.auth import OAuth
 from fastmcp.client.logging import LogMessage
 from fastmcp.client.messages import MessageHandler
+from fastmcp.client.transports import StreamableHttpTransport
 from fastmcp.mcp_config import MCPConfig as FastMCPConfig, RemoteMCPServer
 from key_value.aio.protocols import AsyncKeyValue
+from mcp.shared._httpx_utils import create_mcp_http_client
 
 from openhands.sdk.logger import get_logger
 from openhands.sdk.mcp.client import MCPClient, ToolsReconciledCallback
@@ -114,6 +117,52 @@ def _oauth_auth_from_authentication_config(
     )
 
 
+class _PackageRemoteMCPServer(RemoteMCPServer):
+    """A package-declared remote server whose headers stay on its own origin.
+
+    Agent Plugins §7.2.1: configured headers must not follow a redirect to a
+    different origin. httpx strips only ``Authorization`` there, so this
+    server's HTTP client drops every configured header name from any request
+    that leaves the configured origin.
+    """
+
+    def to_transport(self):  # type: ignore[override]
+        transport = super().to_transport()
+        if isinstance(transport, StreamableHttpTransport) and self.headers:
+            transport.httpx_client_factory = _origin_bound_client_factory(
+                self.url, tuple(self.headers)
+            )
+        return transport
+
+
+def _origin_bound_client_factory(url: str, header_names: tuple[str, ...]):
+    origin = _origin(httpx.URL(url))
+
+    async def drop_headers_off_origin(request: httpx.Request) -> None:
+        # Request hooks run on every redirect hop, after httpx has copied the
+        # previous request's headers onto the next one.
+        if _origin(request.url) != origin:
+            for name in header_names:
+                request.headers.pop(name, None)
+
+    def factory(
+        headers: dict[str, str] | None = None,
+        timeout: httpx.Timeout | None = None,
+        auth: httpx.Auth | None = None,
+        **_: object,
+    ) -> httpx.AsyncClient:
+        client = create_mcp_http_client(headers=headers, timeout=timeout, auth=auth)
+        client.event_hooks = {"request": [drop_headers_off_origin], "response": []}
+        return client
+
+    return factory
+
+
+def _origin(url: httpx.URL) -> tuple[str, str, int | None]:
+    default_port = {"http": 80, "https": 443}.get(url.scheme)
+    return url.scheme, url.host, url.port or default_port
+
+
 def _prepare_mcp_config(
     mcp_config: dict[str, MCPServer],
     *,
@@ -123,6 +172,13 @@ def _prepare_mcp_config(
     """Validate MCP config and apply explicit OpenHands runtime auth metadata."""
     prepared = FastMCPConfig.model_validate(to_fastmcp_mcp_config(mcp_config))
 
+    for server_name, server_spec in mcp_config.items():
+        server = prepared.mcpServers.get(server_name)
+        if server_spec.literal_values and isinstance(server, RemoteMCPServer):
+            prepared.mcpServers[server_name] = _PackageRemoteMCPServer.model_validate(
+                server.model_dump()
+            )
+
     for server_name, server_spec in mcp_config.items():
         auth = server_spec.auth
         if not isinstance(auth, MCPOAuthAuthCredential):

{openhands_sdk-1.49.1 → openhands_sdk-1.49.2}/openhands/sdk/plugin/__init__.py

@@ -27,6 +27,7 @@ from openhands.sdk.plugin.format import (
     PluginFormat,
     detect_format,
 )
+from openhands.sdk.plugin.format.agent_plugins_mcp import get_plugin_data_dir
 from openhands.sdk.plugin.installed import (
     InstalledPluginInfo,
     disable_plugin,
@@ -92,6 +93,7 @@ __all__ = [
     "load_installed_plugins",
     "get_installed_plugins_dir",
     "get_installed_plugin",
+    "get_plugin_data_dir",
     "enable_plugin",
     "disable_plugin",
     "update_plugin",

{openhands_sdk-1.49.1 → openhands_sdk-1.49.2}/openhands/sdk/plugin/format/__init__.py

@@ -12,19 +12,16 @@ Module layout:
 - ``base`` — the abstract :class:`PluginFormat` contract plus the shared
   discovery logic (skills discovery, final assembly).
 - ``claude_code`` — the concrete :class:`ClaudeCodePluginFormat` strategy.
-- ``agent_plugins`` — the :class:`AgentPluginsFormat` strategy, not registered;
-  it also owns our ``dev.openhands`` client-extension namespace.
+- ``agent_plugins`` — the :class:`AgentPluginsFormat` strategy, which also owns
+  our ``dev.openhands`` client-extension namespace, and ``agent_plugins_mcp``,
+  its ``mcp.json`` loader.
 - this package ``__init__`` — the format registry (``_FORMATS``) and the
   :func:`detect_format` dispatcher.
 
 :func:`detect_format` returns the first format in ``_FORMATS`` whose
-:meth:`PluginFormat.detect` returns True. Claude Code is the only *registered*
-format today and its ``detect`` accepts any directory, so it is the universal
-fallback.
-
-:class:`AgentPluginsFormat` is held out of ``_FORMATS`` until its ``mcp.json``
-loader lands (#4405): registering it earlier would claim any directory with a
-root ``plugin.json`` and load it with zero MCP servers.
+:meth:`PluginFormat.detect` returns True. Agent Plugins goes first because it is
+specific — a root ``plugin.json`` — and Claude Code last because its ``detect``
+accepts any directory, making it the universal fallback.
 
 How to add a new plugin format
 ------------------------------
@@ -62,9 +59,7 @@ logger = get_logger(__name__)
 
 # Registered formats, in detection-precedence order. Higher-precedence formats
 # come first; the Claude Code format is last because it accepts any directory.
-# AgentPluginsFormat is intentionally absent until its mcp.json loader lands
-# (see the module docstring); it belongs ahead of ClaudeCodePluginFormat.
-_FORMATS: list[type[PluginFormat]] = [ClaudeCodePluginFormat]
+_FORMATS: list[type[PluginFormat]] = [AgentPluginsFormat, ClaudeCodePluginFormat]
 
 
 def detect_format(plugin_dir: Path) -> PluginFormat:

{openhands_sdk-1.49.1 → openhands_sdk-1.49.2}/openhands/sdk/plugin/format/agent_plugins.py

@@ -8,7 +8,6 @@ See the ``openhands.sdk.plugin.format`` package docstring for the design.
 """
 
 import json
-from functools import cache
 from pathlib import Path
 from typing import Any, ClassVar, Final
 
@@ -18,14 +17,20 @@ from jsonschema.exceptions import ValidationError as JSONSchemaValidationError
 from openhands.sdk.hooks import HookConfig
 from openhands.sdk.logger import get_logger
 from openhands.sdk.mcp.config import MCPServer
+from openhands.sdk.plugin.format.agent_plugins_mcp import (
+    get_plugin_data_dir,
+    load_mcp_servers,
+)
 from openhands.sdk.plugin.format.base import (
     PluginFormat,
+    _load_schema,
     _read_command_definitions,
     _read_hooks_config,
 )
 from openhands.sdk.plugin.types import CommandDefinition, PluginManifest
 from openhands.sdk.subagent.load import load_agents_from_dir
 from openhands.sdk.subagent.schema import AgentDefinition
+from openhands.sdk.utils.path import resolves_within
 
 
 logger = get_logger(__name__)
@@ -39,7 +44,6 @@ MANIFEST_FILE: Final[str] = "plugin.json"
 #: components (§8.2).
 EXTENSION_NAMESPACE: Final[str] = "dev.openhands"
 
-_SCHEMAS_DIR: Final[Path] = Path(__file__).parent / "schemas"
 
 #: The only manifest ``$schema`` we support, and its vendored file. Agent
 #: Plugins also publishes an ``mcp.schema.json``, but that one belongs to the
@@ -51,12 +55,6 @@ MANIFEST_SCHEMA_URL: Final[str] = (
 _MANIFEST_SCHEMA_FILE: Final[str] = "plugin-1.0.0.schema.json"
 
 
-@cache
-def _load_schema(filename: str) -> dict[str, Any]:
-    """Read a vendored schema. Cached; never fetched over the network."""
-    return json.loads((_SCHEMAS_DIR / filename).read_text(encoding="utf-8"))
-
-
 class AgentPluginsFormat(PluginFormat):
     """The Agent Plugins v1.0.0 portable package layout.
 
@@ -79,13 +77,17 @@ class AgentPluginsFormat(PluginFormat):
     moving those directories rather than rewriting them. Namespaces other than
     ours are ignored without validating their contents.
 
-    ``mcp.json`` is a follow-up under #4405, so its loader still returns empty.
-
-    Not registered in ``_FORMATS`` yet; see the package docstring.
+    Args:
+        plugin_data_root: Parent of the per-plugin ``PLUGIN_DATA`` directories.
+            Defaults to the user's plugin data directory; injectable for tests
+            and for callers that keep plugin state somewhere else.
     """
 
     name: ClassVar[str] = "agent-plugins"
 
+    def __init__(self, *, plugin_data_root: Path | None = None) -> None:
+        self._plugin_data_root = plugin_data_root
+
     @classmethod
     def detect(cls, plugin_dir: Path) -> bool:
         # Presence is the whole rule: a broken manifest (bad JSON, missing or
@@ -111,6 +113,10 @@ class AgentPluginsFormat(PluginFormat):
             ValueError: On any fatal manifest violation.
         """
         manifest_path = plugin_dir / MANIFEST_FILE
+        if not resolves_within(manifest_path, plugin_dir):
+            raise ValueError(
+                f"Manifest {manifest_path} resolves outside the plugin root"
+            )
         try:
             # utf-8-sig: tolerate a leading BOM, which RFC 8259 lets us ignore.
             data = json.loads(manifest_path.read_text(encoding="utf-8-sig"))
@@ -161,21 +167,35 @@ class AgentPluginsFormat(PluginFormat):
             data | _extension_manifest_fields(data, manifest_path)
         )
 
-    def load_mcp_config(self, plugin_dir: Path) -> dict[str, MCPServer]:  # noqa: ARG002
-        """Not read yet: root ``mcp.json`` is a follow-up."""
-        return {}
+    def load_mcp_config(self, plugin_dir: Path) -> dict[str, MCPServer]:
+        """Load MCP servers from the root ``mcp.json`` (no leading dot).
+
+        Unlike the Claude Code format, expansion is complete here: Agent Plugins
+        defines exactly two placeholders and forbids every other kind, so there
+        is nothing left to expand once per-conversation secrets arrive.
+        """
+        plugin_root = plugin_dir.resolve()
+        return load_mcp_servers(
+            plugin_dir,
+            plugin_root=plugin_root,
+            plugin_data=get_plugin_data_dir(
+                plugin_root, data_root=self._plugin_data_root
+            ),
+        )
 
     def load_hooks(self, plugin_dir: Path) -> HookConfig | None:
         """Load hooks from ``dev.openhands/hooks/hooks.json``."""
-        return _read_hooks_config(plugin_dir / EXTENSION_NAMESPACE)
+        return _read_hooks_config(plugin_dir / EXTENSION_NAMESPACE, plugin_dir)
 
     def load_agents(self, plugin_dir: Path) -> list[AgentDefinition]:
         """Load agent definitions from ``dev.openhands/agents/``."""
-        return load_agents_from_dir(plugin_dir / EXTENSION_NAMESPACE / "agents")
+        return load_agents_from_dir(
+            plugin_dir / EXTENSION_NAMESPACE / "agents", root=plugin_dir
+        )
 
     def load_commands(self, plugin_dir: Path) -> list[CommandDefinition]:
         """Load command definitions from ``dev.openhands/commands/``."""
-        return _read_command_definitions(plugin_dir / EXTENSION_NAMESPACE)
+        return _read_command_definitions(plugin_dir / EXTENSION_NAMESPACE, plugin_dir)
 
 
 def _extension_manifest_fields(