openhands-sdk 1.49.4__tar.gz → 1.49.5__tar.gz

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.49.4
+Version: 1.49.5
 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

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands/sdk/context/view/properties/tool_call_matching.py

@@ -64,8 +64,9 @@ class ToolCallMatchingProperty(ViewPropertyBase):
     ) -> ManipulationIndices:
         """Calculate manipulation indices for tool call matching.
 
-        This property is maintained by ensuring there are no manipulation indices
-        between action events and their paired observation event.
+        Indices between an action and its matching observation are protected.
+        Observation-like events without a pending action do not affect boundaries;
+        property enforcement separately removes orphaned and duplicate observations.
         """
         # Start with a complete set of manipulation indices, then we'll remove those
         # between actions and their paired observations.
@@ -84,13 +85,7 @@ class ToolCallMatchingProperty(ViewPropertyBase):
                 case ActionEvent():
                     pending_tool_call_ids.add(event.tool_call_id)
                 case ObservationBaseEvent():
-                    # Intentionally use remove(), not discard(): a second
-                    # observation-like event for the same tool_call_id means the
-                    # view has already violated the 1 action -> 1 result
-                    # invariant that downstream LLM APIs expect. That case must
-                    # be fixed by de-duplicating the view before serialization,
-                    # not by silently tolerating it here.
-                    pending_tool_call_ids.remove(event.tool_call_id)
+                    pending_tool_call_ids.discard(event.tool_call_id)
 
             if pending_tool_call_ids:
                 # The enumeration index corresponds to the position of the event, but we

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands/sdk/conversation/secret_registry.py

@@ -11,6 +11,7 @@ from pydantic import BaseModel, Field, PrivateAttr, SecretStr
 
 from openhands.sdk.logger import get_logger
 from openhands.sdk.secret import SecretSource, SecretValue, StaticSecret
+from openhands.sdk.utils.masking import PreserveDataUrls, SkipSecretMasking
 from openhands.sdk.utils.models import OpenHandsModel
 
 
@@ -20,8 +21,14 @@ logger = get_logger(__name__)
 FAILED_LOOKUP_RETRY_SECONDS: Final[float] = 60.0
 
 
-def _mask_value(value: Any, mask: Callable[[str], str]) -> Any:
-    """Recursively mask every ``str`` reachable from ``value``."""
+def _mask_value(
+    value: Any,
+    mask: Callable[[str], str],
+    *,
+    skip_secret_masking: bool = False,
+    preserve_data_urls: bool = False,
+) -> Any:
+    """Recursively mask strings, respecting opaque payload field metadata."""
     match value:
         case Enum():
             # A str-subclass enum is a str, but masking it would downgrade the
@@ -29,20 +36,56 @@ def _mask_value(value: Any, mask: Callable[[str], str]) -> Any:
             # vocabulary is fixed, so it can never hold a secret anyway.
             return value
         case str():
+            if skip_secret_masking:
+                return value
+            if preserve_data_urls and value.startswith("data:") and ";base64," in value:
+                return value
             return mask(value)
         case BaseModel():
             return _mask_model(value, mask)
         case list():
-            return [_mask_value(item, mask) for item in value]
+            return [
+                _mask_value(
+                    item,
+                    mask,
+                    skip_secret_masking=skip_secret_masking,
+                    preserve_data_urls=preserve_data_urls,
+                )
+                for item in value
+            ]
         case tuple():
-            items = [_mask_value(item, mask) for item in value]
+            items = [
+                _mask_value(
+                    item,
+                    mask,
+                    skip_secret_masking=skip_secret_masking,
+                    preserve_data_urls=preserve_data_urls,
+                )
+                for item in value
+            ]
             # Rebuild a NamedTuple through its own constructor; tuple(items)
             # would downgrade it the same way masking an Enum member does.
             return type(value)(*items) if hasattr(value, "_fields") else tuple(items)
         case set() | frozenset():
-            return type(value)(_mask_value(item, mask) for item in value)
+            return type(value)(
+                _mask_value(
+                    item,
+                    mask,
+                    skip_secret_masking=skip_secret_masking,
+                    preserve_data_urls=preserve_data_urls,
+                )
+                for item in value
+            )
         case dict():
-            return {key: _mask_value(item, mask) for key, item in value.items()}
+            return {
+                key: _mask_value(
+                    item,
+                    mask,
+                    skip_secret_masking=skip_secret_masking,
+                    preserve_data_urls=preserve_data_urls,
+                )
+                for key, item in value.items()
+            }
         case _:
             return value
 
