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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.49.5
+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.5 → 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.5 → 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.5 → 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.5 → 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.6/openhands/sdk/llm/meta_profile_store.py

@@ -0,0 +1,274 @@
+"""JSON-file storage for meta-profiles.
+
+Key invariant: every model reference in a meta-profile (``classifier_model``,
+each class's ``model``, and direct-routing prompt outputs) is the *name of a
+saved LLM profile* in
+:class:`~openhands.sdk.llm.llm_profile_store.LLMProfileStore`, not a raw model
+string — credentials/provider settings resolve through that store.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Final
+
+from filelock import FileLock, Timeout
+from pydantic import BaseModel, Field, model_validator
+
+from openhands.sdk.llm.llm_profile_store import PROFILE_NAME_REGEX
+from openhands.sdk.logger import get_logger
+
+
+_LOCK_TIMEOUT_SECONDS: Final[float] = 30.0
+
+logger = get_logger(__name__)
+
+
+def default_meta_profile_dir() -> Path:
+    """Return the default directory for meta-profile storage.
+
+    Agent-server instances can set ``OH_PERSISTENCE_DIR`` to isolate all
+    persisted state. Honor that for bare ``MetaProfileStore()`` instances so
+    runtime tools read the same meta-profiles exposed by the HTTP API. Without
+    that env var, keep the standalone SDK default under ``~/.openhands``.
+    """
+    env_dir = os.environ.get("OH_PERSISTENCE_DIR")
+    if env_dir:
+        return Path(env_dir) / "meta-profiles"
+    return Path.home() / ".openhands" / "meta-profiles"
+
+
+class MetaProfileLimitExceeded(Exception):
+    """Raised when saving would exceed the configured meta-profile limit."""
+
+
+class MetaProfileClass(BaseModel):
+    """A single task category and the LLM profile that should handle it."""
+
+    description: str = Field(
+        description="Natural-language description of the kind of task this "
+        "class covers (e.g. 'task is UI oriented or requires looking at images')."
+    )
+    model: str = Field(
+        description="Name of the saved LLM profile to switch to for tasks "
+        "matching this class."
+    )
+
+
+class MetaProfile(BaseModel):
+    """A declarative model-routing configuration."""
+
+    classifier_model: str = Field(
+        description="Name of the saved LLM profile used to classify the task."
+    )
+    classes: list[MetaProfileClass] = Field(
+        default_factory=list,
+        description="Ordered list of task classes and their target profiles.",
+    )
+    prompt_template: str | None = Field(
+        default=None,
+        description=(
+            "Optional direct-routing prompt template. When set, the classifier "
+            "receives this rendered prompt and should return JSON with a "
+            "`model` field instead of a class number."
+        ),
+    )
+    model_table: str | None = Field(
+        default=None,
+        description=(
+            "Optional text inserted into `{{ model_table }}` for direct-routing "
+            "prompts."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_routing_mode(self) -> MetaProfile:
+        """Require either structured classes or a direct prompt, not both."""
+        if self.prompt_template is None:
+            return self
+        if re.search(r"{{\s*instance_text\s*}}", self.prompt_template) is None:
+            raise ValueError(
+                "Direct-routing meta-profiles must include {{ instance_text }} "
+                "in prompt_template."
+            )
+        if self.classes:
+            raise ValueError("Direct-routing meta-profiles cannot also define classes.")
+        return self
+
+
+class MetaProfileStore:
+    """Read meta-profiles from the default meta-profile directory."""
+
+    def __init__(self, base_dir: Path | str | None = None) -> None:
+        """Initialize the meta-profile store.
+
+        Args:
+            base_dir: Directory where meta-profiles are stored. Defaults to
+                ``$OH_PERSISTENCE_DIR/meta-profiles`` when set, otherwise
+                ``~/.openhands/meta-profiles``.
+        """
+        self.base_dir = (
+            Path(base_dir) if base_dir is not None else default_meta_profile_dir()
+        )
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        self._file_lock = FileLock(self.base_dir / ".meta-profiles.lock")
+
+    @contextmanager
+    def _acquire_lock(self, timeout: float = _LOCK_TIMEOUT_SECONDS) -> Iterator[None]:
+        """Acquire the file lock for safe concurrent access.
+
+        The lock is reentrant within a process, so methods that hold it may
+        call other locked methods (e.g. ``save`` calls ``list``).
+
+        Raises:
+            TimeoutError: If the lock cannot be acquired within ``timeout``.
+        """
+        try:
+            with self._file_lock.acquire(timeout=timeout):
+                yield
+        except Timeout:
+            logger.error(
+                f"[Meta-profile Store] Failed to acquire lock within {timeout}s"
+            )
+            raise TimeoutError(
+                f"Meta-profile store lock acquisition timed out after {timeout}s"
+            )
+
+    def list(self) -> list[str]:
+        """Return stored meta-profile names (without ``.json``), sorted.
+
+        The order is alphabetical, not chronological. Callers that fall back to
+        "the first available" meta-profile (when none is explicitly active) get
+        the alphabetically-first name, which is stable but not "most recent".
+        """
+        return sorted(
+            p.stem
+            for p in self.base_dir.glob("*.json")
+            if PROFILE_NAME_REGEX.match(p.stem)
+        )
+
+    def _get_path(self, name: str) -> Path:
+        clean_name = name.removesuffix(".json")
+        if not PROFILE_NAME_REGEX.match(clean_name):
+            raise ValueError(
+                f"Invalid meta-profile name: {name!r}. "
+                "Names must be 1-64 characters, start with a letter or digit, "
+                "and contain only letters, digits, '.', '_', or '-'."
+            )
+        return self.base_dir / f"{clean_name}.json"
+
+    def load(self, name: str) -> MetaProfile:
+        """Load a meta-profile by name.
+
+        Raises:
+            FileNotFoundError: If the meta-profile does not exist.
+            ValueError: If the file is corrupted or fails validation.
+        """
+        path = self._get_path(name)
+        if not path.exists():
+            existing = self.list()
+            raise FileNotFoundError(
+                f"Meta-profile `{name}` not found. "
+                f"Available meta-profiles: {', '.join(existing) or 'none'}"
+            )
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return MetaProfile.model_validate(data)
+        except Exception as e:
+            raise ValueError(f"Failed to load meta-profile `{name}`: {e}") from e
+
+    def save(
+        self,
+        name: str,
+        meta_profile: MetaProfile,
+        *,
+        max_profiles: int | None = None,
+    ) -> None:
+        """Persist a meta-profile under ``name`` (atomic write, overwrites).
+
+        Args:
+            name: Name of the meta-profile to save.
+            meta_profile: The meta-profile to persist.
+            max_profiles: Optional cap on the number of meta-profiles. When set,
+                raises :class:`MetaProfileLimitExceeded` if creating a *new*
+                meta-profile would exceed the limit.
+
+        Raises:
+            MetaProfileLimitExceeded: If ``max_profiles`` would be exceeded.
+            ValueError: If ``name`` is not a valid meta-profile name.
+        """
+        path = self._get_path(name)
+
+        # Hold the lock across the precondition check and the atomic replace so
+        # concurrent creators cannot both pass the limit check and overshoot
+        # ``max_profiles`` (TOCTOU), mirroring ``LLMProfileStore``.
+        with self._acquire_lock():
+            if max_profiles is not None and not path.exists():
+                if len(self.list()) >= max_profiles:
+                    raise MetaProfileLimitExceeded(
+                        f"Meta-profile limit reached ({max_profiles})."
+                    )
+
+            profile_json = json.dumps(meta_profile.model_dump(mode="json"), indent=2)
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                dir=self.base_dir,
+                suffix=".tmp",
+                delete=False,
+                encoding="utf-8",
+            ) as tmp:
+                tmp.write(profile_json)
+                tmp_path = Path(tmp.name)
+
+            try:
+                Path.replace(tmp_path, path)
+            except Exception:
+                tmp_path.unlink(missing_ok=True)
+                raise
+        logger.info(f"Saved meta-profile `{name}` at {path}")
+
+    def delete(self, name: str) -> None:
+        """Delete a meta-profile (idempotent — missing names are a no-op).
+
+        Raises:
+            ValueError: If ``name`` is not a valid meta-profile name.
+        """
+        path = self._get_path(name)
+        with self._acquire_lock():
+            if not path.exists():
+                logger.info(f"Meta-profile `{name}` not found. Skipping delete.")
+                return
+            path.unlink()
+        logger.info(f"Deleted meta-profile `{name}`")
+
+    def list_summaries(self) -> list[dict[str, Any]]:
+        """List meta-profile metadata without full schema validation.
+
+        Files with corrupted JSON or non-dict top-level values are skipped with
+        a warning so a single bad file never breaks the listing.
+        """
+        summaries: list[dict[str, Any]] = []
+        for name in self.list():
+            try:
+                data = json.loads(self._get_path(name).read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as e:
+                logger.warning(f"Skipping corrupted meta-profile {name!r}: {e}")
+                continue
+            if not isinstance(data, dict):
+                logger.warning(f"Skipping non-dict meta-profile {name!r}")
+                continue
+            classes = data.get("classes") or []
+            summaries.append(
+                {
+                    "name": name,
+                    "classifier_model": data.get("classifier_model"),
+                    "num_classes": len(classes) if isinstance(classes, list) else 0,
+                }
+            )
+        return summaries

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

@@ -109,7 +109,6 @@ 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",
 }
 

{openhands_sdk-1.49.5 → openhands_sdk-1.49.6}/openhands/sdk/llm/utils/verified_models.py

@@ -11,6 +11,8 @@ stay. When a new version lands, drop the oldest one in the same line.
 
 # GPT: gpt-6 and gpt-5.6. Codex: gpt-5.3-codex and gpt-5.2-codex.
 VERIFIED_OPENAI_MODELS = [
+    "gpt-6-sol",
+    "gpt-6-luna",
     "gpt-6-astra",
     "gpt-5.6",
     "gpt-5.6-sol",
@@ -20,10 +22,10 @@ VERIFIED_OPENAI_MODELS = [
     "gpt-5.2-codex",
 ]
 
-# Opus: 5 and 4.8. Sonnet: 5 and 4.6. Haiku: 4.5. Fable: 5.1 and 5.
+# Opus: 5.5 and 5. Sonnet: 5 and 4.6. Haiku: 4.5. Fable: 5.1 and 5.
 VERIFIED_ANTHROPIC_MODELS = [
+    "claude-opus-5-5",
     "claude-opus-5",
-    "claude-opus-4-8",
     "claude-sonnet-5",
     "claude-sonnet-4-6",
     "claude-haiku-4-5-20251001",
@@ -104,12 +106,14 @@ VERIFIED_QWEN_MODELS = [
 # What the ``openhands/`` provider serves. Same rule; every entry must also be in
 # a provider list above, except OpenHands-only models.
 VERIFIED_OPENHANDS_MODELS = [
+    "claude-opus-5-5",
     "claude-opus-5",
-    "claude-opus-4-8",
     "claude-sonnet-5",
     "claude-sonnet-4-6",
     "claude-fable-5-1",
     "claude-fable-5",
+    "gpt-6-sol",
+    "gpt-6-luna",
     "gpt-6-astra",
     "gpt-5.6",
     "gpt-5.3-codex",