openhands-sdk 1.44.0__tar.gz → 1.45.0__tar.gz

{openhands_sdk-1.44.0 → openhands_sdk-1.45.0}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.44.0
+Version: 1.45.0
 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
 Project-URL: Documentation, https://docs.openhands.dev/sdk
 Project-URL: Bug Tracker, https://github.com/OpenHands/software-agent-sdk/issues
 Requires-Python: >=3.12
-Requires-Dist: agent-client-protocol>=0.10.1
+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.0.0
+Requires-Dist: fastmcp>=3.2.0
 Requires-Dist: filelock>=3.20.1
 Requires-Dist: httpx[socks]>=0.27.0
 Requires-Dist: jsonschema>=4.23.0
@@ -22,7 +22,7 @@ Requires-Dist: python-frontmatter>=1.1.0
 Requires-Dist: python-json-logger>=3.3.0
 Requires-Dist: tenacity>=9.1.2
 Requires-Dist: websockets>=12
-Requires-Dist: lmnr<0.8.0,>=0.7.56
+Requires-Dist: lmnr<0.8.0,>=0.7.60
 Requires-Dist: tree-sitter>=0.25
 Requires-Dist: tree-sitter-bash>=0.25
 Provides-Extra: boto3

{openhands_sdk-1.44.0 → openhands_sdk-1.45.0}/openhands/sdk/agent/acp_agent.py

@@ -27,7 +27,14 @@ import threading
 import time
 import uuid
 import weakref
-from collections.abc import Awaitable, Callable, Collection, Generator, Iterable
+from collections.abc import (
+    Awaitable,
+    Callable,
+    Collection,
+    Generator,
+    Iterable,
+    Sequence,
+)
 from concurrent.futures import Future
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Final, Literal, NamedTuple
@@ -69,6 +76,7 @@ from openhands.sdk.agent.acp_file_credentials import (
     codex_auth_file,
     codex_auth_file_is_chatgpt,
     create_file_credential_lifecycle,
+    file_credential_looks_usable,
     write_secret_file,
 )
 from openhands.sdk.agent.acp_models import ACPModelInfo
@@ -94,11 +102,15 @@ from openhands.sdk.logger import get_logger
 from openhands.sdk.mcp.config import MCPServer
 from openhands.sdk.observability.laminar import maybe_init_laminar, observe
 from openhands.sdk.settings.acp_providers import (
+    ACP_PROVIDERS,
+    ACPEnvConflictSpec,
     ACPFileSecretSpec,
+    ACPProviderInfo,
     build_session_model_meta,
     default_acp_file_secrets,
     detect_acp_provider_by_agent_name,
     detect_acp_provider_by_command,
+    get_acp_provider,
 )
 from openhands.sdk.tool import Tool  # noqa: TC002
 from openhands.sdk.tool.builtins.finish import FinishAction, FinishObservation
@@ -145,6 +157,10 @@ _ACP_CANCEL_DRAIN_TIMEOUT: float = float(
 )
 
 _ACP_AUTH_TIMEOUT: float = float(os.environ.get("ACP_AUTH_TIMEOUT", "30.0"))
+_ACP_NPX_CACHE_WARM_TIMEOUT: float = float(
+    os.environ.get("ACP_NPX_CACHE_WARM_TIMEOUT", "300")
+)
+_ACP_VERSION_RE = re.compile(r"v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)")
 
 _ACP_PROMPT_RETRY_DELAYS: tuple[float, ...] = (5.0, 15.0, 30.0)  # seconds
 
@@ -170,26 +186,6 @@ _RETRIABLE_SERVER_ERROR_CODES: frozenset[int] = frozenset({-32603})
 MAX_ACP_CONTENT_CHARS: int = 30_000
 _ACP_SUBPROCESS_LOG_LINE_CHARS = 4_000
 
-# Env vars that must be removed from the subprocess environment when a
-# particular "dominant" env var is present.
-#
-# Rationale: Claude Code's subscription auth uses CLAUDE_CODE_OAUTH_TOKEN, a
-# bearer validated against api.anthropic.com. A co-present ANTHROPIC_API_KEY
-# would take precedence over the token (silently bypassing the subscription),
-# and an ANTHROPIC_BASE_URL would route the bearer to a proxy that rejects it —
-# either silently breaks the intended OAuth auth. When the OAuth token is the
-# active credential we strip both so the subprocess authenticates with the
-# token against api.anthropic.com.
-#
-# Keyed on the credential itself (CLAUDE_CODE_OAUTH_TOKEN), NOT on
-# CLAUDE_CONFIG_DIR: the config dir is a *location* lever (data-dir isolation,
-# #1019) that is orthogonal to which credential is active. Keying the strip on
-# it wrongly fired during API-key isolation and missed the conflict when the
-# token arrived via env without isolation (#3588).
-_ENV_CONFLICT_MAP: dict[str, frozenset[str]] = {
-    "CLAUDE_CODE_OAUTH_TOKEN": frozenset({"ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL"}),
-}
-
 # Number of trailing characters of an ACP session id retained in log lines
 # for correlation.  ACP session ids are server-issued tokens whose possession
 # alone is enough to call ``session/load`` — they're effectively bearer
@@ -242,8 +238,9 @@ _STREAM_READER_LIMIT: int = 100 * 1024 * 1024  # 100 MiB
 
 # Minimum interval between on_activity heartbeat signals (seconds).
 # Throttled to avoid excessive calls while still keeping the idle timer
-# well below the ~20 min runtime-api kill threshold.
-_ACTIVITY_SIGNAL_INTERVAL: float = 30.0
+# well below the ~20 min runtime-api kill threshold.  Shared with the
+# agent-server's streaming-delta heartbeat so both paths keep the same pace.
+ACTIVITY_SIGNAL_INTERVAL: Final[float] = 30.0
 
 # ACP tool-call statuses that represent a terminal outcome.  Non-terminal
 # statuses (``pending``, ``in_progress``) mean the call is still in flight