@@ -53,10 +96,21 @@ def _mask_model[ModelT: BaseModel](model: ModelT, mask: Callable[[str], str]) ->
     ``model_copy`` is used rather than a validate round-trip so private
     attributes survive and no field is re-coerced.
     """
-    updates = {
-        name: _mask_value(getattr(model, name), mask)
-        for name in type(model).model_fields
-    }
+    updates = {}
+    for name, field in type(model).model_fields.items():
+        metadata = field.metadata
+        skip_secret_masking = any(
+            isinstance(item, SkipSecretMasking) for item in metadata
+        )
+        preserve_data_urls = any(
+            isinstance(item, PreserveDataUrls) for item in metadata
+        )
+        updates[name] = _mask_value(
+            getattr(model, name),
+            mask,
+            skip_secret_masking=skip_secret_masking,
+            preserve_data_urls=preserve_data_urls,
+        )
     return model.model_copy(update=updates)
 
 

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands/sdk/extensions/installation/metadata.py

@@ -150,7 +150,7 @@ class InstallationMetadata(BaseModel):
             return cls()
 
         try:
-            return cls.model_validate_json(metadata_path.read_text())
+            return cls.model_validate_json(metadata_path.read_text(encoding="utf-8"))
         except Exception as e:
             logger.warning(f"Failed to load installed extension metadata: {e}")
             return cls()
@@ -159,7 +159,7 @@ class InstallationMetadata(BaseModel):
         """Save metadata to the installed extensions directory."""
         metadata_path = self.get_metadata_path(installed_dir)
         metadata_path.parent.mkdir(parents=True, exist_ok=True)
-        metadata_path.write_text(self.model_dump_json(indent=2))
+        metadata_path.write_text(self.model_dump_json(indent=2), encoding="utf-8")
 
     def validate_tracked(self, installed_dir: Path) -> list[InstallationInfo]:
         """Validate tracked extensions exist on disk.

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands/sdk/llm/message.py

@@ -1,7 +1,7 @@
 import json
 from abc import abstractmethod
 from collections.abc import Sequence
