feat: encrypted secrets in transit for settings API

AGENTS.md

@@ -348,6 +348,7 @@ Note: This is separate from `persistence_dir` which is used for conversation sta
 - Clean caches: `make clean`
 - Run SDK examples: see [openhands-sdk/openhands/sdk/AGENTS.md](openhands-sdk/openhands/sdk/AGENTS.md).
 - The example workflow runs `uv run pytest tests/examples/test_examples.py --run-examples`; each successful example must print an `EXAMPLE_COST: ...` line to stdout (use `EXAMPLE_COST: 0` for non-LLM examples).
+- Example scripts in `examples/` should use top-level code flow (e.g. `with` blocks, bare statements) rather than wrapping logic in a `def main()` function. The `def main` pattern creates unnecessary nesting that makes examples harder to read; keep the code flat and script-like.
 - Conversation plugins passed via `plugins=[...]` are lazy-loaded on the first `send_message()` or `run()`, so example code should inspect plugin-added skills or `resolved_plugins` only after that first interaction.
 - Programmatic settings live in `openhands-sdk/openhands/sdk/settings/`. Keep the exported schema focused on neutral config structure and semantics; downstream apps should own client-specific ordering, icons, widgets, and slash-command presentation.
 </QUICK_COMMANDS>

openhands-agent-server/openhands/agent_server/conversation_service.py

@@ -477,10 +477,23 @@ async def _start_conversation(
         # serialize to plain strings. Pass expose_secrets=True so StaticSecret values
         # are preserved through the round-trip; the dict is only used in-process to
         # construct StoredConversation, not sent over the network.
-        stored = StoredConversation(
-            id=conversation_id,
-            **request.model_dump(mode="json", context={"expose_secrets": True}),
-        )
+        request_data = request.model_dump(mode="json", context={"expose_secrets": True})
+
+        # If secrets_encrypted=True, the agent's secrets (e.g., LLM api_key) are
+        # cipher-encrypted and need decryption during model validation. Pass the
+        # cipher in the validation context so validate_secret() can decrypt them.
+        if request.secrets_encrypted:
+            if self.cipher is None:
+                raise ValueError(
+                    "Cannot decrypt secrets: cipher not configured. "
+                    "Set OH_SECRET_KEY environment variable."
+                )
+            stored = StoredConversation.model_validate(
+                {"id": conversation_id, **request_data},
+                context={"cipher": self.cipher},
+            )
+        else:
+            stored = StoredConversation(id=conversation_id, **request_data)
         event_service = await self._start_event_service(stored)
         initial_message = request.initial_message
         if initial_message:

openhands-agent-server/openhands/agent_server/persistence/__init__.py

@@ -0,0 +1,43 @@
+"""Persistence module for settings and secrets storage."""
+
+from openhands.agent_server.persistence.models import (
+    SECRET_NAME_PATTERN,
+    CustomSecret,
+    CustomSecretCreate,
+    CustomSecretResponse,
+    PersistedSettings,
+    Secrets,
+    SecretsResponse,
+    SettingsUpdatePayload,
+)
+from openhands.agent_server.persistence.store import (
+    FileSecretsStore,
+    FileSettingsStore,
+    SecretsStore,
+    SettingsStore,
+    get_secrets_store,
+    get_settings_store,
+    reset_stores,
+)
+
+
+__all__ = [
+    # Constants
+    "SECRET_NAME_PATTERN",
+    # Models
+    "CustomSecret",
+    "CustomSecretCreate",
+    "CustomSecretResponse",
+    "PersistedSettings",
+    "Secrets",
+    "SecretsResponse",
+    "SettingsUpdatePayload",
+    # Stores
+    "FileSecretsStore",
+    "FileSettingsStore",
+    "SecretsStore",
+    "SettingsStore",
+    "get_secrets_store",
+    "get_settings_store",
+    "reset_stores",
+]