@@ -291,6 +288,44 @@ _AUTH_METHOD_ENV_MAP: dict[str, str] = {
 _GEMINI_OAUTH_PATH = Path(".gemini") / "oauth_creds.json"
 
 
+def _preconfigured_credentials(
+    provider: ACPProviderInfo | None,
+    specs: Sequence[ACPFileSecretSpec],
+    env: dict[str, str],
+) -> list[str]:
+    """Credential sources already in place, named as they were supplied.
+
+    A server whose advertised auth methods we cannot perform may still be
+    authenticated out of band — from a credential file seeded onto disk, or
+    from the provider key it reads straight out of its environment. Both make
+    "no credential is available" the wrong thing to say. Read off the registry
+    record rather than provider names, so this holds for any provider.
+    """
+    present: list[str] = []
+    for spec in specs:
+        location = env.get(spec.env_var)
+        if not location:
+            continue
+        path = Path(location)
+        if spec.env_points_to == "dir":
+            path = path / spec.filename
+        if not path.is_file():
+            continue
+        # A file that exists but cannot authenticate is the case that most
+        # needs the warning, so presence alone is not enough where the SDK
+        # knows the format.
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError):
+            continue
+        if file_credential_looks_usable(spec.secret_name, text):
+            present.append(spec.secret_name)
+    api_key_var = provider.api_key_env_var if provider is not None else None
+    if api_key_var and env.get(api_key_var):
+        present.append(api_key_var)
+    return present
+
+
 def _select_auth_method(
     auth_methods: list[Any],
     env: dict[str, str],
@@ -336,7 +371,11 @@ def _select_auth_method(
     return None
 
 
-def _auth_selection_failure_reason(auth_methods: list[Any], env: dict[str, str]) -> str:
+def _auth_selection_failure_reason(
+    auth_methods: list[Any],
+    env: dict[str, str],
+    provider: ACPProviderInfo | None = None,
+) -> str:
     method_ids = {m.id for m in auth_methods}
     reasons: list[str] = []
     if "chat-gpt" in method_ids:
@@ -349,18 +388,113 @@ def _auth_selection_failure_reason(auth_methods: list[Any], env: dict[str, str])
         env.get(name) for name in ("CODEX_API_KEY", "OPENAI_API_KEY")
     ):
         reasons.append("CODEX_API_KEY and OPENAI_API_KEY are unset")
+    if provider is not None and provider.api_key_env_var:
+        if not env.get(provider.api_key_env_var):
+            reasons.append(f"{provider.api_key_env_var} is unset")
+    # ``type: "terminal"`` marks a login only an interactive TTY can complete,
+    # which the runtime does not have. Named so the log says why the method was
+    # never a candidate rather than implying a missing credential.
+    terminal_ids = sorted(
+        m.id for m in auth_methods if getattr(m, "type", None) == "terminal"
+    )
+    if terminal_ids:
+        reasons.append(
+            f"{', '.join(terminal_ids)} needs an interactive terminal, which the "
+            "headless runtime cannot provide"
+        )
     return "; ".join(reasons) or "no supported credential source is available"
 
 
-def _warn_auth_selection_failure(auth_methods: list[Any], env: dict[str, str]) -> None:
+def _warn_auth_selection_failure(
+    auth_methods: list[Any],
+    env: dict[str, str],
+    provider: ACPProviderInfo | None = None,
+) -> None:
     logger.warning(
         "ACP server offers auth methods %s but no matching credential is available "
         "(%s) — session creation may fail",
         [m.id for m in auth_methods],
-        _auth_selection_failure_reason(auth_methods, env),
+        _auth_selection_failure_reason(auth_methods, env, provider),
     )
 
 
+def _log_acp_provider_version(agent_name: str, agent_version: str) -> None:
+    try:
+        provider = detect_acp_provider_by_agent_name(agent_name)
+        if provider is None:
+            return
+        pinned_version = None
+        for command_part in provider.default_command:
+            package, separator, version = command_part.rpartition("@")
+            if separator and package:
+                pinned_version = version
+                break
+        reported_version = next(
+            (
+                match.group(1)
+                for value in (agent_version, agent_name)
+                if (match := _ACP_VERSION_RE.search(value)) is not None
+            ),
+            None,
+        )
+        logger.info(
+            "ACP provider version: provider=%s, pinned_version=%r, "
+            "agent_name=%r, agent_version=%r, reported_version=%r",
+            provider.key,
+            pinned_version,
+            agent_name,
+            agent_version,
+            reported_version,
+        )
+        if reported_version is None:
+            logger.warning(
+                "Could not parse ACP provider version: provider=%s, "
+                "pinned_version=%r, agent_name=%r, agent_version=%r",
+                provider.key,
+                pinned_version,
+                agent_name,
+                agent_version,
+            )
+        elif pinned_version is not None and reported_version != pinned_version:
+            logger.warning(
+                "ACP provider version mismatch: provider=%s, pinned_version=%r, "
+                "reported_version=%r; provider was probably installed at runtime "
+                "via the npx fallback rather than preinstalled in the image",
+                provider.key,
+                pinned_version,
+                reported_version,
+            )
+    except Exception:
+        logger.warning(
+            "Could not verify ACP provider version: agent_name=%r, agent_version=%r",
+            agent_name,
+            agent_version,
+        )
+
+
+def _npx_packages(command: list[str]) -> list[str]:
+    """Pinned npm specs an ``npx`` command installs, for the cache warm.
+
+    ``--package=<spec>`` flags when present — pi pins its ACP adapter and the
+    engine it spawns separately, and its positional argument is the bare binary
+    name, which would warm an unpinned package. Otherwise the first positional,
+    which is the package for the single-package providers.
+    """
+    if not command or command[0] != "npx":
+        return []
+    pinned = [
+        arg.removeprefix("--package=")
+        for arg in command[1:]
+        if arg.startswith("--package=")
+    ]
+    if pinned:
+        return pinned
+    for arg in command[1:]:
+        if not arg.startswith("-"):
+            return [arg]
+    return []
+
+
 def _with_codex_base_url(
     command: str, args: list[str], env: dict[str, str]
 ) -> dict[str, str]:
@@ -1429,13 +1563,13 @@ class _OpenHandsACPBridge:
         the server's idle_time grows unboundedly and the runtime-api kills
         the pod (default idle threshold ~20 min).
 
-        Throttled to at most once per _ACTIVITY_SIGNAL_INTERVAL seconds to
+        Throttled to at most once per ACTIVITY_SIGNAL_INTERVAL seconds to
         avoid excessive overhead on chatty ACP servers.
         """
         if self.on_activity is None:
             return
         now = time.monotonic()
-        if now - self._last_activity_signal >= _ACTIVITY_SIGNAL_INTERVAL:
+        if now - self._last_activity_signal >= ACTIVITY_SIGNAL_INTERVAL:
             self._last_activity_signal = now
             try:
                 self.on_activity()
@@ -1552,8 +1686,8 @@ class ACPAgent(AgentBase):
         default=None,
         description=(
             "Provider registry key identifying which ACP CLI this agent runs "
-            "('claude-code', 'codex', 'gemini-cli', or 'custom'); None when the "
-            "agent is built directly rather than via ACPAgentSettings. Set by "
+            "(any ACP_PROVIDERS key, or 'custom'); None when the agent is "
+            "built directly rather than via ACPAgentSettings. Set by "
             "ACPAgentSettings.create_agent() from ACPAgentSettings.acp_server so "
             "the authoritative key survives onto the agent — and thus onto "
             "ConversationInfo.agent — because the launch command in acp_command "
@@ -1572,7 +1706,8 @@ class ACPAgent(AgentBase):
             "Session mode ID to set after creating a session. "
             "If None (default), auto-detected from the ACP server type: "
             "'bypassPermissions' for claude-agent-acp, "
-            "'agent-full-access' for codex-acp."
+            "'agent-full-access' for codex-acp; a provider with no such mode "
+            "(pi-acp) skips the call."
         ),
     )
     acp_prompt_timeout: float = Field(
@@ -1699,6 +1834,21 @@ class ACPAgent(AgentBase):
         ),
     )
 
+    @field_validator("agent_context")
+    @classmethod
+    def _drop_project_skills(cls, value: AgentContext | None) -> AgentContext | None:
+        """Clear ``load_project_skills`` — ACP CLIs read the repo themselves.
+
+        Claude Code, Codex and Gemini already ingest ``AGENTS.md`` / ``CLAUDE.md``
+        and their own project skills from the session cwd, so loading them here
+        too would put that content in the prompt twice. Normalised rather than
+        rejected: callers legitimately set the flag on a shared context they also
+        use for OpenHands agents (#4019).
+        """
+        if value is None or not value.load_project_skills:
+            return value
+        return value.model_copy(update={"load_project_skills": False})
+
     def model_post_init(self, __context: object) -> None:
         super().model_post_init(__context)
         # Propagate the actual model name to the sentinel LLM and its
@@ -2325,6 +2475,59 @@ class ACPAgent(AgentBase):
             root = Path(state.workspace.working_dir) / ".openhands" / "acp" / subdir
         return Path(os.path.abspath(root))
 
+    def _acp_npm_cache_dir(self, state: ConversationState) -> Path:
+        if state.persistence_dir:
+            root = Path(state.persistence_dir).parent
+        else:
+            root = Path(state.workspace.working_dir) / ".openhands"
+        cache_dir = root / "npm-cache"
+        cache_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        return Path(os.path.abspath(cache_dir))
+
+    async def _warm_npx_cache(
+        self,
+        packages: Sequence[str],
+        provider_key: str,
+        env: dict[str, str],
+        cwd: str,
+    ) -> None:
+        logger.info(
+            "Warming ACP provider npx cache: provider=%s, packages=%s; "
+            "first use may download the provider before session startup",
+            provider_key,
+            list(packages),
+        )
+        package_args = [arg for package in packages for arg in ("--package", package)]
+        process = await asyncio.create_subprocess_exec(
+            "npx",
+            "--yes",
+            "--prefer-offline",
+            *package_args,
+            "--",
+            "node",
+            "-e",
+            "",
+            cwd=cwd,
+            env=env,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        try:
+            await asyncio.wait_for(process.wait(), timeout=_ACP_NPX_CACHE_WARM_TIMEOUT)
+        except TimeoutError as exc:
+            process.kill()
+            await process.wait()
+            raise RuntimeError(
+                "ACP provider cache warm timed out after "
+                f"{_ACP_NPX_CACHE_WARM_TIMEOUT:.0f}s for {provider_key}"
+            ) from exc
+        if process.returncode:
+            raise RuntimeError(
+                f"ACP provider cache warm failed for {provider_key} "
+                f"(exit code {process.returncode})"
+            )
+
     def _isolate_acp_data_dir(
         self, state: ConversationState, env: dict[str, str]
     ) -> None:
@@ -2351,8 +2554,9 @@ class ACPAgent(AgentBase):
         ``ANTHROPIC_API_KEY`` — API-key Claude gets the same per-conversation
         isolation (and pause/resume continuity) as OAuth Claude (#3588).
 
-        ``HOME`` (gemini-cli's only lever — it hard-codes ``~/.gemini`` and
-        ignores ``XDG``) has a wider blast radius than the surgical
+        ``HOME`` (the only lever for gemini-cli, which hard-codes ``~/.gemini``
+        and ignores ``XDG``, and for pi-acp, whose session map is hard-coded to
+        ``~/.pi/pi-acp``) has a wider blast radius than the surgical
         ``CODEX_HOME`` / ``CLAUDE_CONFIG_DIR``: it also relocates the home dir
         seen by anything the CLI subprocess itself spawns (``git``, ``npm``,
         ``node``, shells — e.g. ``~/.gitconfig``, ``~/.npmrc``, the npm cache).
@@ -2372,6 +2576,42 @@ class ACPAgent(AgentBase):
         data_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
         env[env_var] = str(data_dir)
 
+    def _resolved_provider(self) -> ACPProviderInfo | None:
+        """The provider this agent runs, preferring the authoritative key.
+
+        ``acp_server`` is set by ``ACPAgentSettings.create_agent()`` and is the
+        only identity that survives a custom or aliased ``acp_command``; the
+        command is the fallback for an agent constructed directly.
+        """
+        return get_acp_provider(
+            self.acp_server or ""
+        ) or detect_acp_provider_by_command(self.acp_command)
+
+    def _strip_conflicting_env(self, env: dict[str, str]) -> None:
+        """Remove env vars that would defeat this provider's own credential.
+
+        Scoped to the resolved provider's :attr:`ACPProviderInfo.env_conflicts`:
+        the same variable is another provider's *credential* (a provider whose
+        ``api_key_env_var`` is ``ANTHROPIC_API_KEY``), and stripping it there
+        leaves it with nothing to authenticate with.
+
+        An unrecognised server keeps the conservative union: without an identity
+        we cannot tell whose credential a dominant variable belongs to, and a
+        directly-constructed ``ACPAgent`` running Claude Code is the case the
+        rule was written for (#3588).
+        """
+        provider = self._resolved_provider()
+        if provider is not None:
+            specs: tuple[ACPEnvConflictSpec, ...] = provider.env_conflicts
+        else:
+            specs = tuple(
+                spec for info in ACP_PROVIDERS.values() for spec in info.env_conflicts
+            )
+        for spec in specs:
+            if spec.dominant in env:
+                for name in spec.strip:
+                    env.pop(name, None)
+
     def _materialise_file_secrets(
         self, state: ConversationState, env: dict[str, str]
     ) -> None:
@@ -2634,13 +2874,7 @@ class ACPAgent(AgentBase):
         # Strip CLAUDECODE so nested Claude Code instances don't refuse to start
         env.pop("CLAUDECODE", None)
 
-        # Strip env vars that conflict with an active auth mechanism: an active
-        # CLAUDE_CODE_OAUTH_TOKEN must not coexist with ANTHROPIC_API_KEY (which
-        # takes precedence) or ANTHROPIC_BASE_URL (proxies the bearer). See #3588.
-        for dominant, conflicts in _ENV_CONFLICT_MAP.items():
-            if dominant in env:
-                for conflict in conflicts:
-                    env.pop(conflict, None)
+        self._strip_conflicting_env(env)
 
         command = self.acp_command[0]
         args = list(self.acp_command[1:]) + list(self.acp_args)
@@ -2650,6 +2884,22 @@ class ACPAgent(AgentBase):
         env = _with_codex_base_url(command, args, env)
 
         working_dir = str(state.workspace.working_dir)
+        provider = detect_acp_provider_by_command(self.acp_command)
+        packages = _npx_packages(self.acp_command)
+        if provider is not None and packages:
+            env["npm_config_cache"] = str(self._acp_npm_cache_dir(state))
+            try:
+                self._executor.run_async(
+                    self._warm_npx_cache(packages, provider.key, env, working_dir),
+                    timeout=_ACP_NPX_CACHE_WARM_TIMEOUT + 5,
+                )
+            except Exception as error:
+                logger.warning(
+                    "ACP provider npx cache warm failed: provider=%s; "
+                    "continuing with normal startup: %s",
+                    provider.key,
+                    error,
+                )
 
         # Prior ACP session id — typically survives agent-server restarts via
         # ConversationState.agent_state (serialized into base_state.json).
@@ -2763,6 +3013,7 @@ class ACPAgent(AgentBase):
                 agent_name,
                 agent_version,
             )
+            _log_acp_provider_version(agent_name, agent_version)
 
             # Translate any configured MCP servers into ACP protocol objects,
             # gating remote (http/sse) transports on what this server advertised
@@ -2830,7 +3081,28 @@ class ACPAgent(AgentBase):
                         ) from exc
                     await self._flush_file_credentials()
                 else:
-                    _warn_auth_selection_failure(auth_methods, env)
+                    # A server whose advertised methods we cannot perform may
+                    # still be authenticated out of band — from a seeded
+                    # credential file or the provider key it reads out of the
+                    # environment — so warning about a login we cannot do
+                    # would be noise whenever either is present.
+                    auth_provider = (
+                        self._resolved_provider()
+                        or detect_acp_provider_by_agent_name(agent_name)
+                    )
+                    configured = _preconfigured_credentials(
+                        auth_provider, self.acp_file_secrets, env
+                    )
+                    if configured:
+                        logger.info(
+                            "ACP server offers auth methods %s that cannot be "
+                            "performed here; using the already-configured "
+                            "credential(s) %s instead",
+                            [m.id for m in auth_methods],
+                            configured,
+                        )
+                    else:
+                        _warn_auth_selection_failure(auth_methods, env, auth_provider)
 
             # Resume the prior ACP session if we have its id.  If the server
             # has forgotten it (state wiped, new host, etc.) fall through to

{openhands_sdk-1.44.0 → openhands_sdk-1.45.0}/openhands/sdk/agent/acp_file_credentials.py

@@ -515,3 +515,22 @@ _FILE_CREDENTIAL_LIFECYCLES = {
 
 def supports_file_credential_binding(secret_name: str) -> bool:
     return secret_name in _FILE_CREDENTIAL_LIFECYCLES
+
+
+_FILE_CREDENTIAL_VALIDATORS: dict[str, Callable[[str], bool]] = {
+    CODEX_AUTH_SECRET_NAME: is_valid_codex_auth,
+}
+
+
+def file_credential_looks_usable(secret_name: str, text: str) -> bool:
+    """Whether a materialised credential file is plausibly usable.
+
+    Only a *present* file can be checked here, and only for the few secrets the
+    SDK knows the shape of. An unrecognised secret gets the benefit of the
+    doubt: the CLI owns the format, and refusing to believe a credential we
+    cannot parse would warn on every provider we have not special-cased —
+    which is the noise this is meant to avoid. Returning ``True`` for unknown
+    names keeps that judgement with the provider.
+    """
+    validator = _FILE_CREDENTIAL_VALIDATORS.get(secret_name)
+    return True if validator is None else validator(text)

{openhands_sdk-1.44.0 → openhands_sdk-1.45.0}/openhands/sdk/agent/acp_tracing.py

@@ -25,7 +25,7 @@ logger = get_logger(__name__)
 
 #: Marks a span as produced by an ACP agent rather than the native loop.
 AGENT_KIND_METADATA_KEY = "agent_kind"
-#: Which ACP CLI produced it ('claude-code', 'codex', 'gemini-cli', 'custom').
+#: Which ACP CLI produced it: an ACP_PROVIDERS key, or 'custom'.
 ACP_SERVER_METADATA_KEY = "acp_server"
 #: Model the ACP CLI reported for the turn, when it reports one.
 ACP_MODEL_METADATA_KEY = "acp_model"

{openhands_sdk-1.44.0 → openhands_sdk-1.45.0}/openhands/sdk/agent/base.py

@@ -43,8 +43,8 @@ from openhands.sdk.tool.builtins.vision_inspect import (
     VisionInspectTool,
     has_vision_profile_available,
 )
-from openhands.sdk.utils.deprecation import deprecated
 from openhands.sdk.utils.models import DiscriminatedUnionMixin
+from openhands.sdk.utils.path import get_user_persistence_dir
 
 
 if TYPE_CHECKING:
@@ -58,10 +58,11 @@ logger = get_logger(__name__)
 
 
 # -- SOUL.md loader -------------------------------------------------------
-# SOUL.md is the agent's identity file (~/.openhands/SOUL.md).  When present
-# it replaces the default identity in the system prompt.
+# SOUL.md is the agent's identity file, ``SOUL.md`` under the user persistence
+# directory (~/.openhands/SOUL.md absent OH_PERSISTENCE_DIR).  When present it
+# replaces the default identity in the system prompt.
 
-_SOUL_PATH = os.path.join(os.path.expanduser("~"), ".openhands", "SOUL.md")
+_SOUL_PATH = get_user_persistence_dir() / "SOUL.md"
 _DEFAULT_SOUL = (
     "You are OpenHands agent, a helpful AI assistant that can interact"
     " with a computer to solve tasks."
@@ -84,7 +85,7 @@ _PRESET_BY_FILENAME: dict[str, PromptPreset] = {
 
 
 def _load_soul_md() -> str:
-    """Load ``~/.openhands/SOUL.md``, falling back to the built-in default."""
+    """Load ``SOUL.md`` from the user persistence dir, else the built-in default."""
     try:
         with open(_SOUL_PATH, encoding="utf-8") as f:
             content = f.read().strip()
@@ -735,21 +736,6 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
 
         return self
 
-    @deprecated(
-        deprecated_in="1.40.0",
-        removed_in="1.45.0",
-        details="Use model_dump(exclude_none=True) instead.",
-    )
-    def model_dump_succint(self, **kwargs):
-        """Like model_dump, but excludes None fields by default."""
-        if "exclude_none" not in kwargs:
-            kwargs["exclude_none"] = True
-        dumped = super().model_dump(**kwargs)
-        # remove tool schema details for brevity
-        if "tools" in dumped and isinstance(dumped["tools"], dict):
-            dumped["tools"] = list(dumped["tools"].keys())
-        return dumped
-
     def get_all_llms(self) -> Generator[LLM]:
         """Recursively yield unique *base-class* LLM objects reachable from `self`.
 

{openhands_sdk-1.44.0 → openhands_sdk-1.45.0}/openhands/sdk/agent/response_dispatch.py

@@ -281,7 +281,7 @@ class ResponseDispatchMixin:
         """Create and emit a MessageEvent, running critic if configured."""
         msg_event = MessageEvent(
             source="agent",
-            llm_message=message,
+            llm_message=self._mask_secrets(message, conversation),
             llm_response_id=llm_response.id,
         )
         if self.critic is not None and self.critic.mode == "finish_and_message":
@@ -293,6 +293,28 @@ class ResponseDispatchMixin:
         on_event(msg_event)
         return msg_event
 
+    @staticmethod
+    def _mask_secrets(message: Message, conversation: LocalConversation) -> Message:
+        """Return ``message`` with registered secret values masked in its text.
+
+        ``thinking_blocks`` and ``responses_reasoning_item`` are left alone:
+        they are signed provider payloads, and rewriting them invalidates the
+        signature replayed on the next request.
+        """
+        mask = conversation.state.secret_registry.mask_secrets_in_output
+        reasoning = message.reasoning_content
+        return message.model_copy(
+            update={
+                "content": [
+                    part.model_copy(update={"text": mask(part.text)})
+                    if isinstance(part, TextContent)
+                    else part
+                    for part in message.content
+                ],
+                "reasoning_content": mask(reasoning) if reasoning else reasoning,
+            }
+        )
+
     def _send_corrective_nudge(self, on_event: ConversationCallbackType) -> None:
         """Inject corrective feedback when no tool call and no content.