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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.49.4
+Version: 1.49.6
 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.6}/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.6}/openhands/sdk/conversation/impl/local_conversation.py

@@ -55,6 +55,7 @@ from openhands.sdk.hooks import HookConfig, HookEventProcessor, create_hook_call
 from openhands.sdk.io import FileStore, LocalFileStore
 from openhands.sdk.llm import LLM, Message, TextContent, content_to_str
 from openhands.sdk.llm.auth.openai import create_subscription_llm_from_config
+from openhands.sdk.llm.exceptions import LLMAuthenticationError
 from openhands.sdk.llm.llm import LLMCallContext
 from openhands.sdk.llm.llm_profile_store import LLMProfileStore
 from openhands.sdk.llm.llm_registry import LLMRegistry
@@ -2040,6 +2041,21 @@ class LocalConversation(BaseConversation):
                             )
                         )
                         break
+        except LLMAuthenticationError as e:
+            with self._state:
+                self._state.execution_status = ConversationExecutionStatus.ERROR
+                self._on_event(
+                    ConversationErrorEvent(
+                        source="environment",
+                        code="LLMAuthenticationError",
+                        detail=(
+                            "Your LLM API key appears to be invalid or has expired."
+                        ),
+                    )
+                )
+            raise ConversationRunError(
+                self._state.id, e, persistence_dir=self._state.persistence_dir
+            ) from e
         except Exception as e:
             with self._state:
                 self._state.execution_status = ConversationExecutionStatus.ERROR
@@ -2540,6 +2556,21 @@ class LocalConversation(BaseConversation):
 
                 self._state.execution_status = ConversationExecutionStatus.PAUSED
                 self._on_event(InterruptEvent())
+        except LLMAuthenticationError as e:
+            with self._state:
+                self._state.execution_status = ConversationExecutionStatus.ERROR
+                self._on_event(
+                    ConversationErrorEvent(
+                        source="environment",
+                        code="LLMAuthenticationError",
+                        detail=(
+                            "Your LLM API key appears to be invalid or has expired."
+                        ),
+                    )
+                )
+            raise ConversationRunError(
+                self._state.id, e, persistence_dir=self._state.persistence_dir
+            ) from e
         except Exception as e:
             with self._state:
                 updated_agent_state = dict(self._state.agent_state)

{openhands_sdk-1.49.4 → openhands_sdk-1.49.6}/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.6}/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.6}/openhands/sdk/hooks/executor.py

@@ -566,9 +566,10 @@ class HookExecutor:
                 try:
                     output_data = json.loads(result.stdout)
                     if isinstance(output_data, dict):
-                        # Parse decision
-                        if "decision" in output_data:
-                            decision_str = output_data["decision"].lower()
+                        # Non-string values represent no decision.
+                        decision_value = output_data.get("decision")
+                        if isinstance(decision_value, str):
+                            decision_str = decision_value.lower()
                             if decision_str == "allow":
                                 hook_result.decision = HookDecision.ALLOW
                             elif decision_str == "deny":

{openhands_sdk-1.49.4 → openhands_sdk-1.49.6}/openhands/sdk/llm/__init__.py

@@ -28,6 +28,12 @@ from openhands.sdk.llm.message import (
     ThinkingBlock,
     content_to_str,
 )