-from typing import Any, ClassVar, Literal
+from typing import Annotated, Any, ClassVar, Literal
 
 from litellm import ChatCompletionMessageToolCall, ResponseFunctionToolCall
 from litellm.types.responses.main import (
@@ -16,6 +16,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 from openhands.sdk.logger import get_logger
 from openhands.sdk.utils import DEFAULT_TEXT_CONTENT_LIMIT, maybe_truncate
 from openhands.sdk.utils.deprecation import handle_deprecated_model_fields
+from openhands.sdk.utils.masking import PreserveDataUrls
 
 
 logger = get_logger(__name__)
@@ -203,7 +204,7 @@ class TextContent(BaseContent):
 
 class ImageContent(BaseContent):
     type: Literal["image"] = "image"
-    image_urls: list[str]
+    image_urls: Annotated[list[str], PreserveDataUrls()]
 
     def to_llm_dict(self) -> list[dict[str, str | dict[str, str]]]:
         """Convert to LLM API format."""

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands/sdk/llm/utils/model_features.py

@@ -109,6 +109,7 @@ def _normalized_supported_openai_params(model: str | None) -> frozenset[str]:
 
 
 REASONING_EFFORT_MODEL_OVERRIDES = {
+    "gpt-5.2-codex": "gpt-5.2-codex",
     "kimi-k3": "moonshot/kimi-k3",
 }
 
@@ -188,9 +189,15 @@ SUPPORTS_STOP_WORDS_FALSE_MODELS: list[str] = [
 ]
 
 # Models that should use the OpenAI Responses API path by default
+# NOTE: model_matches uses case-insensitive substring matching, so a bare family
+# token like "gpt-5" / "gpt-6" covers all variants (mini, sol, luna, astra, ...).
 RESPONSES_API_MODELS: list[str] = [
     # OpenAI GPT-5 family (includes mini variants)
     "gpt-5",
+    # OpenAI GPT-6 family (gpt-6-sol, gpt-6-luna, gpt-6-astra, ...). These reject
+    # function tools + reasoning_effort on /v1/chat/completions; /v1/responses
+    # supports both. See saas-deploy #1144.
+    "gpt-6",
     # OpenAI Codex (uses Responses API)
     "codex-mini-latest",
 ]

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands/sdk/llm/utils/telemetry.py

@@ -5,6 +5,7 @@ import traceback
 import uuid
 import warnings
 from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Any, ClassVar
 
 from litellm.cost_calculator import completion_cost as litellm_completion_cost
@@ -21,6 +22,109 @@ from openhands.sdk.logger import get_logger
 logger = get_logger(__name__)
 
 
+@dataclass(frozen=True, slots=True)
+class UsageSnapshot:
+    """Provider-independent view of one response's token accounting.
+
+    LiteLLM reports usage in two disjoint shapes that name the same quantities
+    differently: ``Usage`` (Chat Completions) uses ``prompt_tokens`` /
+    ``completion_tokens``, while ``ResponseAPIUsage`` (Responses API) uses
+    ``input_tokens`` / ``output_tokens``. Normalizing once, at the boundary,
+    keeps every consumer -- metrics, span attributes and completion logs -- on
+    a single vocabulary instead of rediscovering the aliases at each call site.
+    """
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    reasoning_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+    @property
+    def has_tokens(self) -> bool:
+        """Whether the provider reported any prompt or completion tokens."""
+        return self.prompt_tokens > 0 or self.completion_tokens > 0
+
+
+def normalize_usage(usage: Usage | ResponseAPIUsage | None) -> UsageSnapshot | None:
+    """Return a :class:`UsageSnapshot` for either provider usage shape.
+
+    ``None`` means "no token accounting": the provider reported no usage, or
+    reported a shape this module does not recognize. Unrecognized shapes are
+    ignored rather than guessed at, so adding a provider cannot silently feed
+    invented token counts into cost and cache accounting.
+    """
+    if isinstance(usage, Usage):
+        prompt_details = usage.prompt_tokens_details
+        completion_details = usage.completion_tokens_details
+        # ``cache_creation_tokens`` defaults to ``None``, so presence in
+        # ``model_fields_set`` is what distinguishes "provider reported a cache
+        # write" from "provider said nothing about cache writes".
+        cache_write = 0
+        if (
+            prompt_details is not None
+            and "cache_creation_tokens" in prompt_details.model_fields_set
+        ):
+            cache_write = int(prompt_details.cache_creation_tokens or 0)
+        return UsageSnapshot(
+            prompt_tokens=int(usage.prompt_tokens or 0),
+            completion_tokens=int(usage.completion_tokens or 0),
+            reasoning_tokens=(
+                int(completion_details.reasoning_tokens or 0)
+                if completion_details is not None
+                else 0
+            ),
+            cache_read_tokens=(
+                int(prompt_details.cached_tokens or 0)
+                if prompt_details is not None
+                else 0
+            ),
+            cache_write_tokens=cache_write,
+        )
+
+    if isinstance(usage, ResponseAPIUsage):
+        input_details = usage.input_tokens_details
+        output_details = usage.output_tokens_details
+        return UsageSnapshot(
+            prompt_tokens=int(usage.input_tokens or 0),
+            completion_tokens=int(usage.output_tokens or 0),
+            reasoning_tokens=(
+                int(output_details.reasoning_tokens or 0)
+                if output_details is not None
+                else 0
+            ),
+            cache_read_tokens=(
+                int(input_details.cached_tokens or 0)
+                if input_details is not None
+                else 0
+            ),
+        )
+
+    return None
+
+
+def _response_usage(
+    resp: ModelResponse | ResponsesAPIResponse,
+) -> Usage | ResponseAPIUsage | None:
+    """Return the usage object a response carries, if any.
+
+    ``ResponsesAPIResponse`` declares ``usage`` as a field. ``ModelResponse``
+    only accepts it as a constructor argument, so pydantic keeps it in the
+    model's extra mapping instead of its fields; reading that mapping is the
+    typed equivalent of probing for a possibly-absent attribute.
+    """
+    if isinstance(resp, ResponsesAPIResponse):
+        return resp.usage
+    if isinstance(resp, ModelResponse):
+        extra = resp.model_extra
+        if not extra:
+            return None
+        usage = extra.get("usage")
+        if isinstance(usage, (Usage, ResponseAPIUsage)):
+            return usage
+    return None
+
+
 class Telemetry(BaseModel):
     """
     Handles latency, token/cost accounting, and optional logging.
@@ -106,10 +210,10 @@ class Telemetry(BaseModel):
         if cost:
             self.metrics.add_cost(cost)
 
-        # 3) tokens - use typed usage field when available
-        usage = getattr(resp, "usage", None)
+        # 3) tokens - normalize the provider's usage shape exactly once
+        usage = normalize_usage(_response_usage(resp))
 
-        if usage and self._has_meaningful_usage(usage):
+        if usage is not None and usage.has_tokens:
             self._record_usage(
                 usage, response_id, self._req_ctx.get("context_window", 0)
             )
@@ -176,96 +280,20 @@ class Telemetry(BaseModel):
         return
 
     # ---------- Helpers ----------
-    def _has_meaningful_usage(self, usage: Usage | ResponseAPIUsage | None) -> bool:
-        """Check if usage has meaningful (non-zero) token counts.
-
-        Supports both Chat Completions Usage and Responses API Usage shapes.
-        """
-        if usage is None:
-            return False
-        try:
-            prompt_tokens = getattr(usage, "prompt_tokens", None)
-            if prompt_tokens is None:
-                prompt_tokens = getattr(usage, "input_tokens", 0)
-            completion_tokens = getattr(usage, "completion_tokens", None)
-            if completion_tokens is None:
-                completion_tokens = getattr(usage, "output_tokens", 0)
-
-            pt = int(prompt_tokens or 0)
-            ct = int(completion_tokens or 0)
-            return pt > 0 or ct > 0
-        except Exception:
-            return False
-
     def _record_usage(
-        self, usage: Usage | ResponseAPIUsage, response_id: str, context_window: int
+        self, usage: UsageSnapshot, response_id: str, context_window: int
     ) -> None:
-        """
-        Record token usage, supporting both Chat Completions Usage and
-        Responses API Usage.
-
-        Chat shape:
-          - prompt_tokens, completion_tokens
-          - prompt_tokens_details.cached_tokens
-          - completion_tokens_details.reasoning_tokens
-          - _cache_creation_input_tokens for cache_write
-        Responses shape:
-          - input_tokens, output_tokens
-          - input_tokens_details.cached_tokens
-          - output_tokens_details.reasoning_tokens
-        """
-        prompt_tokens = int(
-            getattr(usage, "prompt_tokens", None)
-            or getattr(usage, "input_tokens", 0)
-            or 0
-        )
-        completion_tokens = int(
-            getattr(usage, "completion_tokens", None)
-            or getattr(usage, "output_tokens", 0)
-            or 0
-        )
-
-        cache_read, cache_write = self._cache_buckets(usage)
-
-        reasoning_tokens = 0
-        c_details = getattr(usage, "completion_tokens_details", None) or getattr(
-            usage, "output_tokens_details", None
-        )
-        if c_details is not None:
-            reasoning_tokens = int(getattr(c_details, "reasoning_tokens", 0) or 0)
-
+        """Record an already-normalized usage snapshot into ``metrics``."""
         self.metrics.add_token_usage(
-            prompt_tokens=prompt_tokens,
-            completion_tokens=completion_tokens,
-            cache_read_tokens=cache_read,
-            cache_write_tokens=cache_write,
-            reasoning_tokens=reasoning_tokens,
+            prompt_tokens=usage.prompt_tokens,
+            completion_tokens=usage.completion_tokens,
+            cache_read_tokens=usage.cache_read_tokens,
+            cache_write_tokens=usage.cache_write_tokens,
+            reasoning_tokens=usage.reasoning_tokens,
             context_window=context_window,
             response_id=response_id,
         )
 
-    @staticmethod
-    def _cache_buckets(usage: Usage | ResponseAPIUsage) -> tuple[int, int]:
-        """Return ``(cache_read, cache_write)`` for either usage shape.
-
-        Single source of truth for both ``metrics`` and the span, so the trace
-        and the app's cost cannot disagree about the buckets.
-        """
-        if isinstance(usage, Usage):
-            details = usage.prompt_tokens_details
-            if details is None:
-                return 0, 0
-            cache_write = (
-                details.cache_creation_tokens
-                if "cache_creation_tokens" in details.model_fields_set
-                else 0
-            )
-            return int(details.cached_tokens or 0), int(cache_write or 0)
-
-        details = usage.input_tokens_details
-        cache_read = details.cached_tokens if details is not None else 0
-        return int(cache_read or 0), 0
-
     # ---------- Observability span ----------
     # These bracket one LLM call: ``on_request`` -> transport -> ``on_response``
     # all run inside a single retry attempt, so the span is current while
@@ -284,9 +312,7 @@ class Telemetry(BaseModel):
             logger.debug("Failed to open LLM span", exc_info=True)
             self._span = self._span_cm = None
 
-    def _annotate_span(
-        self, cost: float | None, usage: Usage | ResponseAPIUsage | None
-    ) -> None:
+    def _annotate_span(self, cost: float | None, usage: UsageSnapshot | None) -> None:
         span = self._span
         if span is None:
             return
@@ -297,13 +323,15 @@ class Telemetry(BaseModel):
                 # and priced by the real backend rather than by a name lookup.
                 span.set_attribute("gen_ai.usage.cost", float(cost))
             if usage is not None:
-                cache_read, cache_write = self._cache_buckets(usage)
                 # Emitted unconditionally: lmnr only reports these when
                 # prompt_tokens_details is populated, which not every provider
                 # shape does.
-                span.set_attribute("gen_ai.usage.cache_read_input_tokens", cache_read)
                 span.set_attribute(
-                    "gen_ai.usage.cache_creation_input_tokens", cache_write
+                    "gen_ai.usage.cache_read_input_tokens", usage.cache_read_tokens
+                )
+                span.set_attribute(
+                    "gen_ai.usage.cache_creation_input_tokens",
+                    usage.cache_write_tokens,
                 )
         except Exception:
             logger.debug("Failed to annotate LLM span", exc_info=True)
@@ -339,7 +367,7 @@ class Telemetry(BaseModel):
             extra_kwargs["custom_cost_per_token"] = cost_per_token
 
         try:
-            hidden = getattr(resp, "_hidden_params", {}) or {}
+            hidden = resp._hidden_params or {}
             cost = hidden.get("additional_headers", {}).get(
                 "llm_provider-x-litellm-response-cost"
             )
@@ -391,40 +419,13 @@ class Telemetry(BaseModel):
 
             # Usage summary (prompt, completion, reasoning tokens) for quick inspection
             try:
-                usage = getattr(resp, "usage", None)
-                if usage:
-                    prompt_tokens = int(
-                        getattr(usage, "prompt_tokens", None)
-                        or getattr(usage, "input_tokens", 0)
-                        or 0
-                    )
-                    completion_tokens = int(
-                        getattr(usage, "completion_tokens", None)
-                        or getattr(usage, "output_tokens", 0)
-                        or 0
-                    )
-                    details = getattr(
-                        usage, "completion_tokens_details", None
-                    ) or getattr(usage, "output_tokens_details", None)
-                    reasoning_tokens = (
-                        int(getattr(details, "reasoning_tokens", 0) or 0)
-                        if details
-                        else 0
-                    )
-                    p_details = getattr(
-                        usage, "prompt_tokens_details", None
-                    ) or getattr(usage, "input_tokens_details", None)
-                    cache_read_tokens = (
-                        int(getattr(p_details, "cached_tokens", 0) or 0)
-                        if p_details
-                        else 0
-                    )
-
+                usage = normalize_usage(_response_usage(resp))
+                if usage is not None:
                     data["usage_summary"] = {
-                        "prompt_tokens": prompt_tokens,
-                        "completion_tokens": completion_tokens,
-                        "reasoning_tokens": reasoning_tokens,
-                        "cache_read_tokens": cache_read_tokens,
+                        "prompt_tokens": usage.prompt_tokens,
+                        "completion_tokens": usage.completion_tokens,
+                        "reasoning_tokens": usage.reasoning_tokens,
+                        "cache_read_tokens": usage.cache_read_tokens,
                     }
             except Exception:
                 # Best-effort only; don't fail logging

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands/sdk/mcp/tool.py

@@ -15,7 +15,13 @@ if TYPE_CHECKING:
 import mcp.types
 from litellm import ChatCompletionToolParam
 from openai.types.responses import FunctionToolParam
-from pydantic import Field, ValidationError
+from pydantic import (
+    Field,
+    SerializerFunctionWrapHandler,
+    ValidationError,
+    field_serializer,
+    field_validator,
+)
 
 from openhands.sdk.llm import TextContent
 from openhands.sdk.logger import get_logger
@@ -42,6 +48,44 @@ logger = get_logger(__name__)
 # Default timeout for MCP tool execution in seconds
 MCP_TOOL_TIMEOUT_SECONDS = 300
 
+# mcp 2.x dumps its snake_case attribute names unless by_alias=True; mcp 1.x
+# only reads the camelCase wire names. Keys inside inputSchema/outputSchema
+# are user JSON Schema and must never be renamed.
+_MCP_TOOL_WIRE_KEYS: Final[dict[str, str]] = {
+    "input_schema": "inputSchema",
+    "output_schema": "outputSchema",
+    "meta": "_meta",
+}
+_MCP_NESTED_WIRE_KEYS: Final[dict[str, dict[str, str]]] = {
+    "annotations": {
+        "read_only_hint": "readOnlyHint",
+        "destructive_hint": "destructiveHint",
+        "idempotent_hint": "idempotentHint",
+        "open_world_hint": "openWorldHint",
+    },
+    "execution": {"task_support": "taskSupport"},
+    "icons": {"mime_type": "mimeType"},
+}
+
+
+def _mcp_tool_to_wire_keys(data: Any) -> Any:
+    """Normalize a serialized mcp.types.Tool to the MCP spec's camelCase keys."""
+    if not isinstance(data, dict):
+        return data
+    out = {_MCP_TOOL_WIRE_KEYS.get(k, k): v for k, v in data.items()}
+    for key, renames in _MCP_NESTED_WIRE_KEYS.items():
+        value = out.get(key)
+        if isinstance(value, dict):
+            out[key] = {renames.get(k, k): v for k, v in value.items()}
+        elif isinstance(value, list):
+            out[key] = [
+                {renames.get(k, k): v for k, v in item.items()}
+                if isinstance(item, dict)
+                else item
+                for item in value
+            ]
+    return out
+
 
 # NOTE: We don't define MCPToolAction because it
 # will be a pydantic BaseModel dynamically created from the MCP tool schema.
@@ -244,6 +288,20 @@ class MCPToolDefinition(ToolDefinition[MCPToolAction, MCPToolObservation]):
 
     mcp_tool: mcp.types.Tool = Field(description="The MCP tool definition.")
 
+    @field_validator("mcp_tool", mode="before")
+    @classmethod
+    def _read_either_mcp_spelling(cls, v: Any) -> Any:
+        return _mcp_tool_to_wire_keys(v)
+
+    @field_serializer("mcp_tool", mode="wrap")
+    def _write_mcp_wire_spelling(
+        self, v: mcp.types.Tool, handler: SerializerFunctionWrapHandler
+    ):
+        # Persisted events outlive the resolved mcp major; always write the
+        # spec's wire names so every mcp version can read them back. No return
+        # annotation, so the OpenAPI schema keeps referencing mcp.types.Tool.
+        return _mcp_tool_to_wire_keys(handler(v))
+
     @property
     def name(self) -> str:  # type: ignore[override]
         """Return the MCP tool name instead of the class name."""
@@ -333,7 +391,7 @@ class MCPToolDefinition(ToolDefinition[MCPToolAction, MCPToolObservation]):
         try:
             annotations = (
                 ToolAnnotations.model_validate(
-                    mcp_tool.annotations.model_dump(exclude_none=True)
+                    mcp_tool.annotations.model_dump(exclude_none=True, by_alias=True)
                 )
                 if mcp_tool.annotations
                 else None

openhands_sdk-1.49.5/openhands/sdk/utils/masking.py

@@ -0,0 +1,13 @@
+"""Field metadata used by secret masking."""
+
+
+class SkipSecretMasking:
+    """Mark a field whose value must not be secret-masked."""
+
+    __slots__ = ()
+
+
+class PreserveDataUrls:
+    """Mark string values that contain opaque base64 data URLs."""
+
+    __slots__ = ()

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.49.4
+Version: 1.49.5
 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

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/openhands_sdk.egg-info/SOURCES.txt

@@ -279,6 +279,7 @@ pyproject.toml
 ./openhands/sdk/utils/files.py
 ./openhands/sdk/utils/github.py
 ./openhands/sdk/utils/json.py
+./openhands/sdk/utils/masking.py
 ./openhands/sdk/utils/models.py
 ./openhands/sdk/utils/paging.py
 ./openhands/sdk/utils/path.py
@@ -576,6 +577,7 @@ openhands/sdk/utils/deprecation.py
 openhands/sdk/utils/files.py
 openhands/sdk/utils/github.py
 openhands/sdk/utils/json.py
+openhands/sdk/utils/masking.py
 openhands/sdk/utils/models.py
 openhands/sdk/utils/paging.py
 openhands/sdk/utils/path.py

{openhands_sdk-1.49.4 → openhands_sdk-1.49.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-sdk"
-version = "1.49.4"
+version = "1.49.5"
 description = "OpenHands SDK - Core functionality for building AI agents"
 
 requires-python = ">=3.12"