Simplify secrets API: accept str|SecretSource at API boundary, remove server-side coercion, add LookupSecret timeout

[enyst]

Summary

This PR simplifies the server-side secrets API by aligning the request types with the SDK’s canonical shapes and removing unnecessary coercion logic.

Key changes

• API accepts exactly two formats at the boundary: plain strings or proper SecretSource objects
• Update UpdateSecretsRequest and StartConversationRequest to use SecretValue (str | SecretSource)
• Remove convert_string_secrets validator and drop support for value-only dict format
• Conversation router passes secrets through to EventService; SDK’s SecretRegistry wraps strings into StaticSecret
• Add a default timeout (5s) to LookupSecret.get_value for robustness
• Adjust tests to reflect the two supported shapes only (string or discriminated SecretSource)

Why

• Avoids a third ad-hoc format (value-only dict) and duplication of wrapping logic already implemented in SecretRegistry
• Reduces special cases and keeps the discriminated union design clean and extensible
• Aligns server with SDK expectations and keeps compatibility: existing clients using strings or proper SecretSource continue to work

Compatibility

• Backward compatible with clients passing strings or SecretSource objects
• The previously-added “value-only dict” ({"value": "..."} without kind) is removed to avoid ambiguous shapes; if this was used immediately after Fix server-side automatic string-to-StaticSecret conversion (v1.2.0 compatible) #1234, the error message will advise to post either a string or a proper discriminated SecretSource

Tests & quality

• Updated unit tests in tests/agent_server/test_models.py
• Ran pre-commit hooks (ruff, pyright, pycodestyle) locally
• The full test suite includes some integration/e2e tests that rely on external pieces; the semantic changes here are localized to models/router

Notes

• This follows the simplification discussion from the previous PR. The SDK’s SecretRegistry remains the single place where strings are wrapped into StaticSecret, removing duplication at the API boundary.

Co-authored-by: openhands [email protected]

@enyst can click here to continue refining the PR

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.12-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:6b2fbd6-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-6b2fbd6-python \
  ghcr.io/openhands/agent-server:6b2fbd6-python

All tags pushed for this build

ghcr.io/openhands/agent-server:6b2fbd6-golang-amd64
ghcr.io/openhands/agent-server:6b2fbd6-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:6b2fbd6-golang-arm64
ghcr.io/openhands/agent-server:6b2fbd6-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:6b2fbd6-java-amd64
ghcr.io/openhands/agent-server:6b2fbd6-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:6b2fbd6-java-arm64
ghcr.io/openhands/agent-server:6b2fbd6-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:6b2fbd6-python-amd64
ghcr.io/openhands/agent-server:6b2fbd6-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:6b2fbd6-python-arm64
ghcr.io/openhands/agent-server:6b2fbd6-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:6b2fbd6-golang
ghcr.io/openhands/agent-server:6b2fbd6-java
ghcr.io/openhands/agent-server:6b2fbd6-python

About Multi-Architecture Support

• Each variant tag (e.g., 6b2fbd6-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 6b2fbd6-python-amd64) are also available if needed

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-agent-server/openhands/agent_server
conversation_router.py	101	49	51%	79–81, 95–96, 109, 120–122, 150–153, 164–167, 184, 188–190, 196, 210–212, 214–215, 228–232, 245–249, 264–267, 280, 283–285, 298–301
models.py	102	2	98%	56–57
openhands-sdk/openhands/sdk/conversation
secret_source.py	55	22	60%	38, 55–60, 62–63, 67–72, 74–75, 82–86
TOTAL	12407	5637	54%

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Run tests
  • Pre-commit checks

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #1338 at branch `simplify-secrets-api`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}