+from openhands.sdk.llm.meta_profile_store import (
+    MetaProfile,
+    MetaProfileClass,
+    MetaProfileLimitExceeded,
+    MetaProfileStore,
+)
 from openhands.sdk.llm.router import RouterLLM
 from openhands.sdk.llm.streaming import (
     AsyncTokenCallbackType,
@@ -61,6 +67,10 @@ __all__ = [
     "LLMProfileLoader",
     "LLMProfileMutator",
     "LLMProfileStore",
+    "MetaProfile",
+    "MetaProfileClass",
+    "MetaProfileLimitExceeded",
+    "MetaProfileStore",
     "RouterLLM",
     "RegistryEvent",
     # Messages

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

@@ -96,6 +96,7 @@ from openhands.sdk.llm.exceptions import (
     LLMNoResponseError,
     is_prompt_cache_too_small,
     is_quota_exhaustion_error,
+    looks_like_auth_error,
     map_provider_exception,
 )
 
@@ -661,6 +662,19 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     # a result, so the read/check and store are kept atomic. ClassVar (shared);
     # critical sections are tiny and never cover network I/O.
     _runtime_metadata_lock: ClassVar[threading.Lock] = threading.Lock()
+    # Optional callback that returns a freshly-resolved API key. When set, an
+    # authentication failure (HTTP 401, e.g. a rotated/healed managed proxy key
+    # that LiteLLM reports as ``token_not_found_in_db``) triggers a single
+    # re-resolve of the key followed by one retry of the call. This is a
+    # near-term mitigation for stale credentials reaching a sandbox runtime
+    # agent; the durable fix is reference-only credential delivery (#4288).
+    # Held as a PrivateAttr so it is never serialized into conversation state.
+    _api_key_refresh_hook: Callable[[], str | SecretStr | None] | None = PrivateAttr(
+        default=None
+    )
+    # Recursion guard: set on the refreshed copy so a still-failing key does not
+    # loop. One refresh + one retry per call chain.
+    _auth_refresh_attempted: bool = PrivateAttr(default=False)
     model_config: ClassVar[ConfigDict] = ConfigDict(
         extra="ignore", arbitrary_types_allowed=True
     )
@@ -1011,6 +1025,72 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
             raise mapped from error
         raise
 
+    # =========================================================================
+    # Authentication refresh (refresh-on-401)
+    # =========================================================================
+    def set_api_key_refresh_hook(
+        self, hook: Callable[[], str | SecretStr | None] | None
+    ) -> None:
+        """Register a callback that re-resolves this LLM's API key on a 401.
+
+        When a completion/responses call fails with an authentication error,
+        the hook is invoked once to obtain a fresh key; if it returns a new
+        value the call is retried a single time with that key. This mitigates
+        stale managed/proxy credentials reaching a sandbox runtime agent (e.g.
+        after a server-side managed-key rotation or heal), where the first call
+        would otherwise fail with ``401 token_not_found_in_db``.
+
+        The hook must be non-blocking / cheap; on the async paths it is invoked
+        in a worker thread. It is stored as a private attribute and is never
+        serialized into conversation state.
+        """
+        self._api_key_refresh_hook = hook
+
+    def _resolve_refreshed_api_key(self, error: Exception) -> SecretStr | None:
+        """Return a fresh API key to retry with, or ``None`` to skip refresh.
+
+        Returns ``None`` unless every condition holds: the error looks like an
+        authentication failure, a refresh hook is configured, no refresh has
+        already been attempted in this call chain, this LLM uses ``api_key``
+        auth, and the hook yields a key that differs from the current one.
+        """
+        if self._auth_refresh_attempted:
+            return None
+        if self._api_key_refresh_hook is None:
+            return None
+        if self.auth_type != "api_key":
+            return None
+        if not looks_like_auth_error(error):
+            return None
+        try:
+            new_key = self._api_key_refresh_hook()
+        except Exception:
+            # A flaky hook must not mask the original authentication error;
+            # log and skip the refresh so the caller sees the real 401.
+            logger.warning(
+                "API key refresh hook raised; skipping refresh and "
+                "surfacing the original authentication error.",
+                exc_info=True,
+            )
+            return None
+        if new_key is None:
+            return None
+        new_secret = new_key if isinstance(new_key, SecretStr) else SecretStr(new_key)
+        if not new_secret.get_secret_value():
+            return None
+        current = self._get_api_key_value()
+        if current is not None and current == new_secret.get_secret_value():
+            # A refresh that returns the same (still-rejected) key is useless;
+            # skip the retry and surface the original error.
+            return None
+        return new_secret
+
+    def _auth_refreshed_llm(self, new_api_key: SecretStr) -> LLM:
+        """Copy this LLM with a refreshed key and the recursion guard set."""
+        refreshed = self.model_copy(update={"api_key": new_api_key})
+        refreshed._auth_refresh_attempted = True
+        return refreshed
+
     # =========================================================================
     # Shared helpers for completion / acompletion / responses / aresponses
     # =========================================================================
@@ -1668,6 +1748,21 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
                     on_token=on_token,
                     **_caller_kwargs,
                 )
+            # If the credential was rejected (401) and a refresh hook can supply
+            # a fresh key, re-resolve it and retry the call exactly once.
+            refreshed_key = self._resolve_refreshed_api_key(e)
+            if refreshed_key is not None:
+                logger.warning(
+                    "Authentication error; refreshing API key and retrying once."
+                )
+                return self._auth_refreshed_llm(refreshed_key).completion(
+                    messages,
+                    tools,
+                    add_security_risk_prediction=add_security_risk_prediction,
+                    on_token=on_token,
+                    call_context=call_context,
+                    **_caller_kwargs,
+                )
             return self._handle_error(
                 e,
                 lambda fb: fb.completion(
@@ -1772,6 +1867,24 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
                     on_token=on_token,
                     **_caller_kwargs,
                 )
+            # If the credential was rejected (401) and a refresh hook can supply
+            # a fresh key, re-resolve it (off the event loop) and retry once.
+            loop = asyncio.get_running_loop()
+            refreshed_key = await loop.run_in_executor(
+                None, self._resolve_refreshed_api_key, e
+            )
+            if refreshed_key is not None:
+                logger.warning(
+                    "Authentication error; refreshing API key and retrying once."
+                )
+                return await self._auth_refreshed_llm(refreshed_key).acompletion(
+                    messages,
+                    tools,
+                    add_security_risk_prediction=add_security_risk_prediction,
+                    on_token=on_token,
+                    call_context=call_context,
+                    **_caller_kwargs,
+                )
             # Fallback is synchronous; cast the token callback since the
             # fallback LLM's sync path accepts TokenCallbackType.
             _fb_token = cast("TokenCallbackType | None", on_token)
@@ -1938,6 +2051,23 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
                     on_token=on_token,
                     **_caller_kwargs,
                 )
+            # If the credential was rejected (401) and a refresh hook can supply
+            # a fresh key, re-resolve it and retry the call exactly once.
+            refreshed_key = self._resolve_refreshed_api_key(e)
+            if refreshed_key is not None:
+                logger.warning(
+                    "Authentication error; refreshing API key and retrying once."
+                )
+                return self._auth_refreshed_llm(refreshed_key).responses(
+                    messages,
+                    tools,
+                    include,
+                    store,
+                    add_security_risk_prediction=add_security_risk_prediction,
+                    on_token=on_token,
+                    call_context=call_context,
+                    **_caller_kwargs,
+                )
             return self._handle_error(
                 e,
                 lambda fb: fb.responses(
@@ -2115,6 +2245,26 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
                     on_token=on_token,
                     **_caller_kwargs,
                 )
+            # If the credential was rejected (401) and a refresh hook can supply
+            # a fresh key, re-resolve it (off the event loop) and retry once.
+            loop = asyncio.get_running_loop()
+            refreshed_key = await loop.run_in_executor(
+                None, self._resolve_refreshed_api_key, e
+            )
+            if refreshed_key is not None:
+                logger.warning(
+                    "Authentication error; refreshing API key and retrying once."
+                )
+                return await self._auth_refreshed_llm(refreshed_key).aresponses(
+                    messages,
+                    tools,
+                    include,
+                    store,
+                    add_security_risk_prediction=add_security_risk_prediction,
+                    on_token=on_token,
+                    call_context=call_context,
+                    **_caller_kwargs,
+                )
             _fb_token = cast("TokenCallbackType | None", on_token)
             return await self._ahandle_error(
                 e,

{openhands_sdk-1.49.4 → openhands_sdk-1.49.6}/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."""