feat: workspace.get_llm() and get_secrets() for OpenHandsCloudWorkspace credential inheritance

.pr/README.md

@@ -0,0 +1,55 @@
+# PR #2409 — Integration Test Report
+
+## Test: `workspace.get_llm()` and `workspace.get_secrets()` against staging
+
+**Date:** 2026-03-16
+**Target:** `https://ohpr-13383-240.staging.all-hands.dev` (deploy PR [#3436](https://github.com/OpenHands/deploy/pull/3436))
+**Server PR:** [OpenHands/OpenHands#13383](https://github.com/OpenHands/OpenHands/pull/13383) (companion)
+**SaaS server:** Custom build from [OpenHands/OpenHands#13383](https://github.com/OpenHands/OpenHands/pull/13383) (provides `/sandboxes/{id}/settings/secrets` endpoints)
+**Sandbox agent-server:** `ghcr.io/openhands/agent-server:1.13.0-python` (stock — no SDK PR changes needed in sandbox)
+
+## Final Results (all passing ✅)
+
+| Component | Status | Details |
+|---|---|---|
+| Sandbox provisioning | ✅ | Created, RUNNING in ~50s, cleaned up on exit |
+| `workspace.get_llm()` | ✅ | Retrieves `litellm_proxy/minimax-m2.5` + api_key + base_url from SaaS |
+| `workspace.get_secrets()` | ✅ | Discovers `['DUMMY_1', 'DUMMY_2']` via `GET /sandboxes/{id}/settings/secrets` |
+| `update_secrets(LookupSecret)` | ✅ | LookupSecret with session key in `headers` survives serialization |
+| Env vars exported inside sandbox | ✅ | `_export_envs` resolves LookupSecret → secrets appear as real env vars |
+| Sandbox cleanup | ✅ | `DELETE /api/v1/sandboxes/{id}` succeeds |
+
+### Agent verification output (from inside the sandbox)
+
+The agent ran the exact Python command we gave it. The output proves the secrets
+were resolved by the `_export_envs` pipeline and exported as real env vars:
+
+```
+$ python3 -c "import os; v=os.environ.get('DUMMY_1',''); print(f'DUMMY_1: len={len(v)}, last_half={v[len(v)//2:]}')" && \
+  python3 -c "import os; v=os.environ.get('DUMMY_2',''); print(f'DUMMY_2: len={len(v)}, last_half={v[len(v)//2:]}')"
+
+DUMMY_1: len=14, last_half=ecret 1
+DUMMY_2: len=14, last_half=ecret 2
+```
+
+Both secrets are 14 characters long, non-empty, and the second half matches
+the expected values (`"Dummy secret 1"` → `"ecret 1"`, `"dummy secret 2"` → `"ecret 2"`).
+
+## Issues found and fixed during testing
+
+### 1. Sandbox DELETE 405
+`cleanup()` called `DELETE /api/v1/sandboxes?sandbox_id=X` (query param on collection route) → 405.
+**Fix:** Changed to `DELETE /api/v1/sandboxes/{sandbox_id}?sandbox_id={sandbox_id}`.
+
+### 2. SecretStr serialization redacts headers
+`SecretSource.model_dump(mode="json")` redacts `SecretStr` fields (returns `**********`).
+`LookupSecret.headers` containing `X-Session-API-Key` was lost during `update_secrets()` serialization.
+**Fix:** Added `context={"expose_secrets": True}` to `model_dump()` in `RemoteConversation.update_secrets()`.
+
+### 3. Removed `env_headers` (was unnecessary complexity)
+Original design added `env_headers` field to `LookupSecret` so session key VALUE never appeared
+in serialized JSON (only the env var NAME). This created a deployment dependency — the agent-server
+image needed the new field, but the stock image didn't have it.
+**Fix:** Dropped `env_headers` entirely. Using the existing `headers` field with `expose_secrets`
+context is simpler and works with the stock agent-server image. No custom build or redeploy needed.
+Net: **-35 lines, +10 lines**.

examples/02_remote_agent_server/09_cloud_workspace_saas_credentials.py

@@ -0,0 +1,119 @@
+"""Example: Inherit SaaS credentials via OpenHandsCloudWorkspace.
+
+This example shows the simplified flow where your OpenHands Cloud account's
+LLM configuration and secrets are inherited automatically — no need to
+provide LLM_API_KEY separately.
+
+Compared to 07_convo_with_cloud_workspace.py (which requires a separate
+LLM_API_KEY), this approach uses:
+  - workspace.get_llm()     → fetches LLM config from your SaaS account
+  - workspace.get_secrets()  → builds lazy LookupSecret references for your secrets
+
+Raw secret values never transit through the SDK client. The agent-server
+inside the sandbox resolves them on demand.
+
+Usage:
+  uv run examples/02_remote_agent_server/09_cloud_workspace_saas_credentials.py
+
+Requirements:
+  - OPENHANDS_CLOUD_API_KEY: API key for OpenHands Cloud (the only credential needed)
+
+Optional:
+  - OPENHANDS_CLOUD_API_URL: Override the Cloud API URL (default: https://app.all-hands.dev)
+  - LLM_MODEL: Override the model from your SaaS settings
+"""
+
+import os
+import time
+
+from openhands.sdk import (
+    Conversation,
+    RemoteConversation,
+    get_logger,
+)
+from openhands.tools.preset.default import get_default_agent
+from openhands.workspace import OpenHandsCloudWorkspace
+
+
+logger = get_logger(__name__)
+
+
+cloud_api_key = os.getenv("OPENHANDS_CLOUD_API_KEY")
+if not cloud_api_key:
+    logger.error("OPENHANDS_CLOUD_API_KEY required")
+    exit(1)
+
+cloud_api_url = os.getenv("OPENHANDS_CLOUD_API_URL", "https://app.all-hands.dev")
+logger.info(f"Using OpenHands Cloud API: {cloud_api_url}")
+
+with OpenHandsCloudWorkspace(
+    cloud_api_url=cloud_api_url,
+    cloud_api_key=cloud_api_key,
+) as workspace:
+    # --- LLM from SaaS account settings ---
+    # get_llm() calls GET /users/me?expose_secrets=true (dual auth: Bearer + session key)
+    # and returns a fully configured LLM instance.
+    # You can override any parameter, e.g. workspace.get_llm(model="gpt-4o")
+    llm_kwargs = {}
+    if os.getenv("LLM_MODEL"):
+        llm_kwargs["model"] = os.getenv("LLM_MODEL")
+    llm = workspace.get_llm(**llm_kwargs)
+    logger.info(f"LLM configured: model={llm.model}")
+
+    # --- Secrets from SaaS account ---
+    # get_secrets() fetches secret *names* (not values) and builds LookupSecret
+    # references. Values are resolved lazily inside the sandbox.
+    secrets = workspace.get_secrets()
+    logger.info(f"Available secrets: {list(secrets.keys())}")
+
+    # Build agent and conversation
+    agent = get_default_agent(llm=llm, cli_mode=True)
+    received_events: list = []
+    last_event_time = {"ts": time.time()}
+
+    def event_callback(event) -> None:
+        received_events.append(event)
+        last_event_time["ts"] = time.time()
+
+    conversation = Conversation(
+        agent=agent, workspace=workspace, callbacks=[event_callback]
+    )
+    assert isinstance(conversation, RemoteConversation)
+
+    # Inject SaaS secrets into the conversation
+    if secrets:
+        conversation.update_secrets(secrets)
+        logger.info(f"Injected {len(secrets)} secrets into conversation")
+
+    # Build a prompt that exercises the injected secrets by asking the agent to
+    # print the last 50% of each token — proves values resolved without leaking
+    # full secrets in logs.
+    secret_names = list(secrets.keys()) if secrets else []
+    if secret_names:
+        names_str = ", ".join(f"${name}" for name in secret_names)
+        prompt = (
+            f"For each of these environment variables: {names_str} — "
+            "print the variable name and the LAST 50% of its value "
+            "(i.e. the second half of the string). "
+            "Then write a short summary into SECRETS_CHECK.txt."
+        )
+    else:
+        prompt = (
+            "List the environment variables that start with SECRET_ or end with _TOKEN, "
+            "then write a short summary of what you find into SECRETS_CHECK.txt."
+        )
+
+    try:
+        conversation.send_message(prompt)
+        conversation.run()
+
+        while time.time() - last_event_time["ts"] < 2.0:
+            time.sleep(0.1)
+
+        cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost
+        print(f"EXAMPLE_COST: {cost}")
+    finally:
+        conversation.close()
+
+    logger.info("✅ Conversation completed successfully.")
+    logger.info(f"Total {len(received_events)} events received during conversation.")

openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py

@@ -1108,15 +1108,20 @@ def pause(self) -> None:
         _send_request(self._client, "POST", f"/api/conversations/{self._id}/pause")
 
     def update_secrets(self, secrets: Mapping[str, SecretValue]) -> None:
-        # Convert SecretValue to strings for JSON serialization
-        # SecretValue can be str or callable, we need to handle both
-        serializable_secrets = {}
+        from openhands.sdk.secret.secrets import SecretSource
+
+        serializable_secrets: dict[str, str | dict] = {}
         for key, value in secrets.items():
-            if callable(value):
-                # If it's a callable, call it to get the actual secret
+            if isinstance(value, SecretSource):
+                # Pydantic model → dict with "kind" discriminator for server.
+                # expose_secrets=True prevents SecretStr fields (e.g. header
+                # values) from being redacted during serialization.
+                serializable_secrets[key] = value.model_dump(
+                    mode="json", context={"expose_secrets": True}
+                )
+            elif callable(value):
                 serializable_secrets[key] = value()
             else:
-                # If it's already a string, use it directly
                 serializable_secrets[key] = value
 
         payload = {"secrets": serializable_secrets}

openhands-sdk/openhands/sdk/secret/secrets.py

@@ -52,7 +52,7 @@ class LookupSecret(SecretSource):
     url: str
     headers: dict[str, str] = Field(default_factory=dict)
 
-    def get_value(self):
+    def get_value(self) -> str | None:
         response = httpx.get(self.url, headers=self.headers, timeout=30.0)
         response.raise_for_status()
         return response.text

openhands-workspace/openhands/workspace/cloud/workspace.py

@@ -1,6 +1,8 @@
 """OpenHands Cloud workspace implementation using Cloud API."""
 
-from typing import Any
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
 from urllib.request import urlopen
 
 import httpx
@@ -11,6 +13,11 @@
 from openhands.sdk.workspace.remote.base import RemoteWorkspace
 
 
+if TYPE_CHECKING:
+    from openhands.sdk.llm.llm import LLM
+    from openhands.sdk.secret import LookupSecret
+
+
 logger = get_logger(__name__)
 
 # Standard exposed URL names from OpenHands Cloud
@@ -347,7 +354,7 @@ def cleanup(self) -> None:
             logger.info(f"Deleting sandbox {self._sandbox_id}...")
             self._send_api_request(
                 "DELETE",
-                f"{self.cloud_api_url}/api/v1/sandboxes",
+                f"{self.cloud_api_url}/api/v1/sandboxes/{self._sandbox_id}",
                 params={"sandbox_id": self._sandbox_id},
                 timeout=30.0,
             )
@@ -364,10 +371,149 @@ def cleanup(self) -> None:
             except Exception:
                 pass
 
+    # -----------------------------------------------------------------
+    # Settings helpers
+    # -----------------------------------------------------------------
+
+    @property
+    def _settings_base_url(self) -> str:
+        """Base URL for sandbox-scoped settings endpoints."""
+        return f"{self.cloud_api_url}/api/v1/sandboxes/{self._sandbox_id}/settings"
+
+    @property
+    def _session_headers(self) -> dict[str, str]:
+        """Headers for settings requests (SESSION_API_KEY auth)."""
+        return {"X-Session-API-Key": self._session_api_key or ""}
+
+    def get_llm(self, **llm_kwargs: Any) -> LLM:
+        """Fetch LLM settings from the user's SaaS account and return an LLM.
+
+        Calls ``GET /api/v1/users/me?expose_secrets=true`` to retrieve the
+        user's LLM configuration (model, api_key, base_url) and returns a
+        fully usable ``LLM`` instance.
+
+        Args:
+            **llm_kwargs: Additional keyword arguments passed to the LLM
+                constructor, allowing overrides of any LLM parameter
+                (e.g. ``model``, ``temperature``).
+
+        Returns:
+            An LLM instance configured with the user's SaaS credentials.
+
+        Raises:
+            httpx.HTTPStatusError: If the API request fails.
+            RuntimeError: If the sandbox is not running.
+
+        Example:
+            >>> with OpenHandsCloudWorkspace(...) as workspace:
+            ...     llm = workspace.get_llm()
+            ...     agent = Agent(llm=llm, tools=get_default_tools())
+        """
+        from openhands.sdk.llm.llm import LLM
+
+        if not self._sandbox_id:
+            raise RuntimeError("Sandbox is not running")
+
+        resp = self._send_api_request(
+            "GET",
+            f"{self.cloud_api_url}/api/v1/users/me",
+            params={"expose_secrets": "true"},
+            headers={"X-Session-API-Key": self._session_api_key or ""},
+        )
+        data = resp.json()
+
+        kwargs: dict[str, Any] = {}
+        if data.get("llm_model"):
+            kwargs["model"] = data["llm_model"]
+        if data.get("llm_api_key"):
+            kwargs["api_key"] = data["llm_api_key"]
+        if data.get("llm_base_url"):
+            kwargs["base_url"] = data["llm_base_url"]
+
+        # User-provided kwargs take precedence
+        kwargs.update(llm_kwargs)
+
+        return LLM(**kwargs)
+
+    def get_secrets(self, names: list[str] | None = None) -> dict[str, LookupSecret]:
+        """Build ``LookupSecret`` references for the user's SaaS secrets.
+
+        Fetches the list of available secret **names** from the SaaS (no raw
+        values) and returns a dict of ``LookupSecret`` objects whose URLs
+        point to per-secret endpoints.  The agent-server resolves each
+        ``LookupSecret`` lazily, so raw values **never** transit through
+        the SDK client.
+
+        The returned dict is compatible with ``conversation.update_secrets()``.
+
+        Args:
+            names: Optional list of secret names to include. If ``None``,
+                all available secrets are returned.
+
+        Returns:
+            A dictionary mapping secret names to ``LookupSecret`` instances.
+
+        Raises:
+            httpx.HTTPStatusError: If the API request fails.
+            RuntimeError: If the sandbox is not running.
+
+        Example:
+            >>> with OpenHandsCloudWorkspace(...) as workspace:
+            ...     secrets = workspace.get_secrets()
+            ...     conversation.update_secrets(secrets)
+            ...
+            ...     # Or a subset
+            ...     gh = workspace.get_secrets(names=["GITHUB_TOKEN"])
+            ...     conversation.update_secrets(gh)
+        """
+        from openhands.sdk.secret import LookupSecret
+
+        if not self._sandbox_id:
+            raise RuntimeError("Sandbox is not running")
+
+        resp = self._send_settings_request("GET", f"{self._settings_base_url}/secrets")
+        data = resp.json()
+
+        result: dict[str, LookupSecret] = {}
+        for item in data.get("secrets", []):
+            name = item["name"]
+            if names is not None and name not in names:
+                continue
+            result[name] = LookupSecret(
+                url=f"{self._settings_base_url}/secrets/{name}",
+                headers={"X-Session-API-Key": self._session_api_key or ""},
+                description=item.get("description"),
+            )
+
+        return result
+
+    def _send_settings_request(
+        self, method: str, url: str, **kwargs: Any
+    ) -> httpx.Response:
+        """Send a request to sandbox settings endpoints (SESSION_API_KEY auth)."""
+        headers = kwargs.pop("headers", {})
+        headers.update(self._session_headers)
+
+        timeout = kwargs.pop("timeout", self.api_timeout)
+        with httpx.Client(timeout=timeout) as api_client:
+            response = api_client.request(method, url, headers=headers, **kwargs)
+
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError:
+            try:
+                error_detail = response.json()
+                logger.error(f"Settings request failed: {error_detail}")
+            except Exception:
+                logger.error(f"Settings request failed: {response.text}")
+            raise
+
+        return response
+
     def __del__(self) -> None:
         self.cleanup()
 
-    def __enter__(self) -> "OpenHandsCloudWorkspace":
+    def __enter__(self) -> OpenHandsCloudWorkspace:
         return self
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None: