feat(agent-server): add launch-time skill overlays

[kyletser]

HUMAN:

I reviewed the implementation, test evidence, and rollout notes, and I am comfortable submitting this change for maintainer review.

---

AGENT:

Design doc: Launch-time skill overlays

Why

Clients that launch an Agent Profile send agent_profile_id and let Agent Server resolve the agent. Native ACP sourcing then removes OpenHands-managed skills from that resolved context. The existing system_message_suffix_append field cannot carry a structured skill, is always included in the prompt, and is limited to 32,768 characters. The automation skill that exposed this bug is larger than that limit.

skills_append provides a structured launch overlay after profile resolution and ACP sourcing. Agent Server stores the merged conversation agent, while the stored Agent Profile remains unchanged.

Summary

• Add optional skills_append: list[Skill] to AgentLaunchAdditions.
• Preserve existing same-name skills and the resolved context's disabled_skills deny-list.
• Cover direct and profile launches, native ACP sourcing, restart persistence, later-turn triggers, the ACP prompt boundary, and a real HTTP round trip with content larger than 32 KiB.

Issue Number

Fixes OpenHands/OpenHands#16905

Related to #4019.

How to Test

Run the focused regression suite:

uv run pytest \
  tests/agent_server/test_agent_launch_additions.py \
  tests/agent_server/test_acp_skill_sourcing.py \
  tests/sdk/agent/test_acp_agent.py::TestACPAgentStep::test_step_sends_triggered_skill_content_to_acp_server \
  -q

Local result: 16 passed.

Run the live REST boundary test:

uv run pytest \
  tests/cross/test_remote_conversation_live_server.py::test_agent_launch_skills_roundtrip_over_real_server \
  -q

Local result: 1 passed. The response retained the exact skill content above 32 KiB after native ACP sourcing.

Run static and API schema checks:

uv run pre-commit run --files \
  openhands-sdk/openhands/sdk/conversation/request.py \
  openhands-agent-server/openhands/agent_server/conversation_service.py \
  tests/agent_server/test_agent_launch_additions.py \
  tests/cross/test_remote_conversation_live_server.py

make test-server-schema

All configured pre-commit hooks passed with the repository's Python 3.13 and locked Pyright versions. The OpenAPI schema exported deterministically, passed the repository quality check, and passed Swagger validation.

The tests were written red first. Moving the overlay before native ACP sourcing made the lifecycle test fail with skills=[]; restoring the intended order made it pass.

Video/Screenshots

Not applicable to this API and persistence change. The linked design doc shows the request flow and validation evidence.

Design Doc

Launch-time skill overlays

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

The field is optional and additive for existing clients. Servers released before this field reject it because launch additions forbid unknown keys, so the rollout order is Agent Server, OpenAPI schema, typed client, then downstream use.

Documentation: OpenHands/docs#770

The downstream Agent Canvas change will follow after a compatible Agent Server and typed client are available.

[github-actions]

📁 PR Artifacts Notice

This PR contains a .pr/ directory with temporary PR-specific documents. Because this is a fork PR, the directory will be automatically removed from main immediately after merge.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[all-hands-bot]

🚦 CI is currently failing on this PR's latest commit.

Please fix the failing checks before OpenHands reviews it - this is re-checked automatically once you push a new commit. (A maintainer can also request @all-hands-bot as a reviewer to have it reviewed regardless of CI status.)

This is an automated check - no AI was used to generate this comment.